code-context

代码上下文检索

此技能提供 5 种检索代码上下文的方法。请根据目标选择方法：公共 GitHub 仓库、库文档、代码搜索、直接检查，或克隆后的 Web 补充检索。

Token 隔离（关键）

绝不要在主上下文中运行任何外部查询。务必启动 Task Agent：

• DeepWiki：Agent 调用 read_wiki_structure / read_wiki_contents / ask_question，提取架构摘要和关键关系，并返回简明概览。
• Context7：Agent 调用 resolve-library-id，然后调用 query-docs，提取最低限度可用的 API 范围和用法示例，并返回可复制的代码片段及版本说明。
• Exa：Agent 调用 get_code_context_exa，提取最低限度可用的代码片段，去重近似重复的结果（镜像、分叉仓库、重复的 StackOverflow 答案），并返回可复制的代码片段和简要说明。
• Git 克隆：Agent 克隆到 /tmp/，读取入口文件和核心模块，运行 rm -rf 清理，并返回文件结构摘要和关键模式。
• Web 搜索+抓取：Agent 根据克隆结果中发现的信息，运行 WebSearch 搜索带版本限定的查询，在高信号 URL 上调用 WebFetch，并仅返回经验证且与克隆代码交叉核对过的见解。

无论搜索量多大，都要保持主上下文干净。仅将最终摘要返回给调用方。

方法 1：DeepWiki（AI 驱动的仓库文档）

适用场景：知名的公共 GitHub 仓库，且你需要快速了解架构概览、组件说明或高层次信息。

工具：read_wiki_structure、read_wiki_contents、ask_question

流程：

1. 使用所有者/仓库名（例如 "facebook/react"）调用 read_wiki_structure，获取主题列表
2. 对相关主题调用 read_wiki_contents，或使用 ask_question 进行定向查询
3. 在需要以下内容时使用：架构图、组件关系、设计决策

优势：无需设置，即时获取 AI 摘要文档，适合快速熟悉陌生仓库。

限制：仅适用于公共 GitHub 仓库；覆盖范围因项目知名度而异。

方法 2：Context7（库文档）

适用场景：获取 npm/pip 包和框架的最新 API 文档、用法示例及特定版本文档。

工具：resolve-library-id、query-docs

流程：

1. 使用库名称（例如 "react"、"fastapi"）调用 resolve-library-id，获取规范 ID
2. 用户指定版本时（例如 "react@18"），从 resolve-library-id 返回的 versions 列表中选择匹配版本，并将其附加到库 ID 路径（例如 /facebook/react/18.3.1）
3. 使用 libraryId 和 query 调用 query-docs——这两个是仅有的参数

查询提示：具体描述查询内容——"useCallback dependency array" 比 "react hooks" 更有效。已知时，请注明框架版本。

固定版本：将版本编码到库 ID 路径中（例如 /vercel/next.js/v14.3.0-canary.87），不要将其作为单独参数。使用 resolve-library-id 返回的 versions 列表选择正确的 slug。

优势：文档始终保持最新，支持固定版本，覆盖数千个库，非常适合查阅 API 参考文档。

限制：需要库已编入索引；对于内部或私有包，作用较小。

方法 3：Exa 代码搜索（全网代码示例）

适用于：查找真实使用模式、StackOverflow 风格的回答、GitHub Gist 示例，以及全网的代码片段。

工具：get_code_context_exa

设置：无需 API 密钥即可使用（免费层有速率限制）。如需更高限额，请设置 EXA_API_KEY 环境变量。

流程：

1. 使用精确查询调用 get_code_context_exa
2. 根据需要设置 tokensNum：快速示例设为 3000，全面模式设为 8000
3. 核实结果的发布日期；优先选择近期来源

查询编写指南：

• 包含语言或框架：用 "TypeScript React"，而不只是 "React"
• 相关时包含版本："Next.js 14 app router"
• 使用准确标识符："useServerAction"，而不是 "server action hook"
• 添加模式类型："example"、"error handling"、"migration guide"
• 示例："TypeScript Next.js 14 app router server action error handling example"

优势：能找到多样化的真实示例，不限于官方文档，还能呈现社区解决方案。

局限性：结果可能已过时；请务必检查发布日期，并对照官方文档核实。

方法 4：Git 克隆（直接检查代码）

适用于：私有仓库、详细的实现审查、运行本地分析，或其他方法无法提供足够深度的情况。

流程：

1. 运行 git clone <repo-url> /tmp/<repo-name> --depth=1 获取代码
2. 阅读关键文件：入口点、配置文件、核心模块
3. 梳理文件结构，并在整个代码库中搜索模式
4. 完成后清理：rm -rf /tmp/<repo-name>

优势：可完整访问代码，支持私有仓库（需凭据），并可使用静态分析工具。

局限性：需要网络访问和磁盘空间；大型仓库速度较慢；私有仓库需要凭据。

方法 5：网页搜索 + 获取内容

适用于：源代码之外的概念、原理、“最佳实践”问题、变更日志、问题讨论、博客文章和迁移指南。分为两种模式：

• 独立使用 — 适用于无需克隆、以自然语言提出的目标，例如询问“为什么”／“Z 的最佳实践”／“比较 X 与 Y”。
• 克隆后补充 — 在方法 4 之后作为补充：克隆可提供代码，此方法可提供原因和变更内容。

工具：WebSearch、WebFetch

适用场景：概念／原理／最佳实践查询使用独立模式；在克隆后为仓库检查补充源代码中没有的背景信息时使用克隆后模式。

流程：

1. 提炼有针对性的查询——克隆后模式根据克隆结果提炼（使用源代码中发现的准确标识符、错误字符串或设计模式），独立模式则直接根据自然语言目标提炼
2. 调用 WebSearch，将 query 设为精确且注明版本的字符串（例如，"<library> <version> breaking change <symbol>"）
3. 对每条高价值结果，调用 WebFetch，传入 url（来自搜索结果）和聚焦的 prompt，仅提取相关部分
4. 有克隆代码时，将获取的内容与其交叉核对；否则与官方文档交叉核对
5. 除非主题稳定或属于基础内容，否则舍弃 2 年前的结果

查询模式：

• 变更日志："<repo-name> CHANGELOG v<version>" 或 "<repo-name> release notes"
• 设计原理："<repo-name> <concept> why OR rationale site:github.com"
• 已知问题："<repo-name> <symbol or pattern> issue OR bug site:github.com"
• 迁移："<repo-name> migrate from <old-version> to <new-version>"

优势：能呈现源代码中完全没有的背景信息——弃用通知、上游问题讨论串、作者博客文章、社区迁移经验。

局限性：结果可能过时或不准确；请务必根据实际克隆的代码验证获取内容中的说法。没有 API 密钥时会受到速率限制。

目标分类

每个输入目标都属于以下三种类型之一。选择方法前先进行分类：

• 仓库目标 — owner/repo 标识或 git URL。使用 DeepWiki（公开仓库）或 Git Clone（私有仓库／需要更深入的细节）。
• 库目标 — 裸包名／框架名，可选加上 name@version。使用 Context7；将版本编码到 libraryId 路径中。
• 自然语言目标 — 问题、比较或概念（“X 如何运作”“X 与 Y 的比较”“Z 的最佳实践”）。代码模式使用 Exa；原理、变更日志和“为什么”类问题使用 Web Search+Fetch。如果查询中提到特定库，也运行 Context7，以获取规范的 API 概览。

调用方传入 --method= 时，只使用允许的方法与适用方法的交集。如果某个目标的交集为空，则跳过该目标的外部查询，并报告没有适用的允许方法。

方法选择指南

场景	首选方法	后备方法
“X 库如何运作？”	Context7	DeepWiki
“了解 Y 仓库的架构”	DeepWiki	Git Clone
“查找 Z 模式的示例”	Exa	Context7
“检查私有／内部仓库”	Git Clone	-
“库的 v3 有哪些变化？”	Context7	Exa
“模块之间如何连接？”	DeepWiki	Git Clone
“为什么做出此设计决策？”	Git Clone → Web Search+Fetch	DeepWiki
“版本之间有哪些问题？”	Web Search+Fetch	Context7
“比较 X 与 Y”（自然语言）	Exa + Context7	Web Search+Fetch
“Z 的最佳实践”（自然语言）	Web Search+Fetch	Exa

组合使用方法

如需全面了解上下文，可组合使用以下方法：

1. 使用 DeepWiki 了解架构概览
2. 使用 Context7 获取具体的 API 详情
3. 使用 Exa 查找社区使用模式
4. 需要时使用 Git Clone 查看实现细节

始终优先选择非破坏性的只读操作。克隆时使用 /tmp，并在完成后清理。