lockdocs

lockdocs

从锁文件获取精确版本的库文档——本地、离线、无速率限制。

读取你的锁文件。根据你安装的精确版本的文档和类型声明回答问题。
npm · PyPI · crates.io · Go。MCP 服务和 CLI 集于一个 Rust 二进制文件。无需账户，无需 API 密钥。MIT。

npx -y @sylphx/lockdocs setup

文档 · 快速入门 · 工具 · 基准测试 · 比较 · 工作原理

_{真实终端：一个问题，两种安装版本。pydantic 1.10.18 回答 BaseModel.dict()（pydantic/main.py:427），pydantic 2.9.2 回答 model_dump()（pydantic/main.py:352）。演示还展示了 Next.js 14 与 15 的 cookies()。}

看看它如何工作

在固定使用 pydantic 2.9.2 的项目中，询问 BaseModel.model_dump 的精确签名（即上方演示中的运行示例）：

$ lockdocs api BaseModel.model_dump --tokens 300
[email protected] · pypi · .venv/lib/python3.12/site-packages · pinned in uv.lock

### pydantic.main.BaseModel.model_dump (method) — [email protected] pydantic/main.py:352
def model_dump(self, *, mode: Literal['json', 'python'] | str = 'python', include: IncEx | None = None, …) -> dict[str, Any]
Usage docs: https://docs.pydantic.dev/2.9/concepts/serialization/#modelmodel_dump

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

在 pydantic 1 项目中进行相同调用时，它会回答 pydantic 1.10.18 没有 model_dump，并展示最接近的文档。

快速入门

npx -y @sylphx/lockdocs setup     # add lockdocs to Claude Code, Codex, Cursor, VS Code, Claude Desktop, Windsurf, Gemini CLI

就这么简单。只使用 Claude Code？claude mcp add lockdocs -- npx -y @sylphx/lockdocs mcp。setup 会检测你使用的客户端，写入它们的 MCP 配置，并打印所有变更。再次运行时，不会有任何变化。然后向你的 Agent 提出类似 “使用 lockdocs：我们用的 zod 要如何拒绝未知键？” 的问题。

在任意项目中打开终端并运行：

npx -y @sylphx/lockdocs zod "reject unknown keys"          # docs for the zod version in your lockfile
npx -y @sylphx/lockdocs api axum::Router::route            # exact signature + doc comment
npx -y @sylphx/lockdocs resolve                            # every pinned version, and whether its docs are here
npx -y @sylphx/lockdocs fetch                              # once: add upstream docs at each version's git tag

Cursor 和 VS Code，一键安装

· 在 VS Code 中安装

需要 Node 18+。在编辑器中确认安装，打开项目并启用服务。两个链接都会在本地运行 npx -y @sylphx/lockdocs mcp；无需 API 密钥。

在终端中为 VS Code 安装：

code --add-mcp '{"name":"lockdocs","command":"npx","args":["-y","@sylphx/lockdocs","mcp"]}'

或者将服务添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "lockdocs": {
      "command": "npx",
      "args": [
        "-y",
        "@sylphx/lockdocs",
        "mcp"
      ]
    }
  }
}

对于 .vscode/mcp.json，请使用 VS Code 的 servers 格式：

{
  "servers": {
    "lockdocs": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@sylphx/lockdocs",
        "mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "lockdocs": { "command": "npx", "args": ["-y", "@sylphx/lockdocs", "mcp"] }
  }
}

[mcp_servers.lockdocs]
command = "npx"
args = ["-y", "@sylphx/lockdocs", "mcp"]

为什么选择 lockdocs

你的 Agent 会根据它记忆中的库版本编写代码，而不是你安装的版本。因此，它会对 pydantic 2 模型调用 .dict()，在 Next.js 15 中不加 await 就调用 cookies()，还会在 axum 0.8 中使用 /:id 路由。托管文档服务虽有帮助，但会根据提示词猜测版本、限制免费用量，而且无法访问你的私有软件包。

lockdocs 让版本问题不再成为问题：

• 精确匹配版本，零配置。 它会读取 package-lock.json、pnpm-lock.yaml、yarn.lock、bun.lock、Cargo.lock、uv.lock、poetry.lock、Pipfile.lock、requirements*.txt 和 go.mod。无需库 ID，也不用在提示词中注明“使用 v14”。
• 随代码提供的文档。 README、变更日志和 docs/ 文件夹，以及软件包本身的 API 参考：带有 JSDoc 的 .d.ts 声明、Python 文档字符串和存根、rustdoc 注释、Go 文档注释。只要已安装，就有对应文档，包括你的私有和内部软件包。
• 缓存后离线使用且不限量。 软件包文件从 node_modules、虚拟环境、~/.cargo/registry 和 Go 模块缓存中读取。可选模型只需下载一次（129 MB，磁盘占用为 32 MB）。使用 --offline（或 LOCKDOCS_OFFLINE=1）可禁止所有下载；LOCKDOCS_EMBED=0 仅禁用模型。无需账户，也没有托管查询额度。首次使用时向上游发出的请求会透露正在获取的公开仓库和版本，而不会透露你的问题或项目文件。
• 首次使用时获取上游文档。 Next.js、Django 和 FastAPI 等软件包不附带文档。查询会自动添加公开 GitHub 文档，版本固定为根据你所锁定的发布标签解析出的不可变提交，并以匿名方式获取，且下载量有限。使用 --no-fetch 或 LOCKDOCS_FETCH=0 可选择退出；缓存的文档仍可离线使用。失败情况会与本地答案一并报告，不会以最新版本的文档替代。
• 理解含义，而不只是匹配字词。 混合检索：将 BM25 与小型本地嵌入模型融合（仅下载一次，磁盘占用 32 MB），并支持从弃用说明重定向到 API（例如“改用 model_validate”）。
• 答案简短，并附引用。 内容会压缩在令牌预算内（默认 1,200），每个部分均标注引用，格式为 package@version path:line。

Agent 可获取的内容

三个工具，调用成本低到足以在使用每个不熟悉的 API 前先调用：

生态系统

包中捆绑的旧版副本（例如 zod 4 中的 zod/v3、pydantic 2 中的 pydantic/v1）优先级低于当前 API。

首次使用时获取上游文档

首次查询 docs 或 api 时，会为所选依赖项添加一次公开发布标签对应的文档：它会从包自身的元数据中查找 GitHub 仓库和固定版本对应的 git 标签，将该标签解析为不可变的提交，并且只下载其中的文档目录（Markdown、MDX、reStructuredText、文档示例）。默认情况下，它不会使用环境中的 GitHub 凭据，也不会下载主要版本的网站文档。先前选择加入的文档站点缓存会予以保留，其来源仍清晰可见。lockdocs fetch 仍可用于预先缓存文档，并显式添加主要版本的文档站点。之后，回答会引用 [email protected] upstream:docs/01-app/.../cookies.mdx:12。参见上游文档与获取方式。

未安装？选择加入以获取精确版本

默认情况下，注册表包下载需选择加入；上游内容补充使用已安装的包元数据（另加一次性嵌入模型下载）。如果固定版本的包未安装（例如全新克隆、CI 环境，或正在审查的锁文件），它会说明这一点并告知安装方式。传入 --fetch（或设置 LOCKDOCS_FETCH=1，或运行 lockdocs setup --fetch），即可让它从注册表下载精确版本（npm tarball、PyPI wheel 或 sdist、crates.io .crate、Go module proxy zip）并存入缓存。通过获取的内容生成的回答会注明 fetched from registry.npmjs.org。你也可以查询未使用的版本：lockdocs npm:[email protected] "strict object" --fetch。

基准测试

105 个问题的正确答案取决于版本，涉及 15 个以上的库（zod、Next.js、React Router、pydantic、axum、tokio、Tailwind CSS、ESLint、Prisma、React、Vite、Express、SQLAlchemy、Django、FastAPI），每个问题都在安装了相应版本的真实项目中提问。答案包含符合该版本的 API，且不包含其他版本的 API，即为通过。使用相同的问题和评分器，在 GitHub 托管的运行器上测试 Context7 的匿名 API（运行测试）：

• 在版本最重要的场景中，lockdocs 表现领先 2 倍（较旧主版本为 38/45，对比 19/45）。Context7 经常会给出最新 API 的答案（pydantic 1 的问题得到 pydantic 2 的答案）。
• 在较新主版本（各为 53/55）和 tokio（各为 5/5）上持平；在留出问题上领先（16/18，对比 15/18）。这些问题在其测量的排序变更之前编写，未用于调优。
• 速度更快、token 更少、没有配额限制。 执行 lockdocs fetch 后，每个问题的延迟中位数为 58 ms（首次使用时为 185 ms），每次都会启动全新的 CLI 进程。Context7 托管 API 在较早测试中的延迟中位数为 2,583 ms，其复用答案便来自这些测试。

方法、问题、逐题结果和脚本见：基准测试页面和bench/。

同样的 105 个问题也会通过 Sylphx Search 提问——这是我们平台的网页搜索，其技术文档垂直领域是托管索引，用于收录从不随软件包发布的文档——使用 bench/cloud.py。本地和云端使用同一语料和同一评分器，因此 lockdocs 和 Sylphx Search 使用同一种索引格式和排序，而不是两个产品。

对比

Context7 收录了许多网站和指南，它们从不随软件包发布，因此对于答案只存在于文档网站上的问题，它可能表现更好。lockdocs 则适用于另一种情况：版本很重要、你处于离线状态或受到速率限制，或者软件包属于你。两者搭配使用效果很好。

工作原理

1. 解析。 将项目中的每个锁文件（以及其上级的 monorepo 根目录中的锁文件）解析为精确的 (ecosystem, name, version) 三元组，并标记直接依赖项。
2. 定位。 查找每个包在磁盘上的文件，并对照锁文件检查已安装的版本。版本不一致会报告出来，绝不隐瞒。
3. 提取。 按标题划分 README、变更日志和文档文件夹；使用 tree-sitter 解析 .d.ts、Python、Rust 和 Go 源码，提取包含签名、文档注释和限定路径的符号（z.object、tokio::task::spawn、pydantic.main.BaseModel.model_dump）。
4. 索引和缓存。 使用 BM25（感知标识符的分词器、轻量词干提取，以及小型编程同义词表），并为每个条目使用静态 model2vec 模型生成一个嵌入，按包、版本和来源缓存在磁盘上，因此每个版本只会被索引一次。
5. 回答。 融合关键词和嵌入分数，应用文档信号和弃用重定向，然后在令牌预算内整理结果并附上引用。

在 GitHub 托管的运行器上的典型耗时：为 Next.js 15 的所有声明编制索引（7,700 个符号）约需 0.4 秒，zod 4 约需 0.05 秒，每个版本只需执行一次；此后每次查询耗时 5–20 毫秒。

CLI

lockdocs <package> [question]   Docs for the version this project pins (no question: overview)
lockdocs resolve [filter]       Pinned versions and where their docs are
lockdocs docs <question>        Search all direct dependencies (--pkg to focus)
lockdocs api <symbol>           Exact signature + doc comment
lockdocs fetch [package...]     Once: upstream docs at each version's tag, missing packages, the model
lockdocs index [package]        Build indexes ahead of time
lockdocs cache [clean]          Show or delete the cache
lockdocs upgrade <pkg> <ver>    Pro: API changes from the pinned version to <ver>, with your call sites
lockdocs licence status|activate <token>   Show or activate a Pro licence (free to run)
lockdocs setup                  Configure MCP clients (--client a,b --dry-run --remove --fetch)
lockdocs mcp                    MCP server on stdio

Options: -C/--root <dir>, --pkg <package>, --tokens <n>, --fetch, --no-fetch, --offline, --json

macOS（arm64、x64）、Linux glibc（x64、arm64）和 Windows x64 的预编译二进制文件通过 npm 发布；每个 GitHub 版本中也提供这些文件。从源码安装：cargo install --git https://github.com/SylphxAI/lockdocs lockdocs。

Pro

以上所有功能均免费提供，采用 MIT 许可。Pro 为团队增加两项功能。私有来源：lockdocs 可通过你现有的 GitHub Enterprise、GitLab 和 Bitbucket 主机，以及私有 npm、PyPI、Cargo 和 Go 注册表，读取内部包和文档；使用 .npmrc、uv、pip、Cargo、Go 和 git 已持有的凭据，且凭据只会发送到各自对应的主机。以上功能可在同一组 resolve、docs 和 api 工具以及 lockdocs fetch 中使用。另一项是升级报告（lockdocs upgrade next 15.0.0，或在 docs 工具中使用 upgrade_to）：列出你调用的哪些 API 在固定版本与目标版本之间被移除、重命名或弃用，并附上你的调用位置。请参阅当前 lockdocs Pro 席位价格。许可会在离线状态下验证：运行 lockdocs licence activate <token>（可通过 lockdocs licence status 检查，该命令会在最后 30 天内发出警告），或在 CI 中设置 LOCKDOCS_LICENCE_TOKEN。详情请见：lockdocs Pro。

隐私

lockdocs 会读取你机器上的文件，并通过 stdio 回答。网络使用情况：从 huggingface.co 下载一次嵌入模型（固定修订版本并校验 SHA-256；使用 LOCKDOCS_EMBED=0 或 --offline 可跳过）；首次查询时，为获取已解析发布版本对应提交中的公开文档，会发送匿名 GitHub 请求（查询 git 标签并下载一个 codeload.github.com tarball，不使用受速率限制的 REST API；若仓库归档过大或下载失败，则改为通过 REST API 逐个读取文件）。--fetch / lockdocs fetch 也会访问公开注册表和主要版本的文档站点仓库；只有这些显式 fetch 操作可以使用 GITHUB_TOKEN / GH_TOKEN，且仅限访问 api.github.com（绝不用于 git、codeload 或 raw 下载；不支持私有仓库）。向上游发出的请求会透露仓库、版本和文件路径，不会透露你的问题、锁文件或项目文件。--no-fetch / LOCKDOCS_FETCH=0 会禁用查询时的包和文档下载；--offline / LOCKDOCS_OFFLINE=1 会禁止所有下载。缓存位于操作系统的缓存目录中（可通过 LOCKDOCS_CACHE 覆盖）。

开源 README 视觉元素

上方的 AI 友好度徽章由本地生成，依据的是 repomap 的 Agent 就绪度评分。 在你的代码库中运行 npx -y @sylphx/repomap score，即可获取检查结果、建议的修复方案和徽章代码片段。该评分是一种启发式评估，并非安全审计或认证。评分过程不会上传你的源代码；只有当你打算公开评分时，才发布私有代码库的评分。

GitHub 数据卡片由开源的 Mark 服务提供。以下是此公开代码库的卡片：

[![lockdocs GitHub repository card](https://mark.sylphx.com/api/pin.svg?username=SylphxAI&repo=lockdocs)](https://github.com/SylphxAI/lockdocs)

将 username 和 repo 替换为你的公开代码库。无需用户令牌。请参阅 Mark 的卡片选项和自托管说明。

Sylphx 的其他项目

• anymd：将任意文件（PDF、Word、PowerPoint、Excel、EPUB、HTML、图像）转换为适用于 AI Agent 的简洁 Markdown。
• repomap：为 AI Agent 提供代码库地图：代码图谱、搜索、调用路径和变更影响。
• skills：经过实战检验的 Claude Code 和 Codex Agent 技能，一条命令即可安装。
• readme-mark：通过一个 URL 创建精美的 README 图片：横幅、徽章、图标和数据卡片。

了解 Sylphx 的更多项目：https://sylphx.com/open-source

• Sylphx apps：Sylphx 提供的应用和工具。

Star 历史

支持

有问题、发现错误，或需要团队部署？请发送邮件至 [email protected]，或提交问题。

MIT 许可。© Sylphx Limited，注册于英格兰和威尔士，公司编号 16438428。注册办公地址：128 City Road, London EC1V 2NX, United Kingdom。电子邮箱：[email protected]。隐私 · 条款 · sylphx.com