AgentsKit Doc Bridge

Ofrece a los agentes de codificación transferencias de documentación deterministas y de solo lectura con límites de edición, propiedad y verificaciones requeridas antes de los cambios en el repositorio.

GitHub

Prueba este MCPPatrocinado

Documentación

doc-bridge

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

Temas: ai-agents · documentation · developer-experience · mcp · llms-txt · typescript

Compatibilidad: node >=22 · TypeScript 5.8+ · consumidores con pnpm, npm o yarn

Convierte tu documentación en traspasos ejecutables para agentes de codificación.

doc-bridge lee la documentación de tu repositorio, el mapa de propiedad y el sitio de documentación humana, y luego ofrece a humanos y agentes el mismo punto de partida vinculado a evidencia:

dónde empezar a leer
qué archivos/paquetes puede editar
qué comprobaciones demuestran el cambio
qué documentación humana explica la funcionalidad

No es una wiki ni un RAG alojado. El núcleo funciona sin ningún LLM ni clave de API; el portal de documentación utiliza AgentsKit Chat como una superficie opcional sobre esa capa determinista.

doc-bridge maps human docs into structured agent handoffs

Diseñado para repositorios a escala de agentes

Doc Bridge convierte la estructura y documentación de repositorios grandes en contexto compacto y vinculado a evidencia que humanos y agentes de codificación pueden consultar en lugar de recorrer repetidamente el repositorio completo.

Estimación histórica de carga de contexto

Un ciclo anónimo previo de dogfooding estimó hasta 99% menos de carga de contexto serializada. Esta es una estimación histórica de carga, no una garantía de ahorro de tokens del proveedor, calidad de respuesta o corrección semántica. No es la misma medida que el uso de tokens del proveedor.

Estimated context payload reduction

Señal histórica de A/B controlado

El estudio controlado publicado con 96 ejecuciones anonimizadas reportó una señal operativa direccional de:

18.46% menos unidades equivalentes de tokens de proveedor emparejadas en 46 pares completos de tokens;
39.75 segundos menos en latencia P95;
87.5% de ejecuciones completadas operativamente vs. 75.0% con contexto solo del repositorio.

Estas son medidas históricas definidas por separado: la cifra del 99% es una reducción estimada de carga de contexto, mientras que la cifra del 18.46% usa datos equivalentes a tokens de proveedor de 46 observaciones emparejadas. El adjudicador acotado registró cero resultados de éxito del adjudicador en ambos brazos; debido a que ese adjudicador es mecánico y no juzga de forma independiente la corrección semántica, este resultado es direccional y no concluyente. Un piloto local más nuevo no se promociona aquí intencionalmente mientras su evaluación semántica y revisión de publicación estén incompletas. Consulta la metodología completa y datos anonimizados.

Por qué los equipos lo usan

Los agentes son potentes, pero la mayoría de la documentación de repositorios está escrita para humanos. El resultado es familiar: el agente adivina la propiedad, edita el paquete hermano, ejecuta la prueba incorrecta o ignora la guía humana que ya explicaba la regla.

doc-bridge funciona en ambas direcciones:

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

Dirección	Qué hace	Comando
Documentación humana → agentes	Convierte Fumadocs, Docusaurus, markdown y documentación de propiedad en `AgentHandoff`	`ak-docs index` · `ak-docs query --agent`
Memoria del agente → documentación	Lee `.agent-memory/*` y `.cursor/rules/.mdc`, clasifica lo que debería convertirse en documentación del proyecto y redacta una promoción revisada por humanos	`ak-docs memory ingest` · `classify` · `promote --pr`

El traspaso es un contrato de enrutamiento:

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

Las ejecuciones de flujos de trabajo pueden llevar el mismo sobre opcional correlation utilizado por el runtime de AgentsKit y el protocolo Chat. operationId es la identidad entre repositorios; runId, sessionId, turnId, actionId y traceId conservan su significado local. Es solo metadatos acotados y no debe contener indicaciones, secretos ni contenido de documentos.

Ese contrato funciona desde la terminal, MCP, CI y RAG/chat opcional.

Calidad de documentación y reconciliación

El descubrimiento es solo el primer paso. ak-docs audit documentation compara la documentación y propiedad declaradas con el grafo de proyecto observado y reporta hallazgos basados en evidencia para cobertura faltante, relaciones obsoletas, contradicciones estructuradas, duplicados exactos, ejemplos faltantes y metadatos de mantenimiento incompletos.

La corrección en lenguaje natural, la prosa innecesaria y la redundancia semántica permanecen explícitamente not-analyzed hasta que un agente configurado o una revisión humana los evalúe. Los cambios propuestos permanecen revisables y aprobados 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

Prueba en 60 segundos

Este README contiene la prueba de un solo comando; la guía de inicio contiene la configuración completa del repositorio y el primer flujo de indexación.

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

Sin configuración, sin documentación que leer primero. La salida muestra antes/después, un traspaso real, la compuerta de rojo→verde y el fragmento 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

Verifica la ruta real de traspaso

Este ejemplo verificado ejecuta la demo incluida a través de la CLI pública. La compuerta scripts/check-readme-standard.mjs del repositorio compara este bloque byte por byte con el fixture ejecutable; .github/workflows/ci.yml ejecuta esa compuerta y sus pruebas ejecutables en cada pull request.

Las cifras del estudio a continuación no se recalculan con la compuerta del README; su protocolo, controles de privacidad y limitaciones están documentados en los artefactos del estudio enlazados.

import { execFileSync } from 'node:child_process'

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

node examples/verify-handoff.mjs

Para la configuración completa del repositorio, sigue la guía de inicio.

¿Usas Cline? Sigue la configuración determinista de llms-install.md. Ejecuta el servidor MCP fijado a través de pnpm dlx sin agregar Doc Bridge a las dependencias de tu repositorio.

Qué incluye

Consulta el mapa de superficies para una vista visual de las superficies CLI, MCP, CI y adaptadores.

Superficie	Úsala para	Comando / artefacto
CLI	Inspeccionar propiedad, buscar documentación, ejecutar compuertas, hacer preguntas locales	`ak-docs query`, `search`, `ask`, `doctor`, `gate`
Servidor MCP	Permitir que Cursor, Claude Code y agentes estilo Codex resuelvan traspasos antes de editar	`ak-docs mcp`, `handoff.resolve`
GitHub Action / CI	Fallar índices obsoletos y compuertas de documentación configuradas en PRs	`AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7`
Conformidad de documentación	Verificar el estándar ecosistémico estable con evidencia auditable	`ak-docs conformance run documentation-standard-v1 --text`
Auditoría de documentación	Medir la calidad de la documentación y comparar la documentación con el grafo de proyecto observado	`ak-docs audit documentation --json`
Adaptadores de documentación	Vincular documentación humana con documentación de agentes	`fumadocs`, `docusaurus`, `vitepress`, `starlight`, `nextra`, `plain-markdown`
Enrutamiento de monorepos	Descubrir workspaces y comprobaciones	`pnpm-monorepo`, `nx`
Pipeline de memoria	Convertir notas de agentes en borradores de documentación revisables	`memory ingest`, `classify`, `promote --pr`
RAG/chat opcional	Fundamentar el chat en el mismo índice de traspaso primero	`@agentskit/rag`, `@agentskit/ink`, `ak-docs chat`

Consulta docs/getting-started.md, docs/mcp.md y docs/examples.md.

Plugin de Cursor

Este repositorio también contiene un plugin de Cursor que combina el servidor MCP de Doc Bridge (solo lectura, excepto la herramienta explícita de propuesta) con una habilidad de traspaso. Resuelve startHere, readBeforeEditing, editRoots y checks antes de que Cursor edite un repositorio enrutado. El plugin no solicita credenciales ni escribe archivos de proyecto a través de MCP.

Plugin de GitHub Copilot

El manifiesto raíz de Agent Plugins expone la misma habilidad de traspaso portátil y el servidor MCP a GitHub Copilot CLI. Copilot descubre skills/ y .mcp.json desde el diseño estándar de plugins, por lo que la integración permanece propiedad de la fuente en lugar de copiar indicaciones a otro repositorio.

copilot plugin install AgentsKit-io/doc-bridge

Habilidad de agente portátil

skills/doc-bridge-handoff empaqueta el mismo contrato de enrutamiento de cierre ante fallos en el diseño abierto de Agent Skills para clientes compatibles con OpenClaw, Hermes Agent, Pi, Cursor y otros runtimes que puedan ejecutar un script de habilidad local. La habilidad prefiere la herramienta MCP de solo lectura y recurre a un resolvedor CLI fijado y sin credenciales. Nunca edita archivos, ejecuta comprobaciones devueltas ni otorga autoridad fuera de editRoots.

Instala la habilidad publicada desde ClawHub:

clawhub install doc-bridge-handoff

Los usuarios de Pi pueden instalar la misma habilidad propiedad de la fuente a través del paquete npm:

pi install npm:@agentskit/doc-bridge

Paquete MCP para Claude Desktop

Doc Bridge se puede empaquetar como un paquete MCP local para Claude Desktop. El paquete anuncia 14 herramientas MCP, ejercita 8 de ellas en su prueba de humo y marca todas las herramientas excepto docbridge.proposals como solo lectura. Pide al usuario que seleccione el doc-bridge.config.json del repositorio; ese archivo define el límite del proyecto que Doc Bridge puede leer.

Desde un checkout limpio:

pnpm install --frozen-lockfile
pnpm mcpb:pack

El comando compila Doc Bridge, crea un directorio de staging solo de producción, valida el manifiesto MCPB, empaqueta la extensión, verifica su inventario de archivos y escribe el artefacto local bajo .mcpb-output/. Los paquetes generados y los directorios de staging se excluyen intencionalmente de Git.

La declaración de compatibilidad empaquetada actual es solo para macOS; este proyecto no afirma soporte de paquetes para otros sistemas operativos hasta que el artefacto exacto pase una prueba de instalación independiente allí.

Por qué existe esto

Patrón	Brecha
Wiki + RAG	Explica; débil en dónde actuar y en probar que la documentación coincide con el código
Solo AGENTS.md	Grandes reglas estáticas; sin índice de propiedad, compuertas ni puente humano
Herramientas clase Context7	Documentación de bibliotecas para el modelo; no el enrutamiento de tu monorepo

doc-bridge incluye 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" }
}

Cuando falta una guía humana, los traspasos lo muestran como una funcionalidad:

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

Cuatro bucles (con comandos reales)

Bucle	Comando	Qué ves
Actuar	`ak-docs query package auth --agent`	`editRoots`, `checks`, `startHere`
Puente	`ak-docs bootstrap agent-docs`	Redacta documentación de agente desde el sitio humano; `bridge.humanDoc` en el traspaso
Aprender	`ak-docs memory classify` → `promote`	Borrador HITL para el corpus del agente
Explicar	`ak-docs ask "auth is broken in staging"`	Coincidencia de propiedad + vista previa de traspaso + siguientes 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 tu equipo verifica a diario

Lo siguiente es salida ilustrativa del comando, no una medición de este repositorio. Ejecuta el comando localmente o en CI para valores actuales.

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

El agente lo usa solo

Cableado automático MCP: ak-docs mcp install --cursor
Habilidad/regla: pega docs/skills/doc-bridge.md en las reglas de Cursor — los agentes llaman a handoff.resolve antes de editar packages/*
El traspaso es el siguiente paso: startHere, checks y bridge están en la respuesta JSON/MCP

CI como ciudadano de primera clase

Reutiliza la GitHub Action incluida en cada PR:

Sigue la guía canónica de compuertas y CI, que incluye el flujo de trabajo completo y fija la versión publicada de la Action.

La Action instala el paquete configurado exacto (o el paquete del workspace cuando se usa dogfooding en este repositorio), luego verifica el índice confirmado y las compuertas configuradas sin reconstruirlas silenciosamente. Rechaza versiones de paquete no exactas. Consulta la guía de Marketplace.

La guía está fijada a la versión estable publicada de la Action v1.7.45; la versión del paquete verificada es 1.11.2.

La cobertura es específica del repositorio. Ejecuta ak-docs doctor --badge localmente para emitir insignias actuales de traspaso y puente humano, o pnpm coverage:badge en CI; este README evita intencionalmente publicar un porcentaje estático obsoleto.

O localmente, como dos pasos en lugar de uno, porque responden preguntas 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

Encadenarlos (index && gate run) no puede reportar un índice obsoleto: protege un artefacto escrito un segundo antes contra una reconstrucción del mismo árbol. El valor de la compuerta es que el índice confirmado y el repositorio coinciden, así que ejecútalo como lo hace CI, contra lo que está confirmado. Falla con Index is stale. Run: ak-docs index — la misma verificación y la misma anotación que en CI.

Superficie del producto

Núcleo — siempre (sin LLM)

Superficie	Propósito
Demo	`ak-docs demo` — fixture incluido, sin configuración
Doctor	Puntaje de cobertura, documentación humana/agente faltante, próximas acciones
Índice	`DocBridgeIndex` + `contentHash` + `llms.txt` + capacidades
CLI	`query` / `search` / `list` / `ask` / `gate` / `bench` / `memory` / `bootstrap`
MCP	`handoff.resolve`, `doc.search`, `doc.get`, `gate.status`, …
Compuertas	Frescura, validación de enlaces humanos, estilo OKF opcional
Adaptadores	`pnpm-monorepo`, `nx`, `fumadocs`, `docusaurus`, `vitepress`, `starlight`, `nextra`, `plain-markdown`

Pares opcionales de AgentsKit

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

Consulta docs/chat-and-rag.md.

Ecosistema AgentsKit

Quién lo usa (público)

Diseñado y probado en superficies abiertas de AgentsKit:

Superficie	Enlace
for-agents	agentskit.io/docs/for-agents
Registry	registry.agentskit.io
Playbook	playbook.agentskit.io
AgentsKit Chat	documentación · código fuente
Code Review	CLI nativo del repositorio
Este repositorio	CI en verde · `ak-docs gate run` en cada PR

Patrón Playbook: docs/playbook/doc-bridge-pattern.md — exportar con ak-docs playbook pattern --text

Ejemplos de configuración

Perfil	Ejemplo
Markdown en solitario	`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 · Patrón: docs/playbook/doc-bridge-pattern.md · Recetas: docs/recipes/index-pipeline.md

Bucle de aprendizaje — memoria → PR borrador

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

Estado

Paquete npm publicado: v1.7.45 estable. La versión del paquete en el árbol de trabajo es 1.8.0 y aún no está publicada. El ejemplo de Action a continuación fija intencionalmente la última versión estable publicada; el flujo de trabajo de lanzamiento actualiza el paquete y la versión de Action juntos cuando se publica un nuevo lanzamiento.

El paquete publicado proporciona traspasos portátiles y de cierre seguro a través de la CLI, el servidor MCP, la acción de CI y el skill empaquetado; conformidad determinista con el Documentation Standard v1; procedencia de lanzamiento verificada; y herramientas de auditoría de calidad de documentación.

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

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

Política de privacidad

El servidor MCP local solo lee el proyecto seleccionado a través de doc-bridge.config.json. No requiere una clave API, no envía datos del proyecto a AgentsKit, no recopila telemetría ni escribe archivos del proyecto a través de sus herramientas MCP. Consulta la Política de privacidad completa para conocer las rutas accedidas, el uso, el almacenamiento, el intercambio, la retención, las integraciones opcionales y la información de contacto.

Contribuciones

Los issues y PRs son bienvenidos. Comienza aquí:

Para mejorar la base de evidencia, reproduce el estudio anonimizado, agrega un analizador de lenguaje o framework, contribuye con una regla de calidad de documentación o agrega un fixture para una contradicción real o una relación obsoleta.

Necesidad	Documento
Configuración local, pruebas, flujo de lanzamiento	CONTRIBUTING.md
Gobernanza y responsabilidades de mantenedores	GOVERNANCE.md
Informes de vulnerabilidades	SECURITY.md
Estándares comunitarios	CODE_OF_CONDUCT.md
Historial de lanzamientos	CHANGELOG.md
Posicionamiento del producto	docs/POSITIONING.md

Licencia

MIT