APPLICATION

构建 Context7 本地替代方案

耗时约一周，为 AI 代理打造的本地优先文档工具。无云端、无速率限制、查询延迟低于 10 毫秒。

admin

• 11 min read
构建 Context7 本地替代方案
梯形图转SCL | AI模型价格对比 | AI工具导航 | ONNX模型库 | Vibe Coding教程 | PLC在线仿真器 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

我使用 Context7 作为 MCP 服务器已有数月。这个想法很棒：AI 代理向云服务查询最新的库文档，而非依赖陈旧的训练数据。它大部分时候都能正常工作——直到它失效。

2026 年 1 月，Context7 将免费层从每月约 6000 次请求大幅削减至 1000 次，并新增了每小时 60 次请求的速率限制。我在第一周就触及了这些限制。突然间，在编码过程中，我的 AI 助手变得……毫无用处。当我需要 Next.js 16 的内容时，它开始幻觉出 Next.js 14 的模式；当我需要 AI SDK v6 完全不同的代理循环 API（内置工具编排）时，它却建议使用旧版 AI SDK v4 的 streamText 回调风格。这正是 Context7 本应解决的问题。

于是我构建了自己的版本。耗时约一周，大部分时间与 Claude Code 结对编程。成果是 Context ——一个 AI 代理的本地优先文档工具。无云端、无速率限制、查询延迟低于 10 毫秒。文档是可移植的 .db 文件，构建一次即可与整个团队共享。

以下是它的实现过程和我的心得。

1、"顿悟时刻"：为何不直接将文档存储在本地？

核心洞察出奇地简单。Context7 和 Deepcon 等云端文档服务做三件事：

  1. 克隆库的文档仓库
  2. 将 Markdown 索引为可搜索的分块
  3. 通过 API 提供结果

步骤 1 和 2 只需每个库版本执行一次。但这些服务在服务器上运行它们，并为步骤 3 按次收费。每一次。每一次。

为何不将步骤 1 和 2 在本地执行，将结果存储为文件，完全跳过网络？

这就是全部理念。context add https://github.com/vercel/next.js 会克隆仓库、解析文档、将所有内容索引到 SQLite 数据库，并将其存储在 ~/.context/packages/nextjs@16.0.db。完成。该 .db 文件现在包含 Next.js 16 的每一篇文档，预索引并准备好即时查询。无需互联网、无速率限制、无月度账单。

2、使用 Claude Code 构建

我使用 Claude Code 作为主要开发伙伴构建了整个项目。不是作为“生成样板代码并修复它”的助手——而是作为架构决策、实现和调试的真正协作者。

2.1 技术栈

这是一个 TypeScript 单仓库项目。以下是底层技术：

  • better-sqlite3 — 嵌入式数据库。无服务器、无配置、仅一个文件。这是使整个系统运作的关键选择。
  • SQLite FTS5 — 全文搜索，支持 BM25 排名和 Porter 词干提取。对于本质上仅几行 SQL 的代码，搜索质量出奇地好。
  • @modelcontextprotocol/sdk — MCP 服务器 SDK。这使得 Claude、Cursor、VS Code Copilot 等能够查询文档。
  • remark-parse + unified — Markdown AST 解析。用于智能分块而非简单的文本分割。
  • commander + @inquirer/prompts — 带有交互式标签选择提示的 CLI 框架。

2.2 构建管道的工作原理

当您运行 context add <repo> 时，实际发生以下步骤：

1. 源检测。 CLI 会判断您提供的是 Git URL、本地目录还是预构建的 .db 文件。Git URL 解析本身支持 GitHub、GitLab、Bitbucket、Codeberg、SSH 简写（git@host:user/repo）和单仓库 URL 模式。

2. 浅克隆。 git clone --depth 1 ——我们只需要文档，而非完整历史。CLI 会获取可用标签并让您交互式选择版本，或通过 --tag v16.0.0 实现自动化。

3. 文档文件夹检测。 自动扫描 docs/、documentation/ 或 doc/ 目录。尊重 .gitignore。按语言过滤——默认为英语，但支持 --lang all 以处理多语言仓库。

4. Markdown 解析和分块。 这是有趣的部分。解析器：

  • 提取 YAML 前置元数据中的标题和描述
  • 按 H2 标题分块（文档的自然单元）
  • 目标为每块约 800 个 token，硬性限制为 1200
  • 超大节首先在代码块边界处分割，然后在段落边界处分割
  • 过滤目录节（通过链接比例 >50% 检测）
  • 剥离 MDX 特定的 React 标签（<AppOnly>、<PagesOnly> 等）
  • 使用内容哈希对相同节进行去重

5. SQLite 打包。 所有内容都放入单个 .db 文件：

CREATE TABLE chunks (
  id INTEGER PRIMARY KEY,
  doc_path TEXT NOT NULL,
  doc_title TEXT NOT NULL,
  section_title TEXT NOT NULL,
  content TEXT NOT NULL,
  tokens INTEGER NOT NULL,
  has_code INTEGER DEFAULT 0
);
CREATE VIRTUAL TABLE chunks_fts USING fts5(
  doc_title, section_title, content,
  content='chunks', content_rowid='id',
  tokenize='porter unicode61'
);

带有 Porter 词干提取的 FTS5 虚拟表意味着“authentication middleware”无需任何花哨的 NLP 即可匹配“authenticating in middleware”。BM25 排名将节标题的权重设为正文内容的 10 倍，文档标题设为 5 倍，这使得结果感觉相关，无需嵌入向量。

2.3 搜索管道：保持简单

当 Claude（或任何 MCP 客户端）调用 get_docs({ library: "nextjs@16.0", topic: "middleware" }) 时，搜索管道完全在进程内运行：

FTS5 查询 → BM25 排名 → 相关性过滤 → Token 预算 → 合并相邻 → 格式化

相关性过滤器会丢弃任何得分低于顶部结果 50% 的内容。Token 预算将输出限制在 2000 个 token——足够有用而不会淹没上下文窗口。来自同一文档的相邻块会重新合并，以便 AI 看到连贯的节而非片段。

总延迟：低于 10 毫秒。相比之下，云端往返需要 100-500 毫秒，加上 AI 代理等待才能继续推理的时间。

这比听起来更重要。AI 编码代理每次会话会进行数十次工具调用。如果每次文档查找增加 300 毫秒的网络延迟，那么每次交互就会有数秒的死时间。在本地，这实际上是免费的。

2.4 真正的胜利：构建一次，随处共享

这是我最兴奋的功能，也是我认为云端服务根本无法匹配的功能。

当您构建文档包时，结果是单个 .db 文件。该文件是完全自包含的——元数据、内容、搜索索引、一切。您可以：

# 构建并导出
context add https://github.com/your-org/design-system \
  --name design-system --pkg-version 3.1 --save ./packages/

# 结果：可移植文件
ls -la packages/design-system@3.1.db
# 2.4 MB - 您的整个设计系统文档，已索引并准备就绪

现在以任何方式共享该文件。上传到 S3 存储桶。提交到仓库。放在共享驱动器上。您的队友使用以下命令安装：

context add https://your-cdn.com/design-system@3.1.db

他们端无需构建步骤、无需克隆仓库、无需等待索引。预构建的包会立即安装，因为它已经索引过。

这是本地优先的关键架构优势。 使用云服务时，每个用户都支付查询成本。使用本地包时，您只需支付一次构建成本并分发结果。这与编译二进制文件与解释脚本的原理相同——提前完成昂贵的工作。

对于内部库来说，这意义重大。您可以记录内部 API，在 CI 中构建包，将其与 npm 包一起发布，团队中的每个开发者都能即时、私密、离线地访问最新文档。没有云服务能看到您的专有 API 查询。

2.5 使用 Claude Code 的心得

以下是我使用 Claude Code 作为主要开发工具的一些诚实观察：

它确实擅长管道代码。 Git URL 解析、CLI 参数处理、SQLite 模式设计——这些繁琐但需要正确的代码类型。Claude Code 快速而准确地完成了这些工作。git 模块处理了我没想到的边缘情况：单仓库标签格式如 @ai-sdk/gateway@1.2.3、SSH 简写 URL、从仓库名称中剥离 -docs 后缀。

它在“品味”决策上挣扎。 例如：分块大小应该是多少？我们应该多积极地过滤低相关性结果？哪些 BM25 权重感觉合适？这些需要人类判断和迭代。我会尝试数值、针对真实文档测试、调整、重复。Claude Code 帮助快速实现了每个变体，但哪个感觉合适的决定权在我。

迭代速度是真正的超能力。 整个项目——CLI、构建管道、搜索引擎、MCP 服务器、测试——在约一周内完成。不是因为代码简单（仅 Markdown 解析就处理了十多个边缘情况），而是因为反馈循环紧凑。描述您想要什么、审查您得到什么、调整、继续。

测试驱动的提示效果良好。 我经常以测试用例的形式描述我想要的行为：“此 Markdown 输入应产生这些分块。”Claude Code 会同时编写实现和测试。当它们不匹配时，我们会共同找出原因。

2.6 数据对比

以下是 Context 与云端替代方案的对比：

3、设置方法

如果您想尝试：

# 安装
npm install -g @neuledge/context

# 添加一些文档
context add https://github.com/vercel/next.js
context add https://github.com/vercel/ai

# 连接到您的 AI 代理（Claude Code 示例）
claude mcp add context -- context serve

它适用于 Claude Desktop、Cursor、VS Code Copilot、Windsurf、Zed 和 Goose。实际上任何兼容 MCP 的代理都可以。MCP 服务器公开单个 get_docs 工具，带有已安装库的动态枚举——AI 可以准确看到可用内容并在相关时查询。

4、未来计划

搜索目前基于关键词（FTS5 + BM25）。它对于直接查询如“middleware authentication”或“ai sdk agent loop”效果良好，但它不理解语义相似性。“我如何保护路由？”不会匹配标题为“Authentication Guards”的节，除非词语重叠。

我计划添加本地嵌入向量用于语义搜索——仍然完全离线，可能使用 ONNX Runtime 配合小型模型。SQLite 架构使这变得简单：添加嵌入表，在构建时计算向量，在搜索时使用余弦相似性查询。

我还在考虑类似 GraphRAG 的关系表，用于遍历连接的文档。当您询问中间件时，您可能还想知道身份验证、路由和错误处理。关系图可以自动显示这些内容。

以及一个包注册表——基于 GitHub 的索引，社区可以发现和共享预构建的文档包。而不是每个人独立构建相同的 Next.js 文档，构建一次并发布。

5、要点

这个项目的核心教训：并非一切都需要成为云服务。

AI 代理的文档是本地优先的完美案例。数据变化不频繁（每个库版本），查询需要快速（代理进行大量查询），隐私很重要（您在询问代码库），“构建一次，永久使用”的模型非常合适。

如果您对速率限制、延迟或为本应是静态文件的内容支付月费感到沮丧——试试看。它是开源的（Apache-2.0）、免费的，并且可以离线工作。

原文链接：I Built a Context7 Local-First Alternative With Claude Code

汇智网翻译整理，转载请标明出处