Context7 pi 扩展中的 /c7-docs 斜杠命令：resolve-library-id 与 query-docs 两段式文档检索流程解析

本文围绕 c7-docs.md 这一提示词文件展开，讲解 Context7 官方 pi 扩展（@upstash/context7-pi）中 /c7-docs 斜杠命令的占位符语义、四步执行流程，以及"已知库 ID 时跳过解析"的快捷规则。读完本文，你将掌握该命令在 pi 编码代理中的实际调用方式，并理解它底层如何依次调用 resolve-library-id 与 query-docs 两个工具、最终请求 Context7 API 的哪两个端点，从而在代理会话中稳定地获取最新的库文档与代码示例。

一、/c7-docs 是什么：一个斜杠命令提示词

c7-docs.md 位于 packages/pi/prompts/ 目录下，是 pi 扩展自带的斜杠命令定义文件。pi 扩展的 package.json 在 pi.prompts 字段中声明了 "./prompts" 目录，pi 运行时会把该目录下的每个 .md 文件注册为一条 / 命令，因此这个文件对应的就是 /c7-docs 命令（命令名取自文件名）。

文件分为两部分：

Frontmatter 元数据

---
description: Fetch Context7 documentation for a library
argument-hint: <library> <question>
---

• description：命令在 pi 斜杠命令列表中的展示说明；
• argument-hint: <library> <question>：提示用户该命令需要两个参数——库名和问题。实际调用形如：

/c7-docs next.js Cache Components

提示词正文（即命令被触发后注入给 LLM 的指令模板）

Look up documentation for `$1` using Context7.

1. Determine what to look up in the library's documentation from `${@:2}`.
2. Call the `resolve-library-id` tool with `libraryName="$1"` and what to look up as `query` to find the best matching library.
3. Call the `query-docs` tool with the selected library ID and what to look up as `query`.
4. Summarize the answer for the user with code examples from the returned snippets. Cite the Context7 library ID you used.

If `$1` is already in `/org/project` or `/org/project/version` format, skip library resolution and call `query-docs` directly.

这里有两类占位符需要理解：

占位符	含义	示例（输入 /c7-docs next.js Cache Components）
$1	第一个参数，库名	next.js
${@:2}	从第二个参数开始的全部剩余参数拼接，即用户的实际问题	Cache Components

二、四步工作流程逐步拆解

提示词正文为 LLM 规定了一条严格的线性执行链。结合扩展内的工具实现，可以精确还原每一步的行为。

第 1 步：确定检索意图

Determine what to look up in the library's documentation from ${@:2} —— 让模型先从用户的问题文本中提炼出一个聚焦的检索 query。这与 query-docs 工具参数描述中"scoped to a single concept"（每次调用只查一个概念）的要求一致，参数描述在 packages/pi/lib/prompts.ts 中定义，要求问题跨越多个独立概念时拆分为多次调用，而不是拼在一起。

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

resolve-library-id 工具定义于 packages/pi/lib/tools/resolve-library-id.ts。它接收两个必填参数（TypeBox schema 声明）：

• libraryName：库名，要求使用官方写法与标点，例如传 Next.js 而不是 nextjs；
• query：要查什么，用于让 Context7 API 对候选库按相关性排序。

工具 execute 内部调用 searchLibraries(query, libraryName)（见 packages/pi/lib/api.ts），请求 https://context7.com/api 下的 v2/libs/search 端点。若结果为空，直接返回错误信息（或 No libraries found matching the provided name.）；否则把结果按 Available Libraries: 前缀格式化后返回。

第 3 步：调用 query-docs 拉取文档

从返回的候选列表中选择最佳库后，把选中的库 ID 作为 libraryId 传给 query-docs。该工具定义于 packages/pi/lib/tools/query-docs.ts，参数为 libraryId + query，内部调用 fetchLibraryContext(query, libraryId) 请求 v2/context 端点，返回纯文本的文档片段与代码示例。

第 4 步：汇总作答并引用库 ID

Summarize the answer for the user with code examples from the returned snippets. Cite the Context7 library ID you used. —— 要求回答中带上代码示例并明确标注所用的 Context7 库 ID（形如 /vercel/next.js），保证答案可溯源。

三、快捷规则：已知库 ID 时跳过解析

提示词最后一句是一条重要的短路规则：

If $1 已经是 /org/project 或 /org/project/version 格式，跳过库解析，直接调用 query-docs。

这意味着用户可以绕过检索直接指定精确的库（甚至指定版本）：

/c7-docs /vercel/next.js/v14.3.0-canary.87 Cache Components

这一规则与两个工具的参数描述完全呼应：query-docs 的 libraryId 参数描述（packages/pi/lib/prompts.ts）明确说明库 ID 可以来自 resolve-library-id 的返回，也可以直接来自用户输入；而 resolve-library-id 的描述中同样写明"当用户已在查询中显式提供 /org/project 或 /org/project/version 格式的 ID 时，无需先调用本工具"。

四、工具结果长什么样：搜索结果格式化细节

第 2 步返回的候选列表并非裸 JSON，而是经过 packages/pi/lib/format.ts 中 formatSearchResults 渲染的文本。每个候选项包含：

• Title / Context7-compatible library ID / Description：名称、ID 与简介；
• Code Snippets：可用代码示例数量（totalSnippets 为 -1 或 undefined 时不展示）；
• Source Reputation：由 trustScore 映射而来的权威度标签，映射规则在 getSourceReputationLabel 中写死——trustScore >= 7 为 High，>= 4 为 Medium，其余（含负值与缺失）为 Low，未定义时为 Unknown；
• Benchmark Score：质量分（100 为最高），仅在存在且大于 0 时展示；
• Versions / Source：可用版本列表与来源。

此外，若企业 teamspace 开启了库过滤（searchFilterApplied 为真），输出开头会追加一条提示，说明结果已被质量阈值/黑名单过滤。这些字段正是提示词第 4 步"Cite the Context7 library ID"以及选型依据（名称匹配、权威性、示例覆盖、基准分）的数据来源。

五、底层调用链与错误处理

把 c7-docs 命令的完整执行路径串起来，从源码结构看调用链为：

/c7-docs <library> <question>          （packages/pi/prompts/c7-docs.md）
  → LLM 按提示词编排两次工具调用
    → resolve-library-id                 （packages/pi/lib/tools/resolve-library-id.ts）
        → searchLibraries()              （packages/pi/lib/api.ts，GET v2/libs/search）
    → query-docs                         （packages/pi/lib/tools/query-docs.ts）
        → fetchLibraryContext()          （packages/pi/lib/api.ts，GET v2/context）

API 层（packages/pi/lib/api.ts）的几个关键实现事实：

• 认证：读取环境变量 CONTEXT7_API_KEY，有值时附加 Authorization: Bearer <key> 请求头；无值时请求照常发出，仅受 IP 级速率限制。这与 README（packages/pi/README.md）中"免配置即可试用、免费 Key 可提高配额"的说明一致；
• 429：返回限流/超额提示，并区分有无 API Key 给出不同建议文案；
• 404：返回"该库 ID 不存在，请换库"的提示；
• 401：返回"API Key 无效，Key 应以 ctx7sk 前缀开头"的提示；
• v2/context 返回空文本：返回一段指导性错误，建议改用 resolve-library-id 重新解析库 ID——这正好覆盖了第 3 步用错 ID 时的自纠偏场景；
• 所有失败信息最终以纯文本形式经 packages/pi/lib/result.ts 的 toToolResult 包装为 AgentToolResult（content: [{ type: "text", text }]）返回给模型。

六、与自动触发机制的关系：skill 与手动命令互补

/c7-docs 是手动入口；而扩展同时附带 context7-docs skill，教代理在用户随口问起任何库、框架、SDK、CLI 工具或云服务的问题时自动走同一套流程——"即使你以为自己知道答案，也不要用训练数据回答 API 细节"。skill 中还写明了两条与命令提示词一致的约束：每个问题中两个工具各自最多调用 3 次；query 参数不得包含 API 密钥、密码、个人数据或专有代码（因为它会被发送到 Context7 API）。

因此同一套检索逻辑有两个触发面：skill 负责对话中的自动识别，/c7-docs 负责用户显式指定"就是查这个库"的场景，二者共享底层工具实现。

七、安装、使用与验证

安装（pi 扩展机制，来自 packages/pi/README.md）：

pi install npm:@upstash/context7-pi

认证（可选，提高配额）：

export CONTEXT7_API_KEY=ctx7sk_...

写入 shell profile 后即可在 pi 启动时被读取。

两种用法：

# 自动触发：直接提问
how do I configure caching in Next.js 16?

# 手动命令：显式指定库 + 问题
/c7-docs next.js Cache Components

注册验证：扩展入口 packages/pi/extensions/context7.ts 仅做两件事——pi.registerTool(resolveLibraryIdTool) 与 pi.registerTool(queryDocsTool)。packages/pi/tests/extension.test.ts 通过 mock registerTool 收集已注册工具并断言：工具名恰好为 ["query-docs", "resolve-library-id"]；resolve-library-id 参数键为 ["libraryName", "query"]；query-docs 参数键为 ["libraryId", "query"]。测试中还包含一个 15 秒超时的真实 API 冒烟用例，验证 resolve-library-id 对 React 能返回包含 react 的文本结果。

八、小结

c7-docs.md 用不到 15 行文本定义了一条确定性很高的文档检索管线：$1/${@:2} 占位符承载库名与问题，四步指令串起"意图提炼 → resolve-library-id 解析 → query-docs 取文档 → 引用库 ID 作答"的完整闭环，并以 /org/project[/version] 格式识别作为跳过解析的快捷路径。理解这条管线后，你可以确认 pi 扩展中文档类回答的两个关键质量保障点：库 ID 的可溯源引用，以及 lib/api.ts 中对 401/404/429 与空结果的显式错误文本——它们都会原样回传给模型，引导其在出错时按提示自纠（换库或重新解析），而不是直接放弃。