Serve Runtime

概要

packages/cli/src/serve/ は qwen serve のブートレイヤーです。CLI フラグを ServeOptions に変換し、起動構成を検証し、Express アプリを構築し、ミドルウェアを接続し、ルートを登録し、デーモンホストのプレフライト/ステータスプロバイダーを公開し、権限監査リングを維持し、2 段階のグレースフルシャットダウンシーケンスを管理します。HTTP 関連の処理はこのレイヤーに存在し、ACP 関連の処理はその下のレイヤーである @qwen-code/acp-bridge に存在します（03-acp-bridge.md を参照）。

責務

• ServeOptions の解析と検証: リッスンアドレス、認証、ワークスペース、セッション/接続の上限、MCP バジェット/プール、CORS、プロンプト/SSE/セッションのアイドルタイムアウト、レート制限、および関連するトグル。
• バインドされたワークスペースを正確に 1 回だけ正規化します。同じ正規化形式は、/capabilities、POST /session のフォールバック、およびブリッジで共有されます。
• 安全でない、または無効な起動構成を拒否します: トークンなしの非ループバックバインド、トークンなしの --require-auth、トークンなしの --allow-origin '*'、正の mcpClientBudget なしの mcpBudgetMode='enforce'、存在しないまたはディレクトリではない --workspace、および無効なタイムアウトまたはレート制限値。
• WorkspaceFileSystem ファクトリ、権限監査パブリッシャー、DaemonStatusProvider、および acp-bridge を構築します。
• Express アプリを構築し、ミドルウェア（denyBrowserOriginCors / allowOriginCors -> hostAllowlist -> アクセスログ -> bearerAuth -> レート制限 -> JSON パーサー -> テレメトリ -> ルートごとの mutationGate）を接続し、セッション、ワークスペース CRUD、ファイル、デバイスフロー認証、権限投票、および ACP HTTP ルートをマウントします。
• リッスンポートをバインドし、シグナルハンドラを登録します。
• SIGINT/SIGTERM で 2 段階のシャットダウンを実行します。2 回目のシグナルで強制終了します。

アーキテクチャ

エントリー: packages/cli/src/serve/run-qwen-serve.ts の runQwenServe(opts, deps)。RunHandle ({ url, port, close, ... }) を返します。

アプリファクトリ: packages/cli/src/serve/server.ts の createServeApp(opts, getPort, deps)。Express の Application を構築します。直接組み込む場合やテストでは、ブートストラップラッパーなしで呼び出します。

ケイパビリティレジストリ: packages/cli/src/serve/capabilities.ts の SERVE_CAPABILITY_REGISTRY。各タグには since バージョンとオプションの modes があります。10 個の条件付きタグ（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 を参照してください。

ミドルウェア (packages/cli/src/serve/auth.ts および server.ts):

サブシステム:

ACP ブリッジパッケージのインポート:

• イベントバスプリミティブは @qwen-code/acp-bridge/eventBus からインポートされます。
• ステータスプリミティブは @qwen-code/acp-bridge/status からインポートされます。
• serve/acp-session-bridge.ts は、より広範なブリッジサーフェスの CLI ローカル互換性ファサードとして残っています。

フロー

ブートシーケンス

1. opts.token または QWEN_SERVER_TOKEN からトークンを解決してトリミングします。これにより、cat token.txt の末尾の改行がベアラー比較を静かに壊すのを防ぎます。
2. ホスト名のタイプミスガード: --hostname localhost:4170 はエラーになり、--port を提案します。
3. 認証プレフライト: トークンなしの非ループバックは拒否されます。トークンなしの --require-auth は拒否されます。
4. ワークスペースの検証: 絶対パス、存在すること、ディレクトリであること。EACCES / EPERM はフラグを指すようにラップされます。
5. ワークスペースの正規化: canonicalizeWorkspace(rawWorkspace) は realpathSync.native を 1 回実行し、/capabilities、POST /session のフォールバック、およびブリッジに供給します。
6. MCP バジェット検証: 正の整数。enforce はバジェットを必要とします。
7. MCP プールトグルの推論: 親環境の QWEN_SERVE_NO_MCP_POOL=1 は mcpPoolActive=false にするため、ケイパビリティは正直に mcp_workspace_pool と mcp_pool_restart を省略します。
8. CORS / タイムアウト / レート制限の検証: --allow-origin '*' はトークンを必要とします。プロンプト、ライター、チャネルアイドル、セッションアイドル、リーパー、およびレート制限ウィンドウの値が無効な場合は即座に失敗します。
9. ハンドルごとの childEnvOverrides: process.env を変更する代わりに、BridgeOptions.childEnvOverrides を介して QWEN_SERVE_MCP_CLIENT_BUDGET と QWEN_SERVE_MCP_BUDGET_MODE を ACP 子プロセスに渡します。
10. settings.json を 1 回ロード: 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 になり、1 回警告します。
13. createHttpAcpBridge、03-acp-bridge.md を参照。
14. createServeApp が Express を組み立てます。
15. server.listen(port, hostname)、次にホスト許可リストのために実際の getPort() を解決します。
16. グレースフルシャットダウンのために SIGINT / SIGTERM ハンドラを登録します。

グレースフルシャットダウン

1. 最初のシグナルでのフェーズ 1 - ブリッジのティアダウン:
   • デバイスフローレジストリを破棄し、保留中のフローをキャンセルします。
   • bridge.shutdown() は各チャネルを isDying = true にマークし、各 ACP 子プロセスの stdin にグレースフルクローズを送信し、チャネルごとに KILL_HARD_DEADLINE_MS (10 秒) 待機し、必要に応じて channel.kill() を呼び出します。
2. フェーズ 2 - HTTP のティアダウン:
   • server.close() は新しい接続の受け入れを停止し、実行中のリクエストが完了するのを待ちます。
   • SHUTDOWN_FORCE_CLOSE_MS (5 秒) で server.closeAllConnections() がトリガーされます。
   • 必要に応じて、2 番目の 2 秒のデッドラインで再度エスカレーションします。
3. 終了中の 2 回目のシグナル:
   • 孤立した子プロセスがデーモンの終了をブロックするのを防ぐために、bridge.killAllSync() + process.exit(1) を実行します。

状態とライフサイクル

RunHandle は以下を公開します:

• url: エフェメラルポート解決後の解決済みリッスン URL。
• port: 0 の解決を含む実際のポート。
• close({ timeoutMs? }): 組み込み用およびテスト用のプログラムによるシャットダウン。

createServeApp を直接呼び出すと Application のみが返されます。組み込み側が listen とシャットダウンを所有します。

依存関係

設定

注意事項と既知の制限

• deps.fsFactory または deps.bridge を指定せずに createServeApp を直接呼び出すと、デフォルトで trusted: false になります。エージェント側の ACP writeTextFile は untrusted_workspace として拒否されます。警告は一度だけ出力されます。
• denyBrowserOriginCors は Origin を含むすべてのリクエストを拒否します。デモページが動作するのは、別のミドルウェアが先に一致する同一オリジンの値を削除するためです。
• Body-parser の順序: mutate({ strict: true }) を使用するルートは、express.json() の後にのみ 401 を返します。最悪のケースは --max-connections × express.json({limit: '10mb'}) となり、飽和したループバックリスナーで最大約 2.5 GB の一時的なメモリを消費します。このトレードオフは意図的なものです。
• 1つのプロセスで複数のデーモンを実行する場合は、ハンドルごとに childEnvOverrides を使用する必要があります。defaultSpawnChannelFactory が spawn 時に環境変数のスナップショットを取得するため、process.env の変更は競合を引き起こします。

参照

• packages/cli/src/serve/run-qwen-serve.ts (ブートストラップ、起動時の検証、グレースフルシャットダウン)
• packages/cli/src/serve/server.ts (createServeApp()、ミドルウェアとルートのアセンブリ)
• packages/cli/src/serve/auth.ts (CORS、ホスト許可リスト、Bearer 認証、ミューテーションゲート)
• packages/cli/src/serve/rate-limit.ts (ティアごとの HTTP レート制限)
• packages/cli/src/serve/capabilities.ts (ケイパビリティレジストリと条件付き公開)
• packages/cli/src/serve/types.ts (ServeOptions, CapabilitiesEnvelope)
• packages/cli/src/serve/daemon-status-provider.ts
• packages/cli/src/serve/permission-audit.ts
• Issues: #3803 , #4175