Doc Bridge

doc-bridge

npm： @agentskit/doc-bridge · CLI： ak-docs · 主页： agentskit-io.github.io/doc-bridge

主题： ai-agents · documentation · developer-experience · mcp · llms-txt · typescript

兼容性： node >=22 · TypeScript 5.8+ · pnpm、npm 或 yarn 使用者

以证据为依据，确定性地证明文档存在偏差，并为编码 Agent 提供交接信息。

将文档转化为可执行的交接信息：doc-bridge 会读取仓库文档、所有权映射和面向用户的文档网站，然后为人类和 Agent 提供相同的、附有证据链接的起点：

• 从哪里开始阅读
• 可以编辑哪些文件／软件包
• 哪些检查可以证明变更有效
• 哪些面向用户的文档介绍了该功能

核心功能无需任何大模型或 API 密钥；文档门户将 AgentsKit Chat 作为这一确定性层之上的可选界面进行实际应用。

专为 Agent 规模的仓库打造

Doc Bridge 将大型仓库的结构和文档转换为精简且附有证据链接的上下文，供人类和编码 Agent 查询，而不必反复遍历整个仓库。

历史上下文载荷估算

早期的一轮匿名实际使用周期估算，序列化上下文载荷最多可减少 99%。这是历史载荷估算，并不保证能节省服务提供商的令牌、提升回答质量或确保语义正确性。它与服务提供商的令牌用量不是同一项指标。

历史受控 A/B 测试信号

已发布的受控研究涵盖 96 次匿名执行，报告了以下方向性运行信号：

• 在 46 组令牌数据完整的配对样本中，配对的服务提供商令牌等效单位减少了 18.46%；
• P95 延迟降低 39.75 秒；
• 与仅使用仓库上下文相比，运行完成率从 75.0% 提升至 87.5%。

这些是定义各自独立的历史指标：99% 指估算的上下文载荷减少量，而 18.46% 则基于 46 组配对观测的服务提供商令牌等效数据。受限判定器在两个实验组中记录的判定器成功结果均为零；由于该判定器采用机械方式运行，且不会独立判断语义正确性，因此这一结果仅具方向性，无法得出确切结论。在语义评估和发布审查完成之前，我们暂不公布更新的本地试点结果。请参阅完整的方法说明和匿名数据。另一项独立的 Layer-1 基准测试结果衡量确定性的文档发现，并分别报告原生评分和固定样例评分。

团队为何使用它

Agent 功能强大，但大多数代码仓库文档都是为人类编写的。结果往往很熟悉：Agent 猜测代码归属，修改了相邻的软件包，运行了错误的测试，或忽略了已经说明规则的人类指南。

doc-bridge 可双向工作：

方向	功能	命令
人类文档 → Agent	将 Fumadocs、Docusaurus、markdown 和代码归属文档转换为 AgentHandoff	ak-docs index · ak-docs query --agent
Agent 记忆 → 文档	读取 .agent-memory/** 和 .cursor/rules/*.mdc，判断哪些内容应成为项目文档，并起草供人类审核的晋升提案	ak-docs memory ingest · classify · promote --pr

交接内容是一份路由契约：

{
  "startHere": "docs/for-agents/packages/auth.md",
  "editRoots": ["packages/auth"],
  "checks": ["pnpm --filter @demo/auth test"],
  "humanDoc": "/docs/guides/auth"
}

工作流运行可能携带与 AgentsKit 运行时和 Chat 协议相同的可选 correlation 信封。operationId 是跨代码仓库的标识；runId、sessionId、turnId、actionId 和 traceId 保留其本地含义。这些仅为有界元数据，不得包含提示词、机密或文档内容。

该契约适用于终端、MCP、CI 以及可选的 RAG/Chat。

文档质量与协调

发现只是第一步。ak-docs audit documentation 会将已声明的文档和代码归属与观测到的项目图谱进行比较，并针对覆盖缺失、关系过时、结构性矛盾、完全重复、示例缺失和维护元数据不完整等问题，报告有证据支持的发现。

在配置的 Agent 或人类审核者进行评估之前，自然语言的正确性、不必要的文字和语义冗余都会明确标记为 not-analyzed。拟议的更改仍可审核，并须经人类批准。

Example finding (anonymized)
  CONTRADICTION · high confidence
  Documentation declaration differs from the observed project relation
  Evidence: 4 source files + 1 documentation declaration
  Action: review ownership and update the canonical document

验证文档差异

确定性地比较修订快照：检查符号、CLI、配置和签名更改、历史引用以及仍存在的 head 引用。损坏的引用需要提供移除证据；歧义和不受支持的提取会明确标出。更改过的引用需要审核。默认策略会根据证据状态分别路由发现；使用 --no-policy 可检查原始诊断信息。

在已构建的代码检出目录中运行此比较，会在移除一个被引用的导出项之前和之后，对签名夹具的临时副本分别创建快照。请使用已安装的 ak-docs，或在已构建的代码检出目录中将其替换为 node /path/to/checkout/bin/ak-docs.js。Node 步骤会从发现响应中提取原始快照：

set -e
work=$(mktemp -d)
cp -R tests/fixtures/signature-api "$work/repo"
(cd "$work/repo" && ak-docs discover --json) > "$work/discovery.json"
node -e 'const fs = require("node:fs"); const result = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); fs.writeFileSync(process.argv[2], JSON.stringify(result.snapshot))' "$work/discovery.json" "$work/base.json"
sed '/^export const describeThing/d' "$work/repo/api.ts" > "$work/api.ts"
mv "$work/api.ts" "$work/repo/api.ts"
ak-docs diff --base "$work/base.json" --root "$work/repo"
ak-docs diff --base "$work/base.json" --root "$work/repo" --no-policy
rm -rf "$work"

如需获得真实差异，请分别捕获每个修订版本。有关有界 PR 报告，请参阅差异与发现和Action 建议模式。报告不会批准文档更正。

2.0 工作流

• **Vault：**选择启用 Obsidian 发现后，会读取 wikilink、别名和标签；ak-docs vault export 会生成被忽略的导航笔记，而 vault diff 会将编辑过的生成笔记转换为待处理提案。Vault 指南。
• **理由：**启用 index.knowledgeEntities.enabled，为决策、概念和变更编制索引，然后运行 ak-docs why <path|symbol|concept>。MCP 会公开 knowledge.decision、knowledge.concept 和 knowledge.whyChanged。证据是观察到的理由，而非推断出的因果关系。知识查询规范。
• **修复：**可选的 ak-docs fix --llm 会在无需密钥的指南中使用脚本化的虚假提供方响应；真实提供方需使用显式的智能配置。提案需要经过确定性复查和人工审核。
• 建议：CHANGED_REFERENCE 针对的是关于已变更方面的声明；单纯提及不会触发此项。未知语法仍属于需要审核的不确定情况。操作建议。
• **升级：**请遵循 1.x → 2.0 迁移指南。此软件包不附带 Studio UI；请使用确定性的 StudioGraphV1 导出，通过其他工具可视化图谱。

最新的 Layer-1 基准测试与方法报告称，原生发现的精确率为 100%（15 个 TP、0 个 FP、0 个 FN），历史变更引用发现的精确率为 83.3%（10 个 TP、2 个 FP、0 个 FN），历史负例的假阳性率为 6.25%（2/32）。这些有目的选取的对照组使用不同的分母；它们并不能证明整体语义准确性或已达到发布就绪状态。

60 秒验证

本 README 提供一条命令即可完成验证；入门指南 介绍完整的代码仓库设置和首次索引工作流。

npm i -D @agentskit/doc-bridge
npx ak-docs demo --text

无需配置，也无需先阅读文档。输出会展示前后变化、真实交接过程、门禁从红转绿，以及 MCP 片段：

After (handoff.resolve / query --agent)
  ✓ target:  auth (packages/auth)
  ✓ start:   docs/for-agents/packages/auth.md
  ✓ edit:    packages/auth
  ✓ checks:  pnpm --filter @demo/auth test · pnpm --filter @demo/auth lint
  ✓ human guide: /docs/guides/auth

Gate: red → green

验证真实交接路径

此经过校验的示例通过公开 CLI 运行捆绑的演示。代码仓库中的 scripts/check-readme-standard.mjs 门禁会逐字节比较此代码块与可执行测试夹具； .github/workflows/ci.yml 会在每个拉取请求中运行该门禁及其 可执行测试。

下方的研究数据不会由 README 门禁重新计算；相关协议、 隐私检查和局限性记录在链接的研究资料中。

import { execFileSync } from 'node:child_process'

execFileSync(process.execPath, ['bin/ak-docs.js', 'demo', '--text'], {
  stdio: 'inherit',
})

node examples/verify-handoff.mjs

如需完整的代码仓库设置，请遵循入门指南。

使用 Cline？请遵循确定性的 llms-install.md 设置。该设置会通过 pnpm dlx 运行固定版本的 MCP 服务，不会将 Doc Bridge 添加到代码仓库依赖项中。

发布内容

查看功能概览图，直观了解 CLI、MCP、CI 和适配器功能。

功能	用途	命令 / 产物
CLI	检查归属、搜索文档、运行门禁、询问本地问题	ak-docs query、search、ask、doctor、gate
MCP 服务	让 Cursor、Claude Code、Codex 风格的 Agent 在编辑前解析交接信息	ak-docs mcp、handoff.resolve
GitHub Action / CI	在 PR 上检查索引是否过期，以及配置的文档门禁是否通过	AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7
文档一致性	通过可审计的证据检查稳定的生态标准	ak-docs conformance run documentation-standard-v1 --text
文档审计	衡量文档质量，并将文档与观察到的项目图进行比较	ak-docs audit documentation --json
文档适配器	将面向用户的文档关联到 Agent 文档	fumadocs、docusaurus、vitepress、starlight、nextra、plain-markdown
单体仓库路由	发现工作区和检查项	pnpm-monorepo、nx
记忆流水线	将 Agent 笔记转化为可供审查的文档草稿	memory ingest、classify、promote --pr
可选 RAG / 聊天	基于同一套交接优先索引进行聊天	@agentskit/rag、@agentskit/ink、ak-docs chat

请参阅快速入门、MCP、示例和为什么选择 doc-bridge。

Cursor 插件

此仓库还包含一个 Cursor 插件，它将 Doc Bridge MCP 服务（除明确的提案工具外均为只读）与交接技能配合使用。该插件会在 Cursor 编辑路由仓库前解析 startHere、readBeforeEditing、editRoots 和 checks。此插件不会请求凭据。其 MCP 工具均为只读，唯有 docbridge.proposals 例外；该工具可在 .doc-bridge/ 下保存审查产物，并记录批准或拒绝补充信息的决定；没有任何 MCP 工具会编辑文档或源文件，也不会应用修复措施。

GitHub Copilot 插件

根目录中的 Agent Plugins 清单向 GitHub Copilot CLI 提供相同的可移植交接技能和 MCP 服务。Copilot 会从标准插件布局中发现 skills/ 和 .mcp.json，因此集成内容由源仓库维护，无需将提示词复制到另一个仓库。

copilot plugin install AgentsKit-io/doc-bridge

可移植 Agent 技能

skills/doc-bridge-handoff 按照开放的 Agent Skills 布局封装了相同的故障关闭路由约定，适用于兼容 OpenClaw 的客户端、Hermes Agent、Pi、Cursor，以及其他可执行本地技能脚本的运行时。该技能优先使用只读 MCP 工具，若不可用，则回退到固定版本且无需凭据的 CLI 解析器。它绝不会编辑文件、运行返回的检查项，也不会在 editRoots 之外授予权限。

从 ClawHub 安装已发布的技能：

clawhub install doc-bridge-handoff

Pi 用户也可以通过 npm 包安装同一项由源仓库维护的技能：

pi install npm:@agentskit/doc-bridge

Claude Desktop MCP Bundle

Doc Bridge 可以打包为本地 MCP Bundle，供 Claude Desktop 使用。该 Bundle 会公布 14 个 MCP 工具，在冒烟测试中运行其中 8 个，并将除 docbridge.proposals 之外的所有工具标记为只读。它会要求用户选择仓库的 doc-bridge.config.json；该文件定义了 Doc Bridge 可以读取的项目边界。

从干净的检出开始：

pnpm install --frozen-lockfile
pnpm mcpb:pack

该命令会构建 Doc Bridge，创建仅包含生产环境依赖的暂存目录，验证 MCPB 清单，打包扩展，检查文件清单，并将本地构建产物写入 .mcpb-output/。生成的 Bundle 和暂存目录会有意从 Git 中排除。

当前打包的兼容性声明仅支持 macOS；在其他操作系统上通过独立安装测试之前，本项目不声称支持 Bundle。

存在的原因

模式	不足
Wiki + RAG	能够解释，但不擅长说明在哪里采取行动，也无法证明文档与代码相符
仅使用 AGENTS.md	静态规则很出色，但没有所有权索引、关卡或人工桥接
Context7 类工具	为模型提供库文档，但不负责你自己的单体仓库路由

doc-bridge 提供 AgentHandoff JSON：

{
  "type": "agent-handoff",
  "startHere": "docs/for-agents/packages/auth.md",
  "editRoots": ["packages/auth"],
  "checks": ["pnpm --filter @demo/auth test"],
  "humanDoc": "/docs/guides/auth",
  "bridge": { "humanDoc": "linked" }
}

当缺少人工指南时，交接会将其作为一项功能呈现：

{
  "bridge": {
    "humanDoc": "missing",
    "action": "ak-docs bootstrap agent-docs"
  },
  "notes": ["Human guide missing for billing. Run: ak-docs bootstrap agent-docs"]
}

五个循环（附实际命令）

循环	命令	你会看到什么
行动	ak-docs query package auth --agent	editRoots、checks、startHere
桥接	ak-docs bootstrap agent-docs	根据人工编写的站点生成 Agent 文档；交接中的 bridge.humanDoc
学习	ak-docs memory classify → promote	面向 Agent 语料库的 HITL 草稿
验证	ak-docs diff --base base.json --head head.json	修订差异、评审影响和范围有限的引用问题
说明	ak-docs ask "auth is broken in staging"	所有权匹配 + 交接预览 + 后续命令

ak-docs ask "who owns schemas"
# Best match: ownership os-core
# Handoff preview
#   start:  docs/for-agents/packages/os-core.md
#   edit:   packages/os-core
#   checks: pnpm --filter os-core lint · pnpm --filter os-core test

团队每日检查的覆盖情况

以下是该命令的示例输出，并非对本仓库的测量结果。请在本地或 CI 中运行该命令，以获取当前值。

ak-docs doctor --text
ak-docs doctor --badge          # shields.io markdown for README
ak-docs index --watch           # keep index fresh while editing docs

Score: 82/100 (B)
  Agent docs:      8/10 (80% handoff-ready)
  Human guides:    6/10 (60% bridged)
  Gates:           3/3 passing

Next actions
  → ak-docs bootstrap agent-docs
  → ak-docs query package billing --agent

Agent 可独立使用

1. MCP 自动配置： ak-docs mcp install --cursor
2. 技能/规则： 将 docs/skills/doc-bridge.md 粘贴到 Cursor 规则中 — 编辑 packages/* 之前，Agent 会调用 handoff.resolve
3. 交接就是下一步： JSON/MCP 响应中包含 startHere、checks 和 bridge

CI 是一等公民

在每个 PR 上复用捆绑的 GitHub Action：

请遵循规范版 Gate 和 CI 指南，其中包含完整的工作流，并固定了已发布的 Action 版本。

该 Action 会安装准确配置的包（在本仓库中自用时，则安装工作区包），然后验证已提交的索引和配置的关卡，不会悄悄重新构建它们。它会拒绝非精确的包版本。请参阅 Marketplace 指南。

该指南固定到已发布的稳定 Action 版本 v1.7.45；已签入的包版本为 2.5.1。

覆盖情况因仓库而异。在本地运行 ak-docs doctor --badge 以生成当前的交接和人工桥接徽章，或在 CI 中运行 pnpm coverage:badge；本 README 有意避免发布过时的静态百分比。

对于本仓库，请先生成被忽略的索引，再进行本地检查：

node bin/ak-docs.js index
node bin/ak-docs.js gate run

切勿提交本仓库的 .doc-bridge/index.json。CI 会构建该索引两次并比较构建产物字节，然后检查可复现性和文档一致性。这验证的是确定性生成，而非已提交索引的新鲜度。使用该 Action 的使用方仓库仍会在重新构建前验证其已提交的索引。

产品界面

核心功能 — 始终可用（无需大模型）

界面	用途
演示	ak-docs demo — 内置示例，无需设置
诊断	覆盖率评分、缺少 humanDoc/Agent 文档、后续操作
索引	DocBridgeIndex + contentHash + llms.txt + 功能
命令行	query / search / list / ask / gate / bench / memory / bootstrap
MCP	handoff.resolve、doc.search、doc.get、gate.status、…
门禁	新鲜度、人类链接验证、可选的 OKF 风格
适配器	pnpm-monorepo、nx、fumadocs、docusaurus、vitepress、starlight、nextra、plain-markdown

可选的 AgentsKit 同行组件

npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react
ak-docs rag ingest && ak-docs chat

参见 docs/chat-and-rag.md。

AgentsKit 生态系统

使用者（公开）

专为开放的 AgentsKit 平台设计，并在其上进行自用验证：

平台	链接
for-agents	agentskit.io/docs/for-agents
Registry	registry.agentskit.io
Playbook	playbook.agentskit.io
AgentsKit Chat	文档 · 源代码
Code Review	网站 · 源代码
Harness	文档 · 源代码
本仓库	CI 通过 · 每个 PR 都运行 ak-docs gate run

Playbook 模式： docs/playbook/doc-bridge-pattern.md — 使用 ak-docs playbook pattern --text 导出

配置示例

配置方案	示例
单人 Markdown	examples/minimal-plain-markdown.config.ts
pnpm 单体仓库	examples/pnpm-monorepo.config.ts
Nx 单体仓库	examples/nx-monorepo.config.ts
演示单体仓库	examples/demo-monorepo/
Fumadocs + 聊天	examples/fumadocs-with-chat.config.ts
VitePress	examples/vitepress-only.config.ts
Astro Starlight	examples/starlight-only.config.ts
Nextra	examples/nextra-only.config.ts

契约：docs/spec/config-v1.md · 命令行：docs/spec/cli.md · MCP：docs/mcp.md · 技能：docs/skills/doc-bridge.md · 模式：docs/playbook/doc-bridge-pattern.md · 操作指南：docs/recipes/index-pipeline.md

学习循环 — 记忆 → 草稿 PR

ak-docs memory ingest
ak-docs memory classify
ak-docs memory promote --pr --dry-run   # preview gh commands
ak-docs memory promote --pr              # opens draft PR via gh

状态

已发布的 npm 包：v1.7.45 稳定版。 工作树中的包版本为 1.8.0，尚未发布。下方的 Action 示例特意固定为最新的稳定发布版本；发布新版本时，发布工作流会同时更新包和 Action 版本。

已发布的包通过命令行、MCP 服务、CI Action 和打包技能提供可移植、失败即关闭的交接；支持确定性的 Documentation Standard v1 一致性检查、经过验证的发布溯源，以及文档质量审计工具。

pnpm install && pnpm build && pnpm test
pnpm smoke:ollama    # optional — skips if Ollama/peers unavailable

主页： https://doc-bridge.agentskit.io/

隐私政策

本地 MCP 服务仅读取通过 doc-bridge.config.json 选定的项目。它不需要 API 密钥，不会向 AgentsKit 发送项目数据，也不会收集遥测数据。除 docbridge.proposals 外，其余 MCP 工具均为只读；docbridge.proposals 可以在 .doc-bridge/ 下保存审核产物，并记录批准或拒绝增强内容的决定；没有 MCP 工具会编辑文档或源文件，也不会应用修复措施。有关访问路径、用途、存储、共享、保留期限、可选集成和联系信息，请参阅完整的隐私政策。

贡献

欢迎提交 Issue 和 PR。请从这里开始：

若要完善证据库，可以复现匿名化研究、添加语言或框架分析器、贡献文档质量规则，或为真实矛盾或过时关系添加测试样例。

需求	文档
本地设置、测试、发布流程	CONTRIBUTING.md
治理和维护者职责	GOVERNANCE.md
漏洞报告	SECURITY.md
社区规范	CODE_OF_CONDUCT.md
发布历史	CHANGELOG.md
产品定位	docs/POSITIONING.md

许可证

MIT

升级到 2.0

区域修复、显式重新生成索引以及可配置的记忆路径，请参阅 1.x 到 2.0 迁移指南。