smart-search-cli

Smart Search CLI

将本地 smart-search 命令作为 Web 研究的默认执行层。此入口仅负责路由、边界和参考资料选择；需要了解命令详情或提供商契约时，再加载相应的参考文件。

此 Skill 是什么

smart-search-cli 是一个面向 AI 工具的指令包。它说明何时调用本地 smart-search 可执行文件、哪条命令符合用户意图、如何保留来源证据，以及如何解读提供商状态和回退字段。

• Skill 本身不提供搜索访问能力；实际工作由已配置的 smart-search CLI 及其提供商完成。
• Skill 不是 MCP 服务，不存储提供商 API 密钥，也不会创建 Trellis、钩子、Agent 或命令。
• smart-search setup --install-skills ... 会连接选定的 Agent。已安装的 Skill 使用简短的引导程序：运行 smart-search agent-guide 获取此 CLI 的当前说明，运行 smart-search agent-guide references/<name>.md 获取所引用的文档。
• App 的 Update Skills 页面会读取所选 CLI 的目录。显式同步会备份已更改的文件；Remove Skills 会备份并断开所选目标。自动维护由 CLI 负责，即使 App 已关闭也会运行，并保留个人编辑。每个已连接的目标都会保留自己的 CLI 安装和配置配置文件。
• 升级 CLI 后，常规使用会检查其托管的 Skills；skills status 仍为只读，skills update 则用于显式刷新。更改后请重新打开 Agent 会话（Gemini：/skills reload）。
• Skill 更新不会更改提供商配置或 API 密钥。缺少可选密钥时会继续跳过，而不会将其视为实时检查成功。

默认工作流

1. 配置或可用性不确定时，运行 smart-search doctor --format json。
2. 如果 doctor 报告缺少配置，请使用 smart-search setup；如果用户提供了密钥，则使用 smart-search config set KEY VALUE。默认情况下，不要要求用户编辑全局环境变量。
3. 如果 doctor 成功后，兼容 OpenAI 的 search 仍然挂起或超时，请运行 smart-search diagnose openai-compatible --format markdown 并使用其摘要。
4. 保持 OPENAI_COMPATIBLE_API_MODE=chat-completions，除非某个具名中继已通过官方 Responses 子集探测；仅为该中继设置 responses，并保留诊断证据。
5. 如果 doctor 返回 ok: true，Web 研究只能使用 smart-search CLI 子命令。同一任务中不要调用 Codex 原生 Web 搜索。
6. 如果安装的全局 skill 可能已过时，请使用 smart-search skills status --targets codex --format json；使用 smart-search skills update --targets codex --format json 刷新它，而无需重新运行 setup。
7. CLI／提供商架构变更后，使用 smart-search smoke --mock --format json。仅当有可用的真实密钥且用户希望进行实时检查时，才使用 --live。
8. 将 TAVILY_ENABLED=false 视为有意设置的无网络边界：不要通过直接调用 Tavily 或 map 绕过它。通过 doctor 和实时 smoke 检查 Tavily 是否处于禁用／跳过状态；Firecrawl 仍为独立配置。
9. 如果结果在 provider_notices 中报告了降级的提供商，或某次提供商尝试的状态为 skipped，请运行 smart-search providers status --format json。该通道正处于持久化的失败冷却期；请修复凭证，或运行 smart-search providers reset PROVIDER，不要重试同一个故障提供商。
10. 在回答中保留命令行和来源 URL。优先引用已抓取的页面；将模型引用和未阅读的搜索来源视为发现候选。

路由

• search：单轮检索：由 Jev 或本地规则选择一个合适的渠道，该渠道返回结果和来源；不进行自动评估、后续检索、筛选或综合。
• route：在本地说明能力路由，不执行提供方；--router-mode jev --remote 会明确选择启用可能产生费用的 TypeSafe 判断。
• research：共享的有限循环，通过 Jev 或本地路由进行互补发现、抓取/阅读、查找证据缺口，并可选择综合结果。
• deep：离线 Deep Research 规划器；它不会运行提供方、抓取页面，也不会取代默认的 search。
• zhipu-search：用于中文、国内中国、政策/监管、公告、时事新闻或中国本地来源的发现。
• context7-library / context7-docs：用于库、SDK、API、框架或文档相关需求。普通搜索使用 Context7 排名候选项中的第一个库；research 可以请求 Jev 选择候选项；如果 Jev 失败或没有候选项达到阈值，则使用第一个候选项。无法解析的库允许在相同能力范围内回退。显式命令会保留候选列表和提供的库 id。
• exa-search：用于官方域名、论文、产品页面、可信页面、按日期/域名筛选的低噪声发现，以及通过 exa-similar 发现相关来源。
• fetch：用于用户提供的 URL，或任何依赖页面内容的主张。
• map：在从同一网站抓取多个页面之前，了解文档网站或域名结构。
• anysearch-*：仅用于显式指定的实验性垂直搜索。先检查域名，不要将 AnySearch 用作默认回退。先解析 JSON 参数，再应用可重复的 --param key=value 覆盖项；anysearch-extract --max-length 只会将 URL 发送到上游，并在本地截断成功返回的文本。
• sciverse-*：仅用于显式指定的实验性学术搜索。用于目录/搜索/语义/阅读/关系；不要将 Sciverse 用作 docs_search、standard 或默认 search / research 回退。
• providers status / providers reset：检查或清除可选提供方已持久化的失败冷却状态；当某个渠道反复报告相同故障时使用。
• model current：仅检查显式指定的提供方模型。使用 smart-search config set XAI_MODEL ... 或 smart-search config set OPENAI_COMPATIBLE_MODEL ... 更改模型。

关键边界

• smart-search 应从用户的 PATH 中解析。
• 私有 API 密钥应使用 smart-search setup 或 smart-search config set 保存；CI 和高级用户仍可使用环境变量。
• 在沙盒运行时中，如果默认配置目录不可用或必须固定，请将 SMART_SEARCH_CONFIG_DIR 设置为绝对可写路径。
• 标准最低配置要求至少启用一个检索渠道。Jev 和主模型均为可选项；但所请求的操作仍需要有能力的渠道。
• 回退仅限于相同的能力类别；在普通搜索中，模型回答和网络搜索互为回退选项。不要将 Context7 用于广泛的新闻/网络事实，也不要用页面提取提供方替代文档搜索。
• 在信任 content 之前，请检查 answer_check 和 primary_sources_count。
• xAI Responses 和 OpenAI-compatible 是同级的 main_search 提供方。不要将一个提供方的 URL/密钥挪用于伪造另一个提供方作为回退。
• 对于时事新闻、政策、金融、健康及其他高风险事实，不要只依据广泛的 search.content 作答。请抓取关键页面，并且仅总结抓取到的文本所支持的内容。
• 在这个 CLI 优先的工作流中，原生 web_search 处于禁用状态，除非用户明确配置了其他获准的路由；不要在不告知用户的情况下回退到其他网络搜索路由。

参考资料

• 命令示例、证据文件、超时重试策略和防护措施：references/command-patterns.md
• 深度研究规划器/执行器工作流、计划字段、差距检查和冒烟测试矩阵：references/deep-research-mode.md
• CLI 入口点、命令签名、别名、输出字段、退出代码和工具策略：references/cli-core.md
• 设置、配置存储、技能安装、提供商端点和 OpenAI 兼容诊断：references/setup-config.md
• 意图路由、提供商能力、来源溯源、回退边界和路由维护：references/provider-routing.md
• 回归测试、打包安装检查、发布流程和发布收尾经验：references/regression-release.md
• 较旧说明中提及原始单体文件时适用的兼容性参考映射：references/cli-contract.md