Поэтапное разделение serve server.ts

Цель

Разделить packages/cli/src/serve/server.ts на этапы без изменения поведения демона. На первом этапе извлекаются общие хелперы и группы роутов, границы которых уже четко определены, при этом createServeApp() сохраняет ответственность за подключение middleware, зависимостей с состоянием, монтирование транспортов и финальную обработку ошибок.

Порядок middleware и роутов

Порядок сборки приложения является частью публичного поведения и должен оставаться стабильным:

удаление same-origin Origin
CORS и allowlist хостов
pre-auth /health и /demo для разрешенных loopback-конфигураций
логирование доступа
статические ресурсы Web Shell
bearer-аутентификация
rate limit
парсер тела JSON и маппер ошибок парсинга JSON
post-auth /health и /demo, когда это требуется
телеметрия демона
группы REST-роутов
HTTP и WebSocket роуты ACP
фоллбэк Web Shell
финальный обработчик ошибок

Извлеченные границы

server/request-helpers.ts отвечает за санитизацию тела запроса, парсинг client-id, обнаружение loopback, валидаторы пути/query и парсинг тела permission vote. Модули роутов зависят от этого файла вместо импорта из server.ts.

server/error-response.ts отвечает за таксономию ошибок bridge и маппинг HTTP-ответов. Экспортируемые обертки принимают опциональный логгер демона, чтобы модули роутов могли сохранить существующее поведение stderr и daemon-log.

server/session-list.ts отвечает за слияние сохраненного и активного списка сессий, используемого как в REST, так и в ACP HTTP.

server/fs-factory.ts отвечает за создание фабрики файловой системы рабочего пространства по умолчанию и вывод предупреждений fs audit.

server/telemetry.ts отвечает за классификацию роутов и middleware HTTP-телеметрии демона.

server/prompt-deadline.ts отвечает за вычисление дедлайна промпта и его класс-сентинел прерывания.

Модули роутов следуют существующему стилю registerXRoutes(app, deps). Они получают только необходимые зависимости, а не единый god context.

Нецели

На этом этапе не изменяются тела ответов, коды статусов, заголовки, формат фреймов SSE, порядок аутентификации или таксономия ошибок. Не удаляются shim’ы обратной совместимости с реэкспортом, такие как status.ts, event-bus.ts или in-memory-channel.ts. Не происходит переименование исторических документов или очистка несвязанных camelCase путей.

После этого этапа server.ts может по-прежнему содержать более 200 строк. Критерием приемки являются стабильные границы, которые сделают последующее извлечение сессий и SSE механическим процессом.

Примечания к аудиту

Раунд 1 проверил архитектурные границы и отклонил новую абстракцию Router, поскольку существующие модули роутов уже используют прямые функции registerXRoutes(app, deps).

Раунд 2 проверил пути обработки ошибок и сохранил таксономию ошибок в одном хелпере, чтобы извлечение роутов не могло незаметно изменить HTTP-коды статусов.

Раунд 3 проверил совместимость и сохранил публичные экспорты, используемые run-qwen-serve.ts, диспетчеризацией ACP HTTP и тестами.

Раунд 4 проверил стратегию тестирования и опирается на сфокусированные тесты server.test.ts, ACP HTTP и роутов, поскольку это структурный рефакторинг без видимых для пользователя изменений в поведении.