search-web

Search-Web 技能

概述

用最小搜索链路整合 Context7、Exa、TinyFish、网页正文读取、mcp-deepwiki 和 github-fetcher。普通搜索直接使用当前会话已有工具；环境缺失时提示用户手动运行 $search-web setup 并重启 code agent。

原则：每类搜索目标使用固定工具链；联网搜索优先使用 Exa，仅在 Exa 失败、额度到限、服务不可用或空结果时使用 TinyFish CLI 备用。

参数入口

本 skill 通过调用参数区分两种模式（即 /search-web 后跟随的参数，或 Skill 工具的 args）：

• 参数为 setup（写作 $search-web setup）：执行初始化与 MCP 配置流程，完成后停止当前搜索。
• 其他参数或无参数：直接进入搜索流程，不运行 detect.sh，不自动安装 MCP。

何时使用

• 查询库、框架、SDK 或语言的官方文档（library docs, API reference, framework guides）
• 查找代码示例、教程、博客文章或最新网页资料（code examples, npm packages）
• 读取指定网页正文（仅在已知 URL 后）
• 查看 GitHub 仓库结构、文档、源码入口（README, source code, directory structure）
• 读取 GitHub 仓库中的具体文件或目录结构
• 遇到 library not found、rate limit、documentation outdated 需要查最新资料时

何时不使用

• 纯本地代码检索或无需联网的普通问答
• 需要直接执行代码、运行测试或调试业务逻辑
• 已有完整本地文档且无需联网验证
• 需要修改、重构代码（refactoring）

MCP 快速参考

搜索目标	工具	固定规则
技术文档	Context7	先 resolve-library-id 再 query-docs，每问题≤3次
网络搜索	Exa / TinyFish	Exa 优先；Exa 失败、额度到限、服务不可用或空结果时使用 TinyFish
GitHub 仓库文档	mcp-deepwiki	仓库级文档概览和深读
GitHub 文件/目录	github-fetcher	具体文件或目录结构
网页正文	宿主读取工具 / TinyFish	仅已知 URL 后使用；宿主读取失败时可用 TinyFish 抓取正文

核心流程

1. 如果用户参数为 setup，读 references/setup.md，执行初始化流程，然后停止当前搜索。
2. 普通搜索不运行 bash scripts/detect.sh，直接按搜索目标选择工具。
3. 配置项类问题（阈值、开关、flag、option、parameter、env）先读 references/strategies/config-index-shortcut.md。
4. 技术文档先走 Context7（先 resolve-library-id 再 query-docs）。
5. 联网搜索先使用 Exa；当 Exa 失败、额度到限、服务不可用或空结果时，按 references/tinyfish-fallback.md 使用 TinyFish CLI 备用。
6. 搜索命中 GitHub 仓库时走 mcp-deepwiki；需读具体文件或目录时走 github-fetcher。
7. 只有用户已给出明确 URL、Exa 已定位 URL 或 TinyFish 已定位 URL 后才允许网页正文读取。
8. 最终按 references/rules/output-format.md 组织回答。

MCP 使用边界

工具映射见上方"MCP 快速参考"表。固定禁止：

• 禁止用 open-websearch 或其他未指定搜索工具替代 Exa / TinyFish
• 禁止用 mcp-deepwiki 替代 github-fetcher 的文件读取，或反之
• 普通搜索中，Context7、Exa、mcp-deepwiki、github-fetcher 报未注册、未加载、连接失败或 server unavailable 时，停止当前搜索，提示用户运行 $search-web setup 并重启 code agent。
• 普通搜索不自动执行 setup-mcp.sh，不自动写入任何 MCP 配置。
• TinyFish 是 CLI 备用工具；只有 Exa 已调用但失败、额度到限、服务不可用或空结果时才尝试使用。
• 宿主类型未识别时，普通搜索照常进行；用户可主动运行 $search-web setup 获取通用 MCP JSON。

常见错误

• 跳过 resolve-library-id 直接猜测 libraryId（Context7 必须两步调用）
• 缺少 libraryName 参数调用 resolve-library-id
• 用 libraryName 传给 query-docs（应该用 libraryId）
• Exa MCP 未注册或未加载时直接走 TinyFish（应按 MCP 缺失处理并提示重启；只有 Exa 搜索调用返回失败、额度到限、服务不可用或空结果时才用 TinyFish）
• 把网页正文读取当成搜索步骤替代 Exa
• 用 mcp-deepwiki 替代 github-fetcher 读文件，或反之
• Context7 超过 3 次调用限制后仍继续调用（应转 Exa）
• MCP 未加载时反复重试（应提示用户运行 $search-web setup 并重启）

按需继续加载

只有在以下场景再读 examples/usage.md：

• 需要 Context7、Exa、TinyFish、网页正文读取、mcp-deepwiki 或 github-fetcher 的参数示例
• 需要 Context7 的错误示范、调用顺序示例或多源整合案例
• 需要网页正文读取降级案例
• 需要常见失败场景或排障示例

如果示例文档与正文流程冲突，以本文件为准。

只有用户调用 $search-web setup，或用户明确要求配置/修复搜索环境时，读 references/setup.md。

需要标准输出模板、来源标注规则或 Markdown 结构约束时，读 references/rules/output-format.md。

需要 TinyFish 安装、TINYFISH_API_KEY 写入、备用搜索或正文抓取命令时，读 references/tinyfish-fallback.md。

遇到精确配置项名、阈值、开关、flag、option、parameter、env 一类问题时，读 references/strategies/config-index-shortcut.md。

输出要求

• 最终回答前，必须按 references/rules/output-format.md 格式化
• 明确标注来源类型：Context7、Exa、TinyFish、网页正文读取、mcp-deepwiki、github-fetcher
• 保留原始链接、文档入口或仓库标识
• 如果从 Exa 降级到 TinyFish，必须说明 Exa 的失败原因
• 如果发生降级、读取失败或信息不足，要直接说明
• 不编造未读取到的内容