@blxzer/smart-search

smart-search

原项目: 本项目基于 konbakuyomu/smartsearch 开发

简体中文 | English

smart-search 是一个给 AI 助手和命令行用户使用的 CLI-first 网页研究工具。它把普通联网搜索、来源发现、网页正文抓取、站点 map、配置检查和 live 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 research "OpenAI Responses API web_search 和 Chat Completions 联网搜索怎么选" --format markdown

当前架构分两层：

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

smart-search search 保持快速、直接联网。smart-search research 是 live Deep Research 执行器：它会先在内部生成计划，再按 plan -> discover -> fetch/read -> gap check -> evidence-only synthesis 执行。

安装

稳定版：

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

测试版：

npm install -g @blxzer/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

1. 普通快速搜索：

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

1. 抓取关键网页正文：

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

1. 让 CLI 直接执行 live Deep Research：

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

当前架构

能力	主要命令	Provider	负责什么
main_search	search	OpenAI-compatible Chat Completions	综合回答、快速搜索、初步总结
docs_search	context7-library、context7-docs、exa-search	Context7、Exa	官方文档、SDK、API、框架/库文档
web_search	search 内部中英双语来源发现；zhipu-search 仅作 deprecated 手动兼容	Tavily、Firecrawl；智谱 Web Search API 仅在显式请求时使用	每个常规研究问题都做中文和英文网页来源发现
web_fetch	fetch	Tavily、Jina Reader、Firecrawl	已知 URL 正文抓取、证据提取
site_map	map	Tavily	文档站、产品站、目录型站点结构
research_executor	research / rs	按 capability 注册的 provider	live 深度研究执行：规划、发现、抓取/读取、gap check、仅基于证据综合

同能力兜底关系：

能力	兜底链
main_search	OpenAI-compatible
docs_search	Context7 处理库/API/文档意图；Exa 处理官方域名、论文、产品页、可信站点发现
web_search	Tavily -> Firecrawl；智谱仅在显式选择 deprecated legacy 命令时使用
web_fetch	Tavily -> 带 JINA_API_KEY 的 Jina Reader -> Firecrawl

Jina Reader 只属于 web_fetch，不是通用搜索 provider。只有配置 JINA_API_KEY 后，它才可以满足 SMART_SEARCH_MINIMUM_PROFILE=standard；匿名 r.jina.ai 只能当显式/实验抓取能力，不能让最低配置检查放松。

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

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

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

balanced 和 strict 的 search 默认通过 Tavily / Firecrawl 执行中英双语 web_search 来源发现：同一个用户问题会生成一个中文来源查询和一个英文来源查询。--validation fast 跳过补强。没有主回答来源、docs、fetch 或显式来源证据的 strict 查询仍可能返回 evidence_error；需要可引用证据时，用 --extra-sources N、exa-search 这类 source-first 命令，或直接 fetch 关键 URL。docs 补强继续保持显式 docs/API/库/框架关键词触发。

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

搜索引擎选择速记：先用 search 做中英双语宽泛探索和综合；想让 CLI 执行完整证据流时用 research；库/API/框架文档优先用 Context7；官方域名、论文、产品页、可信站点和低噪声发现再用 Exa；Tavily/Firecrawl 负责双语网页发现和 URL/页面证据；Jina 用于已知 URL 正文抓取。智谱只保留为 deprecated 手动兼容命令，不再作为默认路径。

Deep Research 深度搜索

普通问题用：

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

如果你希望 CLI 直接执行完整 live Deep Research，用：

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

research 会先在内部生成 Deep Research 计划，再执行 plan -> discover -> fetch/read -> gap check -> evidence-only synthesis。规划阶段会产出：

• 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：关键结论没有正文证据就继续抓，或者降级成未验证候选。

Deep Research 不是固定题材配方。行情、选型、技术文档、新闻政策、真假核验、用户给 URL 这些只是用户语言示例，不是 schema 枚举。

规划只允许组合现有 CLI 积木：

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

doctor 是 preflight 配置预检，不是 research step；它帮助 AI 判断当前 provider 是否可用，但不算 Deep Research 的取证步骤。

默认 --fallback auto，会在同一 capability 内兜底；--fallback off 只尝试每个 capability 选中的第一个 provider，适合手动调试某个 provider。

research JSON 会包含 final_answer、citations、evidence_items、gap_check、provider_attempts、fallback_used、degraded、route_policy_version 和 evidence_dir。发现阶段的 snippet 只是候选，不会直接变成 citation；只有 fetch/read 到正文的来源才会被引用。兜底仍然补不齐证据时，research 会降级输出 gap，不会编造结论。

research 的路由是 capability-first 加 provider 优势：

• Context7 优先处理库/API/框架文档，Exa 用于官方域名、论文、产品页、可信站点和低噪声发现。
• Tavily / Firecrawl 负责中英双语宽泛来源发现。智谱已从默认路由弃用，除非显式请求 legacy 命令，否则不会用于中文、时效、国内搜索。
• Jina 优先用于已知公开 URL、PDF、arXiv 正文抽取；ReaderLM-v2 仍要求 JINA_API_KEY。
• Firecrawl 优先用于 JS-heavy、动态页面、浏览器式抽取、OCR/PDF 或强兜底抓取。

高级路由覆盖项是 SMART_SEARCH_RESEARCH_PREFERRED_PROVIDERS 和 SMART_SEARCH_RESEARCH_DISABLED_PROVIDERS。它们只能在 provider 已支持的 capability 内调整顺序或禁用，不能把 provider 移到另一个 capability。

可以用这些标准问题测试 live Deep Research：

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

看到输出里有 mode=deep_research_execution、citations、evidence_items、gap_check，就说明已经进入 Deep Research 执行模式。

API 和 Key 申请入口

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

Provider / 路线	用途	主要配置项	官方文档	Key / 控制台
OpenAI-compatible Chat Completions	主搜索，适合 OpenAI 官方或兼容中转	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	仅用于 deprecated 手动 zhipu-search 兼容；不参与默认路由	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
Jina Reader	已知 URL 正文抓取；满足 standard 最低配置必须有 key	JINA_API_KEY、JINA_READER_API_URL、JINA_RESPOND_WITH、JINA_TIMEOUT_SECONDS	Jina Reader	Jina AI
Firecrawl	fetch 兜底、补充网页来源	FIRECRAWL_API_URL、FIRECRAWL_API_KEY	Firecrawl docs	Firecrawl API keys

几个容易混淆的点：

• OpenAI-compatible 兼容中转/网关走 Chat Completions /chat/completions，只通过 OPENAI_COMPATIBLE_* 配置。
• OPENAI_COMPATIBLE_STREAM=true 或 smart-search search --stream 只会给 OpenAI-compatible 的 search 和 provider 侧 fetch 设置 stream=true。它是中转长请求兼容开关，不改变 URL 描述和来源排序行为。
• 旧的 SMART_SEARCH_API_URL、SMART_SEARCH_API_KEY、SMART_SEARCH_API_MODE、SMART_SEARCH_MODEL 不再是受支持配置项。请显式使用 OPENAI_COMPATIBLE_*。
• 默认网页发现走 Tavily / Firecrawl 的中英双语路径。zhipu-search 仅保留为 deprecated 手动兼容命令，不参与普通 search 或 research 路由。
• zhipu-search 对应的是智谱 Web Search API，不是 Chat Completions tools=[web_search]，不是 Search Agent，也不是 MCP Server。
• Jina Reader 不是通用搜索 provider。只有配置 JINA_API_KEY 后才计入 standard；JINA_RESPOND_WITH=readerlm-v2 也必须配置 JINA_API_KEY。
• 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。

非交互配置示例：

smart-search setup --non-interactive `
  --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" `
  --jina-key "your-jina-key" `
  --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"

仅在显式需要 legacy 智谱兼容时，smart-search setup --non-interactive --zhipu-key "your-zhipu-key" --zhipu-api-url "https://open.bigmodel.cn/api" --zhipu-search-engine "search_pro_sogou" 仍会保存这条 deprecated 手动路径。

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

• main_search：OpenAI-compatible；
• docs_search：Exa 或 Context7 二选一；
• web_fetch：Tavily、带 JINA_API_KEY 的 Jina、Firecrawl 三选一。

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

本机配置和证据文件位置：

• Windows 默认：%LOCALAPPDATA%\smart-search\config.json。
• Linux/macOS 默认：~/.config/smart-search/config.json。
• SMART_SEARCH_CONFIG_DIR 是高级覆盖项，适合 CI、容器、沙箱或便携安装。
• research 证据默认保存到当前配置目录下的 evidence，例如 Windows 上的 %LOCALAPPDATA%\smart-search\evidence。
• SMART_SEARCH_EVIDENCE_DIR 可覆盖证据根目录；相对路径会解析到当前配置目录下，绝对路径按原样使用。
• 更早的 Windows 源码默认路径曾是 ~\.config\smart-search\config.json，但有些安装会通过 SMART_SEARCH_CONFIG_DIR 提前固定到 %LOCALAPPDATA%\smart-search。如果新版默认位置还没有配置，但旧 home 路径存在配置，Smart Search 会以 legacy_windows_home 方式继续读取旧配置，避免升级后配置丢失；config path 和 doctor 会同时报告当前生效路径、默认路径、旧 home 路径、SMART_SEARCH_CONFIG_DIR、SMART_SEARCH_EVIDENCE_DIR 和最终解析出的证据根目录。

常用环境变量：

变量	用途
OPENAI_COMPATIBLE_API_URL	OpenAI-compatible /v1 base URL
OPENAI_COMPATIBLE_API_KEY	OpenAI-compatible key
OPENAI_COMPATIBLE_MODEL	兼容模型名，默认 grok-4.20-multi-agent-xhigh
OPENAI_COMPATIBLE_STREAM	OpenAI-compatible 中转兼容开关，接受 true/1/yes，默认 true
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
JINA_API_KEY	Jina Reader key；满足 standard 必须配置
JINA_READER_API_URL	Jina Reader endpoint，默认 https://r.jina.ai
JINA_RESPOND_WITH	Jina Reader 响应模式，例如 readerlm-v2；需要 JINA_API_KEY
JINA_TIMEOUT_SECONDS	Jina Reader 请求超时，默认 60
TAVILY_API_URL	Tavily REST base
TAVILY_API_KEY	Tavily key
TAVILY_TIMEOUT_SECONDS	Tavily 连通性检查超时，默认 60；公益站/号池较慢时可调大
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_RESEARCH_PREFERRED_PROVIDERS	research 路由优先 provider CSV，只能在同 capability 内调整顺序
SMART_SEARCH_RESEARCH_DISABLED_PROVIDERS	research 禁用 provider CSV，不能改变 provider capability 边界
SMART_SEARCH_CONFIG_DIR	指定本机配置和日志根目录
SMART_SEARCH_EVIDENCE_DIR	指定 research 默认证据根目录

常用命令

命令	简写	用途
search	s	快速联网搜索和综合回答
research	rs	live Deep Research 执行
fetch	f	抓一个 URL 正文
map	m	读取站点结构
exa-search	exa、x	Exa 来源发现
exa-similar	xs	从一个 URL 找相似页面
zhipu-search	z、zp	DEPRECATED — 0.2.0 移除；legacy 智谱 Web Search API
context7-library	c7、ctx7	查 Context7 库候选
context7-docs	c7d、c7docs、ctx7-docs	抓 Context7 文档
doctor	d	配置和连通性检查
setup	init	配置向导
config	cfg	本机配置读写

示例：

smart-search search "query" --validation balanced --extra-sources 3 --timeout 90 --format json --output result.json
smart-search research "query" --budget deep --fallback auto --format json --output research.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 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

输出和证据策略

AI 和脚本解析优先用 JSON：

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

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

smart-search doctor --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。

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

$Config = smart-search config path --format json | ConvertFrom-Json
$EvidenceDir = Join-Path $Config.resolved_evidence_dir "iran-hormuz"
New-Item -ItemType Directory -Force -Path $EvidenceDir | Out-Null
smart-search exa-search "Reuters Iran Hormuz latest" --format json --output (Join-Path $EvidenceDir "01-exa.json")
smart-search fetch "https://example.com/source" --format markdown --output (Join-Path $EvidenceDir "02-fetch.md")

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

1. 用中英双语 search、exa-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；
• 把大问题拆成多个小问题；
• 先用中英双语 search 或 exa-search 找来源，再 fetch 关键网页。

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

smart-search --help
smart-search --version
smart-search doctor --format json

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

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

开发验证

.\.venv\Scripts\python.exe -m compileall -q src tests
.\.venv\Scripts\python.exe -m pytest tests -q
npm test
npm pack --dry-run

最新稳定版说明

v0.1.14

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

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

Deprecation 声明

zhipu-search CLI 命令（deprecated；计划移除）

zhipu-search 子命令（别名 z、zp）及底层 providers/zhipu.py 路由已 deprecated，不再参与默认 search / research 路由，仅保留用于显式 legacy 兼容。

移除时间表：

版本	动作
0.1.x（当前）	每次 zhipu-search 调用向 stderr 输出 deprecation warning；doctor 报告 deprecated 状态；文档标记该命令 deprecated。不移除任何代码。
0.2.0（下个 minor）	移除 zhipu-search CLI 子命令与 research_discovery zhipu 分支。
1.0.0（下个 major）	移除 providers/zhipu.py 与所有 ZHIPU_* 配置键。

迁移：改用 search（Tavily / Firecrawl 双语发现）或 research（完整 Deep Research）。

Community

LINUX DO

License

MIT