AgentsKit Doc Bridge

Fornece a agentes de codificação transferências determinísticas e somente leitura de documentação, com limites de edição, propriedade e verificações obrigatórias antes de alterações no repositório.

GitHub

Experimente este MCPPatrocinado

Documentação

doc-bridge

npm: @agentskit/doc-bridge · CLI: ak-docs · Landing: agentskit-io.github.io/doc-bridge

Tópicos: ai-agents · documentation · developer-experience · mcp · llms-txt · typescript

Compatibilidade: node >=22 · TypeScript 5.8+ · consumidores via pnpm, npm ou yarn

Transforme sua documentação em entregas executáveis para agentes de codificação.

O doc-bridge lê a documentação do seu repositório, o mapa de propriedade e o site de documentação humana, e então oferece a humanos e agentes o mesmo ponto de partida baseado em evidências:

por onde começar a ler
quais arquivos/pacotes ele pode editar
quais verificações comprovam a alteração
quais documentos humanos explicam o recurso

Não é uma wiki nem um RAG hospedado. O núcleo funciona sem qualquer LLM ou chave de API; o portal de documentação utiliza o AgentsKit Chat como uma superfície opcional sobre essa camada determinística.

doc-bridge maps human docs into structured agent handoffs

Construído para repositórios em escala de agentes

O Doc Bridge transforma a estrutura e a documentação de grandes repositórios em contexto compacto e vinculado a evidências, que humanos e agentes de codificação podem consultar em vez de percorrer repetidamente o repositório inteiro.

Estimativa histórica de carga de contexto

Um ciclo anterior anonimizado de dogfooding estimou uma redução de até 99% na carga de contexto serializado. Esta é uma estimativa histórica de carga — não uma garantia de economia de tokens do provedor, qualidade de resposta ou correção semântica. Não é a mesma medida que o uso de tokens do provedor.

Estimated context payload reduction

Sinal histórico de A/B controlado

O estudo controlado publicado, com 96 execuções anonimizadas, relatou um sinal operacional direcional de:

18,46% menos unidades equivalentes a tokens do provedor emparelhadas em 46 pares completos de tokens;
39,75 segundos a menos na latência P95;
87,5% de execuções concluídas operacionalmente vs. 75,0% com contexto apenas do repositório.

Estas são medidas históricas, definidas separadamente: o valor de 99% é uma redução estimada da carga de contexto, enquanto o valor de 18,46% usa dados equivalentes a tokens do provedor de 46 observações emparelhadas. O avaliador limitado registrou zero resultados de sucesso do avaliador em ambos os braços; como esse avaliador é mecânico e não julga independentemente a correção semântica, este resultado é direcional e inconclusivo. Um piloto local mais recente não é promovido aqui intencionalmente enquanto sua avaliação semântica e revisão de publicação permanecem incompletas. Consulte a metodologia completa e dados anonimizados.

Por que as equipes usam

Agentes são poderosos, mas a maioria das documentações de repositório é escrita para humanos. O resultado é familiar: o agente adivinha a propriedade, edita o pacote vizinho, executa o teste errado ou ignora o guia humano que já explicou a regra.

O doc-bridge funciona nas duas direções:

doc-bridge connects human docs to coding agents and agent memory back to draft docs

Direção	O que faz	Comando
Documentação humana → agentes	Transforma Fumadocs, Docusaurus, markdown e documentos de propriedade em `AgentHandoff`	`ak-docs index` · `ak-docs query --agent`
Memória do agente → documentação	Lê `.agent-memory/*` e `.cursor/rules/.mdc`, classifica o que deve virar documentação do projeto e elabora uma promoção revisada por humanos	`ak-docs memory ingest` · `classify` · `promote --pr`

A entrega é um contrato de roteamento:

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

As execuções do fluxo de trabalho podem carregar o mesmo envelope opcional correlation usado pelo runtime do AgentsKit e pelo protocolo Chat. operationId é a identidade entre repositórios; runId, sessionId, turnId, actionId e traceId mantêm significado local. São apenas metadados limitados e não devem conter prompts, segredos ou conteúdo de documentos.

Esse contrato funciona a partir do terminal, MCP, CI e RAG/chat opcional.

Qualidade da documentação e reconciliação

A descoberta é apenas o primeiro passo. ak-docs audit documentation compara a documentação e a propriedade declaradas com o grafo do projeto observado e relata descobertas baseadas em evidências para cobertura ausente, relações desatualizadas, contradições estruturadas, duplicatas exatas, exemplos ausentes e metadados de manutenção incompletos.

Correção em linguagem natural, prosa desnecessária e redundância semântica permanecem explicitamente not-analyzed até que um agente configurado ou revisão humana os avalie. As alterações propostas permanecem revisáveis e aprovadas por humanos.

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

Prova em 60 segundos

Este README contém a prova de comando único; o guia de introdução contém a configuração completa do repositório e o fluxo de primeira indexação.

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

Sem configuração, sem documentação para ler antes. A saída mostra antes/depois, uma entrega real, gate vermelho→verde e o trecho do 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

Verifique o caminho real de entrega

Este exemplo verificado executa a demonstração incluída por meio da CLI pública. O gate scripts/check-readme-standard.mjs do repositório compara este bloco byte a byte com o fixture executável; .github/workflows/ci.yml executa esse gate e seus testes executáveis em cada pull request.

Os valores do estudo abaixo não são recalculados pelo gate do README; seu protocolo, verificações de privacidade e limitações estão documentados nos artefatos do estudo vinculados.

import { execFileSync } from 'node:child_process'

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

node examples/verify-handoff.mjs

Para a configuração completa do repositório, siga o guia de introdução.

Usando Cline? Siga a configuração determinística llms-install.md. Ela executa o servidor MCP fixado por meio de pnpm dlx sem adicionar o Doc Bridge às dependências do seu repositório.

O que acompanha o pacote

Consulte o mapa de superfícies para uma visão geral visual das superfícies CLI, MCP, CI e adaptadores.

Superfície	Use para	Comando / artefato
CLI	Inspecionar propriedade, pesquisar documentação, executar gates, fazer perguntas locais	`ak-docs query`, `search`, `ask`, `doctor`, `gate`
Servidor MCP	Permitir que agentes Cursor, Claude Code e estilo Codex resolvam entregas antes de editar	`ak-docs mcp`, `handoff.resolve`
GitHub Action / CI	Falhar índices desatualizados e gates de documentação configurados em PRs	`AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7`
Conformidade de documentação	Verificar o padrão estável do ecossistema com evidências auditáveis	`ak-docs conformance run documentation-standard-v1 --text`
Auditoria de documentação	Medir a qualidade da documentação e comparar a documentação com o grafo do projeto observado	`ak-docs audit documentation --json`
Adaptadores de documentação	Vincular documentação humana à documentação de agentes	`fumadocs`, `docusaurus`, `vitepress`, `starlight`, `nextra`, `plain-markdown`
Roteamento de monorepo	Descobrir workspaces e verificações	`pnpm-monorepo`, `nx`
Pipeline de memória	Transformar notas de agentes em rascunhos de documentação revisáveis	`memory ingest`, `classify`, `promote --pr`
RAG/chat opcional	Fundamentar o chat no mesmo índice orientado a entregas	`@agentskit/rag`, `@agentskit/ink`, `ak-docs chat`

Consulte docs/getting-started.md, docs/mcp.md e docs/examples.md.

Plugin Cursor

Este repositório também contém um plugin Cursor que combina o servidor MCP do Doc Bridge (somente leitura, exceto pela ferramenta explícita de proposta) com uma habilidade de entrega. Ele resolve startHere, readBeforeEditing, editRoots e checks antes que o Cursor edite um repositório roteado. O plugin não solicita credenciais nem grava arquivos do projeto por meio do MCP.

Plugin GitHub Copilot

O manifesto raiz de Plugins de Agente expõe a mesma habilidade portátil de entrega e o servidor MCP para o GitHub Copilot CLI. O Copilot descobre skills/ e .mcp.json a partir do layout padrão do plugin, então a integração permanece de propriedade da fonte, em vez de copiar prompts para outro repositório.

copilot plugin install AgentsKit-io/doc-bridge

Habilidade de Agente Portátil

skills/doc-bridge-handoff empacota o mesmo contrato de roteamento com falha fechada no layout aberto de Habilidades de Agente para clientes compatíveis com OpenClaw, Hermes Agent, Pi, Cursor e outros runtimes que podem executar um script de habilidade local. A habilidade prefere a ferramenta MCP somente leitura e recorre a um resolvedor CLI fixado e sem credenciais. Ela nunca edita arquivos, executa verificações retornadas ou concede autoridade fora de editRoots.

Instale a habilidade publicada a partir do ClawHub:

clawhub install doc-bridge-handoff

Usuários de Pi podem instalar a mesma habilidade de propriedade da fonte por meio do pacote npm:

pi install npm:@agentskit/doc-bridge

Pacote MCP para Claude Desktop

O Doc Bridge pode ser empacotado como um Pacote MCP local para o Claude Desktop. O pacote anuncia 14 ferramentas MCP, exercita 8 delas em seu teste de fumaça e marca todas as ferramentas, exceto docbridge.proposals, como somente leitura. Ele pede ao usuário para selecionar o doc-bridge.config.json do repositório; esse arquivo define o limite do projeto que o Doc Bridge pode ler.

A partir de um checkout limpo:

pnpm install --frozen-lockfile
pnpm mcpb:pack

O comando compila o Doc Bridge, cria um diretório de staging somente para produção, valida o manifesto MCPB, empacota a extensão, verifica seu inventário de arquivos e grava o artefato local em .mcpb-output/. Pacotes gerados e diretórios de staging são intencionalmente excluídos do Git.

A declaração de compatibilidade empacotada atual é somente para macOS; este projeto não reivindica suporte de pacote para outros sistemas operacionais até que o artefato exato passe em um teste de instalação independente nesses sistemas.

Por que isso existe

Padrão	Lacuna
Wiki + RAG	Explica; fraco em onde agir e em provar que a documentação corresponde ao código
Somente AGENTS.md	Ótimas regras estáticas; sem índice de propriedade, gates ou ponte humana
Ferramentas classe Context7	Documentação de bibliotecas para o modelo; não o roteamento do seu monorepo

O doc-bridge entrega AgentHandoff em 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" }
}

Quando um guia humano está ausente, as entregas o destacam como um recurso:

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

Quatro loops (com comandos reais)

Loop	Comando	O que você vê
Agir	`ak-docs query package auth --agent`	`editRoots`, `checks`, `startHere`
Ponte	`ak-docs bootstrap agent-docs`	Rascunha documentação de agente a partir do site humano; `bridge.humanDoc` na entrega
Aprender	`ak-docs memory classify` → `promote`	Rascunho HITL para o corpus de agentes
Explicar	`ak-docs ask "auth is broken in staging"`	Correspondência de propriedade + prévia da entrega + próximos comandos

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

Cobertura que sua equipe verifica diariamente

O seguinte é uma saída ilustrativa do comando, não uma medição deste repositório. Execute o comando localmente ou no CI para valores atuais.

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

O agente usa sozinho

Conexão automática via MCP: ak-docs mcp install --cursor
Habilidade/regra: cole docs/skills/doc-bridge.md nas regras do Cursor — os agentes chamam handoff.resolve antes de editar packages/*
A entrega é o próximo passo: startHere, checks e bridge estão na resposta JSON/MCP

CI como cidadão de primeira classe

Reutilize a GitHub Action incluída em cada PR:

Siga o guia canônico de Gate e CI, que inclui o fluxo de trabalho completo e fixa a versão publicada da Action.

A Action instala o pacote configurado exato (ou o pacote do workspace ao fazer dogfooding deste repositório) e então verifica o índice confirmado e os gates configurados sem reconstruí-los silenciosamente. Ela rejeita versões de pacote não exatas. Consulte o guia do Marketplace.

O guia está fixado na versão estável publicada da Action v1.7.45; a versão do pacote verificada é 1.11.2.

A cobertura é específica do repositório. Execute ak-docs doctor --badge localmente para emitir os selos atuais de entrega e ponte humana, ou pnpm coverage:badge no CI; este README evita intencionalmente publicar uma porcentagem estática desatualizada.

Ou localmente, como duas etapas em vez de uma, porque respondem a perguntas diferentes:

ak-docs index     # after changing docs or config — then review and commit the result
ak-docs gate run  # verifies the committed index, which is what CI verifies

Encadeá-los (index && gate run) não pode reportar um índice obsoleto: ele valida um artefato escrito um segundo antes contra uma reconstrução da mesma árvore. O valor do gate é que o índice commitado e o repositório concordam, então execute-o da mesma forma que o CI faz, contra o que está commitado. Ele falha com Index is stale. Run: ak-docs index — a mesma verificação e a mesma anotação, como no CI.

Superfície do produto

Núcleo — sempre (sem LLM)

Superfície	Propósito
Demo	`ak-docs demo` — fixture incluída, sem configuração
Doctor	Pontuação de cobertura, humanDoc/agent doc ausentes, próximas ações
Index	`DocBridgeIndex` + `contentHash` + `llms.txt` + capacidades
CLI	`query` / `search` / `list` / `ask` / `gate` / `bench` / `memory` / `bootstrap`
MCP	`handoff.resolve`, `doc.search`, `doc.get`, `gate.status`, …
Gates	Frescor, validação de link humano, estilo OKF opcional
Adapters	`pnpm-monorepo`, `nx`, `fumadocs`, `docusaurus`, `vitepress`, `starlight`, `nextra`, `plain-markdown`

Peers opcionais do AgentsKit

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

Veja docs/chat-and-rag.md.

Ecossistema AgentsKit

Quem usa (público)

Projetado e testado em superfícies abertas do AgentsKit:

Superfície	Link
for-agents	agentskit.io/docs/for-agents
Registry	registry.agentskit.io
Playbook	playbook.agentskit.io
AgentsKit Chat	documentação · código-fonte
Code Review	CLI nativo do repositório
Este repositório	CI verde · `ak-docs gate run` em cada PR

Padrão Playbook: docs/playbook/doc-bridge-pattern.md — exportar com ak-docs playbook pattern --text

Exemplos de configuração

Perfil	Exemplo
Markdown solo	`examples/minimal-plain-markdown.config.ts`
Monorepo pnpm	`examples/pnpm-monorepo.config.ts`
Monorepo Nx	`examples/nx-monorepo.config.ts`
Monorepo demo	`examples/demo-monorepo/`
Fumadocs + chat	`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`

Contrato: docs/spec/config-v1.md · CLI: docs/spec/cli.md · MCP: docs/mcp.md · Skill: docs/skills/doc-bridge.md · Padrão: docs/playbook/doc-bridge-pattern.md · Receitas: docs/recipes/index-pipeline.md

Loop de aprendizado — memória → PR de rascunho

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

Status

Pacote npm publicado: v1.7.45 estável. A versão do pacote na árvore de trabalho é 1.8.0 e ainda não foi publicada. O exemplo de Action abaixo fixa intencionalmente a versão estável publicada mais recente; o fluxo de trabalho de release atualiza o pacote e a versão da Action juntos quando um novo release é publicado.

O pacote publicado fornece handoffs portáveis e com falha segura por meio do CLI, servidor MCP, ação de CI e skill empacotada; conformidade determinística com o Documentation Standard v1; proveniência de release verificada; e ferramentas de auditoria de qualidade de documentação.

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

Landing: https://doc-bridge.agentskit.io/

Política de Privacidade

O servidor MCP local lê apenas o projeto selecionado por meio de doc-bridge.config.json. Ele não exige uma chave de API, não envia dados do projeto para o AgentsKit, não coleta telemetria e não escreve arquivos do projeto por meio de suas ferramentas MCP. Veja a Política de Privacidade completa para caminhos acessados, uso, armazenamento, compartilhamento, retenção, integrações opcionais e informações de contato.

Contribuindo

Issues e PRs são bem-vindos. Comece aqui:

Para melhorar a base de evidências, reproduza o estudo anonimizado, adicione um analisador de linguagem ou framework, contribua com uma regra de qualidade de documentação ou adicione uma fixture para uma contradição real ou relação obsoleta.

Necessidade	Doc
Configuração local, testes, fluxo de release	CONTRIBUTING.md
Governança e responsabilidades dos mantenedores	GOVERNANCE.md
Relatórios de vulnerabilidade	SECURITY.md
Padrões da comunidade	CODE_OF_CONDUCT.md
Histórico de releases	CHANGELOG.md
Posicionamento do produto	docs/POSITIONING.md

Licença

MIT