Среда выполнения Serve

Обзор

packages/cli/src/serve/ — это загрузочный слой для qwen serve. Он преобразует флаги CLI в ServeOptions, проверяет конфигурацию запуска, собирает приложение Express, подключает middleware, регистрирует маршруты, предоставляет провайдеры preflight/статуса для хоста демона, поддерживает кольцо аудита разрешений и управляет двухфазным процессом корректного завершения работы (graceful shutdown). Работа с HTTP находится в этом слое; работа с ACP находится на уровень ниже в @qwen-code/acp-bridge (см. 03-acp-bridge.md).

Функции

• Парсинг и валидация ServeOptions: адрес прослушивания, аутентификация, рабочее пространство (workspace), лимиты сессий/подключений, бюджет/пул MCP, CORS, таймауты простоя для промптов/SSE/сессий, rate limit и связанные переключатели.
• Канонизация привязанного рабочего пространства ровно один раз. Одна и та же каноническая форма используется в /capabilities, fallback для POST /session и в bridge.
• Отклонение небезопасных или невалидных конфигураций запуска: привязка не к loopback-интерфейсу без токена, --require-auth без токена, --allow-origin '*' без токена, mcpBudgetMode='enforce' без положительного mcpClientBudget, несуществующий или не являющийся директорией --workspace, а также невалидные значения таймаутов или rate-limit.
• Создание фабрики WorkspaceFileSystem, издателя аудита разрешений (permission audit publisher), DaemonStatusProvider и acp-bridge.
• Сборка приложения Express, подключение middleware (denyBrowserOriginCors / allowOriginCors -> hostAllowlist -> access log -> bearerAuth -> rate limit -> JSON parser -> telemetry -> per-route mutationGate) и монтирование маршрутов для сессий, CRUD-операций с рабочим пространством, файлами, аутентификации через device-flow, голосования за разрешения и ACP HTTP.
• Привязка порта прослушивания и регистрация обработчиков сигналов.
• Запуск двухфазного завершения работы по SIGINT/SIGTERM; принудительный выход при получении второго сигнала.

Архитектура

Точка входа: runQwenServe(opts, deps) в packages/cli/src/serve/run-qwen-serve.ts. Возвращает RunHandle ({ url, port, close, ... }).

Фабрика приложения: createServeApp(opts, getPort, deps) в packages/cli/src/serve/server.ts. Собирает Express Application. Прямые встраивающие модули и тесты вызывают её без обёртки бутстрапа.

Реестр возможностей: SERVE_CAPABILITY_REGISTRY в packages/cli/src/serve/capabilities.ts. Каждый тег имеет версию since и опциональные modes. Десять условных тегов (require_auth, mcp_workspace_pool, mcp_pool_restart, allow_origin, prompt_absolute_deadline, writer_idle_timeout, workspace_settings, session_shell_command, rate_limit, workspace_reload) исключаются, если соответствующий переключатель выключен. См. 11-capabilities-versioning.md.

Middleware (packages/cli/src/serve/auth.ts и server.ts):

Подсистемы:

Импорты из пакета ACP bridge:

• Примитивы event-bus импортируются из @qwen-code/acp-bridge/eventBus.
• Примитивы статуса импортируются из @qwen-code/acp-bridge/status.
• serve/acp-session-bridge.ts остается как локальный для CLI фасад совместимости для более широкой поверхности bridge.

Поток выполнения

Последовательность загрузки

1. Получение и обрезка токена из opts.token или QWEN_SERVER_TOKEN; это предотвращает скрытое нарушение сравнения bearer-токена из-за завершающего символа новой строки от cat token.txt.
2. Защита от опечаток в hostname: --hostname localhost:4170 вызывает ошибку и предлагает использовать --port.
3. Preflight аутентификации: отказ при non-loopback без токена; отказ при --require-auth без токена.
4. Валидация рабочего пространства: абсолютный путь, существует, является директорией. EACCES / EPERM оборачиваются, чтобы указать на флаг.
5. Канонизация рабочего пространства: canonicalizeWorkspace(rawWorkspace) один раз запускает realpathSync.native и передает результат в /capabilities, fallback для POST /session и в bridge.
6. Валидация бюджета MCP: положительное целое число; enforce требует указания бюджета.
7. Вывод переключателя пула MCP: родительская переменная окружения QWEN_SERVE_NO_MCP_POOL=1 устанавливает mcpPoolActive=false, поэтому возможности честно исключают mcp_workspace_pool и mcp_pool_restart.
8. Валидация CORS / таймаутов / rate-limit: --allow-origin '*' требует токен; значения таймаутов простоя промптов, writer, канала, сессии, reaper и окна rate-limit приводят к быстрому сбою при невалидности.
9. childEnvOverrides для каждого handle: передача QWEN_SERVE_MCP_CLIENT_BUDGET и QWEN_SERVE_MCP_BUDGET_MODE дочернему процессу ACP через BridgeOptions.childEnvOverrides вместо мутации process.env.
10. Однократная загрузка settings.json: чтение context.fileName, policy.permissionStrategy и policy.consensusQuorum. Поврежденные файлы откатываются к значениям по умолчанию. validatePolicyConfig() проверяет policy.* на соответствие SERVE_CAPABILITY_REGISTRY.permission_mediation.modes; неизвестные стратегии или неположительный consensusQuorum выбрасывают InvalidPolicyConfigError. Кворум, установленный для стратегии, отличной от consensus, логирует предупреждение в stderr.
11. Выделение PermissionAuditRing (512 записей).
12. Сборка fsFactory: runQwenServe по умолчанию использует trusted: true; прямые вызовы createServeApp по умолчанию используют trusted: false и выводят одно предупреждение.
13. createHttpAcpBridge, см. 03-acp-bridge.md.
14. createServeApp собирает Express.
15. server.listen(port, hostname), затем разрешение фактического getPort() для allowlist хоста.
16. Регистрация обработчиков SIGINT / SIGTERM для корректного завершения работы.

Корректное завершение работы

1. Фаза 1 - разбор bridge по первому сигналу:
   • Удаление реестра device-flow и отмена ожидающих потоков.
   • bridge.shutdown() помечает каждый канал как isDying = true, отправляет корректное закрытие в stdin каждого дочернего процесса ACP, ждет KILL_HARD_DEADLINE_MS (10 с) для каждого канала, затем при необходимости вызывает channel.kill().
2. Фаза 2 - разбор HTTP:
   • server.close() прекращает прием новых соединений и позволяет завершиться выполняющимся запросам.
   • SHUTDOWN_FORCE_CLOSE_MS (5 с) инициирует server.closeAllConnections().
   • Второй дедлайн в 2 с при необходимости снова эскалирует завершение.
3. Второй сигнал во время выхода:
   • bridge.killAllSync() + process.exit(1), чтобы избежать блокировки выхода демона осиротевшими дочерними процессами.

Состояние и жизненный цикл

RunHandle предоставляет:

• url: разрешенный URL прослушивания, после разрешения эфемерного порта.
• port: фактический порт, включая разрешение 0.
• close({ timeoutMs? }): программное завершение работы для встраивающих модулей и тестов.

Прямой вызов createServeApp возвращает только Application; встраивающий модуль сам управляет listen и завершением работы.

Зависимости

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

Важные замечания и известные ограничения

• Прямой вызов createServeApp без deps.fsFactory или deps.bridge по умолчанию устанавливает trusted: false; ACP writeTextFile на стороне агента отклоняет запрос с ошибкой untrusted_workspace. Предупреждение выводится один раз.
• denyBrowserOriginCors отклоняет все запросы, содержащие заголовок Origin; демо-страница работает, потому что другой middleware сначала удаляет совпадающие значения same-origin.
• Порядок body-parser: маршруты, использующие mutate({ strict: true }), возвращают 401 только после express.json(). В худшем случае это --max-connections × express.json({limit: '10mb'}), что может привести к выделению до 2,5 ГБ временной памяти при максимальной нагрузке на loopback-листенер; этот компромисс является осознанным.
• Несколько демонов в одном процессе должны использовать childEnvOverrides для каждого хендла; изменение process.env приводит к гонкам, так как defaultSpawnChannelFactory делает снимок окружения в момент запуска.

Ссылки

• packages/cli/src/serve/run-qwen-serve.ts (инициализация, валидация при запуске, корректное завершение работы)
• packages/cli/src/serve/server.ts (createServeApp(), сборка middleware и маршрутов)
• packages/cli/src/serve/auth.ts (CORS, allowlist хостов, bearer-аутентификация, контроль мутаций)
• packages/cli/src/serve/rate-limit.ts (HTTP rate limit для каждого уровня)
• packages/cli/src/serve/capabilities.ts (реестр capabilities и их условное объявление)
• packages/cli/src/serve/types.ts (ServeOptions, CapabilitiesEnvelope)
• packages/cli/src/serve/daemon-status-provider.ts
• packages/cli/src/serve/permission-audit.ts
• Задачи: #3803 , #4175