search-web

Files (9)

• README.md
• SKILL.md
• usage.md · examples/
• output-format.md · references/rules/
• setup.md · references/
• config-index-shortcut.md · references/strategies/
• tinyfish-fallback.md · references/
• detect.sh · scripts/
• setup-mcp.sh · scripts/

SKILL.md (first lines)

# 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` 的失败原因
- 如果发生降级、读取失败或信息不足，要直接说明
- 不编造未读取到的内容

From karthrand/karthrand-ai-public, MIT.

More from karthrand/karthrand-ai-public