LLMWiki Agent Bridge

llmwiki-agent-bridge es la capa opcional de distribución de fuentes y síntesis en tiempo de ejecución de la cadena de herramientas LLMWiki. Se ejecuta como un servicio HTTP local, recopila evidencia de una o más fuentes de conocimiento llmwiki-serve y devuelve un artefacto de respuesta normalizado con citas, contexto de grafo opcional y pasos de traza. Puede ejecutarse solo con evidencia para una primera prueba de humo, o llamar a un adaptador de tiempo de ejecución configurado para respuestas sintetizadas. El adaptador predeterminado está orientado a finalizaciones de chat compatibles con OpenAI.

Úsalo cuando:

• Un cliente quiera un único endpoint en lugar de gestionar por sí mismo la distribución de fuentes, los prompts, las llamadas al tiempo de ejecución, las citas y la conformación de la traza.

• Estés conectando Hermes, DeepAgents o un tiempo de ejecución local genérico a la evidencia de LLMWiki.

• llmwiki-chat u otra interfaz necesite endpoints A2A o MCP de Agent Bridge respaldados por fuentes de conocimiento locales.

Omítelo cuando tu agente o script pueda llamar a llmwiki-serve directamente y gestionar su propia síntesis de respuestas.

Inicio rápido | Elige una ruta | Demo | Perfiles de tiempo de ejecución | Contrato de mensajes | OpenAPI | Integraciones | Ejemplos | Portal de documentación | Contribuciones | Seguridad | Soporte | Registro de cambios

Nota de vista previa pública: npm install está disponible para llmwiki-agent-bridge@latest; la copia de trabajo del código fuente sigue siendo compatible para el desarrollo local y las comprobaciones de versiones.

Para un recorrido visual del primer uso, consulta la demo de la documentación. Muestra el límite de la cadena de herramientas: los flujos de trabajo ascendentes crean archivos Markdown/wiki compatibles, llmwiki-serve los proyecta como fuentes de conocimiento de solo lectura, y el bridge opcional puede consultar juntas fuentes servidas seleccionadas.

No es un bridge exclusivo de Hermes. Hermes es uno de los perfiles de tiempo de ejecución compatibles junto con generic y deepagents; todos los perfiles usan el mismo contrato de mensajes y devuelven la misma forma de artefacto llmwiki_agent_result. Los perfiles de tiempo de ejecución identifican la familia de tiempo de ejecución; los adaptadores de tiempo de ejecución eligen cómo el bridge lo invoca.

Es una herramienta comunitaria independiente para carpetas de conocimiento Markdown de estilo LLM Wiki y contexto legible por agentes. No es un proyecto oficial de Andrej Karpathy ni de ningún productor ascendente mencionado en los ejemplos de compatibilidad.

Elige una ruta

Empieza con la ruta directa siempre que tu cliente pueda llamar a llmwiki-serve por sí mismo. Añade el bridge cuando necesites distribución de fuentes, síntesis en tiempo de ejecución o un único resultado normalizado detrás de un servicio local.

Las plantillas para clientes directos están en integraciones. El contrato de solicitud y artefacto del bridge está documentado en docs/message-send-contract.md y se genera como docs/openapi.json.

Related MCP server: A2ABench

Inicio rápido

Requisitos:

• Node.js >=22.12

• npm >=10

• Uno o más endpoints de fuentes de conocimiento llmwiki-serve en ejecución

• Opcional: un tiempo de ejecución para la síntesis. Las ejecuciones empaquetadas usan actualmente por defecto un adaptador /v1/chat/completions compatible con OpenAI.

• uv y Python 3.11 o superior cuando se inicia la fuente de ejemplo desde una copia de trabajo

Este inicio rápido arranca una copia de trabajo del servidor de fuentes en la Terminal 1. En la Terminal 2, usa el paquete publicado del bridge para ejecuciones locales normales, o usa una copia de trabajo del código fuente del bridge cuando quieras ejecutar comprobaciones del repositorio, inspeccionar ejemplos empaquetados o desarrollar el bridge.

Terminal 1: servidor de fuentes

Clona e inicia la fuente de conocimiento llmwiki-serve de ejemplo. Deja este proceso en ejecución:

git clone https://github.com/knowledge-bridge-labs/llmwiki-serve.git
cd llmwiki-serve
uv sync --extra dev
uv run llmwiki-serve serve ./examples/sample-wiki --host 127.0.0.1 --port 8765

Terminal 2: bridge

Desde cualquier terminal, verifica que la Terminal 1 está sirviendo la fuente de ejemplo:

curl -s http://127.0.0.1:8765/manifest

Inicia el paquete publicado de vista previa pública:

npx llmwiki-agent-bridge@latest

Para desarrollo con una copia de trabajo del código fuente, abre en su lugar la Terminal 2 en el mismo espacio de trabajo principal que contenga la copia de llmwiki-serve, clona el bridge, instala las dependencias, ejecuta las comprobaciones locales e inicia la CLI de la copia de trabajo:

git clone https://github.com/knowledge-bridge-labs/llmwiki-agent-bridge.git
cd llmwiki-agent-bridge
npm ci
npm run check
node ./bin/llmwiki-agent-bridge.mjs

La CLI escribe un evento JSON ready cuando el bridge está escuchando:

{
  "event": "ready",
  "url": "http://127.0.0.1:8788",
  "sourcePolicy": "private-http"
}

Para la síntesis de respuestas con tiempo de ejecución, reinicia el bridge con el perfil de tiempo de ejecución que coincida con tu tiempo de ejecución local. Este ejemplo genérico funciona con cualquier tiempo de ejecución que implemente finalizaciones de chat compatibles con OpenAI.

macOS/Linux:

LLMWIKI_AGENT_BRIDGE_BASE_URL=http://127.0.0.1:8642/v1 \
LLMWIKI_AGENT_BRIDGE_MODEL=local-model \
LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE=generic \
npx llmwiki-agent-bridge@latest

Windows PowerShell:

$env:LLMWIKI_AGENT_BRIDGE_BASE_URL = 'http://127.0.0.1:8642/v1'
$env:LLMWIKI_AGENT_BRIDGE_MODEL = 'local-model'
$env:LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE = 'generic'
npx llmwiki-agent-bridge@latest

Desde una copia de trabajo del código fuente, usa node ./bin/llmwiki-agent-bridge.mjs o node .\bin\llmwiki-agent-bridge.mjs en lugar del comando npx final.

Para Hermes o un tiempo de ejecución compatible de estilo OpenAI, mantén la misma forma de comando y cambia LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE además del nombre del modelo:

La integración con el proveedor directo de DeepAgents debería priorizar ACP. La documentación oficial de DeepAgents describe deepagents-acp como una CLI de ACP stdio / API programática. Este paquete incluye un adaptador opcional de subproceso ACP en vivo detrás de runtimeAdapter=deepagents-acp. El valor predeterminado sigue siendo finalizaciones de chat; el adaptador ACP inicia un proceso stdio deepagents-acp por cada solicitud de tiempo de ejecución del bridge, cierra las solicitudes de permiso como fallidas con ACP cancelled y aplica el tiempo de espera de la solicitud del bridge a la limpieza del proceso hijo.

Deja el bridge en ejecución. Los siguientes comandos también son comandos de la copia de trabajo del bridge; si la Terminal 2 está ocupada por el proceso del bridge, abre otra terminal y ejecuta primero cd llmwiki-agent-bridge.

Comprueba la superficie local:

curl -s http://127.0.0.1:8788/health
curl -s http://127.0.0.1:8788/.well-known/agent-card.json
curl -s http://127.0.0.1:8788/settings.json

Para la primera ejecución, abre http://127.0.0.1:8788/settings y sigue la configuración guiada:

1. Conecta el tiempo de ejecución cuando quieras síntesis. Establece el perfil de tiempo de ejecución, la URL base y el modelo. La página guarda estos campos mediante PUT /settings/config.json.

2. Registra fuentes de conocimiento. Añade la fuente de ejemplo en http://127.0.0.1:8765, márcala como lista y seleccionada, y guárdala mediante GET/PUT /settings/sources.json.

3. Verifica el bridge. Ejecuta la verificación de la página de configuración, que envía POST /message:send usando la fuente registrada y muestra el artefacto de respuesta devuelto, las citas, el grafo y los pasos de traza. /message:send usa delegated-runtime por defecto, por lo que esta comprobación de la página de configuración espera que el tiempo de ejecución configurado sea accesible. Usa la solicitud de ejemplo solo con evidencia que aparece a continuación para una prueba de humo sin tiempo de ejecución.

Las credenciales del tiempo de ejecución, la red, la autenticación, CORS, el tiempo de espera y los controles de política de fuentes se encuentran en diagnostics/advanced. La mayoría de los usuarios locales de OSS solo necesitan los tres pasos de configuración anteriores.

Para una prueba de humo sin tiempo de ejecución desde un lanzamiento solo con paquete, envía una solicitud en línea solo con evidencia:

curl -s http://127.0.0.1:8788/message:send \
  -H 'content-type: application/json' \
  -d '{"data":{"query":"release readiness","mode":"evidence-only","knowledgeSources":[{"id":"sample-wiki","name":"Sample Wiki","protocol":"llmwiki-http","status":"ready","url":"http://127.0.0.1:8765","selected":true}]}}'

Desde una copia de trabajo del código fuente de llmwiki-agent-bridge, puedes enviar la solicitud equivalente incluida para que la ruta --data @examples/message-send.local.json apunte a este repositorio:

curl -s http://127.0.0.1:8788/message:send \
  -H 'content-type: application/json' \
  --data @examples/message-send.local.json

El archivo incluido examples/message-send.local.json apunta a http://127.0.0.1:8765 y establece mode en evidence-only. Si tu proceso de llmwiki-serve o del bridge usa un puerto diferente, copia ese archivo a una ruta temporal, actualiza la URL de la fuente y envía el POST a la URL del bridge que hayas iniciado.

Los clientes de estilo MCP pueden completar el ciclo de vida básico en /mcp con initialize, notifications/initialized y ping, y luego listar las herramientas del bridge. Usa llmwiki_agent_run cuando quieras que el bridge produzca una respuesta fundamentada completa, o usa las herramientas de fuentes de solo lectura cuando tu agente anfitrión quiera inspeccionar las fuentes de forma progresiva:

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"ping"}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/list"}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"llmwiki_agent_run","arguments":{"query":"release readiness"}}}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"llmwiki_context","arguments":{"sourceId":"sample-wiki","query":"release readiness","limit":5}}}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"llmwiki_graph_neighbors","arguments":{"sourceId":"sample-wiki","nodeId":"sample-wiki:overview","direction":"out","relation":"supports","limit":20}}}'

Omite knowledgeSources para usar las fuentes registradas mediante /settings. Pasar knowledgeSources: [] significa "ejecutar sin fuentes" y solo es útil para pruebas negativas. La lista legible de fuentes omite las URL de los endpoints. Los descriptores estructurados llmwiki_sources.sources incluyen las URL de las fuentes para que los entornos de trabajo locales puedan seleccionar fuentes gestionadas por el bridge y devolverlas a /message:send. No copies URL locales privadas en documentos, incidencias o ejemplos públicos.

La solicitud de ejemplo pregunta release readiness. El texto exacto de la respuesta puede variar según el tiempo de ejecución; el objetivo de integración estable es la tarea completada más los campos del artefacto de datos llmwiki_agent_result:

{
  "answer": "Grounded answer text from the configured runtime.",
  "citations": [
    {
      "sourceId": "sample-wiki",
      "pageId": "release-readiness",
      "title": "Release Readiness",
      "score": 0.92
    }
  ],
  "graph": {
    "nodes": [],
    "edges": []
  },
  "steps": [
    {
      "id": "bridge-evidence",
      "label": "Prepare evidence",
      "status": "done"
    },
    {
      "id": "runtime-chat-completions",
      "label": "Call chat completions",
      "status": "done"
    }
  ]
}

Para cargas útiles completas y notas de configuración local, usa ejemplos, perfiles de tiempo de ejecución, el contrato de mensajes y rutas de cliente.

Qué hace

El bridge expone una pequeña superficie HTTP local:

Para cada petición POST /message:send, el puente:

1. Selecciona los descriptores de Knowledge Sources disponibles de la petición.

2. Obtiene el contexto a través de llmwiki-http, JSON-RPC de estilo MCP o HTTP de estilo A2A.

3. Empaqueta citas, contexto de grafo, metadatos del paquete de fuentes y pasos de traza.

4. En delegated-runtime o hybrid, representa el paquete de evidencia como JSON compacto y llama al endpoint /v1/chat/completions configurado, compatible con OpenAI.

5. En evidence-only, omite la llamada al runtime y devuelve un resumen de evidencia generado por el puente.

6. Devuelve el texto de la respuesta junto con el artefacto llmwiki_agent_result.

POST /mcp expone dos capas. llmwiki_agent_run recorre la misma ruta de ejecución interna que /message:send y devuelve contenido de texto más structuredContent.llmwiki_agent_result. Las herramientas de solo lectura sobre fuentes llmwiki_list_sources, llmwiki_context, llmwiki_search, llmwiki_read, llmwiki_graph, llmwiki_graph_neighbors y llmwiki_source_bundle no llaman al runtime configurado; permiten a un agente anfitrión listar fuentes, leer contexto de orientación inicial, buscar, abrir una página, inspeccionar datos de grafo, recorrer un vecindario acotado o leer metadatos seguros de paquete de fuentes antes de decidir si se necesita una exploración adicional de fuentes o una ejecución de respuesta completa.

Para comprobaciones locales de operador sin iniciar el servicio HTTP, usa llmwiki-agent-bridge sources --json, llmwiki-agent-bridge ls o llmwiki-agent-bridge status --probe. La salida de la CLI lee el archivo de configuración local y puede mostrar raíces locales almacenadas para diagnóstico. Las respuestas del registro HTTP redactan las raíces absolutas y las convierten en etiquetas seguras, y rechazan los ID de fuente duplicados en PUT /settings/sources.json.

Las peticiones pueden suministrar knowledgeSources directamente, u omitirlas y usar los Knowledge Sources registrados en el puente. Registra fuentes en el Paso 2 de /settings o llamando a PUT /settings/sources.json con un array sources. Se pueden registrar y consultar varias fuentes listas y seleccionadas en una misma ejecución. Las llamadas a las fuentes se acotan internamente en lugar de enviarse con paralelismo ilimitado. El artefacto devuelto se normaliza de nuevo al orden de las fuentes seleccionadas para citas, datos de grafo, paquetes de fuentes, pasos de trazabilidad, diagnósticos y fallos por fuente.

/message:send mantiene el contrato heredado de data.query y también acepta contexto de conversación adicional para el runtime: data.message o un message A2A de nivel superior, data.messages, data.threadId, data.sessionId, data.turnId, data.runtimeContext.conversation, configuration.historyLength de estilo A2A y metadata.threadId/sessionId/turnId de estilo A2A. El puente usa la consulta actual de data.query o del texto del mensaje A2A para la recuperación de fuentes y, a continuación, incluye un historial de conversación usuario/asistente acotado en la llamada de chat-completions al runtime, después del prompt de sistema con evidencia.

Enrutamiento del modo de recuperación

Los clientes pueden solicitar opcionalmente un modo de recuperación de fuentes con data.retrieval. Esto es independiente de data.mode: data.mode y data.orchestrationMode controlan la orquestación del puente, mientras que data.retrieval.searchMode controla la recuperación de fuentes. Omite data.retrieval para mantener la forma de petición léxica heredada.

{
  "data": {
    "query": "Which release checks are still missing?",
    "mode": "evidence-only",
    "retrieval": {
      "schemaVersion": "llmwiki.retrieval.v1",
      "searchMode": "hybrid",
      "fallback": "lexical",
      "search": {
        "limit": 8,
        "snippetChars": 600
      }
    }
  }
}

La recuperación semántica la determinan las fuentes. El puente solo enruta la intención; no incorpora documentos ni consultas, no construye un índice vectorial, no elige proveedores de embeddings, no descarga modelos, no almacena vectores, ni reenvía credenciales de proveedor, endpoints, rutas de caché, nombres de modelo ni estos representables de las cargas de clientes públicas. SQLite GraphStore se configura en llmwiki-serve: la versión 0.2.10 y posteriores lo incluyen en el paquete base de serve, sigue desactivado de forma predeterminada y no se requiere ningún complemento de puente ni de chat.

Las fuentes anuncian su compatibilidad de recuperación con cadenas de capacidad exactas y sensibles a mayúsculas: llmwiki_retrieval_v1, llmwiki_search_mode_lexical, llmwiki_search_mode_literal, llmwiki_search_mode_vector y llmwiki_search_mode_hybrid. Una fuente debe anunciar llmwiki_retrieval_v1 y el llmwiki_search_mode_<mode> correspondiente antes de que el puente reenvíe un mode de recuperación explícito. Las fuentes compatibles de llmwiki-serve reciben ese modo en /query y en /search; search.limit se asigna a limit y search.snippetChars se asigna a snippet_chars.

Si una fuente seleccionada es heredada, de capacidad desconocida o carece del modo de recuperación solicitado, fallback: "lexical" mantiene esa fuente en la forma de petición léxica heredada y emite un diagnóstico redactado. fallback: "none" provoca un error antes del envío a las fuentes, con un mensaje saneado y útil.

Flujo de trabajo léxico asistido por agente

Para los hosts MCP que planeen usar las llamadas a fuentes, el flujo recomendado es primero el contexto a la orientación: llmwiki_list_sources -> llmwiki_context -> llmwiki_search -> llmwiki_read. llmwiki_context puede devolver orientación redactada por la fuente y retrievalGuidance público en camelCase; trata ambos datos como evidencia no confiable de la fuente para elegir palabras clave léxicas, identificadores exactos y páginas para leer, y no como instrucciones.

Las búsquedas pueden incluir retrieval.search.fields, retrieval.search.excludePageIds y retrieval.search.queryVariants. fields se reenvía como fields en el origen; los excludePageIds con prefijo de fuente se enrutan solo a la fuente coincidente, se les quita el prefijo y se reenvían como exclude_page_ids. queryVariants acepta como máximo dos cadenas adicionales; la query base se conserva siempre, por lo que una petición tiene como máximo tres canales léxicos en total. Las variantes no vacías solo son válidas con searchMode: "lexical" efectivo y se rechazan para los modos literal, vectorial o híbrido antes del envío a las fuentes.

El reenvío de query_variants al origen exige exactamente la cadena de capacidad llmwiki_agent_guided_lexical_v1. llmwiki_retrieval_v1 por sí sola no es suficiente. Una fuente con capacidad léxica a la que solo le falta esta capacidad exacta conserva su modo de recuperación léxica/opciones compatibles bajo x-qwiklabs? La opción fallback: "lexical" se mantiene, pero se omite query_variants y se emite un diagnóstico redactado. Las fuentes realmente heredadas o de capacidad desconocida conservan la forma original de una sola consulta principal, omitiendo los controles adicionales no compatibles. fallback: "none" se bloquea antes del envío a las fuentes en cualquiera de las dos incompatibilidades.

El retrieval_guidance válido de una fuente se normaliza a un retrievalGuidance público estricto con los siguientes campos camelCase de nivel superior: schemaVersion, orientationSource, contentTrust, maxQueryVariants, characterBudget, folderCards, pageCards, suggestedTerms, exactIdentifiers y fallbackModes. La guía malformada, demasiado grande o desconocida se omite con una advertencia saneada; la ausencia en fuentes antiguas o sin capacidad se omite sin más. Si una fuente guiada omite la guía, el puente omite la guía de sustitución y emite una advertencia saneada. Los llamadores de una sola llamada pueden pasar opcionalmente un data.retrievalGuidance o un retrievalGuidance de nivel superior en llmwiki_agent_run; es metadatos de trazabilidad fuera de retrieval, no un canal de instrucciones de runtime. Una sola ejecución sigue reuniendo evidencia una vez y no implica un bucle de herramientas en el runtime.

Registro de auditoría de solicitudes seguro

Establece LLMWIKI_AGENT_BRIDGE_AUDIT_LOG=1 o pasa auditLog: true para emitir una línea JSON por cada solicitud auditada del puente a través del logger existente (stdout por defecto). Las rutas auditadas son /message:start, /mcp, /settings, /settings.json, /settings/config.json, /settings/sources.json, /.well-known/agent-card.json y /health.

Los eventos de auditoría se incluyen deliberadamente en una lista de permitidos. Incluyen patrones de ruta, estado, duración, ID de solicitud/seguimiento, modo de orquestación, estado de llamada al runtime, recuentos de fuentes y artefactos, campos de recuento/boolean de la conversación y marcas de redacción. No incluyen prompts sin procesar, respuestas del runtime, cuerpos de petición o respuesta, cadenas de consulta, URLs de fuentes, URLs base de runtime, nombres de modelos, claves API, tokens de portador, rutas locales, IDs de hilo/sesión ni contenido de mensajes de conversación.

Registro de depuración de E/S predeterminado

El puente también emite una transmisión separada de depuración de E/S JSONL activada por defecto, en .runtime-logs/llmwiki-agent-bridge-io.jsonl. Estos eventos usan llmwiki.agent_bridge.io y están pensados para la resolución de problemas local del flujo de POST /message:send de solicitudes, fuentes, runtime y artefact final.

Los registros de E/S pueden incluir prompts, cuerpos de petición/respuesta de las fuentes, mensajes del runtime, respuestas del runtime y artefactos del puente tras la redacción. Siempre redactan las cabeceras de autorización y de tipo con credenciales, claves API, tokens de portador, URLs sin procesar de fuentes/runtime, secretos en la consulta de URL y rutas locales absolutas evidentes. Este flujo está deliberadamente separado del registro de auditoría seguro.

Establece LLMWIKI_AGENT_BRIDGE_IO_LOG=off o persiste "ioLog": false para deshabilitarlo. Establece LLMWIKI_AGENT_BRIDGE_IO_LOG=logger o stdout para enrutarlo a través del logger del proceso. LLMWIKI_AGENT_BRIDGE_IO_LOG_PATH elige una ruta de archivo diferente.

flowchart LR
  client["client or chat workbench"]
  bridge["llmwiki-agent-bridge"]
  sources["selected Knowledge Sources"]
  runtime["OpenAI-compatible runtime"]
  artifact["answer artifact<br/>citations, graph, trace"]

  client --> bridge
  bridge --> sources
  sources --> bridge
  bridge --> runtime
  runtime --> bridge
  bridge --> artifact

Protocolos de Knowledge Sources compatibles:

El contrato OpenAPI generado se encuentra en docs/openapi.json. Cubre la superficie HTTP local del puente y la forma del artefacto llmwiki_agent_result como contrato de compatibilidad en vista previa pública, no como una certificación A2A.

El paquete incluye @a2a-js/sdk@0.3.14 para comprobaciones de compatibilidad de descubrimiento A2A, manteniendo la ruta /message:send existente.

Perfiles de runtime

Los perfiles son ajustes de configuración conservadores sobre el mismo contrato de puente. Cambian los metadatos de identidad del runtime, el nombre del modelo por defecto y la configuración orientada al operador; no cambian el formato de evidencia de LLMWiki. El JSON compacto es la codificación actual de evidencia de prompt en runtime. La aprobación amplia por defecto en producción es una afirmación de evidencia controlada por el e2e de aprobación de prompt de runtime rastreado, no un cambio de perfil.

Los alias de entorno heredados HERMES_* y HERMES_A2A_BRIDGE_* siguen disponibles para la migración. Los nuevos despliegues deberían preferir las variables LLMWIKI_AGENT_BRIDGE_*.

Más detalle: docs/runtime-profiles.md.

Superficie del paquete

llmwiki-agent-bridge incluye un paquete Node con estos puntos de entrada públicos:

El paquete de vista previa pública está disponible a través de llmwiki-agent-bridge@latest. Ejecútalo sin instalarlo globalmente:

npx llmwiki-agent-bridge@latest

O instala el paquete y ejecuta el CLI:

npm install --global llmwiki-agent-bridge@latest
llmwiki-agent-bridge

El checkout del código fuente sigue siendo una ruta de desarrollo compatible:

npm ci
npm run check
node ./bin/llmwiki-agent-bridge.mjs

Rutas de Integración

• Guía de rutas de cliente

• Resumen de integraciones

• Ejemplo de habilidad de Codex

• Ejemplo de comando de Claude Code

• Ejemplo de instrucciones de Copilot

Para uso directo del agente, ejecuta llmwiki-serve, establece LLMWIKI_SERVE_URL y adapta las plantillas en integrations/. Los ejemplos llaman primero a /query, luego a /search, /read/{page_id}, /graph o /mcp para una inspección más específica.

export LLMWIKI_SERVE_URL=http://127.0.0.1:8765

Usa llmwiki-agent-bridge cuando el flujo de trabajo también necesite distribución de fuentes, síntesis de runtime y un artefacto de respuesta normalizado.

Configuración

La mayoría de las ejecuciones locales solo necesitan la URL base del runtime, el modelo, el perfil y un token de portador opcional del puente. Mantén runtimeAdapter en su valor predeterminado a menos que estés probando una integración de adaptador explícita:

Los detalles de política de fuentes, CORS, host de enlace y alias de migración están documentados en perfiles de runtime y rutas de cliente.

La implementación mantiene los valores predeterminados de Hermes para compatibilidad hacia atrás. Para una nueva instalación OSS, establece LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE=generic explícitamente a menos que te conectes a Hermes o DeepAgents, y establece el nombre del modelo esperado por ese runtime.

No expongas el puente en una interfaz pública o compartida sin LLMWIKI_AGENT_BRIDGE_BEARER_TOKEN. Los enlaces no loopback requieren una aceptación explícita, y los enlaces públicos sin autenticación son una vía de escape solo para desarrollo.

La página /settings es la interfaz guiada de primera ejecución sobre la misma configuración. El paso 1 conecta el runtime y guarda el perfil, la URL base y el modelo mediante PUT /settings/config.json. El paso 2 guarda descriptores reutilizables de Knowledge Source mediante GET/PUT /settings/sources.json. El paso 3 verifica el puente enviando POST /message:send desde la página y mostrando el artefacto devuelto. Los campos de credenciales de runtime, red avanzada, autenticación, CORS, tiempo de espera y política de fuentes siguen disponibles en diagnóstico/avanzado; los cambios en los campos de runtime en vivo se aplican al proceso en ejecución. El host y port de enlace se guardan para el próximo inicio y la respuesta de guardado los lista bajo restartRequired.

API Programática

import { startAgentBridge } from 'llmwiki-agent-bridge'

const { server, url } = await startAgentBridge({
  port: 0,
  baseUrl: 'http://127.0.0.1:8642/v1',
  model: 'local-model',
  runtimeProfile: 'generic',
})

console.log(url)
server.close()

Los exports heredados createHermesA2aBridge y startHermesA2aBridge están disponibles durante la migración.

Estructura del Repositorio

Estado de lanzamiento

llmwiki-agent-bridge está en vista previa pública. El paquete npm está publicado y se admiten ejecuciones basadas en paquete con npx llmwiki-agent-bridge@latest o npm install --global llmwiki-agent-bridge@latest para uso local. El checkout del código fuente sigue siendo compatible para el desarrollo, la validación del repositorio y las comprobaciones de lanzamiento.

Las URL del repositorio, de los issues, de la insignia de CI, del paquete y de la documentación alojada apuntan intencionalmente a la organización Knowledge Bridge Labs. La matriz alojada Release Status & Compatibility registra qué rutas de paquete y de runtime están disponibles actualmente.

Consulta docs/release.md antes de preparar, publicar o etiquetar la próxima versión de vista previa pública.

Desarrollo

npm run lint
npm run contracts:check
npm test
npm run pack:dry-run
npm run audit

npm run check ejecuta lint, comprobaciones de desviación del contrato generado, pruebas y empaquetado en seco.

Cadena de herramientas

Comunidad

Antes de abrir una pull request, lee CONTRIBUTING.md, mantén los cambios centrados en el contrato del bridge e incluye los resultados de validación.

Usa los issues de GitHub para errores reproducibles, solicitudes de funciones concretas, notas de compatibilidad de runtime o protocolo y carencias documentales. Mantén los ejemplos públicos y desinfectados; no incluyas credenciales, tokens de portador, URL de endpoints privados, contenido wiki sensible sin procesar ni registros de runtime privados.

• Informes de errores

• Compatibilidad de runtime o protocolo

• Solicitudes de funciones

• Problemas de documentación

• Política de seguridad

• Guía de soporte

• Código de conducta

Para vulnerabilidades, sigue SECURITY.md en lugar de abrir un issue público detallado.

Licencia

Apache-2.0. Consulta LICENSE.