我用 Claude Code 构建了一个 Context7 本地优先的替代方案

I’m happy to help translate the article, but I need the actual text you’d like translated. Could you please paste the content of the article (or the portions you want translated) here? I’ll then provide the Simplified Chinese version while preserving the original formatting, markdown, and any code blocks.

Source: https://example.com/your-article

Context — 面向 AI 代理的本地优先文档工具

我在 Context7 削减免费套餐并加入速率限制后构建了它。结果是一个可移植、离线优先的文档数据库，你可以与整个团队共享。

“恍然大悟”时刻：为什么不直接本地存储文档？

云文档服务（Context7、Deepcon 等）通常会做三件事：

1. 克隆 一个库的文档仓库。
2. 索引 Markdown 为可搜索的块。
3. 通过 API 提供 查询结果。

第 1 步和第 2 步只需在 每个库版本 执行一次，但这些服务在它们的服务器上完成，并且对第 3 步的每一次查询都向你收费——每一次都要付费。

解决方案： 在本地完成第 1 步和第 2 步，将结果保存为文件，完全跳过网络。

context add https://github.com/vercel/next.js

• context add 会克隆仓库、解析文档、将所有内容索引到 SQLite 数据库，并将其存放在 ~/.context/packages/nextjs@16.0.db。
• 生成的 .db 文件包含了 Next.js 16 的全部文档，已预先索引，可即时查询。
• 无需网络、无速率限制、也没有月费。

使用 Claude Code 构建

我使用 Claude Code 作为主要的开发伙伴完成了整个项目——它不仅是一个“生成模板‑并‑修复”助理，更是架构、实现和调试的真正协作者。

技术栈

构建流水线工作原理

运行 context add <source> 会执行以下步骤：

1. 源检测 – 判断参数是 git URL、本地目录，还是预构建的 .db 文件。支持 GitHub、GitLab、Bitbucket、Codeberg、SSH 简写 (git@host:user/repo) 以及 monorepo URL 模式。
2. 浅克隆 – 执行 git clone --depth 1（仅克隆文档，不包括完整历史）。CLI 会获取标签并让你交互式选择版本，或通过 --tag v16.0.0 实现自动化。
3. 文档文件夹检测 – 自动扫描 docs/、documentation/ 或 doc/ 目录，遵循 .gitignore，并按语言过滤（默认：英文；--lang all 可处理多语言仓库）。
4. Markdown 解析与分块 –
   • 提取 YAML front‑matter 中的标题和描述。
   • 按 H2 标题（文档的自然单元）进行分块。
   • 目标每块约 800 token，硬上限 1 200。
   • 对超大章节先在代码块边界拆分，再在段落边界拆分。
   • 过滤目录章节（通过链接比例 > 50 % 检测）。
   • 去除 MDX 特有的 React 标签（和）等。
   • 使用内容哈希去重相同章节。
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” 能匹配 “authenticating in middleware”，无需额外的 NLP。BM25 排序把章节标题的权重乘以 10，文档标题乘以 5，超过正文内容的权重，从而在不使用向量嵌入的情况下提供相关结果。

搜索流水线：保持简洁

当一个

MCP 客户端（例如 Claude）调用：

get_docs({ library: "nextjs@16.0", topic: "middleware" })

进程内管道运行：

FTS5 query → BM25 ranking → Relevance filter → Token budget → Merge adjacent → Format

• Relevance filter – 删除任何得分低于最高命中 50 % 的结果。
• Token budget – 将输出限制在 2 000 个 token（足够有用且不会淹没上下文窗口）。
• Merge adjacent – 将同一文档的相邻块合并，使 LLM 接收到连贯的章节而不是碎片。

Total latency: 低于 10 ms，相比云端往返的 100–500 ms 加上 AI 的等待时间。这种速度在助手正进行编码会话时尤为重要。

TL;DR

• Local‑first 文档 → 没有速率限制，也没有月度费用。
• SQLite + FTS5 → 快速、零配置的存储和搜索。
• Claude Code → 通过一周的配对编程完成了整个系统。

试一试吧：Context on GitHub。

AI 编码代理与本地优先文档

AI 编码代理在每个会话中会进行数十次工具调用。如果每次文档查找增加约 300 ms 的网络延迟，那么每次交互就会出现数秒的空闲时间。而在本地，这几乎是免费的。

真正的优势：一次构建，随处共享

当你构建一个文档包时，结果是一个单独的 .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 查询。

使用 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 同时编写实现代码和测试。当两者不匹配时，我们一起找出原因。

数字

设置

# Install
npm install -g @neuledge/context

# Add some docs
context add https://github.com/vercel/next.js
context add https://github.com/vercel/ai

# Connect to your AI agent (Claude Code example)
claude mcp add context -- context serve

它可在 Claude Desktop、Cursor、VS Code Copilot、Windsurf、Zed、Goose 以及任何兼容 MCP 的代理上使用。MCP 服务器公开了一个名为 get_docs 的工具，具备已安装库的动态枚举——AI 能准确看到可用内容，并在相关时进行查询。

接下来

搜索目前基于关键字（FTS5 + BM25）。它对诸如 “middleware authentication” 或 “ai sdk agent loop” 之类的直接查询表现良好，但不理解语义相似性。像 “How do I protect routes?” 这类问题除非词语重叠，否则不会匹配标题为 “Authentication Guards” 的章节。

计划改进：

1. 本地嵌入用于语义搜索 – 仍然完全离线，可能使用 ONNX Runtime 加载小模型。SQLite 架构使这很直接：添加 embeddings 表，在构建时计算向量，搜索时使用余弦相似度查询。
2. GraphRAG‑style relations table – 遍历关联文档。当你询问中间件时，可能也想了解认证、路由和错误处理。关系图可以自动呈现这些内容。
3. Package registry – 基于 GitHub 的索引，社区可以发现并共享预构建的文档包。与其每个人都独立构建相同的 Next.js 文档，不如一次构建后发布。

要点

本项目的核心教训是：并非所有东西都必须是云服务。

AI 代理的文档是本地优先的完美案例。数据更改频率低（随库版本），查询需要快速响应（代理会大量发起查询），隐私很重要（你在查询自己的代码库），而“一次构建，永久使用”的模型非常契合。

如果你对速率限制、延迟或为本应是静态文件的东西每月付费感到沮丧——试试看。

Context MCP 在 github.com/neuledge/context 开源。已在 npm 上发布，包名为 @neuledge/context。