Context7 Copilot CLI 的 docs-researcher 子代理：一套五步工作流实现精准的库文档检索

本文围绕 Context7 仓库中 GitHub Copilot CLI 插件的 docs-researcher 子代理定义文件展开，完整讲解该代理“识别库名 → 解析库 ID → 选定最佳匹配 → 拉取文档 → 返回聚焦回答”的五步检索工作流、两步工具调用的参数规范，以及“用独立子代理隔离文档上下文”的设计动机。读完本文，你可以理解该代理在插件中的定位与调用方式，并掌握 resolve-library-id 与 query-docs 两个 MCP 工具的参数语义和版本锁定技巧。

docs-researcher 在 Copilot CLI 插件中的定位

docs-researcher.agent.md 是 Context7 官方 Copilot CLI 插件（插件清单，版本 1.0.2，MIT 许可）中随插件分发的一个代理定义文件。文件的 YAML frontmatter 声明了两项元数据：

name: docs-researcher
description: Lightweight agent for fetching library documentation without cluttering your main conversation context.

从 plugin.json 可以看出，该代理是插件四大组成部分之一——插件同时提供 MCP Server（mcpServers 指向 .mcp.json）、自动触发的 Skills、docs-researcher 代理，以及手动查询命令 /context7:docs。插件 README 将 Context7 要解决的问题概括为：AI 编码助手的训练数据过期、会“幻觉”出不存在的 API；Context7 的对策是不依赖模型的过期知识，而是直接从源仓库拉取当前文档。docs-researcher 代理正是承担“拉取”这一职责的专用执行者。

设计动机：为什么用独立的轻量代理

frontmatter 的 description 已经点明了设计意图：在“不污染主对话上下文”的前提下获取库文档（"without cluttering your main conversation context"）。从工作流本身可以推断其原因：

1. 文档检索是“多轮工具调用 + 大量中间数据”的过程——resolve-library-id 会返回多个候选库及版本列表，query-docs 返回的是按相关性排序的文档片段，且问题跨多个概念时还要按概念拆分多次调用。这些原始输出体量不小；
2. 若在主对话中完成，这些中间数据会长期占据上下文窗口，挤压后续开发工作的空间；
3. 而子代理拥有独立上下文：它在自己的上下文里完成全部检索与阅读，最终只把“简洁、可执行、带代码示例的答案”返回给主对话（工作流第 5 步的硬性要求）。

也就是说，该代理本质上是一个“上下文防火墙”：把文档噪声挡在主对话之外，只放行提炼后的结论。

完整五步文档检索工作流

代理定义文件的核心是一张五步流程表。以下逐步展开，并结合仓库内实际的工具实现佐证每个步骤的参数语义。

步骤 1：识别目标库（Identify the library）

从用户问题中提取库/框架名称。看似简单，但提取质量直接影响下一步的检索命中率——例如用户说 “Next.js 15”，既要提取库名 Next.js，也要保留版本号这一关键信息供步骤 3 使用。

步骤 2：调用 resolve-library-id 解析库 ID

第一步工具调用是 resolve-library-id，定义文件要求传入两个参数：

• libraryName：库名，如 "react"、"next.js"、"prisma"；
• query：说明要在该库文档中查找什么，用于相关性排序（relevance ranking）。

仓库中 packages/tools-ai-sdk 包提供了同一组工具的 SDK 实现，其 resolve-library-id 工具的 zod 输入模式 补充了两个代理定义中未写明、但实际执行时很关键的约束：

• libraryName 应使用带正确标点的官方库名——例如写 "Next.js" 而不是 "nextjs"、"Customer.io" 而不是 "customerio"；
• query 会被用于按“用户想完成的事情”对候选库结果排序，且不得包含 API 密钥、密码等敏感信息。

实现层面，该工具最终通过 @upstash/context7-sdk 的 client.searchLibrary(query, libraryName, { type: "txt" }) 发起检索（见 resolve-library-id.ts），查无结果时返回换词重试的提示。插件 README 给出了输入输出示意：输入 "next.js"，输出形如 { id: "/vercel/next.js", name: "Next.js", versions: ["v15.1.8", "v14.2.0", ...] }——注意返回中同时包含 id 和 versions，为步骤 3 的版本选择提供了依据。

步骤 3：选择最佳匹配（Select the best match）

resolve-library-id 通常返回多个候选。定义文件给出的选择优先级为：

1. 精确或最接近的名称匹配（Exact or closest name match）；
2. 最高的 benchmark score（基准分越高，说明该库的文档质量越好）；
3. 版本匹配：如果用户指定了版本（如 “React 19”），应选择对应的 v19.x 版本。

定义文件的 Guidelines 还补充了一条消歧规则：当返回多个匹配时，优先选择官方/主包，而非社区 fork。

步骤 4：调用 query-docs 拉取文档

第二步工具调用是 query-docs，参数为：

• libraryId：步骤 3 选定的 Context7 库 ID，如 /vercel/next.js；
• query：说明要查找什么，限定为单一概念（scoped to a single concept）。

同样可以从 SDK 实现中挖出更完整的参数说明。query-docs 工具的输入模式 明确了 libraryId 的两种合法形态：/org/project 或 /org/project/version（如 /vercel/next.js/v14.3.0-canary.87），并给出了 query 的 Good/Bad 对照：

• Good："How to set up authentication with JWT in Express.js"、"React useEffect cleanup function examples"——具体、含必要细节；
• Bad（太模糊）："auth"、"hooks"；
• Bad（太宽泛）："routing and auth and caching in Next.js"——多概念混合会稀释排序质量。

实现上该工具调用 client.getContext(query, libraryId, { type: "txt" }) 获取文档（见 query-docs.ts）；如果因库 ID 无效而查不到文档，返回信息会显式提示“请改用 resolveLibraryId 获取合法 ID”——这与工作流中“先解析、后查询”的先后顺序是自洽的。

步骤 5：返回聚焦回答（Return a focused answer）

代理的最终输出不是文档原文的转储，而是对相关内容做摘要后的聚焦回答，包含三要素：

• 对问题的直接回答；
• 来自文档的代码示例；
• 可用的链接或引用来源。

检索策略的五条硬约束

定义文件末尾的 Guidelines 一节，规定了代理执行工作流时必须遵守的策略约束。这些约束解释了 Context7 检索质量的关键机制：

约束	原文要点	背后的机制
单概念查询	query 参数只描述要查什么，且每次查询保持单一概念	混合查询会稀释排序（"combined queries dilute ranking"），导致每个主题都只返回浅层结果
多概念拆分调用	问题跨多个独立概念（如路由、认证、缓存）时，对同一 libraryId 按概念各调一次 query-docs；例外是问题本身在问“这些概念如何交互”	库 ID 只需解析一次，查询按概念拆分，兼顾召回质量与调用效率
版本感知	用户提到版本（如 “Next.js 15”）时，若有版本专属库 ID 则使用之	结合步骤 3 的版本匹配规则
优先官方源	多个匹配时优先官方/主包而非社区 fork	降低拉到过时/偏离的 fork 文档的风险
回答保持简洁	目标是回答问题，不是转储整份文档	呼应子代理“不污染主上下文”的设计初衷

这套约束在插件内是跨载体一致的：skills/context7-mcp/SKILL.md 的技能提示词把同样的流程拆成 Step 1–4（解析 ID → 选最佳匹配 → 拉文档 → 使用文档），并在“一个 query 只谈一个主题”上做了同样的强调。可以推断，代理与技能两条路径共享同一套检索纪律，分别服务于“自动触发”和“子代理隔离”两种使用场景。

实战：安装插件并调用 docs-researcher

插件 README 给出的完整使用路径如下。

1. 安装插件（添加 marketplace 并安装）：

copilot plugin marketplace add upstash/context7
copilot plugin install context7@context7-marketplace

2. 配置 API Key（推荐）。不带 Key 时插件以匿名方式连接并共享匿名速率限制；若要使用自己的配额，需设置环境变量：

# 例如写入 ~/.zshrc 或 ~/.bashrc
export CONTEXT7_API_KEY="your-api-key"

.mcp.json 解释了 Key 如何被自动拾取——插件注册的 HTTP 型 MCP 服务器通过请求头 ${CONTEXT7_API_KEY:-} 透传鉴权，设置后重启 Copilot CLI 即可生效。

3. 调用 docs-researcher 代理：当希望主上下文保持干净时，可以显式指定代理执行查询：

copilot --agent docs-researcher -p "look up Supabase auth methods"

与之平行的手动方式是插件命令 /context7:docs（见 commands/docs.md），例如 /context7:docs next.js authentication；两者底层走的是同一条“解析库 ID → query-docs 拉取”的链路，区别在于命令直接在当前对话执行，而代理把过程隔离在子上下文中。

4. 版本锁定查询。若项目锁定在某个版本，可将版本写入库 ID：

/context7:docs /vercel/next.js/v15.1.8 middleware
/context7:docs /supabase/supabase row level security

README 强调：resolve-library-id 的返回结果中包含可用版本列表（versions 字段），因此代理在步骤 3 选择匹配时，总能挑到与项目一致的版本，如 /vercel/next.js/v15.1.8、/supabase/supabase/v2.45.0。

同一设计在其他客户端的分发

值得注意的是，这份代理定义并非 Copilot CLI 独有。仓库中面向 Claude Code 的 plugins/claude/context7/agents/docs-researcher.md 与本文所分析的 Copilot 版正文完全一致，仅在 frontmatter 中额外声明了 model: sonnet（指定运行模型）；此外仓库还有面向通用 agent 插件生态的 plugins/agent-plugins/context7 与 rules/context7-mcp.md 等分发形态。从源码结构看，Context7 将“五步工作流 + 单概念查询纪律”沉淀为一段可移植的提示词模板，通过 frontmatter 元数据适配各客户端的代理注册机制——这也解释了为什么各客户端版本间仅差几行 frontmatter。

小结

• docs-researcher 是 Context7 Copilot CLI 插件中专用于库文档检索的轻量子代理，其定义文件是一张可执行的提示词规格：五步工作流（识别库名 → resolve-library-id 解析 → 按名称/benchmark/版本选优 → query-docs 拉取 → 返回带代码示例的聚焦回答）加五条策略约束；
• 它的核心价值不在“能查文档”，而在上下文隔离：把多轮工具调用的中间数据关在子代理上下文里，主对话只收到提炼后的答案；
• 两个工具的关键参数语义（官方库名拼写、单一概念查询、/org/project[/version] 的 ID 形态、多概念拆分调用）在仓库的 SDK 实现 resolve-library-id.ts 与 query-docs.ts 中均有完整佐证，可作为自行集成 Context7 MCP 工具时的参数参考；
• 使用门槛很低：安装插件、可选地导出 CONTEXT7_API_KEY，即可通过 copilot --agent docs-researcher -p "..." 或 /context7:docs 命令获得与源仓库同步的当前文档，避免模型基于过期训练数据幻觉 API。