Context7 Claude Code 插件中的 docs-researcher 子代理：把库文档调研隔离到独立上下文，保持主会话精简

docs-researcher 是 Context7 为 Claude Code 提供的官方插件（plugins/claude/context7/agents/docs-researcher.md）中的一个专用子代理：当你在一个长任务中需要查阅第三方库的最新文档时，它可以在独立的上下文窗口里完成"解析库 ID → 检索文档 → 提炼答案"的全流程，只把浓缩后的结果交回主会话，避免文档工具调用的大量中间输出污染主上下文。读完本文，你将理解该代理的完整五步工作流、库 ID 的选型判据、"一次查询只问一个概念"的设计原则，以及它背后依赖的 resolve-library-id 与 query-docs 两个 MCP 工具的真实实现链路。

一、代理定位：为什么需要一个"轻量文档调研员"

docs-researcher.md 文件的 YAML frontmatter 定义了这个代理的三要素：

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

• name：代理标识符，Claude Code 通过它来 spawn 该代理；
• description：明确了它的存在目的——"轻量级（Lightweight）"，且核心诉求是"without cluttering your main conversation context"（不污染主对话上下文）；
• model: sonnet：指定该代理运行在 Sonnet 模型上。官方 Claude Code 文档（docs/clients/claude-code.mdx）对此的解释是：它使用同样的工具（resolve-library-id 和 query-docs），但跑在更轻量的模型上以"keep things fast"（保持快速）。

这与插件 README（plugins/claude/context7/README.md）中列出的四种触发方式形成对照：插件同时提供自动触发的 Skill、手动命令 /context7:docs，以及这个需要显式 spawn 的 Agent。三者中，Agent 是唯一"上下文隔离"的执行路径——README 给出的调用方式就是一句自然语言：

spawn docs-researcher to look up Supabase auth methods

官方文档还给出了"何时用 Agent 而非内联工具"的对照表（docs/clients/claude-code.mdx）：

场景	推荐方式
任务进行到较深处、上下文已经很长	Agent
想避免上下文膨胀	Agent
上下文还短	内联工具（Skill / 命令）
希望文档内容直接可见于对话	内联工具

典型使用例子包括：

spawn docs-researcher to look up React hooks documentation
spawn docs-researcher: how do I set up Prisma with PostgreSQL?
spawn docs-researcher to find Tailwind CSS grid utilities

二、五步工作流：从用户问题到可执行答案

docs-researcher.md 的主体是一份给 LLM 执行的角色指令（"You are a documentation researcher specializing in fetching up-to-date library and framework documentation from Context7"），其 Process 部分规定了严格的五步流程。这五步完整继承如下。

第 1 步：识别库（Identify the library）

从用户问题中提取库/框架的名称，例如用户问"Next.js 15 里怎么配置认证"，提取出的库名就是 next.js。

第 2 步：解析库 ID（Resolve the library ID）

调用 MCP 工具 resolve-library-id，传入两个参数：

• libraryName：库名（如 "react"、"next.js"、"prisma"）；
• query：要在这个库文档里查什么——这个参数会参与服务端的相关性排序（relevance ranking）。

第 3 步：选出最佳匹配（Select the best match）

从解析结果中按以下三条标准挑选：

1. Exact or closest name match：精确或最接近的名称匹配优先；
2. Highest benchmark score：Benchmark Score 越高，文档质量指标越好；
3. 版本匹配：如果用户指定了版本（如 "React 19"），应查找对应的 v19.x 版本 ID。

第 4 步：获取文档（Fetch documentation）

调用 query-docs，传入：

• libraryId：选定的 Context7 库 ID，格式形如 /vercel/next.js（带版本则为 /vercel/next.js/v15.1.8）；
• query：要查什么，且必须 scoped to a single concept（限定为单一概念）。

第 5 步：返回聚焦的答案（Return a focused answer）

对检索到的文档做提炼，返回内容包含三部分：

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

注意第 5 步的措辞是 "Summarize"（总结）而非 "Return the docs"（返回文档）——这正呼应了代理描述中"不污染上下文"的设计：子代理消化掉大段原始文档，主会话只拿到浓缩后的答案。

三、选型判据背后的数据字段：这些指标从哪来

第 3 步提到的 "benchmark score"、"版本"等判据并非凭空设定，而是直接对应 resolve-library-id 返回结果的字段结构。MCP 服务端的工具注册处（packages/mcp/src/index.ts#L175-L263）在 resolve-library-id 的 description 中声明了每个结果项包含：

• Library ID：Context7 兼容标识符，格式 /org/project；
• Name / Description：库名与简短摘要；
• Code Snippets：可用代码示例数量；
• Source Reputation：权威性指标（High / Medium / Low / Unknown）；
• Benchmark Score：质量指标（100 为最高分）；
• Versions：可用版本列表，格式 /org/project/version。

服务端将搜索结果渲染为文本时，packages/mcp/src/lib/utils.ts#L25-L58 中的 formatSearchResult 函数负责拼装这些字段。其中 Source Reputation 由数值 trustScore 映射而来（>=7 为 High，>=4 为 Medium，其余为 Low，缺失为 Unknown）；Code Snippets、Benchmark Score、Versions 均只在取值有效时才输出。也就是说，docs-researcher 指令中"看 Benchmark Score、看版本列表"的操作，读到的正是这个格式化后的字段集合。

代理指令还补充了一条上面判据之外的规则："If resolve-library-id returns multiple matches, prefer official/primary packages over community forks"（多个匹配时优先官方/主包，而非社区 fork）。结合源码中 Source Reputation 字段的存在可以推断：这条指引的落地方式正是借助 High/Medium 声誉标签与名称精确度做二次甄别。

工具调用的次数上限

值得注意的实现细节是：MCP 服务端在两个工具的描述中都写入了硬性调用上限（packages/mcp/src/index.ts#L211、packages/mcp/src/index.ts#L273）：

"Do not call this tool more than 3 times per question."

即 resolve-library-id 和 query-docs 每个问题各最多调用 3 次，超过后应使用已有最佳结果。这意味着 docs-researcher 的五步流程在有限预算内运行：一次解析（顶多 3 次尝试）+ 按概念拆分的若干次查询（顶多 3 次），天然约束了子代理的探索深度。

四、Guidelines：多概念拆分与版本意识

docs-researcher.md 末尾的 Guidelines 部分给出了四条行为约束，这是该代理与"随便查一下"的本质区别所在，完整继承如下：

1. 一次查询限定一个概念：在 query 参数中描述要查什么，但保持每个 query 只覆盖单一概念；
2. 多概念问题拆成多次 query-docs 调用：例如问题同时涉及 routing、auth、caching 时，用同一个 library ID 分别发起多次调用；例外是问题本身就是问"这些概念如何交互"（如"Next.js 里路由和缓存如何配合"），此时合并查询才是合理的——指令原文给出的理由是"combined queries dilute ranking and return shallow results for each topic"（合并查询会稀释排序结果，导致每个主题都只返回浅层内容）；
3. 版本意识：当用户提到版本（如 "Next.js 15"），若解析结果中存在版本专用的库 ID，应优先使用，如 /vercel/next.js/v15.1.8；
4. 保持回答精炼：目标是回答问题，而不是把整个文档倾倒出来（"the goal is to answer the question, not dump entire documentation"）。

第 2 条在 MCP 服务端的 query-docs 参数描述中得到了呼应（packages/mcp/src/index.ts#L282-L286），那里甚至给出了好/坏示例：

Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'.

也就是说，代理指令层面的"拆分多概念"与服务端参数校验层面的"single concept"是同一套检索策略的两道防线：代理负责在发起调用前拆分，工具描述负责在单次调用内收敛。

五、底层实现链路：两个 MCP 工具如何落地

docs-researcher 代理本身只是一份 Markdown 提示词，真正的执行能力来自 Context7 的 MCP 服务端（packages/mcp/src/index.ts）。把整条链路串起来看：

1. 工具注册与参数校验。 createMcpServer() 中通过 server.registerTool 注册两个工具，输入参数用 Zod 校验：

• resolve-library-id：query（string）+ libraryName（string）；
• query-docs：libraryId（string，如 /mongodb/docs、/vercel/next.js、/vercel/next.js/v14.3.0-canary.87）+ query（string）。

两个工具都标注了 readOnlyHint: true、idempotentHint: true——对代理来说这意味着调用是只读且可重试的，在子上下文中反复尝试没有副作用风险。

2. 别名重写（aliasArgs）。 LLM 客户端经常照抄工具描述中的措辞而不是字面 schema 键名，例如把 query-docs 的 libraryId 写成 libraryName，导致 Zod 校验直接失败。服务端在 schema 前加了一层 z.preprocess(aliasArgs(...))（packages/mcp/src/index.ts#L110-L146），把常见的幻觉别名（如 userQuery、question → query；context7CompatibleLibraryID、libraryID、libraryName → libraryId）在验证前重写为规范键名。对 docs-researcher 这类由 LLM 驱动调用工具的代理来说，这层容错显著提升了流程的通过率。

3. API 调用。 工具处理函数最终落到 packages/mcp/src/lib/api.ts：

• searchLibraries()（packages/mcp/src/lib/api.ts#L118-L144）请求 GET {base}/v2/libs/search?query=...&libraryName=...，返回结果数组与错误信息；
• fetchLibraryContext()（packages/mcp/src/lib/api.ts#L152-L183）请求 GET {base}/v2/context?query=...&libraryId=...，返回按相关性重排后的文档上下文文本。

两个请求均设置了 60 秒的 AbortSignal.timeout 上限；fetchLibraryContext 在拿到空响应时会返回一段明确指引——提示库 ID 可能无效，应改用 resolve-library-id 重新解析。这为代理流程的"第 2 步兜底"提供了服务端支持：即便代理选错了 ID，错误信息本身也会把它引导回正确的流程分支。

4. 认证上下文。 服务端通过 getClientContext() 获取当前客户端的 API Key 等上下文（packages/mcp/src/index.ts#L92-L108）。对应到 Claude Code 侧：插件 MCP 配置会自动读取环境变量 CONTEXT7_API_KEY（plugins/claude/context7/README.md），不设置则走匿名配额。因此推荐在启动 Claude Code 前配置：

# e.g. in ~/.zshrc or ~/.bashrc
export CONTEXT7_API_KEY="your-api-key"

六、与插件内其他组件的协作关系

在 Claude Code 插件的四个组件中，docs-researcher 与另外三个共享同一套工具与同一套"resolve → select → query"流程，差异只在执行位置与触发方式：

组件	文件	触发方式	上下文位置
Agent（本文主角）	plugins/claude/context7/agents/docs-researcher.md	显式 spawn docs-researcher ...	独立子上下文
Skill	plugins/claude/context7/skills/context7-mcp/SKILL.md	提到库/框架时自动触发	主会话
Command	plugins/claude/context7/commands/docs.md	手动 /context7:docs <library> [query]	主会话
MCP Server	packages/mcp/src/index.ts	被以上三者调用	—

Skill 的 SKILL.md 与代理指令使用的是同构的"四步流程"（Resolve → Select → Fetch → Use）和同样的多概念拆分规则；/context7:docs 命令则额外支持直接传库 ID 跳过解析步骤（plugins/claude/context7/commands/docs.md）：

/context7:docs react hooks
/context7:docs /vercel/next.js/v15.1.8 app router

命令文档中的"## How It Works"与代理流程互为印证：以 / 开头的参数直接作为 Context7 ID，否则先 resolve-library-id 再 query-docs。可以推断，docs-researcher 的价值恰恰在于：当 Skill 和命令在主会话中执行同样流程时，所有中间检索文本都会留在主上下文里；而 spawn 代理后，这些中间产物被隔离在子窗口，主会话只收到最终答案。

七、安装与验证

使用 docs-researcher 的前提是安装 Context7 Claude Code 插件（plugins/claude/context7/README.md）：

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

（Claude Code 交互界面中等价命令为 /plugin marketplace add upstash/context7 与 /plugin install context7@context7-marketplace，见 docs/clients/claude-code.mdx。）

安装后的验证路径：

1. 确认工具可用：会话中让 Claude 调用 resolve-library-id 查询任意库，应返回带 Library ID、Source Reputation、Benchmark Score 等字段的结果列表（格式由 packages/mcp/src/lib/utils.ts 的 formatSearchResults 生成）；
2. spawn 代理：输入 spawn docs-researcher to look up Supabase auth methods，预期返回的是浓缩后的答案（直接回答 + 代码示例 + 引用），而非大段原始文档；
3. 版本查询：用 spawn docs-researcher: how do I configure middleware in Next.js 15? 验证它是否按第 3 步规则选择了带版本后缀的库 ID。

八、小结

docs-researcher 是 Context7 插件在 Claude Code 生态中的"上下文卫生"方案：它把文档调研这类高频、低价值密度的工具调用从主会话中剥离出去，用一份结构清晰的五步指令（识别库 → 解析 ID → 按名称/质量分/版本选型 → 单概念查询 → 浓缩回答）约束子代理的行为边界。它的可行性不依赖提示词本身，而是由 MCP 服务端的一系列实现保障——工具调用的 3 次上限、single concept 的参数约束、参数别名容错、以及"ID 无效时回指引到 resolve"的错误兜底。对于在长任务中频繁需要最新库文档的开发者，spawn 这个轻量 Sonnet 代理，是比在主会话里直接查文档更可控、更省上下文的选择。