context7

文档查询

使用 Context7 CLI 检索任意库的最新文档和代码示例。

运行命令前，请确保 CLI 已更新：

npm install -g ctx7@latest

也可以直接运行，无需安装：

npx ctx7@latest <command>

工作流

分两步：先将库名称解析为 ID，然后使用该 ID 查询文档。

# Step 1: Resolve library ID
ctx7 library <name> <query>

# Step 2: Query documentation
ctx7 docs <libraryId> <query>

除非用户明确提供了 /org/project 或 /org/project/version 格式的库 ID，否则必须先调用 ctx7 library 获取有效的库 ID。

重要：每个问题最多运行这些命令 3 次。如果尝试 3 次后仍未找到所需内容，请使用现有结果中最合适的结果。

第 1 步：解析库

将软件包／产品名称解析为 Context7 兼容的库 ID，并返回匹配的库。

ctx7 library react "How to clean up useEffect with async operations"
ctx7 library nextjs "How to set up app router with middleware"
ctx7 library prisma "How to define one-to-many relations with cascade delete"

始终传入 query 参数——这是必需参数，会直接影响结果排序。根据用户的意图构造查询内容，以便在多个库名称相似时消除歧义。查询中不得包含任何敏感或机密信息，例如 API 密钥、密码、凭据、个人数据或专有代码。

结果字段

每个结果都包含：

• 库 ID — Context7 兼容的标识符（格式：/org/project）
• 名称 — 库或软件包名称
• 描述 — 简要说明
• 代码片段 — 可用代码示例的数量
• 来源可信度 — 权威性指标（高、中、低或未知）
• 基准分数 — 质量指标（最高为 100 分）
• 版本 — 可用版本列表。如果用户在查询中指定了版本，请使用其中一个版本。格式为 /org/project/version。

选择流程

1. 分析查询，了解用户要查找的库／软件包
2. 根据以下因素选择最相关的匹配项：
   • 名称与查询的相似度（优先选择完全匹配项）
   • 描述与查询意图的相关性
   • 文档覆盖度（优先选择代码片段数量较多的库）
   • 来源可信度（高或中表示来源更具权威性）
   • 基准分数（分数越高越好，最高为 100）
3. 如果存在多个合适的匹配项，请说明这一点，但继续使用最相关的匹配项
4. 如果没有合适的匹配项，请明确说明并建议改进查询
5. 如果查询有歧义，请先请求用户澄清，再选择最可能的匹配项

特定版本的 ID

如果用户提到了特定版本，请使用特定版本的库 ID：

# General (latest indexed)
ctx7 docs /vercel/next.js "How to set up app router"

# Version-specific
ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"

可用版本列在 ctx7 library 的输出中。请使用最接近用户指定版本的版本。

第 2 步：查询文档

检索已解析库的最新文档和代码示例。

ctx7 docs /facebook/react "How to clean up useEffect with async operations"
ctx7 docs /vercel/next.js "How to add authentication middleware to app router"
ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"

编写优质查询

查询会直接影响结果质量。请具体描述并提供相关细节。查询中不得包含任何敏感或机密信息，例如 API 密钥、密码、凭据、个人数据或专有代码。

质量	示例
好	"How to set up authentication with JWT in Express.js"
好	"React useEffect cleanup function with async operations"
差	"auth"
差	"hooks"

尽可能将用户的完整问题用作查询；含糊的单词查询只会返回通用结果。

输出包含两种内容：代码片段（带标题和语言标记的代码块）以及信息片段（附有面包屑上下文的文字说明）。

身份验证

无需身份验证即可使用。若要提高速率限制：

# Option A: environment variable
export CONTEXT7_API_KEY=your_key

# Option B: OAuth login
ctx7 login

错误处理

如果命令因配额错误（“Monthly quota reached” 或 “quota exceeded”）而失败：

1. 告知用户其 Context7 配额已用尽
2. 建议用户进行身份验证以获得更高的限额：ctx7 login
3. 如果用户无法或选择不进行身份验证，则根据训练知识作答，并明确说明信息可能已过时

不要静默地回退到训练数据——始终告知用户未使用 Context7 的原因。

常见错误

• 库 ID 需要以 / 为前缀——/facebook/react，而不是 facebook/react
• 始终先运行 ctx7 library——没有有效 ID 时，ctx7 docs react "hooks" 会失败
• 使用描述性查询，而不是单个词——"React useEffect cleanup function"，而不是 "hooks"
• 查询中不要包含敏感信息（API 密钥、密码、凭据）