qwen-code 全局架构图(main @ 53940f2afc)

By 陈成 · 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. 一句话版本


1. 全局分层图(运行时视角)

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

要点:


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。

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

声明里看不出来的事实:


4. 实际代码 import 耦合

4.1 包间 import 站点数(生产代码)

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

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 的完整链路(默认模式)

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

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,另外两处是跨进程:

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

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):

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):

// 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):

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):

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):

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

channel 来自 spawnChannel.ts:549,就是拉起子进程:

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):

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):

// 模型轮:直接用 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

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

关键代码:

// 子进程 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 请求,要等浏览器里有人投票才返回:

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 }
// 子进程 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)

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 中转)
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):

{
  "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 } }
    }
  }
}

分层:

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

两种运行方式:

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 里投票。

一条消息的完整路径:

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: 出站消息

关键代码:

// 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 声明:

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

ChannelAgentBridge 的两个实现:

// 独立模式: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):

// 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 启动参数

// 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 默认回退值
// 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 的传输)

// 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):

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';
// 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"

现在长成了什么样

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 类型:

// 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 那份一致:

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 里,大方向是对的。

问题出在包的切分,不在放的位置。 四件事放进了同一个发布单元:协议定义、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 走,不该和客户端绑在同一个版本号上。

建议的切分

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 派出去的编码会话。

全景

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

要点:

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

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 的"能力"就是这一组工具:

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):

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):

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>;
}

两个实现:

// 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):

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

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:

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() 启动(见上图)。

按"跟谁打交道"分组

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 里出现最多的是:

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。

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() 渲染
// 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 都是双向依赖),不能按目录拆开替换。下图只画和"谁调谁"相关的主干。

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 用户"机器上会有这些进程:

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):

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)还在迁移,默认关。

参考

Read this report as Markdown · Cite it (BibTeX)