Skip to Content
デベロッパーガイドDaemonデーモン開発者ドキュメント

デーモン開発者ドキュメント

これは qwen-code デーモンモード の開発者向け技術ドキュメントです。対象は qwen serve HTTP デーモン、@qwen-code/acp-bridge パッケージ、ワークスペーススコープの MCP トランスポートプール、マルチクライアントパーミッション調停、型付きデーモンイベントスキーマ v1、TypeScript SDK デーモンクライアント、およびデーモンに接続するアダプター群です。

このドキュメントは既存のドキュメントを補完するものであり、置き換えるものではありません:

既存ドキュメント対象読者情報源として扱う内容
../../users/qwen-serve.md運用者ユーザークイックスタート、フラグ、脅威モデル
../qwen-serve-protocol.mdプロトコル実装者HTTP ルートカタログ、リクエスト/レスポンス形式、エラーコード
../examples/daemon-client-quickstart.mdSDK 利用者TypeScript エンドツーエンドウォークスルー
../daemon-client-adapters/アダプター作成者レガシークライアントアダプターの設計ドキュメント
14-cli-tui-adapter.mdアダプター作成者クライアントアダプターの設計メモ
../../design/f2-mcp-transport-pool.mdF2 メンテナーワークスペース 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 - システムアーキテクチャ、プロセストポロジー、パッケージマップ、および7つのトップレベルシーケンス図。

サーバーコア

  • 02-serve-runtime.md - runQwenServe ブートストラップ、Express アプリ、ミドルウェアチェーン、グレースフルシャットダウン。
  • 03-acp-bridge.md - @qwen-code/acp-bridge パッケージ内部、セッション多重化、チャネルファクトリー、ACP 子プロセス起動。
  • 04-permission-mediation.md - MultiClientPermissionMediator、4つのポリシー、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、モノトニック ID、リングリプレイ、Last-Event-ID、スロークライアントバックプレッシャー、client_evicted。
  • 11-capabilities-versioning.md - ケイパビリティレジストリ、プロトコルバージョン、スキーマバージョン、条件付きアドバタイズ。
  • 12-auth-security.md - ベアラーミドルウェア、ホスト許可リスト、CORS 拒否、ミューテーションゲート、--require-auth、/health 除外、デバイスフロー。

クライアント

  • 13-sdk-daemon-client.md - TypeScript SDK: DaemonClient、DaemonSessionClient、DaemonAuthFlow、SSE パーサー、イベントリデューサー、ui/* トランスクリプトレイヤー。
  • 14-cli-tui-adapter.md - 共有 UI トランスクリプトレイヤーとレガシー CLI TUI デーモンアダプターの関係。
  • 15-channel-adapters.md - DaemonChannelBridge 共有ベース、および DingTalk、WeChat (Weixin)、Telegram、Feishu の各チャネルアダプター。
  • 16-vscode-ide-adapter.md - DaemonIdeConnection、ループバック専用の強制、ウェブビューブリッジング。

リファレンス付録

用語集

  • ACP - Agent Client Protocol。デーモンブリッジと ACP 子プロセス間で使用される stdio 上の JSON-RPC。クライアントがデーモンに対して使用する HTTP プロトコルとは異なります。
  • ACP child - デーモンが起動する子プロセス (qwen --acp)。実際のエージェントランタイムをホストします。ブリッジは1つの ACP 子プロセスを多くの接続クライアントに多重化します。
  • acp-bridge - @qwen-code/acp-bridge パッケージ (packages/acp-bridge/)。セッション多重化、パーミッションメディエーター、イベントバス、チャネルファクトリーを管理します。
  • BridgeClient - packages/acp-bridge/src/bridgeClient.ts。1つの ACP ClientSideConnection をラップし、requestPermission、sendPrompt、cancelSession を処理します。
  • Channel factory - ACP 子プロセスを起動またはアタッチするためのプラガブル戦略。デフォルトの spawnChannel は qwen --acp をサブプロセスとして実行し、inMemoryChannel はテスト用にインプロセスで実行します。
  • DaemonClient - packages/sdk-typescript/src/daemon/DaemonClient.ts。デーモンに対する TypeScript SDK HTTP レベルのファサード。
  • DaemonSessionClient - packages/sdk-typescript/src/daemon/DaemonSessionClient.ts。SSE リプレイのために lastSeenEventId を追跡するセッションスコープのラッパー。
  • EventBus - packages/acp-bridge/src/eventBus.ts。モノトニック ID、有界リング、サブスクライバーごとのバックプレッシャーを持つセッションごとのインメモリ pub/sub。
  • 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 ワークスペーススコープのプール。サーバー名と設定フィンガープリントごとに1つの MCP トランスポートを共有します。
  • Mediator policy - first-responder、designated、consensus、local-only のいずれか。マルチクライアントのパーミッション投票の解決方法を決定します。
  • Originator client id - 現在パーミッションを要求しているプロンプトを開始したクライアントの X-Qwen-Client-Id。designated ポリシーはこの id からの投票のみを受け付けます。
  • PoolEntry - packages/core/src/tools/mcp-pool-entry.ts。McpTransportPool の1エントリー: 1つの MCP トランスポート、アタッチされたセッションの参照カウント、アイドルドレインタイマー。
  • Session scope - single（すべてのクライアントで共有される1つの ACP セッション）または thread（会話スレッドごとに1つのセッション）。デフォルトは single。
  • SSE - Server-Sent Events。デーモンのアウトバウンドイベントチャネル (GET /session/:id/events)。
  • Workspace - 起動時にデーモンがバインドされたディレクトリ (--workspace または cwd)。1つのデーモンプロセスは1つのワークスペースに対応します。

実装ソースアンカー

ドキュメントから最新の main コードに移動する際はこれらのアンカーを使用してください:

サーフェス実装アンカー主要ドキュメント
ブートストラップと HTTP アセンブリpackages/cli/src/serve/run-qwen-serve.ts, server.ts, /demo02, 20
ACP ブリッジとセッション多重化packages/acp-bridge/src/bridge.ts, packages/acp-bridge/src/bridgeTypes.ts, @qwen-code/acp-bridge03, 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, MCPCallInterruptedError05, 06
MCP バジェットガードレールpackages/core/src/tools/mcp-workspace-budget.ts, ServeMcpBudgetStatusCell.scope, budgets[]06
ワークスペースファイルシステムpackages/cli/src/serve/fs/, assertTrustedForIntent(trusted, intent), meta.matchedIgnore, includeIgnored07
イベントスキーマと 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, serverId09, 10
イベント再同期state_resync_required, awaitingResync, RESYNC_PASSTHROUGH_TYPES, asKnownDaemonEvent, unrecognizedKnownEventCount09, 10
ケイパビリティpackages/cli/src/serve/capabilities.ts, mcp_server_restart_refused.reason, MCP_RESTART_REFUSED_REASONS.has11
認証とデバイスフローpackages/cli/src/serve/auth.ts, packages/cli/src/serve/auth/device-flow.ts12
TypeScript SDK デーモンクライアントpackages/sdk-typescript/src/daemon/{DaemonClient,DaemonSessionClient,DaemonAuthFlow,sse,events,types}.ts, MCP_RESTART_DEFAULT_TIMEOUT_MS13
共有 UI トランスクリプトレイヤーDaemonUiEventType, DaemonSessionProvider, packages/webui/src/daemon/13, 14, ../daemon-ui/README.md
チャネルと IDE アダプターpackages/channels/, packages/vscode-ide-companion/src/services/daemonIdeConnection.ts15, 16

意図的なスコープ外

  • Java / Python SDK デーモンクライアント - 現時点でデーモンクライアントを提供しているのは TypeScript SDK のみです。ドキュメント 13 は TypeScript 専用です。
  • Web UI 製品の詳細 - 共有トランスクリプトレイヤーと Web UI デーモンエントリーポイントはここでカバーされていますが、製品 UI レイアウトは docs/developers/daemon-ui/ とアダプター設計メモで管理されています。
  • Zed 拡張機能 (packages/zed-extension/) - stdio 経由で qwen --acp を直接起動し、デーモンをバイパスします。
  • 試験的なインプロセスホスティング - --no-http-bridge は現在も http-bridge にフォールバックします。安定したインプロセスサービングモードが実装された際には新しいドキュメントが必要です。

現在のデーモンモードのカバレッジ

サーバーコアのカバレッジ

領域現在の状態主要ドキュメント
ブートストラップ / リッスンパスqwen serve は runQwenServe を遅延ロードし、auth/workspace/budget/settings を検証し、Express アプリを構築してから app.listen を呼び出してシグナルが来るまでブロックします。02, 20
認証 / ネットワークガードレールループバックはデフォルトでベアラー不要。非ループバックはベアラーが必要。--require-auth はループバックと /health にもベアラーを要求します。ホスト許可リストとデフォルト CORS 拒否が有効です。12, 17
セッションライフサイクルPOST /session、load、resume、メタデータパッチ、ハートビート、退避、アイドルリーピング、プロンプト保留制限、グレースフルクローズがドキュメント化されています。08, 10
ACP ブリッジデフォルトでは1つの 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種類の既知イベントタイプ。ID なしサブスクライバーの合成フレーム。SSE 書き込み境界でスタンプされる _meta.serverTimestamp。09, 10
ケイパビリティSERVE_PROTOCOL_VERSION = 'v1'。67の登録済みタグ。10の条件付きタグ。11
セッションシェルPOST /session/:id/shell は --enable-session-shell、ベアラー認証、セッションバインドの 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
Web UI デーモンコンシューマーpackages/webui/src/daemon/ は React プロバイダーとアダプターを通じて SDK トランスクリプトストアを利用します。14, ../daemon-client-adapters/web-ui.md
CLI TUI / チャネル / VS Codeレガシーパスは引き続き存在します。共有トランスクリプトプリミティブへの移行はフォローアップ作業としてドキュメント化されており、完了した動作ではありません。14, 15, 16

リファレンスと運用

領域現在の状態主要ドキュメント
設定qwen serve の全フラグ、環境変数、settings.json、ServeOptions、BridgeOptions、重要な定数が1ページにまとめられています。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 は未知のタイプを前方互換として扱う必要があります。
  • ケイパビリティタグは動作のコントラクトです。新しい動作には新しいタグが必要です。特にクライアントがルートを呼び出す前にプリフライトする可能性がある場合は必須です。
  • sessionScope: 'thread' は現在の会話スレッドごとの分割方式です。古いクライアントスコープの表現を再導入しないでください。
  • エンベロープ _meta と ACP ペイロード data._meta は別物です。ツール呼び出しのプロベナンスは ACP ペイロード下にあり、サーバー発行タイムスタンプは SSE エンベロープにあります。

バージョンの出自

このドキュメントセットは、#4412  のフォローアップ作業を含む、現在 main にマージされているデーモンモードのサーフェスを反映しています。以前の F シリーズの計画スナップショットではなく、現在の動作を意図的に記述しています。

Last updated on
チャネルプラグイン開発者ガイドデーモンアーキテクチャ