Документация разработчика демона

Это техническая документация для разработчиков, касающаяся режима демона qwen-code: HTTP-демон qwen serve, пакет @qwen-code/acp-bridge, пул транспортов MCP с привязкой к рабочей области, посредничество разрешений для нескольких клиентов, типизированная схема событий демона v1, клиент демона TypeScript SDK и адаптеры, подключающиеся к демону.

Она дополняет (но не заменяет) следующие существующие документы:

Существующий документ	Аудитория	Источник истины для
`../../users/qwen-serve.md`	Операторы	Быстрый старт пользователя, флаги, модель угроз
`../qwen-serve-protocol.md`	Реализаторы протокола	Каталог HTTP-маршрутов, формы запросов/ответов, коды ошибок
`../examples/daemon-client-quickstart.md`	Пользователи SDK	Сквозной пример на TypeScript
`../daemon-client-adapters/`	Авторы адаптеров	Документация по проектированию адаптеров для старых клиентов
`14-cli-tui-adapter.md`	Авторы адаптеров	Заметки по проектированию клиентского адаптера
`../../design/f2-mcp-transport-pool.md`	Разработчики F2	Дизайн пула транспортов MCP для рабочей области v2.2

Если вы хотите запустить демон и использовать его, сначала прочитайте qwen-serve.md. Если вы хотите создать клиент для работы с протоколом, прочитайте qwen-serve-protocol.md. Если вы хотите понять, расширить или отладить внутренности демона, читайте этот набор.

Порядок чтения

Выберите путь, соответствующий вашей цели:

Сначала запустить и проверить демон: 20 -> 17 -> 19.
Новый участник: 01 -> 02 -> 03 -> 08 -> 09 -> 10 -> 11 -> 12.
Добавление нового клиентского адаптера: 01 -> 09 -> 10 -> 13 -> (14 / 15 / 16).
Работа над пулом MCP или бюджетом: 01 -> 03 -> 05 -> 06.
Работа над разрешениями: 01 -> 03 -> 04 -> 12.
Отладка демона в продакшене: 19 -> 18 -> 17 -> 20.

Набор документов

Основы

01-architecture.md — архитектура системы, топология процессов, карта пакетов и все семь диаграмм последовательности верхнего уровня.

Ядро сервера

02-serve-runtime.md — загрузка runQwenServe, приложение Express, цепочка middleware, корректное завершение работы.
03-acp-bridge.md — внутренности пакета @qwen-code/acp-bridge, мультиплексирование сессий, фабрика каналов, порождение дочерних процессов ACP.
04-permission-mediation.md — MultiClientPermissionMediator, четыре политики, инвариант таймаута N1, сторожевой сигнал отмены.
05-mcp-transport-pool.md — McpTransportPool (F2), записи пула, обратный индекс, перезапуск, слив.
06-mcp-budget-guardrails.md — WorkspaceMcpBudget, режимы (off/warn/enforce), гистерезис, группировка отклонённых пакетов.
07-workspace-filesystem.md — изолированная среда WorkspaceFileSystem, политика путей, аудит, контракт BridgeFileSystem.
08-session-lifecycle.md — создание / прикрепление / загрузка / возобновление, X-Qwen-Client-Id, пульс, вытеснение, метаданные.
09-event-schema.md — типизированная схема событий v1: все 43 известных типа событий с нагрузками, редьюсеры, обратная совместимость.
10-event-bus.md — EventBus, монотонные идентификаторы, кольцевой повтор, Last-Event-ID, противодавление от медленных клиентов, client_evicted.
11-capabilities-versioning.md — реестр возможностей, версия протокола, версия схемы, условная реклама.
12-auth-security.md — middleware на основе bearer, белый список хостов, запрет CORS, шлюз изменений, --require-auth, исключение /health, поток устройства.

Клиенты

13-sdk-daemon-client.md — TypeScript SDK: DaemonClient, DaemonSessionClient, DaemonAuthFlow, парсер SSE, редьюсеры событий, слой транскрипции ui/*.
14-cli-tui-adapter.md — общий слой транскрипции пользовательского интерфейса и связь с адаптером демона для интерфейса командной строки TUI.
15-channel-adapters.md — общая база DaemonChannelBridge плюс адаптеры для отдельных каналов: DingTalk, WeChat (Weixin), Telegram, Feishu.
16-vscode-ide-adapter.md — DaemonIdeConnection, принудительное использование только локальной петли, мост через webview.

Справочные приложения

17-configuration.md — переменные окружения, флаги командной строки, ключи settings.json, влияющие на демон.
18-error-taxonomy.md — типизированные ошибки по слоям с рекомендациями по устранению.
19-observability.md — QWEN_SERVE_DEBUG, рецепты отладки, пробелы в телеметрии.
20-quickstart-operations.md — самый короткий путь запуска, проверки через curl, карта маршрутов и встроенные рецепты вызова.

Глоссарий

ACP — Agent Client Protocol. JSON-RPC через stdio между мостом демона и дочерним процессом ACP. Это не HTTP-протокол, который клиенты используют для связи с демоном.
Дочерний процесс ACP — дочерний процесс, порождаемый демоном (qwen --acp), в котором выполняется фактическая среда агента. Мост мультиплексирует один дочерний процесс ACP между множеством подключённых клиентов.
acp-bridge — пакет @qwen-code/acp-bridge (packages/acp-bridge/). Отвечает за мультиплексирование сессий, посредника разрешений, шину событий и фабрику каналов.
BridgeClient — packages/acp-bridge/src/bridgeClient.ts. Оборачивает одно ClientSideConnection ACP, обрабатывает requestPermission, sendPrompt и cancelSession.
Фабрика каналов — подключаемая стратегия для порождения или подключения к дочернему процессу ACP. Реализация по умолчанию spawnChannel запускает qwen --acp как подпроцесс; inMemoryChannel выполняет его в том же процессе для тестов.
DaemonClient — packages/sdk-typescript/src/daemon/DaemonClient.ts. HTTP-обёртка TypeScript SDK для демона.
DaemonSessionClient — packages/sdk-typescript/src/daemon/DaemonSessionClient.ts. Обёртка с областью сессии, отслеживающая lastSeenEventId для повтора событий SSE.
EventBus — packages/acp-bridge/src/eventBus.ts. Постоянная в памяти подписка/публикация для каждой сессии с монотонными идентификаторами, ограниченным кольцевым буфером и противодавлением для каждого подписчика.
F1 / F2 / F3 / F4 — внутренние этапы, отслеживаемые в #4175 . F1: извлечение моста и BridgeFileSystem. F2: пул транспорта MCP с областью рабочей области. F3: посредничество разрешений для нескольких клиентов. F4: завершение протокола и внешние интерфейсы клиента демона.
MCP — Model Context Protocol. Серверы предоставляют инструменты, ресурсы и подсказки; дочерний процесс ACP демона подключается к ним.
McpTransportPool — packages/core/src/tools/mcp-transport-pool.ts. Пул с областью рабочей области F2, разделяющий один транспорт MCP на имя сервера и отпечаток конфигурации.
Политика посредника — одна из first-responder, designated, consensus или local-only. Определяет, как разрешаются голоса за разрешения от нескольких клиентов.
Идентификатор клиента-инициатора — X-Qwen-Client-Id клиента, инициировавшего подсказку, для которой запрашивается разрешение. Политика designated принимает голоса только от этого идентификатора.
PoolEntry — packages/core/src/tools/mcp-pool-entry.ts. Одна запись в McpTransportPool: один транспорт MCP, счётчик ссылок прикреплённых сессий и таймер сброса в режиме ожидания.
Область сессии — single (одна сессия ACP, разделяемая всеми клиентами) или thread (одна сессия на цепочку разговора). По умолчанию single.
SSE — Server-Sent Events. Исходящий канал событий демона (GET /session/:id/events).
Рабочая область — каталог, к которому был привязан демон при запуске (--workspace или cwd). Один процесс демона = одна рабочая область.

Исходные точки привязки реализации

Используйте эти привязки при переходе от документации к последнему коду main:

Поверхность	Точки привязки реализации	Основная документация
Загрузка и сборка HTTP	`packages/cli/src/serve/run-qwen-serve.ts`, `server.ts`, `/demo`	`02`, `20`
Мост ACP и мультиплексирование сессий	`packages/acp-bridge/src/bridge.ts`, `packages/acp-bridge/src/bridgeTypes.ts`, `@qwen-code/acp-bridge`	`03`, `08`
Посредничество разрешений	`packages/acp-bridge/src/permissionMediator.ts`, `fromLoopback: boolean`, `policy.*`	`04`, `12`
Пул транспорта MCP	`packages/core/src/tools/mcp-transport-pool.ts`, `mcp-pool-key.ts`, `pid-descendants.ts`, `session-mcp-view.ts`, `/mcp refresh`, `MCPCallInterruptedError`	`05`, `06`
Ограничители бюджета MCP	`packages/core/src/tools/mcp-workspace-budget.ts`, `ServeMcpBudgetStatusCell.scope`, `budgets[]`	`06`
Файловая система рабочей области	`packages/cli/src/serve/fs/`, `assertTrustedForIntent(trusted, intent)`, `meta.matchedIgnore`, `includeIgnored`	`07`
Схема событий и запись SSE	`packages/sdk-typescript/src/daemon/events.ts`, `packages/cli/src/serve/server.ts`, `formatSseFrame`, `packages/cli/src/acp-integration/session/emitters/ToolCallEmitter.ts`, `ToolCallEmitter.resolveToolProvenance`, `tool_call.provenance`, `serverId`	`09`, `10`
Повторная синхронизация событий	`state_resync_required`, `awaitingResync`, `RESYNC_PASSTHROUGH_TYPES`, `asKnownDaemonEvent`, `unrecognizedKnownEventCount`	`09`, `10`
Возможности	`packages/cli/src/serve/capabilities.ts`, `mcp_server_restart_refused.reason`, `MCP_RESTART_REFUSED_REASONS.has`	`11`
Аутентификация и поток устройств	`packages/cli/src/serve/auth.ts`, `packages/cli/src/serve/auth/device-flow.ts`	`12`
Клиент демона TypeScript SDK	`packages/sdk-typescript/src/daemon/{DaemonClient,DaemonSessionClient,DaemonAuthFlow,sse,events,types}.ts`, `MCP_RESTART_DEFAULT_TIMEOUT_MS`	`13`
Уровень транскрипции общего UI	`DaemonUiEventType`, `DaemonSessionProvider`, `packages/webui/src/daemon/`	`13`, `14`, `../daemon-ui/README.md`
Каналы и адаптеры IDE	`packages/channels/`, `packages/vscode-ide-companion/src/services/daemonIdeConnection.ts`	`15`, `16`

Что намеренно выходит за рамки

Java / Python SDK daemon clients — на данный момент только TypeScript SDK поставляется с демон-клиентом. Doc 13 предназначен только для TypeScript.
Web UI product details — общий слой транскриптов и точки входа демона веб-интерфейса описаны здесь, но макет пользовательского интерфейса продукта отслеживается в docs/developers/daemon-ui/ и заметках по дизайну адаптеров.
Zed extension (packages/zed-extension/) — он запускает qwen --acp напрямую через stdio и обходит демон.
Experimental in-process hosting — --no-http-bridge по-прежнему возвращается к http-bridge; стабильный режим встраиваемого сервера потребует новой документации при его внедрении.

Текущее покрытие режима демона

Покрытие ядра сервера

Область	Текущее состояние	Основные документы
Загрузка / путь прослушивания	`qwen serve` лениво загружает `runQwenServe`, проверяет auth/workspace/budget/settings, собирает Express-приложение, затем вызывает `app.listen` и блокируется до сигнала.	`02`, `20`
Аутентификация / сетевые ограничения	Loopback по умолчанию не требует bearer; non-loopback требует bearer; `--require-auth` расширяет bearer на loopback и `/health`; активно работает белый список хостов и запрет CORS по умолчанию.	`12`, `17`
Жизненный цикл сессии	Документированы: `POST /session`, `load`, `resume`, патч метаданных, heartbeat, вытеснение, очистка бездействующих сессий, лимиты ожидающих запросов и корректное закрытие.	`08`, `10`
Мост ACP	Один дочерний процесс ACP мультиплексируется по умолчанию; `sessionScope` поддерживает `single` и `thread`; подключены `BridgeFileSystem`, контекстное имя файла, переменные окружения и таймаут бездействия канала.	`03`, `07`
Пул MCP / бюджет	Пул MCP рабочего пространства включён по умолчанию, если только не установлено `QWEN_SERVE_NO_MCP_POOL=1`; документированы события защиты и семантика перезапуска.	`05`, `06`
Разрешения	Медиатор F3 поддерживает `first-responder`, `designated`, `consensus` и `local-only`; недопустимые настройки явно завершаются ошибкой.	`04`, `12`

Проводной протокол

Область	Текущее состояние	Основные документы
HTTP-маршруты	Каталог маршрутов находится в `qwen-serve-protocol.md`; данный набор демонов только ссылается на него и объясняет принадлежность реализации.	`../qwen-serve-protocol.md`, `20`
Схема событий	`EVENT_SCHEMA_VERSION = 1`; 43 известных типа событий; синтетические фреймы подписчиков без идентификатора; `_meta.serverTimestamp` проставляется при записи SSE.	`09`, `10`
Возможности	`SERVE_PROTOCOL_VERSION = 'v1'`; 67 зарегистрированных тегов; 10 условных тегов.	`11`
Оболочка сессии	`POST /session/:id/shell` существует за флагами `--enable-session-shell`, bearer-аутентификацией и привязанным к сессии `X-Qwen-Client-Id`; тег возможности является условным.	`11`, `17`, `20`
Ограничение скорости	Опциональное поуровневое HTTP-ограничение скорости задаётся флагами CLI/переменными окружения и условным тегом возможности.	`11`, `17`

Клиенты / SDK

Область	Текущее состояние	Основные документы
Демон-клиент TypeScript SDK	Документированы: `DaemonClient`, `DaemonSessionClient`, `DaemonAuthFlow`, парсер SSE, редукторы событий, предварительная проверка возможностей и экспорт транскриптов UI.	`13`
Общий слой транскриптов UI	SDK `daemon/ui/*` нормализует события демона в 37 семантических типов событий UI, сводит их в блоки транскриптов и предоставляет рендереры/вспомогательные средства проверки соответствия.	`14`, `../daemon-ui/README.md`, `../daemon-ui/MIGRATION.md`
Потребитель демона веб-интерфейса	`packages/webui/src/daemon/` потребляет хранилище транскриптов SDK через React-провайдеры и адаптеры.	`14`, `../daemon-client-adapters/web-ui.md`
CLI TUI / каналы / VS Code	Устаревшие пути всё ещё существуют; миграция на общие примитивы транскриптов задокументирована как последующая работа, а не завершённое поведение.	`14`, `15`, `16`

Справочная информация и операции

Область	Текущее состояние	Основная документация
Конфигурация	Полные флаги `qwen serve`, переменные окружения, `settings.json`, `ServeOptions`, `BridgeOptions` и важные константы собраны на одной странице.	`17`
Быстрый старт / операции	Кратчайший путь запуска, рецепты запуска, проверки через curl, поведение аутентификации на демо-странице, разделение маршрутов, поведение завершения и рецепты встроенного вызова рассмотрены.	`20`
Ошибки	Критические ошибки при запуске, ошибки маршрутов, ошибки моста, ошибки EventBus, ошибки файловой системы и ошибки медиатора сведены с рекомендациями по устранению.	`18`
Наблюдаемость	`QWEN_SERVE_DEBUG`, рецепты curl, полезные события, пробелы в телеметрии и чек-листы для расследования задокументированы.	`19`

Устаревшие или исторические поверхности

Поверхность	Статус
`docs/developers/daemon-client-adapters/tui.md`	Исторический черновик старого прототипа `DaemonTuiAdapter`; текущая архитектура общего UI-транскрипта описана в документе 14.
`packages/cli/src/ui/daemon/daemon-tui-adapter.ts`	Унаследованный экспериментальный адаптер, всё ещё в дереве. Новая общая работа с UI должна предпочитать SDK `daemon/ui/*`.
`--no-http-bridge`	Принимается для совместимости, но откатывается к http-bridge и выводит сообщение в stderr.

Прямая совместимость

Схема событий v1 является аддитивной. Новые известные типы событий должны добавляться в DAEMON_KNOWN_EVENT_TYPE_VALUES; старые SDK должны обрабатывать неизвестные типы как совместимые вперёд.
Теги возможностей (capability tags) являются контрактами поведения. Для нового поведения требуется новый тег, особенно если клиенты могут проверять его наличие перед вызовом маршрута.
sessionScope: 'thread' — текущее разделение по цепочкам разговоров; избегайте повторного использования более старой терминологии с областью клиента.
Envelope _meta и полезная нагрузка ACP data._meta различаются. Происхождение вызова инструментов находится в полезной нагрузке ACP; временные метки отправки сервера — на обёртке SSE.

Происхождение версии

Набор документов отражает текущую поверхность режима демона, объединённую в main, включая последующую работу из #4412 . В нём намеренно описывается текущее поведение, а не более ранние плановые снимки серии F.