1 项目概述项目概述

Qwen Code 是一个基于 AI Agent 的智能编程助手，采用模块化分层架构设计。核心是一个AI Agent 对话循环，持续协调用户输入、大语言模型（LLM）推理和工具执行，直到任务完成。

项目代码仓库：https://github.com/QwenLM/qwen-code.git

开发者指南： https://qwenlm.github.io/qwen-code-docs/zh/developers/architecture/

2 整体架构设计

2.1 架构分层

2.2 模块职责说明

2.3 客户端集成方式对比

3 核心流程详解

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.ts
 async function* sendMessageStream(request, turns = MAX_TURNS):
    // 1. 检查限制
    if exceedMaxTurns() or exceedTokenLimit():
        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.ts
async function runNonInteractive(userInput):
    currentMessages = [{ role: 'user', parts: userInput }]
    
    while true:
        turnCount++
        if turnCount > maxSessionTurns:
            handleMaxTurnsExceededError()
        
        // 调用核心层的递归 Loop
        responseStream = geminiClient.sendMessageStream(...)
        

        toolCallRequests = [ ]

        
        // 处理流式响应，转换为 JSON Lines
        for await (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 退出条件详解

4 核心模块详解

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 协议通信等功能。

5 模块间数据流向

5.1 完整数据流向

5.2 关键对接点

6 核心服务系统

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

存储位置：~/.qwen/tmp/<project_id>/chats/<session_id>.jsonl

6.1.2 核心方法

6.2 循环检测服务 (LoopDetectionService)

循环检测服务防止 AI 陷入无限循环，通过多种策略检测重复模式。核心文件: packages/core/src/services/loopDetectionService.ts

6.2.1 检测策略

6.2.2 工具调用循环检测

// 检测逻辑
private checkToolCallLoop(toolCall: { name: string; args: object }): boolean {
  const key = this.getToolCallKey(toolCall); // SHA256 哈希
  if (this.lastToolCallKey === key) {
    this.toolCallRepetitionCount++;
  } else {
    this.lastToolCallKey = key;
    this.toolCallRepetitionCount = 1;
  }
  return this.toolCallRepetitionCount >= TOOL_CALL_LOOP_THRESHOLD; // 5
}

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 会话恢复流程

7 总结

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 → Core
VSCode/Zed ──ACP 协议──→ Session → Core
SDK 程序化 ──JSON Lines──→ Session → Core

附录 A：关键文件索引

核心模块

核心服务

CLI 模块

IDE 集成

附录 B：术语表