smart-search：给 AI 一个可复现的搜索工作台

为什么不用原生联网搜索#

Codex / Claude Code 这类工具自带的搜索更像“临时上网查一下”。smart-search 的定位不同：它给 AI 配了一套可复现的检索工作台，让搜索、抓网页正文、保存证据、按计划深搜都能变成命令行步骤。

普通搜索可以这样跑：

1
smart-search search "今天有什么值得关注的 AI 新闻？" --format json

如果要做 Deep Research，第一步不是直接联网，而是先生成研究计划：

1
smart-search deep "深度调研 OpenAI Responses API 的 web_search 应该怎么选" --format json

当前能力分层#

smart-search 不把所有问题都塞给同一个搜索源，而是按能力分层。每个 provider 只在适合自己的场景里发挥作用。

兜底也只发生在同一类能力里：

普通搜索和 Deep Research 怎么分#

普通搜索适合快速查资料：

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

Deep Research 适合需要分解、交叉验证和抓正文证据的任务：

1
smart-search deep "帮我核验这个说法是真是假：https://example.com/article" --format json

Deep Research 计划里会包含：

• intent_signals：是否强时效、是否 docs/API、是否给了 URL、是否高风险。
• decomposition：复杂问题拆成多个子问题。
• capability_plan：决定需要哪些搜索能力。
• steps：每一步具体执行的 smart-search 命令和证据输出路径。
• evidence_policy=fetch_before_claim：关键结论必须来自抓到的正文。
• gap_check：如果关键结论没有正文证据，就继续抓，或者降级为未验证候选。

为什么坚持 CLI + Skills#

这条路线的核心优点很简单：

1. 可复现：每一步都是命令，可以复制、保存、重跑。
2. 可保存证据：--output 可以把 JSON / Markdown 证据文件落到本地。
3. 跨工具通用：Codex、Claude Code、Cursor、Hermes、脚本和终端都能用。
4. 可回归测试：regression、smoke --mock 可以验证路由、兜底和 Deep Research 计划结构。
5. 不依赖单个 MCP session：普通 CLI 更适合搜索、抓取、保存证据这类一次性任务。

安装和初始化#

稳定版安装：

1
npm install -g @konbakuyomu/smart-search@latest
2
smart-search --version
3
smart-search setup

升级后建议同步已经装到 AI 工具里的 skill：

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

如果 OpenAI-compatible 搜索卡住或超时，单独跑诊断：

1
smart-search diagnose openai-compatible --format markdown

setup 会做什么#

smart-search setup 会进入一个向导：

1. 选择语言。
2. 可选把 smart-search-cli skill 安装到 Codex / Claude Code / Cursor / OpenCode / GitHub Copilot / Hermes 等工具。
3. 按能力配置 provider：main_search、docs_search、web_fetch、可选 web_search 和实验 vertical_search。
4. 高级项里可以按需开启 OPENAI_COMPATIBLE_STREAM，也可以配置 AnySearch 的 URL、key 和超时时间。

最低建议配齐三类：main_search + docs_search + web_fetch。

API 从哪里申请#

当前搜索链路#

下面这段仍然按标准 Mermaid 代码块书写，博客会在浏览器里把它渲染成 SVG 图。预览环境会加 noindex，所以可以放心先看效果再合并。

1
flowchart LR
2
    A["用户问题"] --> B["smart-search"]
3
    B --> C["智能路由"]
4

5
    C --> D["主搜索<br/>xAI / OpenAI-compatible"]
6
    C --> E["文档搜索<br/>Exa / Context7"]
7
    C --> F["Web Search<br/>智谱 / Tavily / Firecrawl"]
8
    C --> G["网页抓取<br/>Tavily / Firecrawl"]
9
    C --> J["垂直搜索（实验）<br/>AnySearch"]
10

11
    D --> H["回答"]
12
    E --> H
13
    F --> H
14
    G --> H
15
    J --> H
16

17
    H --> I["JSON / Markdown<br/>来源 + 兜底记录 + 路由信息"]

常用命令#

1
# 普通搜索
2
smart-search search "今天有什么值得关注的 AI 新闻？" --format json
3

4
# Deep Research 计划
5
smart-search deep "深度搜索一下最近的比特币行情" --format json
6

7
# Context7 查库 / API / 框架文档
8
smart-search context7-library "react" "hooks" --format json
9
smart-search context7-docs "/facebook/react" "useEffect cleanup" --format json
10

11
# Exa 查官方域名 / 论文 / 产品页 / 可信站点
12
smart-search exa-search "OpenAI Responses API documentation" --num-results 5 --include-highlights --format json
13

14
# 抓网页正文
15
smart-search fetch "https://example.com" --format markdown

这次测试验证了什么#

这篇文章故意保留了几类内容：

• Markdown 标题、段落、列表、表格和代码块。
• 原生 HTML：<div>、<aside>、<p>、<a>、<code>。
• 行内 HTML：<kbd> provider 标签。
• 从 Obsidian 迁移时对 callout、远程图片和 Mermaid 图的处理。

结论：当前 Astro 博客可以直接承载 Markdown 内嵌 HTML，并且可以把 ```mermaid 代码块渲染成图。后续真正从 Obsidian 精选文章时，需要额外规范图片、callout 和内部双链的转换规则。