---
title: "qwen-code 全局架构"
author: "陈成"
author_url: "https://research.sorrycc.dev/@sorrycc"
question: "qwen-code 的包、协议面和进程是怎么组织的？web-shell、SDK、serve、acp-bridge、core 之间谁调谁？"
url: "https://research.sorrycc.dev/@sorrycc/qwen-code-architecture"
emoji: "🏗️"
published: 2026-11-18T11:22:30Z
updated: 2026-11-18T11:22:30Z
version: 3
cite: "https://research.sorrycc.dev/@sorrycc/qwen-code-architecture.bib"
---

# qwen-code 全局架构图（main @ `53940f2afc`）

By [陈成](https://research.sorrycc.dev/@sorrycc) · Published November 18, 2026

> qwen-code 的包、协议面和进程是怎么组织的？web-shell、SDK、serve、acp-bridge、core 之间谁调谁？

> 基于 `~/Downloads/qwen-code-harness-分析/` 01–09 报告（同一 commit），并在仓库里对包依赖、入口分派、serve ↔ web-shell、sdk / acp 依赖做了复核。
> 行号、计数都是这个 commit 上的。"声明依赖"指 package.json；"实际 import"指源码 import；"运行时调用"指进程间协议。三者经常不一致，下面分开画。

---

## 0. 一句话版本

- **核心只有三块**：`core`（agent 运行时）、`cli`（TUI、headless、ACP agent、`qwen serve` 守护进程、子命令都在这里）、`acp-bridge`（serve 用来拉起和管理 `qwen --acp` 子进程的 ACP client）。
- **所有上层应用都通过四个协议面接入**，基本不直接调代码：
  1. `qwen serve`：REST/SSE（主要），外加 `/acp` HTTP/WS
  2. `qwen --acp`：stdio ACP
  3. `qwen -p --input-format stream-json`：SDK 控制协议
  4. IDE MCP：CLI 连 VS Code 插件起的 MCP server
- **web-shell 是 `qwen serve` 的前端**：serve 托管它的静态资源；它通过 `@qwen-code/sdk/daemon` 调 serve 的 REST/SSE；serve 再经 acp-bridge 把请求转给 `qwen --acp` 子进程，子进程里跑 core。
- **`@qwen-code/sdk` 是 serve 的官方客户端库**：web-shell、VS Code 插件、qwen-live、cli 自己（反向依赖）都用它。它在构建时把 core / acp-bridge 的少量常量 inline 进来，发布时还把整个 CLI bundle 打进包里。
- "ACP" 有三层含义：`@agentclientprotocol/sdk` 库、`@qwen-code/acp-bridge` 包、`qwen --acp` 协议。依赖它们的包各不相同，见 §6。
- **qwen-live 是"语音指挥编码 agent"的独立产品**：macOS 上的 Live Host 负责音频和浮层，Live daemon 连 DashScope 实时语音模型，通过 `handoff` 把任务派给 `qwen --acp`、`qodercli --acp` 等编码 agent。daemon 有独立版（`packages/qwen-live`）和内置于 `qwen serve` 的两个实现，见 §6.5。
- "channel" 也有三层含义：IM / 代码平台渠道（产品功能）、`--channel` 启动参数（客户端身份，只用于统计）、acp-bridge 的 `AcpChannel`（到子进程的 stdio 传输），见 §6.3。

---

## 1. 全局分层图（运行时视角）

```mermaid
flowchart TB
  subgraph UI["前端 / 宿主"]
    direction LR
    TERM["终端用户<br/>qwen（Ink / OpenTUI）"]
    WS["web-shell<br/>React SPA"]
    DESK["desktop<br/>Tauri 壳"]
    MOB["mobile-shell<br/>Android WebView"]
    CHR["chrome-extension"]
    VSC["vscode-ide-companion"]
    ZED["zed-extension"]
    LH["live-host"]
  end

  subgraph CLIENTS["客户端库 / 中间层"]
    direction LR
    SDKTS["@qwen-code/sdk<br/>query() · /daemon · /peer"]
    SDKJ["sdk-java"]
    SDKP["sdk-python"]
    QL["qwen-live"]
    CHB["channel-base + 10 个 channel-*"]
    MAS["managed-agent-server<br/>Java Spring Boot"]
  end

  subgraph SURF["协议面（全部由 packages/cli 提供）"]
    direction LR
    SERVE{{"qwen serve<br/>REST/SSE · /acp HTTP+WS · WS(/terminal /voice /live)"}}
    ACPSTDIO{{"qwen --acp<br/>stdio ndjson ACP"}}
    SJ{{"qwen -p stream-json<br/>control_request"}}
    TUI{{"交互 TUI"}}
  end

  subgraph HARNESS["harness"]
    direction LR
    BR["acp-bridge<br/>BridgeClient implements Client"]
    CLI["cli<br/>acp-integration · serve · nonInteractive · ui"]
    CORE["core<br/>Config · LlmClient · CoreToolScheduler · tools · services · managed-runtime"]
  end

  TERM --> TUI
  WS -->|import| SDKTS
  DESK -->|spawn serve + 加载| WS
  MOB -->|WebView| WS
  VSC -->|内嵌| WS
  SDKTS -->|DaemonClient| SERVE
  SDKTS -->|"query() spawn"| SJ
  SDKJ --> SJ
  SDKJ -->|DaemonClient| SERVE
  SDKP --> SJ
  CHR -->|HTTP :4170| SERVE
  LH -->|"/live/*"| SERVE
  QL --> SERVE
  QL --> ACPSTDIO
  MAS -->|"serve --profile hosted-harness"| SERVE
  WS -.->|"managed 模式 /api/agent/web-shell/v1/*"| MAS
  VSC -->|"--acp --channel=VSCode"| ACPSTDIO
  VSC -->|"serve --no-web"| SERVE
  ZED --> ACPSTDIO
  CHB -->|"AcpBridge spawn --acp"| ACPSTDIO

  SERVE --> BR
  BR -->|"spawn qwen --acp 子进程"| ACPSTDIO
  TUI --> CLI
  ACPSTDIO --> CLI
  SJ --> CLI
  SERVE --> CLI
  CLI --> CORE
  BR --> CORE
  CLI -.->|IDE MCP client| VSC
```

要点：

- `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`）。
- 所以从 web-shell 出发，链路是：**web-shell → sdk/daemon → serve REST → acp-session-bridge → acp-bridge → stdio ACP → `qwen --acp`（acp-integration/Session.ts）→ core**。

---

## 2. 包清单与分层

| 层 | 包 | npm 名 | 角色 |
|---|---|---|---|
| harness | `packages/core` | `@qwen-code/qwen-code-core`（private） | agent 运行时：`Config`、`LlmClient`/`LlmChat`/`Turn`、`CoreToolScheduler`、tools、services、providers、managed-runtime、ide client、ipc（peer） |
| harness | `packages/cli` | `@qwen-code/qwen-code`（private，经根 `dist/` 发布，bin `qwen`） | 入口分派、Ink / OpenTUI TUI、headless、ACP agent（`acp-integration/`）、`qwen serve` 守护进程（`serve/`，586 个文件）、子命令 |
| harness | `packages/acp-bridge` | `@qwen-code/acp-bridge`（private） | serve 侧的 ACP client，spawn 和管理 `qwen --acp` 子进程；也导出一批协议常量和 transcript 回放 |
| 客户端库 | `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` |
| 客户端库 | `sdk-java` / `sdk-python` | Maven / PyPI | stream-json `query()`；Java 另有 `DaemonClient` |
| 前端 | `packages/web-shell` | `@qwen-code/web-shell` | serve 的 Web UI，也被 VS Code 插件、desktop、mobile-shell 复用 |
| 前端 | `vscode-ide-companion` | VS Code 插件 | 两条路：直连 `--acp`，或拉起 `serve --no-web` 后内嵌 web-shell；同时作为 IDE MCP server |
| 前端 | `desktop` / `mobile-shell` / `chrome-extension` / `live-host` / `zed-extension` | — | 壳或轻客户端，只走协议 |
| 中间层 | `qwen-live` | `@qwen-code/qwen-live` | Live 编排，adaptor 同时接 serve 和 `--acp` |
| 中间层 | `channels/base` + 10 个 `channel-*` | `@qwen-code/channel-*` | IM / 代码平台渠道，**宿主是 cli** |
| 控制面 | `managed-agent-server` | Java | Hosted Harness 控制面；拉起 `qwen serve --profile hosted-harness`；给 web-shell managed 模式提供 `/api/agent/web-shell/v1/*` |
| 工具 / MCP | `browser-use`、`cua-driver`（`@qwen-code/cua-sdk`）、`node-repl`、`mobile-mcp`、`audio-capture`、`web-templates` | — | 被 core / cli 引用或作为 MCP server 独立运行 |
| 扩展 | `integrations/*` | — | 以 `qwen-extension.json` 方式被 cli 加载 |

---

## 3. package.json 声明的 workspace 依赖

只列 `@qwen-code/*` 和 `@agentclientprotocol/sdk`。实线是 `dependencies`，虚线是 `devDependencies` / `peerDependencies`。

```mermaid
flowchart LR
  CLI["cli<br/>@qwen-code/qwen-code"]
  CORE["core"]
  BR["acp-bridge"]
  SDK["sdk-typescript<br/>@qwen-code/sdk"]
  WS["web-shell"]
  VSC["vscode-ide-companion"]
  QL["qwen-live"]
  WT["web-templates"]
  AC["audio-capture"]
  CHB["channel-base"]
  CHX["channel-* ×10"]
  BU["browser-use"]
  CUA["cua-sdk"]
  NR["node-repl-mcp"]
  ACPSDK(["@agentclientprotocol/sdk 0.14.1"])

  CLI --> CORE
  CLI --> BR
  CLI --> SDK
  CLI --> WT
  CLI --> AC
  CLI --> CHB
  CLI --> CHX
  CLI --> ACPSDK
  BR --> CORE
  BR --> ACPSDK
  CHX --> CHB
  CHB --> ACPSDK
  QL --> SDK
  QL --> ACPSDK
  VSC --> BR
  VSC --> CORE
  VSC --> SDK
  VSC --> WS
  VSC --> ACPSDK
  VSC -.dev.-> CLI
  SDK -.dev, 构建时 inline.-> CORE
  SDK -.dev, 构建时 inline.-> BR
  WS -.peer+dev.-> SDK
  WS -.dev.-> BR
  WS -.dev.-> CHX
  WT -.dev.-> SDK
  WT -.dev.-> WS
  CORE -.dev.-> BU
  CUA --> BU
  NR --> CUA
```

声明里看不出来的事实：

- **web-shell 没声明 core，但生产代码 import 了 core**（5 处，靠 workspace hoist 解析的幽灵依赖），见 §4。
- **cli 依赖 sdk 和 channel-***，方向是"harness 依赖上层"，见 §4.2。
- desktop、mobile-shell、chrome-extension、live-host、managed-agent-server、sdk-java、sdk-python、zed-extension **没有任何 workspace 依赖**，只走协议。

---

## 4. 实际代码 import 耦合

### 4.1 包间 import 站点数（生产代码）

数据来自报告 02 §4.2，口径是生产文件的 import 语句。

```mermaid
flowchart LR
  CLI["cli"] -- "2057 站点 / 846 文件" --> CORE["core"]
  CLI -- "232 / 117 文件" --> BR["acp-bridge"]
  BR -- "28 / 12 文件" --> CORE
  CLI -- "62 / 39 文件（反向）" --> CH["channels/*"]
  CLI -- "15 / 12 文件（反向）" --> SDK["sdk-typescript"]
  CLI -- "2（反向）" --> WT["web-templates"]
  WS["web-shell"] -- "约 450 条 / 212 文件<br/>几乎全是 @qwen-code/sdk/daemon" --> SDK
  WS -. "5（未声明依赖）" .-> CORE
  WS -. "1" .-> BR
  SDK -. "3 运行时（构建时 inline）" .-> CORE
  SDK -. "5 运行时 + 2 type" .-> BR
  VSC["vscode-ide-companion"] -- "29 / 24 文件" --> CORE
  VSC -- "9" --> SDK
  VSC -- "1" --> BR
  VSC -- "1（./export）" --> CLI
  LH["live-host"] -- "22" --> QL["qwen-live"]
```

### 4.2 值得注意的几条

| 现象 | 细节 | 位置 |
|---|---|---|
| **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` |
| **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/*` |
| **sdk 打包整个 CLI** | `prepack` 执行 `bundle:cli`，把根 `dist/cli.js` 复制进 `@qwen-code/sdk`，`query()` 默认 spawn 这份 CLI | `sdk-typescript/scripts/bundle-cli.js` |
| **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/*` | — |
| **cli 反向依赖 channels** | 39 个生产文件 import `@qwen-code/channel-*`。channels 的宿主是 cli（`qwen channel …` 和 serve 内的 channel worker） | `cli/src/serve/channel-*.ts`、`cli/src/commands/channel/*` |
| **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/*` |
| **cli → core 通配深 import** | core 的 `exports` 有 `"./*" → "./dist/src/*"`，cli 生产代码有 1469 处深 import，涉及 348 个 core 内部模块；ESLint 规则还在推动"从定义处 deep import" | `eslint.config.js`、`eslint.legacy-core-barrel-imports.mjs` |
| **managed-agent-server ↔ core / serve 契约** | 不 import TS，但 Java 端通过 33 个 `*-vN.fixtures.json` 契约 fixture 绑定 `core/src/managed-runtime/contracts` 和 `cli/src/serve/contracts` | — |

---

## 5. 专题：web-shell 和 serve 的关系

### 5.1 三重关系

| 关系 | 怎么做的 | 证据 |
|---|---|---|
| **托管（构建 / 部署期）** | `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） |
| **调用（运行期）** | 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` |
| **鉴权配对** | serve 在 bearer 之前挂了 web-shell pairing 路由；`web-shell-preauth.ts` 用 sdk 处理预授权 | `server.ts:60`、`cli/src/serve/web-shell-preauth.ts` |

`/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。

web-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`。

### 5.2 一次 prompt 的完整链路（默认模式）

```mermaid
sequenceDiagram
  autonumber
  participant U as 浏览器 web-shell
  participant SDK as sdk/daemon DaemonClient
  participant S as qwen serve（Express 5）
  participant SB as serve/acp-session-bridge.ts
  participant BR as acp-bridge BridgeClient
  participant A as qwen --acp 子进程<br/>acp-integration/QwenAgent + Session
  participant C as core（LlmChat / CoreToolScheduler / tools）

  U->>SDK: sendPrompt(...)
  SDK->>S: POST /session/:id/prompt（bearer）
  Note over S: hostAllowlist → CORS → bearerAuth → json → mutate gate
  S->>SB: routes/session.ts:7698
  SB->>BR: bridge.prompt(...)
  BR->>A: ACP session/prompt（stdio ndjson；按工作区运行时复用子进程）
  A->>C: Session.#executePromptInner → LlmChat.sendMessageStream / 工具执行
  C-->>A: 流式事件、工具调用
  A-->>BR: session/update · qwen/notify/* · session/request_permission
  BR-->>S: daemon 事件
  S-->>SDK: SSE GET /session/:id/events
  SDK-->>U: UI 事件（审批、工具卡片、消息流）
  U->>SDK: 用户点"允许"
  SDK->>S: 权限应答 REST
  S->>BR: 回填 request_permission
  BR->>A: ACP response
```

### 5.3 哪些宿主在跑 web-shell

```mermaid
flowchart LR
  WS["web-shell dist"]
  S1["qwen serve（浏览器直接打开）"] -->|静态托管| WS
  D["desktop（Tauri）<br/>spawn serve --port 0 --require-auth"] -->|加载| WS
  M["mobile-shell（Android WebView）"] -->|加载 daemon 托管的页面| WS
  V["vscode-ide-companion<br/>spawn serve --no-web --require-auth --allow-origin *"] -->|webview 内嵌| WS
  MAS["managed-agent-server"] -.->|managed 模式后端| WS
```

### 5.4 逐层调用代码：web-shell → sdk → serve → acp-bridge → `qwen --acp` → core

§5.2 是时序，这里把每一跳落到代码上。先分清两种关系：**import**（同进程内调函数）和**协议**（跨进程）。五个包里只有三处是 import，另外两处是跨进程：

```mermaid
flowchart LR
  subgraph P1["浏览器 / webview 进程"]
    WS["web-shell<br/>daemon/session/actions.ts"]
    SDK["@qwen-code/sdk/daemon<br/>DaemonSessionClient · DaemonClient · RestSseTransport"]
  end
  subgraph P2["qwen serve 进程（packages/cli）"]
    RT["serve/routes/<br/>session.ts · sse-events.ts · permission.ts"]
    BR["@qwen-code/acp-bridge<br/>session-control-plane.ts · BridgeClient · EventBus · PermissionMediator"]
  end
  subgraph P3["qwen --acp 子进程（packages/cli，每个工作区一个）"]
    AG["acp-integration/acpAgent.ts<br/>QwenAgent"]
    SE["acp-integration/session/Session.ts"]
    CORE["core<br/>LlmChat · ToolRegistry · tools"]
  end
  WS -->|import| SDK
  SDK ==>|"HTTP：POST /session/:id/prompt<br/>SSE：GET /session/:id/events<br/>POST /session/:id/permission/:requestId"| RT
  RT -->|"import（runtime.bridge）"| BR
  BR ==>|"spawn node cli.js --acp<br/>stdio ndjson ACP"| AG
  AG --> SE -->|import| CORE
```

粗箭头是跨进程。core 不知道 serve 和 web-shell 的存在，它只被 `qwen --acp` 子进程里的 `Session` 调用；serve 进程本身不跑 agent loop（hosted-harness profile 除外）。

#### 下行：一次 prompt

```mermaid
sequenceDiagram
  autonumber
  participant WS as web-shell<br/>actions.ts
  participant SDK as sdk<br/>DaemonSessionClient / DaemonClient
  participant RT as serve<br/>routes/session.ts
  participant CP as acp-bridge<br/>session-control-plane.ts
  participant AG as qwen --acp<br/>QwenAgent
  participant SE as Session.ts
  participant C as core<br/>LlmChat / tools
  WS->>SDK: session.submitPrompt(req)
  SDK->>RT: POST /session/:id/prompt
  RT->>CP: admitSessionPrompt → runtime.bridge.sendPrompt()
  RT-->>SDK: 202 { promptId, lastEventId, eventEpoch }
  CP->>CP: 入队（每会话串行），回显 user_message 到事件总线
  CP->>AG: entry.connection.prompt(req)（ACP session/prompt）
  AG->>SE: session.prompt(params, ctx, signal)
  SE->>C: chat.sendMessageStream(...) / invocation.execute(...)
```

**① web-shell 发起**（`web-shell/client/daemon/session/actions.ts:1435`）：

```ts
async sendPrompt(text, options) {
  // …组装 promptRequest（prompt 块、附件引用、_meta: qwen.submittedPrompt 等）
  accepted = await session.submitPrompt(promptRequest, ctrl.signal);
  options?.onAdmitted?.({ promptId: accepted.promptId });
  // 不等 HTTP 返回结果，而是等 SSE 上同一 promptId 的 turn 结束事件
  return await waitForAcceptedPromptCompletion(activePrompts, settled, sessionId, ctrl, accepted.promptId);
}
```

`session` 是 SDK 的 `DaemonSessionClient`，由 `DaemonSessionProvider.tsx` 创建并持有。

**② SDK 发 HTTP**（`sdk-typescript/src/daemon/DaemonSessionClient.ts:759`、`DaemonClient.ts:7082`）：

```ts
// DaemonSessionClient：带上 clientId，clientId 失效时自动重新注册再重试
async submitPrompt(req, signal, beforeDispatch) {
  return this.withClientIdSelfHeal(() =>
    this.client.promptNonBlocking(this.sessionId, req, signal, this.clientId));
}

// DaemonClient：非阻塞提交，serve 回 202
async promptNonBlocking(sessionId, req, signal, clientId) {
  const res = await this.transport.fetch(`${this.baseUrl}/session/${urlEncode(sessionId)}/prompt`, {
    method: 'POST',
    headers: this.headers({ 'Content-Type': 'application/json' }, clientId), // Bearer + X-Qwen-Client-Id
    body: JSON.stringify(req),
    signal,
  });
  if (res.status === 202) return await res.json(); // { promptId, lastEventId, eventEpoch }
  // …
}
```

**③ serve 路由收下，交给 bridge**（`cli/src/serve/routes/session.ts:7697`、`routes/session-prompt-admission.ts:295`）：

```ts
app.post('/session/:id/prompt', mutate(), withOwnerMutableSession(async (req, res, runtime) => {
  const admission = admitSessionPrompt(deps, {
    runtime, sessionId, prompt, request: forwardedBody, idempotencyKey, clientId, signal: abort.signal,
  });
  res.status(202).json({
    promptId: admission.promptId,
    lastEventId: admission.lastEventId,   // 客户端从这里开始订阅，不丢事件
    eventEpoch: admission.eventEpoch,
  });
}, { promptAdmission: true }));

// admitSessionPrompt 里：
const ownerBridge = runtime.bridge;
promptPromise = ownerBridge.sendPrompt(sessionId, request, signal, { promptId, clientId, /* … */ });
```

`runtime.bridge` 在 serve 启动工作区运行时时创建（`cli/src/serve/run-qwen-serve.ts:6447`）：`runtime.createAcpSessionBridge({...})`，工厂来自 `@qwen-code/acp-bridge/bridge`，经 `serve/acp-session-bridge.ts` 转出。

**④ acp-bridge 排队，然后通过 ACP 发给子进程**（`acp-bridge/src/session-control-plane.ts:11439`、`:12026`）：

```ts
sendPrompt(sessionId, req, signal, context) {
  // 校验、分配 promptId、进每会话队列（满了抛 PromptQueueFullError）、挂 deadline
  // …轮到它时：
  echoPromptToSessionBus(entry, { ...promptRequest, prompt: dispatchBlocks }, promptId, originatorClientId);
  const promptPromise = entry.connection
    .prompt(promptRequest)            // ACP session/prompt，走 stdio
    .then((response) => { /* turn_complete 广播、收尾后台 turn */ return response; });
}
```

`entry.connection` 是 `@agentclientprotocol/sdk` 的 `ClientSideConnection`，Client 这一侧的实现是 `BridgeClient`（`acp-bridge/src/channel-connection.ts:350`）：

```ts
export function createHarnessConnection(client: Client, channel: AcpChannel) {
  return new ClientSideConnection(() => client /* BridgeClient */, channel.stream);
}
```

`channel` 来自 `spawnChannel.ts:549`，就是拉起子进程：

```ts
child = spawn(
  process.execPath,
  [...nodeArgs, cliEntry, '--acp', ...(options.extraArgs ?? [])],
  { cwd: workspaceCwd, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32', env: childEnv },
);
```

**⑤ 子进程：ACP agent 收到 prompt**（`cli/src/acp-integration/acpAgent.ts:3098`、`:3284`、`:7279`）：

```ts
export async function runAcpAgent(config, settings, argv, …) {
  output = createAcpOutput(process.stdout);
  const stdin = Readable.toWeb(process.stdin);
  console.log = console.error;                 // stdout 只留给 ACP 帧
  const stream = ndJsonStream(output.stream, stdin, { /* 观测钩子 */ });
  connection = new AgentSideConnection((conn) => {
    agentInstance = new QwenAgent(config, settings, argv, conn, …);
    return agentInstance;
  }, stream);
}

class QwenAgent implements Agent {
  async prompt(params: PromptRequest) {
    const session = this.sessions.get(normalizeSessionIdForLookup(params.sessionId)); // 一个子进程托管多个会话
    // 剥离 / 校验 _meta（daemon 私有键只认受信父进程）
    return await session.prompt(sanitizedParams, invocationContext, call.controller.signal, modelPrompt);
  }
}
```

**⑥ Session 调 core**（`cli/src/acp-integration/session/Session.ts:5911` → `#executePromptInner:7057`）：

```ts
// 模型轮：直接用 core 的 LlmChat，绕过 LlmClient（§8）
const chat = this.#getCurrentChat();
sourceStream = await chat.sendMessageStream(model, { message, config: { abortSignal } }, promptId, goalPermit, …);

// 工具：自己跑 runToolCalls，从 core 的 ToolRegistry 拿工具再执行，不经过 CoreToolScheduler
const registry = this.config.getToolRegistry();
return invocation.execute(activeToolAbortSignal, onToolProgress, this.config.getShellExecutionConfig());
```

`Session.ts` 本身有 31 处 `@qwen-code/qwen-code-core/...` 深 import。

#### 上行：事件流回到 web-shell

```mermaid
sequenceDiagram
  autonumber
  participant C as core
  participant SE as Session.ts
  participant BC as acp-bridge<br/>BridgeClient
  participant EB as EventBus（每会话）
  participant RT as serve<br/>routes/sse-events.ts
  participant SDK as sdk<br/>RestSseTransport
  participant WS as web-shell<br/>DaemonSessionProvider
  C-->>SE: StreamEvent / 工具结果
  SE-->>BC: this.client.sessionUpdate(params)（ACP session/update）
  BC->>EB: prepareSessionUpdateFrames → events.publish(frame)
  WS->>SDK: activeSession.events({ signal })
  SDK->>RT: GET /session/:id/events（Last-Event-ID）
  RT->>EB: runtime.bridge.subscribeEvents(sessionId, { lastEventId, epoch })
  EB-->>RT: 帧
  RT-->>SDK: res.write(SSE)
  SDK-->>WS: 解析后的 DaemonEvent → store.dispatch
```

关键代码：

```ts
// 子进程 Session.ts:10818 —— 把模型/工具进度变成 ACP 通知
await this.client.sessionUpdate(params);

// acp-bridge bridgeClient.ts:1227 —— 在 serve 进程里收到通知，按会话发到事件总线
async sessionUpdate(params: SessionNotification) {
  const entry = this.resolveEntry(params.sessionId);
  const prepared = this.prepareSessionUpdateFrames(params, entry);
  for (const frame of prepared.frames) entry.events.publish(frame);
}

// serve routes/sse-events.ts:182 / :393 —— 订阅总线，写成 SSE
app.get('/session/:id/events', async (req, res) => {
  const iterable = runtime.bridge.subscribeEvents(sessionId, { signal, lastEventId, epoch: eventEpoch });
  for await (const event of iterable) res.write(/* id / event / data */);
});

// sdk RestSseTransport.ts:99-122 —— 带 Last-Event-ID 断线续传
headers['Last-Event-ID'] = String(opts.lastEventId);
url = `${this.baseUrl}/session/${encodeURIComponent(sessionId)}/events`;

// web-shell DaemonSessionProvider.tsx:3971 —— 消费事件，进 reducer
for await (const event of activeSession.events({ signal: eventStreamController.signal, maxQueued })) {
  // config_option_update / 消息块 / 工具卡片 / permission_request / turn_complete …
}
```

#### 权限：两段跨进程的往返

子进程里的权限请求是一个**挂起的 ACP 请求**，要等浏览器里有人投票才返回：

```mermaid
sequenceDiagram
  participant SE as Session.ts（子进程）
  participant BC as BridgeClient（serve）
  participant PM as PermissionMediator（serve）
  participant WS as web-shell
  SE->>BC: client.requestPermission(params)（ACP，挂起）
  BC->>BC: events.publish(permission_request)
  BC->>PM: 登记请求，等投票
  Note over WS: SSE 收到 permission_request，弹审批卡片
  WS->>BC: POST /session/:id/permission/:requestId<br/>→ routes/permission.ts:47 → bridge.respondToSessionPermission
  BC->>PM: 投票（校验会话归属、clientId、local-only 策略）
  PM-->>BC: 决议
  BC-->>SE: ACP 响应 { outcome }
```

```ts
// 子进程 Session.ts:15096 —— 排队发出权限请求（同一会话串行）
: this.client.requestPermission(params)

// web-shell actions.ts:2510 → sdk DaemonClient.ts:7291
async respondToPermission(requestId, response) {
  return session.respondToSessionPermission(requestId, response);
}
async respondToSessionPermission(sessionId, requestId, response, clientId) {
  return this.fetchWithTimeout(
    `${this.baseUrl}/session/${urlEncode(sessionId)}/permission/${urlEncode(requestId)}`,
    { method: 'POST', headers: this.headers({ 'Content-Type': 'application/json' }, clientId), body: JSON.stringify(response) },
    …);
}

// serve routes/permission.ts:47 → acp-bridge session-control-plane.ts:12503
app.post('/session/:id/permission/:requestId', mutate(), async (req, res) => {
  accepted = runtime.bridge.respondToSessionPermission(sessionId, requestId, response, { clientId, fromLoopback });
});
```

#### 一张表：谁调谁、靠什么

| 调用方 → 被调方 | 方式 | 入口 |
|---|---|---|
| web-shell → sdk | import `@qwen-code/sdk/daemon` | `DaemonSessionClient.submitPrompt / events / respondToSessionPermission` |
| 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` |
| serve → acp-bridge | import（同进程，`runtime.bridge`） | `sendPrompt`、`subscribeEvents`、`respondToSessionPermission` |
| acp-bridge → `qwen --acp` | spawn + stdio ndjson ACP（`ClientSideConnection` / `BridgeClient`） | `session/prompt` 下行；`session/update`、`session/request_permission`、`qwen/notify/*` 上行 |
| `qwen --acp` → core | import（同进程） | `LlmChat.sendMessageStream`、`ToolRegistry` → `invocation.execute` |
| sdk / acp-bridge → core | 只有常量和纯函数 import（sdk 构建时 inline），**不调运行时** | 见 §4.2 |

---

## 6. 专题：谁依赖 SDK，谁依赖 ACP

### 6.1 `@qwen-code/sdk`（sdk-typescript）

```mermaid
flowchart LR
  subgraph USERS["使用方"]
    WS["web-shell<br/>~450 import，/daemon 为主"]
    VSC["vscode-ide-companion<br/>/daemon 11 + 根 2"]
    QL["qwen-live<br/>/daemon"]
    CLI["cli（反向）<br/>attach、channel worker、serve 部分路由、导出"]
    WT["web-templates（dev）"]
    EXT["外部用户"]
  end
  SDK["@qwen-code/sdk"]
  subgraph SDKPARTS["SDK 内部"]
    Q["query()<br/>ProcessTransport"]
    D["/daemon<br/>DaemonClient · RestSseTransport · AcpHttp/AcpWs"]
    P["/peer<br/>UDS 跨会话"]
    MCP["qwen-serve-mcp bin"]
  end
  WS --> SDK
  VSC --> SDK
  QL --> SDK
  CLI --> SDK
  WT -.-> SDK
  EXT --> SDK
  SDK --- Q
  SDK --- D
  SDK --- P
  SDK --- MCP
  Q -->|"spawn 内嵌 CLI<br/>--input-format stream-json<br/>29 个 flag · 16 种 control subtype"| SJ{{"qwen -p stream-json<br/>nonInteractiveCli.ts"}}
  D -->|"~206 个路由字面量<br/>88 个 ACP 方法（acpRouteTable.ts）"| SERVE{{"qwen serve"}}
  P -->|"QWEN_HOME 或 ~/.qwen 下的 UDS"| IPC{{"core/src/ipc（peer）"}}
  MCP --> SERVE
  SDK -.->|"构建时 inline 8 处常量/纯函数"| CORE["core / acp-bridge"]
```

同协议的其他语言 SDK：

| SDK | stream-json `query()` | serve DaemonClient |
|---|---|---|
| sdk-typescript | ✅ | ✅ |
| sdk-java | ✅（`TransportOptionsAdapter.java`） | ✅（`qwencode/.../daemon/DaemonClient.java`） |
| sdk-python | ✅（`transport.py`） | — |

### 6.2 "ACP" 的三层含义和各自依赖方

| 含义 | 依赖方 |
|---|---|
| **`@agentclientprotocol/sdk` 库**（0.14.1） | cli（Agent 侧 `AgentSideConnection`）、acp-bridge（Client 侧）、qwen-live、vscode-ide-companion、channel-base。注意 sdk-typescript **不依赖**这个库，serve 的 `/acp` 也是手写 JSON-RPC 帧 |
| **`@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`） |
| **`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 中转） |

```mermaid
flowchart LR
  subgraph PARENTS["谁 spawn qwen --acp"]
    BR["acp-bridge（在 qwen serve 里）"]
    ZED["Zed 扩展"]
    VSC["VS Code 直连"]
    CHB["channel-base AcpBridge<br/>（qwen channel start）"]
    QL["qwen-live acp-adaptor"]
  end
  AG["qwen --acp<br/>cli/src/acp-integration/acpAgent.ts<br/>class QwenAgent implements Agent"]
  BR -->|"标准方法 + 大量私有 ext<br/>⇄ qwen/notify/*"| AG
  ZED -->|标准方法| AG
  VSC -->|"标准 + 5 个旧 ext"| AG
  CHB -->|"标准 + qwen/control/session/*"| AG
  QL -->|"标准 + live ext"| AG
  AG --> SESSION["session/Session.ts<br/>多会话 Map，按 sessionId 路由"]
  SESSION --> CORE["core"]

  HTTPACP["serve /acp HTTP+SSE / WS<br/>acp-http/dispatch.ts<br/>13 标准 + 74 个 _qwen/*"] --> BR
  SDKD["sdk AcpHttp/AcpWsTransport<br/>（默认不启用）"] -.-> HTTPACP
  CHREXT["chrome-extension"] --> HTTPACP
```

### 6.3 专题：qwen-code 里的 "channel" 是什么

"channel" 在代码里有三个互不相干的意思，读代码时很容易混：

| # | 意思 | 在哪 | 一句话 |
|---|---|---|---|
| A | **IM / 代码平台渠道**（产品功能） | `packages/channels/*`、`settings.json` 的 `channels`、`qwen channel …`、serve 的 `channel-*.ts` | 把 Telegram、微信、钉钉、飞书、企业微信、QQ、邮件、GitHub、GitLab 等的消息接进来，交给 agent 处理，再把回复发回去 |
| B | **`--channel` 启动参数**（客户端身份） | `cli/src/config/config.ts:280`、`acp-channel-fallback.ts` | 标记"谁启动了这个 CLI"：`VSCode / ACP / SDK / CI / desktop / daemon`。**只用于上报统计** |
| C | **`AcpChannel`**（进程间传输） | `acp-bridge/src/channel.ts`、`spawnChannel.ts`、`inMemoryChannel.ts` | acp-bridge 和 `qwen --acp` 子进程之间的那根 stdio 管道（测试里换成内存管道） |

另外还有一些名字里带 channel 的东西，都从属于 A：会话的 `sourceType: 'channel'`（web-shell 历史列表里过滤掉的就是这类会话）、`qwen.channel.*` 这组 `_meta` 键、`channel_loop` MCP 工具（让 channel 会话创建定时提醒，代替 `cron_create`）。npm 的 `latest / nightly` 在代码里叫 `distTag`，不叫 channel。

#### A. IM / 代码平台渠道

**规模**：`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 个文件）。

**用户怎么配**（`docs/users/features/channels/overview.md`）：

```json
{
  "channels": {
    "my-channel": {
      "type": "telegram",
      "token": "$MY_BOT_TOKEN",
      "privatePolicy": "allowlist",
      "allowedUsers": ["123456789"],
      "sessionScope": "user",
      "cwd": "/path/to/working/directory",
      "instructions": "Optional system instructions for the agent.",
      "groupPolicy": "disabled",
      "groups": { "*": { "requireMention": true } }
    }
  }
}
```

**分层**：

```mermaid
flowchart TB
  subgraph PLAT["外部平台"]
    TG["Telegram / 微信 / 钉钉 / 飞书 / QQ<br/>邮件 / GitHub / GitLab …"]
  end
  subgraph ADP["平台适配器（channel-* 或扩展里的插件）"]
    PL["ChannelPlugin<br/>{ channelType, createChannel() }"]
    CH["XxxChannel extends ChannelBase<br/>connect() · sendMessage() · disconnect()"]
  end
  subgraph BASE["@qwen-code/channel-base"]
    CB["ChannelBase.handleInbound(envelope)"]
    GATE["SenderGate / DmGate / GroupGate<br/>白名单 · 配对 · 群里是否 @"]
    RT["SessionRouter<br/>(channel, sender, chat, thread) → sessionId<br/>sessionScope: user | thread | chat_thread | single"]
    IF{{"ChannelAgentBridge 接口<br/>newSession · prompt · 事件"}}
    ACPB["AcpBridge<br/>自己 spawn qwen --acp"]
    DCB["DaemonChannelBridge<br/>经 sdk 连 qwen serve"]
  end
  TG <-->|"webhook / 长轮询 / WS"| CH
  PL --> CH
  CH -->|入站消息| CB --> GATE --> RT --> IF
  IF --> ACPB
  IF --> DCB
  IF -.->|"回复分块 / 工具事件"| CH
  CH -->|"sendMessage(chatId, text)"| TG
```

**两种运行方式**：

```mermaid
flowchart LR
  subgraph A1["独立模式：qwen channel start"]
    CB1["channel-* + channel-base<br/>（cli 进程内）"] -->|"AcpBridge：spawn node cli.js --acp"| AG1["qwen --acp"]
  end
  subgraph B1["daemon 模式：serve 托管"]
    SV["qwen serve<br/>channel-worker-supervisor.ts"] -->|"spawn cli.js channel daemon-worker"| W["worker 进程<br/>commands/channel/daemon-worker.ts"]
    W -->|"DaemonChannelBridge → sdk DaemonSessionClient<br/>HTTP + SSE"| SV
    SV -->|acp-bridge| AG2["qwen --acp"]
  end
```

daemon 模式下，channel 会话就是 serve 里的普通会话（`sourceType: 'channel'`），所以 web-shell 也能看到它，权限审批可以在 web-shell 里投票。

**一条消息的完整路径**：

```mermaid
sequenceDiagram
  autonumber
  participant P as 平台（如 Telegram）
  participant CH as XxxChannel
  participant CB as ChannelBase
  participant R as SessionRouter
  participant BR as ChannelAgentBridge
  participant AG as qwen --acp（直连或经 serve）
  P->>CH: 入站消息
  CH->>CB: handleInbound(envelope)
  CB->>CB: preflightInbound：门禁、配对、群 @、消息路由前缀（/review …）
  CB->>R: router.resolve(channel, sender, chat, thread, cwd, isGroup)
  R-->>CB: sessionId（没有就 bridge.newSession）
  CB->>BR: bridge.prompt(sessionId, text, { images, outputMode, … })
  BR->>AG: ACP session/prompt 或 POST /session/:id/prompt<br/>_meta: qwen.channel.prompt = true
  AG-->>BR: 流式回复 / 工具事件
  BR-->>CB: 回复分块事件
  CB->>CH: onResponseChunk / sendMessage(chatId, text)
  CH->>P: 出站消息
```

关键代码：

```ts
// 1. 平台适配器：一个插件就是一个工厂（channels/plugin-example/src/index.ts）
export const plugin: ChannelPlugin = {
  channelType: 'plugin-example',
  displayName: 'Plugin Example',
  requiredConfigFields: ['serverWsUrl'],
  createChannel: (name, config, bridge, options) => new MockPluginChannel(name, config, bridge, options),
};

// 2. 适配器只做"平台消息 ⇄ Envelope"（MockPluginChannel.ts）
class MockPluginChannel extends ChannelBase {
  private onInboundMessage(msg: InboundMessage) {
    this.handleInbound({ channelName: this.name, senderId: msg.senderId, senderName: msg.senderName,
                         chatId: msg.chatId, text: msg.text, isGroup: false, isMentioned: false, isReplyToBot: false });
  }
  async sendMessage(chatId: string, text: string) { this.sendOutbound(chatId, text); }
}

// 3. 公共逻辑在 ChannelBase（channel-base/src/ChannelBase.ts:492、:6745、:7239）
export abstract class ChannelBase {
  abstract connect(): Promise<void>;
  abstract sendMessage(chatId: string, text: string): Promise<void>;
  abstract disconnect(): void | Promise<void>;

  async handleInbound(envelope: Envelope) {
    if (!(await this.preflightInbound(envelope))) return;   // 门禁 / 配对 / 路由
    await this.processPreflightedInbound(envelope);
  }
  // processPreflightedInbound 里：
  //   sessionId = await this.router.resolve(this.name, envelope.senderId, envelope.chatId,
  //                                         envelope.threadId, this.config.cwd, envelope.isGroup, …);
  //   … this.bridge.prompt(sessionId, text, options)
}
```

内置适配器在 `cli/src/commands/channel/channel-registry.ts:407` 按需 `import('@qwen-code/channel-telegram')` 等加载；第三方适配器通过扩展的 `qwen-extension.json` 声明：

```json
{ "name": "qwen-channel-plugin-example",
  "channels": { "plugin-example": { "entry": "dist/index.js", "displayName": "Plugin Example Channel" } } }
```

`ChannelAgentBridge` 的两个实现：

```ts
// 独立模式：channel-base/src/AcpBridge.ts:165 —— 自己拉一个 ACP 子进程
const args = [...process.execArgv, cliEntryPath, '--acp'];
this.child = spawn(process.execPath, args, {
  cwd, stdio: ['pipe', 'pipe', 'pipe'],
  env: { ...process.env, QWEN_CODE_DISABLE_CRON: '1',
         QWEN_CODE_PRIVATE_ACP_CAPABILITY: privateParentCapability }, // 受信父进程凭据
});
this.connection = new ClientSideConnection(…);

// daemon 模式：channel-base/src/DaemonChannelBridge.ts:826 —— 经 sdk 走 serve
result = await session.prompt({
  prompt,
  _meta: {
    'qwen.channel.prompt': true,                       // serve 只对已认证的 channel worker 认这个键
    ...(options?.outputMode === 'per_task' ? { 'qwen.channel.outputMode': 'per_task' } : {}),
  },
});
```

daemon 模式的 worker 由 serve 拉起（`cli/src/serve/channel-worker-supervisor.ts:1057`），worker 里用 SDK 回连 serve（`commands/channel/daemon-worker.ts:1064`）：

```ts
// serve 侧
const argv = [opts.cliEntryPath, 'channel', 'daemon-worker', ...selectionChannelArgs(opts.selection)];
const env = createWorkerEnv({ daemonUrl, workspace, daemonToken });   // 带一次性 prompt 授权凭据

// worker 侧
const bridge = new DaemonChannelBridge({
  cwd: daemonWorkspace,
  sessionFactory: createDaemonSessionFactory({
    client, DaemonSessionClient: sdk.DaemonSessionClient,
    clientId: `qwen-channel-worker:${process.pid}`,
  }),
  sessionPermissionVote: capabilities.features.includes(SESSION_PERMISSION_VOTE_FEATURE),
});
```

#### B. `--channel` 启动参数

```ts
// cli/src/config/config.ts:280
channel: {
  type: 'string',
  choices: ['VSCode', 'ACP', 'SDK', 'CI', 'desktop', 'daemon'],
  description: 'Channel identifier (VSCode, ACP, SDK, CI, desktop, daemon)',
},
```

谁传什么：

| 启动方 | 值 | 怎么来的 |
|---|---|---|
| VS Code 插件 | `VSCode` | `acpConnection.ts` 显式传 `--channel=VSCode` |
| SDK `query()` | `SDK` | `sdk-typescript/src/transport/ProcessTransport.ts:320` 显式传 `--channel=SDK` |
| serve 拉起的 `--acp` 子进程 | `daemon` | 不传参数；acp-bridge 设 `QWEN_CODE_SERVE=1`，子进程回退时识别 |
| Tauri desktop 经 serve | `desktop` | desktop 设 `QWEN_CODE_DESKTOP=1`，子进程继承 |
| 其他 `--acp`（Zed 等） | `ACP` | 默认回退值 |

```ts
// cli/src/config/acp-channel-fallback.ts
export function resolveAcpChannelFallback(env = process.env): string {
  if (env['QWEN_CODE_DESKTOP'] === '1') return 'desktop';
  if (env['QWEN_CODE_SERVE'] === '1') return 'daemon';
  return 'ACP';
}

// core/src/telemetry/qwen-logger/qwen-logger.ts:356 —— 唯一的读取方
...(this.config?.getChannel?.() ? { channel: this.config.getChannel() } : {}),
```

`Config.getChannel()` 在 core 里只有这一个调用方，所以它**不影响任何行为**，只是 RUM 上报里的一个维度。另外注意：daemon 模式下的 IM channel 会话，上报的 `channel` 是 `daemon`，不是 IM 平台名。

#### C. `AcpChannel`（acp-bridge 的传输）

```ts
// acp-bridge/src/channel.ts:28
export interface AcpChannel {
  stream: Stream;                       // ACP ndjson 双向流
  transportFailed?: Promise<unknown>;
  transportGuard?: AcpChannelTransportGuard;
  kill(): Promise<void>;
  killSync(): void;
}
export type ChannelFactory = (workspaceCwd: string, childEnvOverrides?, signal?, startup?) => Promise<AcpChannel>;
```

默认工厂是 `defaultSpawnChannelFactory`（`spawnChannel.ts:549`，拉起 `qwen --acp`，见 §5.4），测试用 `createInMemoryChannel()`。acp-bridge 里的 `channel-connection.ts`、`channel-lifecycle.ts`、`channel-liveness.ts`、`channel-startup.ts` 等十来个文件都是这个意思，和 A 无关。

#### 我的看法

1. **命名冲突的代价是真实的。** acp-bridge 里有大量 `channel-*.ts` 文件（意思 C），serve 里也有大量 `channel-*.ts` 文件（意思 A）。上报里的 `channel=daemon`（意思 B）又会把 A 的会话也算进去。新人在 serve 目录里看到 `channel-worker-*` 和 `managed-engine-channel-factory.ts` 放在一起，很难分清哪个是 IM、哪个是传输。建议：
   - B 改名为 `--client` / `clientKind`，并保留 `--channel` 作为别名。它本来就是"客户端身份"，而且只影响统计。
   - C 改名为 `AcpTransport`（`ChannelFactory` → `AcpTransportFactory`），只在 acp-bridge 内部，改动面小。
   - "Channel" 只留给 A。
2. **A 是一个独立的产品子系统，体量和 web-shell 相当。** channel-base 加适配器约 6.5 万行，再加上 cli 里的命令和 serve 托管代码。它通过 `ChannelAgentBridge` 接口和 agent 解耦，有两个实现，这个抽象做得好。问题在依赖方向：cli 依赖全部 10 个 `channel-*` 包（§4.2），等于把所有平台 SDK 都塞进了 CLI 安装包。更合理的是内置适配器也按扩展的方式按需安装，cli 只依赖 `channel-base`。
3. **两种运行方式长期并存，有重复。** 独立模式（`AcpBridge`）和 daemon 模式（`DaemonChannelBridge`）各自实现了会话管理、权限、附件和私有 `_meta`。daemon 模式能被 web-shell 看到、审批和恢复，能力更全。建议把 daemon 模式作为默认，独立模式只保留给"不想常驻 serve"的场景，新功能先只做 daemon 模式。
4. **对融合的影响**：A 是 Qwen 独有的产品能力，按融合方案的规则应放在 Qwen 产品层；它通过 `qwen --acp`（独立模式）或 serve（daemon 模式）接入，依赖的是 ACP 私有扩展（`qwen/control/session/*`、`qwen/control/session/btw`）和 `qwen.channel.*` 这组 `_meta` 键。切到新内核时，这些都要列进兼容清单。

### 6.4 专题：为什么把 daemon 客户端放进 SDK，以及这样做的得失

#### 当初的理由

daemon 客户端是在 `qwen serve` 第一阶段（#3889，2026-05-13，设计 issue #3803）里和 serve 一起加进 `@qwen-code/sdk` 的。提交说明给了三条理由：

1. **验证"协议同构"**：SDK 客户端可以不走 `query()` 的 stdio + stream-json，直接通过 HTTP 驱动 daemon，端到端跑通。
2. **和 `query()` 并列，不替代它**：`DaemonClient` is a sibling of ProcessTransport, not a replacement. `query()` 用户不受影响；需要 daemon 模式能力的应用（多客户端 attach、共享 MCP 池、网络可达、先到先得的权限投票）自己选择 `new DaemonClient(...)`。
3. **wire 类型放在 SDK 一侧，SDK 不依赖 CLI**（"Wire types live SDK-side (no SDK→CLI dep)"），兼容性靠 `/capabilities` 的 `v` 和 `features` 协商。

官方文档 `docs/developers/daemon/13-sdk-daemon-client.md` 把它定位成"连接 `qwen serve` 的**标准**方式……其他所有适配器都依赖它"。入口在 SDK 根导出和子路径里都有（`sdk-typescript/src/index.ts`）：

```ts
export { query } from './query/createQuery.js';      // 模式一：spawn CLI，走 stream-json
export { Query } from './query/Query.js';
// Daemon HTTP client (talks to `qwen serve`)          // 模式二：HTTP + SSE 连 serve
export { DaemonClient, DaemonSessionClient, WorkspaceDaemonClient, … } from './daemon/index.js';
```

```jsonc
// sdk-typescript/package.json exports
".":                   "./dist/index.mjs",
"./daemon":            "./dist/daemon/index.js",       // web-shell / VS Code 用这个
"./daemon/transports": "./dist/daemon/transports.js",  // RestSse / AcpHttp / AcpWs
"./daemon/transcript": "./dist/daemon/transcript.js",
"./daemon/ui":         "./dist/daemon/ui/index.js",    // normalizer + transcript reducer + 渲染辅助
"./peer":              "./dist/peer/index.js"
```

#### 现在长成了什么样

```mermaid
flowchart TB
  subgraph SDKPKG["@qwen-code/sdk（仓库 0.1.32；npm 最新 0.1.35 解包 81 MB / 904 个文件）"]
    direction LR
    Q["query()<br/>约 1 万行（含 peer 等）<br/>需要 CLI"]
    D["daemon/<br/>约 4 万行<br/>DaemonClient 10k · types 6.3k · events 3.5k<br/>DaemonSessionClient 1.8k · ACP 传输"]
    UI["daemon/ui/<br/>normalizer 2.4k · transcript 3k<br/>UI 状态机"]
    CLIB[["dist/cli.js<br/>prepack 时打进来的整个 CLI"]]
  end
  Q --> CLIB
  WS["web-shell（浏览器）"] -->|"/daemon、/daemon/ui"| D & UI
  VSC["VS Code 插件"] -->|"/daemon"| D
  QL["qwen-live"] --> D
  CLI["cli 自己<br/>attach · channel worker · serve 路由"] -->|"/daemon、/daemon/ui<br/>（serve 用 SDK 里的类型当 wire 契约）"| D
  EXT["外部：QwenMate 等"] -->|"根导出 query()"| Q
  D -. "构建时 inline 常量 / 纯函数<br/>types-sync.ts 编译期断言两边类型一致" .-> BRC["acp-bridge / core"]
```

几个从代码里看出来的事实：

**① daemon 已经是 SDK 的主体。** `src/daemon` 非测试代码约 4 万行，SDK 其余部分约 1 万行。"SDK 的一个功能"已经变成"SDK 主要就是 daemon 客户端"。

**② SDK 实际上成了协议定义包。** serve（服务端）反过来从客户端 SDK 导入 wire 类型：

```ts
// cli/src/serve/routes/subscription-auth.ts
import type { DaemonSubscriptionFlow } from '@qwen-code/sdk/daemon';
// cli/src/serve/routes/daemon-update.ts
import type { DaemonUpdateStatus } from '@qwen-code/sdk/daemon';
// cli/src/serve/web-shell-preauth.ts
import { WEB_SHELL_PWA_ASSETS } from '@qwen-code/sdk/daemon';
```

同时 SDK 又从 acp-bridge / core 导入常量（构建时 inline），并且在 `daemon/types-sync.ts` 里用编译期断言保证自己的副本和 acp-bridge 那份一致：

```ts
import type { BridgePendingPermissionInteraction } from '@qwen-code/acp-bridge/bridgeTypes';
import type { DaemonPendingPermissionInteraction } from './types.js';

type PendingPermissionInteractionStaysInSync = Assert<
  MutuallyAssignable<BridgePendingPermissionInteraction, DaemonPendingPermissionInteraction>
>;
```

也就是说，同一份契约有两处定义（`acp-bridge/bridgeTypes.ts` 和 `sdk/daemon/types.ts`），靠断言保持一致；服务端还会反向引用客户端那份。§11 第 1 条说的依赖环就是这么来的。

**③ 一个包装了两种很不一样的东西。** `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。

**④ 版本号和 serve 分开。** SDK 是 0.1.32，CLI 是 0.27.2，靠 `capabilities.features` 做兼容。真正需要版本错开容忍的只有外部使用方；web-shell 和 VS Code 插件都是和 serve 同一次构建发布的。

#### 我的看法

**放在 SDK 里，大方向是对的。**

- 同一个协议只有一个官方客户端。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 共用一份，比各写一份强得多。
- 自己的产品用的就是对外发布的那份客户端，公开 API 的质量有保障。
- `daemon/` 保持浏览器安全（不导入 `node:`），所以 web-shell 能直接用。这个约束守得很好。

**问题出在包的切分，不在放的位置。** 四件事放进了同一个发布单元：协议定义、HTTP 客户端、UI 状态机、CLI 运行时。后果是：

1. **协议没有自己的家。** 服务端引用客户端的类型，客户端 inline 服务端的常量，两份类型靠断言同步。协议应该是双方都依赖的第三个包，而不是放在任何一方里。
2. **体积和依赖错配。** daemon 使用方被迫带上 CLI bundle。
3. **语义化版本被绑在一起。** `query()` 用户（例如 QwenMate，见 IDE 集成建议 §1.5）和 daemon 用户共用一个版本号。daemon 协议迁到 serve v2 时，SDK 升到 1.x 会连带波及只用 `query()` 的人，这正是 IDE 文档 §4.5 担心的事。
4. **UI 状态机放进了 SDK。** `daemon/ui`（normalizer + transcript reducer，约 5.4k 行）是给渲染端用的，和"连接 serve"的客户端是两层东西。共享它没问题，但它的变化频率跟着 UI 走，不该和客户端绑在同一个版本号上。

#### 建议的切分

```mermaid
flowchart LR
  subgraph NOW["现在"]
    direction TB
    S1["@qwen-code/sdk<br/>query() + daemon 客户端 + daemon/ui + 协议类型 + CLI bundle"]
    SV1["serve（cli）"] -->|"import type"| S1
    S1 -. "inline + types-sync 断言" .-> BR1["acp-bridge / core"]
  end
  subgraph NEXT["建议"]
    direction TB
    PROTO["@qwen-code/protocol<br/>daemon wire 类型 · 事件名 · 常量 · capabilities<br/>（可由 OpenAPI 生成或反过来生成 OpenAPI）"]
    DC["@qwen-code/sdk/daemon<br/>只有 HTTP/SSE 客户端，浏览器安全，无 CLI"]
    DUI["@qwen-code/sdk/daemon/ui<br/>（或独立包）UI 状态机"]
    QRY["@qwen-code/sdk 根<br/>query()；CLI 改为 optionalDependency<br/>或优先用本机已装的 qwen"]
    SV2["serve（cli）"] --> PROTO
    BR2["acp-bridge"] --> PROTO
    DC --> PROTO
    DUI --> DC
  end
  NOW --> NEXT
```

1. **抽出 `@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 里做一致性检查。
2. **CLI bundle 移出 SDK 主包。** 变成 optionalDependency（例如 `@qwen-code/sdk-cli-runtime`），或者让 `query()` 优先找本机的 `qwen`，找不到才提示安装。daemon 使用方从 81 MB 降到几 MB。
3. **导入路径不变，各子路径语义化版本独立。** `@qwen-code/sdk/daemon` 这个导入路径保持兼容，底下可以是独立发布的包再转出。daemon 协议升到 v2 时，只有 daemon 客户端升大版本，`query()` 用户不受影响。
4. **`daemon/ui` 视情况独立。** 如果 UI 状态机的变更频率明显高于客户端，就拆成单独的包，让 web-shell 和 VS Code 锁定自己的版本。

和融合方案的关系：融合后的"SDK 1.x → serve v2"本质上是 daemon 客户端和协议的大版本升级。先按上面切开，1.x 的破坏性变更就只落在 daemon 那一部分，`query()` 的外部用户可以继续留在 0.x。

### 6.5 专题：qwen-live 是什么

#### 一句话

**Qwen Live 是一个"语音指挥编码 agent"的产品**：用户对着 macOS 上的小浮层说话，一个实时语音模型（DashScope `qwen3.5-omni-plus-realtime`）负责对话、判断意图，需要动手的事通过 `handoff` 工具交给一个或多个编码会话去做，结果再用语音播报回来。语音模型是"前台"，编码 agent 是"后台工人"。

它由三个部分组成，而且有**两个实现**：

| 部分 | 包 / 位置 | 规模 | 角色 |
|---|---|---|---|
| **Live daemon（独立版）** | `packages/qwen-live`，npm `@qwen-code/qwen-live`，bin `qwen-live` | 约 4.2 万行 | 控制面：连 Host、连实时语音模型、调度编码会话、记忆、主动提醒 |
| **Live daemon（内置版）** | `packages/cli/src/serve/live/`（`qwen serve` 的 `/live/*` 路由） | 约 1.1 万行 | 同一件事的早期实现，挂在 serve 里，web-shell 设置里开关，默认关闭 |
| **Live Host** | `packages/live-host`（Electron，macOS 专用） | 约 1.3 万行 | 原生"外壳"：浮层小球、全局快捷键 `⌘E`、麦克风 / 扬声器、摄像头、截屏（`appshot.mm`） |

历史：内置版先出（#7859，2026-08-05，"web-shell: add native Live Voice"）；独立版后出（#10367，2026-09-01，"standalone voice daemon package"）。独立版 README 已经把"连 `qwen serve`"标成 Legacy 后端。

和本文其他部分的关系：web-shell 的会话列表里过滤掉的 `sourceType: 'qwen-live'` 和 `sourceId` 前缀 `realtime_voice:`（见 IDE 集成建议 §1.3.2 的 EmbeddedApp 过滤代码），就是 Live 派出去的编码会话。

#### 全景

```mermaid
flowchart LR
  subgraph MAC["用户的 Mac"]
    HOST["Live Host（Electron）<br/>浮层 · ⌘E · 麦克风 / 扬声器<br/>摄像头 · 原生截屏"]
  end
  DISC[("~/.qwen/live/daemon.json<br/>发现文件：端口 · token · protocolVersion")]
  subgraph LIVE["Live daemon（二选一）"]
    SA["qwen-live（独立版）<br/>LiveSession 编排器"]
    BI["qwen serve /live/*（内置版）"]
  end
  OMNI(["DashScope Realtime<br/>qwen3.5-omni-plus-realtime<br/>WebSocket：VAD · 语音对话 · 工具调用"])
  subgraph BACKENDS["编码后端（可多个，按会话路由）"]
    QA["AcpAdaptor<br/>spawn qwen --acp / qodercli --acp /<br/>gemini --experimental-acp / claude-agent-acp / codex-acp"]
    QS["QwenCodeAdaptor（Legacy）<br/>sdk DaemonClient → qwen serve"]
  end
  MEM[("~/.qwen-live/<br/>config.json · sessions/*.jsonl<br/>memories/ SQLite FTS5")]

  SA & BI -->|写| DISC
  HOST -->|读| DISC
  HOST <-->|"WS /live/host（Live Host 协议 v9）<br/>音频帧 · 截图 · 状态"| SA
  HOST <-.->|同协议| BI
  SA <-->|"WS：音频 + 工具调用"| OMNI
  SA -->|"handoff / session_create …"| QA & QS
  SA --- MEM
```

要点：

- **Host 不认 daemon 是哪一个**：两个 daemon 写同一个发现文件（`~/.qwen/live/daemon.json`）、开同一个 WS 路径（`/live/host`），Host 读到谁就连谁，并校验 `protocolVersion`。
- **对话归 Live，任务归后端**：Live 自己的通话记录在 `~/.qwen-live/sessions/`；派给后端的编码会话是普通会话，挂断后继续跑。
- **后端不限于 Qwen**：独立版通过 ACP 可以驱动 qodercli、Gemini、Claude Code、Codex。这是唯一一个把 qodercli 当作一等后端的仓内组件。

#### 一次"说一句话 → 改代码 → 播报结果"

```mermaid
sequenceDiagram
  autonumber
  participant U as 用户
  participant H as Live Host
  participant L as qwen-live LiveSession
  participant O as Omni Realtime
  participant A as BackendAdaptor
  participant B as 编码 agent（qwen --acp 等）
  U->>H: 说话（⌘E 开始通话）
  H->>L: WS 音频帧
  L->>O: 转发音频
  O-->>L: 语音回复："好，我让编码会话去改"
  O-->>L: 工具调用 handoff({ task: 用户原话, session?, input_refs? })
  L->>A: adaptor.prompt(handle, blocks, { steer: busy })
  A->>B: ACP session/prompt（或 POST /session/:id/prompt）
  L-->>O: 立即返回回执（accepted / queued / steered）
  B-->>A: 流式进度、权限请求、完成
  A-->>L: BackendEvent
  L->>O: Injector 注入 [COMPLETE] / 权限请求等静默上下文
  O-->>H: 语音播报结果
  H-->>U: 扬声器
```

#### 关键代码

**① 语音模型能用的工具**（`qwen-live/src/tools/definitions.ts`）。Live 的"能力"就是这一组工具：

```ts
export const APPSHOT_TOOL_NAME = 'appshot';                 // 截屏 / 摄像头取一帧
export const SESSION_LIST_TOOL_NAME = 'session_list';       // 列出所有后端的会话
export const SESSION_CREATE_TOOL_NAME = 'session_create';   // 开一个新的并行工作流
export const HANDOFF_TOOL_NAME = 'handoff';                 // 把任务交给编码会话
export const SESSION_MONITOR_TOOL_NAME = 'session_monitor';
export const SESSION_STOP_TOOL_NAME = 'session_stop';
export const RESPOND_PERMISSION_TOOL_NAME = 'respond_permission'; // 用语音回答后端的权限请求
export const CREATE_PROACTIVE_MONITOR_TOOL_NAME = 'create_proactive_monitor'; // 盯着屏幕，满足条件时提醒
export const CREATE_PROACTIVE_TIMER_TOOL_NAME = 'create_proactive_timer';
// … 以及 memory 的 omniretrieve / omnibio

// handoff 的定义（节选）
{
  name: HANDOFF_TOOL_NAME,
  description:
    "Send the user's request to a coding session for execution. This is the default action for " +
    'anything that touches files, runs commands … Pass the user\'s own words in `task`; do not rewrite them. ' +
    'Returns a receipt immediately — the result arrives later as a [COMPLETE] context message. …',
  parameters: {
    type: 'object',
    properties: {
      task: { type: 'string', description: "The user's request, in their own words." },
      session: { type: 'string', description: 'Target session handle from session_list (e.g. "session_1").' },
      input_refs: { type: 'array', items: { type: 'string' }, description: 'Asset ids to attach (e.g. an appshot screenshot).' },
    },
    required: ['task'],
  },
}
```

**② 编排器处理 `handoff`**（`qwen-live/src/orchestrator/live-session.ts:2353`）：

```ts
handlers.set(HANDOFF_TOOL_NAME, async (args, ctx) => {
  const task = typeof args['task'] === 'string' ? args['task'].trim() : '';
  const { handle, backend } = await this.resolveHandoffTarget(context, args['session']);
  const blocks = await this.buildHandoffBlocks(task, ctx.activeTranscript, args['input_refs']); // 附上近期对话和截图
  const adaptor = this.adaptorFor(backend);
  const caps = adaptor.capabilities();
  if (!caps.imageInput) /* 去掉图片，回执里说明 */;
  this.ensurePump(handle, backend);                       // 开始消费这个会话的事件流
  const receipt = await adaptor.prompt(backend, sentBlocks, {
    steer: adaptor.isBusy(backend) && caps.steering !== 'none', // 会话忙时追加指令而不是新开
  });
  return receipt;                                          // 立刻回给语音模型，不等任务完成
});
```

**③ 后端抽象**（`qwen-live/src/adaptor/types.ts`）：

```ts
interface BackendAdaptor {
  readonly name: string;
  capabilities(): BackendCapabilities;        // imageInput、steering 等
  preflight(): Promise<void>;
  createSession(opts?: { cwd?: string; label?: string }): Promise<BackendHandle>;
  listSessions(): Promise<SessionSummary[]>;
  prompt(handle, blocks: readonly ContentBlock[], opts?): Promise<PromptReceipt>;
  events(handle, …): AsyncIterable<BackendEvent>;
  isBusy(handle): boolean;
  cancel(handle): Promise<void>;
  cancelJob?(handle, jobRef): Promise<CancelJobResult>;
  respondPermission(…): Promise<…>;
  close(): Promise<void>;
}
```

两个实现：

```ts
// AcpAdaptor（acp-adaptor.ts:769, :515）—— 任意 ACP agent
const child = spawn(this.options.command, this.options.args ?? [], {   // 例如 'qodercli', ['--acp']
  cwd, stdio: ['pipe', 'pipe', 'pipe'],
  env: { ...process.env, ...this.options.env, QWEN_CODE_NO_RELAUNCH: 'true' },
});
// … new ClientSideConnection(…)
const response = await conn.prompt({ sessionId, prompt: blocks.map(toAcpBlock) });

// QwenCodeAdaptor（qwen-code-adaptor.ts:346, :406）—— 经 sdk 连 qwen serve
this.client = new DaemonClient({ baseUrl: options.baseUrl, token: options.token });
const session = await this.client.createOrAttachSession({
  workspaceCwd: cwd,
  sessionScope: 'thread',
  sourceType: 'qwen-live',          // web-shell / VS Code 历史列表里据此过滤
}, this.options.clientId);
```

**④ 连实时语音模型**（`qwen-live/src/realtime/realtime-session.ts:617`）：一个到 DashScope Realtime 的 WebSocket，音频双向流，模型侧负责 VAD、直接回答和工具调用。后端事件由 `orchestrator/injector.ts` 排队，在模型不说话的间隙以"静默上下文"注入（`[COMPLETE]`、权限请求、停止确认等），避免打断播报。

**⑤ Host 发现与握手**（`qwen-live/src/host/discovery.ts`、`live-host/src/main/discovery.ts`、`daemon-connection.ts`）：

```ts
// daemon 侧：写 ~/.qwen/live/daemon.json（加锁、原子写）
export const LIVE_DISCOVERY_RELATIVE_PATH = path.join('live', 'daemon.json');
const HOST_WS_PATH = '/live/host';

// Host 侧：读同一个文件，连上后先比协议版本
if (!configured) return join(homedir(), '.qwen', 'live', 'daemon.json');
…
if (message.protocolVersion !== LIVE_PROTOCOL_VERSION) { /* 拒绝连接 */ }
```

#### 独立版里另外几块

| 模块 | 行数 | 做什么 |
|---|---|---|
| `memory/` | 约 5k | 跨通话记忆：对话、用户事实、可选的视觉观察，存在 `~/.qwen-live/memories/<id>/`（SQLite FTS5，需 Node ≥ 22.13）；有整理模型（默认 `qwen3.7-plus`） |
| `proactive/` | 约 4k | 主动任务：盯屏幕（定时截图让模型判断）、定时器、播报 |
| `host/` | 约 4k | Host 协调、Host 安装器（下载签名的 `.app`，校验 SHA-256、签名、Gatekeeper） |
| `subagents/` | 约 0.7k | 给浮层上的 "Subagents" 面板记账：每个 handoff / 监控任务的状态，不编进度百分比 |
| `permissions/` | 约 0.3k | 后端权限请求的中转：通话中用语音回答，挂断后在面板里回答 |
| `init.ts` | — | `qwen-live init` 向导：扫描 PATH 里的 qodercli / qwen / gemini / claude / codex，选默认后端，填 DashScope key |

#### 我的看法

1. **定位清楚，设计有意思。** 用实时语音模型做"前台调度"、编码 agent 做"后台执行"，两边用 `handoff` + 回执 + 静默上下文注入解耦。语音模型不用等任务完成，用户可以继续说话、开并行任务。`BackendAdaptor` 让后端可以换成任何 ACP agent，这层抽象做得好。
2. **两个实现并存是最大的问题。** `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` 的依赖。
3. **它其实不属于 qwen-code 的"内核"，而是一个独立产品。** qwen-live 只通过协议（ACP 或 serve REST）用 qwen-code，自己有配置目录（`~/.qwen-live/`）、自己的会话格式、自己的记忆库，还能驱动别家 agent。放在这个 monorepo 里主要是为了共用 sdk 和 Host 发布流程。
4. **对融合的影响：**
   - 独立版已经把 `qodercli --acp` 当作一等后端，所以融合后的 `qwen-next --acp` 只要保持 ACP 兼容就能直接用，不需要额外适配。
   - `QwenCodeAdaptor` 依赖 sdk 的 `DaemonClient`，属于 IDE 集成建议 §4.5 说的 SDK 消费方，serve v2 时要一起迁，或者干脆按 README 的 Legacy 标注删掉，只保留 ACP 路径。
   - 内置版依赖 serve 和 cli 的 `ui/voice`，是迁移成本最高的部分。按上面第 2 条先删掉，迁移面会小很多。
5. **平台限制**：Host 只有 macOS（需要原生麦克风、全局快捷键和截屏），Linux / Windows 用户目前用不了语音。

---

## 7. cli 内部：入口分派

`qwen` 一个 bin 承载了所有模式。分派在 `packages/cli/index.ts` → `src/cli.ts` → `src/llm.tsx`。

```mermaid
flowchart TD
  IDX["packages/cli/index.ts"]
  IDX -->|"managed-runtime-bootstrap"| MRB["serve/managed-runtime-bootstrap.ts<br/>Java 的私有 stdio worker"]
  IDX -->|"managed-runtime-bootstrap-worker"| MRS["serve/managed-runtime-ssh-worker.ts"]
  IDX -->|"--workspace-recovery-worker"| WRW["serve/workspace-recovery-worker.ts"]
  IDX -->|其他| CLIENTRY["src/cli.ts runCliEntryPoint"]
  CLIENTRY -->|"快速路径：mcp / memory / help / session-send-mcp"| FAST["yargs 子命令"]
  CLIENTRY --> MAIN["src/llm.tsx main()"]
  MAIN -->|"yargs 子命令<br/>(config/config.ts 注册)"| SUB["serve · daemon · attach · channel · sessions · agents<br/>batch · board · auth · mcp · memory · extensions · hooks<br/>review · autofix-pr · sandbox · update"]
  SUB -->|serve| SERVE["serve/run-qwen-serve.ts<br/>createServeApp (server.ts:890)"]
  MAIN -->|"--acp / --experimental-acp"| ACP["acp-integration/acpAgent.ts runAcpAgent"]
  MAIN -->|"TTY 交互，renderer=opentui"| OTUI["ui/opentui/start-opentui-ui.ts"]
  MAIN -->|"TTY 交互，默认"| INK["ui/startInteractiveUI.ts（Ink）"]
  MAIN -->|"--input-format stream-json"| SJ["nonInteractive runNonInteractiveStreamJson"]
  MAIN -->|"-p / 管道输入"| HL["nonInteractiveCli.ts runNonInteractive"]
  SERVE -->|"默认 profile"| BRG["acp-bridge → spawn qwen --acp"]
  SERVE -->|"--profile hosted-harness"| HH["hosted-harness-*.ts（自带 loop）"]
```

`cli/src` 主要目录：

| 目录 | 内容 | 规模（生产行） |
|---|---|---|
| `serve/` | daemon：Express app、70 多个 `register*Routes`、`acp-http/`、channel worker、managed/hosted、live、web-shell 静态托管 | 约 27.6 万 |
| `ui/` | Ink TUI（`ui/opentui/` 是 OpenTUI） | 约 16.0 万 + 4.8 万 |
| `acp-integration/` | `qwen --acp` agent 侧（`acpAgent.ts` 18k 行，`session/Session.ts` 21k 行） | 约 5.0 万 |
| `commands/` | 17 个顶层子命令，`review/` 最大（`/review` skill 的确定性步骤），见 §7.1 | 约 12.8 万 |
| `nonInteractive/` + `nonInteractiveCli.ts` | headless、stream-json 控制协议 | — |
| `config/`、`services/`、`runtime/`、`startup/` 等 | 运行时装配 | 约 7.2 万 |

### 7.1 子命令全览

`qwen` 除了"跑 agent"的几种模式（交互 TUI、`-p`、stream-json、`--acp`），还挂了 17 个顶层子命令，注册在 `cli/src/config/config.ts:907-941`：

```ts
yargsInstance
  .command(mcpCommand).command(memoryCommand).command(extensionsCommand).command(authCommand)
  .command(hooksCommand).command(channelCommand).command(boardCommand)
  .command(serveCommand)      // Stage 1 daemon
  .command(daemonCommand)     // local daemon inspection and control
  .command(attachCommand)     // terminal client for a running daemon session
  .command(sessionsCommand).command(agentsCommand).command(batchCommand)
  .command(updateCommand).command(sandboxCommand);

// /review、/autofix-pr 的辅助命令很大，只在 argv 里出现时才加载
if (rawArgv.includes('review'))     yargsInstance.command((await import('../commands/review.js')).reviewCommand);
if (rawArgv.includes('autofix-pr')) yargsInstance.command((await import('../commands/autofix-pr.js')).autofixPrCommand);
```

另外 `cli.ts` 对 `mcp`、`memory`、`help`、`session-send-mcp` 有一条快速路径，不走完整的 `llm.tsx main()` 启动（见上图）。

#### 按"跟谁打交道"分组

```mermaid
flowchart LR
  subgraph G1["① 本地配置管理<br/>直接读写 ~/.qwen 和项目 .qwen"]
    MCP["mcp<br/>add · remove · list · approve · reject · reconnect"]
    EXT["extensions<br/>install · uninstall · link · new · enable · disable · update · settings · sources"]
    MEM["memory<br/>import codex"]
    HK["hooks（提示用 /hooks）"]
    AU["auth（已移除，只打印提示）"]
    UP["update（自更新）"]
    SB["sandbox（检查 / 验证工具隔离）"]
  end
  subgraph G2["② daemon 生命周期与客户端<br/>经 HTTP 连 qwen serve"]
    SV["serve（前台跑 daemon）"]
    DM["daemon<br/>start · stop · restart · status · logs · token"]
    AT["attach（终端 attach 到 daemon 会话）"]
    AG["agents<br/>join · session-send-mcp"]
  end
  subgraph G3["③ 多会话 / 多 agent 协作<br/>本机文件与 UDS"]
    SS["sessions<br/>list · ps · add · remove · controllers"]
    BD["board<br/>task · claim · done · ask · answer · show · prune"]
  end
  subgraph G4["④ 外部平台集成"]
    CH["channel<br/>start · stop · status · set · reload · pairing · …"]
    BT["batch<br/>run · check · collect · list · retry · cancel · clean"]
  end
  subgraph G5["⑤ 给内置 skill 用的确定性工具"]
    RV["review<br/>约 45 个子命令（fetch-pr · capture-local · agent-prompt · findings · compose-review · submit · run …）"]
    AF["autofix-pr<br/>prepare · snapshot · fix-start · fix-end · push · reply · status · …"]
  end

  G1 --> CORE[("core<br/>Storage · settings · McpClientManager · 扩展管理")]
  SV --> SERVE{{"qwen serve 进程"}}
  DM -->|"spawn detached: cli.js serve --port … --no-token-qr"| SERVE
  AT -->|"sdk DaemonClient + /daemon/ui"| SERVE
  AG -->|"join link → 本机 serve 的 agent-host"| SERVE
  SS --> REG[("会话注册表 · Agent View 记录<br/>peer 控制器令牌")]
  BD --> BFS[("board 目录（文件 + 锁）<br/>core/board → agents/team/board-*.ts")]
  CH -->|"独立模式 AcpBridge / daemon-worker"| SERVE
  BT -->|"DashScope Batch API（HTTP）"| DS(["DashScope"])
  RV & AF -->|"gh / git / 本地文件"| GH(["GitHub · git 工作区"])
  SKILL["内置 skill<br/>/review · /autofix-pr"] -->|"Shell 工具里调用 qwen review … / qwen autofix-pr …"| RV & AF
```

#### 逐个说明

| 命令 | 生产代码行数 | 子命令 | 做什么 | 依赖 |
|---|---|---|---|---|
| `mcp` | 1.2k | add / remove / list / approve / reject / reconnect | 管理 MCP 服务器配置，审批项目级 MCP | core（settings、MCP 客户端） |
| `extensions` | 1.8k | install / uninstall / link / new / enable / disable / update / settings / sources | 管理扩展（`qwen-extension.json`，可带 MCP、skills、channels、commands） | core |
| `memory` | 0.2k | import codex | 预览并导入外部工具（Codex）的记忆 | core |
| `hooks` | 25 行 | — | 只提示"交互模式里用 `/hooks`" | — |
| `auth` | 71 行 | 旧子命令（`api-key`、`qwen-oauth` 等） | **已移除**，只打印迁移提示；认证改在 TUI `/auth`、web-shell 或 serve 的认证接口里做 | — |
| `update` | 0.2k | — | 自更新（区分 npm 安装 / 独立安装、`latest` / `nightly` dist-tag） | `ui/standalone-update`、`installationInfo` |
| `sandbox` | 0.3k | `sandbox [cmd...]` | 检查当前解析出的工具隔离后端，验证它，或在隔离里跑一条命令 | core `runtime-info` |
| `serve` | 1.4k | — | 前台启动 daemon（§5、§9） | `serve/` |
| `daemon` | 1.9k | start / stop / restart / status / logs / token | 后台管理 `qwen serve`：detached spawn、写发现记录、读日志、取 token | `serve/daemon-discovery` |
| `attach` | 0.4k | — | 终端里 attach 到 daemon 上的某个会话，渲染事件、可发 prompt | **sdk** `DaemonClient`、`DaemonSessionClient`、`/daemon/ui` |
| `agents` | 0.5k | join `<link>` / session-send-mcp | 把本机正在跑的 serve 作为 Agent Host 加入一个协调者；`session-send-mcp` 是给子会话用的 stdio MCP 服务器（提供 `session_send`） | `serve/agent-host-join`、MCP SDK |
| `sessions` | 0.7k | list / ps / add / remove / controllers | `list` 扫保存的会话记录；`ps` 看实时注册表和 Agent View 的托管记录；`controllers` 签发 / 吊销可以驱动你会话的控制器令牌（跨会话协议） | core（peer 注册表） |
| `board` | 0.4k | task / claim / done / decline / ask / answer / show / prune | Agent Board：同一台机器上独立启动的 agent 通过文件共享任务。实验性，不负责启动或唤醒 agent | `core/board`（`agents/team/board-*.ts`） |
| `channel` | 约 7k + serve 侧 | start / stop / status / set / reload / pairing / approve / configure-weixin / managed-email / daemon-worker | IM / 代码平台渠道（§6.3） | channel-base、全部 `channel-*`、sdk |
| `batch` | 3.7k | run / check / collect / list / retry / cancel / clean | DashScope Batch API：半价异步批量推理。agent 用 `/batch-api` 准备计划，`qwen batch` 提交、跟踪、落盘结果 | core 的 contentGenerator 配置，直接 HTTP 调 DashScope |
| `review` | **约 9.8 万** | 约 45 个 | `/review` skill 的确定性步骤：抓 PR、截取本地 diff、拼 agent 提示词、去重 findings、组装评审、提交评论、CI 门禁（`run --fail-on request-changes`） | git、`gh`、本地缓存 |
| `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` |

#### 几种值得注意的模式

**① skill + CLI 子命令的分工（`review`、`autofix-pr`）。** 内置 skill（`core/src/skills/bundled/review/SKILL.md`）负责判断，确定性的部分做成 CLI 子命令，让 skill 在 Shell 工具里调用。SKILL.md 里出现最多的是：

```text
qwen review run        ×14     qwen review fetch-pr      ×5
qwen review submit     ×5      qwen review agent-prompt  ×5
qwen review findings   ×4      qwen review presubmit     ×3
```

这种模式的好处是：可以重放、可以单测、模型不用自己写 git / gh 脚本。代价是体量：`commands/review/` 约 9.8 万行，比 `acp-integration/` 还大，是 cli 里最大的一块。好在只有 argv 里出现 `review` 时才 `import()`，不拖慢普通启动。

**② daemon 的三个入口：serve、daemon、attach。**

```mermaid
sequenceDiagram
  participant U as 用户
  participant D as qwen daemon start
  participant S as qwen serve（后台）
  participant F as 发现记录
  participant A as qwen attach
  U->>D: qwen daemon start
  D->>S: spawn(cli.js, ['serve','--port',…,'--hostname',…,'--no-token-qr', …], { detached: true })
  S->>F: 写发现记录（url、token、workspaces）
  U->>A: qwen attach --session <id>
  A->>F: 找到 daemon
  A->>S: DaemonSessionClient.load(client, id) → events() 渲染
```

```ts
// commands/daemon.ts:565 —— 组装后台 serve 的参数
const childArgs = ['serve', '--port', String(port), '--hostname', hostname, '--no-token-qr'];
if (!options.web) childArgs.push('--no-web');
if (options.requireAuth) childArgs.push('--require-auth');
// … spawn(command, args, { detached: true, … })

// commands/attach.ts:164 —— 终端客户端就是一个 SDK 消费方
const client = new DaemonClient({ baseUrl: target.record.url, token: resolved.token ?? '' });
const session = await DaemonSessionClient.load(client, argv.session, { workspaceCwd });
for await (const event of session.events({ signal })) renderEvent(event);
```

`attach` 是 cli 反向依赖 sdk 的原因之一（§4.2），但这里是正当的：它就是一个 daemon 客户端，和 web-shell 同一层。

**③ 已经移走或空壳的命令。** `auth` 只打印"已移除"，`hooks` 只提示用 `/hooks`。它们留着是为了老脚本不至于报"未知命令"。

**④ 多 agent 协作有三套机制，容易混。**

| 机制 | 命令 | 载体 | 能做什么 |
|---|---|---|---|
| Agent Board | `qwen board` | 本机文件 + 锁 | 记录任务、认领、问答；**不**启动或唤醒任何 agent |
| 跨会话协议（peer） | `qwen sessions ps / controllers`、`session_send` MCP | 会话注册表 + UDS（`core/src/ipc`、sdk `/peer`） | 会话之间发消息，用控制器令牌驱动别的会话 |
| Agent Host / 协调者 | `qwen agents join <link>` | 本机 `qwen serve` 加入远端协调者 | 让协调者把会话派到这台机器的 serve 上跑 |

官方文档（`docs/users/features/agent-board.md`）特意说明 Board "not the Qwen Agent Team scheduler or the cross-session messaging transport"，可见确实容易混。

#### 我的看法

1. **cli 承担了太多"不是 CLI 的东西"。** 17 个子命令里，真正的 agent 入口只有默认命令；`serve`（27.6 万行）、`review`（9.8 万行）、`channel` 加 serve 侧的 channel 代码、`batch` 都是独立子系统。它们共用 `qwen` 这个 bin 是为了方便分发，代价是 cli 包的依赖和体积都被放大（例如全部 `channel-*` 包）。懒加载（`review`、`autofix-pr`）是对的方向，可以推广到 `channel`、`batch`、`board`。
2. **`review` / `autofix-pr` 的"skill 做判断、CLI 做确定性步骤"模式值得保留**，而且适合作为扩展机制公开出来：第三方 skill 也可以带自己的确定性子命令，不用都塞进 cli 本体。
3. **对融合的影响：**
   - 全部是 Qwen 产品层的东西，按融合方案的规则放在 Qwen 产品层，通过 `runCli({ declarations })` 命令清单挂到新内核上（IDE 集成建议 §4.1 的扩展点 4）。
   - 直接依赖 core 内部模块的有 `mcp`、`extensions`、`memory`、`sessions`、`board`、`batch`、`sandbox`。新内核里这些 core 模块的位置和接口都会变，是迁移工作量的主要来源。
   - `serve`、`daemon`、`attach`、`agents` 跟着 serve v2 走；`attach` 只依赖 SDK，换 SDK 1.x 即可。
   - `review`、`autofix-pr` 只依赖 git 和 `gh`，与内核无关，可以原样搬。

---

## 8. core 内部与 agent loop 入口

core 的 34 个一级子目录里有 31 个在同一个强连通分量里（`config ↔ tools`、`config ↔ services`、`agents ↔ tools` 都是双向依赖），不能按目录拆开替换。下图只画和"谁调谁"相关的主干。

```mermaid
flowchart LR
  subgraph ENTRIES["7 个 loop 入口"]
    INK["Ink TUI<br/>ui/hooks/use-llm-stream.ts"]
    OTUI["OpenTUI<br/>ui/opentui/live-session.ts"]
    HL["Headless / stream-json / SDK query()<br/>nonInteractiveCli.ts"]
    ACP["ACP（Zed / VS Code / serve / web-shell / channels）<br/>acp-integration/session/Session.ts"]
    HH["Hosted Harness<br/>serve/hosted-harness-model.ts"]
    AC["AgentCore（subagent / 后台 / workflow / team）<br/>core/agents/runtime/agent-core.ts"]
    SPEC["Speculation<br/>core/followup/speculation.ts"]
  end
  subgraph CORELOOP["core/src/core"]
    LOOP["agent-loop.ts<br/>runAgentLoop / runModelRound / runToolBatch<br/>（experimental.unifiedAgentLoop，默认关）"]
    CLIENT["LlmClient (client.ts)"]
    TURN["Turn (turn.ts)"]
    CHAT["LlmChat (llm-chat.ts)<br/>重试 · 回退 · 自动压缩"]
    CTS["CoreToolScheduler"]
  end
  PROV["providers / models"]
  TOOLS["tools · mcp · skills · hooks · permissions"]
  CFG["Config（上帝对象）"]

  INK --> CLIENT
  OTUI --> CLIENT
  HL --> CLIENT
  HH --> CLIENT
  ACP -->|绕过 client| CHAT
  AC -->|绕过 client| CHAT
  SPEC -->|绕过 client| CHAT
  CLIENT --> TURN --> CHAT --> PROV
  INK & OTUI & HL & AC --> CTS
  ACP -.->|自带 runToolCalls / runTool| TOOLS
  HH -.->|HostedWorkspaceToolTurn → broker| TOOLS
  CTS --> TOOLS
  ENTRIES -.->|开关开时| LOOP
  LOOP --> CLIENT
  LOOP --> CTS
  CFG -.-> CLIENT & CTS & TOOLS
```

迁移状态（详见报告 01）：开关打开后，Ink、OpenTUI、Headless、ACP、AgentCore 的模型轮和工具批都跑在 `agent-loop.ts` 上；Hosted Harness 不读开关；Speculation 还没迁（#17029）。#17045 计划把 1.0 preview 的事件总线 loop 内核落到 main，并默认开。

---

## 9. 进程拓扑总览

一个典型的"desktop / web-shell 用户"机器上会有这些进程：

```mermaid
flowchart TB
  subgraph HOST["用户机器"]
    BROWSER["浏览器 / Tauri / WebView<br/>web-shell"]
    subgraph DAEMON["qwen serve 进程（:4170 或随机端口）"]
      EXP["Express app + WS upgrade"]
      BRG["acp-bridge"]
      CWS["channel worker supervisor"]
    end
    subgraph CHILDREN["子进程"]
      ACP1["qwen --acp（工作区 A）<br/>多个会话"]
      ACP2["qwen --acp（工作区 B）"]
      CW["qwen channel daemon-worker ×N"]
      MCPS["MCP servers<br/>browser-use / node-repl / mobile-mcp / 第三方"]
    end
    VSCODE["VS Code<br/>ide-companion：IDE MCP server"]
    DISK[("~/.qwen<br/>settings.json · tmp/&lt;hash&gt;/chats/*.jsonl · live/daemon.json")]
  end
  BROWSER -->|REST/SSE/WS| EXP
  EXP --> BRG
  BRG -->|stdio ACP| ACP1
  BRG -->|stdio ACP| ACP2
  CWS -->|spawn| CW
  CW -->|sdk DaemonClient| EXP
  ACP1 -->|stdio / http MCP| MCPS
  ACP1 -->|IDE MCP client| VSCODE
  ACP1 --- DISK
  VSCODE -. "直接读写 settings / 会话 jsonl" .-> DISK
```

托管部署（managed）：

```mermaid
flowchart LR
  WSM["web-shell（managed 模式）"] -->|"/api/agent/web-shell/v1/*"| MAS["managed-agent-server（Java）"]
  MAS -->|"spawn / k8s：qwen serve --profile hosted-harness --http-bridge --no-web"| HHS["qwen serve（hosted profile）<br/>只开放 hosted 路由 + /health /capabilities"]
  MAS -->|"qwen managed-runtime-bootstrap（私有 stdio worker）"| MRB["managed runtime worker<br/>/internal/managed-runtime/**"]
  HHS --> CORE["core managed-runtime"]
  MRB --> CORE
  MAS -. "33 个契约 fixture" .-> CONTRACTS["core/src/managed-runtime/contracts<br/>cli/src/serve/contracts"]
```

---

## 10. 速查表：X 依赖什么

| 组件 | 代码依赖（import） | 运行时依赖（协议） |
|---|---|---|
| web-shell | sdk（主）、core 幽灵依赖 2 个符号、acp-bridge 1 个常量 | qwen serve REST/SSE/WS；managed 模式下是 managed-agent-server |
| vscode-ide-companion | core（深）、sdk、acp-bridge、web-shell、cli `./export` | `qwen --acp`（直连）或 `qwen serve --no-web`；自己提供 IDE MCP server；直接读写 `~/.qwen` |
| sdk-typescript | core、acp-bridge（构建时 inline）；内嵌 CLI bundle | stream-json（`query()`）、qwen serve（`/daemon`）、peer UDS |
| sdk-java / sdk-python | — | stream-json；Java 另有 qwen serve |
| desktop / mobile-shell | — | spawn / 连接 qwen serve，加载 web-shell |
| chrome-extension | — | qwen serve `/health` `/capabilities` `/acp` `/workspace` |
| 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/*`） |
| channels/* | channel-base | 独立：spawn `qwen --acp`；daemon：由 serve 拉起 worker，经 sdk 回连 serve |
| zed-extension | — | `qwen --acp`（固定 npm 0.10.0） |
| managed-agent-server | 契约 fixture | spawn `qwen serve --profile hosted-harness`；`qwen managed-runtime-bootstrap` |
| cli | core、acp-bridge、sdk、channel-*、web-templates、audio-capture | 作为 serve 时 spawn 自己的 `--acp` 子进程；作为 IDE MCP client 连 VS Code |
| acp-bridge | core、`@agentclientprotocol/sdk` | stdio ACP client |
| core | （dev）browser-use | MCP client、provider HTTP、IDE MCP client、peer UDS |

---

## 11. 架构上的几个"坑"

1. **依赖方向不干净**：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。
2. **web-shell 有未声明的 core 依赖**，只靠 workspace hoist 解析。
3. **VS Code 插件是耦合最深的上层**：直接用 core 的 provider 安装、`Storage`、文件搜索，直接读会话 jsonl，比 web-shell 深一个量级。
4. **core 没有 API 边界**：`exports` 的 `"./*"` 让每个内部文件都是公开入口，cli 深 import 了 348 个内部模块。
5. **serve 默认是"代理 + 子进程"模型**：REST 是对外契约，ACP（含 117 个私有 ext 方法）是 serve 和子进程之间的内部契约；`/acp` 对外端点存在但默认没人用。
6. **两套 serve 实现**：默认 profile（acp-bridge + `--acp` 子进程）和 hosted-harness profile（自带 loop、日志式工具执行）。
7. **agent loop 有 7 个入口**，统一循环（`unifiedAgentLoop`）还在迁移，默认关。

---

## 参考

- 报告：`~/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 入口）
- §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`
- 本次复核过的源码位置：`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` 依赖
