llmwiki-agent-bridge

Actually no, we need mapping.

Let's extract all lines from user:

• Line "# LLMWiki Agent Bridge" (heading)

• Badges

• "llmwiki-agent-bridge is the optional source and fan-out and runtime..."

• Bullet list

• "Use it when:" list

• LLM her...

• "Skip it when..."

• "## Choose a Path"

• Table "| Path | Use when | Flow"

• "Direct templates..."

• "## Quick Start" list

• Requirements list

• "Terminal 1" section

• "### Terminal 1: source server" heading

• code GXP1

• "Terminal 2" heading

• code GXP2, GXP3

• "GXP4" etc

• "GXP5", "GXP6", "GXP7" etc

• "> For Hermes or ..., keep ..."

• "| Profile | Use ..." table

• "DeepAgents direct-provider integration..."

• "Leave the bridge running..."

• "Check the local surfaces:"

• code GXP8

• "For the first run..."

• "1. Connect runtime..."

• "2. Register..."

• "3. Verify Bridge..."

• "Runtime credentials..."

• "For no-runtime smoke..."

• "From an llmwiki-agent source checkout..."

• "GXP10"

• "The bundled examples/message.local.json points at ..."

• "GXP11"

• "MCP-style clients..."

• "Use llmwiki_agent_run..."

• "GXP12"

• "Omit knowledgeSources..."

• "GXP13"

• "The human-readable source list omits endpoint URLs..."

• "GXP14" ? Wait not all, there is "GXP15"?

• Need scan.

Actually user after "GXP1"? Let's scroll through user input:

Immediately after "GXP1" (Terminal 1) there is "### Terminal 2: bridge", then GXP2, GXP3, etc. After the JSON "ready" paragraph, "GXP5". Then "For runtime-backed answer synthesis..." GXP6 GXP7 etc. "For Hermes..." LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE model name table with generic hermes deepagents rows. Then large "DeepAgents direct-provider integration..." paragraph. Then "Leave the bridge running..." etc. Then code "GXP8" for local surface? Then "First run" etc. Then GXP9? Actually after "local surface:" maybe a code block "GXP8". Need map.

Let's map from source exactly from top after the "## Choose a Path" table:

The table has three columns: "| Path | Use when |". Then "Flow".

Source:

"templates live in integrations. The bridge request and artifact contract is documented in docs/message-send-contract.md and generated as docs/openapi.json."

Need translate.

Then "## Quick Start" block, headings, etc. Good.

Need decide "Skip it when..." etc.

The first part "CLI writes JSON ready event" maybe after code? Actually after GXP1 there is "The CLI writes a JSON ready event..." no code? Actually "GXP1" followed by "The CLI writes a JSON ready event when the bridge is listening:" then code "GXP2"? Let's not invent. The source code after GXP1 includes:

Для каждого запроса POST /message:send мост:

1. Выбирает из запроса дескрипторы готовых источников знаний.

2. Получает контекст через llmwiki-http, JSON-RPC в стиле MCP или HTTP в стиле A2A.

3. Упаковывает цитаты, графовый контекст, метаданные пакета источников и шаги трассировки.

4. В режиме delegated-runtime или hybrid преобразует набор доказательств в компактный JSON и вызывает настроенную конечную точку /v1/chat/completions, совместимую с OpenAI.

5. В режиме evidence-only пропускает вызов среды выполнения и возвращает сводку доказательств, сформированную мостом.

6. Возвращает текст ответа и артефакт llmwiki_agent_result.

POST /mcp предоставляет два уровня. llmwiki_agent_run использует тот же внутренний путь выполнения, что и /message:send, и возвращает текстовое содержимое вместе с structuredContent.llmwiki_agent_result. Инструменты источников только для чтения llmwiki_list_sources, llmwiki_context, llmwiki_search, llmwiki_read, llmwiki_graph, llmwiki_graph_neighbors и llmwiki_source_bundle не вызывают настроенную среду выполнения; они позволяют агенту-хосту перечислить источники, прочитать контекст с приоритетом ориентации, выполнить поиск, открыть страницу, изучить графовые данные, обойти ограниченную окрестность или прочитать безопасные метаданные пакета источников, прежде чем решить, нужно ли дальнейшее исследование источников или полный запуск ответа.

Для локальных проверок оператором без запуска HTTP-сервиса используйте llmwiki-agent-bridge sources --json, llmwiki-agent-bridge ls или llmwiki-agent-bridge status --probe. Вывод CLI читает локальный файл настроек и может показывать сохранённые локальные корневые пути для диагностики. Ответы HTTP-реестра заменяют абсолютные корневые пути безопасными метками и отклоняют дублирующиеся идентификаторы источников при PUT /settings/sources.json.

Запросы могут передавать knowledgeSources напрямую либо опускать их и использовать зарегистрированные в мосте источники знаний. Зарегистрируйте источники на шаге 2 в /settings или вызвав PUT /settings/sources.json с массивом sources. Несколько готовых выбранных источников можно зарегистрировать и опросить за один запуск. Вызовы источников ограничиваются внутренне, а не отправляются с неограниченным параллелизмом. Возвращаемый артефакт нормализуется обратно к порядку выбранных источников для цитат, графовых данных, пакетов источников, шагов трассировки, диагностики и сбоев по каждому источнику.

/message:send сохраняет прежний контракт data.query, а также принимает дополнительный контекст разговора для среды выполнения: data.message или message верхнего уровня в стиле A2A, data.messages, data.threadId, data.sessionId, data.turnId, data.runtimeContext.conversation, configuration.historyLength в стиле A2A и metadata.threadId/sessionId/turnId в стиле A2A. Мост использует текущий запрос из data.query или текст сообщения A2A для поиска по источникам, а затем включает ограниченную историю разговора пользователя/ассистента в вызов chat-completions среды выполнения после системного промпта с доказательствами.

Маршрутизация режима поиска

Клиенты могут дополнительно запросить режим поиска по источникам с помощью data.retrieval. Это отдельно от data.mode: data.mode и data.orchestrationMode управляют оркестрацией моста, а data.retrieval.searchMode управляет поиском по источникам. Опустите data.retrieval, чтобы сохранить прежнюю лексическую форму запроса.

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

Семантический поиск принадлежит источникам. Мост маршрутизирует только намерение; он не создаёт эмбеддинги документов или запросов, не строит векторный индекс, не выбирает провайдеров эмбеддингов, не загружает модели, не хранит векторы и не передаёт учётные данные провайдеров, конечные точки, пути кэша, названия моделей или исходные эмбеддинги из публичных полезных нагрузок клиентов. SQLite GraphStore настраивается на llmwiki-serve: версия 0.2.10 и новее включает его в базовый пакет serve, он остаётся выключенным по умолчанию, и не требуется никаких дополнительных модулей моста или чата.

Источники сообщают о поддержке поиска точными строками возможностей с учётом регистра: llmwiki_retrieval_v1, llmwiki_search_mode_lexical, llmwiki_search_mode_literal, llmwiki_search_mode_vector и llmwiki_search_mode_hybrid. Источник должен сообщить llmwiki_retrieval_v1 и соответствующую llmwiki_search_mode_<mode>, прежде чем мост передаст явный режим mode поиска. Совместимые источники llmwiki-serve получают этот режим на /query и /search; search.limit сопоставляется с limit, а search.snippetChars — с snippet_chars.

Если выбранный источник является устаревшим, с неизвестными возможностями или не поддерживает запрошенный режим поиска, fallback: "lexical" оставляет этот источник на прежней лексической форме запроса и выдаёт диагностику без конфиденциальных данных. fallback: "none" завершается ошибкой до разветвления по источникам с понятным очищенным сообщением об ошибке.

Лексический рабочий процесс под руководством агента

Для MCP-хостов, планирующих вызовы источников, рекомендуется подход «сначала контекст»: llmwiki_list_sources -> llmwiki_context -> llmwiki_search -> llmwiki_read. llmwiki_context может возвращать ориентацию, созданную источником, и публичный retrievalGuidance в camelCase; относитесь к обоим как к недоверенным данным источника для выбора лексических ключевых слов, точных идентификаторов и страниц для чтения, а не как к инструкциям.

Лексические поиски могут добавлять retrieval.search.fields, retrieval.search.excludePageIds и retrieval.search.queryVariants. fields передаётся дальше как fields вышестоящей системе; excludePageIds с префиксом источника направляются только соответствующему источнику, очищаются от префикса и передаются как exclude_page_ids. queryVariants принимает не более двух дополнительных строк; базовый query всегда сохраняется, поэтому всего в запросе может быть не более трёх лексических каналов. Непустые варианты допустимы только с эффективным searchMode: "lexical" и отклоняются для режимов literal, vector или hybrid до разветвления по источникам.

Передача query_variants в вышестоящую систему требует точной строки возможности источника llmwiki_agent_guided_lexical_v1. Одного llmwiki_retrieval_v1 недостаточно. Источник, поддерживающий лексику, но не имеющий только этой точной возможности, сохраняет свой поддерживаемый лексический режим/параметры при fallback: "lexical", но query_variants опускается, и выдаётся диагностика без конфиденциальных данных. Действительно устаревшие источники или источники с неизвестными возможностями сохраняют прежнюю форму с одним основным запросом, а неподдерживаемые дополнительные элементы управления опускаются. fallback: "none" завершается ошибкой до разветвления при любой из этих несовместимостей.

Действительный retrieval_guidance источника нормализуется в строгий публичный retrievalGuidance со следующими полями верхнего уровня в camelCase: schemaVersion, orientationSource, contentTrust, maxQueryVariants, characterBudget, folderCards, pageCards, suggestedTerms, exactIdentifiers и fallbackModes. Некорректные, слишком большие или неизвестные рекомендации опускаются с очищенным предупреждением; их отсутствие у старых или неспособных источников просто опускается. Если источник с поддержкой рекомендаций опускает рекомендации, мост также не добавляет заменяющие рекомендации и сообщает очищенное предупреждение. Вызывающие код в один проход могут передать необязательный недоверенный data.retrievalGuidance в /message:send или retrievalGuidance верхнего уровня в llmwiki_agent_run; это метаданные трассируемости вне retrieval, а не канал инструкций для среды выполнения. Однопроходные запуски по-прежнему собирают доказательства один раз и не подразумевают цикл инструментов среды выполнения.

Безопасное журналирование аудита запросов

Установите LLMWIKI_AGENT_BRIDGE_AUDIT_LOG=1 или передайте auditLog: true, чтобы выводить по одной JSON-строке на каждый проверяемый запрос к мосту через существующий регистратор (по умолчанию stdout). Проверяемые маршруты: /message:send, /mcp, /settings, /settings.json, /settings/config.json, /settings/sources.json, /.well-known/agent-card.json и /health.

События аудита намеренно включены в разрешённый список. Они включают шаблоны маршрутов, статус, длительность, идентификаторы запросов/трассировок, режим оркестрации, признак вызова среды выполнения, количество источников и артефактов, счётчики/булевы поля разговора и флаги редактирования. Они не включают исходные промпты, ответы среды выполнения, тела запросов или ответов, строки запроса, URL-адреса источников, базовые URL-адреса среды выполнения, названия моделей, ключи API, токены bearer, локальные пути, идентификаторы потоков/сессий или содержимое сообщений разговора.

Журналирование отладки ввода-вывода по умолчанию

Мост также по умолчанию выводит отдельный JSONL-поток отладки ввода-вывода в .runtime-logs/llmwiki-agent-bridge-io.jsonl. Эти события используют llmwiki.agent_bridge.io и предназначены для локального устранения неполадок потока запроса /message:send, источников, среды выполнения и итогового артефакта.

Журналы ввода-вывода могут включать промпты, тела запросов/ответов источников, сообщения среды выполнения, ответы среды выполнения и артефакты ответов моста после редактирования. Они всегда удаляют заголовки Authorization и похожие на учётные данные заголовки, ключи API, токены bearer, исходные URL-адреса источников/среды выполнения, секреты в URL-запросах и очевидные локальные абсолютные пути. Этот поток намеренно отделён от безопасного журналирования аудита.

Установите LLMWIKI_AGENT_BRIDGE_IO_LOG=off или сохраните "ioLog": false, чтобы отключить журналы ввода-вывода. Установите LLMWIKI_AGENT_BRIDGE_IO_LOG=logger или stdout, чтобы направлять JSONL через регистратор процесса. LLMWIKI_AGENT_BRIDGE_IO_LOG_PATH выбирает другой путь к файлу.

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

Поддерживаемые протоколы источников знаний:

Сгенерированный контракт OpenAPI зафиксирован в docs/openapi.json. Он описывает локальную HTTP-поверхность моста и форму артефакта llmwiki_agent_result как контракт совместимости для публичного предварительного просмотра, а не как сертифицированное соответствие A2A.

Пакет включает @a2a-js/sdk@0.3.14 для проверок совместимости обнаружения A2A, сохраняя при этом стабильным существующий маршрут /message:send.

Профили среды выполнения

Профили — это консервативные пресеты конфигурации поверх одного и того же контракта моста. Они меняют метаданные идентификации рантайма, задание имени модели по умолчанию и конфигурацию, обращённую к оператору; они не меняют формат доказательств LLMWiki. Компактный JSON — текущая кодировка доказательств промптов рантайма. Шкальное одобрение продакшн-дефолта — это утверждение о доказательствах, которое контролируется отслеживаемым e2e-покрытием одобрения промптов рантайма, а не переключателем профиля.

Устаревшие алиасы переменных окружения HERMES_* и HERMES_A2A_BRIDGE_* остаются доступны для миграции. В новых развёртываниях следует предпочитать переменные LLMWIKI_AGENT_BRIDGE_*.

Подробнее: docs/runtime-profiles.md.

Related MCP server: A2ABench

Внешняя поверхность пакета

llmwiki-agent-bridge поставляется как один Node-пакет со следующими публичными точками входа:

Пакет публичной предварительной версии доступен через llmwiki-agent-bridge@latest. Запустите его без глобальной установки:

npx llmwiki-agent-bridge@latest

Или установите пакет и запустите CLI:

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

Локальная копия исходников остаётся поддерживаемым вариантом разработки:

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

Пути интеграции

Для прямых клиентских интеграций лучше всего подходит вариант, когда агент может безопасно получать контекст напрямую из llmwiki-serve. Мостовые интеграции подходят лучше, когда клиенту нужен один локальный сервис, который собирает доказательства, вызывает рантайм и возвращает нормализованный результат.

• Руководство по клиентским путям

• Обзор интеграций

• Пример навыка Codex

• Пример команды Claude Code

• Пример инструкций для Copilot

Для прямого использования агента запустите llmwiki-serve, задайте LLMWIKI_SERVE_URL и адаптируйте шаблоны в local каталоге integrations/. В примерах first вызывается /query, затем /search, /read/{page_id}, /graph или /mcp для более детального просмотра.

export LLMWIKI_SERVE_URL=http://127.0.0.1:8765

GXmpне, когда рабочему процессу также нужны source fan-out`, Ggle Д.{{??} runtime реагирование и единый нормализованный артефакт ответа.

Конфигурация

Для большинства локальных запусков достаточно указать базовый URL рантайма, имя модели, профиль и, optionally, bearer-токен моста. Держите runtimeAdapter по умолчанию, если вы не тестируете интеграцию с явным адаптером:

Сведения о политике источников, CORS, bind-host`и алиасах миграции описаны в профилях рантайма и клиентских путях.

Реализация сохраняет настройки по умолчанию Hermes для обратной совместимости. Для новой установки OSS явно задайте LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE=generic, если вы не работаете с Hermes или DeepAgents, и укажите имя модели, ожидаемое этим рантаймом.

Не открывайте мост на публичном или общем интерфейсе без LLMWIKI_AGENT_BRIDGE_BEARER_TOKEN. Привязка к не-loopback-интерфейсу требует явного согласия; публичные привязки без аутентификации — это запасной вариант, допустимый только при разработке.

Страница /settings — это пошаговый интерфейс первого запуска поверх той же конфигурации. Шаг 1 подключает рантайм и сохраняет профиль, базовый URL и модель через PUT /settings/config.json. Шаг 2 сохраняет переиспользуемые де финиции источников знаний через GET/PUT /settings/sources.json. Шаг 3 проверяет мост, отправляя POST /message:send прямо со страницы и показывая возвращённый артефакт. Поля учётных данных рантайма, дополнительной сетевой конфигурации, аутентификации, CORS, таймаута и политики источников по-прежнему доступны в разделах диагностики и расширенных настроек; изменения живых полей рантайма применяются к запущенному процессу. Значения host и port сохраняются для следующего запуска, и ответ после сохранения перечисляет их в поле restartRequired.

Программный 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()

Устаревшие экспорты createHermesA2aBridge и startHermesA2aBristleBridge доступны на время миграции.

Структура репозитория

Статус выпуска

llmwiki-agent-bridge находится в публичной предварительной версии. Пакет npm опубликован, и поддерживаются запуски на основе пакета npx llmwiki-agent-bridge@latest или npm install --global llmwiki-agent-bridge@latest для локального использования. Работа из локальной копии репозитория по-прежнему поддерживается для разработки, проверки репозитория и проверок выпуска.

URL-адреса репозитория, issue, бейджа CI, пакета и размещённой документации намеренно указывают на организацию Knowledge Bridge Labs. Размещённая матрица Release Status & Compatibility фиксирует, какие пакеты и пути среды выполнения доступны в настоящее время.

См. docs/release.md перед подготовкой, публикацией или тегированием следующего выпуска публичной предварительной версии.

Разработка

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

npm run check запускает lint, проверки расхождений сгенерированного контракта, тесты и пробную упаковку.

Инструментарий

Сообщество

Перед открытием pull request прочитайте CONTRIBUTING.md, сосредоточьте изменения на контракте моста и включите результаты проверки.

Используйте GitHub issues для воспроизводимых ошибок, точечных запросов функций, заметок о совместимости среды выполнения или протокола и пробелов в документации. Держите примеры публичными и очищенными; не включайте учётные данные, bearer-токены, частные URL-адреса конечных точек, необработанное чувствительное содержимое вики или частные журналы среды выполнения.

• Сообщения об ошибках

• Совместимость среды выполнения или протокола

• Запросы новых функций

• Проблемы с документацией

• Политика безопасности

• Руководство по поддержке

• Кодекс поведения

Для уязвимостей следуйте SECURITY.md, а не открывайте подробный публичный issue.

Лицензия

Apache-2.0. См. LICENSE.