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 の利用者

ドキュメントのずれを決定論的に検出し、コーディングエージェントへ根拠付きの引き継ぎ情報を提供します。

ドキュメントを実行可能な引き継ぎ情報に変換します。doc-bridge は、リポジトリのドキュメント、オーナーシップマップ、人間向けドキュメントサイトを読み込み、人間とエージェントに同じ根拠付きの出発点を提供します。

• 読み始める場所
• 編集可能なファイル／パッケージ
• 変更を検証するチェック
• 機能を説明する人間向けドキュメント

コア機能は LLM や API キーなしで動作します。ドキュメントポータルでは、この決定論的な基盤の上に任意のインターフェースとして AgentsKit Chat を活用しています。

エージェント規模のリポジトリ向けに構築

Doc Bridge は、大規模なリポジトリの構造とドキュメントを、根拠付きのコンパクトなコンテキストに変換します。人間やコーディングエージェントは、リポジトリ全体を繰り返し調べる代わりに、このコンテキストを照会できます。

過去のコンテキストペイロード推定値

以前に行われた匿名化済みのドッグフーディングでは、シリアライズされたコンテキストペイロードを最大 99% 削減できると推定されました。これは過去のペイロード推定値であり、プロバイダートークンの節約、回答品質、意味的な正確性を保証するものではありません。プロバイダートークンの使用量とは別の指標です。

過去の対照 A/B テストの傾向

匿名化された96件の実行を対象に公開された対照研究では、運用上の傾向として次の結果が報告されています。

• 46組のトークン完全ペア全体で、プロバイダートークン相当単位が 18.46%減少しました。
• P95 レイテンシが 39.75秒短縮しました。
• リポジトリのみのコンテキストを使用した場合の75.0%に対し、運用上完了した実行は 87.5% でした。

これらは過去の、それぞれ異なる方法で定義された指標です。99%という数値は推定コンテキストペイロード削減率であり、18.46%という数値は46組の観測データに基づくプロバイダートークン相当データを使用しています。範囲を限定した判定器では、両方の群で判定器が成功した結果はゼロでした。この判定器は機械的なもので、意味的な正確性を独立して評価するものではないため、この結果は傾向を示すにとどまり、結論は出ていません。より新しいローカルパイロットは、意味的評価と公開レビューが未完了のため、ここでは意図的に取り上げていません。方法論と匿名化データの全文をご覧ください。別途公開されているLayer-1 ベンチマーク結果では、ネイティブスコアとフィクスチャスコアを分けて報告し、決定論的なドキュメント検出結果を測定しています。

チームが利用する理由

エージェントは強力ですが、ほとんどのリポジトリのドキュメントは人間向けに書かれています。その結果はおなじみです。エージェントが担当範囲を推測したり、隣のパッケージを編集したり、誤ったテストを実行したり、すでにルールを説明している人間向けガイドを無視したりします。

doc-bridge は双方向に機能します。

方向	機能	コマンド
人間向けドキュメント → エージェント	Fumadocs、Docusaurus、Markdown、担当範囲のドキュメントを AgentHandoff に変換します	ak-docs index · ak-docs query --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／チャットから利用できます。

ドキュメントの品質と整合性の確認

検出は最初のステップにすぎません。ak-docs audit documentation は、宣言されたドキュメントと担当範囲を観測されたプロジェクトグラフと照合し、カバレッジの不足、古くなった関係、構造化された矛盾、完全な重複、例の欠如、メンテナンスメタデータの不備について、根拠に基づく検出結果を報告します。

自然言語としての正確性、不要な文章、意味的な冗長性は、設定されたエージェントまたは人間のレビューで評価されるまで、明示的に 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、設定、シグネチャの変更、過去の参照、残っている現在の引用を確認します。参照の破損には削除の証拠が必要です。不明瞭な点や抽出を裏付ける情報の不足は、明示されたままにします。変更された参照にはレビューが必要です。デフォルトのポリシーでは、検出結果を根拠のステータスとは別に振り分けます。生の診断結果を確認するには --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 レポートについては、差分と検出結果およびアクションのアドバイザリーモードを参照してください。レポートがドキュメント修正を承認することはありません。

2.0 ワークフロー

• Vault： オプトインの Obsidian 検出機能は、ウィキリンク、エイリアス、タグを読み取ります。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 件、偽陽性 0 件、偽陰性 0 件）、履歴上の変更参照の検出結果の適合率 83.3%（真陽性 10 件、偽陽性 2 件、偽陰性 0 件）、履歴上の陰性ケースにおける偽陽性率 6.25%（2/32）が報告されています。これらの目的に沿って選定された対照群は、異なる分母を測定するものであり、一般的な意味精度やリリース準備状況を示すものではありません。

60 秒で確認

この README では、1 コマンドでの確認方法を説明しています。はじめに では、リポジトリのセットアップ全体と、最初のインデックス作成ワークフローを説明しています。

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 のセットアップに従ってください。リポジトリの依存関係に Doc Bridge を追加することなく、固定バージョンの MCP サーバーを pnpm dlx 経由で実行できます。

提供内容

CLI、MCP、CI、アダプターの各サーフェスの概要については、サーフェスマップをご覧ください。

サーフェス	用途	コマンド／成果物
CLI	所有範囲の確認、ドキュメントの検索、ゲートの実行、ローカルな質問	ak-docs query、search、ask、doctor、gate
MCP サーバー	Cursor、Claude Code、Codex 形式のエージェントが編集前に引き継ぎ情報を解決できるようにします	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
ドキュメントアダプター	人間向けドキュメントをエージェント向けドキュメントにリンクします	fumadocs、docusaurus、vitepress、starlight、nextra、plain-markdown
モノレポのルーティング	ワークスペースとチェックを検出します	pnpm-monorepo、nx
メモリパイプライン	エージェントのメモをレビュー可能なドキュメントの下書きに変換します	memory ingest、classify、promote --pr
オプションの RAG／チャット	同じ引き継ぎ優先インデックスに基づいてチャットを行います	@agentskit/rag、@agentskit/ink、ak-docs chat

はじめに、MCP、例、doc-bridge を選ぶ理由をご覧ください。

Cursor プラグイン

このリポジトリには、Doc Bridge MCP サーバー（明示的な提案ツールを除き読み取り専用）と引き継ぎスキルを組み合わせた Cursor プラグインも含まれています。Cursor がルーティングされたリポジトリを編集する前に、startHere、readBeforeEditing、editRoots、checks を解決します。このプラグインは認証情報を要求しません。MCP ツールは、.doc-bridge/ 配下にレビュー成果物を保存し、エンリッチメントの承認／却下の判断を記録できる docbridge.proposals を除き、読み取り専用です。どの MCP ツールもドキュメントやソースファイルを編集したり、修正を適用したりすることはありません。

GitHub Copilot プラグイン

ルートの Agent Plugins マニフェストにより、同じポータブルな引き継ぎスキルと MCP サーバーを GitHub Copilot CLI でも利用できます。Copilot は標準プラグインレイアウトから skills/ と .mcp.json を検出するため、プロンプトを別のリポジトリにコピーせず、統合をソース側で管理できます。

copilot plugin install AgentsKit-io/doc-bridge

ポータブルエージェントスキル

skills/doc-bridge-handoff は、OpenClaw 互換クライアント、Hermes Agent、Pi、Cursor、およびローカルスキルスクリプトを実行できるその他のランタイム向けに、同じフェイルクローズのルーティング契約をオープンな Agent Skills レイアウトで提供します。このスキルは読み取り専用 MCP ツールを優先し、利用できない場合は、固定バージョンで認証情報を必要としない CLI リゾルバーにフォールバックします。ファイルの編集、返されたチェックの実行、editRoots の範囲外への権限付与は行いません。

公開済みのスキルは ClawHub からインストールできます。

clawhub install doc-bridge-handoff

Pi ユーザーは、npm パッケージを通じて同じソース管理のスキルをインストールできます。

pi install npm:@agentskit/doc-bridge

Claude Desktop MCP バンドル

Doc Bridge は、Claude Desktop 用のローカル MCP バンドルとしてパッケージ化できます。このバンドルは 14 個の MCP ツールを公開し、スモークテストでそのうち 8 個を実行します。また、docbridge.proposals 以外のすべてのツールを読み取り専用として指定します。ユーザーにはリポジトリの doc-bridge.config.json を選択するよう求めます。このファイルによって、Doc Bridge が読み取り可能なプロジェクトの範囲が定義されます。

クリーンなチェックアウトから実行します。

pnpm install --frozen-lockfile
pnpm mcpb:pack

このコマンドは Doc Bridge をビルドし、本番環境用のファイルだけを含むステージングディレクトリを作成して、MCPB マニフェストを検証し、拡張機能をパッケージ化して、そのファイル一覧を確認し、ローカル成果物を .mcpb-output/ に出力します。生成されたバンドルとステージングディレクトリは、意図的に Git の対象外としています。

現在のパッケージ互換性宣言は macOS のみを対象としています。このプロジェクトでは、他のオペレーティングシステム上で成果物そのものの独立したインストールテストに合格するまでは、それらの環境でのバンドル対応を保証していません。

これが存在する理由

パターン	不足している点
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"]
}

5 つのループ（実際のコマンドを使用）

ループ	コマンド	確認できる内容
実行	ak-docs query package auth --agent	editRoots、checks、startHere
橋渡し	ak-docs bootstrap agent-docs	人間向けサイトからエージェント用ドキュメントを下書きします。引き継ぎ情報内の bridge.humanDoc
学習	ak-docs memory classify → promote	エージェント用コーパスの 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

エージェントだけで利用する

1. MCP の自動設定： ak-docs mcp install --cursor
2. スキル／ルール： docs/skills/doc-bridge.md を Cursor のルールに貼り付けます。エージェントは packages/* を編集する前に handoff.resolve を呼び出します
3. 引き継ぎ情報が次のステップです： startHere、checks、bridge が JSON／MCP 応答に含まれます

CI を第一級の機能として扱う

すべての PR で、バンドルされている GitHub Action を再利用します。

完全なワークフローと公開済み Action リリースの固定を含む、正式な Gate と CI のガイドに従ってください。

この Action は、設定されたパッケージそのもの（または、このリポジトリ自体を対象にする場合はワークスペースのパッケージ）をインストールし、コミット済みのインデックスと設定済みのゲートを、暗黙に再ビルドすることなく検証します。完全一致ではないパッケージバージョンは拒否します。Marketplace ガイドを参照してください。

このガイドでは、公開済みの安定版 Action リリース v1.7.45 を固定しています。チェックイン済みのパッケージバージョンは 2.5.1 です。

カバレッジはリポジトリごとに異なります。ローカルで ak-docs doctor --badge を実行すると、現在の引き継ぎバッジと人間向け橋渡しバッジを出力できます。CI では pnpm coverage:badge を実行してください。この README では、古くなった静的なパーセンテージを公開しない方針です。

このリポジトリでは、ローカルチェックの前に、Git の対象外となるインデックスを生成します。

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

このリポジトリの .doc-bridge/index.json は、絶対にコミットしないでください。CI はこれを 2 回ビルドして成果物のバイト列を比較し、その後、再現性とドキュメント適合性を検査します。これにより決定論的な生成を検証しますが、コミット済みインデックスが最新であることは検証しません。この Action を使用するコンシューマーリポジトリでは、再ビルドの前にコミット済みインデックスを検証します。

製品の機能

コア — 常時利用可能（LLM 不要）

インターフェース	目的
デモ	ak-docs demo — セットアップ不要の同梱フィクスチャ
ドクター	カバレッジスコア、不足しているhumanDoc／エージェント向けドキュメント、次のアクション
インデックス	DocBridgeIndex ＋ contentHash ＋ llms.txt ＋機能
CLI	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.agentskit.io
プレイブック	playbook.agentskit.io
AgentsKit Chat	ドキュメント · ソース
コードレビュー	サイト · ソース
Harness	ドキュメント · ソース
このリポジトリ	CI 成功 · すべてのPRでak-docs gate runを実行

プレイブックのパターン：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 · CLI：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のバージョンを同時に更新します。

公開済みパッケージでは、CLI、 MCPサーバー、CIアクション、パッケージ化されたスキルを通じたポータブルなフェイルクローズ型ハンドオフ、 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 に送信したり、テレメトリーを収集したりすることはありません。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 への移行ガイドをご覧ください。