Skip to Content
デベロッパーガイドDaemon Client AdaptersチャンネルおよびWebバックエンドデーモンアダプター草案

チャンネルおよびWebバックエンドデーモンアダプター草案

目標

既存のチャンネルACPサブプロセス動作をデフォルトとして維持しながら、チャンネルアダプターとWebチャットバックエンドがDaemonSessionClientを通じてqwen serveを利用できるようにする。

この草案はサーバーサイドクライアントのみを対象とする：

  • チャンネルボットバックエンド -> qwen serve
  • ブラウザ -> Webバックエンド / BFF -> qwen serve

ブラウザのJavaScriptがデーモンを直接呼び出すことは明示的に許可しない。 デーモンは設計上、ブラウザのOriginリクエストを現在拒否している。

提案するエントリーポイント

チャンネルバックエンド：

QWEN_CHANNEL_DAEMON_URL=http://127.0.0.1:4170 qwen channel start telegram

Webバックエンド：

QWEN_WEB_DAEMON_URL=http://127.0.0.1:4170 qwen web-chat-backend

共有オプション変数：

QWEN_DAEMON_TOKEN=...
QWEN_DAEMON_WORKSPACE=/repo

最小チャンネルフロー

このPRはDaemonChannelBridgeを追加する。これはチャンネルおよびWebバックエンドアダプター向けのローカルで検証可能なサーバーサイドブリッジである。既存のACPブリッジをデフォルトとして維持し、バックエンドプロセス内でデーモンセッション状態を管理する。

  1. チャンネルの送信者/スレッドをチャンネルセッションキーに解決する。
  2. DaemonClient + DaemonSessionClient.createOrAttach()を使用する。
  3. session.prompt()でインバウンドのユーザーテキストを送信する。
  4. session.events()をサブスクライブしてアシスタントのテキストチャンクを収集する。
  5. プラットフォームアダプターを通じて最終テキストを返送する。
  6. session.respondToPermission()を通じてパーミッション投票を行う。
  7. session.cancel()を通じてアクティブな処理をキャンセルする。

最小Webバックエンドフロー

  1. ブラウザがWebバックエンドへのWebSocketまたはHTTPストリームを開く。
  2. バックエンドがDaemonSessionClientを保有する。
  3. バックエンドがブラウザのメッセージをデーモンのプロンプトに変換する。
  4. バックエンドがデーモンのSSEイベントをブラウザセーフなアプリイベントに変換する。
  5. バックエンドがデーモンのsessionIdと最後に確認したイベントIDをサーバーサイドに保存する。

ブラウザクライアントはデーモンのベアラートークンを受け取ってはならない。

セッション分離の制約

現在のデーモンStage 1の動作は、デーモン設定レベルで実質的にsessionScope: singleとなっている。リクエスト単位のsessionScopeが実装されるまで、マルチユーザーのチャンネルまたはWeb展開では以下の安全な構成のいずれかを選択する必要がある：

  • チャンネルスレッド/Webルームごとに1つのデーモン
  • ユーザーワークスペースごとに1つのデーモン
  • シングルユーザーのデモのみ

無関係なチャンネルスレッドを1つのデーモンセッションに暗黙的に多重化しないこと。

イベントマッピングの契約

デーモンイベントチャンネル/Webバックエンドの処理
session_update / agent_message_chunkアシスタントテキストを追記
session_update / agent_thought_chunkオプションの非表示/デバッグストリーム
session_update / tool_callツールステータスカード/メッセージを送出
permission_requestプラットフォーム固有の承認インタラクション
permission_resolved承認インタラクションを閉じる/更新する
model_switchedバックエンドセッションメタデータを更新
session_diedユーザーに通知してストリームを停止

未知のデーモンイベントは無視するか、デバッグメタデータとして転送すること。致命的なエラーとして扱わないこと。

ブリッジはまだqwen channel startに組み込まれていない。既存のTelegram、Weixin、Dingtalk、プラグインチャンネル、およびブラウザの動作は変更されない。

明示的な非目標

  • ブラウザからデーモンへの直接fetchまたはEventSourceは行わない。
  • このアダプターPRではCORSの緩和を行わない。
  • Telegram、Weixin、Dingtalk、またはプラグインチャンネルのデフォルト移行は行わない。
  • ファイルCRUD、メモリCRUD、MCPの再起動、またはプロバイダーの変更は行わない。
  • デーモンサイドのサポートが存在しない場合のクライアントでのsessionScopeエミュレーションは行わない。

マージの安全性

  • デフォルトは無効。
  • 既存のACPチャンネルブリッジがデフォルトのまま維持される。
  • Webバックエンドは明示的なBFFレイヤーであり、デーモンのセキュリティ変更ではない。
  • チャンネルアダプターはデーモントークンをフロントエンド/ブラウザコードにインポートしてはならない。

検証計画

  • チャンネルセッションキーとデーモンセッションのバインディングをユニットテストする。
  • デーモンイベントからチャンネル/Webメッセージへのマッピングをユニットテストする。
  • プロンプト、キャンセル、モデル切り替え、パーミッション応答の転送をユニットテストする。
  • ローカルのqwen serveに対してシングルユーザーのチャンネルバックエンドをスモークテストする。
  • ブラウザ -> BFF -> デーモンの経路でデーモントークンを露出させずにスモークテストする。

デフォルト移行前のブロッカー

  • リクエスト単位のsessionScope。
  • セッションメタデータとクローズ/削除のライフサイクル。
  • デーモンがスタンプしたクライアントID。
  • セッションスコープのパーミッションルート。
  • MCP、スキル、プロバイダー、および環境の読み取り専用診断。
Last updated on
クイックスタートと運用IDE デーモンアダプター草案