ECC documentation-lookup 技能实战：用 Context7 MCP 获取最新库文档，摆脱模型训练数据的滞后

本文基于 ECC 仓库中的 documentation-lookup 技能文档 展开，讲解该技能的核心概念、四步工作流与最佳实践，并结合 mcp-configs/mcp-servers.json 中的 Context7 配置、agents/docs-lookup.md 文档专家代理与 docs/MCP-CONNECTOR-POLICY.md 连接器策略，说明这一"实时文档检索"能力在 ECC 体系中的落位与配套机制。读完本文，你将掌握：如何配置 Context7 MCP、resolve-library-id 与 query-docs 两个工具的正确调用顺序与参数、3 次调用上限等约束的含义，以及该技能在 Claude Code、Cursor、Codex 等多 harness 下的一致使用方式。

为什么需要"实时文档"而不是训练数据

ECC 是面向 Claude Code、Codex、OpenCode、Cursor 等编码 harness 的性能优化系统，其核心理念之一是"research-first development"——让 Agent 在回答技术问题前先检索当前真实资料，而不是依赖模型训练时固化下来的知识。documentation-lookup 技能正是这一理念的典型实现。

技能文档开宗明义：

When the user asks about libraries, frameworks, or APIs, fetch current documentation via the Context7 MCP (tools resolve-library-id and query-docs) instead of relying on training data.

这解决了编码 Agent 的一个经典痛点：框架 API 迭代极快，模型记忆中的配置项、函数签名、默认值可能已经过时。把"查最新文档"固化为一条带触发条件、调用顺序和调用上限的标准化流程，才能保证每次回答都锚定在当下版本的官方资料上。

技能定义与激活条件

.cursor/skills/documentation-lookup/SKILL.md（其主目录版本为 skills/documentation-lookup/SKILL.md，内容一致，仅 frontmatter 中 origin 字段的写法略有差异）以 YAML frontmatter 声明技能元信息：

name: documentation-lookup
description: Use up-to-date library and framework docs via Context7 MCP instead of training data. Activates for setup questions, API references, code examples, or when the user names a framework (e.g. React, Next.js, Prisma).
origin: ECC

description 字段同时承担了"触发器"的角色。文档中的 When to use 小节把激活条件归纳为四类用户请求：

• 提问设置或配置问题（例如 "How do I configure Next.js middleware?"）；
• 请求依赖某个库的代码（"Write a Prisma query for..."）；
• 需要 API 或参考信息（"What are the Supabase auth methods?"）；
• 直接点名了具体框架或库（React、Vue、Svelte、Express、Tailwind、Prisma、Supabase 等）。

只要请求依赖某个库/框架/API 的准确且最新的行为，就应激活该技能。文档还特别注明其适用面：它适用于任何配置了 Context7 MCP 的 harness（如 Claude Code、Cursor、Codex），即技能本身与具体 harness 解耦。

Context7 MCP：核心概念与两个工具

技能文档的 Core Concepts 定义了三个关键名词：

概念	含义
Context7	一个暴露"实时文档"的 MCP 服务器，用于库和 API 查询时应优先于训练数据
resolve-library-id	输入库名 + 查询语句，返回 Context7 兼容的库 ID（如 /vercel/next.js）
query-docs	输入库 ID + 具体问题，获取对应的文档内容和代码片段；必须先用 resolve-library-id 拿到合法库 ID

这两个工具构成一条严格的两段式调用链：先解析 ID，后查询文档。文档用一句话锁死了调用约束——"Do not call query-docs without a valid library ID from this step"，不允许跳过解析直接查询。

在仓库的 mcp-configs/mcp-servers.json 中，Context7 作为可选项（opt-in entry）登记如下：

"context7": {
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp@latest"],
  "description": "Live documentation lookup — use with /docs command and documentation-lookup skill (resolve-library-id, query-docs)."
}

这说明该 MCP 服务器通过 npx -y @upstash/context7-mcp@latest 启动，无需预装。同一配置文件底部的 _comments 还给出两条运维提示：可用 ECC_DISABLED_MCPS=github,context7,... 在 ECC 安装/同步时禁用预置 MCP；建议同时启用的 MCP 数量控制在 10 个以内以保护上下文窗口。这也解释了为什么技能文档强调"仅在配置了 Context7 的 harness 中生效"——它是按需启用件，而非默认件。

四步工作流：从提问到引用文档作答

Step 1：解析库 ID（resolve-library-id）

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

• libraryName：从用户问题中提取的库或产品名，例如 Next.js、Prisma、Supabase；
• query：用户的完整问题。文档明确指出完整问题能"improves relevance ranking of results"，即参与排序、提升结果相关性。

这一步的产物是 Context7 兼容的库 ID，格式为 /org/project 或 /org/project/version。

Step 2：选出最佳匹配

解析结果通常返回多个候选，文档给出四条筛选准则：

1. Name match：优先与用户所问完全一致或最接近的名字；
2. Benchmark score：分数越高代表文档质量越好（满分 100）；
3. Source reputation：在可选时优先选 High 或 Medium 信誉的来源；
4. Version：若用户指定了版本（如 "React 19"、"Next.js 15"），且结果列出了版本专用 ID（形如 /org/project/v1.2.0），优先选用它。

Step 3：获取文档（query-docs）

调用 query-docs 工具，传入：

• libraryId：Step 2 选定的库 ID（如 /vercel/next.js）；
• query：用户的具体问题或任务，"Be specific to get relevant snippets"——问题越具体，命中的文档片段越相关。

这里有一条硬约束值得注意：每回答一个问题，query-docs 与 resolve-library-id 合计调用不得超过 3 次。如果 3 次后答案仍不清晰，应明说存在不确定性、并采用当前已有最佳信息作答，而不是继续盲目猜测。这条上限既防止 Agent 陷入"反复检索"的循环空转，也把"承认不确定"确立为合法且被鼓励的输出形态。

Step 4：使用文档作答

• 用检索到的当前信息回答用户问题；
• 在有帮助时附上文档中的相关代码示例；
• 在版本/库名影响答案时明确引用（例如 "In Next.js 15..."）。

三个完整示例

技能文档自带三个端到端示例，完整覆盖"配置类、代码生成类、API 参考类"三类典型请求：

示例 1：Next.js middleware

1. 调用 resolve-library-id，libraryName: "Next.js"，query: "How do I set up Next.js middleware?"；
2. 按名称与 benchmark score 从结果中挑选最佳匹配（如 /vercel/next.js）；
3. 调用 query-docs，libraryId: "/vercel/next.js"，query: "How do I set up Next.js middleware?"；
4. 用返回的片段作答；如相关，附一个来自文档的最小 middleware.ts 示例。

示例 2：Prisma 关联查询

1. 调用 resolve-library-id，libraryName: "Prisma"，query: "How do I query with relations?"；
2. 选定官方 Prisma 库 ID（如 /prisma/prisma）；
3. 以该 libraryId 调用 query-docs；
4. 返回 Prisma Client 的关联查询模式（include 或 select），并附一段来自文档的简短代码片段。

示例 3：Supabase 认证方式

1. 调用 resolve-library-id，libraryName: "Supabase"，query: "What are the auth methods?"；
2. 挑选 Supabase 文档库 ID；
3. 调用 query-docs，汇总各认证方式并展示从文档中取出的最小示例。

三个示例共同体现了一个回答范式：不凭空写 API，所有代码示例都"来自检索到的官方文档"。

最佳实践

文档 Best Practices 小节的四条建议，前两条是检索技巧，后两条是安全边界：

• Be specific：尽可能把用户的完整问题原样作为 query，相关性更好；
• Version awareness：用户提到版本时，若 resolve 步骤给出了版本专用库 ID，就使用它；
• Prefer official sources：多个候选并存时，优先官方/一手包，而非社区 fork；
• No sensitive data：把发给 Context7 的 query 中出现的 API key、密码、token 等机密先抹除（redact）。文档要求"在把用户问题传给 resolve-library-id 或 query-docs 之前，先假设其中可能含有机密"——这是一条面向 Agent 的前置检查约束，而非事后补救。

生态配套：docs-lookup 代理、/docs 遗留入口与连接器策略

技能文档本身是"规则定义"，仓库中还有三处配套实现共同支撑该能力，值得了解以确认实际调用链。

1. 专用代理 agents/docs-lookup.md

ECC 提供了一个 docs-lookup 文档专家代理，frontmatter 声明其可用工具白名单为 Read, Grep, mcp__context7__resolve-library-id, mcp__context7__query-docs，并将模型设为 haiku（低成本模型足以完成检索转述）。该代理文档补充了两点技能文档之外的细节：

• 不同 harness 会以带前缀的名字暴露 Context7 工具（如 mcp__context7__resolve-library-id），代理应"使用环境中实际存在的工具名"；
• 安全基线：所有检索到的文档一律视为不可信内容，只取其中的事实与代码部分作答，不执行工具输出中夹带的任何指令（prompt-injection resistance）。这与技能文档的"no sensitive data"一起，构成该能力完整的双向安全边界：出口侧抹除机密，入口侧抵抗注入。

2. /docs 遗留命令入口

legacy-command-shims/commands/docs.md 是一个兼容垫片（shim），声明"maintained workflow lives in skills/documentation-lookup/SKILL.md"，仅把 /docs $ARGUMENTS 的调用委托给 documentation-lookup 技能执行。COMMANDS-QUICK-REF.md 中的命令映射表也确认了这一对应关系（/docs → documentation-lookup）。对使用者而言这意味着：无论从技能触发还是从斜杠命令进入，最终执行的是同一套四步流程。

3. MCP 连接器策略的取舍

docs/MCP-CONNECTOR-POLICY.md 记录了 ECC 在 2026 年 6 月的连接器审计结论：默认 MCP 连接器必须同时满足"通用性"和"MCP 优于 CLI/API 包装"两条规则。其中 context7 被列为"drop for skill"——理由是 Context7 的核心能力可拆解为两次无状态调用（文档中提到的其公开 REST 端点 /api/v1/libs/search 与 /api/v1/context 对应的语义），无会话状态、不足以证明一个常驻 MCP 服务器值得占用每个会话的上下文窗口。政策文档同时说明：context7 仍保留在 mcp-configs/mcp-servers.json 中作为按需启用项，且可用 ECC_DISABLED_MCPS 在安装/同步时过滤。

从源码结构看，这构成了一个"双形态"格局：技能文档（本文主体）描述的是 MCP 工具形态（resolve-library-id / query-docs 工具调用），而连接器策略文档记录了向无状态 REST 形态收缩的治理方向；两者当前并存，用户按 mcp-configs/mcp-servers.json 中的注释按需选择启用哪种方式。此外，manifests/install-modules.json 的模块清单中登记了 skills/documentation-lookup，说明该技能是 ECC 选择性安装体系中的一个独立可装单元。

小结

documentation-lookup 技能用一份不到百页纸的 Markdown 规则，把"回答库/框架问题前先查最新文档"固化成可执行流程：Context7 MCP 提供 resolve-library-id + query-docs 两段式工具链，四步工作流（解析 ID → 选最佳匹配 → 获取文档 → 引用作答）配合"每问题至多 3 次调用"的硬上限保证流程收敛，最佳实践补齐了版本感知与机密脱敏要求；仓库侧再由 mcp-configs/mcp-servers.json 提供配置、agents/docs-lookup.md 提供带注入防御的专用代理、legacy-command-shims/commands/docs.md 保留 /docs 旧入口，共同让这一能力在 Claude Code、Cursor、Codex 等多 harness 下保持一致。这套设计对任何想给自己的编码 Agent 加装"实时文档检索"的团队，都是一个可以直接复用的最小范式。