企业官网建设流程全解析

qwen-code 子代理执行模式投影（Agent Execution Mode Projection）解析：让 Web Shell 与运行时对前后台判定保持一致

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code

导读

在 qwen-code 的运行时（Runtime）中，一个agent/task子代理调用究竟以前台（foreground）还是后台（background）方式执行，是由"工具参数 + 已加载的子代理配置"共同决定的，而 Web 客户端此前只能看到工具参数，无法复现完整判定规则，导致同一调用在客户端与运行时可能出现前后台分类不一致。本文基于仓库设计文档 docs/design/2026-08-25-agent-execution-mode-projection.md，深入讲解该问题的根因、executionMode投影方案的设计思路、运行时端的判定"真相源"实现、Web Shell 端的规范化与权威采纳逻辑，以及针对旧会话与旧守护进程的兼容回退路径，帮助你完整理解 qwen-code 中子代理前后台显示一致性的端到端链路。

问题背景：客户端与运行时的判定分歧

前后台判定的真实规则并不只依赖参数

在 qwen-code 的运行时中，一次子代理调用是否进入后台执行，由以下因素共同决定：

• 工具参数中的run_in_background；
• 已加载的子代理配置（subagentConfig）中的background标志；
• 是否为 fork（fork）调用；
• 会话是否为顶层会话（top-level session）；
• 是否携带working_dir、name等参数。

也就是说，客户端如果只拿到调用参数，就无法准确复现运行时基于"已加载子代理配置"得出的最终结论。例如某个子代理配置自带background: true，但客户端看不到这份配置，仅凭参数推断就会得出与运行时相反的结论。这正是指定文档所描述的核心痛点：

"The runtime decides whether an agent runs in the foreground or background using both tool arguments and loaded subagent configuration. Web clients only receive the arguments, so they can classify the same call differently from the runtime."

为什么需要"投影"而不是让客户端自行复刻规则

让每个客户端各自复刻一遍运行时的判定逻辑，存在明显缺陷：

• 判定规则依赖SubagentConfig（从磁盘加载的子代理配置），客户端拿不到完整配置；
• 规则本身会随版本演进（如嵌套限制、worktree 守卫、fork 语义变化），客户端难以同步；
• 多个客户端（Web Shell、Electron 桌面客户端等）各自维护一份逻辑，极易漂移。

因此设计文档给出的思路是：运行时在流式输出工具原始输出（tool raw output）时，把已解析的最终执行模式直接投影到现有的 task-execution 显示帧上，客户端只需读取并采纳这个权威值。

设计核心：把已解析的执行模式投影到 task-execution 帧

投影时机与不变性保证

设计文档明确了两个关键约束：

1. 首次 running 更新即可用：执行模式在第一条 running 状态的更新帧中就已经携带，客户端无需等待生命周期状态推进；
2. 值在生命周期推进期间保持不变：executionMode在任务从 running 推进到 completed / failed / cancelled 等状态的过程中不会改变，因此客户端可以在收到首帧后直接采纳并缓存，不必担心后续帧覆盖。

兼容性回退：旧会话与旧守护进程

投影字段是新增的，因此：

• 历史录制会话（recorded sessions）中不包含该字段；
• 旧版本守护进程（older daemons）也不会输出该字段。

对于这类帧，客户端必须保留原有的"参数 + 状态推断"逻辑作为兼容回退，即继续使用run_in_background、working_dir、name等参数以及rawOutput.status === 'background'来推断。这一回退逻辑在 Web Shell 中被称为"冻结的兼容路径"（frozen compatibility path），详见下文。

非目标（Non-goals）：明确的边界

设计文档用 Non-goals 划定了本次改动的边界，理解这些边界有助于避免误用：

• 不改变后台调度或生命周期状态的语义：投影只是把既有结论"广播"给客户端，不改变运行时后台任务注册表（BackgroundTaskRegistry）的调度行为，也不改变 running / background / completed 等状态的含义；
• 不新增第二个顶层 ACP 字段：executionMode复用了既有的 task-execution 显示帧（该帧本就作为 tool raw output 流式输出），不额外增加顶层 ACP 协议字段，保持协议面最小化；
• 不更新独立的 Electron 客户端：仓库内另一个消费不同结果格式的 Electron 客户端不在本次改动范围内（事实上该客户端已被 fork 出本仓库独立维护，见下文源码注释）。

运行时实现：判定真相源在 agent.ts

backgroundRequested 与 shouldRunInBackground 的完整判定链

运行时侧的真相源位于 packages/core/src/tools/agent/agent.ts 的AgentTool中。从源码结构看，判定链可以概括为（对应 agent.ts#L2700-L2711）：

const backgroundRequested = isFork && !this.config.isInteractive() ? true : (this.params.run_in_background ?? subagentConfig.background ?? (!isForkRequested && this.params.working_dir === undefined && this.params.name === undefined)); const shouldRunInBackground = backgroundRequested && isTopLevelSession();

逐项拆解：

两个重要细节值得注意：

1. 隐式后台请求降级：嵌套调用中，隐式后台请求会降级为等待的前台运行（Background request downgraded to a foreground run调试日志），而不是把子代理结果"孤儿化"；显式run_in_background: true的嵌套请求则被运行时 spawn 守卫直接拒绝（buildSpawnBlockedResult）。
2. worktree 守卫：当working_dir与后台执行冲突时（shouldRunInBackground为 true 且携带working_dir），运行时会在任何显示更新之前返回 blocked 结果——一个从未启动的调用绝不能发出带权威executionMode: 'background'的 running 帧，否则会与不带executionMode的 blocked 结果帧自相矛盾（agent.ts#L2713-L2733）。

投影帧的组装

判定完成后，运行时组装 task-execution 显示帧（agent.ts#L2735-L2746）：

this.currentDisplay = { type: 'task_execution' as const, subagentName: subagentConfig.name, taskDescription: this.params.description, taskPrompt: this.params.prompt, executionMode: shouldRunInBackground ? 'background' : 'foreground', subagentSessionReady: false, status: 'running' as const, subagentColor: subagentConfig.color, }; if (shouldRunInBackground) this.setupEventListeners(updateOutput); updateOutput?.(this.currentDisplay);

executionMode与status: 'running'同帧出现，正好满足设计文档"首次 running 更新即可用"的约束；帧通过updateOutput回调以 tool raw output 的形式流式下发。

桌面客户端的分叉与同步提示

源码注释明确提到：消费不同结果格式的桌面客户端已从本仓库 fork 出去（基于 OpenWork，不再在本仓库内 vendored），它收不到这次投影，因此在自己的副本里复刻了这条规则。仓库内的注释明确要求"如果这条规则变化，务必同步告知该 fork"（agent.ts#L2694-L2699）。这印证了设计文档 Non-goals 中"不更新 Electron 客户端"的取舍——协议演进只面向仍在仓库内的 Web Shell。

Web Shell 适配：规范化与权威采纳

传输层字段与类型定义

Web Shell 通过守护进程（daemon）的转录消息接收工具调用数据。投影字段在传输模型中被定义为可选字段（packages/web-shell/client/adapters/messageTypes.ts#L50-L54）：

export interface DaemonMessageToolCall { callId: string; toolName: string; args?: Record<string, unknown>; executionMode?: 'foreground' | 'background'; subagentSessionReady?: boolean; status: DaemonMessageToolCallStatus; // ... }

executionMode的可选性正是为兼容旧守护进程与历史录制会话而保留的。

转录块到工具调用模型的规范化

守护进程转录块（transcript block）在 packages/web-shell/client/adapters/transcriptToMessages.ts 中被转换为 Web Shell 的工具调用模型。关键转换逻辑（transcriptToMessages.ts#L1264-L1303）：

const executionMode = safeToolProjection ? block.background === true ? 'background' : 'foreground' : getRecord(rawOutput)?.['executionMode']; // ... executionMode: isTaskExecutionMode(executionMode) ? executionMode : undefined,

• 在安全投影（safeToolProjection）路径下，直接以转录块的background布尔值换算；
• 在常规路径下，从工具原始输出（rawOutput）中读取executionMode，并通过isTaskExecutionMode校验取值合法后才写入模型，非法/缺失值统一归一为undefined，从而走兼容回退。

此外，工具调用合并逻辑在 transcriptToMessages.ts#L1208 中遵循"已存在的值优先"策略：

target.executionMode = source.executionMode ?? target.executionMode;

这与设计文档"值在生命周期推进期间保持不变"的约束相互印证——后续帧即使不携带该字段，也不会清空首帧已确立的权威值。

权威采纳与冻结的兼容回退

Web Shell 对前后台分类的入口是 packages/web-shell/client/adapters/toolClassification.ts 中的isBackgroundSubAgentToolCall（toolClassification.ts#L61-L91）：

export function isBackgroundSubAgentToolCall(tool: ACPToolCall): boolean { if (!isSubAgentToolCall(tool)) return false; if (tool.executionMode) return tool.executionMode === 'background'; // Older daemon frames and recorded sessions do not include executionMode. const rawOutput = getRecord(tool.rawOutput); const name = tool.toolName.toLowerCase(); const args = tool.args; const isTopLevelQwenAgent = name === 'agent' && tool.parentToolCallId === undefined; const defaultsToBackground = isTopLevelQwenAgent && args !== undefined && args?.run_in_background === undefined && args?.working_dir === undefined && args?.name === undefined && (typeof args?.subagent_type !== 'string' || args.subagent_type.toLowerCase() !== 'fork'); const explicitlyBackground = args?.run_in_background === true && (name !== 'agent' || isTopLevelQwenAgent); return ( rawOutput?.['status'] === 'background' || explicitlyBackground || defaultsToBackground ); }

这段代码精确实现了设计文档的三层语义：

1. 权威采纳：只要tool.executionMode存在，就直接返回executionMode === 'background'，不再参考任何参数或原始输出——运行时结论优先；
2. 旧帧兼容回退：executionMode缺失时（旧守护进程帧、投影特性之前的录制会话、以及当前核心的 blocked-spawn 结果帧），退回到"参数 + 状态"推断；
3. 冻结不变式：源码注释特别强调，这条回退启发式是冻结的兼容路径，核心侧判定规则变化时不得同步更新它（toolClassification.ts#L52-L60）——活规则在agent.ts的backgroundRequested/shouldRunInBackground，桌面端镜像副本已被 fork 出仓库，而这里已经存在一处有意为之的差异：subagentConfig.background在回退路径中天然不可见，正因如此才需要executionMode投影来补足。

回退路径中还有两个值得注意的细节：

• rawOutput.status === 'background'优先于参数推断，即便参数写的是run_in_background: false，只要运行状态帧表明进入了后台，就按后台处理；
• fork参数单独排除出"缺省进后台"启发式：仅凭参数无法区分交互式分离 fork 与 headless 注册表支持的 fork，因此这类帧信任rawOutput.status反映的真实运行模式。

测试证据：权威值压过参数

packages/web-shell/client/adapters/toolClassification.test.ts 用一组针对性用例印证了"权威采纳"语义（toolClassification.test.ts#L90-L115）：

it('trusts the runtime background status when present', () => { expect( isBackgroundSubAgentToolCall({ ...agentTool({ run_in_background: false }), rawOutput: { type: 'task_execution', status: 'background' }, }), ).toBe(true); }); it('trusts the runtime background execution mode over foreground args', () => { expect( isBackgroundSubAgentToolCall({ ...agentTool({ run_in_background: false }), executionMode: 'background', }), ).toBe(true); }); it('trusts the runtime foreground execution mode over background args', () => { expect( isBackgroundSubAgentToolCall({ ...agentTool({ run_in_background: true }), executionMode: 'foreground', }), ).toBe(false); });

也就是说：

• 参数写run_in_background: false，但投影值executionMode: 'background'→ 判定为后台（配置中的background: true等客户端不可见因素生效）；
• 参数写run_in_background: true，但投影值executionMode: 'foreground'→ 判定为前台（嵌套降级、worktree 冲突等运行时规则生效）。

同文件中还有working_dir默认前台、命名队友不改变分类、嵌套调用无论标志如何都保持前台等用例（toolClassification.test.ts#L60-L88），共同覆盖了兼容回退路径的既有行为。

端到端链路与兼容矩阵

综合运行时与 Web Shell 两端，一次子代理调用的执行模式投影链路如下：

1. 模型发起agent/task工具调用（携带run_in_background、fork、subagent_type、working_dir、name、description、prompt等参数）；
2. 运行时加载子代理配置SubagentConfig（含background、executor、color等字段），计算backgroundRequested与shouldRunInBackground，必要时触发嵌套降级、worktree 守卫或 spawn 守卫；
3. 运行时组装task_execution显示帧，携带executionMode: 'foreground' | 'background'与status: 'running'，通过updateOutput流式下发为 tool raw output；
4. Web Shell 守护进程转录块经 transcriptToMessages.ts 规范化到DaemonMessageToolCall.executionMode，再进入工具调用模型；
5. isBackgroundSubAgentToolCall优先采纳executionMode，缺失时才走冻结的旧推断路径，最终驱动 UI 渲染。

各场景下的取值与路径可以归纳为下表：

结语

executionMode投影是 qwen-code 在"运行时决策、客户端呈现"边界上的一次精准收敛：它不改变任何调度与生命周期语义，不新增顶层 ACP 字段，而是复用既有的 task-execution 显示帧，把依赖已加载子代理配置的复杂判定结果以最小代价广播给 Web Shell，同时为旧会话与旧守护进程保留冻结的兼容回退。对于想要深入理解 qwen-code 子代理前后台机制或在此基础上构建客户端适配层的开发者，建议沿着三条线索继续阅读：运行时判定真相源 packages/core/src/tools/agent/agent.ts（backgroundRequested/shouldRunInBackground与 spawn 守卫）、Web Shell 规范化入口 packages/web-shell/client/adapters/transcriptToMessages.ts（daemonToolBlockToToolCall与mergeToolCallInto）、以及分类权威入口 packages/web-shell/client/adapters/toolClassification.ts（isBackgroundSubAgentToolCall及其冻结回退），再结合 toolClassification.test.ts 的用例理解边界行为。

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code