find-docs

文档查找

使用 Context7 CLI 检索任何库的当前文档和代码示例。

使用 npx ctx7@latest 运行命令，这样设置始终使用最新 CLI，无需全局安装：

npx ctx7@latest library <name> "<query>"
npx ctx7@latest docs <libraryId> "<query>"

如果您更喜欢使用裸 ctx7 命令，也可以选择全局安装：

npm install -g ctx7@latest

工作流程

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

# 步骤 1：解析库 ID
npx ctx7@latest library <name> "<query>"

# 步骤 2：查询文档
npx ctx7@latest docs <libraryId> "<query>"

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

重要提示：每个问题不要运行这些命令超过 3 次。如果 3 次尝试后仍未找到所需内容，请使用您获得的最佳结果。

步骤 1：解析库

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

npx ctx7@latest library React "How to clean up useEffect with async operations"
npx ctx7@latest library "Next.js" "How to set up app router with middleware"
npx ctx7@latest library Prisma "How to define one-to-many relations with cascade delete"

使用带有正确标点符号的官方库名称（例如，“Next.js”而不是“nextjs”，“Customer.io”而不是“customerio”，“Three.js”而不是“threejs”）。如果结果看起来不对，请在更改查询之前尝试其他拼写，例如 next.js。

始终传递 query 参数——它是必需的，并直接影响结果排名。使用用户的意图来构建查询，这有助于在多个库名称相似时消除歧义。不要在查询中包含任何敏感或机密信息，例如 API 密钥、密码、凭据、个人数据或专有代码。

结果字段

每个结果包括：

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

选择过程

1. 分析查询以了解用户正在寻找哪个库/包
2. 根据以下条件选择最相关的匹配项：
   • 名称与查询的相似性（优先精确匹配）
   • 描述与查询意图的相关性
   • 文档覆盖率（优先选择代码片段数较高的库）
   • 来源信誉（考虑信誉高或中的库更权威）
   • 基准分数（越高越好，100 为最高）
3. 如果存在多个良好匹配，请确认这一点，但继续使用最相关的一个
4. 如果没有良好匹配，请明确说明并建议优化查询
5. 对于模糊查询，在继续最佳猜测匹配之前请求澄清

版本特定 ID

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

# 通用（最新索引）
npx ctx7@latest docs /vercel/next.js "How to set up app router"

# 版本特定
npx ctx7@latest docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"

可用版本在 library 命令输出中列出。使用与用户指定版本最接近的匹配。

步骤 2：查询文档

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

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

编写好的查询

查询直接影响结果质量。要具体并包含相关细节，但每个查询只针对一个主题——如果问题涉及多个不同的概念，请为每个概念单独运行 docs 命令，而不是将它们组合在一起，除非问题是关于这些概念如何交互。不要在查询中包含任何敏感或机密信息，例如 API 密钥、密码、凭据、个人数据或专有代码。

质量	示例
好	"How to set up authentication with JWT in Express.js"
好	"React useEffect cleanup function with async operations"
差（太模糊）	"auth"
差（太模糊）	"hooks"
差（太宽泛）	"routing and auth and caching in Next.js"

尽可能使用用户的完整问题作为查询——模糊的单词查询会返回通用结果，多主题查询会稀释排名并为每个主题返回浅层结果。

输出包含两种类型的内容：代码片段（带标题和语言标记块）和信息片段（带有面包屑上下文的散文解释）。

身份验证

无需身份验证即可工作。如需更高速率限制：

# 选项 A：环境变量
export CONTEXT7_API_KEY=your_key

# 选项 B：OAuth 登录
npx ctx7@latest login

错误处理

如果命令因配额错误（“月度配额已用完”或“超出配额”）而失败：

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

不要静默回退到训练数据——始终告诉用户为什么没有使用 Context7。

常见错误

• 库 ID 需要 / 前缀——/facebook/react 而不是 facebook/react
• 始终先运行 npx ctx7@latest library——npx ctx7@latest docs react "hooks" 在没有有效 ID 的情况下会失败
• 使用描述性查询，而不是单个单词——"React useEffect cleanup function" 而不是 "hooks"
• 每个查询一个主题——将 "routing and auth and caching" 拆分为每个概念单独的 docs 命令，除非问题是关于它们如何交互
• 不要在查询中包含敏感信息（API 密钥、密码、凭据）