smart-search

简体中文 | English

smart-search 是一个给 AI 助手和命令行用户使用的 CLI-first 网页研究工具。它把普通联网搜索、来源发现、网页正文抓取、站点 map、配置检查和 Deep Research 规划统一成一个可复现的命令层。

它到底是什么

它不是 MCP Server，而是一个普通命令行工具。AI 工具通过 smart-search-cli skill 调它，脚本和终端用户也可以直接调它：

smart-search search "今天 OpenAI Responses API 有什么新变化" --format json
smart-search fetch "https://example.com/article" --format markdown
smart-search deep "OpenAI Responses API web_search 和 Chat Completions 联网搜索怎么选" --format json

当前架构分两层：

| 层 | 负责什么 | | --- | --- | | CLI 执行层 | 稳定执行命令、provider 路由、同能力兜底、JSON/Markdown 输出、本机配置、smoke/regression | | Skill / AI 编排层 | 判断用户意图，决定普通搜索还是 Deep Research，按计划执行 CLI 积木，最后写出有来源支撑的回答 |

smart-search search 保持快速、直接联网。smart-search deep 是显式 Deep Research 离线规划入口：默认不联网、不跑 provider、不抓网页，只输出 research_plan。真正联网发生在 AI 或用户继续执行 steps[].command 的时候。

安装

稳定版：

npm install -g @xiaokcoding/smart-search@latest
smart-search --version
smart-search setup

测试版：

npm install -g @xiaokcoding/smart-search@next
smart-search --version

npm 包安装时会自动创建隔离的 Python 运行环境。你平时只需要使用 smart-search 这个命令。

前置条件：

• 已安装 Node.js / npm。
• 已安装 Python 3.10 或更新版本，并且终端里能运行 python、python3 或 Windows 的 py -3。

快速开始

1. 配置 provider：

smart-search setup
smart-search doctor --format json

2. 普通快速搜索：

smart-search search "今天有什么值得关注的 AI 新闻？" --validation balanced --extra-sources 2 --format json

3. 抓取关键网页正文：

smart-search fetch "https://example.com/source" --format markdown --output evidence.md

4. 生成 Deep Research 计划：

smart-search deep "深度搜索一下最近的比特币行情" --budget standard --format json

5. 把 skill 安装给 AI 工具：

smart-search setup --non-interactive --install-skills codex,claude,cursor,hermes

Skill 安装会把内置 smart-search-cli 写入用户级工具目录，例如 ~/.codex/skills、 ~/.claude/skills、~/.cursor/skills、~/.hermes/skills。它不会初始化 Trellis、hooks、 agents 或 commands。--skills-root PATH 只适合便携安装或测试时高级覆盖根目录。

6. 升级 CLI 后，同步已经安装到全局 AI 工具里的 skill：

smart-search skills status --targets codex --format json
smart-search skills update --targets codex --format json

setup --install-skills 仍然保留给第一次配置使用。平时升级包以后，优先用 skills status 和 skills update；它们只检查或覆盖 smart-search-cli 托管文件，不会改 provider key，也不会创建 Trellis、hooks、agents 或 commands。

当前架构

| 能力 | 主要命令 | Provider | 负责什么 | | --- | --- | --- | --- | | main_search | search | xAI Responses、OpenAI-compatible Chat Completions | 综合回答、快速搜索、初步总结 | | docs_search | context7-library、context7-docs、exa-search | Context7、Exa | 官方文档、SDK、API、框架/库文档 | | web_search | zhipu-search、search 内部意图补强 | 智谱、Tavily、Firecrawl | 中文、国内、时效、域名过滤、补充来源 | | web_fetch | fetch | Tavily、Firecrawl | 已知 URL 正文抓取、证据提取 | | vertical_search | anysearch-domains、anysearch-search、anysearch-extract、anysearch-batch | AnySearch（实验） | 验收 CVE、金融、法律、学术、代码/文档等结构化垂直域 | | site_map | map | Tavily | 文档站、产品站、目录型站点结构 | | deep_planner | deep / dr | 本地 planner | 离线生成 Deep Research 计划，不默认联网 |

同能力兜底关系：

| 能力 | 兜底链 | | --- | --- | | main_search | xAI Responses -> OpenAI-compatible | | docs_search | Context7 处理库/API/文档意图；Exa 处理官方域名、论文、产品页、可信站点发现 | | web_search | 智谱 -> Tavily -> Firecrawl | | web_fetch | Tavily -> Firecrawl |

AnySearch 当前只作为实验 vertical_search 暴露，不进入 web_search 兜底链，也不是 standard 最低配置要求。请先用显式命令做验收和能力边界判断，再决定未来是否把某个垂直域提升成正式路线。

这里有一个重要边界：兜底只在同一类能力里发生。不会用 Context7 去查普通新闻，也不会用 Firecrawl 假装做文档语义检索。

输出里会保留可观测字段：

| 字段 | 作用 | | --- | --- | | routing_decision | 为什么触发了某些补强路径 | | provider_attempts | 每个 provider 的尝试结果 | | providers_used | 最终用到哪些 provider | | fallback_used | 是否触发同能力兜底 | | primary_sources | 主搜索回答里带出的来源 | | extra_sources | Tavily / Firecrawl 等额外发现的候选来源 | | source_warning | 来源和回答之间可能存在的证据边界提醒 |

extra_sources 只是候选来源，不等于自动事实校验。新闻、政策、财经、医疗、严肃评测、工具选型等高风险问题，建议先发现来源，再 fetch 关键网页正文，最后只基于抓到的正文写结论。

搜索引擎选择速记：先用 search 做宽泛探索和综合；中文、国内、政策、公告、当前新闻优先补 zhipu-search；库/API/框架文档优先用 Context7；官方域名、论文、产品页、可信站点和低噪声发现再用 Exa；Tavily/Firecrawl 通过 search --extra-sources 做横向候选，通过 fetch 做正文证据；AnySearch 只在明确要实验性垂直搜索时使用。

Deep Research 深度搜索

普通问题用：

smart-search search "React useEffect cleanup 文档" --format json

需要深度搜索、拆解、核验、选型、严肃评测、多来源交叉验证时用：

smart-search deep "OpenAI Responses API web_search 和 Chat Completions 联网搜索怎么选" --budget deep --format json
smart-search dr "https://example.com/source" --format json

Deep Research 不是固定题材配方。行情、选型、技术文档、新闻政策、真假核验、用户给 URL 这些只是用户语言示例，不是 schema 枚举。它会先抽取 intent_signals，再生成 decomposition 和 capability_plan。

计划里会包含：

• mode="deep_research" 和 query_mode="deep"；
• intent_signals：是否强时效、是否 docs/API、是否给 URL、是否高风险、是否需要权威来源、是否需要交叉验证；
• decomposition：复杂问题拆成 1-6 个子问题；
• capability_plan：选择需要的能力；
• steps[]：每一步的 tool、purpose、command、output_path、subquestion_id；
• evidence_policy="fetch_before_claim"；
• gap_check：关键结论没有正文证据就继续抓，或者降级成未验证候选。
• usage_boundary：说明 search 是直接联网，deep 是离线规划，真正执行发生在计划命令里。

Deep Research 只允许组合现有 CLI 积木：

search, exa-search, exa-similar, zhipu-search, context7-library, context7-docs, fetch, map

doctor 是 preflight 配置预检，不是 research step。smart-search deep 这一步本身是离线 planner；后续执行计划里的 steps[].command 时才会联网。

换句话说，doctor 只是配置预检；它帮助 AI 判断当前 provider 是否可用，但不算 Deep Research 的取证步骤。

可以用这些标准问题测试是否进入深搜模式：

smart-search deep "深度搜索一下最近的比特币行情" --format json
smart-search deep "OpenAI Responses API web_search 和 Chat Completions 联网搜索怎么选" --budget deep --format json
smart-search deep "帮我核验这个说法是真是假：某某工具已经完全替代 Tavily 做 AI 搜索了" --format json
smart-search deep "https://example.com/source" --format json

看到输出里有 mode=deep_research、decomposition、多步 steps、evidence_policy=fetch_before_claim、preflight.executed_by_deep_command=false，就说明已经进入 Deep Research 计划模式。

API 和 Key 申请入口

普通用户优先用 smart-search setup 配置。环境变量仍然支持 CI 和高级用户。

| Provider / 路线 | 用途 | 主要配置项 | 官方文档 | Key / 控制台 | | --- | --- | --- | --- | --- | | xAI Responses API | 主搜索，走 web_search,x_search 工具 | XAI_API_KEY、XAI_API_URL、XAI_MODEL、XAI_TOOLS | docs.x.ai | xAI API keys | | OpenAI-compatible Chat Completions | 主搜索，适合 OpenAI 官方或兼容中转；这里不会发送 xAI search tools | OPENAI_COMPATIBLE_API_URL、OPENAI_COMPATIBLE_API_KEY、OPENAI_COMPATIBLE_MODEL、OPENAI_COMPATIBLE_STREAM | OpenAI platform docs | OpenAI API keys 或你的兼容服务商 | | Exa | 官方文档、API、论文、产品页、可信网页的低噪声发现 | EXA_API_KEY | Exa docs | Exa API keys | | Context7 | SDK、库、框架、API 文档兜底 | CONTEXT7_API_KEY、CONTEXT7_BASE_URL | Context7 docs | Context7 | | 智谱 Web Search API | 中文、国内、时效、域名过滤类来源发现 | ZHIPU_API_KEY、ZHIPU_API_URL、ZHIPU_SEARCH_ENGINE | 智谱联网搜索文档 | 智谱 API keys | | Tavily | 额外来源、URL fetch、站点 map | TAVILY_API_URL、TAVILY_API_KEY | Tavily docs | Tavily app | | Firecrawl | fetch 兜底、补充网页来源 | FIRECRAWL_API_URL、FIRECRAWL_API_KEY | Firecrawl docs | Firecrawl API keys | | AnySearch | 实验垂直搜索验收入口，不是默认兜底 | ANYSEARCH_API_URL、ANYSEARCH_API_KEY、ANYSEARCH_TIMEOUT_SECONDS | 服务商文档 | AnySearch 控制台 / 服务商控制台 |

几个容易混淆的点：

• xAI 官方联网搜索路线是 Responses API /responses，只通过 XAI_* 配置。兼容中转/网关走 Chat Completions /chat/completions，只通过 OPENAI_COMPATIBLE_* 配置。
• OPENAI_COMPATIBLE_STREAM=true 或 smart-search search --stream 只会给 OpenAI-compatible 的 search 和 provider 侧 fetch 设置 stream=true。它是中转长请求兼容开关，不改变 xAI Responses、URL 描述和来源排序行为。
• 旧的 SMART_SEARCH_API_URL、SMART_SEARCH_API_KEY、SMART_SEARCH_API_MODE、SMART_SEARCH_MODEL、SMART_SEARCH_XAI_TOOLS 不再是受支持配置项。请显式使用 XAI_* 或 OPENAI_COMPATIBLE_*。
• 不要给 OpenAI-compatible Chat Completions 中转强塞 xAI 的 web_search / x_search 工具或旧 search_parameters。
• 当前项目里的智谱是 Web Search API，不是 Chat Completions tools=[web_search]，不是 Search Agent，也不是 MCP Server。
• ZHIPU_SEARCH_ENGINE 默认是 search_std。官方值包括 search_std、search_pro、search_pro_sogou、search_pro_quark；config set 仍允许自定义值，方便官方以后新增服务。
• TAVILY_API_URL 只影响 Tavily，不会代理智谱。Tavily Hikari / 号池用 https://<host>/api/tavily；setup 会把根域名或 /mcp 输入规范化成这个 REST base。
• FIRECRAWL_API_URL 默认是 https://api.firecrawl.dev/v2。
• AnySearch 默认走 https://api.anysearch.com/mcp 的 JSON-RPC 2.0 tools/call。没有 key 时允许匿名请求；有 key 时发送 Authorization: Bearer ...。HTTP 200 但 result.isError=true 会按 provider error 处理，不能当成功证据。

非交互配置示例：

smart-search setup --non-interactive `
  --xai-api-key "your-xai-key" `
  --xai-model "grok-4-fast" `
  --openai-compatible-api-url "https://api.openai.com/v1" `
  --openai-compatible-api-key "your-openai-or-relay-key" `
  --openai-compatible-model "gpt-4.1" `
  --openai-compatible-stream "false" `
  --validation-level "balanced" `
  --fallback-mode "auto" `
  --minimum-profile "standard" `
  --exa-key "your-exa-key" `
  --context7-key "your-context7-key" `
  --zhipu-key "your-zhipu-key" `
  --zhipu-api-url "https://open.bigmodel.cn/api" `
  --zhipu-search-engine "search_pro_sogou" `
  --tavily-api-url "https://api.tavily.com" `
  --tavily-key "your-tavily-key" `
  --firecrawl-api-url "https://api.firecrawl.dev/v2" `
  --firecrawl-key "your-firecrawl-key"

默认最低配置是 SMART_SEARCH_MINIMUM_PROFILE=standard，至少需要：

• main_search：xAI Responses 或 OpenAI-compatible 二选一；
• docs_search：Exa 或 Context7 二选一；
• web_fetch：Tavily 或 Firecrawl 二选一。

缺少任一最低能力时，doctor 和 search 会 fail closed 并返回缺失 capability。SMART_SEARCH_MINIMUM_PROFILE=off 只建议本地实验使用。

AnySearch 是可选实验配置，不满足也不改变 standard 最低配置：

smart-search setup --non-interactive --anysearch-api-url "https://api.anysearch.com/mcp" --anysearch-key "your-anysearch-key"
smart-search anysearch-domains security --format json
smart-search anysearch-search "CVE-2024-3094" --domain security.cve --max-results 3 --format json
smart-search anysearch-extract "https://example.com/source" --format json
smart-search anysearch-batch "AAPL" "RAG papers" --max-results 2 --format json

垂直域支持点号简写：security.cve 会由 CLI 发成 domain=security 加 sub_domain=cve。也可以显式写成 --domain security --sub-domain cve。

本机配置文件位置：

• Windows 默认：%LOCALAPPDATA%\smart-search\config.json。
• Linux/macOS 默认：~/.config/smart-search/config.json。
• SMART_SEARCH_CONFIG_DIR 是高级覆盖项，适合 CI、容器、沙箱或便携安装。
• 更早的 Windows 源码默认路径曾是 ~\.config\smart-search\config.json，但有些安装会通过 SMART_SEARCH_CONFIG_DIR 提前固定到 %LOCALAPPDATA%\smart-search。如果新版默认位置还没有配置，但旧 home 路径存在配置，Smart Search 会以 legacy_windows_home 方式继续读取旧配置，避免升级后配置丢失；doctor 会同时报告当前生效路径、默认路径、旧 home 路径、SMART_SEARCH_CONFIG_DIR 的值，以及这个覆盖项是不是只是等于当前默认路径。

常用环境变量：

| 变量 | 用途 | | --- | --- | | XAI_API_KEY | xAI Responses provider key | | XAI_API_URL | xAI API 地址，默认 https://api.x.ai/v1 | | XAI_MODEL | xAI 模型名 | | XAI_TOOLS | xAI Responses 工具列表，通常 web_search,x_search | | OPENAI_COMPATIBLE_API_URL | OpenAI-compatible /v1 base URL | | OPENAI_COMPATIBLE_API_KEY | OpenAI-compatible key | | OPENAI_COMPATIBLE_MODEL | 兼容模型名 | | OPENAI_COMPATIBLE_STREAM | OpenAI-compatible 中转兼容开关，接受 true/1/yes，默认 false | | ANYSEARCH_API_URL | AnySearch JSON-RPC endpoint，默认 https://api.anysearch.com/mcp | | ANYSEARCH_API_KEY | 可选 AnySearch key | | ANYSEARCH_TIMEOUT_SECONDS | AnySearch 请求超时，默认 30 | | EXA_API_KEY | Exa key | | CONTEXT7_API_KEY | Context7 key | | ZHIPU_API_KEY | 智谱 Web Search key | | ZHIPU_API_URL | 智谱 API 地址，默认 https://open.bigmodel.cn/api | | ZHIPU_SEARCH_ENGINE | 智谱搜索服务，例如 search_pro_sogou | | TAVILY_API_URL | Tavily REST base | | TAVILY_API_KEY | Tavily key | | TAVILY_TIMEOUT_SECONDS | Tavily 连通性检查超时，默认 30；公益站/号池较慢时可调大 | | FIRECRAWL_API_URL | Firecrawl REST base | | FIRECRAWL_API_KEY | Firecrawl key | | SMART_SEARCH_VALIDATION_LEVEL | fast、balanced、strict | | SMART_SEARCH_FALLBACK_MODE | auto 或 off | | SMART_SEARCH_CONFIG_DIR | 指定本机配置和日志根目录 |

常用命令

| 命令 | 简写 | 用途 | | --- | --- | --- | | search | s | 快速联网搜索和综合回答 | | deep | dr | Deep Research 离线计划 | | fetch | f | 抓一个 URL 正文 | | map | m | 读取站点结构 | | exa-search | exa、x | Exa 来源发现 | | exa-similar | xs | 从一个 URL 找相似页面 | | zhipu-search | z、zp | 智谱 Web Search API | | anysearch-domains | as-domains | 实验 AnySearch 域名/能力发现 | | anysearch-search | as-search、as | 实验 AnySearch 垂直/通用搜索 | | anysearch-extract | as-extract | 实验 AnySearch URL 抽取 | | anysearch-batch | as-batch | 实验 AnySearch 批量搜索，最多 5 条 | | context7-library | c7、ctx7 | 查 Context7 库候选 | | context7-docs | c7d、c7docs、ctx7-docs | 抓 Context7 文档 | | doctor | d | 配置和连通性检查 | | setup | init | 配置向导 | | config | cfg | 本机配置读写 | | model | mdl | 查看显式 provider 模型；修改请用 config set XAI_MODEL 或 OPENAI_COMPATIBLE_MODEL | | smoke | sm | provider 路由冒烟测试 | | regression | reg | 离线回归测试 |

示例：

smart-search search "query" --validation balanced --extra-sources 3 --timeout 90 --format json --output result.json
smart-search search "query" --stream --format json
smart-search search "query" --no-stream --format json
smart-search search "nba战报" --format content
smart-search exa-search "OpenAI Responses API documentation" --include-domains platform.openai.com developers.openai.com --num-results 5 --include-text --format json
smart-search context7-library "react" "hooks" --format json
smart-search context7-docs "/facebook/react" "useEffect cleanup" --format json
smart-search zhipu-search "今天国内 AI 新闻" --search-engine search_pro_sogou --count 5 --format json
smart-search anysearch-search "CVE-2024-3094" --domain security.cve --max-results 3 --format json
smart-search anysearch-extract "https://example.com/source" --format json
smart-search exa-similar "https://example.com/source" --num-results 5 --format json
smart-search fetch "https://example.com/source" --format markdown --output page.md
smart-search map "https://docs.example.com" --instructions "Find API reference pages" --max-depth 1 --limit 50 --format json
smart-search doctor --format markdown
smart-search smoke --mock --format json
smart-search regression

输出和证据策略

AI 和脚本解析优先用 JSON：

smart-search search "query" --format json
smart-search doctor --format json

给人看连接状态、详细排障报告、冒烟结果、来源列表、网页正文时用 Markdown：

smart-search doctor --format markdown
smart-search smoke --mock --format markdown
smart-search exa-search "OpenAI Responses API documentation" --format markdown
smart-search fetch "https://example.com" --format markdown

终端快速扫正文或摘要用 content：

smart-search search "nba战报" --format content
smart-search doctor --format content

content 刻意保持很短，只适合快速看结论。完整排障给人看用 doctor --format markdown，给脚本和 AI 解析用 doctor --format json。

多来源研究建议保存证据文件：

smart-search exa-search "Reuters Iran Hormuz latest" --format json --output C:\tmp\smart-search-evidence\iran-hormuz\01-exa.json
smart-search fetch "https://example.com/source" --format markdown --output C:\tmp\smart-search-evidence\iran-hormuz\02-fetch.md

写 claim-level 结论时建议流程：

1. 用 search、exa-search、zhipu-search 或 exa-similar 找候选 URL。
2. 用 fetch 抓关键 URL 正文。
3. 最终回答只引用 fetch 正文能支撑的事实。
4. 没有 fetch 的来源标为未验证候选。

排障

如果 doctor 返回 config_error：

smart-search setup
smart-search config list --format json
smart-search doctor --format markdown

如果搜索慢：

• 降低 --extra-sources；
• 把大问题拆成多个小问题；
• 先用 exa-search 或 zhipu-search 找来源，再 fetch 关键网页。

如果想确认安装是否正常：

smart-search --help
smart-search --version
smart-search regression
smart-search smoke --mock --format json

Windows npm/mise 安装后建议验证中文 JSON 管道：

smart-search deep "深度搜索一下最近的比特币行情" --format json | ConvertFrom-Json

开发验证

.\.venv\Scripts\python.exe -m compileall -q src tests
.\.venv\Scripts\python.exe -m pytest tests -q
.\.venv\Scripts\python.exe -m smart_search.cli regression
.\.venv\Scripts\python.exe -m smart_search.cli smoke --mock --format json
npm test
npm pack --dry-run

最新稳定版说明

v0.1.14

这个稳定补丁版把已经验证过的 0.1.13-beta.4 CLI 和内置 skill contract 推到 npm latest。

• 修复 GitHub issue #7：npm latest 现在包含新版 smart-search-cli skill 会调用的 smart-search skills 命令。
• smart-search skills status 可以只读检查用户级 skill 是缺失、过期、已最新，还是有额外文件。
• smart-search skills update 用于升级 CLI 后刷新指定 AI 工具里的托管 smart-search-cli 文件，不会改 provider key，也不会创建 Trellis/hooks/agents/commands。
• smart-search diagnose openai-compatible --format markdown 会生成适合复制给维护者的 OpenAI-compatible 卡住/超时诊断报告。
• 文档/API 路由现在优先用 Context7 处理库/框架文档，Exa 继续负责官方域名、论文、产品页和可信站点发现。
• README、打包 skill 资源、release notes 和测试已经同步说明并验证这次稳定包行为。

发布通道

稳定版走 Git tag 和 npm latest：

git tag v0.1.14
git push origin v0.1.14

测试版不移动 latest。推送到 main 会发布下一个 <package.json version>-beta.N 到 npm next，并且 N 按每个稳定版本重新从 1 开始。例如 0.1.10-beta.1、0.1.10-beta.2 之后是 0.1.10-beta.3。

已发布 npm 版本不可变。旧的 *-dev.* 包不能原地改名，只能发布新的 *-beta.N 替代。

稳定版 GitHub Release 会读取 .github/releases/vX.Y.Z.md 作为正文，并自动追加 npm package、dist-tag、workflow run 等元数据。打稳定 tag 前先写这个文件，避免 Release 页面只显示包名和 workflow 链接。

发布收尾检查：

1. 先读 npm view @xiaokcoding/smart-search versions --json、npm view @xiaokcoding/smart-search dist-tags --json、gh release list --repo xiaokcoding/smartsearch --limit 100。
2. beta 发布必须保持 latest 不动，只移动 next 或指定的非 latest tag。
3. 遇到 npm E409，先查版本是否已经发布，再串行重跑对应版本。
4. 最后安装指定版本并运行 smart-search --version、smart-search regression、smart-search smoke --mock --format json。
5. Windows npm/mise 包装层额外跑中文 JSON 管道：smart-search deep "深度搜索一下最近的比特币行情" --format json | ConvertFrom-Json。

License

MIT