find-docs

用途

find-docs 用于检索任意开发者技术的最新文档、API 参考和代码示例。当用户询问某个库、框架或产品的用法、API 或代码示例时，该技能通过 Context7 CLI 获取当前文档，避免依赖可能过时的训练数据。

主要能力

将包或产品名称解析为 Context7 兼容的库 ID。
使用库 ID 查询最新文档与代码示例。
支持版本特定的库 ID，格式为 /org/project/version。
解析结果包含库 ID、名称、描述、代码片段数量、来源声誉（High、Medium、Low、Unknown）、基准分数（最高 100）以及可用版本列表。
查询输出包含两类内容：带标题和语言标记的代码片段，以及带面包屑上下文的说明性文字片段。

使用方式

通过 Context7 CLI 直接运行，命令形式为：

pnpx ctx7@latest <command>

工作流为两步：

第一步，解析库 ID：

ctx7 library <name> <query>

示例：

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"

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

第二步，查询文档：

ctx7 docs <library-id> <query>

示例：

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"

版本特定查询示例：

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

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

可用版本列在 ctx7 library 的输出中，应选择与用户指定版本最接近的匹配。

查询编写建议

查询内容直接影响结果质量，应具体并包含相关细节。尽量使用用户的完整问题作为查询，模糊的单词查询会返回泛化结果。

好的示例：

"How to set up authentication with JWT in Express.js"
"React useEffect cleanup function with async operations"

差的示例：

"auth"
"hooks"

不要在查询中包含任何敏感或机密信息，例如 API 密钥、密码、凭据、个人数据或专有代码。

结果选择

解析库时，根据以下因素选择最相关的匹配：名称与查询的相似度（优先精确匹配）、描述与查询意图的相关性、文档覆盖度（优先代码片段数量较多的库）、来源声誉（High 或 Medium 更权威）、基准分数（越高越好，最高 100）。若存在多个良好匹配，应说明并继续使用最相关的一个；若无良好匹配，应明确说明并建议优化查询；若查询有歧义，应先请求澄清再继续。

认证

无需认证即可使用。如需更高请求配额，可采用以下方式之一：

# 方式 A：环境变量
export CONTEXT7_API_KEY=your_key

# 方式 B：OAuth 登录
ctx7 login

错误处理

若命令因配额错误失败（如 "Monthly quota reached" 或 "quota exceeded"）：

告知用户其 Context7 配额已耗尽。
建议其认证以获得更高限额：ctx7 login。
若用户无法或不愿认证，可基于训练知识回答，并明确说明内容可能已过时。

不要静默回退到训练数据，始终告知用户为何未使用 Context7。

常见错误

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

限制

每个问题不要运行这些命令超过 3 次；若 3 次尝试后仍找不到所需内容，使用已有的最佳结果。
未认证时请求配额有限，超出后需认证或基于训练知识回答。
查询中不得包含敏感或机密信息。

适用场景

当用户询问某个开发者技术的文档、API 参考或代码示例时使用，尤其适合需要获取比训练数据更新的库用法、配置方式或版本特定行为的场景。