LLMWiki Agent Bridge

llmwiki-agent-bridge ist die optionale Quellen-Fan-out- und Laufzeit-Synthese-Ebene für die LLMWiki-Toolchain. Es läuft als lokaler HTTP-Dienst, sammelt Belege von einer oder mehreren llmwiki-serve-Wissensquellen und gibt ein normalisiertes Antwort-Artefakt mit Zitaten, optionalem Graphenkontext und Trace-Schritten zurück. Es kann für einen ersten Smoke-Test nur Belege ausführen oder einen konfigurierten Laufzeitadapter für synthetisierte Antworten aufrufen. Der Standardadapter zielt auf OpenAI-kompatible Chat-Completions ab.

Verwenden Sie es, wenn:

• Ein Client einen einzigen Endpunkt möchte, anstatt selbst Quellen-Fan-out, Prompting, Laufzeitaufrufe, Zitate und Trace-Formung zu verwalten.

• Sie Hermes, DeepAgents oder eine generische lokale Laufzeit mit LLMWiki-Belegen verbinden.

• llmwiki-chat oder eine andere UI Agent-Bridge-A2A- oder MCP-Endpunkte benötigt, die durch lokale Wissensquellen unterstützt werden.

Verzichten Sie darauf, wenn Ihr Agent oder Skript llmwiki-serve direkt aufrufen und seine eigene Antwortsynthese übernehmen kann.

Schnellstart | Einen Weg wählen | Demo | Laufzeitprofile | Nachrichtenvertrag | OpenAPI | Integrationen | Beispiele | Dokumentationsportal | Mitwirken | Sicherheit | Support | Changelog

Hinweis zur öffentlichen Vorschau: npm install ist für llmwiki-agent-bridge@latest verfügbar; ein Source-Checkout bleibt für lokale Entwicklung und Release-Prüfungen unterstützt.

Eine visuelle Einführung für den ersten Start finden Sie in der Doku-Demo. Sie zeigt die Grenze der Toolchain: vorgelagerte Workflows erzeugen kompatible Markdown-/Wiki-Dateien, llmwiki-serve projiziert sie schreibgeschützt als Wissensquellen, und die optionale Bridge kann ausgewählte bereitgestellte Quellen gemeinsam abfragen.

Es ist keine reine Hermes-Bridge. Hermes ist neben generic und deepagents ein unterstütztes Laufzeitprofil; alle Profile verwenden denselben Nachrichtenvertrag und geben dieselbe llmwiki_agent_result-Artefaktform zurück. Laufzeitprofile identifizieren die Laufzeitfamilie; Laufzeitadapter legen fest, wie die Bridge die Laufzeit aufruft.

Es ist ein unabhängiges Community-Werkzeug für LLM-Wiki-artige Markdown-Wissensordner und agentenlesbaren Kontext. Es ist kein offizielles Projekt von Andrej Karpathy oder einem der in den Kompatibilitätsbeispielen genannten vorgelagerten Hersteller.

Einen Weg wählen

Beginnen Sie mit dem direkten Weg, wenn Ihr Client llmwiki-serve selbst aufrufen kann. Fügen Sie die Bridge hinzu, wenn Sie Fan-out, Laufzeitsynthese oder ein einzelnes normalisiertes Ergebnis hinter einem lokalen Dienst benötigen.

Vorlagen für direkte Clients befinden sich in Integrationen. Der Bridge-Anfrage- und Artefaktvertrag ist in docs/message-send-contract.md dokumentiert und wird als docs/openapi.json generiert.

Related MCP server: A2ABench

Schnellstart

Anforderungen:

• Node.js >=22.12

• npm >=10

• Ein oder mehrere laufende llmwiki-serve-Wissensquellen-Endpunkte

• Optional: eine Laufzeit für die Synthese. Verpackte Ausführungen verwenden standardmäßig derzeit einen OpenAI-kompatiblen /v1/chat/completions-Adapter.

• uv und Python 3.11 oder neuer, wenn Sie die Beispielquelle aus einem Checkout starten

Diese Schnellstartanleitung startet einen Source-Server-Checkout in Terminal 1. Verwenden Sie in Terminal 2 für normale lokale Ausführungen das veröffentlichte Bridge-Paket oder einen Bridge-Source-Checkout, wenn Sie Repository-Prüfungen ausführen, verpackte Beispiele ansehen oder die Bridge entwickeln möchten.

Terminal 1: Quellserver

Klonen und starten Sie die Beispiel-Wissensquelle llmwiki-serve. Lassen Sie diesen Prozess laufen:

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

Prüfen Sie von einem beliebigen Terminal aus, dass Terminal 1 die Beispielquelle bereitstellt:

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

Starten Sie das veröffentlichte Public-Preview-Paket:

npx llmwiki-agent-bridge@latest

Für die Entwicklung mit Source-Checkout öffnen Sie stattdessen Terminal 2 in demselben übergeordneten Workspace, der den llmwiki-serve-Checkout enthält, klonen Sie die Bridge, installieren Sie Abhängigkeiten, führen Sie die lokalen Prüfungen aus und starten Sie die Checkout-CLI:

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

Die CLI schreibt ein JSON-ready-Ereignis, sobald die Bridge lauscht:

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

Für eine laufzeitgestützte Antwortsynthese starten Sie die Bridge mit dem Laufzeitprofil neu, das zu Ihrer lokalen Laufzeit passt. Dieses generische Beispiel funktioniert für jede Laufzeit, die OpenAI-kompatible Chat-Completions implementiert.

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

Verwenden Sie bei einem Source-Checkout node ./bin/llmwiki-agent-bridge.mjs oder node .\bin\llmwiki-agent-bridge.mjs anstelle des abschließenden npx-Befehls.

Für Hermes oder eine kompatible OpenAI-ähnliche Laufzeit behalten Sie die gleiche Befehlsform bei und ändern LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE sowie den Modellnamen:

Die DeepAgents-Direktanbieterintegration sollte ACP-orientiert sein. Die offizielle DeepAgents-Dokumentation beschreibt deepagents-acp als eine ACP-stdio-CLI/programmatische API. Dieses Paket enthält einen optionalen Live-ACP-Subprozess-Adapter hinter runtimeAdapter=deepagents-acp. Der Standard bleibt Chat-Completions; der ACP-Adapter startet einen deepagents-acp-stdio-Prozess pro Bridge-Laufzeitanfrage, schließt Berechtigungsaufforderungen mit ACP cancelled ab und wendet das Bridge-Anfrage-Timeout auf die Bereinigung des untergeordneten Prozesses an.

Lassen Sie die Bridge laufen. Die folgenden Befehle sind ebenfalls Bridge-Checkout-Befehle; wenn Terminal 2 durch den Bridge-Prozess belegt ist, öffnen Sie eine weitere Eingabeaufforderung und führen Sie zuerst cd llmwiki-agent-bridge aus.

Prüfen Sie die lokale Oberfläche:

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

Öffnen Sie für den ersten Lauf http://127.0.0.1:8788/settings und folgen Sie der geführten Einrichtung:

1. Verbinden Sie die Laufzeit, wenn Sie Synthese wünschen. Legen Sie das Laufzeitprofil, die Basis-URL und das Modell fest. Die Seite speichert diese Felder über PUT /settings/config.json.

2. Registrieren Sie Wissensquellen. Fügen Sie die Beispielquelle unter http://127.0.0.1:8765 hinzu, markieren Sie sie als bereit und ausgewählt, und speichern Sie sie über GET/PUT /settings/sources.json.

3. Bridge überprüfen. Führen Sie die Überprüfung der Einstellungsseite aus, die POST /message:send mit der registrierten Quelle sendet und das zurückgegebene Antwort-Artefakt, Zitate, Graph und Trace-Schritte anzeigt. /message:send standardmäßig auf delegated-runtime, daher erwartet diese Einstellungsseiten-Prüfung, dass die konfigurierte Laufzeit erreichbar ist. Verwenden Sie die folgende Beispielanfrage mit nur Belegen für einen Smoke-Test ohne Laufzeit.

Laufzeit-Anmeldeinformationen, Netzwerk, Authentifizierung, CORS, Zeitüberschreitung und Quellenrichtlinien-Steuerelemente befinden sich unter diagnostics/advanced. Die meisten lokalen OSS-Benutzer benötigen nur die drei obigen Einrichtungsschritte.

Für einen Smoke-Test ohne Laufzeit aus einem reinen Paketstart senden Sie eine Inline-Anfrage mit nur Belegen:

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}]}}'

Von einem llmwiki-agent-bridge-Source-Checkout aus können Sie die gebündelte äquivalente Anfrage senden, damit der Pfad --data @examples/message-send.local.json zu diesem Repository aufgelöst wird:

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

Die gebündelte Datei examples/message-send.local.json zeigt auf http://127.0.0.1:8765 und setzt mode auf evidence-only. Wenn Ihr llmwiki-serve- oder Bridge-Prozess einen anderen Port verwendet, kopieren Sie diese Datei in einen temporären Pfad, aktualisieren Sie die Quellen-URL und senden Sie sie an die von Ihnen gestartete Bridge-URL.

MCP-artige Clients können den grundlegenden Lebenszyklus auf /mcp mit initialize, notifications/initialized und ping durchlaufen und dann die Bridge-Tools auflisten. Verwenden Sie llmwiki_agent_run, wenn die Bridge eine vollständige fundierte Antwort erzeugen soll, oder verwenden Sie die schreibgeschützten Quellen-Tools, wenn Ihr Host-Agent Quellen schrittweise untersuchen möchte:

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}}}'

Lassen Sie knowledgeSources weg, um über /settings registrierte Quellen zu verwenden. Die Übergabe von knowledgeSources: [] bedeutet „ohne Quellen ausführen“ und ist nur für Negativtests nützlich. Die menschenlesbare Quellenliste lässt Endpunkt-URLs aus. Die strukturierten llmwiki_sources.sources-Deskriptoren enthalten Quellen-URLs, sodass lokale Workbenches Bridge-verwaltete Quellen auswählen und an /message:send zurückgeben können. Kopieren Sie keine privaten lokalen URLs in öffentliche Dokumentationen, Issues oder Beispiele.

Die Beispielanfrage fragt nach release readiness. Der genaue Antwortwortlaut kann je nach Laufzeit variieren; das stabile Integrationsziel ist die abgeschlossene Aufgabe plus die Daten-Artefaktfelder von 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"
    }
  ]
}

Für vollständige Payloads und lokale Einrichtungshinweise verwenden Sie Beispiele, Laufzeitprofile, den Nachrichtenvertrag und Client-Pfade.

Was es tut

Die Bridge stellt eine kleine lokale HTTP-Oberfläche bereit:

Für jede POST /message:send-Anfrage führt die Bridge Folgendes aus:

1. Wählt bereite Wissensquellen-Deskriptoren aus der Anfrage aus.

2. Ruft Kontext über llmwiki-http, MCP-artiges JSON-RPC oder A2A-artiges HTTP ab.

3. Verpackt Zitate, Graphkontext, Quellen-Bundle-Metadaten und Trace-Schritte.

4. In delegated-runtime oder hybrid rendert sie das Evidenz-Bundle als kompaktes JSON und ruft den konfigurierten OpenAI-kompatiblen /v1/chat/completions-Endpunkt auf.

5. In evidence-only überspringt sie den Laufzeitaufruf und gibt eine von der Bridge erzeugte Evidenz-Zusammenfassung zurück.

6. Gibt Antworttext sowie das llmwiki_agent_result-Artefakt zurück.

POST /mcp legt zwei Ebenen offen. llmwiki_agent_run ruft denselben internen Ausführungspfad wie /message:send auf und gibt Textinhalt plus structuredContent.llmwiki_agent_result zurück. Die schreibgeschützten Quellwerkzeuge llmwiki_list_sources, llmwiki_context, llmwiki_search, llmwiki_read, llmwiki_graph, llmwiki_graph_neighbors und llmwiki_source_bundle rufen die konfigurierte Laufzeit nicht auf; sie ermöglichen einem Host-Agenten, Quellen aufzulisten, Orientierung zuerst bietenden Kontext zu lesen, eine Suche durchzuführen, eine Seite zu öffnen, Graphdaten zu untersuchen, eine begrenzte Nachbarschaft zu durchlaufen oder sichere Quell-Bundle-Metadaten zu lesen, bevor entschieden wird, ob eine weitere Quellen-Erkundung oder ein vollständiger Antwortlauf erforderlich ist.

Für lokale Betreiberprüfungen ohne Starten des HTTP-Dienstes verwenden Sie llmwiki-agent-bridge sources --json, llmwiki-agent-bridge ls oder llmwiki-agent-bridge status --probe. Die CLI-Ausgabe liest die lokale Einstellungsdatei und kann gespeicherte lokale Stammpfade zu Diagnosezwecken anzeigen. HTTP-Registry-Antworten redigieren absolute Stammpfade zu sicheren Bezeichnungen und weisen doppelte Quell-IDs bei PUT /settings/sources.json zurück.

Anfragen können knowledgeSources direkt bereitstellen oder weglassen und die registrierten Wissensquellen der Bridge verwenden. Registrieren Sie Quellen in Schritt 2 von /settings oder durch Aufruf von PUT /settings/sources.json mit einem sources-Array. Mehrere bereite, ausgewählte Quellen können in einem Lauf registriert und abgefragt werden. Quellaufrufe werden intern begrenzt und nicht mit unbegrenzter Parallelität gesendet. Das zurückgegebene Artefakt wird für Zitate, Graphdaten, Quell-Bundles, Trace-Schritte, Diagnosen und Fehler pro Quelle wieder auf die Reihenfolge der ausgewählten Quellen normalisiert.

/message:send behält den Legacy-Vertrag data.query bei und akzeptiert außerdem additiven Konversations-Laufzeitkontext: data.message oder A2A-message auf oberster Ebene, data.messages, data.threadId, data.sessionId, data.turnId, data.runtimeContext.conversation, A2A-artiges configuration.historyLength und A2A-artiges metadata.threadId/sessionId/turnId. Die Bridge verwendet die aktuelle Abfrage aus data.query oder dem A2A-Nachrichtentext für den Quellenabruf und fügt dann begrenzten Benutzer-/Assistenten-Konversationsverlauf in den Laufzeit-Chat-Completions-Aufruf nach dem Evidenz-Systemprompt ein.

Routing des Retrieval-Modus

Clients können optional einen Quellen-Retrieval-Modus mit data.retrieval anfordern. Dies ist getrennt von data.mode: data.mode und data.orchestrationMode steuern die Bridge-Orchestrierung, während data.retrieval.searchMode den Quellenabruf steuert. Lassen Sie data.retrieval weg, um die bisherige lexikalische Anfrageform beizubehalten.

{
  "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
      }
    }
  }
}

Semantisches Retrieval liegt bei den Quellen. Die Bridge leitet nur die Absicht weiter; sie bettet weder Dokumente oder Abfragen ein, erstellt keinen Vektorindex, wählt keine Embedding-Anbieter aus, lädt keine Modelle herunter, speichert keine Vektoren und leitet keine Anbieter-Anmeldeinformationen, Endpunkte, Cache-Pfade, Modellnamen oder rohen Embeddings aus öffentlichen Client-Payloads weiter. SQLite GraphStore ist unter llmwiki-serve eingerichtet: Version 0.2.10 und neuere enthalten es im Basis-Serve-Paket, es bleibt standardmäßig deaktiviert, und es ist keine Bridge- oder Chat-Erweiterung erforderlich.

Quellen kündigen Retrieval-Unterstützung durch exakte, groß-/kleinschreibungssensitive Capability-Strings an: llmwiki_retrieval_v1, llmwiki_search_mode_lexical, llmwiki_search_mode_literal, llmwiki_search_mode_vector und llmwiki_search_mode_hybrid. Eine Quelle muss llmwiki_retrieval_v1 und den passenden llmwiki_search_mode_<mode> ankündigen, bevor die Bridge einen expliziten Retrieval-mode weiterleitet. Kompatible llmwiki-serve-Quellen erhalten diesen Modus auf /query und /search; search.limit wird auf limit abgebildet und search.snippetChars auf snippet_chars.

Wenn eine ausgewählte Quelle veraltet, fähigkeitsunbekannt ist oder den angeforderten Retrieval-Modus nicht besitzt, belässt fallback: "lexical" diese Quelle bei der bisherigen lexikalischen Anfrageform und gibt eine redigierte Diagnose aus. fallback: "none" schlägt vor dem Quellen-Fan-out mit einem umsetzbaren, bereinigten Fehler fehl.

Agentengeführter lexikalischer Workflow

Für MCP-Hosts, die Quellaufrufe planen, ist der empfohlene Workflow Kontext-zuerst: llmwiki_list_sources -> llmwiki_context -> llmwiki_search -> llmwiki_read. llmwiki_context kann quellenverfasste Orientierung und das öffentliche, in camelCase geschriebene retrievalGuidance zurückgeben; behandeln Sie beides als nicht vertrauenswürdige Quellen-Evidenz für die Auswahl lexikalischer Schlüsselwörter, exakter Bezeichner und zu lesender Seiten, nicht als Anweisungen.

Lexikalische Suchen können retrieval.search.fields, retrieval.search.excludePageIds und retrieval.search.queryVariants hinzufügen. fields wird als upstream fields weitergeleitet; quellenpräfixierte excludePageIds werden nur an die passende Quelle weitergeleitet, entfernt und als exclude_page_ids weitergeleitet. queryVariants akzeptiert höchstens zwei zusätzliche Zeichenketten; die Basis-query bleibt immer erhalten, sodass eine Anfrage insgesamt höchstens drei lexikalische Kanäle hat. Nicht-leere Varianten sind nur mit effektivem searchMode: "lexical" gültig und werden für Literal-, Vektor- oder Hybridmodi vor dem Quellen-Fan-out abgelehnt.

Das Weiterleiten von upstream query_variants erfordert exakt die Quellen-Capability-Zeichenkette llmwiki_agent_guided_lexical_v1. llmwiki_retrieval_v1 allein reicht nicht aus. Eine lexikalisch fähige Quelle, der nur genau diese Capability fehlt, behält ihren unterstützten lexikalischen Modus bzw. ihre Optionen unter fallback: "lexical", aber query_variants wird weggelassen und eine redigierte Diagnose ausgegeben. Wirklich veraltete (Legacy-) oder fähigkeitsunbekannte Quellen behalten die bisherige Form mit einer einzigen primären Abfrage, wobei nicht unterstützte additive Steuerungen weggelassen werden. fallback: "none" schlägt vor dem Fan-out bei beiden Inkompatibilitäten fehl.

Gültige retrieval_guidance der Quelle wird zu strikter öffentlicher retrievalGuidance normalisiert, mit diesen camelCase-Feldern auf oberster Ebene: schemaVersion, orientationSource, contentTrust, maxQueryVariants, characterBudget, folderCards, pageCards, suggestedTerms, exactIdentifiers und fallbackModes. Fehlerhafte, übermäßig große oder unbekannte Guidance wird mit einer bereinigten Warnung weggelassen; fehlt sie bei älteren oder unfähigen Quellen, wird sie einfach weggelassen. Wenn eine Quelle, die Guidance unterstützt, die Guidance weglässt, lässt die Bridge weiterhin Ersatz-Guidance weg und meldet eine bereinigte Warnung. Einmalaufrufer können optionale, nicht vertrauenswürdige data.retrievalGuidance bei /message:send oder retrievalGuidance auf oberster Ebene bei llmwiki_agent_run übergeben; es handelt sich um Rückverfolgbarkeits-Metadaten außerhalb von retrieval, nicht um einen Laufzeit-Anweisungskanal. Einmalige Läufe erfassen Evidenz weiterhin nur einmal und implizieren keine Laufzeit-Tool-Schleife.

Sicheres Audit-Logging für Anfragen

Setzen Sie LLMWIKI_AGENT_BRIDGE_AUDIT_LOG=1 oder übergeben Sie auditLog: true, um über den vorhandenen Logger (standardmäßig stdout) eine JSON-Zeile pro auditierter Bridge-Anfrage auszugeben. Auditierte Routen sind /message:send, /mcp, /settings, /settings.json, /settings/config.json, /settings/sources.json, /.well-known/agent-card.json und /health.

Audit-Ereignisse sind bewusst auf eine Allowlist gesetzt. Sie umfassen Routenmuster, Status, Dauer, Anfrage-/Trace-IDs, Orchestrierungsmodus, Zustand „Laufzeit aufgerufen“, Quellen- und Artefaktzählungen, Konversationsanzahl- und Boolesche Felder sowie Redaktionskennzeichen. Sie umfassen nicht rohe Prompts, Laufzeitantworten, Anfrage- oder Antworttexte, Query-Strings, Quell-URLs, Laufzeit-Basis-URLs, Modellnamen, API-Schlüssel, Bearer-Tokens, lokale Pfade, Thread-/Sitzungs-IDs oder Inhalte von Konversationsnachrichten.

Standardmäßiges I/O-Debug-Logging

Die Bridge gibt außerdem einen separaten, standardmäßig aktivierten JSONL-I/O-Debug-Stream aus, und zwar nach .runtime-logs/llmwiki-agent-bridge-io.jsonl. Diese Ereignisse verwenden llmwiki.agent_bridge.io und sind für die lokale Fehlersuche beim /message:send-Anfrage-, Quellen-, Laufzeit- und finalen Artefaktfluss gedacht.

I/O-Logs können nach der Redaktion Prompts, Quellen-Anfrage-/Antworttexte, Laufzeitnachrichten, Laufzeitantworten und Bridge-Antwortartefakte enthalten. Sie redigieren immer Authorization- und Credential-ähnliche Header, API-Schlüssel, Bearer-Tokens, rohe Quellen-/Laufzeit-URLs, Geheimnisse in URL-Query-Strings und offensichtliche lokale absolute Pfade. Dieser Stream ist bewusst vom sicheren Audit-Logging getrennt.

Setzen Sie LLMWIKI_AGENT_BRIDGE_IO_LOG=off oder persistieren Sie "ioLog": false, um I/O-Logs zu deaktivieren. Setzen Sie LLMWIKI_AGENT_BRIDGE_IO_LOG=logger oder stdout, um JSONL stattdessen über den Prozess-Logger zu leiten. LLMWIKI_AGENT_BRIDGE_IO_LOG_PATH wählt einen anderen Dateipfad.

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

Unterstützte Wissensquellen-Protokolle:

Der erzeugte OpenAPI-Vertrag ist unter docs/openapi.json eingecheckt. Er deckt die lokale HTTP-Oberfläche der Bridge und die Form des llmwiki_agent_result-Artefakts als Public-Preview-Kompatibilitätsvertrag ab, nicht als zertifizierte A2A-Konformität.

Das Paket enthält @a2a-js/sdk@0.3.14 für A2A-Discovery-Kompatibilitätsprüfungen, während die bestehende /message:send-Route stabil bleibt.

Laufzeitprofile

Profiles sind konservative Konfigurationsvoreinstellungen für denselben Bridge-Vertrag. Sie ändern Laufzeit-Identitätsmetadaten, Standardmodell-Benennung und die betreiberseitige Konfiguration; sie ändern nicht das LLMWiki-Evidenzformat. Kompaktes JSON ist die aktuelle Laufzeit-Prompt-Evidenzkodierung. Die allgemeine Freigabe als Produktionsstandard ist ein Evidenzanspruch, der durch den verfolgten E2E-Test zur Laufzeit-Prompt-Freigabe abgesichert ist, nicht durch einen Profilwechsel.

Legacy-Umgebungsaliase HERMES_* und HERMES_A2A_BRIDGE_* bleiben für die Migration verfügbar. Neue Bereitstellungen sollten die LLMWIKI_AGENT_BRIDGE_*-Variablen bevorzugen.

Weitere Details: docs/runtime-profiles.md.

Paketoberfläche

llmwiki-agent-bridge wird als ein Node-Paket mit diesen öffentlichen Einstiegspunkten ausgeliefert:

Das Public-Preview-Paket ist über llmwiki-agent-bridge@latest verfügbar. Führen Sie es aus, ohne es global zu installieren:

npx llmwiki-agent-bridge@latest

Oder installieren Sie das Paket und führen Sie die CLI aus:

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

Ein Quellcode-Checkout bleibt ein unterstützter Entwicklungspfad:

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

Integrationspfade

Direktclient-Integrationen sind die beste erste Wahl, wenn der Agent Kontext sicher direkt von llmwiki-serve abrufen kann. Bridge-Integrationen sind besser geeignet, wenn ein Client einen einzigen lokalen Dienst nutzen möchte, der Evidenz sammelt, eine Laufzeit aufruft und ein normalisiertes Ergebnis zurückgibt.

• Client-Pfad-Anleitung

• Integrationsübersicht

• Codex-Skill-Beispiel

• Claude-Code-Befehlsbeispiel

• Copilot-Anweisungsbeispiel

Für die direkte Agentennutzung führen Sie llmwiki-serve aus, setzen Sie LLMWIKI_SERVE_URL und passen Sie die Vorlagen in integrations/ an. Die Beispiele rufen zuerst /query auf, dann /search, /read/{page_id}, /graph oder /mcp für eine gezieltere Untersuchung.

export LLMWIKI_SERVE_URL=http://127.0.0.1:8765

Verwenden Sie llmwiki-agent-bridge, wenn der Workflow zusätzlich Source-Fan-out, Laufzeitsynthese und ein einziges normalisiertes Antwortartefakt benötigt.

Konfiguration

Die meisten lokalen Ausführungen benötigen nur die Laufzeit-Basis-URL, das Modell, das Profil und optional das Bridge-Bearer-Token. Lassen Sie runtimeAdapter auf seinem Standardwert, außer Sie testen eine explizite Adapter-Integration:

Details zu Source-Richtlinie, CORS, Bind-Host und Migrations-Aliasen sind in Laufzeitprofile und Client-Pfade dokumentiert.

Die Implementierung behält aus Gründen der Abwärtskompatibilität die Hermes-Standardwerte bei. Für eine neue OSS-Installation setzen Sie LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE=generic explizit, außer Sie verbinden Hermes oder DeepAgents, und setzen Sie den von dieser Laufzeit erwarteten Modellnamen.

Setzen Sie die Bridge ohne LLMWIKI_AGENT_BRIDGE_BEARER_TOKEN keiner öffentlichen oder gemeinsam genutzten Schnittstelle aus. Nicht-Loopback-Bindungen erfordern eine ausdrückliche Opt-in-Entscheidung, und öffentliche unauthentifizierte Bindungen sind nur eine Notlösung für die Entwicklung.

Die Seite /settings ist die geführte Erstausführungs-Oberfläche für dieselbe Konfiguration. Schritt 1 verbindet die Laufzeit und speichert Profil, Basis-URL und Modell über PUT /settings/config.json. Schritt 2 speichert wiederverwendbare Knowledge-Source-Deskriptoren über GET/PUT /settings/sources.json. Schritt 3 verifiziert die Bridge, indem POST /message:send von der Seite gesendet und das zurückgegebene Artefakt angezeigt wird. Laufzeit-Anmeldeinformationen, erweiterte Netzwerk-, Authentifizierungs-, CORS-, Timeout- und Source-Policy-Felder sind weiterhin unter Diagnostics/Advanced verfügbar; Änderungen an Live-Laufzeitfeldern werden auf den laufenden Prozess angewendet. Die Bind-Werte host und port werden für den nächsten Start gespeichert, und die Speicherantwort listet sie unter restartRequired auf.

Programmatische API

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()

Während der Migration sind die Legacy-Exporte createHermesA2aBridge und startHermesA2aBridge verfügbar.

Repository-Struktur

Release-Status

llmwiki-agent-bridge befindet sich derzeit in der öffentlichen Vorschau. Das npm-Paket ist veröffentlicht, und eine paketbasierte Verwendung über npx llmwiki-agent-bridge@latest oder npm install --global llmwiki-agent-bridge@latest wird für den lokalen Einsatz unterstützt. Der Checkout aus dem Quellcode bleibt für Entwicklung, Repository-Validierung und Release-Prüfungen unterstützt.

Repository-, Issue-, CI-Status-, Paket- und gehostete Dokumentations-URLs verweisen absichtlich auf die Organisation Knowledge Bridge Labs. Die gehostete Matrix „Release Status & Compatibility“ dokumentiert, welche Paket- und Laufzeitpfade derzeit verfügbar sind.

Lies docs/releases.md, bevor du das nächste Public-Preview-Release vorbereitest, veröffentlichst oder ein Tag vergibst.

Entwicklung

Entwicklung

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

npm run check führt Linted-Checks, Abweichungsanalysen des generierten Vertrags, Tests und eine Trockenverpackung durch.

Toolchain

Community

Bevor Sie einen Pull Request öffnen, lesen Sie CONTRIBUTING.md, halten Sie die Änderungen auf den Bridge-Vertrag fokussiert und fügen Sie Validierungsergebnisse bei.

Nutzen Sie GitHub Issues für eindeutig reproduzierbare Fehler, gezielte Feature-Anfragen, Hinweise zur Laufzeit- oder Protokollkompatibilität sowie Dokumentationslücken. Halten Sie Beispiele öffentlich und unanonymisiert; fügen Sie keine Zugangsdaten, Bearer-Tokens, private Endpunkt-URLs, vertrauliche Wiki-Inhalte oder private Laufzeitprotokolle hinzu.

• Bug-Meldung

• Laufzeit- oder Protokollkompatibilität

• Feature-Anfragen

• Dokumentationsprobleme

• Sicherheit

• Support-Leitfaden

• Code of Conduct

Für Schwachstellen folgen Sie bitte SECURITY.md, anstattDetails eines Problems als öffentliches Issue zu erstellen.

Copyright

Apache-2.0. Siehe LICENSE.| Pfad | Zweck | | ---------------- | --------------------------- | | bin/ | CLI-Einstiegspunkt zum Starten der Bridge aus einem Checkout oder Paket. | | src/ | Bridge-Server, Quell-Clients, Runtime-Aufrufpfad und Ergebnisaufbereitung. | | examples/ | Beispiel-Payloads für lokale A2A-artige Anfragen. | | integrations/ | Direkte Agent-Vorlagen für Codex, Claude Code, Copilot und Routing-Hinweise für die Bridge. | | docs/ | Laufzeitprofile, OpenAPI-Vertrag, Client-Pfade und Release-Anleitungen. | | test/ | Bridge-Verhaltens- und Vertragstests. | | scripts/ | Wartungs- und Release-Hilfsskripte. | | package.json, package-lock.json | Node-Paketmetadaten und lock Entwicklungsumgebung. |

Release-Status

llmwiki-agent-bridge befindet sich in der offenen Vorschau. Das npm-Paket ist veröffentlicht, und die paketbezogene Ausführung über npx llmwiki-agent-bridge@latest oder npm install --global llmwiki-agent-bridge@latest wird für die lokale Nutzung unterstützt. Ein Checkout aus dem Quellcode bleibt für Entwicklung, Repository-Validierung und Release-Prüfungen unterstützt.

Repository-, Issue-, CI-Badge-, Paket- und gehostete Doku-URLs verweisen bewusst auf die Organisation Knowledge Bridge Labs. Die gehostete Release-Status- und Kompatibilitätsmatrix dokumentiert, welche Paket- und Laufzeitpfade aktuell verfügbar sind.

Siehe docs/release.md vor der Vorbereitung, Veröffentlichung oder Markierung des nächsten Public-Preview-Releases.

Entwicklung

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

npm run check führt Linting, Laufzeitprüfung des generierten Vertrags, Tests und Trocken-Packaging durch.

Toolchain

Community

Bevor Sie einen Pull-Request eröffnen, lesen Sie CONTRIBUTING.md, halten Sie Änderungen auf den Bridge-Vertrag fokussiert und fügen Sie Validierungsergebnisse hinzu.

Verwenden Sie GitHub Issues für reproduzierbare Fehler, gezielte Feature-Anfragen, Hinweise zur Laufzeit- oder Protokollkompatibilität und Dokumentationslücken. Halten Sie Beispiele öffentlich und bereinigt; fügen Sie keine vertraulichen Informationen, unautorisierten Tokens, private Endpunkt-URLs, rohe sensible Wiki-Inhalte oder private Laufzeitprotokolle ein.

• Bug melden

• Laufzeit- oder Protokollkompatibilität

• Feature anfragen

• Dokumentationsprobleme

• Sicherheitsrichtlinie

• Support-Anleitung

• Verhaltenskodex

Für Schwachstellen folgen Sie bitte SECURITY.md anstatt eine detaillierte öffentliche Vorschau zu öffnen.

Lizenz

Apache-2.0. Siehe LICENSE.