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. 一句话版本
- 核心只有三块:
core(agent 运行时)、cli(TUI、headless、ACP agent、qwen serve守护进程、子命令都在这里)、acp-bridge(serve 用来拉起和管理qwen --acp子进程的 ACP client)。 - 所有上层应用都通过四个协议面接入,基本不直接调代码:
qwen serve:REST/SSE(主要),外加/acpHTTP/WSqwen --acp:stdio ACPqwen -p --input-format stream-json:SDK 控制协议- 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. 全局分层图(运行时视角)
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。
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 语句。
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 无关。
我的看法
- 命名冲突的代价是真实的。 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。
- B 改名为
- A 是一个独立的产品子系统,体量和 web-shell 相当。 channel-base 加适配器约 6.5 万行,再加上 cli 里的命令和 serve 托管代码。它通过
ChannelAgentBridge接口和 agent 解耦,有两个实现,这个抽象做得好。问题在依赖方向:cli 依赖全部 10 个channel-*包(§4.2),等于把所有平台 SDK 都塞进了 CLI 安装包。更合理的是内置适配器也按扩展的方式按需安装,cli 只依赖channel-base。 - 两种运行方式长期并存,有重复。 独立模式(
AcpBridge)和 daemon 模式(DaemonChannelBridge)各自实现了会话管理、权限、附件和私有_meta。daemon 模式能被 web-shell 看到、审批和恢复,能力更全。建议把 daemon 模式作为默认,独立模式只保留给"不想常驻 serve"的场景,新功能先只做 daemon 模式。 - 对融合的影响: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 的。提交说明给了三条理由:
- 验证"协议同构":SDK 客户端可以不走
query()的 stdio + stream-json,直接通过 HTTP 驱动 daemon,端到端跑通。 - 和
query()并列,不替代它:DaemonClientis a sibling of ProcessTransport, not a replacement.query()用户不受影响;需要 daemon 模式能力的应用(多客户端 attach、共享 MCP 池、网络可达、先到先得的权限投票)自己选择new DaemonClient(...)。 - 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 里,大方向是对的。
- 同一个协议只有一个官方客户端。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 运行时。后果是:
- 协议没有自己的家。 服务端引用客户端的类型,客户端 inline 服务端的常量,两份类型靠断言同步。协议应该是双方都依赖的第三个包,而不是放在任何一方里。
- 体积和依赖错配。 daemon 使用方被迫带上 CLI bundle。
- 语义化版本被绑在一起。
query()用户(例如 QwenMate,见 IDE 集成建议 §1.5)和 daemon 用户共用一个版本号。daemon 协议迁到 serve v2 时,SDK 升到 1.x 会连带波及只用query()的人,这正是 IDE 文档 §4.5 担心的事。 - 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
- 抽出
@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 里做一致性检查。 - CLI bundle 移出 SDK 主包。 变成 optionalDependency(例如
@qwen-code/sdk-cli-runtime),或者让query()优先找本机的qwen,找不到才提示安装。daemon 使用方从 81 MB 降到几 MB。 - 导入路径不变,各子路径语义化版本独立。
@qwen-code/sdk/daemon这个导入路径保持兼容,底下可以是独立发布的包再转出。daemon 协议升到 v2 时,只有 daemon 客户端升大版本,query()用户不受影响。 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
要点:
- 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 当作一等后端的仓内组件。
一次"说一句话 → 改代码 → 播报结果"
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 |
我的看法
- 定位清楚,设计有意思。 用实时语音模型做"前台调度"、编码 agent 做"后台执行",两边用
handoff+ 回执 + 静默上下文注入解耦。语音模型不用等任务完成,用户可以继续说话、开并行任务。BackendAdaptor让后端可以换成任何 ACP agent,这层抽象做得好。 - 两个实现并存是最大的问题。
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的依赖。 - 它其实不属于 qwen-code 的"内核",而是一个独立产品。 qwen-live 只通过协议(ACP 或 serve REST)用 qwen-code,自己有配置目录(
~/.qwen-live/)、自己的会话格式、自己的记忆库,还能驱动别家 agent。放在这个 monorepo 里主要是为了共用 sdk 和 Host 发布流程。 - 对融合的影响:
- 独立版已经把
qodercli --acp当作一等后端,所以融合后的qwen-next --acp只要保持 ACP 兼容就能直接用,不需要额外适配。 QwenCodeAdaptor依赖 sdk 的DaemonClient,属于 IDE 集成建议 §4.5 说的 SDK 消费方,serve v2 时要一起迁,或者干脆按 README 的 Legacy 标注删掉,只保留 ACP 路径。- 内置版依赖 serve 和 cli 的
ui/voice,是迁移成本最高的部分。按上面第 2 条先删掉,迁移面会小很多。
- 独立版已经把
- 平台限制: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",可见确实容易混。
我的看法
- cli 承担了太多"不是 CLI 的东西"。 17 个子命令里,真正的 agent 入口只有默认命令;
serve(27.6 万行)、review(9.8 万行)、channel加 serve 侧的 channel 代码、batch都是独立子系统。它们共用qwen这个 bin 是为了方便分发,代价是 cli 包的依赖和体积都被放大(例如全部channel-*包)。懒加载(review、autofix-pr)是对的方向,可以推广到channel、batch、board。 review/autofix-pr的"skill 做判断、CLI 做确定性步骤"模式值得保留,而且适合作为扩展机制公开出来:第三方 skill 也可以带自己的确定性子命令,不用都塞进 cli 本体。- 对融合的影响:
- 全部是 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,与内核无关,可以原样搬。
- 全部是 Qwen 产品层的东西,按融合方案的规则放在 Qwen 产品层,通过
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/<hash>/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. 架构上的几个"坑"
- 依赖方向不干净: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。 - web-shell 有未声明的 core 依赖,只靠 workspace hoist 解析。
- VS Code 插件是耦合最深的上层:直接用 core 的 provider 安装、
Storage、文件搜索,直接读会话 jsonl,比 web-shell 深一个量级。 - core 没有 API 边界:
exports的"./*"让每个内部文件都是公开入口,cli 深 import 了 348 个内部模块。 - serve 默认是"代理 + 子进程"模型:REST 是对外契约,ACP(含 117 个私有 ext 方法)是 serve 和子进程之间的内部契约;
/acp对外端点存在但默认没人用。 - 两套 serve 实现:默认 profile(acp-bridge +
--acp子进程)和 hosted-harness profile(自带 loop、日志式工具执行)。 - 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依赖