从源码看 Qwen Code 的设计思路

02

—

整体架构设计

2.1 架构分层

2.2 模块职责说明

2.3 客户端集成方式对比

03

—

核心流程详解

3.1 交互流程

从用户输入到最终响应的完整交互流程：

3.2 Agent Loop 执行流程

Agent Loop 是 Qwen Code 的核心对话循环机制，负责协调用户输入、模型响应、工具执行之间的交互，直到任务完成。

3.2.1 Agent Loop 入口触发条件

Agent Loop 在以下情况下被触发：

• 用户发送消息时：当用户通过 CLI 输入问题或命令时，调用 GeminiClient.sendMessageStream() 方法进入 Loop

• 工具执行结果需要继续对话时：当工具执行完成后，将工具结果作为新的用户消息重新进入 Loop

• 模型主动要求继续时：通过 checkNextSpeaker 检测到模型需要继续发言时，递归调用 sendMessageStream

3.2.2 详细执行流程

3.2.3 详细步骤说明

步骤 1: 入口检查 (sendMessageStream)

• 检查会话 Turn 数是否超过 maxSessionTurns 限制

• 检查 Token 数是否超过 sessionTokenLimit 限制

• 确保不超过硬编码的最大轮数 MAX_TURNS（默认 100）

• 创建 Turn 实例，传入 chat 会话和 prompt_id

步骤 2: Turn 执行 (Turn.run)

• 构建请求消息，包含：

• 用户输入内容

• 对话历史记录

• 可用工具定义（function declarations）

• 系统提示（system prompt）

• 调用模型 API（Gemini/Qwen/Anthropic）

• 接收流式响应，逐块解析

步骤 3: 响应处理

• 文本内容：通过 yield 发送 Content 事件，实时展示给用户

• 工具调用：收集 

• name: 工具名称

• args: 工具参数

• id: 调用 ID（用于匹配响应）

• 完成信号：记录 finishReason（STOP、MAX_TOKENS、SAFETY 等）

步骤 4: 工具调用执行

• 工具查找：通过 ToolRegistry.getTool() 根据工具名称查找对应的工具实例

• 构建调用：调用 tool.build() 创建 ToolInvocation 对象，封装参数和执行逻辑

• 权限检查：根据当前执行模式（ApprovalMode）决定如何处理：

• Plan 模式：

• 如果是 exit_plan_mode 工具：显示计划确认对话框，用户可选择继续执行或取消

• 其他工具：阻止执行，返回错误提示（Plan 模式下不允许执行普通工具）

• Default 模式：

• 需要确认的工具：显示确认对话框等待用户批准

• 不需要确认的工具：直接执行

• Auto-edit 模式：

• 编辑类工具（如 write_file、edit）：自动执行无需确认

• 其他工具：需要确认

• YOLO 模式：所有工具自动执行，无需确认

• 执行工具：调用 invocation.execute() 执行实际逻辑

• 返回结果：封装为 ToolResult 返回，包含执行结果或错误信息

步骤 5: 循环控制

• 如果有工具执行结果，将结果构建为 nextMessage，继续下一轮 Loop

• 如果没有工具调用，检查 

• 如果是 STOP，Loop 正常结束

• 如果模型需要继续（通过 checkNextSpeaker 判断），发送 “Please continue” 继续 Loop

• 检查是否达到最大轮数，防止无限循环

3.2.4 两种 Loop 调用方式对比

Qwen Code 中有两种 Agent Loop 的调用方式，核心 Loop 逻辑都在 packages/core/src/core/client.ts 中实现，非交互式模式通过 packages/cli/src/nonInteractiveCli.ts 再进行了一次包装适配。

为什么需要非交互式包装？非交互式包装的核心目的是将直接 API 调用转换为进程间通信协议：

• 协议适配：将内部 AsyncGenerator 事件转换为 JSON 格式输出，让 IDE/SDK 能解析

• 控制平面：IDE 集成需要双向通信（权限请求、模式切换、中断控制等）

关系对比：

交互式 CLI ──→ 直接调用 sendMessageStream() ──→ Core Agent Loop (递归)                    ↑非交互式 CLI ──→ while 循环包装 ──→ 协议转换/控制平面

Core 层 Loop 伪代码：

# client.tsasync function* sendMessageStream(request, turns = MAX_TURNS):    // 1. 检查限制    ifexceedMaxTurns() orexceedTokenLimit():        yield { type: 'MaxSessionTurns' } / { type: 'SessionTokenLimitExceeded' }        return turn    // 2. 执行 Turn    turn = new Turn(chat, prompt_id)    for event in turn.run(model, request):        yield event  // Content, ToolCallRequest, Error 等    // 3. 检查是否需要继续（模型主动要求继续）    if no pending tools and not aborted:        nextSpeaker = checkNextSpeaker()        if nextSpeaker == 'model':            // 递归调用，turns - 1            yield* sendMessageStream([{ text: 'Please continue.' }], turns - 1)    return turn

非交互式 Loop 伪代码：

# nonInteractiveCli.tsasync function runNonInteractive(userInput):    currentMessages = [{ role: 'user', parts: userInput }]    while true:        turnCount++        if turnCount > maxSessionTurns:            handleMaxTurnsExceededError()        // 调用核心层的递归 Loop        responseStream = geminiClient.sendMessageStream(...)        toolCallRequests = [ ]        // 处理流式响应，转换为 JSON Lines        forawait (event of responseStream):            adapter.processEvent(event)  // 转换为 JSON 输出            if event.type == 'ToolCallRequest':                toolCallRequests.push(event.value)        // 执行工具调用        if toolCallRequests.length > 0:            toolResponseParts = [ ]            for request in toolCallRequests:                // 可能需要通过 Control Plane 请求权限                response = await executeToolCall(config, request, abortSignal)                toolResponseParts.push(...response.responseParts)            // 工具结果作为下一轮输入            currentMessages = [{ role: 'user', parts: toolResponseParts }]            // ← 继续 while 循环        else:            // 没有工具调用，Loop 结束            adapter.emitResult({ isError: false, numTurns: turnCount })            return

3.2.5 Loop 退出条件详解

04

—

核心模块详解

4.1 CLI 模块 (packages/cli)

CLI 模块是用户的主要交互入口，负责命令解析、界面渲染、会话管理和配置设置。

4.1.1 控制平面 (Control Plane)

控制器列表：

• SystemController: 处理初始化、中断、模型设置、命令查询

• PermissionController: 处理工具权限请求和权限模式设置

• SdkMcpController: 处理 MCP 服务器状态管理

4.1.2 ACP 通信系统

ACP (Agent Client Protocol) 实现 IDE 与 Qwen Code CLI 之间的双向通信，基于 JSON-RPC 2.0 协议。

核心文件：

• packages/cli/src/acp-integration/

• packages/vscode-ide-companion/

ACP 消息通信流程：

4.2 Core 模块 (packages/core)

Core 模块是业务逻辑核心，提供 API 客户端、提示构建、工具注册与执行、状态管理等功能。

4.2.1 Agent Loop 与 Tools/Subagent 衔接

Subagent 的实现是一种特殊的 tools。

4.2.2 工具系统

工具系统是 Qwen Code 的核心能力之一，采用注册表模式实现工具的动态发现、注册和执行。系统主要由三个核心组件构成：ToolRegistry（工具注册表）、CoreToolScheduler（工具调度器）和各类 Tool（工具实现）。核心文件位置：

• 工具注册表

  packages/core/src/tools/tool-registry.ts

• 工具调度器

  packages/core/src/core/coreToolScheduler.ts

• 工具实现

  packages/core/src/tools/

4.2.2.1 工具系统图

4.2.2.2 工具定义与分类

Qwen Code 中的工具分为三大类：

内置工具列表：

4.2.2.3 工具注册流程

工具注册代码逻辑：

// Config.createToolRegistry 方法async createToolRegistry(sendSdkMcpMessage) {  const registry = new ToolRegistry(this, eventEmitter, sendSdkMcpMessage);  // 1. 注册内置工具  registry.registerTool(new ReadFileTool(this));  registry.registerTool(new WriteFileTool(this));  registry.registerTool(new ShellTool(this));  // ... 其他内置工具  // 2. 发现外部工具  await registry.discoverAllTools();  return registry;}

4.2.2.4 工具调用&执行流程

核心步骤：

• 模型请求工具调用 – 返回 functionCalls 数组，包含工具名称、参数、调用 ID

• 工具查找与构建 – 从 ToolRegistry 获取工具，调用 tool.build() 创建 ToolInvocation

• 权限检查与执行 – CoreToolScheduler 根据执行模式决定是否需要确认（详见 4.2.3 节）

• 结果返回 – 构建 functionResponse，作为下一轮消息发送给模型

4.2.3 执行模式系统

Qwen Code 提供四种执行模式控制工具调用的权限：

核心代码位置：

权限检查流程：

关键衔接点：

• 工具定义层 – 每个工具实现 shouldConfirmExecute() 方法，返回是否需要确认

• 调度器层 – CoreToolScheduler._schedule() 调用 shouldConfirmExecute() 并根据 ApprovalMode 决定行为

• 配置层 – Config.getApprovalMode() 提供当前模式，Config.setApprovalMode() 切换模式

• UI 层 – 用户通过命令或快捷键切换模式，触发 setApprovalMode()

Plan 模式特殊机制：当处于 Plan 模式时，Agent 可以使用 exit_plan_mode 工具来提交计划并退出规划模式。

4.2.4 子智能体系统

子智能体系统是 Qwen Code 实现任务分解和专业化处理的核心机制。通过子智能体，可以将复杂任务拆分为多个子任务，由专门的智能体并行或串行处理，最后汇总结果。

核心代码位置：

关键衔接点：

• 工具层衔接 – TaskTool 作为普通工具注册到 ToolRegistry

• 管理器层衔接 – Config.getSubagentManager() 提供子智能体管理器实例

• 执行层衔接 – SubAgentScope.create() 创建隔离环境，启动嵌套 Agent Loop

• 配置层衔接 – 子智能体配置文件（.qwen/agents/*.md）通过 SubagentManager 加载

子智能体调用流程：

常见场景：

• 代码审查：专门的审查智能体，只读模式，检查代码质量

• 安全审计：扫描安全漏洞，生成安全报告

• 多智能体并行：前端、后端、测试智能体并行处理复杂任务

4.2.4.1 子智能体系统架构

关键特性：

• 隔离的配置和工具集

• 独立的系统提示词

• 可配置的执行限制

• 结果以自然语言返回

4.2.5 MCP 系统集成

MCP (Model Context Protocol) 是一个开放协议，用于标准化 AI 模型与外部工具、数据源之间的集成。

4.3 SDK 模块

4.3.1 TypeScript SDK 架构

SDK 采用进程间通信（IPC）方式与 Qwen Code CLI 交互：

4.3.2 SDK 与 ACP 协议对比

4.3.3 Java SDK 双模式支持

Java SDK 提供两套独立的 API：

4.4 VSCode IDE Companion

VSCode 插件提供 IDE 内嵌聊天界面、文件和编辑器集成、ACP 协议通信等功能。

05

—

模块间数据流向

5.1 完整数据流向

5.2 关键对接点

06

—

核心服务系统

6.1 会话记录服务 (ChatRecordingService)

会话记录服务负责将对话历史持久化到磁盘，支持会话恢复和审计。核心文件:

packages/core/src/services/chatRecordingService.ts

6.1.1 存储格式

采用 JSONL (JSON Lines) 格式，每行一条记录：

interface ChatRecord {  uuid: string; // 记录唯一标识  parentUuid: string | null; // 父记录 UUID（树形结构）  sessionId: string; // 会话 ID  timestamp: string; // ISO 8601 时间戳  type: 'user' | 'assistant' | 'tool_result' | 'system';  subtype?:    | 'chat_compression'    | 'slash_command'    | 'ui_telemetry'    | 'at_command';  cwd: string; // 工作目录  version: string; // CLI 版本  gitBranch?: string; // Git 分支  message?: Content; // API 格式的消息内容  usageMetadata?: GenerateContentResponseUsageMetadata;  model?: string;  toolCallResult?: Partial<ToolCallResponseInfo>;  systemPayload?: Record<string, unknown>;}

存储位置：

6.1.2 核心方法

6.2 循环检测服务 (LoopDetectionService)

循环检测服务防止 AI 陷入无限循环，通过多种策略检测重复模式。核心文件:

packages/core/src/services/loopDetectionService.ts

6.2.1 检测策略

6.2.2 工具调用循环检测

6.2.3 内容循环检测

采用滑动窗口算法：

1. 将流式文本分割为固定大小的块（50 字符）

2. 对每个块计算 SHA256 哈希

3. 跟踪相同哈希出现的位置

4. 当相同块在短距离内重复 10 次时触发

特殊处理：

• 代码块内容不检测（避免误报）

• 表格、列表、标题等结构化内容重置检测

6.2.4 LLM 辅助循环检测

当对话超过 30 轮后，定期调用 LLM 分析最近 20 轮对话：

// 系统提示词（简化）const LOOP_DETECTION_SYSTEM_PROMPT = `你是一个专业的 AI 诊断智能体，负责识别对话是否陷入无进展状态。无进展状态的特征：1. 重复操作：重复相同的工具调用或响应2. 认知循环：无法确定下一步，反复询问相同问题3. 无净变化：在文件间循环但没有实质进展请区分真正的循环和合理的增量进展。`;// 返回格式{  reasoning: string; // 推理过程  confidence: number; // 0.0-1.0 的置信度}

动态调整检查间隔：

• 高置信度（> 0.9）：触发循环检测

• 中等置信度：缩短检查间隔（5 轮）

• 低置信度：延长检查间隔（15 轮）

6.3 对话压缩服务 (ChatCompressionService)

对话压缩服务在对话历史过长时自动压缩，减少 Token 消耗。核心文件:

packages/core/src/services/chatCompressionService.ts

6.3.1 压缩触发条件

6.3.2 压缩流程

6.4 会话管理服务 (SessionService)

会话管理服务提供会话的列表、加载、保存、删除等操作。核心文件:

packages/core/src/services/sessionService.ts

6.4.1 核心功能

6.4.2 会话恢复流程

07

—

总结

Qwen Code 采用清晰的两层架构设计：

1. 客户端层 – 提供多种接入方式（CLI 交互式、VSCode/Zed IDE 集成、SDK 程序化调用）

2. 核心引擎层 – 共享的 Agent Loop、工具系统、子智能体系统、核心服务

核心设计特点：

• Agent Loop – 核心对话循环，协调用户输入、模型响应、工具执行

• 多客户端支持 – CLI 直接调用、IDE 通过 ACP 协议、SDK 通过进程通信

• 工具注册表模式 – 动态发现和加载工具（内置、MCP、命令行发现）

• 执行模式控制 – Plan/Default/Auto-edit/YOLO 四种权限策略

• 核心服务系统 – 会话记录、循环检测、对话压缩等关键能力

• 子智能体系统 – 支持任务分解和嵌套执行

• MCP 集成 – 扩展外部工具生态

关键数据流：

客户端（CLI/IDE/SDK）→ Session → Agent Loop → 模型 API→ 工具调用 → CoreToolScheduler → 权限检查 → 工具执行→ 结果返回 → 继续 Loop → 流式输出

客户端集成方式：

CLI 交互式 ──直接调用──→ Session → CoreVSCode/Zed ──ACP 协议──→ Session → CoreSDK 程序化 ──JSON Lines──→ Session → Core