Context7 如何添加私有文档源供 AI 助手查询？

Context7 如何添加私有文档源供 AI 助手查询？

【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7

你的团队有一份内部文档（Git 仓库、Confluence 空间或 OpenAPI 规范），希望 AI 编程助手在写代码时能查到这些私有资料，而不是只依赖模型训练数据。Context7 支持把这类私有文档源加入 teamspace，解析并索引后，AI 助手和 API 就能通过私有源的 library ID 查询它。本文按 Context7 官方文档给出添加私有源的完整操作路径：前提条件、控制台添加步骤、context7.json解析控制、用 API 验证可查询性，以及让 AI 助手使用你自己的 API key。

适用前提（来自文档，先核对）：

• 添加私有源需要Pro 或 Enterprise 套餐；Free 套餐只能添加公开库；
• 需要有一个 teamspace，并且你的角色是Owner 或 Admin（Developer 只能查看源文档，不能添加、刷新或删除私有源）；
• 验证和 AI 助手接入需要 API key，格式为ctx7sk-...，在 Context7 dashboard 的 API Keys 卡片创建，创建后只显示一次，需立即保存。

在 teamspace 的 Sources 页添加私有源

主路径在控制台完成，步骤来自 私有源文档：

1. 进入 teamspace 的Sources标签页。
2. 点击Add another，打开源类型选择器。可选的源类型有：
   • GitHub— 连接 GitHub 账户并选择仓库；
   • GitLab— 连接 GitLab 账户并选择项目；
   • Bitbucket— 连接 Bitbucket 账户并选择仓库；
   • Other Git— 通过 URL 添加任意 Git 仓库；
   • Confluence— 连接 Confluence 工作区；
   • OpenAPI— 添加 OpenAPI 规范。
3. 按提示授权 Context7 访问该源（需要时）。
4. 可选：勾选Generate docs。当仓库几乎没有成文文档时，Context7 会从源码生成文档。这一点公开仓库是自动回退，私有仓库是显式开启的；API 方式对应generateDocs标志。
5. 提交解析。

如果还没有 teamspace，先创建：从 dashboard 左上角下拉菜单选择Create a teamspace并命名。teamspace 成员限制为：Free 仅 1 人（个人），Pro 最多 10 人，Enterprise 不限；只有 teamspace owner 需要付费套餐，受邀成员不需要自己的订阅。详见 teamspace 文档。

可选：用 context7.json 控制解析范围

如果要更精细地控制 Context7 解析哪些内容，可以在仓库根目录提交一个context7.json文件。它控制的是 Context7去哪里找文档，而不是读什么类型的文件（解析的文件类型为.md、.mdx、.markdown、.rst、.txt、.ipynb，见 Adding Libraries）。完整字段说明见 Library Owners，常用配置如下：

{ "$schema": "https://context7.com/schema/context7.json", "projectTitle": "Your Project Name", "description": "Brief description of your project", "folders": ["docs", "guides"], "excludeFolders": ["tests", "dist", "node_modules"], "excludeFiles": ["CHANGELOG.md"], "branch": "main", "rules": ["Always validate user input", "Use TypeScript strict mode"] }

各字段的作用（以官方文档描述为准）：

• folders：只解析列出的目录；为空则扫描整个仓库，根级 markdown 文件始终包含。
• excludeFolders：支持简单目录名、路径、glob 模式（如**/dist、docs/**/internal）。excludeFolders的优先级始终高于folders：文件路径命中排除模式就直接排除；folders非空且文件不在其中则排除；其余才纳入。
• excludeFiles：按文件名排除，只写文件名不写路径。未指定时 Context7 有一组默认排除（如CHANGELOG.md、LICENSE.md、各类*archive*、i18n/zh*等目录）。
• branch：指定要解析的 git 分支；不提供时使用默认分支。
• rules：写给编码 agent 的最佳实践提示，会作为建议出现在提供给 coding agents 的文档上下文中。
• previousVersions/branchVersions：让旧版本（按 tag 或按分支）也可在 Context7 中查询。
• $schema字段可让编辑器提供自动补全和校验。

验证私有文档已可被查询

添加并解析完成后，用 API 直接查询私有源，确认它已可被 AI 助手拿到。私有 Git 仓库的 library ID 形如/owner/repo（见 API Guide）。所有 API 请求都要在Authorization头携带 API key：

curl "https://context7.com/api/v2/context?libraryId=/owner/repo&query=your%20question" \ -H "Authorization: Bearer YOUR_API_KEY"

把YOUR_API_KEY替换为你在 dashboard 创建的 key，把/owner/repo替换为你添加的私有仓库的 library ID（即 context7.com 上该库页面的 URL 路径）。查询建议用具体的自然语言问题而不是单个词，效果与响应都更好。

按 API 文档的错误码判断结果：

错误响应是带error和message字段的 JSON，例如：

{ "error": "library_not_found", "message": "Library \"/owner/repo\" not found. Please check the library ID or your access permissions." }

费用也可以核对：在 teamspace 的Overview标签页可以看到 Parsing Tokens 指标，添加新的私有源会计费，刷新时只对变更内容计费，缓存页面不收费（见 Monitor Usage）。

让 AI 助手使用你自己的私有源

AI 助手接入 Context7 后，查询私有库时用的身份取决于认证方式。以 Claude Code 为例（见 Claude Code 客户端文档）：

• 一键配置：npx ctx7 setup --claude，该流程通过 OAuth 认证、生成 API key 并安装对应的 skill，可选择 CLI 或 MCP 模式；
• 使用自己的 key 而非匿名额度：在 dashboard 创建 API key 后，启动前导出环境变量，插件会自动读取：

# e.g. in ~/.zshrc or ~/.bashrc export CONTEXT7_API_KEY="your-api-key"

设置后重启 Claude Code，可在 dashboard 确认请求计入你自己的套餐。未设置该变量时插件仍可用，但请求走匿名层，速率限制更低。

注意：私有源对查询方的可见性由 teamspace 的角色和套餐决定——Developer 角色可以查看源文档，但要能管理源本身需要 Owner 或 Admin。团队内的助手账号若查不到私有库，先核对该成员的 teamspace 角色。

刷新与删除

私有源添加后不会自动保持最新，需要手动刷新：点击源旁边的刷新图标，Context7 重新解析，且只对变更内容计费。文档建议在文档有重大更新、发布新功能或发现信息过时后刷新，不要频繁刷新以控制成本。

删除源：点击源旁边的垃圾桶图标并在弹窗中确认。该操作不可逆，确认后源文档立即不可用，API 也无法再访问该源。

限制与注意事项

• 计划要求：私有源功能仅 Pro / Enterprise 可用；公开库走 context7.com 的 Add Library 页面，与私有源流程不同。
• 角色要求：仅 Owner 与 Admin 可添加、刷新、删除私有源。
• 解析范围：context7.json只影响"从哪里找"，不会改变被解析的文件类型；私有仓库从源码生成文档必须显式勾选Generate docs（或 API 传generateDocs），不会像公开仓库那样自动回退。

【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7