context7

Context7

通过 Context7 文档聚合平台，直接从源库查询最新、特定版本的文档和代码示例。

为什么选择 Context7

优势	描述
当前 API	不会出现幻觉或过时的模式——文档来自实际来源
特定版本	获取你所用确切库版本的文档
代码示例	从实际文档中提取的真实可用代码
广泛覆盖	涵盖 React、Next.js、Vue、Go、Python、Kubernetes 等 1000 多个库

设置

# Install dependencies
cd ~/.claude/skills/context7/Tools
bun install

# Optional: link binaries globally so c7-lookup / c7-resolve / c7-query are on PATH
bun link

# Optional: API key for higher rate limits
export CONTEXT7_API_KEY="ctx7sk_your_key_here"   # context7.com/dashboard

可用的 CLI 工具

工具	用途	简写（运行 bun link 后）	完整命令
lookup	一步完成解析和查询	c7-lookup <library> <query>	bun src/cli/lookup.ts <library> <query>
resolve	查找 Context7 库 ID	c7-resolve <library> [query]	bun src/cli/resolve.ts <library> [query]
query	按已知 ID 查询文档	c7-query <library_id> <query>	bun src/cli/query.ts <library_id> <query>

CLI 标志

这三个 CLI 均接受相同的一组标志。

标志	作用
--json	在 stdout 输出 JSON；禁止输出装饰性内容。可通过管道传给 jq。
--quiet、-q	禁止输出信息/成功日志（警告/错误仍会输出到 stderr）。
--no-cache	本次调用跳过 24 小时磁盘缓存（~/.cache/context7/resolved.json）。
--clear-cache	清除磁盘缓存并退出。
--timeout <ms>	HTTP 超时时间，单位为毫秒。默认值为 30000。
--max-retries <n>	对 429 Rate Limit 响应的重试次数上限（使用 Retry-After）。默认值为 1。
--api-key <key>	覆盖 CONTEXT7_API_KEY 环境变量。
--version、-V	打印版本并退出。
--help、-h	打印用法并退出。

快速参考

完整查询（推荐）

使用一条命令解析库并查询文档：

# After `bun link`:
c7-lookup react "useEffect cleanup function"
c7-lookup next.js "app router middleware"
c7-lookup kubernetes "deployment rolling update"

# Or without linking:
cd ~/.claude/skills/context7/Tools && bun src/cli/lookup.ts react "useEffect cleanup function"

JSON 输出（用于脚本/管道）

c7-lookup react "useState" --json | jq '.libraryId'
c7-resolve drizzle "many to many" --json | jq '.bestMatch'

分步操作（需要时）

c7-resolve react                                    # → /facebook/react
c7-resolve next.js "authentication"                 # → ranked candidates
c7-query /facebook/react "useEffect cleanup"        # → docs for known ID

常见库 ID

库	Context7 ID	CLI 快捷方式
React	/facebook/react	react
Next.js	/vercel/next.js	next.js、nextjs
Vue	/vuejs/vue	vue
Kubernetes	/kubernetes/kubernetes	kubernetes、k8s
Go 标准库	/golang/go	go、golang
Python	/python/cpython	python
Node.js	/nodejs/node	node、nodejs
TypeScript	/microsoft/typescript	typescript、ts
Prisma	/prisma/prisma	prisma
Tailwind	/tailwindlabs/tailwindcss	tailwind、tailwindcss

工作流路由

工作流	触发语句	文件
ResolveLibrary	“查找库 ID”、“解析库”	Workflows/ResolveLibrary.md
QueryDocs	“查询文档”、“获取文档”、“代码示例”	Workflows/QueryDocs.md
FullLookup	“帮我了解 [library]”、“如何使用 [feature]”	Workflows/FullLookup.md

注意事项

如果不了解以下 Context7 API 的实际行为，就很容易踩坑。如果查询出错的原因尚未记录，请将其补充到此列表中。

1. 库 ID 必须以斜杠开头。 /facebook/react 可用；facebook/react 会因一个含糊的“找不到库”错误而失败。错误信息不会告诉你缺少开头的斜杠。
2. 解析器采用模糊匹配和排序，不是确定性的。 resolve.ts <name> 会返回多个候选项，并由一个会考虑可选上下文查询的 LLM 驱动排序器进行排序。范围狭窄的上下文可能会让一个不那么权威的分支排在官方仓库前面。将 ID 传给 query.ts 前，务必检查排名最高的匹配项。
3. 在主版本边界处，版本固定很重要。 库 ID 可以包含版本段：/vercel/next.js/14.2.0。不带版本的 ID 会解析到 Context7 当前视为“最新稳定版”的版本，这可能落后于实际发布版本——如果不固定版本，询问 Next.js 的“app router”时可能会返回 Next 13 文档。当框架在不同主版本之间发生重大变化时，请固定版本。
4. 公共速率限制很严格。 如果没有 CONTEXT7_API_KEY，你会比预期更快触及限制。本技能中“每个问题最多调用 3 次”的建议，是为了防范 Claude 的行为；它并不代表真实的 API 调用额度。需要持续使用时，请从 context7.com/dashboard 获取 API 密钥。
5. 代码片段截断不会提示。 较长的文档页面会返回摘录，而非完整内容。如果返回的示例引用了代码片段中未定义的函数或符号，请勿猜测其作用——应使用范围更窄、更具体的问题重新查询，而不是编造缺失内容。
6. 已知 ID 缓存可能过时。 常见库（react、next.js、kubernetes 等）会直接使用 Tools/src/lib/context7.ts 中的硬编码 ID，完全跳过解析器。如果上游项目重命名仓库或迁移所属组织，缓存的 ID 就会失效，查询也会悄无声息地漏掉结果。要强制重新解析，请使用缓存不识别的别名，或传入 --no-cache。

常见错误

CLI 使用有类型的退出码，以便调用方（包括 Claude）无需解析字符串即可区分故障类别。

退出码	类型	原因	处理方法
3	auth	401 — CONTEXT7_API_KEY 错误或缺失	从 context7.com/dashboard 获取并设置环境变量，或传入 --api-key <key>。
4	not_found	404 — 找不到库或文档路径；或 ID 格式错误（缺少开头的 /）	运行 c7-resolve <name> 获取有效 ID；检查 /org/project 格式。
5	rate_limit	429 — 触及公共速率限制；存在 Retry-After 时会自动重试一次	设置 CONTEXT7_API_KEY 以获得更高限制，或提高 --max-retries。
6	server	5xx — Context7 服务器暂时出错	稍等片刻后重试。
7	timeout	408 — 请求因客户端超时而中止	提高 --timeout（例如 --timeout 60000），或检查网络。
2	(arg)	未知标志、值无效、缺少必需的标志参数	运行 --help。
1	(other)	其他任何错误，包括状态码为 0 的网络错误	检查 stderr 消息；然后重试。

错误始终会向 stderr 输出 Error: <message> 和一行 Hint: <remediation>。使用 --json 时，stdout 保持干净且可解析；stderr 仍会输出适合人工阅读的错误信息。

示例

示例 1：React Hooks 文档

cd ~/.claude/skills/context7/Tools
bun src/cli/lookup.ts react "useEffect cleanup function"

输出包含当前 React 文档中的清理模式示例。

示例 2：Kubernetes Deployment 规范

bun src/cli/lookup.ts kubernetes "deployment spec rolling update strategy"

输出包含当前 K8s API 的 Deployment 参考文档。

示例 3：Next.js App Router

bun src/cli/lookup.ts next.js "middleware authentication app router"

输出包含最新的 Next.js 中间件文档。

示例 4：在 Claude Code 会话中使用

在编码会话期间需要文档时：

User: "How do I implement server-side data fetching in Next.js 14?"

Claude runs:
  cd ~/.claude/skills/context7/Tools && bun src/cli/lookup.ts next.js "server components data fetching"

Then synthesizes response with current patterns (Server Components, not old getServerSideProps)

环境变量

变量	说明	默认值
CONTEXT7_API_KEY	用于提高速率限制的 API 密钥	无（使用公共速率限制）

在 context7.com/dashboard 获取 API 密钥

提示

• 查询要具体，以获得更好的结果
• 每个问题最多调用 3 次——如果尝试 3 次后仍找不到，请使用当前可用的最佳信息
• 如果需要特定版本的文档，请在查询中注明版本（例如，“React 18 并发特性”）
• 结合本地上下文——使用 Context7 验证 API，然后应用到你的代码库中
• 已知 ID 可跳过 API——react、next.js 等常见库使用缓存的 ID，可跳过解析步骤

项目结构

Tools/
├── package.json              # Bun + bin entries (c7-resolve, c7-query, c7-lookup)
├── tsconfig.json             # TypeScript strict config
├── src/
│   ├── index.ts              # Public exports (client, types, helpers)
│   ├── lib/
│   │   ├── context7.ts       # Core API client + retry + typed errors
│   │   ├── cache.ts          # Disk cache for resolved library IDs (24h TTL)
│   │   ├── flags.ts          # Shared CLI argument parser
│   │   └── errors.ts         # Error → exit-code + hint formatter
│   └── cli/
│       ├── lookup.ts         # Full lookup command (c7-lookup)
│       ├── resolve.ts        # Library ID resolver (c7-resolve)
│       └── query.ts          # Documentation query (c7-query)
└── tests/
    ├── cache.test.ts         # Cache I/O + TTL roundtrips
    ├── flags.test.ts         # Argument parsing edge cases
    └── errors.test.ts        # Exit code + hint mapping

API 参考

也可以通过编程方式导入 TypeScript 客户端：

import {
  Context7Client,
  getKnownLibraryId,
  setLogLevel,
  formatError,
  getCached,
  setCached,
} from "./src/index.js";

setLogLevel("warn"); // silence info/success logs

const client = new Context7Client({
  apiKey: process.env.CONTEXT7_API_KEY,
  timeout: 30_000,
  maxRetries: 2,
});

// Full lookup with disk cache
const cached = await getCached("react", 24 * 60 * 60 * 1000);
if (cached) {
  const docs = await client.queryDocs(cached, "useEffect cleanup");
  console.log(docs.rawContent);
} else {
  const result = await client.lookup("react", "useEffect hooks");
  if (result.library) await setCached("react", result.library.id);
  console.log(result.rawContent);
}