{"author":{"id":"4e3fvwoonbfzbvqtdwehr2fzdp","name":"陈成","avatar_url":"https://lh3.googleusercontent.com/a/ACg8ocLP6uaUWVTzl3dUQgZAldOJdTbU_NCUcOxb0Jx1K5CuD97UlDiQ=s96-c","handle":"sorrycc"},"mine":false,"report":{"topic_id":"p5hmpjzplmjv","markdown":"# qwen-code 全局架构图（main @ `53940f2afc`）\n\n\u003e 基于 `~/Downloads/qwen-code-harness-分析/` 01–09 报告（同一 commit），并在仓库里对包依赖、入口分派、serve ↔ web-shell、sdk / acp 依赖做了复核。\n\u003e 行号、计数都是这个 commit 上的。\"声明依赖\"指 package.json；\"实际 import\"指源码 import；\"运行时调用\"指进程间协议。三者经常不一致，下面分开画。\n\n---\n\n## 0. 一句话版本\n\n- **核心只有三块**：`core`（agent 运行时）、`cli`（TUI、headless、ACP agent、`qwen serve` 守护进程、子命令都在这里）、`acp-bridge`（serve 用来拉起和管理 `qwen --acp` 子进程的 ACP client）。\n- **所有上层应用都通过四个协议面接入**，基本不直接调代码：\n  1. `qwen serve`：REST/SSE（主要），外加 `/acp` HTTP/WS\n  2. `qwen --acp`：stdio ACP\n  3. `qwen -p --input-format stream-json`：SDK 控制协议\n  4. IDE MCP：CLI 连 VS Code 插件起的 MCP server\n- **web-shell 是 `qwen serve` 的前端**：serve 托管它的静态资源；它通过 `@qwen-code/sdk/daemon` 调 serve 的 REST/SSE；serve 再经 acp-bridge 把请求转给 `qwen --acp` 子进程，子进程里跑 core。\n- **`@qwen-code/sdk` 是 serve 的官方客户端库**：web-shell、VS Code 插件、qwen-live、cli 自己（反向依赖）都用它。它在构建时把 core / acp-bridge 的少量常量 inline 进来，发布时还把整个 CLI bundle 打进包里。\n- \"ACP\" 有三层含义：`@agentclientprotocol/sdk` 库、`@qwen-code/acp-bridge` 包、`qwen --acp` 协议。依赖它们的包各不相同，见 §6。\n- **qwen-live 是\"语音指挥编码 agent\"的独立产品**：macOS 上的 Live Host 负责音频和浮层，Live daemon 连 DashScope 实时语音模型，通过 `handoff` 把任务派给 `qwen --acp`、`qodercli --acp` 等编码 agent。daemon 有独立版（`packages/qwen-live`）和内置于 `qwen serve` 的两个实现，见 §6.5。\n- \"channel\" 也有三层含义：IM / 代码平台渠道（产品功能）、`--channel` 启动参数（客户端身份，只用于统计）、acp-bridge 的 `AcpChannel`（到子进程的 stdio 传输），见 §6.3。\n\n---\n\n## 1. 全局分层图（运行时视角）\n\n```mermaid\nflowchart TB\n  subgraph UI[\"前端 / 宿主\"]\n    direction LR\n    TERM[\"终端用户\u003cbr/\u003eqwen（Ink / OpenTUI）\"]\n    WS[\"web-shell\u003cbr/\u003eReact SPA\"]\n    DESK[\"desktop\u003cbr/\u003eTauri 壳\"]\n    MOB[\"mobile-shell\u003cbr/\u003eAndroid WebView\"]\n    CHR[\"chrome-extension\"]\n    VSC[\"vscode-ide-companion\"]\n    ZED[\"zed-extension\"]\n    LH[\"live-host\"]\n  end\n\n  subgraph CLIENTS[\"客户端库 / 中间层\"]\n    direction LR\n    SDKTS[\"@qwen-code/sdk\u003cbr/\u003equery() · /daemon · /peer\"]\n    SDKJ[\"sdk-java\"]\n    SDKP[\"sdk-python\"]\n    QL[\"qwen-live\"]\n    CHB[\"channel-base + 10 个 channel-*\"]\n    MAS[\"managed-agent-server\u003cbr/\u003eJava Spring Boot\"]\n  end\n\n  subgraph SURF[\"协议面（全部由 packages/cli 提供）\"]\n    direction LR\n    SERVE{{\"qwen serve\u003cbr/\u003eREST/SSE · /acp HTTP+WS · WS(/terminal /voice /live)\"}}\n    ACPSTDIO{{\"qwen --acp\u003cbr/\u003estdio ndjson ACP\"}}\n    SJ{{\"qwen -p stream-json\u003cbr/\u003econtrol_request\"}}\n    TUI{{\"交互 TUI\"}}\n  end\n\n  subgraph HARNESS[\"harness\"]\n    direction LR\n    BR[\"acp-bridge\u003cbr/\u003eBridgeClient implements Client\"]\n    CLI[\"cli\u003cbr/\u003eacp-integration · serve · nonInteractive · ui\"]\n    CORE[\"core\u003cbr/\u003eConfig · LlmClient · CoreToolScheduler · tools · services · managed-runtime\"]\n  end\n\n  TERM --\u003e TUI\n  WS --\u003e|import| SDKTS\n  DESK --\u003e|spawn serve + 加载| WS\n  MOB --\u003e|WebView| WS\n  VSC --\u003e|内嵌| WS\n  SDKTS --\u003e|DaemonClient| SERVE\n  SDKTS --\u003e|\"query() spawn\"| SJ\n  SDKJ --\u003e SJ\n  SDKJ --\u003e|DaemonClient| SERVE\n  SDKP --\u003e SJ\n  CHR --\u003e|HTTP :4170| SERVE\n  LH --\u003e|\"/live/*\"| SERVE\n  QL --\u003e SERVE\n  QL --\u003e ACPSTDIO\n  MAS --\u003e|\"serve --profile hosted-harness\"| SERVE\n  WS -.-\u003e|\"managed 模式 /api/agent/web-shell/v1/*\"| MAS\n  VSC --\u003e|\"--acp --channel=VSCode\"| ACPSTDIO\n  VSC --\u003e|\"serve --no-web\"| SERVE\n  ZED --\u003e ACPSTDIO\n  CHB --\u003e|\"AcpBridge spawn --acp\"| ACPSTDIO\n\n  SERVE --\u003e BR\n  BR --\u003e|\"spawn qwen --acp 子进程\"| ACPSTDIO\n  TUI --\u003e CLI\n  ACPSTDIO --\u003e CLI\n  SJ --\u003e CLI\n  SERVE --\u003e CLI\n  CLI --\u003e CORE\n  BR --\u003e CORE\n  CLI -.-\u003e|IDE MCP client| VSC\n```\n\n要点：\n\n- `qwen serve` 默认**不在本进程跑 agent loop**。每个工作区运行时由 acp-bridge spawn 一个 `qwen --acp` 子进程（`acp-bridge/src/spawnChannel.ts:551`），一个子进程托管多个会话。只有 `--profile hosted-harness` 自带 loop（`cli/src/serve/hosted-harness-model.ts`）。\n- 所以从 web-shell 出发，链路是：**web-shell → sdk/daemon → serve REST → acp-session-bridge → acp-bridge → stdio ACP → `qwen --acp`（acp-integration/Session.ts）→ core**。\n\n---\n\n## 2. 包清单与分层\n\n| 层 | 包 | npm 名 | 角色 |\n|---|---|---|---|\n| harness | `packages/core` | `@qwen-code/qwen-code-core`（private） | agent 运行时：`Config`、`LlmClient`/`LlmChat`/`Turn`、`CoreToolScheduler`、tools、services、providers、managed-runtime、ide client、ipc（peer） |\n| harness | `packages/cli` | `@qwen-code/qwen-code`（private，经根 `dist/` 发布，bin `qwen`） | 入口分派、Ink / OpenTUI TUI、headless、ACP agent（`acp-integration/`）、`qwen serve` 守护进程（`serve/`，586 个文件）、子命令 |\n| harness | `packages/acp-bridge` | `@qwen-code/acp-bridge`（private） | serve 侧的 ACP client，spawn 和管理 `qwen --acp` 子进程；也导出一批协议常量和 transcript 回放 |\n| 客户端库 | `packages/sdk-typescript` | `@qwen-code/sdk` | 导出 `.`（`query()`，spawn CLI 走 stream-json）、`./daemon`（serve 客户端 `DaemonClient`）、`./daemon/transports`、`./daemon/transcript`、`./daemon/ui`、`./peer`（UDS 跨会话）；bin `qwen-serve-mcp` |\n| 客户端库 | `sdk-java` / `sdk-python` | Maven / PyPI | stream-json `query()`；Java 另有 `DaemonClient` |\n| 前端 | `packages/web-shell` | `@qwen-code/web-shell` | serve 的 Web UI，也被 VS Code 插件、desktop、mobile-shell 复用 |\n| 前端 | `vscode-ide-companion` | VS Code 插件 | 两条路：直连 `--acp`，或拉起 `serve --no-web` 后内嵌 web-shell；同时作为 IDE MCP server |\n| 前端 | `desktop` / `mobile-shell` / `chrome-extension` / `live-host` / `zed-extension` | — | 壳或轻客户端，只走协议 |\n| 中间层 | `qwen-live` | `@qwen-code/qwen-live` | Live 编排，adaptor 同时接 serve 和 `--acp` |\n| 中间层 | `channels/base` + 10 个 `channel-*` | `@qwen-code/channel-*` | IM / 代码平台渠道，**宿主是 cli** |\n| 控制面 | `managed-agent-server` | Java | Hosted Harness 控制面；拉起 `qwen serve --profile hosted-harness`；给 web-shell managed 模式提供 `/api/agent/web-shell/v1/*` |\n| 工具 / MCP | `browser-use`、`cua-driver`（`@qwen-code/cua-sdk`）、`node-repl`、`mobile-mcp`、`audio-capture`、`web-templates` | — | 被 core / cli 引用或作为 MCP server 独立运行 |\n| 扩展 | `integrations/*` | — | 以 `qwen-extension.json` 方式被 cli 加载 |\n\n---\n\n## 3. package.json 声明的 workspace 依赖\n\n只列 `@qwen-code/*` 和 `@agentclientprotocol/sdk`。实线是 `dependencies`，虚线是 `devDependencies` / `peerDependencies`。\n\n```mermaid\nflowchart LR\n  CLI[\"cli\u003cbr/\u003e@qwen-code/qwen-code\"]\n  CORE[\"core\"]\n  BR[\"acp-bridge\"]\n  SDK[\"sdk-typescript\u003cbr/\u003e@qwen-code/sdk\"]\n  WS[\"web-shell\"]\n  VSC[\"vscode-ide-companion\"]\n  QL[\"qwen-live\"]\n  WT[\"web-templates\"]\n  AC[\"audio-capture\"]\n  CHB[\"channel-base\"]\n  CHX[\"channel-* ×10\"]\n  BU[\"browser-use\"]\n  CUA[\"cua-sdk\"]\n  NR[\"node-repl-mcp\"]\n  ACPSDK([\"@agentclientprotocol/sdk 0.14.1\"])\n\n  CLI --\u003e CORE\n  CLI --\u003e BR\n  CLI --\u003e SDK\n  CLI --\u003e WT\n  CLI --\u003e AC\n  CLI --\u003e CHB\n  CLI --\u003e CHX\n  CLI --\u003e ACPSDK\n  BR --\u003e CORE\n  BR --\u003e ACPSDK\n  CHX --\u003e CHB\n  CHB --\u003e ACPSDK\n  QL --\u003e SDK\n  QL --\u003e ACPSDK\n  VSC --\u003e BR\n  VSC --\u003e CORE\n  VSC --\u003e SDK\n  VSC --\u003e WS\n  VSC --\u003e ACPSDK\n  VSC -.dev.-\u003e CLI\n  SDK -.dev, 构建时 inline.-\u003e CORE\n  SDK -.dev, 构建时 inline.-\u003e BR\n  WS -.peer+dev.-\u003e SDK\n  WS -.dev.-\u003e BR\n  WS -.dev.-\u003e CHX\n  WT -.dev.-\u003e SDK\n  WT -.dev.-\u003e WS\n  CORE -.dev.-\u003e BU\n  CUA --\u003e BU\n  NR --\u003e CUA\n```\n\n声明里看不出来的事实：\n\n- **web-shell 没声明 core，但生产代码 import 了 core**（5 处，靠 workspace hoist 解析的幽灵依赖），见 §4。\n- **cli 依赖 sdk 和 channel-***，方向是\"harness 依赖上层\"，见 §4.2。\n- desktop、mobile-shell、chrome-extension、live-host、managed-agent-server、sdk-java、sdk-python、zed-extension **没有任何 workspace 依赖**，只走协议。\n\n---\n\n## 4. 实际代码 import 耦合\n\n### 4.1 包间 import 站点数（生产代码）\n\n数据来自报告 02 §4.2，口径是生产文件的 import 语句。\n\n```mermaid\nflowchart LR\n  CLI[\"cli\"] -- \"2057 站点 / 846 文件\" --\u003e CORE[\"core\"]\n  CLI -- \"232 / 117 文件\" --\u003e BR[\"acp-bridge\"]\n  BR -- \"28 / 12 文件\" --\u003e CORE\n  CLI -- \"62 / 39 文件（反向）\" --\u003e CH[\"channels/*\"]\n  CLI -- \"15 / 12 文件（反向）\" --\u003e SDK[\"sdk-typescript\"]\n  CLI -- \"2（反向）\" --\u003e WT[\"web-templates\"]\n  WS[\"web-shell\"] -- \"约 450 条 / 212 文件\u003cbr/\u003e几乎全是 @qwen-code/sdk/daemon\" --\u003e SDK\n  WS -. \"5（未声明依赖）\" .-\u003e CORE\n  WS -. \"1\" .-\u003e BR\n  SDK -. \"3 运行时（构建时 inline）\" .-\u003e CORE\n  SDK -. \"5 运行时 + 2 type\" .-\u003e BR\n  VSC[\"vscode-ide-companion\"] -- \"29 / 24 文件\" --\u003e CORE\n  VSC -- \"9\" --\u003e SDK\n  VSC -- \"1\" --\u003e BR\n  VSC -- \"1（./export）\" --\u003e CLI\n  LH[\"live-host\"] -- \"22\" --\u003e QL[\"qwen-live\"]\n```\n\n### 4.2 值得注意的几条\n\n| 现象 | 细节 | 位置 |\n|---|---|---|\n| **web-shell → core 幽灵依赖** | 3 个运行时符号：`parseManagedPermissionRules`（core `managed-runtime/managed-permission-rules.js`，3 个文件）、`formatSubscriptionQuotaDisplay`（core `utils/subscription-quota.js`，2 个文件）、`IMAGE_ONLY_PROMPT_TEXT`（acp-bridge `bridgeTypes`，1 个文件） | `web-shell/client/components/managed/*`、`messages/SystemMessage.tsx`、`ToolGroup.tsx`、`hooks/useQueuedPrompts.ts` |\n| **sdk → core / acp-bridge** | 8 条运行时 import，都是协议常量或纯函数（事件名、超时、`_meta` key、`shellResult`、`transcriptRecords`、`transcriptReplay`）。只写在 devDeps，构建时 inline，`scripts/peer-build-assertions.js` 断言产物里不泄漏包名 | `sdk-typescript/src/daemon/{DaemonClient,events,shellResult}.ts`、`daemon/ui/*` |\n| **sdk 打包整个 CLI** | `prepack` 执行 `bundle:cli`，把根 `dist/cli.js` 复制进 `@qwen-code/sdk`，`query()` 默认 spawn 这份 CLI | `sdk-typescript/scripts/bundle-cli.js` |\n| **cli 反向依赖 sdk** | 12 个生产文件 import `@qwen-code/sdk`：`commands/attach.ts`、`commands/channel/{daemon-worker,reload,set,status,stop}.ts`、`serve/routes/{daemon-update,subscription-auth,weixin-auth}.ts`、`serve/web-shell-preauth.ts`、`ui/utils/export/*` | — |\n| **cli 反向依赖 channels** | 39 个生产文件 import `@qwen-code/channel-*`。channels 的宿主是 cli（`qwen channel …` 和 serve 内的 channel worker） | `cli/src/serve/channel-*.ts`、`cli/src/commands/channel/*` |\n| **VS Code 插件深度耦合 core** | 24 个文件、68 个符号：Provider/Auth 安装计划、`Storage`、IDE 协议 schema、`FileDiscoveryService`、`SessionService`，以及直接 import cli 的 `./export`；还**直接读写** `~/.qwen/settings.json` 和会话 jsonl | `vscode-ide-companion/src/services/*`、`webview/*` |\n| **cli → core 通配深 import** | core 的 `exports` 有 `\"./*\" → \"./dist/src/*\"`，cli 生产代码有 1469 处深 import，涉及 348 个 core 内部模块；ESLint 规则还在推动\"从定义处 deep import\" | `eslint.config.js`、`eslint.legacy-core-barrel-imports.mjs` |\n| **managed-agent-server ↔ core / serve 契约** | 不 import TS，但 Java 端通过 33 个 `*-vN.fixtures.json` 契约 fixture 绑定 `core/src/managed-runtime/contracts` 和 `cli/src/serve/contracts` | — |\n\n---\n\n## 5. 专题：web-shell 和 serve 的关系\n\n### 5.1 三重关系\n\n| 关系 | 怎么做的 | 证据 |\n|---|---|---|\n| **托管（构建 / 部署期）** | `npm run bundle` 把 `packages/web-shell/dist` 复制到根 `dist/web-shell/`；`qwen serve` 启动时 `resolveWebShellDir()` 先找 bundle 旁边的 `web-shell/`，再往上找 `packages/web-shell/dist`；找不到就只提供 API（`--no-web` 也是只提供 API） | `scripts/copy_bundle_assets.js:619-645`、`cli/src/serve/web-shell-resolver.ts`、`run-qwen-serve.ts:9256-9269`、`server.ts:4424`（SPA fallback） |\n| **调用（运行期）** | web-shell 约 450 条 import 走 `@qwen-code/sdk/daemon`（`DaemonClient` + `RestSseTransport`），调 serve 的 REST，订阅 SSE `GET /session/:id/events`；另有约 38 处直接 `fetch` daemon（agent threads、weixin auth、desktop-relay、`/live/*`、`/voice/stream`、`/uploads` 等）；WS 用于 `/terminal`、`/voice/stream`、`/live/*` | `sdk-typescript/src/daemon/DaemonClient.ts:925`、`RestSseTransport.ts:29` |\n| **鉴权配对** | serve 在 bearer 之前挂了 web-shell pairing 路由；`web-shell-preauth.ts` 用 sdk 处理预授权 | `server.ts:60`、`cli/src/serve/web-shell-preauth.ts` |\n\n`/acp` HTTP+WS 端点虽然存在（`cli/src/serve/acp-http/`），SDK 也有 `AcpHttpTransport` / `AcpWsTransport`，但 daemon 的 `/capabilities.transports` 只宣告 `['rest']`（`cli/src/serve/routes/capabilities.ts:121`），**所以默认没有任何仓内客户端走 ACP 传输**，web-shell 实际走的是 REST/SSE。\n\nweb-shell 还有一个 **managed 模式**：不连 `qwen serve`，而是连 Java `managed-agent-server` 的 `/api/agent/web-shell/v1/*`（87 个接口，生成代码在 `web-shell/client/components/managed/generated/managed-agent-api.ts`）。managed-agent-server 再去拉起 `qwen serve --profile hosted-harness`。\n\n### 5.2 一次 prompt 的完整链路（默认模式）\n\n```mermaid\nsequenceDiagram\n  autonumber\n  participant U as 浏览器 web-shell\n  participant SDK as sdk/daemon DaemonClient\n  participant S as qwen serve（Express 5）\n  participant SB as serve/acp-session-bridge.ts\n  participant BR as acp-bridge BridgeClient\n  participant A as qwen --acp 子进程\u003cbr/\u003eacp-integration/QwenAgent + Session\n  participant C as core（LlmChat / CoreToolScheduler / tools）\n\n  U-\u003e\u003eSDK: sendPrompt(...)\n  SDK-\u003e\u003eS: POST /session/:id/prompt（bearer）\n  Note over S: hostAllowlist → CORS → bearerAuth → json → mutate gate\n  S-\u003e\u003eSB: routes/session.ts:7698\n  SB-\u003e\u003eBR: bridge.prompt(...)\n  BR-\u003e\u003eA: ACP session/prompt（stdio ndjson；按工作区运行时复用子进程）\n  A-\u003e\u003eC: Session.#executePromptInner → LlmChat.sendMessageStream / 工具执行\n  C--\u003e\u003eA: 流式事件、工具调用\n  A--\u003e\u003eBR: session/update · qwen/notify/* · session/request_permission\n  BR--\u003e\u003eS: daemon 事件\n  S--\u003e\u003eSDK: SSE GET /session/:id/events\n  SDK--\u003e\u003eU: UI 事件（审批、工具卡片、消息流）\n  U-\u003e\u003eSDK: 用户点\"允许\"\n  SDK-\u003e\u003eS: 权限应答 REST\n  S-\u003e\u003eBR: 回填 request_permission\n  BR-\u003e\u003eA: ACP response\n```\n\n### 5.3 哪些宿主在跑 web-shell\n\n```mermaid\nflowchart LR\n  WS[\"web-shell dist\"]\n  S1[\"qwen serve（浏览器直接打开）\"] --\u003e|静态托管| WS\n  D[\"desktop（Tauri）\u003cbr/\u003espawn serve --port 0 --require-auth\"] --\u003e|加载| WS\n  M[\"mobile-shell（Android WebView）\"] --\u003e|加载 daemon 托管的页面| WS\n  V[\"vscode-ide-companion\u003cbr/\u003espawn serve --no-web --require-auth --allow-origin *\"] --\u003e|webview 内嵌| WS\n  MAS[\"managed-agent-server\"] -.-\u003e|managed 模式后端| WS\n```\n\n### 5.4 逐层调用代码：web-shell → sdk → serve → acp-bridge → `qwen --acp` → core\n\n§5.2 是时序，这里把每一跳落到代码上。先分清两种关系：**import**（同进程内调函数）和**协议**（跨进程）。五个包里只有三处是 import，另外两处是跨进程：\n\n```mermaid\nflowchart LR\n  subgraph P1[\"浏览器 / webview 进程\"]\n    WS[\"web-shell\u003cbr/\u003edaemon/session/actions.ts\"]\n    SDK[\"@qwen-code/sdk/daemon\u003cbr/\u003eDaemonSessionClient · DaemonClient · RestSseTransport\"]\n  end\n  subgraph P2[\"qwen serve 进程（packages/cli）\"]\n    RT[\"serve/routes/\u003cbr/\u003esession.ts · sse-events.ts · permission.ts\"]\n    BR[\"@qwen-code/acp-bridge\u003cbr/\u003esession-control-plane.ts · BridgeClient · EventBus · PermissionMediator\"]\n  end\n  subgraph P3[\"qwen --acp 子进程（packages/cli，每个工作区一个）\"]\n    AG[\"acp-integration/acpAgent.ts\u003cbr/\u003eQwenAgent\"]\n    SE[\"acp-integration/session/Session.ts\"]\n    CORE[\"core\u003cbr/\u003eLlmChat · ToolRegistry · tools\"]\n  end\n  WS --\u003e|import| SDK\n  SDK ==\u003e|\"HTTP：POST /session/:id/prompt\u003cbr/\u003eSSE：GET /session/:id/events\u003cbr/\u003ePOST /session/:id/permission/:requestId\"| RT\n  RT --\u003e|\"import（runtime.bridge）\"| BR\n  BR ==\u003e|\"spawn node cli.js --acp\u003cbr/\u003estdio ndjson ACP\"| AG\n  AG --\u003e SE --\u003e|import| CORE\n```\n\n粗箭头是跨进程。core 不知道 serve 和 web-shell 的存在，它只被 `qwen --acp` 子进程里的 `Session` 调用；serve 进程本身不跑 agent loop（hosted-harness profile 除外）。\n\n#### 下行：一次 prompt\n\n```mermaid\nsequenceDiagram\n  autonumber\n  participant WS as web-shell\u003cbr/\u003eactions.ts\n  participant SDK as sdk\u003cbr/\u003eDaemonSessionClient / DaemonClient\n  participant RT as serve\u003cbr/\u003eroutes/session.ts\n  participant CP as acp-bridge\u003cbr/\u003esession-control-plane.ts\n  participant AG as qwen --acp\u003cbr/\u003eQwenAgent\n  participant SE as Session.ts\n  participant C as core\u003cbr/\u003eLlmChat / tools\n  WS-\u003e\u003eSDK: session.submitPrompt(req)\n  SDK-\u003e\u003eRT: POST /session/:id/prompt\n  RT-\u003e\u003eCP: admitSessionPrompt → runtime.bridge.sendPrompt()\n  RT--\u003e\u003eSDK: 202 { promptId, lastEventId, eventEpoch }\n  CP-\u003e\u003eCP: 入队（每会话串行），回显 user_message 到事件总线\n  CP-\u003e\u003eAG: entry.connection.prompt(req)（ACP session/prompt）\n  AG-\u003e\u003eSE: session.prompt(params, ctx, signal)\n  SE-\u003e\u003eC: chat.sendMessageStream(...) / invocation.execute(...)\n```\n\n**① web-shell 发起**（`web-shell/client/daemon/session/actions.ts:1435`）：\n\n```ts\nasync sendPrompt(text, options) {\n  // …组装 promptRequest（prompt 块、附件引用、_meta: qwen.submittedPrompt 等）\n  accepted = await session.submitPrompt(promptRequest, ctrl.signal);\n  options?.onAdmitted?.({ promptId: accepted.promptId });\n  // 不等 HTTP 返回结果，而是等 SSE 上同一 promptId 的 turn 结束事件\n  return await waitForAcceptedPromptCompletion(activePrompts, settled, sessionId, ctrl, accepted.promptId);\n}\n```\n\n`session` 是 SDK 的 `DaemonSessionClient`，由 `DaemonSessionProvider.tsx` 创建并持有。\n\n**② SDK 发 HTTP**（`sdk-typescript/src/daemon/DaemonSessionClient.ts:759`、`DaemonClient.ts:7082`）：\n\n```ts\n// DaemonSessionClient：带上 clientId，clientId 失效时自动重新注册再重试\nasync submitPrompt(req, signal, beforeDispatch) {\n  return this.withClientIdSelfHeal(() =\u003e\n    this.client.promptNonBlocking(this.sessionId, req, signal, this.clientId));\n}\n\n// DaemonClient：非阻塞提交，serve 回 202\nasync promptNonBlocking(sessionId, req, signal, clientId) {\n  const res = await this.transport.fetch(`${this.baseUrl}/session/${urlEncode(sessionId)}/prompt`, {\n    method: 'POST',\n    headers: this.headers({ 'Content-Type': 'application/json' }, clientId), // Bearer + X-Qwen-Client-Id\n    body: JSON.stringify(req),\n    signal,\n  });\n  if (res.status === 202) return await res.json(); // { promptId, lastEventId, eventEpoch }\n  // …\n}\n```\n\n**③ serve 路由收下，交给 bridge**（`cli/src/serve/routes/session.ts:7697`、`routes/session-prompt-admission.ts:295`）：\n\n```ts\napp.post('/session/:id/prompt', mutate(), withOwnerMutableSession(async (req, res, runtime) =\u003e {\n  const admission = admitSessionPrompt(deps, {\n    runtime, sessionId, prompt, request: forwardedBody, idempotencyKey, clientId, signal: abort.signal,\n  });\n  res.status(202).json({\n    promptId: admission.promptId,\n    lastEventId: admission.lastEventId,   // 客户端从这里开始订阅，不丢事件\n    eventEpoch: admission.eventEpoch,\n  });\n}, { promptAdmission: true }));\n\n// admitSessionPrompt 里：\nconst ownerBridge = runtime.bridge;\npromptPromise = ownerBridge.sendPrompt(sessionId, request, signal, { promptId, clientId, /* … */ });\n```\n\n`runtime.bridge` 在 serve 启动工作区运行时时创建（`cli/src/serve/run-qwen-serve.ts:6447`）：`runtime.createAcpSessionBridge({...})`，工厂来自 `@qwen-code/acp-bridge/bridge`，经 `serve/acp-session-bridge.ts` 转出。\n\n**④ acp-bridge 排队，然后通过 ACP 发给子进程**（`acp-bridge/src/session-control-plane.ts:11439`、`:12026`）：\n\n```ts\nsendPrompt(sessionId, req, signal, context) {\n  // 校验、分配 promptId、进每会话队列（满了抛 PromptQueueFullError）、挂 deadline\n  // …轮到它时：\n  echoPromptToSessionBus(entry, { ...promptRequest, prompt: dispatchBlocks }, promptId, originatorClientId);\n  const promptPromise = entry.connection\n    .prompt(promptRequest)            // ACP session/prompt，走 stdio\n    .then((response) =\u003e { /* turn_complete 广播、收尾后台 turn */ return response; });\n}\n```\n\n`entry.connection` 是 `@agentclientprotocol/sdk` 的 `ClientSideConnection`，Client 这一侧的实现是 `BridgeClient`（`acp-bridge/src/channel-connection.ts:350`）：\n\n```ts\nexport function createHarnessConnection(client: Client, channel: AcpChannel) {\n  return new ClientSideConnection(() =\u003e client /* BridgeClient */, channel.stream);\n}\n```\n\n`channel` 来自 `spawnChannel.ts:549`，就是拉起子进程：\n\n```ts\nchild = spawn(\n  process.execPath,\n  [...nodeArgs, cliEntry, '--acp', ...(options.extraArgs ?? [])],\n  { cwd: workspaceCwd, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32', env: childEnv },\n);\n```\n\n**⑤ 子进程：ACP agent 收到 prompt**（`cli/src/acp-integration/acpAgent.ts:3098`、`:3284`、`:7279`）：\n\n```ts\nexport async function runAcpAgent(config, settings, argv, …) {\n  output = createAcpOutput(process.stdout);\n  const stdin = Readable.toWeb(process.stdin);\n  console.log = console.error;                 // stdout 只留给 ACP 帧\n  const stream = ndJsonStream(output.stream, stdin, { /* 观测钩子 */ });\n  connection = new AgentSideConnection((conn) =\u003e {\n    agentInstance = new QwenAgent(config, settings, argv, conn, …);\n    return agentInstance;\n  }, stream);\n}\n\nclass QwenAgent implements Agent {\n  async prompt(params: PromptRequest) {\n    const session = this.sessions.get(normalizeSessionIdForLookup(params.sessionId)); // 一个子进程托管多个会话\n    // 剥离 / 校验 _meta（daemon 私有键只认受信父进程）\n    return await session.prompt(sanitizedParams, invocationContext, call.controller.signal, modelPrompt);\n  }\n}\n```\n\n**⑥ Session 调 core**（`cli/src/acp-integration/session/Session.ts:5911` → `#executePromptInner:7057`）：\n\n```ts\n// 模型轮：直接用 core 的 LlmChat，绕过 LlmClient（§8）\nconst chat = this.#getCurrentChat();\nsourceStream = await chat.sendMessageStream(model, { message, config: { abortSignal } }, promptId, goalPermit, …);\n\n// 工具：自己跑 runToolCalls，从 core 的 ToolRegistry 拿工具再执行，不经过 CoreToolScheduler\nconst registry = this.config.getToolRegistry();\nreturn invocation.execute(activeToolAbortSignal, onToolProgress, this.config.getShellExecutionConfig());\n```\n\n`Session.ts` 本身有 31 处 `@qwen-code/qwen-code-core/...` 深 import。\n\n#### 上行：事件流回到 web-shell\n\n```mermaid\nsequenceDiagram\n  autonumber\n  participant C as core\n  participant SE as Session.ts\n  participant BC as acp-bridge\u003cbr/\u003eBridgeClient\n  participant EB as EventBus（每会话）\n  participant RT as serve\u003cbr/\u003eroutes/sse-events.ts\n  participant SDK as sdk\u003cbr/\u003eRestSseTransport\n  participant WS as web-shell\u003cbr/\u003eDaemonSessionProvider\n  C--\u003e\u003eSE: StreamEvent / 工具结果\n  SE--\u003e\u003eBC: this.client.sessionUpdate(params)（ACP session/update）\n  BC-\u003e\u003eEB: prepareSessionUpdateFrames → events.publish(frame)\n  WS-\u003e\u003eSDK: activeSession.events({ signal })\n  SDK-\u003e\u003eRT: GET /session/:id/events（Last-Event-ID）\n  RT-\u003e\u003eEB: runtime.bridge.subscribeEvents(sessionId, { lastEventId, epoch })\n  EB--\u003e\u003eRT: 帧\n  RT--\u003e\u003eSDK: res.write(SSE)\n  SDK--\u003e\u003eWS: 解析后的 DaemonEvent → store.dispatch\n```\n\n关键代码：\n\n```ts\n// 子进程 Session.ts:10818 —— 把模型/工具进度变成 ACP 通知\nawait this.client.sessionUpdate(params);\n\n// acp-bridge bridgeClient.ts:1227 —— 在 serve 进程里收到通知，按会话发到事件总线\nasync sessionUpdate(params: SessionNotification) {\n  const entry = this.resolveEntry(params.sessionId);\n  const prepared = this.prepareSessionUpdateFrames(params, entry);\n  for (const frame of prepared.frames) entry.events.publish(frame);\n}\n\n// serve routes/sse-events.ts:182 / :393 —— 订阅总线，写成 SSE\napp.get('/session/:id/events', async (req, res) =\u003e {\n  const iterable = runtime.bridge.subscribeEvents(sessionId, { signal, lastEventId, epoch: eventEpoch });\n  for await (const event of iterable) res.write(/* id / event / data */);\n});\n\n// sdk RestSseTransport.ts:99-122 —— 带 Last-Event-ID 断线续传\nheaders['Last-Event-ID'] = String(opts.lastEventId);\nurl = `${this.baseUrl}/session/${encodeURIComponent(sessionId)}/events`;\n\n// web-shell DaemonSessionProvider.tsx:3971 —— 消费事件，进 reducer\nfor await (const event of activeSession.events({ signal: eventStreamController.signal, maxQueued })) {\n  // config_option_update / 消息块 / 工具卡片 / permission_request / turn_complete …\n}\n```\n\n#### 权限：两段跨进程的往返\n\n子进程里的权限请求是一个**挂起的 ACP 请求**，要等浏览器里有人投票才返回：\n\n```mermaid\nsequenceDiagram\n  participant SE as Session.ts（子进程）\n  participant BC as BridgeClient（serve）\n  participant PM as PermissionMediator（serve）\n  participant WS as web-shell\n  SE-\u003e\u003eBC: client.requestPermission(params)（ACP，挂起）\n  BC-\u003e\u003eBC: events.publish(permission_request)\n  BC-\u003e\u003ePM: 登记请求，等投票\n  Note over WS: SSE 收到 permission_request，弹审批卡片\n  WS-\u003e\u003eBC: POST /session/:id/permission/:requestId\u003cbr/\u003e→ routes/permission.ts:47 → bridge.respondToSessionPermission\n  BC-\u003e\u003ePM: 投票（校验会话归属、clientId、local-only 策略）\n  PM--\u003e\u003eBC: 决议\n  BC--\u003e\u003eSE: ACP 响应 { outcome }\n```\n\n```ts\n// 子进程 Session.ts:15096 —— 排队发出权限请求（同一会话串行）\n: this.client.requestPermission(params)\n\n// web-shell actions.ts:2510 → sdk DaemonClient.ts:7291\nasync respondToPermission(requestId, response) {\n  return session.respondToSessionPermission(requestId, response);\n}\nasync respondToSessionPermission(sessionId, requestId, response, clientId) {\n  return this.fetchWithTimeout(\n    `${this.baseUrl}/session/${urlEncode(sessionId)}/permission/${urlEncode(requestId)}`,\n    { method: 'POST', headers: this.headers({ 'Content-Type': 'application/json' }, clientId), body: JSON.stringify(response) },\n    …);\n}\n\n// serve routes/permission.ts:47 → acp-bridge session-control-plane.ts:12503\napp.post('/session/:id/permission/:requestId', mutate(), async (req, res) =\u003e {\n  accepted = runtime.bridge.respondToSessionPermission(sessionId, requestId, response, { clientId, fromLoopback });\n});\n```\n\n#### 一张表：谁调谁、靠什么\n\n| 调用方 → 被调方 | 方式 | 入口 |\n|---|---|---|\n| web-shell → sdk | import `@qwen-code/sdk/daemon` | `DaemonSessionClient.submitPrompt / events / respondToSessionPermission` |\n| sdk → serve | HTTP + SSE（Bearer、`X-Qwen-Client-Id`、`Last-Event-ID`） | `POST /session/:id/prompt`、`GET /session/:id/events`、`POST /session/:id/permission/:requestId` |\n| serve → acp-bridge | import（同进程，`runtime.bridge`） | `sendPrompt`、`subscribeEvents`、`respondToSessionPermission` |\n| acp-bridge → `qwen --acp` | spawn + stdio ndjson ACP（`ClientSideConnection` / `BridgeClient`） | `session/prompt` 下行；`session/update`、`session/request_permission`、`qwen/notify/*` 上行 |\n| `qwen --acp` → core | import（同进程） | `LlmChat.sendMessageStream`、`ToolRegistry` → `invocation.execute` |\n| sdk / acp-bridge → core | 只有常量和纯函数 import（sdk 构建时 inline），**不调运行时** | 见 §4.2 |\n\n---\n\n## 6. 专题：谁依赖 SDK，谁依赖 ACP\n\n### 6.1 `@qwen-code/sdk`（sdk-typescript）\n\n```mermaid\nflowchart LR\n  subgraph USERS[\"使用方\"]\n    WS[\"web-shell\u003cbr/\u003e~450 import，/daemon 为主\"]\n    VSC[\"vscode-ide-companion\u003cbr/\u003e/daemon 11 + 根 2\"]\n    QL[\"qwen-live\u003cbr/\u003e/daemon\"]\n    CLI[\"cli（反向）\u003cbr/\u003eattach、channel worker、serve 部分路由、导出\"]\n    WT[\"web-templates（dev）\"]\n    EXT[\"外部用户\"]\n  end\n  SDK[\"@qwen-code/sdk\"]\n  subgraph SDKPARTS[\"SDK 内部\"]\n    Q[\"query()\u003cbr/\u003eProcessTransport\"]\n    D[\"/daemon\u003cbr/\u003eDaemonClient · RestSseTransport · AcpHttp/AcpWs\"]\n    P[\"/peer\u003cbr/\u003eUDS 跨会话\"]\n    MCP[\"qwen-serve-mcp bin\"]\n  end\n  WS --\u003e SDK\n  VSC --\u003e SDK\n  QL --\u003e SDK\n  CLI --\u003e SDK\n  WT -.-\u003e SDK\n  EXT --\u003e SDK\n  SDK --- Q\n  SDK --- D\n  SDK --- P\n  SDK --- MCP\n  Q --\u003e|\"spawn 内嵌 CLI\u003cbr/\u003e--input-format stream-json\u003cbr/\u003e29 个 flag · 16 种 control subtype\"| SJ{{\"qwen -p stream-json\u003cbr/\u003enonInteractiveCli.ts\"}}\n  D --\u003e|\"~206 个路由字面量\u003cbr/\u003e88 个 ACP 方法（acpRouteTable.ts）\"| SERVE{{\"qwen serve\"}}\n  P --\u003e|\"QWEN_HOME 或 ~/.qwen 下的 UDS\"| IPC{{\"core/src/ipc（peer）\"}}\n  MCP --\u003e SERVE\n  SDK -.-\u003e|\"构建时 inline 8 处常量/纯函数\"| CORE[\"core / acp-bridge\"]\n```\n\n同协议的其他语言 SDK：\n\n| SDK | stream-json `query()` | serve DaemonClient |\n|---|---|---|\n| sdk-typescript | ✅ | ✅ |\n| sdk-java | ✅（`TransportOptionsAdapter.java`） | ✅（`qwencode/.../daemon/DaemonClient.java`） |\n| sdk-python | ✅（`transport.py`） | — |\n\n### 6.2 \"ACP\" 的三层含义和各自依赖方\n\n| 含义 | 依赖方 |\n|---|---|\n| **`@agentclientprotocol/sdk` 库**（0.14.1） | cli（Agent 侧 `AgentSideConnection`）、acp-bridge（Client 侧）、qwen-live、vscode-ide-companion、channel-base。注意 sdk-typescript **不依赖**这个库，serve 的 `/acp` 也是手写 JSON-RPC 帧 |\n| **`@qwen-code/acp-bridge` 包** | 声明：cli、vscode-ide-companion（dep）、sdk-typescript（dev，inline）、web-shell（dev）。实际：cli 117 个文件（serve 为主，另有 acp-integration、runtime）、sdk 4 个文件、web-shell 1 个、VS Code 1 个（`logRedaction`） |\n| **`qwen --acp` 协议（stdio）的调用方** | ① serve 的 acp-bridge（主要用户，用了全部 149 个方法里的大部分私有扩展 `qwen/status/*`、`qwen/control/*`、`craft/*`、`qwen/notify/*`）② Zed（只用标准方法）③ VS Code 直连模式（标准方法 + 5 个旧 ext）④ channels `AcpBridge`（标准方法 + 少量 `qwen/control/session/*`）⑤ qwen-live `acp-adaptor` ⑥ node-repl desktop-relay（经 serve 中转） |\n\n```mermaid\nflowchart LR\n  subgraph PARENTS[\"谁 spawn qwen --acp\"]\n    BR[\"acp-bridge（在 qwen serve 里）\"]\n    ZED[\"Zed 扩展\"]\n    VSC[\"VS Code 直连\"]\n    CHB[\"channel-base AcpBridge\u003cbr/\u003e（qwen channel start）\"]\n    QL[\"qwen-live acp-adaptor\"]\n  end\n  AG[\"qwen --acp\u003cbr/\u003ecli/src/acp-integration/acpAgent.ts\u003cbr/\u003eclass QwenAgent implements Agent\"]\n  BR --\u003e|\"标准方法 + 大量私有 ext\u003cbr/\u003e⇄ qwen/notify/*\"| AG\n  ZED --\u003e|标准方法| AG\n  VSC --\u003e|\"标准 + 5 个旧 ext\"| AG\n  CHB --\u003e|\"标准 + qwen/control/session/*\"| AG\n  QL --\u003e|\"标准 + live ext\"| AG\n  AG --\u003e SESSION[\"session/Session.ts\u003cbr/\u003e多会话 Map，按 sessionId 路由\"]\n  SESSION --\u003e CORE[\"core\"]\n\n  HTTPACP[\"serve /acp HTTP+SSE / WS\u003cbr/\u003eacp-http/dispatch.ts\u003cbr/\u003e13 标准 + 74 个 _qwen/*\"] --\u003e BR\n  SDKD[\"sdk AcpHttp/AcpWsTransport\u003cbr/\u003e（默认不启用）\"] -.-\u003e HTTPACP\n  CHREXT[\"chrome-extension\"] --\u003e HTTPACP\n```\n\n### 6.3 专题：qwen-code 里的 \"channel\" 是什么\n\n\"channel\" 在代码里有三个互不相干的意思，读代码时很容易混：\n\n| # | 意思 | 在哪 | 一句话 |\n|---|---|---|---|\n| A | **IM / 代码平台渠道**（产品功能） | `packages/channels/*`、`settings.json` 的 `channels`、`qwen channel …`、serve 的 `channel-*.ts` | 把 Telegram、微信、钉钉、飞书、企业微信、QQ、邮件、GitHub、GitLab 等的消息接进来，交给 agent 处理，再把回复发回去 |\n| B | **`--channel` 启动参数**（客户端身份） | `cli/src/config/config.ts:280`、`acp-channel-fallback.ts` | 标记\"谁启动了这个 CLI\"：`VSCode / ACP / SDK / CI / desktop / daemon`。**只用于上报统计** |\n| C | **`AcpChannel`**（进程间传输） | `acp-bridge/src/channel.ts`、`spawnChannel.ts`、`inMemoryChannel.ts` | acp-bridge 和 `qwen --acp` 子进程之间的那根 stdio 管道（测试里换成内存管道） |\n\n另外还有一些名字里带 channel 的东西，都从属于 A：会话的 `sourceType: 'channel'`（web-shell 历史列表里过滤掉的就是这类会话）、`qwen.channel.*` 这组 `_meta` 键、`channel_loop` MCP 工具（让 channel 会话创建定时提醒，代替 `cron_create`）。npm 的 `latest / nightly` 在代码里叫 `distTag`，不叫 channel。\n\n#### A. IM / 代码平台渠道\n\n**规模**：`channels/base` 约 2.1 万行；各平台适配器 dingtalk 8.4k、qqbot 8.8k、github 9.6k、dws 4.8k、feishu 4.1k、email 2.7k、wecom 2.7k、weixin 2k、telegram 0.7k、gitlab 0.6k。cli 里还有 `commands/channel/`（约 40 个文件）和 `serve/channel-*.ts`（约 25 个文件）。\n\n**用户怎么配**（`docs/users/features/channels/overview.md`）：\n\n```json\n{\n  \"channels\": {\n    \"my-channel\": {\n      \"type\": \"telegram\",\n      \"token\": \"$MY_BOT_TOKEN\",\n      \"privatePolicy\": \"allowlist\",\n      \"allowedUsers\": [\"123456789\"],\n      \"sessionScope\": \"user\",\n      \"cwd\": \"/path/to/working/directory\",\n      \"instructions\": \"Optional system instructions for the agent.\",\n      \"groupPolicy\": \"disabled\",\n      \"groups\": { \"*\": { \"requireMention\": true } }\n    }\n  }\n}\n```\n\n**分层**：\n\n```mermaid\nflowchart TB\n  subgraph PLAT[\"外部平台\"]\n    TG[\"Telegram / 微信 / 钉钉 / 飞书 / QQ\u003cbr/\u003e邮件 / GitHub / GitLab …\"]\n  end\n  subgraph ADP[\"平台适配器（channel-* 或扩展里的插件）\"]\n    PL[\"ChannelPlugin\u003cbr/\u003e{ channelType, createChannel() }\"]\n    CH[\"XxxChannel extends ChannelBase\u003cbr/\u003econnect() · sendMessage() · disconnect()\"]\n  end\n  subgraph BASE[\"@qwen-code/channel-base\"]\n    CB[\"ChannelBase.handleInbound(envelope)\"]\n    GATE[\"SenderGate / DmGate / GroupGate\u003cbr/\u003e白名单 · 配对 · 群里是否 @\"]\n    RT[\"SessionRouter\u003cbr/\u003e(channel, sender, chat, thread) → sessionId\u003cbr/\u003esessionScope: user | thread | chat_thread | single\"]\n    IF{{\"ChannelAgentBridge 接口\u003cbr/\u003enewSession · prompt · 事件\"}}\n    ACPB[\"AcpBridge\u003cbr/\u003e自己 spawn qwen --acp\"]\n    DCB[\"DaemonChannelBridge\u003cbr/\u003e经 sdk 连 qwen serve\"]\n  end\n  TG \u003c--\u003e|\"webhook / 长轮询 / WS\"| CH\n  PL --\u003e CH\n  CH --\u003e|入站消息| CB --\u003e GATE --\u003e RT --\u003e IF\n  IF --\u003e ACPB\n  IF --\u003e DCB\n  IF -.-\u003e|\"回复分块 / 工具事件\"| CH\n  CH --\u003e|\"sendMessage(chatId, text)\"| TG\n```\n\n**两种运行方式**：\n\n```mermaid\nflowchart LR\n  subgraph A1[\"独立模式：qwen channel start\"]\n    CB1[\"channel-* + channel-base\u003cbr/\u003e（cli 进程内）\"] --\u003e|\"AcpBridge：spawn node cli.js --acp\"| AG1[\"qwen --acp\"]\n  end\n  subgraph B1[\"daemon 模式：serve 托管\"]\n    SV[\"qwen serve\u003cbr/\u003echannel-worker-supervisor.ts\"] --\u003e|\"spawn cli.js channel daemon-worker\"| W[\"worker 进程\u003cbr/\u003ecommands/channel/daemon-worker.ts\"]\n    W --\u003e|\"DaemonChannelBridge → sdk DaemonSessionClient\u003cbr/\u003eHTTP + SSE\"| SV\n    SV --\u003e|acp-bridge| AG2[\"qwen --acp\"]\n  end\n```\n\ndaemon 模式下，channel 会话就是 serve 里的普通会话（`sourceType: 'channel'`），所以 web-shell 也能看到它，权限审批可以在 web-shell 里投票。\n\n**一条消息的完整路径**：\n\n```mermaid\nsequenceDiagram\n  autonumber\n  participant P as 平台（如 Telegram）\n  participant CH as XxxChannel\n  participant CB as ChannelBase\n  participant R as SessionRouter\n  participant BR as ChannelAgentBridge\n  participant AG as qwen --acp（直连或经 serve）\n  P-\u003e\u003eCH: 入站消息\n  CH-\u003e\u003eCB: handleInbound(envelope)\n  CB-\u003e\u003eCB: preflightInbound：门禁、配对、群 @、消息路由前缀（/review …）\n  CB-\u003e\u003eR: router.resolve(channel, sender, chat, thread, cwd, isGroup)\n  R--\u003e\u003eCB: sessionId（没有就 bridge.newSession）\n  CB-\u003e\u003eBR: bridge.prompt(sessionId, text, { images, outputMode, … })\n  BR-\u003e\u003eAG: ACP session/prompt 或 POST /session/:id/prompt\u003cbr/\u003e_meta: qwen.channel.prompt = true\n  AG--\u003e\u003eBR: 流式回复 / 工具事件\n  BR--\u003e\u003eCB: 回复分块事件\n  CB-\u003e\u003eCH: onResponseChunk / sendMessage(chatId, text)\n  CH-\u003e\u003eP: 出站消息\n```\n\n关键代码：\n\n```ts\n// 1. 平台适配器：一个插件就是一个工厂（channels/plugin-example/src/index.ts）\nexport const plugin: ChannelPlugin = {\n  channelType: 'plugin-example',\n  displayName: 'Plugin Example',\n  requiredConfigFields: ['serverWsUrl'],\n  createChannel: (name, config, bridge, options) =\u003e new MockPluginChannel(name, config, bridge, options),\n};\n\n// 2. 适配器只做\"平台消息 ⇄ Envelope\"（MockPluginChannel.ts）\nclass MockPluginChannel extends ChannelBase {\n  private onInboundMessage(msg: InboundMessage) {\n    this.handleInbound({ channelName: this.name, senderId: msg.senderId, senderName: msg.senderName,\n                         chatId: msg.chatId, text: msg.text, isGroup: false, isMentioned: false, isReplyToBot: false });\n  }\n  async sendMessage(chatId: string, text: string) { this.sendOutbound(chatId, text); }\n}\n\n// 3. 公共逻辑在 ChannelBase（channel-base/src/ChannelBase.ts:492、:6745、:7239）\nexport abstract class ChannelBase {\n  abstract connect(): Promise\u003cvoid\u003e;\n  abstract sendMessage(chatId: string, text: string): Promise\u003cvoid\u003e;\n  abstract disconnect(): void | Promise\u003cvoid\u003e;\n\n  async handleInbound(envelope: Envelope) {\n    if (!(await this.preflightInbound(envelope))) return;   // 门禁 / 配对 / 路由\n    await this.processPreflightedInbound(envelope);\n  }\n  // processPreflightedInbound 里：\n  //   sessionId = await this.router.resolve(this.name, envelope.senderId, envelope.chatId,\n  //                                         envelope.threadId, this.config.cwd, envelope.isGroup, …);\n  //   … this.bridge.prompt(sessionId, text, options)\n}\n```\n\n内置适配器在 `cli/src/commands/channel/channel-registry.ts:407` 按需 `import('@qwen-code/channel-telegram')` 等加载；第三方适配器通过扩展的 `qwen-extension.json` 声明：\n\n```json\n{ \"name\": \"qwen-channel-plugin-example\",\n  \"channels\": { \"plugin-example\": { \"entry\": \"dist/index.js\", \"displayName\": \"Plugin Example Channel\" } } }\n```\n\n`ChannelAgentBridge` 的两个实现：\n\n```ts\n// 独立模式：channel-base/src/AcpBridge.ts:165 —— 自己拉一个 ACP 子进程\nconst args = [...process.execArgv, cliEntryPath, '--acp'];\nthis.child = spawn(process.execPath, args, {\n  cwd, stdio: ['pipe', 'pipe', 'pipe'],\n  env: { ...process.env, QWEN_CODE_DISABLE_CRON: '1',\n         QWEN_CODE_PRIVATE_ACP_CAPABILITY: privateParentCapability }, // 受信父进程凭据\n});\nthis.connection = new ClientSideConnection(…);\n\n// daemon 模式：channel-base/src/DaemonChannelBridge.ts:826 —— 经 sdk 走 serve\nresult = await session.prompt({\n  prompt,\n  _meta: {\n    'qwen.channel.prompt': true,                       // serve 只对已认证的 channel worker 认这个键\n    ...(options?.outputMode === 'per_task' ? { 'qwen.channel.outputMode': 'per_task' } : {}),\n  },\n});\n```\n\ndaemon 模式的 worker 由 serve 拉起（`cli/src/serve/channel-worker-supervisor.ts:1057`），worker 里用 SDK 回连 serve（`commands/channel/daemon-worker.ts:1064`）：\n\n```ts\n// serve 侧\nconst argv = [opts.cliEntryPath, 'channel', 'daemon-worker', ...selectionChannelArgs(opts.selection)];\nconst env = createWorkerEnv({ daemonUrl, workspace, daemonToken });   // 带一次性 prompt 授权凭据\n\n// worker 侧\nconst bridge = new DaemonChannelBridge({\n  cwd: daemonWorkspace,\n  sessionFactory: createDaemonSessionFactory({\n    client, DaemonSessionClient: sdk.DaemonSessionClient,\n    clientId: `qwen-channel-worker:${process.pid}`,\n  }),\n  sessionPermissionVote: capabilities.features.includes(SESSION_PERMISSION_VOTE_FEATURE),\n});\n```\n\n#### B. `--channel` 启动参数\n\n```ts\n// cli/src/config/config.ts:280\nchannel: {\n  type: 'string',\n  choices: ['VSCode', 'ACP', 'SDK', 'CI', 'desktop', 'daemon'],\n  description: 'Channel identifier (VSCode, ACP, SDK, CI, desktop, daemon)',\n},\n```\n\n谁传什么：\n\n| 启动方 | 值 | 怎么来的 |\n|---|---|---|\n| VS Code 插件 | `VSCode` | `acpConnection.ts` 显式传 `--channel=VSCode` |\n| SDK `query()` | `SDK` | `sdk-typescript/src/transport/ProcessTransport.ts:320` 显式传 `--channel=SDK` |\n| serve 拉起的 `--acp` 子进程 | `daemon` | 不传参数；acp-bridge 设 `QWEN_CODE_SERVE=1`，子进程回退时识别 |\n| Tauri desktop 经 serve | `desktop` | desktop 设 `QWEN_CODE_DESKTOP=1`，子进程继承 |\n| 其他 `--acp`（Zed 等） | `ACP` | 默认回退值 |\n\n```ts\n// cli/src/config/acp-channel-fallback.ts\nexport function resolveAcpChannelFallback(env = process.env): string {\n  if (env['QWEN_CODE_DESKTOP'] === '1') return 'desktop';\n  if (env['QWEN_CODE_SERVE'] === '1') return 'daemon';\n  return 'ACP';\n}\n\n// core/src/telemetry/qwen-logger/qwen-logger.ts:356 —— 唯一的读取方\n...(this.config?.getChannel?.() ? { channel: this.config.getChannel() } : {}),\n```\n\n`Config.getChannel()` 在 core 里只有这一个调用方，所以它**不影响任何行为**，只是 RUM 上报里的一个维度。另外注意：daemon 模式下的 IM channel 会话，上报的 `channel` 是 `daemon`，不是 IM 平台名。\n\n#### C. `AcpChannel`（acp-bridge 的传输）\n\n```ts\n// acp-bridge/src/channel.ts:28\nexport interface AcpChannel {\n  stream: Stream;                       // ACP ndjson 双向流\n  transportFailed?: Promise\u003cunknown\u003e;\n  transportGuard?: AcpChannelTransportGuard;\n  kill(): Promise\u003cvoid\u003e;\n  killSync(): void;\n}\nexport type ChannelFactory = (workspaceCwd: string, childEnvOverrides?, signal?, startup?) =\u003e Promise\u003cAcpChannel\u003e;\n```\n\n默认工厂是 `defaultSpawnChannelFactory`（`spawnChannel.ts:549`，拉起 `qwen --acp`，见 §5.4），测试用 `createInMemoryChannel()`。acp-bridge 里的 `channel-connection.ts`、`channel-lifecycle.ts`、`channel-liveness.ts`、`channel-startup.ts` 等十来个文件都是这个意思，和 A 无关。\n\n#### 我的看法\n\n1. **命名冲突的代价是真实的。** acp-bridge 里有大量 `channel-*.ts` 文件（意思 C），serve 里也有大量 `channel-*.ts` 文件（意思 A）。上报里的 `channel=daemon`（意思 B）又会把 A 的会话也算进去。新人在 serve 目录里看到 `channel-worker-*` 和 `managed-engine-channel-factory.ts` 放在一起，很难分清哪个是 IM、哪个是传输。建议：\n   - B 改名为 `--client` / `clientKind`，并保留 `--channel` 作为别名。它本来就是\"客户端身份\"，而且只影响统计。\n   - C 改名为 `AcpTransport`（`ChannelFactory` → `AcpTransportFactory`），只在 acp-bridge 内部，改动面小。\n   - \"Channel\" 只留给 A。\n2. **A 是一个独立的产品子系统，体量和 web-shell 相当。** channel-base 加适配器约 6.5 万行，再加上 cli 里的命令和 serve 托管代码。它通过 `ChannelAgentBridge` 接口和 agent 解耦，有两个实现，这个抽象做得好。问题在依赖方向：cli 依赖全部 10 个 `channel-*` 包（§4.2），等于把所有平台 SDK 都塞进了 CLI 安装包。更合理的是内置适配器也按扩展的方式按需安装，cli 只依赖 `channel-base`。\n3. **两种运行方式长期并存，有重复。** 独立模式（`AcpBridge`）和 daemon 模式（`DaemonChannelBridge`）各自实现了会话管理、权限、附件和私有 `_meta`。daemon 模式能被 web-shell 看到、审批和恢复，能力更全。建议把 daemon 模式作为默认，独立模式只保留给\"不想常驻 serve\"的场景，新功能先只做 daemon 模式。\n4. **对融合的影响**：A 是 Qwen 独有的产品能力，按融合方案的规则应放在 Qwen 产品层；它通过 `qwen --acp`（独立模式）或 serve（daemon 模式）接入，依赖的是 ACP 私有扩展（`qwen/control/session/*`、`qwen/control/session/btw`）和 `qwen.channel.*` 这组 `_meta` 键。切到新内核时，这些都要列进兼容清单。\n\n### 6.4 专题：为什么把 daemon 客户端放进 SDK，以及这样做的得失\n\n#### 当初的理由\n\ndaemon 客户端是在 `qwen serve` 第一阶段（#3889，2026-05-13，设计 issue #3803）里和 serve 一起加进 `@qwen-code/sdk` 的。提交说明给了三条理由：\n\n1. **验证\"协议同构\"**：SDK 客户端可以不走 `query()` 的 stdio + stream-json，直接通过 HTTP 驱动 daemon，端到端跑通。\n2. **和 `query()` 并列，不替代它**：`DaemonClient` is a sibling of ProcessTransport, not a replacement. `query()` 用户不受影响；需要 daemon 模式能力的应用（多客户端 attach、共享 MCP 池、网络可达、先到先得的权限投票）自己选择 `new DaemonClient(...)`。\n3. **wire 类型放在 SDK 一侧，SDK 不依赖 CLI**（\"Wire types live SDK-side (no SDK→CLI dep)\"），兼容性靠 `/capabilities` 的 `v` 和 `features` 协商。\n\n官方文档 `docs/developers/daemon/13-sdk-daemon-client.md` 把它定位成\"连接 `qwen serve` 的**标准**方式……其他所有适配器都依赖它\"。入口在 SDK 根导出和子路径里都有（`sdk-typescript/src/index.ts`）：\n\n```ts\nexport { query } from './query/createQuery.js';      // 模式一：spawn CLI，走 stream-json\nexport { Query } from './query/Query.js';\n// Daemon HTTP client (talks to `qwen serve`)          // 模式二：HTTP + SSE 连 serve\nexport { DaemonClient, DaemonSessionClient, WorkspaceDaemonClient, … } from './daemon/index.js';\n```\n\n```jsonc\n// sdk-typescript/package.json exports\n\".\":                   \"./dist/index.mjs\",\n\"./daemon\":            \"./dist/daemon/index.js\",       // web-shell / VS Code 用这个\n\"./daemon/transports\": \"./dist/daemon/transports.js\",  // RestSse / AcpHttp / AcpWs\n\"./daemon/transcript\": \"./dist/daemon/transcript.js\",\n\"./daemon/ui\":         \"./dist/daemon/ui/index.js\",    // normalizer + transcript reducer + 渲染辅助\n\"./peer\":              \"./dist/peer/index.js\"\n```\n\n#### 现在长成了什么样\n\n```mermaid\nflowchart TB\n  subgraph SDKPKG[\"@qwen-code/sdk（仓库 0.1.32；npm 最新 0.1.35 解包 81 MB / 904 个文件）\"]\n    direction LR\n    Q[\"query()\u003cbr/\u003e约 1 万行（含 peer 等）\u003cbr/\u003e需要 CLI\"]\n    D[\"daemon/\u003cbr/\u003e约 4 万行\u003cbr/\u003eDaemonClient 10k · types 6.3k · events 3.5k\u003cbr/\u003eDaemonSessionClient 1.8k · ACP 传输\"]\n    UI[\"daemon/ui/\u003cbr/\u003enormalizer 2.4k · transcript 3k\u003cbr/\u003eUI 状态机\"]\n    CLIB[[\"dist/cli.js\u003cbr/\u003eprepack 时打进来的整个 CLI\"]]\n  end\n  Q --\u003e CLIB\n  WS[\"web-shell（浏览器）\"] --\u003e|\"/daemon、/daemon/ui\"| D \u0026 UI\n  VSC[\"VS Code 插件\"] --\u003e|\"/daemon\"| D\n  QL[\"qwen-live\"] --\u003e D\n  CLI[\"cli 自己\u003cbr/\u003eattach · channel worker · serve 路由\"] --\u003e|\"/daemon、/daemon/ui\u003cbr/\u003e（serve 用 SDK 里的类型当 wire 契约）\"| D\n  EXT[\"外部：QwenMate 等\"] --\u003e|\"根导出 query()\"| Q\n  D -. \"构建时 inline 常量 / 纯函数\u003cbr/\u003etypes-sync.ts 编译期断言两边类型一致\" .-\u003e BRC[\"acp-bridge / core\"]\n```\n\n几个从代码里看出来的事实：\n\n**① daemon 已经是 SDK 的主体。** `src/daemon` 非测试代码约 4 万行，SDK 其余部分约 1 万行。\"SDK 的一个功能\"已经变成\"SDK 主要就是 daemon 客户端\"。\n\n**② SDK 实际上成了协议定义包。** serve（服务端）反过来从客户端 SDK 导入 wire 类型：\n\n```ts\n// cli/src/serve/routes/subscription-auth.ts\nimport type { DaemonSubscriptionFlow } from '@qwen-code/sdk/daemon';\n// cli/src/serve/routes/daemon-update.ts\nimport type { DaemonUpdateStatus } from '@qwen-code/sdk/daemon';\n// cli/src/serve/web-shell-preauth.ts\nimport { WEB_SHELL_PWA_ASSETS } from '@qwen-code/sdk/daemon';\n```\n\n同时 SDK 又从 acp-bridge / core 导入常量（构建时 inline），并且在 `daemon/types-sync.ts` 里用编译期断言保证自己的副本和 acp-bridge 那份一致：\n\n```ts\nimport type { BridgePendingPermissionInteraction } from '@qwen-code/acp-bridge/bridgeTypes';\nimport type { DaemonPendingPermissionInteraction } from './types.js';\n\ntype PendingPermissionInteractionStaysInSync = Assert\u003c\n  MutuallyAssignable\u003cBridgePendingPermissionInteraction, DaemonPendingPermissionInteraction\u003e\n\u003e;\n```\n\n也就是说，同一份契约有两处定义（`acp-bridge/bridgeTypes.ts` 和 `sdk/daemon/types.ts`），靠断言保持一致；服务端还会反向引用客户端那份。§11 第 1 条说的依赖环就是这么来的。\n\n**③ 一个包装了两种很不一样的东西。** `query()` 需要一个 CLI 可执行文件，所以 `prepack` 会跑 `bundle:cli`，把整个 CLI 打进 SDK（`scripts/bundle-cli.js`：\"so consumers don't need a separate CLI install\"）。daemon 客户端只是 HTTP 客户端，`src/daemon` 里没有任何 `node:` 导入，可以直接在浏览器里跑。结果是只想要 `DaemonClient` 的使用方（浏览器前端、服务端后台、别的 IDE 插件）也要下载 81 MB 的 CLI。\n\n**④ 版本号和 serve 分开。** SDK 是 0.1.32，CLI 是 0.27.2，靠 `capabilities.features` 做兼容。真正需要版本错开容忍的只有外部使用方；web-shell 和 VS Code 插件都是和 serve 同一次构建发布的。\n\n#### 我的看法\n\n**放在 SDK 里，大方向是对的。**\n\n- 同一个协议只有一个官方客户端。bearer + `X-Qwen-Client-Id`、clientId 失效后自愈重试、SSE 的 `Last-Event-ID` / epoch 续传、超时要覆盖 body 读取但不能杀掉长连接 SSE，这些细节都很难写对（见 §5.4 的代码和 `13-sdk-daemon-client.md` 里的 `fetchWithTimeout` 说明）。web-shell、VS Code、qwen-live、`qwen attach`、channel worker 共用一份，比各写一份强得多。\n- 自己的产品用的就是对外发布的那份客户端，公开 API 的质量有保障。\n- `daemon/` 保持浏览器安全（不导入 `node:`），所以 web-shell 能直接用。这个约束守得很好。\n\n**问题出在包的切分，不在放的位置。** 四件事放进了同一个发布单元：协议定义、HTTP 客户端、UI 状态机、CLI 运行时。后果是：\n\n1. **协议没有自己的家。** 服务端引用客户端的类型，客户端 inline 服务端的常量，两份类型靠断言同步。协议应该是双方都依赖的第三个包，而不是放在任何一方里。\n2. **体积和依赖错配。** daemon 使用方被迫带上 CLI bundle。\n3. **语义化版本被绑在一起。** `query()` 用户（例如 QwenMate，见 IDE 集成建议 §1.5）和 daemon 用户共用一个版本号。daemon 协议迁到 serve v2 时，SDK 升到 1.x 会连带波及只用 `query()` 的人，这正是 IDE 文档 §4.5 担心的事。\n4. **UI 状态机放进了 SDK。** `daemon/ui`（normalizer + transcript reducer，约 5.4k 行）是给渲染端用的，和\"连接 serve\"的客户端是两层东西。共享它没问题，但它的变化频率跟着 UI 走，不该和客户端绑在同一个版本号上。\n\n#### 建议的切分\n\n```mermaid\nflowchart LR\n  subgraph NOW[\"现在\"]\n    direction TB\n    S1[\"@qwen-code/sdk\u003cbr/\u003equery() + daemon 客户端 + daemon/ui + 协议类型 + CLI bundle\"]\n    SV1[\"serve（cli）\"] --\u003e|\"import type\"| S1\n    S1 -. \"inline + types-sync 断言\" .-\u003e BR1[\"acp-bridge / core\"]\n  end\n  subgraph NEXT[\"建议\"]\n    direction TB\n    PROTO[\"@qwen-code/protocol\u003cbr/\u003edaemon wire 类型 · 事件名 · 常量 · capabilities\u003cbr/\u003e（可由 OpenAPI 生成或反过来生成 OpenAPI）\"]\n    DC[\"@qwen-code/sdk/daemon\u003cbr/\u003e只有 HTTP/SSE 客户端，浏览器安全，无 CLI\"]\n    DUI[\"@qwen-code/sdk/daemon/ui\u003cbr/\u003e（或独立包）UI 状态机\"]\n    QRY[\"@qwen-code/sdk 根\u003cbr/\u003equery()；CLI 改为 optionalDependency\u003cbr/\u003e或优先用本机已装的 qwen\"]\n    SV2[\"serve（cli）\"] --\u003e PROTO\n    BR2[\"acp-bridge\"] --\u003e PROTO\n    DC --\u003e PROTO\n    DUI --\u003e DC\n  end\n  NOW --\u003e NEXT\n```\n\n1. **抽出 `@qwen-code/protocol`**（IDE 集成建议 §4.1 也建议把 IDE 协议放在这里）。serve、acp-bridge、SDK 都依赖它，删掉 `types-sync.ts` 和 serve 对 SDK 的反向 import。`docs/developers/daemon-rest-api.openapi.json` 已经存在，可以让协议包和 OpenAPI 互相生成，至少在 CI 里做一致性检查。\n2. **CLI bundle 移出 SDK 主包。** 变成 optionalDependency（例如 `@qwen-code/sdk-cli-runtime`），或者让 `query()` 优先找本机的 `qwen`，找不到才提示安装。daemon 使用方从 81 MB 降到几 MB。\n3. **导入路径不变，各子路径语义化版本独立。** `@qwen-code/sdk/daemon` 这个导入路径保持兼容，底下可以是独立发布的包再转出。daemon 协议升到 v2 时，只有 daemon 客户端升大版本，`query()` 用户不受影响。\n4. **`daemon/ui` 视情况独立。** 如果 UI 状态机的变更频率明显高于客户端，就拆成单独的包，让 web-shell 和 VS Code 锁定自己的版本。\n\n和融合方案的关系：融合后的\"SDK 1.x → serve v2\"本质上是 daemon 客户端和协议的大版本升级。先按上面切开，1.x 的破坏性变更就只落在 daemon 那一部分，`query()` 的外部用户可以继续留在 0.x。\n\n### 6.5 专题：qwen-live 是什么\n\n#### 一句话\n\n**Qwen Live 是一个\"语音指挥编码 agent\"的产品**：用户对着 macOS 上的小浮层说话，一个实时语音模型（DashScope `qwen3.5-omni-plus-realtime`）负责对话、判断意图，需要动手的事通过 `handoff` 工具交给一个或多个编码会话去做，结果再用语音播报回来。语音模型是\"前台\"，编码 agent 是\"后台工人\"。\n\n它由三个部分组成，而且有**两个实现**：\n\n| 部分 | 包 / 位置 | 规模 | 角色 |\n|---|---|---|---|\n| **Live daemon（独立版）** | `packages/qwen-live`，npm `@qwen-code/qwen-live`，bin `qwen-live` | 约 4.2 万行 | 控制面：连 Host、连实时语音模型、调度编码会话、记忆、主动提醒 |\n| **Live daemon（内置版）** | `packages/cli/src/serve/live/`（`qwen serve` 的 `/live/*` 路由） | 约 1.1 万行 | 同一件事的早期实现，挂在 serve 里，web-shell 设置里开关，默认关闭 |\n| **Live Host** | `packages/live-host`（Electron，macOS 专用） | 约 1.3 万行 | 原生\"外壳\"：浮层小球、全局快捷键 `⌘E`、麦克风 / 扬声器、摄像头、截屏（`appshot.mm`） |\n\n历史：内置版先出（#7859，2026-08-05，\"web-shell: add native Live Voice\"）；独立版后出（#10367，2026-09-01，\"standalone voice daemon package\"）。独立版 README 已经把\"连 `qwen serve`\"标成 Legacy 后端。\n\n和本文其他部分的关系：web-shell 的会话列表里过滤掉的 `sourceType: 'qwen-live'` 和 `sourceId` 前缀 `realtime_voice:`（见 IDE 集成建议 §1.3.2 的 EmbeddedApp 过滤代码），就是 Live 派出去的编码会话。\n\n#### 全景\n\n```mermaid\nflowchart LR\n  subgraph MAC[\"用户的 Mac\"]\n    HOST[\"Live Host（Electron）\u003cbr/\u003e浮层 · ⌘E · 麦克风 / 扬声器\u003cbr/\u003e摄像头 · 原生截屏\"]\n  end\n  DISC[(\"~/.qwen/live/daemon.json\u003cbr/\u003e发现文件：端口 · token · protocolVersion\")]\n  subgraph LIVE[\"Live daemon（二选一）\"]\n    SA[\"qwen-live（独立版）\u003cbr/\u003eLiveSession 编排器\"]\n    BI[\"qwen serve /live/*（内置版）\"]\n  end\n  OMNI([\"DashScope Realtime\u003cbr/\u003eqwen3.5-omni-plus-realtime\u003cbr/\u003eWebSocket：VAD · 语音对话 · 工具调用\"])\n  subgraph BACKENDS[\"编码后端（可多个，按会话路由）\"]\n    QA[\"AcpAdaptor\u003cbr/\u003espawn qwen --acp / qodercli --acp /\u003cbr/\u003egemini --experimental-acp / claude-agent-acp / codex-acp\"]\n    QS[\"QwenCodeAdaptor（Legacy）\u003cbr/\u003esdk DaemonClient → qwen serve\"]\n  end\n  MEM[(\"~/.qwen-live/\u003cbr/\u003econfig.json · sessions/*.jsonl\u003cbr/\u003ememories/ SQLite FTS5\")]\n\n  SA \u0026 BI --\u003e|写| DISC\n  HOST --\u003e|读| DISC\n  HOST \u003c--\u003e|\"WS /live/host（Live Host 协议 v9）\u003cbr/\u003e音频帧 · 截图 · 状态\"| SA\n  HOST \u003c-.-\u003e|同协议| BI\n  SA \u003c--\u003e|\"WS：音频 + 工具调用\"| OMNI\n  SA --\u003e|\"handoff / session_create …\"| QA \u0026 QS\n  SA --- MEM\n```\n\n要点：\n\n- **Host 不认 daemon 是哪一个**：两个 daemon 写同一个发现文件（`~/.qwen/live/daemon.json`）、开同一个 WS 路径（`/live/host`），Host 读到谁就连谁，并校验 `protocolVersion`。\n- **对话归 Live，任务归后端**：Live 自己的通话记录在 `~/.qwen-live/sessions/`；派给后端的编码会话是普通会话，挂断后继续跑。\n- **后端不限于 Qwen**：独立版通过 ACP 可以驱动 qodercli、Gemini、Claude Code、Codex。这是唯一一个把 qodercli 当作一等后端的仓内组件。\n\n#### 一次\"说一句话 → 改代码 → 播报结果\"\n\n```mermaid\nsequenceDiagram\n  autonumber\n  participant U as 用户\n  participant H as Live Host\n  participant L as qwen-live LiveSession\n  participant O as Omni Realtime\n  participant A as BackendAdaptor\n  participant B as 编码 agent（qwen --acp 等）\n  U-\u003e\u003eH: 说话（⌘E 开始通话）\n  H-\u003e\u003eL: WS 音频帧\n  L-\u003e\u003eO: 转发音频\n  O--\u003e\u003eL: 语音回复：\"好，我让编码会话去改\"\n  O--\u003e\u003eL: 工具调用 handoff({ task: 用户原话, session?, input_refs? })\n  L-\u003e\u003eA: adaptor.prompt(handle, blocks, { steer: busy })\n  A-\u003e\u003eB: ACP session/prompt（或 POST /session/:id/prompt）\n  L--\u003e\u003eO: 立即返回回执（accepted / queued / steered）\n  B--\u003e\u003eA: 流式进度、权限请求、完成\n  A--\u003e\u003eL: BackendEvent\n  L-\u003e\u003eO: Injector 注入 [COMPLETE] / 权限请求等静默上下文\n  O--\u003e\u003eH: 语音播报结果\n  H--\u003e\u003eU: 扬声器\n```\n\n#### 关键代码\n\n**① 语音模型能用的工具**（`qwen-live/src/tools/definitions.ts`）。Live 的\"能力\"就是这一组工具：\n\n```ts\nexport const APPSHOT_TOOL_NAME = 'appshot';                 // 截屏 / 摄像头取一帧\nexport const SESSION_LIST_TOOL_NAME = 'session_list';       // 列出所有后端的会话\nexport const SESSION_CREATE_TOOL_NAME = 'session_create';   // 开一个新的并行工作流\nexport const HANDOFF_TOOL_NAME = 'handoff';                 // 把任务交给编码会话\nexport const SESSION_MONITOR_TOOL_NAME = 'session_monitor';\nexport const SESSION_STOP_TOOL_NAME = 'session_stop';\nexport const RESPOND_PERMISSION_TOOL_NAME = 'respond_permission'; // 用语音回答后端的权限请求\nexport const CREATE_PROACTIVE_MONITOR_TOOL_NAME = 'create_proactive_monitor'; // 盯着屏幕，满足条件时提醒\nexport const CREATE_PROACTIVE_TIMER_TOOL_NAME = 'create_proactive_timer';\n// … 以及 memory 的 omniretrieve / omnibio\n\n// handoff 的定义（节选）\n{\n  name: HANDOFF_TOOL_NAME,\n  description:\n    \"Send the user's request to a coding session for execution. This is the default action for \" +\n    'anything that touches files, runs commands … Pass the user\\'s own words in `task`; do not rewrite them. ' +\n    'Returns a receipt immediately — the result arrives later as a [COMPLETE] context message. …',\n  parameters: {\n    type: 'object',\n    properties: {\n      task: { type: 'string', description: \"The user's request, in their own words.\" },\n      session: { type: 'string', description: 'Target session handle from session_list (e.g. \"session_1\").' },\n      input_refs: { type: 'array', items: { type: 'string' }, description: 'Asset ids to attach (e.g. an appshot screenshot).' },\n    },\n    required: ['task'],\n  },\n}\n```\n\n**② 编排器处理 `handoff`**（`qwen-live/src/orchestrator/live-session.ts:2353`）：\n\n```ts\nhandlers.set(HANDOFF_TOOL_NAME, async (args, ctx) =\u003e {\n  const task = typeof args['task'] === 'string' ? args['task'].trim() : '';\n  const { handle, backend } = await this.resolveHandoffTarget(context, args['session']);\n  const blocks = await this.buildHandoffBlocks(task, ctx.activeTranscript, args['input_refs']); // 附上近期对话和截图\n  const adaptor = this.adaptorFor(backend);\n  const caps = adaptor.capabilities();\n  if (!caps.imageInput) /* 去掉图片，回执里说明 */;\n  this.ensurePump(handle, backend);                       // 开始消费这个会话的事件流\n  const receipt = await adaptor.prompt(backend, sentBlocks, {\n    steer: adaptor.isBusy(backend) \u0026\u0026 caps.steering !== 'none', // 会话忙时追加指令而不是新开\n  });\n  return receipt;                                          // 立刻回给语音模型，不等任务完成\n});\n```\n\n**③ 后端抽象**（`qwen-live/src/adaptor/types.ts`）：\n\n```ts\ninterface BackendAdaptor {\n  readonly name: string;\n  capabilities(): BackendCapabilities;        // imageInput、steering 等\n  preflight(): Promise\u003cvoid\u003e;\n  createSession(opts?: { cwd?: string; label?: string }): Promise\u003cBackendHandle\u003e;\n  listSessions(): Promise\u003cSessionSummary[]\u003e;\n  prompt(handle, blocks: readonly ContentBlock[], opts?): Promise\u003cPromptReceipt\u003e;\n  events(handle, …): AsyncIterable\u003cBackendEvent\u003e;\n  isBusy(handle): boolean;\n  cancel(handle): Promise\u003cvoid\u003e;\n  cancelJob?(handle, jobRef): Promise\u003cCancelJobResult\u003e;\n  respondPermission(…): Promise\u003c…\u003e;\n  close(): Promise\u003cvoid\u003e;\n}\n```\n\n两个实现：\n\n```ts\n// AcpAdaptor（acp-adaptor.ts:769, :515）—— 任意 ACP agent\nconst child = spawn(this.options.command, this.options.args ?? [], {   // 例如 'qodercli', ['--acp']\n  cwd, stdio: ['pipe', 'pipe', 'pipe'],\n  env: { ...process.env, ...this.options.env, QWEN_CODE_NO_RELAUNCH: 'true' },\n});\n// … new ClientSideConnection(…)\nconst response = await conn.prompt({ sessionId, prompt: blocks.map(toAcpBlock) });\n\n// QwenCodeAdaptor（qwen-code-adaptor.ts:346, :406）—— 经 sdk 连 qwen serve\nthis.client = new DaemonClient({ baseUrl: options.baseUrl, token: options.token });\nconst session = await this.client.createOrAttachSession({\n  workspaceCwd: cwd,\n  sessionScope: 'thread',\n  sourceType: 'qwen-live',          // web-shell / VS Code 历史列表里据此过滤\n}, this.options.clientId);\n```\n\n**④ 连实时语音模型**（`qwen-live/src/realtime/realtime-session.ts:617`）：一个到 DashScope Realtime 的 WebSocket，音频双向流，模型侧负责 VAD、直接回答和工具调用。后端事件由 `orchestrator/injector.ts` 排队，在模型不说话的间隙以\"静默上下文\"注入（`[COMPLETE]`、权限请求、停止确认等），避免打断播报。\n\n**⑤ Host 发现与握手**（`qwen-live/src/host/discovery.ts`、`live-host/src/main/discovery.ts`、`daemon-connection.ts`）：\n\n```ts\n// daemon 侧：写 ~/.qwen/live/daemon.json（加锁、原子写）\nexport const LIVE_DISCOVERY_RELATIVE_PATH = path.join('live', 'daemon.json');\nconst HOST_WS_PATH = '/live/host';\n\n// Host 侧：读同一个文件，连上后先比协议版本\nif (!configured) return join(homedir(), '.qwen', 'live', 'daemon.json');\n…\nif (message.protocolVersion !== LIVE_PROTOCOL_VERSION) { /* 拒绝连接 */ }\n```\n\n#### 独立版里另外几块\n\n| 模块 | 行数 | 做什么 |\n|---|---|---|\n| `memory/` | 约 5k | 跨通话记忆：对话、用户事实、可选的视觉观察，存在 `~/.qwen-live/memories/\u003cid\u003e/`（SQLite FTS5，需 Node ≥ 22.13）；有整理模型（默认 `qwen3.7-plus`） |\n| `proactive/` | 约 4k | 主动任务：盯屏幕（定时截图让模型判断）、定时器、播报 |\n| `host/` | 约 4k | Host 协调、Host 安装器（下载签名的 `.app`，校验 SHA-256、签名、Gatekeeper） |\n| `subagents/` | 约 0.7k | 给浮层上的 \"Subagents\" 面板记账：每个 handoff / 监控任务的状态，不编进度百分比 |\n| `permissions/` | 约 0.3k | 后端权限请求的中转：通话中用语音回答，挂断后在面板里回答 |\n| `init.ts` | — | `qwen-live init` 向导：扫描 PATH 里的 qodercli / qwen / gemini / claude / codex，选默认后端，填 DashScope key |\n\n#### 我的看法\n\n1. **定位清楚，设计有意思。** 用实时语音模型做\"前台调度\"、编码 agent 做\"后台执行\"，两边用 `handoff` + 回执 + 静默上下文注入解耦。语音模型不用等任务完成，用户可以继续说话、开并行任务。`BackendAdaptor` 让后端可以换成任何 ACP agent，这层抽象做得好。\n2. **两个实现并存是最大的问题。** `serve/live/`（约 1.1 万行）和 `qwen-live`（约 4.2 万行）做的是同一件事，文件名都对得上（`discovery.ts`、`live-host-coordinator.ts`、`live-host-installer.ts`），但互相不 import，共享的只有 Host 协议和发现文件路径。Host 协议每改一版，两边都得改。建议：内置版冻结，web-shell 的 Live 开关改成\"启动 / 连接独立 `qwen-live`\"，过一两个版本后删掉 `serve/live/`。这样 serve 少 1.1 万行，也去掉了 serve 对 `ui/voice` 的依赖。\n3. **它其实不属于 qwen-code 的\"内核\"，而是一个独立产品。** qwen-live 只通过协议（ACP 或 serve REST）用 qwen-code，自己有配置目录（`~/.qwen-live/`）、自己的会话格式、自己的记忆库，还能驱动别家 agent。放在这个 monorepo 里主要是为了共用 sdk 和 Host 发布流程。\n4. **对融合的影响：**\n   - 独立版已经把 `qodercli --acp` 当作一等后端，所以融合后的 `qwen-next --acp` 只要保持 ACP 兼容就能直接用，不需要额外适配。\n   - `QwenCodeAdaptor` 依赖 sdk 的 `DaemonClient`，属于 IDE 集成建议 §4.5 说的 SDK 消费方，serve v2 时要一起迁，或者干脆按 README 的 Legacy 标注删掉，只保留 ACP 路径。\n   - 内置版依赖 serve 和 cli 的 `ui/voice`，是迁移成本最高的部分。按上面第 2 条先删掉，迁移面会小很多。\n5. **平台限制**：Host 只有 macOS（需要原生麦克风、全局快捷键和截屏），Linux / Windows 用户目前用不了语音。\n\n---\n\n## 7. cli 内部：入口分派\n\n`qwen` 一个 bin 承载了所有模式。分派在 `packages/cli/index.ts` → `src/cli.ts` → `src/llm.tsx`。\n\n```mermaid\nflowchart TD\n  IDX[\"packages/cli/index.ts\"]\n  IDX --\u003e|\"managed-runtime-bootstrap\"| MRB[\"serve/managed-runtime-bootstrap.ts\u003cbr/\u003eJava 的私有 stdio worker\"]\n  IDX --\u003e|\"managed-runtime-bootstrap-worker\"| MRS[\"serve/managed-runtime-ssh-worker.ts\"]\n  IDX --\u003e|\"--workspace-recovery-worker\"| WRW[\"serve/workspace-recovery-worker.ts\"]\n  IDX --\u003e|其他| CLIENTRY[\"src/cli.ts runCliEntryPoint\"]\n  CLIENTRY --\u003e|\"快速路径：mcp / memory / help / session-send-mcp\"| FAST[\"yargs 子命令\"]\n  CLIENTRY --\u003e MAIN[\"src/llm.tsx main()\"]\n  MAIN --\u003e|\"yargs 子命令\u003cbr/\u003e(config/config.ts 注册)\"| SUB[\"serve · daemon · attach · channel · sessions · agents\u003cbr/\u003ebatch · board · auth · mcp · memory · extensions · hooks\u003cbr/\u003ereview · autofix-pr · sandbox · update\"]\n  SUB --\u003e|serve| SERVE[\"serve/run-qwen-serve.ts\u003cbr/\u003ecreateServeApp (server.ts:890)\"]\n  MAIN --\u003e|\"--acp / --experimental-acp\"| ACP[\"acp-integration/acpAgent.ts runAcpAgent\"]\n  MAIN --\u003e|\"TTY 交互，renderer=opentui\"| OTUI[\"ui/opentui/start-opentui-ui.ts\"]\n  MAIN --\u003e|\"TTY 交互，默认\"| INK[\"ui/startInteractiveUI.ts（Ink）\"]\n  MAIN --\u003e|\"--input-format stream-json\"| SJ[\"nonInteractive runNonInteractiveStreamJson\"]\n  MAIN --\u003e|\"-p / 管道输入\"| HL[\"nonInteractiveCli.ts runNonInteractive\"]\n  SERVE --\u003e|\"默认 profile\"| BRG[\"acp-bridge → spawn qwen --acp\"]\n  SERVE --\u003e|\"--profile hosted-harness\"| HH[\"hosted-harness-*.ts（自带 loop）\"]\n```\n\n`cli/src` 主要目录：\n\n| 目录 | 内容 | 规模（生产行） |\n|---|---|---|\n| `serve/` | daemon：Express app、70 多个 `register*Routes`、`acp-http/`、channel worker、managed/hosted、live、web-shell 静态托管 | 约 27.6 万 |\n| `ui/` | Ink TUI（`ui/opentui/` 是 OpenTUI） | 约 16.0 万 + 4.8 万 |\n| `acp-integration/` | `qwen --acp` agent 侧（`acpAgent.ts` 18k 行，`session/Session.ts` 21k 行） | 约 5.0 万 |\n| `commands/` | 17 个顶层子命令，`review/` 最大（`/review` skill 的确定性步骤），见 §7.1 | 约 12.8 万 |\n| `nonInteractive/` + `nonInteractiveCli.ts` | headless、stream-json 控制协议 | — |\n| `config/`、`services/`、`runtime/`、`startup/` 等 | 运行时装配 | 约 7.2 万 |\n\n### 7.1 子命令全览\n\n`qwen` 除了\"跑 agent\"的几种模式（交互 TUI、`-p`、stream-json、`--acp`），还挂了 17 个顶层子命令，注册在 `cli/src/config/config.ts:907-941`：\n\n```ts\nyargsInstance\n  .command(mcpCommand).command(memoryCommand).command(extensionsCommand).command(authCommand)\n  .command(hooksCommand).command(channelCommand).command(boardCommand)\n  .command(serveCommand)      // Stage 1 daemon\n  .command(daemonCommand)     // local daemon inspection and control\n  .command(attachCommand)     // terminal client for a running daemon session\n  .command(sessionsCommand).command(agentsCommand).command(batchCommand)\n  .command(updateCommand).command(sandboxCommand);\n\n// /review、/autofix-pr 的辅助命令很大，只在 argv 里出现时才加载\nif (rawArgv.includes('review'))     yargsInstance.command((await import('../commands/review.js')).reviewCommand);\nif (rawArgv.includes('autofix-pr')) yargsInstance.command((await import('../commands/autofix-pr.js')).autofixPrCommand);\n```\n\n另外 `cli.ts` 对 `mcp`、`memory`、`help`、`session-send-mcp` 有一条快速路径，不走完整的 `llm.tsx main()` 启动（见上图）。\n\n#### 按\"跟谁打交道\"分组\n\n```mermaid\nflowchart LR\n  subgraph G1[\"① 本地配置管理\u003cbr/\u003e直接读写 ~/.qwen 和项目 .qwen\"]\n    MCP[\"mcp\u003cbr/\u003eadd · remove · list · approve · reject · reconnect\"]\n    EXT[\"extensions\u003cbr/\u003einstall · uninstall · link · new · enable · disable · update · settings · sources\"]\n    MEM[\"memory\u003cbr/\u003eimport codex\"]\n    HK[\"hooks（提示用 /hooks）\"]\n    AU[\"auth（已移除，只打印提示）\"]\n    UP[\"update（自更新）\"]\n    SB[\"sandbox（检查 / 验证工具隔离）\"]\n  end\n  subgraph G2[\"② daemon 生命周期与客户端\u003cbr/\u003e经 HTTP 连 qwen serve\"]\n    SV[\"serve（前台跑 daemon）\"]\n    DM[\"daemon\u003cbr/\u003estart · stop · restart · status · logs · token\"]\n    AT[\"attach（终端 attach 到 daemon 会话）\"]\n    AG[\"agents\u003cbr/\u003ejoin · session-send-mcp\"]\n  end\n  subgraph G3[\"③ 多会话 / 多 agent 协作\u003cbr/\u003e本机文件与 UDS\"]\n    SS[\"sessions\u003cbr/\u003elist · ps · add · remove · controllers\"]\n    BD[\"board\u003cbr/\u003etask · claim · done · ask · answer · show · prune\"]\n  end\n  subgraph G4[\"④ 外部平台集成\"]\n    CH[\"channel\u003cbr/\u003estart · stop · status · set · reload · pairing · …\"]\n    BT[\"batch\u003cbr/\u003erun · check · collect · list · retry · cancel · clean\"]\n  end\n  subgraph G5[\"⑤ 给内置 skill 用的确定性工具\"]\n    RV[\"review\u003cbr/\u003e约 45 个子命令（fetch-pr · capture-local · agent-prompt · findings · compose-review · submit · run …）\"]\n    AF[\"autofix-pr\u003cbr/\u003eprepare · snapshot · fix-start · fix-end · push · reply · status · …\"]\n  end\n\n  G1 --\u003e CORE[(\"core\u003cbr/\u003eStorage · settings · McpClientManager · 扩展管理\")]\n  SV --\u003e SERVE{{\"qwen serve 进程\"}}\n  DM --\u003e|\"spawn detached: cli.js serve --port … --no-token-qr\"| SERVE\n  AT --\u003e|\"sdk DaemonClient + /daemon/ui\"| SERVE\n  AG --\u003e|\"join link → 本机 serve 的 agent-host\"| SERVE\n  SS --\u003e REG[(\"会话注册表 · Agent View 记录\u003cbr/\u003epeer 控制器令牌\")]\n  BD --\u003e BFS[(\"board 目录（文件 + 锁）\u003cbr/\u003ecore/board → agents/team/board-*.ts\")]\n  CH --\u003e|\"独立模式 AcpBridge / daemon-worker\"| SERVE\n  BT --\u003e|\"DashScope Batch API（HTTP）\"| DS([\"DashScope\"])\n  RV \u0026 AF --\u003e|\"gh / git / 本地文件\"| GH([\"GitHub · git 工作区\"])\n  SKILL[\"内置 skill\u003cbr/\u003e/review · /autofix-pr\"] --\u003e|\"Shell 工具里调用 qwen review … / qwen autofix-pr …\"| RV \u0026 AF\n```\n\n#### 逐个说明\n\n| 命令 | 生产代码行数 | 子命令 | 做什么 | 依赖 |\n|---|---|---|---|---|\n| `mcp` | 1.2k | add / remove / list / approve / reject / reconnect | 管理 MCP 服务器配置，审批项目级 MCP | core（settings、MCP 客户端） |\n| `extensions` | 1.8k | install / uninstall / link / new / enable / disable / update / settings / sources | 管理扩展（`qwen-extension.json`，可带 MCP、skills、channels、commands） | core |\n| `memory` | 0.2k | import codex | 预览并导入外部工具（Codex）的记忆 | core |\n| `hooks` | 25 行 | — | 只提示\"交互模式里用 `/hooks`\" | — |\n| `auth` | 71 行 | 旧子命令（`api-key`、`qwen-oauth` 等） | **已移除**，只打印迁移提示；认证改在 TUI `/auth`、web-shell 或 serve 的认证接口里做 | — |\n| `update` | 0.2k | — | 自更新（区分 npm 安装 / 独立安装、`latest` / `nightly` dist-tag） | `ui/standalone-update`、`installationInfo` |\n| `sandbox` | 0.3k | `sandbox [cmd...]` | 检查当前解析出的工具隔离后端，验证它，或在隔离里跑一条命令 | core `runtime-info` |\n| `serve` | 1.4k | — | 前台启动 daemon（§5、§9） | `serve/` |\n| `daemon` | 1.9k | start / stop / restart / status / logs / token | 后台管理 `qwen serve`：detached spawn、写发现记录、读日志、取 token | `serve/daemon-discovery` |\n| `attach` | 0.4k | — | 终端里 attach 到 daemon 上的某个会话，渲染事件、可发 prompt | **sdk** `DaemonClient`、`DaemonSessionClient`、`/daemon/ui` |\n| `agents` | 0.5k | join `\u003clink\u003e` / session-send-mcp | 把本机正在跑的 serve 作为 Agent Host 加入一个协调者；`session-send-mcp` 是给子会话用的 stdio MCP 服务器（提供 `session_send`） | `serve/agent-host-join`、MCP SDK |\n| `sessions` | 0.7k | list / ps / add / remove / controllers | `list` 扫保存的会话记录；`ps` 看实时注册表和 Agent View 的托管记录；`controllers` 签发 / 吊销可以驱动你会话的控制器令牌（跨会话协议） | core（peer 注册表） |\n| `board` | 0.4k | task / claim / done / decline / ask / answer / show / prune | Agent Board：同一台机器上独立启动的 agent 通过文件共享任务。实验性，不负责启动或唤醒 agent | `core/board`（`agents/team/board-*.ts`） |\n| `channel` | 约 7k + serve 侧 | start / stop / status / set / reload / pairing / approve / configure-weixin / managed-email / daemon-worker | IM / 代码平台渠道（§6.3） | channel-base、全部 `channel-*`、sdk |\n| `batch` | 3.7k | run / check / collect / list / retry / cancel / clean | DashScope Batch API：半价异步批量推理。agent 用 `/batch-api` 准备计划，`qwen batch` 提交、跟踪、落盘结果 | core 的 contentGenerator 配置，直接 HTTP 调 DashScope |\n| `review` | **约 9.8 万** | 约 45 个 | `/review` skill 的确定性步骤：抓 PR、截取本地 diff、拼 agent 提示词、去重 findings、组装评审、提交评论、CI 门禁（`run --fail-on request-changes`） | git、`gh`、本地缓存 |\n| `autofix-pr` | 9.9k | prepare / snapshot / fix-start / fix-end / push / reply / rerun / schedule / status / sync / cleanup / ci-log | `/autofix-pr` skill 的确定性步骤：盯一个 PR，修 CI 失败、评审意见和冲突，在独立 worktree 里修完推回去 | git、`gh` |\n\n#### 几种值得注意的模式\n\n**① skill + CLI 子命令的分工（`review`、`autofix-pr`）。** 内置 skill（`core/src/skills/bundled/review/SKILL.md`）负责判断，确定性的部分做成 CLI 子命令，让 skill 在 Shell 工具里调用。SKILL.md 里出现最多的是：\n\n```text\nqwen review run        ×14     qwen review fetch-pr      ×5\nqwen review submit     ×5      qwen review agent-prompt  ×5\nqwen review findings   ×4      qwen review presubmit     ×3\n```\n\n这种模式的好处是：可以重放、可以单测、模型不用自己写 git / gh 脚本。代价是体量：`commands/review/` 约 9.8 万行，比 `acp-integration/` 还大，是 cli 里最大的一块。好在只有 argv 里出现 `review` 时才 `import()`，不拖慢普通启动。\n\n**② daemon 的三个入口：serve、daemon、attach。**\n\n```mermaid\nsequenceDiagram\n  participant U as 用户\n  participant D as qwen daemon start\n  participant S as qwen serve（后台）\n  participant F as 发现记录\n  participant A as qwen attach\n  U-\u003e\u003eD: qwen daemon start\n  D-\u003e\u003eS: spawn(cli.js, ['serve','--port',…,'--hostname',…,'--no-token-qr', …], { detached: true })\n  S-\u003e\u003eF: 写发现记录（url、token、workspaces）\n  U-\u003e\u003eA: qwen attach --session \u003cid\u003e\n  A-\u003e\u003eF: 找到 daemon\n  A-\u003e\u003eS: DaemonSessionClient.load(client, id) → events() 渲染\n```\n\n```ts\n// commands/daemon.ts:565 —— 组装后台 serve 的参数\nconst childArgs = ['serve', '--port', String(port), '--hostname', hostname, '--no-token-qr'];\nif (!options.web) childArgs.push('--no-web');\nif (options.requireAuth) childArgs.push('--require-auth');\n// … spawn(command, args, { detached: true, … })\n\n// commands/attach.ts:164 —— 终端客户端就是一个 SDK 消费方\nconst client = new DaemonClient({ baseUrl: target.record.url, token: resolved.token ?? '' });\nconst session = await DaemonSessionClient.load(client, argv.session, { workspaceCwd });\nfor await (const event of session.events({ signal })) renderEvent(event);\n```\n\n`attach` 是 cli 反向依赖 sdk 的原因之一（§4.2），但这里是正当的：它就是一个 daemon 客户端，和 web-shell 同一层。\n\n**③ 已经移走或空壳的命令。** `auth` 只打印\"已移除\"，`hooks` 只提示用 `/hooks`。它们留着是为了老脚本不至于报\"未知命令\"。\n\n**④ 多 agent 协作有三套机制，容易混。**\n\n| 机制 | 命令 | 载体 | 能做什么 |\n|---|---|---|---|\n| Agent Board | `qwen board` | 本机文件 + 锁 | 记录任务、认领、问答；**不**启动或唤醒任何 agent |\n| 跨会话协议（peer） | `qwen sessions ps / controllers`、`session_send` MCP | 会话注册表 + UDS（`core/src/ipc`、sdk `/peer`） | 会话之间发消息，用控制器令牌驱动别的会话 |\n| Agent Host / 协调者 | `qwen agents join \u003clink\u003e` | 本机 `qwen serve` 加入远端协调者 | 让协调者把会话派到这台机器的 serve 上跑 |\n\n官方文档（`docs/users/features/agent-board.md`）特意说明 Board \"not the Qwen Agent Team scheduler or the cross-session messaging transport\"，可见确实容易混。\n\n#### 我的看法\n\n1. **cli 承担了太多\"不是 CLI 的东西\"。** 17 个子命令里，真正的 agent 入口只有默认命令；`serve`（27.6 万行）、`review`（9.8 万行）、`channel` 加 serve 侧的 channel 代码、`batch` 都是独立子系统。它们共用 `qwen` 这个 bin 是为了方便分发，代价是 cli 包的依赖和体积都被放大（例如全部 `channel-*` 包）。懒加载（`review`、`autofix-pr`）是对的方向，可以推广到 `channel`、`batch`、`board`。\n2. **`review` / `autofix-pr` 的\"skill 做判断、CLI 做确定性步骤\"模式值得保留**，而且适合作为扩展机制公开出来：第三方 skill 也可以带自己的确定性子命令，不用都塞进 cli 本体。\n3. **对融合的影响：**\n   - 全部是 Qwen 产品层的东西，按融合方案的规则放在 Qwen 产品层，通过 `runCli({ declarations })` 命令清单挂到新内核上（IDE 集成建议 §4.1 的扩展点 4）。\n   - 直接依赖 core 内部模块的有 `mcp`、`extensions`、`memory`、`sessions`、`board`、`batch`、`sandbox`。新内核里这些 core 模块的位置和接口都会变，是迁移工作量的主要来源。\n   - `serve`、`daemon`、`attach`、`agents` 跟着 serve v2 走；`attach` 只依赖 SDK，换 SDK 1.x 即可。\n   - `review`、`autofix-pr` 只依赖 git 和 `gh`，与内核无关，可以原样搬。\n\n---\n\n## 8. core 内部与 agent loop 入口\n\ncore 的 34 个一级子目录里有 31 个在同一个强连通分量里（`config ↔ tools`、`config ↔ services`、`agents ↔ tools` 都是双向依赖），不能按目录拆开替换。下图只画和\"谁调谁\"相关的主干。\n\n```mermaid\nflowchart LR\n  subgraph ENTRIES[\"7 个 loop 入口\"]\n    INK[\"Ink TUI\u003cbr/\u003eui/hooks/use-llm-stream.ts\"]\n    OTUI[\"OpenTUI\u003cbr/\u003eui/opentui/live-session.ts\"]\n    HL[\"Headless / stream-json / SDK query()\u003cbr/\u003enonInteractiveCli.ts\"]\n    ACP[\"ACP（Zed / VS Code / serve / web-shell / channels）\u003cbr/\u003eacp-integration/session/Session.ts\"]\n    HH[\"Hosted Harness\u003cbr/\u003eserve/hosted-harness-model.ts\"]\n    AC[\"AgentCore（subagent / 后台 / workflow / team）\u003cbr/\u003ecore/agents/runtime/agent-core.ts\"]\n    SPEC[\"Speculation\u003cbr/\u003ecore/followup/speculation.ts\"]\n  end\n  subgraph CORELOOP[\"core/src/core\"]\n    LOOP[\"agent-loop.ts\u003cbr/\u003erunAgentLoop / runModelRound / runToolBatch\u003cbr/\u003e（experimental.unifiedAgentLoop，默认关）\"]\n    CLIENT[\"LlmClient (client.ts)\"]\n    TURN[\"Turn (turn.ts)\"]\n    CHAT[\"LlmChat (llm-chat.ts)\u003cbr/\u003e重试 · 回退 · 自动压缩\"]\n    CTS[\"CoreToolScheduler\"]\n  end\n  PROV[\"providers / models\"]\n  TOOLS[\"tools · mcp · skills · hooks · permissions\"]\n  CFG[\"Config（上帝对象）\"]\n\n  INK --\u003e CLIENT\n  OTUI --\u003e CLIENT\n  HL --\u003e CLIENT\n  HH --\u003e CLIENT\n  ACP --\u003e|绕过 client| CHAT\n  AC --\u003e|绕过 client| CHAT\n  SPEC --\u003e|绕过 client| CHAT\n  CLIENT --\u003e TURN --\u003e CHAT --\u003e PROV\n  INK \u0026 OTUI \u0026 HL \u0026 AC --\u003e CTS\n  ACP -.-\u003e|自带 runToolCalls / runTool| TOOLS\n  HH -.-\u003e|HostedWorkspaceToolTurn → broker| TOOLS\n  CTS --\u003e TOOLS\n  ENTRIES -.-\u003e|开关开时| LOOP\n  LOOP --\u003e CLIENT\n  LOOP --\u003e CTS\n  CFG -.-\u003e CLIENT \u0026 CTS \u0026 TOOLS\n```\n\n迁移状态（详见报告 01）：开关打开后，Ink、OpenTUI、Headless、ACP、AgentCore 的模型轮和工具批都跑在 `agent-loop.ts` 上；Hosted Harness 不读开关；Speculation 还没迁（#17029）。#17045 计划把 1.0 preview 的事件总线 loop 内核落到 main，并默认开。\n\n---\n\n## 9. 进程拓扑总览\n\n一个典型的\"desktop / web-shell 用户\"机器上会有这些进程：\n\n```mermaid\nflowchart TB\n  subgraph HOST[\"用户机器\"]\n    BROWSER[\"浏览器 / Tauri / WebView\u003cbr/\u003eweb-shell\"]\n    subgraph DAEMON[\"qwen serve 进程（:4170 或随机端口）\"]\n      EXP[\"Express app + WS upgrade\"]\n      BRG[\"acp-bridge\"]\n      CWS[\"channel worker supervisor\"]\n    end\n    subgraph CHILDREN[\"子进程\"]\n      ACP1[\"qwen --acp（工作区 A）\u003cbr/\u003e多个会话\"]\n      ACP2[\"qwen --acp（工作区 B）\"]\n      CW[\"qwen channel daemon-worker ×N\"]\n      MCPS[\"MCP servers\u003cbr/\u003ebrowser-use / node-repl / mobile-mcp / 第三方\"]\n    end\n    VSCODE[\"VS Code\u003cbr/\u003eide-companion：IDE MCP server\"]\n    DISK[(\"~/.qwen\u003cbr/\u003esettings.json · tmp/\u0026lt;hash\u0026gt;/chats/*.jsonl · live/daemon.json\")]\n  end\n  BROWSER --\u003e|REST/SSE/WS| EXP\n  EXP --\u003e BRG\n  BRG --\u003e|stdio ACP| ACP1\n  BRG --\u003e|stdio ACP| ACP2\n  CWS --\u003e|spawn| CW\n  CW --\u003e|sdk DaemonClient| EXP\n  ACP1 --\u003e|stdio / http MCP| MCPS\n  ACP1 --\u003e|IDE MCP client| VSCODE\n  ACP1 --- DISK\n  VSCODE -. \"直接读写 settings / 会话 jsonl\" .-\u003e DISK\n```\n\n托管部署（managed）：\n\n```mermaid\nflowchart LR\n  WSM[\"web-shell（managed 模式）\"] --\u003e|\"/api/agent/web-shell/v1/*\"| MAS[\"managed-agent-server（Java）\"]\n  MAS --\u003e|\"spawn / k8s：qwen serve --profile hosted-harness --http-bridge --no-web\"| HHS[\"qwen serve（hosted profile）\u003cbr/\u003e只开放 hosted 路由 + /health /capabilities\"]\n  MAS --\u003e|\"qwen managed-runtime-bootstrap（私有 stdio worker）\"| MRB[\"managed runtime worker\u003cbr/\u003e/internal/managed-runtime/**\"]\n  HHS --\u003e CORE[\"core managed-runtime\"]\n  MRB --\u003e CORE\n  MAS -. \"33 个契约 fixture\" .-\u003e CONTRACTS[\"core/src/managed-runtime/contracts\u003cbr/\u003ecli/src/serve/contracts\"]\n```\n\n---\n\n## 10. 速查表：X 依赖什么\n\n| 组件 | 代码依赖（import） | 运行时依赖（协议） |\n|---|---|---|\n| web-shell | sdk（主）、core 幽灵依赖 2 个符号、acp-bridge 1 个常量 | qwen serve REST/SSE/WS；managed 模式下是 managed-agent-server |\n| vscode-ide-companion | core（深）、sdk、acp-bridge、web-shell、cli `./export` | `qwen --acp`（直连）或 `qwen serve --no-web`；自己提供 IDE MCP server；直接读写 `~/.qwen` |\n| sdk-typescript | core、acp-bridge（构建时 inline）；内嵌 CLI bundle | stream-json（`query()`）、qwen serve（`/daemon`）、peer UDS |\n| sdk-java / sdk-python | — | stream-json；Java 另有 qwen serve |\n| desktop / mobile-shell | — | spawn / 连接 qwen serve，加载 web-shell |\n| chrome-extension | — | qwen serve `/health` `/capabilities` `/acp` `/workspace` |\n| qwen-live / live-host | qwen-live → sdk、`@agentclientprotocol/sdk`；live-host 无 workspace 依赖（只用 ws，另外编译时打包 qwen-live 的 i18n 模块） | qwen-live：DashScope Realtime WS、任意 `xxx --acp`、（Legacy）qwen serve REST；live-host：经 `~/.qwen/live/daemon.json` 发现后连 `/live/host` WS（独立 qwen-live 或 serve 内置 `/live/*`） |\n| channels/* | channel-base | 独立：spawn `qwen --acp`；daemon：由 serve 拉起 worker，经 sdk 回连 serve |\n| zed-extension | — | `qwen --acp`（固定 npm 0.10.0） |\n| managed-agent-server | 契约 fixture | spawn `qwen serve --profile hosted-harness`；`qwen managed-runtime-bootstrap` |\n| cli | core、acp-bridge、sdk、channel-*、web-templates、audio-capture | 作为 serve 时 spawn 自己的 `--acp` 子进程；作为 IDE MCP client 连 VS Code |\n| acp-bridge | core、`@agentclientprotocol/sdk` | stdio ACP client |\n| core | （dev）browser-use | MCP client、provider HTTP、IDE MCP client、peer UDS |\n\n---\n\n## 11. 架构上的几个\"坑\"\n\n1. **依赖方向不干净**：cli（harness）反向依赖 sdk、channel-*、web-templates、audio-capture；sdk 又在构建时 inline core / acp-bridge，还内嵌 CLI bundle，形成 `cli → sdk → (inline) core`、`sdk → (bundle) cli` 的环。根源是 daemon 协议没有自己的包，SDK 兼任了协议定义，见 §6.4。\n2. **web-shell 有未声明的 core 依赖**，只靠 workspace hoist 解析。\n3. **VS Code 插件是耦合最深的上层**：直接用 core 的 provider 安装、`Storage`、文件搜索，直接读会话 jsonl，比 web-shell 深一个量级。\n4. **core 没有 API 边界**：`exports` 的 `\"./*\"` 让每个内部文件都是公开入口，cli 深 import 了 348 个内部模块。\n5. **serve 默认是\"代理 + 子进程\"模型**：REST 是对外契约，ACP（含 117 个私有 ext 方法）是 serve 和子进程之间的内部契约；`/acp` 对外端点存在但默认没人用。\n6. **两套 serve 实现**：默认 profile（acp-bridge + `--acp` 子进程）和 hosted-harness profile（自带 loop、日志式工具执行）。\n7. **agent loop 有 7 个入口**，统一循环（`unifiedAgentLoop`）还在迁移，默认关。\n\n---\n\n## 参考\n\n- 报告：`~/Downloads/qwen-code-harness-分析/02-size-coupling.md`（包图、import 计数）、`03-rest-routes.md`（serve 架构、601 条路由）、`04-acp-methods.md`（ACP 拓扑、方法清单）、`05-upper-layers.md`（上层应用、协议入口、磁盘耦合）、`01-agent-loop.md`（loop 入口）\n- §5.4 调用链源码位置：`web-shell/client/daemon/session/actions.ts:1435,2510`、`web-shell/client/daemon/session/DaemonSessionProvider.tsx:3971`、`sdk-typescript/src/daemon/DaemonSessionClient.ts:759`、`DaemonClient.ts:7082,7291`、`RestSseTransport.ts:99-122`、`cli/src/serve/routes/session.ts:7697`、`routes/session-prompt-admission.ts:295,370`、`routes/sse-events.ts:182,393`、`routes/permission.ts:47`、`run-qwen-serve.ts:6447`、`acp-bridge/src/session-control-plane.ts:11439,12026,12503`、`channel-connection.ts:350`、`spawnChannel.ts:549`、`bridgeClient.ts:1050,1227`、`cli/src/acp-integration/acpAgent.ts:3098,3284,7279`、`session/Session.ts:5911,7057,10818,11295,15096,19204`\n- 本次复核过的源码位置：`packages/cli/index.ts`、`packages/cli/src/cli.ts:711`、`packages/cli/src/llm.tsx:1377-1781`、`packages/cli/src/config/config.ts:72-130`、`packages/cli/src/serve/web-shell-resolver.ts`、`packages/cli/src/serve/channel-worker-supervisor.ts:1059`、`scripts/copy_bundle_assets.js:619-660`、`packages/sdk-typescript/package.json`（exports）、各包 `package.json` 依赖\n","html":"","default_view":"markdown","version":3,"updated_by":"4e3fvwoonbfzbvqtdwehr2fzdp","updated_at":"2026-11-18T11:22:30Z","assets":[],"base_url":"/pub/p5hmpjzplmjv/p/"},"sources":[],"topic":{"id":"p5hmpjzplmjv","title":"qwen-code 全局架构","question":"qwen-code 的包、协议面和进程是怎么组织的？web-shell、SDK、serve、acp-bridge、core 之间谁调谁？","visibility":"public","slug":"qwen-code-architecture","hue":250,"emoji":"🏗️","owner_id":"4e3fvwoonbfzbvqtdwehr2fzdp","created_at":"2026-11-18T11:22:21Z","updated_at":"2026-11-18T11:22:30Z","published_at":"2026-11-18T11:22:30Z","item_count":0,"report_words":11555,"formats":["markdown"],"url":"https://research.sorrycc.dev/@sorrycc/qwen-code-architecture"}}
