smart-search：CLI + Skills 路线的 AI 搜索工作台

Markdown 内嵌 HTML 测试

smart-search

站在巨人肩膀上，基于 CLI + Skills 路线的多来源自动路由搜索工具。

GitHub 仓库 npm install -g @konbakuyomu/smart-search@latest

Grok / xAI OpenAI-compatible Exa Context7 智谱 Tavily Firecrawl AnySearch

这篇文章从 Obsidian 的 草稿纸.md 微调而来，主要用来验证当前博客是否能稳定承载 Markdown + 原生 HTML 的混排效果。结论是：可以。普通 .md 文章可以写 HTML 标签、<kbd>、<div>、<p>、<a>、<code> 等静态结构；如果后续要嵌可交互组件，再换成 .mdx。

为什么不用原生联网搜索

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

普通搜索可以这样跑：

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

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

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

当前能力分层

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

能力	主要命令	Provider	负责什么
`main_search`	`search`	xAI Responses / OpenAI-compatible	综合回答、快速搜索、初步总结
`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-*`	AnySearch（实验）	CVE、金融、法律、学术、代码文档等垂直域验收
`site_map`	`map`	Tavily	文档站、产品站、目录型站点结构
`deep_planner`	`deep` / `dr`	本地 planner	离线生成 Deep Research 计划

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

能力	兜底链
主搜索	xAI Responses -> OpenAI-compatible
文档搜索	Context7 处理库/API/框架文档意图；Exa 处理官方域名、论文、产品页和可信站点发现
Web Search 补强	智谱 -> Tavily -> Firecrawl
网页抓取	Tavily -> Firecrawl
实验垂直搜索	AnySearch 只通过 `anysearch-*` 显式调用，不进入默认 fallback

普通搜索和 Deep Research 怎么分

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

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

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

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

博客渲染测试点

这一块是直接写在 Markdown 文件里的 HTML。它不是 Astro 组件，也不是 MDX 组件，但会作为原生 HTML 输出。

为什么坚持 CLI + Skills

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

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

安装和初始化

稳定版安装：

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

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

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

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

smart-search diagnose openai-compatible --format markdown

setup 会做什么

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

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

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

API 从哪里申请

API / 服务	在 smart-search 里的作用	官方入口
xAI Responses API	主搜索，走 xAI 官方 Responses API，可启用 `web_search` / `x_search`	xAI API keys
OpenAI-compatible	主搜索，可接 OpenAI 官方或兼容中转	OpenAI API keys
Exa	官方文档、API、论文、产品页、可信网页来源发现	Exa API keys
Context7	SDK、库、框架、API 文档检索兜底	Context7
智谱 Web Search API	中文、国内、时效、域名过滤类 Web Search	智谱 API keys
Tavily	额外来源、URL 正文抓取、站点 map	Tavily app
Firecrawl	fetch 兜底、补充网页来源	Firecrawl API keys
AnySearch	实验垂直搜索，不进默认 fallback	AnySearch API keys

当前搜索链路

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

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

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

    D --> H["回答"]
    E --> H
    F --> H
    G --> H
    J --> H

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

常用命令

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

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

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

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

# 抓网页正文
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 和内部双链的转换规则。