简介

Qwen Code 是一个基于大语言模型（LLM）的智能编程助手项目，由 Qwen 团队开发维护。该项目旨在为开发者提供高效的代码编写、理解和编辑能力，支持多种模型提供商和本地部署方案。

Qwen Code 采用模块化架构设计，核心包含命令行界面（CLI）包和 Web UI 组件库两个主要子系统，能够适应不同的使用场景和部署环境。资料来源：README.md:1-10

技术架构

整体架构图

graph TD
    A[用户界面层] --> B[CLI 终端界面]
    A --> C[Web UI 组件库]
    B --> D[核心业务逻辑层]
    C --> D
    D --> E[模型交互层]
    E --> F[多模型提供商]
    F --> G[OpenAI 兼容 API]
    F --> H[Ollama 本地模型]
    F --> I[vLLM 服务]
    F --> J[阿里云 ModelStudio]

核心包结构

资料来源：packages/webui/README.md:1-30

CLI 包架构

目录结构

packages/cli/
├── src/
│   ├── ui/                    # 终端用户界面
│   │   ├── components/         # UI 组件
│   │   │   ├── arena/         # Arena 对比系统
│   │   │   ├── subagents/     # 子代理管理
│   │   │   ├── mcp/           # MCP 协议支持
│   │   │   ├── extensions/    # 扩展系统
│   │   │   ├── background-view/ # 后台任务视图
│   │   │   └── views/         # 通用视图组件
│   │   ├── hooks/             # 自定义 React Hooks
│   │   └── keyMatchers.ts     # 键盘快捷键匹配
│   ├── nonInteractiveCli.ts   # 非交互式 CLI
│   └── ...

UI 组件系统

CLI 包采用 React 组件化设计，所有 UI 组件基于 ink 库构建，支持终端环境下的富文本渲染。

核心组件分类：

资料来源：packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:1-50

Arena 对比系统

Arena 是 Qwen Code 中的 Agent 对比评估模块，允许用户同时运行多个代理并比较它们的结果。

Arena 核心功能：

• 选择对话框 (ArenaSelectDialog.tsx)：展示可用代理列表，支持状态筛选
• 停止对话框 (ArenaStopDialog.tsx)：提供清理或保留工作树的选项
• 卡片展示 (ArenaCards.tsx)：显示对比结果和统计数据

graph LR
    A[启动 Arena] --> B[选择代理]
    B --> C[运行对比]
    C --> D[结果展示]
    D --> E[选择获胜者]
    E --> F{清理策略}
    F -->|cleanup| G[清理工作树]
    F -->|preserve| H[保留Artifacts]

资料来源：packages/cli/src/ui/components/arena/ArenaStopDialog.tsx:1-60

子代理系统

子代理（Subagents）允许用户创建自定义的 AI 代理，配置专属的系统提示词、工具集和颜色标识。

子代理创建流程：

1. 配置基本信息（名称、描述）
2. 选择可用工具集
3. 设置系统提示词
4. 选择存储位置（项目级或用户级）
5. 保存并激活

interface SubagentConfig {
  name: string;
  description: string;
  systemPrompt: string;
  tools: string[];
  color?: string;
  location: 'project' | 'user';
  model?: string;
}

资料来源：packages/cli/src/ui/components/subagents/create/CreationSummary.tsx:1-40

MCP 协议支持

Qwen Code 集成了 MCP（Model Context Protocol）协议，支持通过 MCP 服务器扩展工具能力。

MCP 功能特性：

资料来源：packages/cli/src/ui/components/views/McpStatus.tsx:1-50

后台任务系统

后台任务视图（BackgroundTasksDialog）提供了长时间运行任务的监控能力。

任务状态展示：

• 运行中：显示进度文本和会话数量
• 已完成：显示执行时长和主题统计
• 错误状态：展示错误信息和警告
• 锁释放警告：提示可能的锁定问题

stateDiagram-v2
    [*] --> Running: 启动任务
    Running --> Completed: 成功完成
    Running --> Failed: 发生错误
    Completed --> [*]: 清理
    Failed --> [*]: 清理
    Completed --> LockWarning: 锁释放失败

资料来源：packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:1-80

Web UI 组件库

组件分类

资料来源：packages/webui/README.md:50-100

平台上下文

WebUI 提供 Platform Context 作为平台抽象层，支持不同运行环境的适配：

import { PlatformProvider, usePlatform } from '@qwen-code/webui/context';

主题系统

组件支持自定义主题配置，包括：

• 颜色系统：主色、强调色、状态色（成功/错误/警告）
• 尺寸变体：sm | md | lg
• 状态标识：错误状态、加载状态、空状态

文档站点

文档网站采用以下技术栈：

开发命令：

npm install    # 安装依赖
npm run link   # 链接 docs 目录内容
npm run dev    # 启动开发服务器

资料来源：docs-site/README.md:1-40

配置系统

模型配置

Qwen Code 支持配置多个模型提供商，通过 ~/.qwen/settings.json 文件管理：

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3:32b",
        "name": "Qwen3 32B (Ollama)",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": {
          "contextWindowSize": 131072
        }
      }
    ]
  },
  "model": {
    "name": "qwen3:32b"
  }
}

键盘快捷键

资料来源：packages/cli/src/ui/keyMatchers.test.ts:1-40

性能统计

StatsDisplay 组件展示任务执行的详细性能数据：

资料来源：packages/cli/src/ui/components/StatsDisplay.tsx:1-60

扩展系统

Qwen Code 支持通过扩展（Extensions）机制增强功能，每个扩展包含：

资料来源：packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:1-50

技术栈总结

总结

Qwen Code 项目采用现代化 monorepo 架构，通过 packages/cli 和 packages/webui 两个核心包分别服务终端用户和 Web 应用场景。丰富的组件系统（Arena、Subagents、MCP、Extensions）提供了强大的扩展能力，而统一的配置系统和键盘快捷键设计确保了用户体验的一致性。

环境要求

在开始使用 Qwen Code 之前，请确保您的开发环境满足以下要求：

资料来源：packages/webui/README.md

安装步骤

方式一：通过 npm 全局安装

npm install -g @qwen-code/cli

安装完成后，运行以下命令验证安装：

qwen --version

方式二：通过包管理器安装

根据您使用的包管理器选择相应命令：

# 使用 npm
npm install

# 使用 yarn
yarn install

# 使用 pnpm
pnpm install

资料来源：README.md

首次配置

配置模型提供商

Qwen Code 支持配置多个模型提供商，您需要在配置文件中添加 API 密钥和模型信息：

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.6-plus",
        "name": "qwen3.6-plus",
        "baseUrl": "https://api.example.com/v1",
        "description": "Qwen 3.6 Plus 模型",
        "envKey": "YOUR_API_KEY"
      }
    ]
  }
}

配置文件的默认位置为 ~/.qwen/config.json（用户级别）或项目目录下的 .qwen/config.json（项目级别）。

资料来源：README.md

配置环境变量

将您的 API 密钥设置为环境变量：

export YOUR_API_KEY="your-api-key-here"

支持的认证方式包括：

资料来源：packages/cli/src/ui/auth/AuthDialog.tsx

启动应用

配置完成后，通过以下命令启动 Qwen Code：

qwen

启动后将进入交互式命令行界面，您可以直接输入自然语言描述来生成代码。

资料来源：README.md

基本操作

切换模型

使用 /model 命令可以在已配置的模型之间切换：

/model

系统将显示可用模型列表，供您选择。

资料来源：README.md

管理子代理

Qwen Code 支持创建和管理子代理（Subagents），用于处理特定任务：

graph TD
    A[创建子代理] --> B[配置工具]
    B --> C[设置系统提示词]
    C --> D[生成描述]
    D --> E[保存到项目或用户级别]
    
    F[项目级别] --> E
    G[用户级别] --> E

子代理配置包括以下选项：

资料来源：packages/cli/src/ui/components/subagents/create/CreationSummary.tsx

MCP 服务器集成

Qwen Code 支持 MCP（Model Context Protocol）服务器，可扩展工具能力：

graph LR
    A[MCP 服务器] --> B[工具注册]
    B --> C[状态监控]
    C --> D{连接状态}
    D -->|已连接| E[可用工具列表]
    D -->|断开连接| F[显示错误日志]

常用 MCP 命令：

资料来源：packages/cli/src/ui/components/views/McpStatus.tsx 资料来源：packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx

交互界面

工具调用显示

工具调用结果在界面中以卡片形式展示：

对于文件操作类工具，系统会显示操作结果和文件列表：

ToolCallContainer
├── 状态标志
├── 操作描述
└── 文件位置列表

资料来源：packages/webui/src/components/toolcalls/GenericToolCall.tsx

性能统计

Qwen Code 提供实时性能统计功能：

资料来源：packages/cli/src/ui/components/StatsDisplay.tsx

键盘快捷键

资料来源：packages/cli/src/ui/keyMatchers.test.ts

Arena 对战模式

Arena 是 Qwen Code 的代码对比评估功能，可比较不同代理的代码生成结果：

graph TD
    A[进入 Arena] --> B[选择代理]
    B --> C[执行任务]
    C --> D[生成差异对比]
    D --> E[选择获胜者]
    E --> F[查看性能统计]

Arena 界面显示：

• 状态信息：执行状态、耗时、Token 数量、文件数量
• 差异统计：代码增删行数（绿色添加/红色删除）
• Token 效率：各代理的 Token 使用量和运行时间对比

资料来源：packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx 资料来源：packages/cli/src/ui/components/arena/ArenaCards.tsx

后台任务管理

Qwen Code 支持后台任务执行，适合长时间运行的任务：

graph TD
    A[提交任务] --> B[锁定资源]
    B --> C{执行状态}
    C -->|成功| D[释放锁]
    C -->|失败| E[记录错误]
    C -->|警告| F[锁释放警告]
    C -->|警告| G[元数据写入警告]

后台任务显示信息包括：

资料来源：packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx

扩展管理

Qwen Code 支持通过扩展增强功能：

资料来源：packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx

下一步

完成快速入门后，建议继续阅读以下文档：

• 配置指南：深入了解配置文件格式和高级选项
• 认证配置：学习如何配置各种认证方式
• 扩展开发：了解如何开发自定义扩展
• API 参考：查看完整的命令行接口文档

概述

Qwen Code 是一个模块化的命令行 AI 编程助手，采用多包架构设计以实现核心逻辑与用户界面的分离。项目主要由 packages/cli、packages/core 和 packages/webui 三个核心包组成，支持扩展机制、后台任务管理、代理（Agent）编排以及 MCP（Model Context Protocol）协议集成。

整体架构

graph TD
    User[用户] --> CLI[packages/cli<br/>命令行界面]
    CLI --> WebUI[packages/webui<br/>Web UI 组件]
    CLI --> Core[packages/core<br/>核心逻辑]
    Core --> Memory[记忆管理模块]
    Core --> Planner[任务规划模块]
    Core --> Tools[工具系统]
    CLI --> Mcp[MCP 服务器集成]
    Mcp --> Servers[外部 MCP 服务]

核心包结构

packages/core — 核心逻辑层

核心包负责 AI 代理的核心功能实现，包括任务规划、记忆管理和工具调用。

记忆管理模块

extractionAgentPlanner.ts 实现了记忆提取代理，规划器会扫描项目中的自动记忆主题文档并生成摘要块。该模块支持以下功能：

• 扫描 auto-memory 主题文档
• 截断长文本以控制上下文长度
• 构建 Markdown 格式的记忆摘要

资料来源：packages/core/src/memory/extractionAgentPlanner.ts:1-30

packages/cli — 命令行界面

CLI 包提供终端用户界面，处理用户输入、命令解析和状态展示。

Arena 竞技场组件

Arena 模块支持多代理并行对比功能。ArenaSelectDialog.tsx 实现了代理选择对话框，提供以下状态信息展示：

• 运行状态及颜色编码
• 运行时长
• Token 消耗统计
• 代码变更（增加/删除行数）
• 涉及文件数量

资料来源：packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:1-40

后台任务管理

BackgroundTasksDialog.tsx 实现了后台任务监控界面，支持以下功能：

• 任务进度文本显示
• Session 计数展示
• 主题追踪列表
• 错误状态展示
• 锁定释放警告
• 元数据写入警告

资料来源：packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:1-80

MCP 集成

MCP 模块负责与外部 MCP 服务器的通信：

graph LR
    CLI[CLI] --> ServerList[服务器列表]
    CLI --> ToolList[工具列表]
    ServerList --> Status[连接状态]
    ToolList --> Validation[工具验证]
    Status -->|disconnected| Debug[调试提示]

• ServerListStep.tsx: 显示 MCP 服务器列表及连接状态
• ToolListStep.tsx: 显示可用工具列表，支持滚动和选择
• 无效工具显示警告信息及原因

资料来源：packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx:1-50 资料来源：packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx:1-60

packages/webui — Web UI 组件库

WebUI 包提供可复用的 React 组件，支持 Storybook 文档化。

Platform Context

提供平台特定能力的抽象层：

import { PlatformProvider, usePlatform } from '@qwen-code/webui/context';

统计与性能监控

StatsDisplay.tsx 组件负责展示运行统计数据：

资料来源：packages/cli/src/ui/components/StatsDisplay.tsx:1-60

扩展机制

扩展系统支持自定义功能和 MCP 服务器集成：

• 扩展版本和路径信息展示
• 激活状态管理
• MCP 服务器关联配置
• 自定义命令注册

资料来源：packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:1-50

键盘交互系统

CLI 实现了一套完整的键盘快捷键匹配系统：

子代理创建流程

CreationSummary.tsx 组件展示子代理创建的配置摘要：

• 位置选择：项目级（.qwen/agents/）或用户级（~/.qwen/agents/）
• 工具配置显示
• 颜色标识
• 系统提示词和描述预览

资料来源：packages/cli/src/ui/components/subagents/create/CreationSummary.tsx:1-50

数据流架构

graph TD
    Input[用户输入] --> AtCmd[@ 命令处理]
    AtCmd --> Processor[命令处理器]
    Processor --> Config[配置系统]
    Config --> Agent[代理执行]
    Agent --> Tools[工具调用]
    Tools --> Mcp[MCP 协议]
    Mcp --> External[外部服务]
    Agent --> Memory[记忆更新]
    Memory --> UI[UI 更新]
    UI --> Stats[统计展示]

配置模型

项目支持灵活的配置模型，支持多个模型提供商：

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.6-plus",
        "name": "qwen3.6-plus",
        "baseUrl": "https://...",
        "envKey": "API_KEY",
        "generationConfig": {}
      }
    ]
  }
}

支持的配置项：

• 模型 ID 和名称
• API Base URL
• 环境变量密钥
• 生成配置（温度、最大 token 等）
• 思考模式启用

资料来源：README.md:1-50

技术栈总结

项目概述

Qwen Code 是一个采用 Monorepo（单仓库）结构管理的多语言 SDK 项目。根据项目根目录的 README.md 和各子包的文档，该项目包含了 CLI 命令行工具、WebUI 界面、Core 核心库、文档站点 等多个子包。

资料来源：README.md:1-50

整体架构

Qwen Code 采用 monorepo 结构组织代码，所有子包位于 packages/ 目录下。核心子包包括：

资料来源：packages/webui/README.md:1-30

子包详细结构

packages/cli

CLI 子包是用户与 Qwen Code 交互的主要入口，提供终端 UI 界面。

packages/cli/
├── src/
│   ├── ui/
│   │   ├── components/        # UI 组件目录
│   │   │   ├── arena/         # Arena 对战组件
│   │   │   ├── background-view/  # 后台任务视图
│   │   │   ├── extensions/    # 扩展管理组件
│   │   │   ├── subagents/     # 子代理创建组件
│   │   │   ├── mcp/           # MCP 服务器管理组件
│   │   │   ├── messages/      # 消息渲染组件
│   │   │   ├── hooks/         # Hook 配置组件
│   │   │   ├── views/         # 状态视图组件
│   │   │   └── DiffRenderer.tsx  # 差异渲染器
│   │   ├── commands/          # 命令定义
│   │   └── App.tsx            # 主应用组件
│   ├── i18n/                  # 国际化配置
│   │   ├── locales/           # 语言文件
│   │   └── mustTranslateKeys.test.ts  # 翻译覆盖测试
│   └── hooks/                 # 自定义 Hooks
└── package.json

核心 UI 组件功能说明：

资料来源：packages/cli/README.md

packages/webui

WebUI 子包提供基于 React 的图形化界面，支持 Storybook 组件预览。

packages/webui/
├── src/
│   ├── components/
│   │   ├── icons/             # 图标组件
│   │   ├── layout/            # 布局组件
│   │   ├── messages/          # 消息组件
│   │   └── ui/                # UI 基础组件
│   ├── context/               # 平台上下文
│   ├── hooks/                 # 自定义 React Hooks
│   └── types/                 # TypeScript 类型定义
├── .storybook/                # Storybook 配置
├── tailwind.preset.cjs        # Tailwind 预设
└── vite.config.ts             # Vite 构建配置

开发命令：

# 启动 Storybook
cd packages/webui && npm run storybook

# 构建生产版本
npm run build

# 类型检查
npm run typecheck

资料来源：packages/webui/README.md:1-60

packages/core

Core 子包包含核心业务逻辑，包括内存管理、内容生成等功能。

packages/core/
├── src/
│   ├── memory/
│   │   ├── prompt.ts              # 内存提示词配置
│   │   └── extractionAgentPlanner.ts  # 提取代理规划器
│   ├── core/
│   │   └── openaiContentGenerator/  # OpenAI 内容生成器
│   └── utils/
│       └── toml-to-markdown-converter.ts  # TOML 转 Markdown 工具

核心模块说明：

内存管理模块 (memory/)

内存管理模块负责管理对话中的持久化记忆，支持外部系统引用、主题文档扫描等功能。

• prompt.ts - 定义内存保存的规则和示例，包含 WHAT_NOT_TO_SAVE_SECTION 等常量
• extractionAgentPlanner.ts - 提供 buildTopicSummaryBlock 和 buildTaskPrompt 等函数用于构建主题摘要

内容生成模块 (openaiContentGenerator/)

openaiContentGenerator.ts 实现内容嵌入和生成功能：

const embedding = await this.pipeline.client.embeddings.create({
  model: 'text-embedding-ada-002',
  input: text,
});

工具函数 (utils/)

toml-to-markdown-converter.ts 提供 TOML 格式检测和转换功能：

• isTomlFormat(content: string): boolean - 检测内容是否为 TOML 格式

资料来源：packages/core/src/memory/prompt.ts:1-30

docs-site

文档站点基于 Next.js 和 Nextra 构建，提供项目文档的 Web 展示。

docs-site/
├── src/
│   └── app/
│       ├── [[...mdxPath]]/        # 动态 MDX 路由
│       │   └── page.jsx
│       └── layout.jsx             # 根布局
├── mdx-components.js               # MDX 组件配置
├── next.config.mjs                # Next.js 配置
└── package.json

文档内容通过符号链接从 ../docs 目录挂载：

npm run link  # 创建符号链接
npm run dev   # 启动开发服务器

资料来源：docs-site/README.md:1-40

依赖关系图

graph TD
    A[docs-site] --> B[docs]
    C[CLI] --> D[Core]
    C --> E[WebUI]
    E --> D
    F[webui] --> G[Core]
    
    style A fill:#e1f5fe
    style C fill:#fff3e0
    style E fill:#f3e5f5
    style G fill:#e8f5e9

技术栈总结

许可证

Qwen Code 项目采用 Apache-2.0 许可证发布。

资料来源：packages/webui/README.md:60

概述

智能体运行时（Agent Runtime）是 Qwen Code 系统中负责协调和管理智能体（Agent）生命周期、任务执行、工具调用的核心模块。它提供了智能体的交互式执行环境、后台任务管理、权限控制、以及运行时状态监控等功能。智能体运行时与 UI 层紧密集成，通过事件驱动的架构实现用户与智能体之间的实时交互。

智能体运行时的设计目标是为 AI 编程助手提供一个可扩展、安全且响应迅速的执行环境，支持单智能体任务执行和多智能体协作（如 Arena 对战模式）。

核心架构

组件层次

graph TD
    subgraph "UI 层"
        ArenaSelectDialog[Arena 选择对话框]
        BackgroundTasksDialog[后台任务对话框]
        StatsDisplay[统计信息显示]
    end
    
    subgraph "状态管理层"
        UIActionsContext[UI 操作上下文]
        AgentViewContext[智能体视图上下文]
    end
    
    subgraph "运行时核心"
        AgentCore[智能体核心]
        ToolScheduler[工具调度器]
        PermissionFlow[权限流程]
    end
    
    subgraph "执行层"
        ToolCalls[工具调用]
        SubAgents[子智能体]
        Monitors[监控器]
    end
    
    ArenaSelectDialog --> UIActionsContext
    BackgroundTasksDialog --> UIActionsContext
    UIActionsContext --> AgentCore
    AgentCore --> ToolScheduler
    AgentCore --> PermissionFlow
    ToolScheduler --> ToolCalls
    AgentCore --> SubAgents
    AgentCore --> Monitors

智能体状态模型

智能体运行时通过 AgentResultDisplay 类型定义智能体的执行状态：

资料来源：packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx:9-25

interface AgentResultDisplay {
  type: 'task_execution';
  subagentName: string;
  taskDescription: string;
  taskPrompt: string;
  status: 'running' | 'completed' | 'failed' | 'cancelled';
  toolCalls: ToolCall[];
}

任务执行机制

工具调用链

智能体运行时通过 ToolCall 结构管理所有工具调用操作。每个工具调用包含唯一标识符、调用名称、执行状态和结果描述。

graph LR
    UserInput[用户输入] --> AgentCore
    AgentCore --> ToolScheduler
    ToolScheduler --> Tool1[工具: read_file]
    ToolScheduler --> Tool2[工具: write_file]
    ToolScheduler --> Tool3[工具: bash]
    Tool1 --> Result1[成功/失败]
    Tool2 --> Result2[成功/失败]
    Tool3 --> Result3[成功/失败]
    Result1 --> StatsDisplay[统计显示]
    Result2 --> StatsDisplay
    Result3 --> StatsDisplay

工具调用数据结构

资料来源：packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx:27-34

子智能体任务

当智能体调用 agent 工具时，运行时会创建子智能体任务。子智能体继承父智能体的上下文，可以独立执行特定任务：

// 子智能体任务创建示例
{
  type: 'task_execution',
  subagentName: 'reviewer',
  taskDescription: 'reviewer task',
  taskPrompt: 'Run reviewer',
  status: 'running',
  toolCalls: [
    {
      callId: 'reviewer-read-1',
      name: 'read_file',
      status: 'success',
      description: 'Read file'
    }
  ]
}

子智能体运行时保持了焦点机制，使 Ctrl+E 快捷键可以展开查看详细信息。运行中的子智能体显示为 focused=true，而完成的子智能体可以正常折叠。

资料来源：packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx:63-68

Arena 模式

Arena 选择对话框

Arena 是 Qwen Code 支持的多智能体对战模式。用户可以通过 Arena 选择对话框选择不同的智能体进行对比测试或对战。

graph TD
    UserOpen[打开 Arena 对话框] --> ArenaSelectDialog
    ArenaSelectDialog --> FetchAgents[获取智能体列表]
    FetchAgents --> FilterAgents[筛选成功状态的智能体]
    FilterAgents --> DisplayList[显示智能体列表]
    DisplayList --> UserSelect{用户选择}
    UserSelect -->|选中| RunComparison[运行对比]
    UserSelect -->|Escape| CloseDialog[关闭对话框]
    RunComparison --> ShowResults[展示结果]

智能体选择状态

Arena 对话框中的每个智能体选项显示以下信息：

资料来源：packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:1-22

快捷键绑定

Arena 对话框支持以下键盘交互：

资料来源：packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:39-50

Arena 操作上下文

Arena 相关的操作通过 UIActionsContext 统一管理：

资料来源：packages/cli/src/ui/contexts/UIActionsContext.tsx:31-33

后台任务管理

后台任务对话框

BackgroundTasksDialog 组件负责展示和管理后台运行的智能体任务，包括长时间运行的任务、监控事件和会话状态。

graph TD
    Entry[任务条目] --> CheckStatus{状态检查}
    CheckStatus -->|有错误| ShowError[显示错误信息]
    CheckStatus -->|有警告| ShowWarning[显示警告信息]
    CheckStatus -->|正常| CheckTopics{有主题?}
    CheckTopics -->|是| ShowTopics[显示触及的主题]
    CheckTopics -->|否| CheckProgress{有进度?}
    CheckProgress -->|是| ShowProgress[显示进度文本]
    ShowTopics --> DisplaySummary[显示摘要]
    ShowProgress --> DisplaySummary
    ShowWarning --> DisplaySummary

任务状态展示

资料来源：packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:1-80

锁释放错误处理

当任务执行过程中出现锁释放错误时，系统会显示专门的警告信息：

Lock release warning: <错误描述>
Subsequent dreams may be skipped as locked until the next session's staleness sweep cleans the file.

这种设计确保终端状态保持为"已完成"，同时通过警告形式解释后续任务可能被跳过的原因。

资料来源：packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:37-50

监控器系统

监控通知机制

智能体运行时支持监控器（Monitor）功能，用于追踪长时间运行的任务和事件流。监控通知通过 XML 格式的回调函数传递：

type MonitorNotificationCallback = (
  displayText: string,        // 显示给用户的文本
  modelText: string,          // 模型原始文本
  meta: {
    monitorId: string;        // 监控器 ID
    toolUseId?: string;       // 关联的工具调用 ID
    status: 'running' | 'completed' | 'failed' | 'cancelled';
    eventCount: number;       // 事件计数
  }
) => void;

监控通知 XML 格式

Monitor emitted event #1.

<task-notification>
  <task-id>mon_1</task-id>
  <kind>monitor</kind>
  <status>running</status>
  <result>ready</result>
</task-notification>

监控器生命周期

资料来源：packages/cli/src/nonInteractiveCli.test.ts:1-50

性能统计

统计信息显示

StatsDisplay 组件展示智能体运行时的性能指标：

资料来源：packages/cli/src/ui/components/StatsDisplay.tsx:1-50

百分比计算

性能统计中的百分比通过以下公式计算：

apiTimePercent = (totalApiTime / agentActiveTime) × 100
toolTimePercent = (totalToolTime / agentActiveTime) × 100
cacheEfficiency = (cachedTokens / totalTokens) × 100

权限与安全

权限流程

智能体运行时通过 PermissionFlow 模块管理工具调用的权限请求。当智能体尝试执行受限操作（如文件写入、终端命令）时，系统会弹出权限请求对话框。

资料来源：packages/core/src/core/permissionFlow.ts

设置作用域

权限和其他设置支持两种作用域：

配置与扩展

MCP 服务器集成

智能体运行时支持 MCP（Model Context Protocol）服务器扩展。运行时通过 mcpServers 配置连接外部工具服务：

资料来源：packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:1-40

MCP 服务器状态处理

当存在断开的 MCP 服务器时，系统显示提示信息：

※ Run qwen --debug to see error logs

资料来源：packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx:1-30

总结

智能体运行时是 Qwen Code 系统的核心执行引擎，它协调管理智能体的生命周期、任务调度、工具调用、权限控制和状态监控。该系统通过以下特性提供可靠的 AI 编程辅助体验：

• 状态驱动：清晰的状态模型支持 UI 层实时反映任务执行状态
• 工具调度：统一的工具调度器管理所有工具调用和子智能体任务
• Arena 模式：支持多智能体对比和协作
• 后台任务：长时间运行任务的后台管理，减少对主界面的干扰
• 监控通知：实时事件通知机制，支持长时间任务的追踪
• 性能统计：详细的运行时性能指标，帮助用户了解资源消耗

概述

Qwen Code 的工具系统是整个代码智能助手的核心能力模块，它为 AI Agent 提供了与代码库、文件系统、外部服务交互的能力。该系统支持多种类型的工具调用，包括内置工具（如 Shell 执行、文件编辑、LSP 通信）、MCP（Model Context Protocol）服务器工具以及子代理（Subagent）自定义工具。

工具系统在 UI 层通过 ToolListStep 组件呈现交互式列表界面，支持工具搜索、选择、滚动浏览等功能。同时，工具使用情况会在 ContextUsage 组件中单独统计，显示每个工具消耗的 token 数量。资料来源：packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx:1-80，packages/cli/src/ui/components/views/ContextUsage.tsx:1-100

概述

模型集成是 Qwen Code 框架的核心子系统，负责与各类大语言模型（LLM）提供商建立通信连接、发送请求并处理响应。该系统通过统一的内容生成器接口抽象不同提供商的实现细节，使上层业务逻辑能够以一致的方式调用各种模型服务。资料来源：packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts

架构设计

整体架构

graph TD
    A[业务层] --> B[ContentGenerator 接口]
    B --> C[OpenAI ContentGenerator]
    B --> D[Anthropic ContentGenerator]
    B --> E[Gemini Chat]
    C --> F[Provider 层]
    F --> G[DashScope Provider]
    F --> H[OpenRouter Provider]
    F --> I[OpenAI Compatible Provider]

核心接口抽象

系统定义了统一的内容生成器接口，所有具体实现必须遵循该契约：

资料来源：packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts:30-80

Provider 实现体系

DashScope Provider（阿里云）

DashScope 是阿里云提供的大模型服务，Qwen Code 通过专门的 Provider 进行集成：

// packages/core/src/core/openaiContentGenerator/provider/dashscope.ts
export class DashScopeProvider implements ModelProvider {
  readonly baseUrl = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
  
  async chat(params: ChatParams): Promise<ChatResponse> {
    // 实现与阿里云 DashScope API 的通信
  }
}

配置示例：

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.6-plus",
        "name": "qwen3.6-plus (Coding Plan)",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "description": "qwen3.6-plus from ModelStudio Coding Plan",
        "envKey": "BAILIAN_CODING_PLAN_API_KEY"
      }
    ]
  }
}

资料来源：packages/core/src/core/openaiContentGenerator/provider/dashscope.ts

OpenRouter Provider

OpenRouter 提供对多种模型的统一访问接口：

// packages/core/src/core/openaiContentGenerator/provider/openrouter.ts
export class OpenRouterProvider implements ModelProvider {
  readonly baseUrl = 'https://openrouter.ai/api/v1';
  
  async chat(params: ChatParams): Promise<ChatResponse> {
    // 实现与 OpenRouter API 的通信
  }
}

资料来源：packages/core/src/core/openaiContentGenerator/provider/openrouter.ts

OpenAI 兼容 Provider

通用的 OpenAI API 兼容实现，可连接任何遵循 OpenAI API 规范的服务：

graph LR
    A[请求] --> B[OpenAI Compatible Provider]
    B --> C{目标服务}
    C --> D[本地部署模型]
    C --> E[vLLM]
    C --> F[Ollama]
    C --> G[其他兼容服务]

vLLM 配置示例：

{
  "modelProviders": {
    "openai": [
      {
        "id": "Qwen/Qwen3-32B",
        "name": "Qwen3 32B (vLLM)",
        "baseUrl": "http://localhost:8000/v1",
        "description": "Qwen3 32B running locally via vLLM",
        "generationConfig": {
          "contextWindowSize": 131072
        }
      }
    ]
  }
}

Ollama 配置示例：

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3:32b",
        "name": "Qwen3 32B (Ollama)",
        "baseUrl": "http://localhost:11434/v1",
        "description": "Qwen3 32B running locally via Ollama",
        "generationConfig": {
          "contextWindowSize": 131072
        }
      }
    ]
  }
}

资料来源：README.md:50-120

Anthropic Claude 集成

内容生成器实现

Anthropic Claude 通过专门的内容生成器进行集成：

// packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts
export class AnthropicContentGenerator implements ContentGenerator {
  private readonly client: Anthropic;
  
  async generate(
    prompt: string,
    options?: GenerationOptions
  ): Promise<GenerationResult> {
    const message = await this.client.messages.create({
      model: this.model,
      max_tokens: options?.maxTokens ?? 4096,
      messages: [{ role: 'user', content: prompt }],
    });
    
    return {
      content: message.content[0].text,
      usage: {
        inputTokens: message.usage.input_tokens,
        outputTokens: message.usage.output_tokens,
      },
    };
  }
}

特性支持

资料来源：packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts

Google Gemini 集成

聊天实现

Gemini 通过专门的聊天模块进行集成：

// packages/core/src/core/geminiChat.ts
export class GeminiChat {
  private readonly model: GenerativeModel;
  
  async generateContent(
    prompt: string,
    config?: GenerationConfig
  ): Promise<GenerateContentResult> {
    const result = await this.model.generateContent(prompt);
    return result;
  }
  
  async streamGenerateContent(
    prompt: string,
    config?: GenerationConfig
  ): Promise<AsyncIterable<string>> {
    const result = await this.model.generateContentStream(prompt);
    // 返回流式响应
  }
}

资料来源：packages/core/src/core/geminiChat.ts

配置管理

配置文件结构

模型集成通过 ~/.qwen/settings.json 进行统一配置：

{
  "modelProviders": {
    "openai": [...],
    "anthropic": {
      "apiKey": "sk-..."
    },
    "google": {
      "apiKey": "..."
    }
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3:32b"
  }
}

模型切换

用户可以通过 /model 命令在运行时切换不同模型：

qwen
> /model qwen3.6-plus

资料来源：README.md:100-150

请求处理流程

标准生成流程

sequenceDiagram
    participant U as 用户
    participant G as ContentGenerator
    participant P as Provider
    participant API as 外部API
    
    U->>G: generate(prompt, options)
    G->>P: chat(params)
    P->>API: HTTP POST /chat/completions
    API-->>P: Response
    P-->>G: ChatResponse
    G-->>U: GenerationResult

错误处理

资料来源：packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts:100-150

与记忆系统的集成

模型集成与记忆系统深度协作，支持上下文管理和持久化：

// packages/core/src/memory/extractionAgentPlanner.ts
async function buildTopicSummaryBlock(projectRoot: string): Promise<string> {
  const docs = await scanAutoMemoryTopicDocuments(projectRoot);
  return docs.map((doc) => {
    return [
      `- [${doc.title}](${doc.relativePath})`,
      `  topic=${doc.type}`,
      `  current=${doc.body}`,
    ].join('\n');
  }).join('\n\n');
}

资料来源：packages/core/src/memory/extractionAgentPlanner.ts:20-60

总结

模型集成模块是 Qwen Code 连接各类大语言模型服务的桥梁，通过标准化的 Provider 接口设计，系统能够灵活支持多种模型提供商，包括阿里云 DashScope、OpenRouter、OpenAI 兼容接口、Google Gemini 和 Anthropic Claude 等。该设计遵循开闭原则，便于后续扩展新的模型提供商。

概述

记忆系统是 Qwen Code 的核心组件之一，负责在 AI 与用户的交互过程中自动捕获、存储和检索有用的上下文信息。该系统通过智能记忆提取、定期梦境整理和上下文召回三大机制，帮助 AI 保持对项目、用户偏好、外部系统引用等长期信息的感知能力。

记忆系统的主要目标包括：

• 减少重复信息传递：用户无需反复告知 AI 相同的背景信息
• 维护项目上下文：保存项目相关的架构决策、外部依赖和重要约定
• 个性化体验：记住用户的偏好和工作习惯
• 外部系统追踪：记录对外部系统（如 Linear、Grafana）的引用关系

资料来源：packages/core/src/memory/prompt.ts:1-50

系统架构

记忆系统采用分层架构，包含五个核心模块，各模块职责分明、协同工作。

graph TD
    subgraph 记忆系统架构
        A[记忆管理器<br/>manager.ts] --> B[提取模块<br/>extract.ts]
        A --> C[召回模块<br/>recall.ts]
        A --> D[梦境模块<br/>dream.ts]
        A --> E[索引模块<br/>indexer.ts]
    end
    
    subgraph 外部交互
        E --> F[记忆存储<br/>文件系统]
        F --> C
        B --> G[对话历史]
        D --> F
    end
    
    style A fill:#e1f5fe
    style F fill:#fff3e0

组件职责矩阵

资料来源：packages/core/src/memory/manager.ts, packages/core/src/memory/indexer.ts

核心功能模块

1. 记忆提取（Extract）

记忆提取模块负责从对话历史中自动识别有价值的信息片段。该模块通过专门的提示词工程（Prompt Engineering）引导 AI 理解何时应该保存记忆、保存什么类型的信息。

#### 提取的记忆类型

根据 prompt.ts 中的定义，系统将记忆分为以下几类：

graph LR
    subgraph 记忆分类
        A[user] --> E[用户偏好]
        B[feedback] --> F[反馈信息]
        C[project] --> G[项目信息]
        D[reference] --> H[外部引用]
    end
    
    style E fill:#c8e6c9
    style F fill:#ffe0b2
    style G fill:#bbdefb
    style H fill:#e1bee7

用户偏好（user/）：存储用户的个人偏好、工作习惯和配置选择

反馈信息（feedback/）：记录用户对 AI 回复的纠正和调整

项目信息（project/）：保存项目相关的架构决策、技术选型和重要约定

外部引用（reference/）：追踪对外部系统的引用（如缺陷追踪系统、监控系统）

资料来源：packages/core/src/memory/prompt.ts:1-80

#### 提取时机与策略

系统仅在特定情况下触发记忆提取：

• 外部系统引用：当用户提到 bugs 在 Linear 中跟踪或反馈在某个 Slack 频道时
• 架构决策：当用户描述项目的技术选型或设计模式时
• 配置变更：当用户修改了项目配置或工具设置时

提取模块遵循以下原则：

• 仅保存非显而易见的长期信息
• 不保存代码模式、文件路径等可从代码库推导的内容
• 不保存 Git 历史或调试解决方案（这些可通过 git log 等命令获取）
• 保持每类记忆的唯一性，避免重复

资料来源：packages/core/src/memory/prompt.ts:85-100

2. 记忆召回（Recall）

召回模块是记忆系统的"读取"端，负责在需要时检索相关记忆。

#### 召回流程

sequenceDiagram
    participant AI as AI 代理
    participant Recall as 召回模块
    participant Index as 索引模块
    participant Storage as 记忆存储
    
    AI->>Recall: 请求召回相关记忆
    Recall->>Index: 查询索引
    Index-->>Recall: 返回记忆文件列表
    Recall->>Storage: 读取记忆内容
    Storage-->>Recall: 返回记忆内容
    Recall-->>AI: 提供相关上下文

#### 召回触发场景

召回机制在以下场景被激活：

1. 用户消息预处理：在处理用户输入前，先检索可能相关的记忆
2. 上下文窗口构建：将相关记忆注入 AI 的上下文窗口
3. 决策参考：当 AI 需要做出影响用户的决策时获取背景信息

资料来源：packages/core/src/memory/recall.ts, packages/core/src/memory/indexer.ts

3. 梦境模块（Dream）

梦境模块是记忆系统的维护组件，定期对记忆进行整理和强化。

#### 梦境机制

graph TD
    A[定时触发] --> B{锁定记忆文件}
    B --> C[读取所有记忆]
    C --> D[分析记忆关联性]
    D --> E[强化重要记忆]
    E --> F[清理过时信息]
    F --> G[更新索引]
    G --> H[释放文件锁]
    
    style A fill:#ffecb3
    style H fill:#c8e6c9

#### 梦境行为说明

• 文件锁定：防止在整理过程中被其他进程修改
• 关联分析：识别记忆间的关联关系，优化检索效率
• 强化机制：对频繁访问的记忆增加访问优先级
• 清理机制：移除不再相关或已被覆盖的记忆条目

注意：梦境操作可能导致锁释放失败或元数据写入失败。锁释放失败会使后续梦境被静默跳过，元数据写入失败可能导致调度器无法获取最新运行状态。

资料来源：packages/core/src/memory/dream.ts, packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:50-75

4. 索引管理（Indexer）

索引模块负责维护记忆文件的元数据索引，支持高效的召回查询。

#### 索引结构

索引文件采用 Markdown 链接格式，每行代表一个记忆条目：

- [记忆标题](relative/path.md) — 一句话描述

索引遵循以下规则：

• 每个记忆文件必须有对应的索引条目
• 索引条目必须包含标题、相对路径和一句话描述
• 创建或删除记忆文件时必须同步更新索引
• 索引本身不是记忆，内容不直接写入

资料来源：packages/core/src/memory/extractionAgentPlanner.ts:1-30, packages/core/src/memory/extractionAgentPlanner.ts:35-60

记忆存储结构

记忆系统使用文件系统存储记忆，每个记忆类别对应一个子目录：

~/.qwen/memory/
├── user/           # 用户偏好记忆
├── feedback/       # 用户反馈记忆
├── project/        # 项目信息记忆
├── reference/      # 外部引用记忆
└── index.md        # 记忆索引文件

记忆文件格式

记忆文件采用 Markdown 格式，包含 YAML frontmatter 元数据：

概述

会话管理（Session Management）是 Qwen Code 核心系统之一，负责管理和维护用户与 AI 助手交互的所有对话历史。系统通过结构化的数据模型存储会话信息，支持会话分叉（Fork）、会话列表检索、后台任务状态跟踪等核心功能。

会话数据以 JSONL（JSON Lines）格式持久化存储在项目目录的 ~/.qwen/chats/ 下，每个会话文件以会话 ID 命名，格式为 {sessionId}.jsonl。资料来源：packages/core/src/services/sessionService.ts:1-50

核心数据模型

ChatRecord 会话记录

会话中的每条消息都被封装为 ChatRecord 结构，是会话持久化的基本单元：

资料来源：packages/core/src/services/sessionService.ts:35-50

会话元数据结构

会话检索时返回的元数据结构包含以下关键字段：

资料来源：packages/vscode-ide-companion/src/services/qwenAgentManager.ts:30-45

会话服务架构

SessionService 核心服务

SessionService 是会话管理的核心服务类，负责：

• 会话文件的读写操作
• 会话 ID 验证与生成
• 会话分叉（Fork）操作
• 项目所有权验证

class SessionService {
  private getChatsDir(): string;
  private getSessionFilePath(sessionId: string): string;
  private validateSessionId(newSessionId: string): void;
  async forkSession(sourceSessionId: string, newSessionId: string): Promise<void>;
}

资料来源：packages/core/src/services/sessionService.ts:1-100

会话文件模式验证

系统使用正则表达式 SESSION_FILE_PATTERN 验证会话 ID 的合法性，确保文件名安全：

SESSION_FILE_PATTERN.test(`${newSessionId}.jsonl`)

不合法的会话 ID 将抛出错误：Invalid new sessionId: ${newSessionId}

资料来源：packages/core/src/services/sessionService.ts:15-20

会话分叉（Fork）

分叉机制概述

会话分叉允许从现有会话创建新会话，同时保持与原会话的消息血缘关系。分叉操作会重建父消息 UUID 链，确保新会话是原会话的线性后裔。

分叉流程图

graph TD
    A[源会话] --> B[读取源会话记录]
    B --> C[验证项目所有权]
    C --> D{验证通过?}
    D -->|否| E[抛出错误]
    D -->|是| F[重建 parentUuid 链]
    F --> G[设置 forkedFrom 元数据]
    G --> H[创建新会话文件]
    H --> I[分叉完成]

forkedFrom 元数据结构

分叉后的每条消息都记录其来源信息：

interface ForkedFrom {
  sessionId: string;    // 来源会话 ID
  messageUuid: string; // 来源消息 UUID
}

资料来源：packages/core/src/services/sessionService.ts:40-55

分叉实现代码

const forked: ChatRecord[] = records.map((record) => {
  const next: ChatRecord = {
    ...record,
    sessionId: newSessionId,
    parentUuid: prevUuid,
    forkedFrom: {
      sessionId: sourceSessionId,
      messageUuid: record.uuid,
    },
  };
  prevUuid = record.uuid;
  return next;
});

资料来源：packages/core/src/services/sessionService.ts:60-75

会话标题管理

标题生成服务

sessionTitle.ts 负责为新会话生成有意义的标题。系统通过分析会话内容自动提取标题，便于用户快速识别和检索会话。

标题生成策略

• 分析首条用户消息的主题
• 提取关键主题词作为标题
• 支持自定义标题覆盖

资料来源：packages/core/src/services/sessionTitle.ts:1-30

聊天压缩服务

压缩机制

chatCompressionService.ts 实现了会话历史压缩功能，当会话长度超过阈值时自动压缩早期消息，减少 token 消耗同时保留关键上下文。

压缩触发条件

资料来源：packages/core/src/services/chatCompressionService.ts:1-50

子代理追踪

SubAgentTracker

SubAgentTracker 负责追踪会话中的子代理（Sub-Agent）活动。当主代理派生子代理完成任务时，跟踪器记录子代理的执行状态和结果。

追踪数据结构

interface SubAgentInfo {
  agentId: string;
  parentAgentId: string;
  status: 'running' | 'completed' | 'failed';
  startTime: number;
  endTime?: number;
  result?: unknown;
}

资料来源：packages/cli/src/acp-integration/session/SubAgentTracker.ts:1-40

后台任务与会话关联

状态显示

后台任务对话框显示与会话相关的状态信息：

资料来源：packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:20-60

错误与警告展示

系统会展示会话相关的错误和警告信息：

• 错误状态：显示 entry.error 内容
• 锁定释放警告：当锁定释放失败时提示后续梦境可能被跳过
• 元数据写入警告：Scheduler Gate 未获取最新运行的提示

资料来源：packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:70-100

会话检索机制

ACP 会话列表获取

系统通过 ACP（Agent Communication Protocol）接口获取会话列表：

// ACP 方式获取会话
const sessions = await acpClient.getSessions();

// 文件系统方式获取（降级方案）
const sessions = await this.sessionReader.getAllSessions(undefined, true);

获取策略

1. 优先尝试 ACP 接口获取会话列表
2. ACP 获取失败时降级到文件系统直接读取
3. 返回统一格式的会话元数据数组

资料来源：packages/vscode-ide-companion/src/services/qwenAgentManager.ts:20-50

VSCode IDE 集成

QwenAgentManager

VSCode 扩展通过 QwenAgentManager 服务管理会话，集成以下功能：

• 会话列表展示
• 会话详情查看
• 新会话创建
• 会话切换

服务初始化

class QwenAgentManager {
  private sessionReader: SessionReader;
  
  async getAllSessions(): Promise<QwenSession[]>;
  async getSessionById(sessionId: string): Promise<QwenSession | null>;
}

资料来源：packages/vscode-ide-companion/src/services/qwenAgentManager.ts:1-60

最佳实践

会话命名规范

• 使用有意义的会话标题
• 避免特殊字符在会话 ID 中
• 定期清理不需要的会话文件

会话分叉使用场景

性能优化

• 及时压缩长会话减少内存占用
• 使用项目哈希快速定位相关会话
• 通过 messageCount 评估会话复杂度

概述

技能（Skills）与钩子（Hooks）系统是 Qwen Code 框架的核心扩展机制，旨在为 AI 编程助手提供高度模块化、可定制的功能扩展能力。技能系统允许开发者定义独立的工具集和功能模块，而钩子系统则在关键执行节点提供拦截、修改和增强行为的能力。

技能与钩子系统的主要职责包括：

• 动态加载：在运行时从文件系统或远程源加载技能包
• 生命周期管理：管理技能的激活、停用和卸载流程
• 事件拦截：在工具执行、消息处理等关键节点注入自定义逻辑
• 上下文注入：向 AI 模型提供额外的系统提示和上下文信息
• 错误处理增强：通过钩子机制提供更细粒度的错误处理和恢复策略

系统架构

整体架构图

graph TB
    subgraph "技能层 Skill Layer"
        SM[技能管理器<br/>SkillManager]
        SA[技能激活器<br/>SkillActivator]
        SL[技能加载器<br/>SkillLoader]
    end
    
    subgraph "钩子层 Hook Layer"
        HS[钩子系统<br/>HookSystem]
        HR[钩子注册表<br/>HookRegistry]
        HP[钩子处理器<br/>HookProcessor]
    end
    
    subgraph "执行层 Execution Layer"
        TS[工具调度器<br/>ToolScheduler]
        MB[消息总线<br/>MessageBus]
    end
    
    subgraph "工具层 Tool Layer"
        BT[内置工具<br/>BuiltinTools]
        MCPT[MCP工具<br/>MCPTools]
        SKT[技能工具<br/>SkillTools]
    end
    
    SM --> SA
    SL --> SM
    SA --> TS
    HS --> MB
    HR --> HP
    HP --> TS
    BT --> TS
    MCPT --> TS
    SKT --> TS

技能系统架构

技能系统采用管理器模式，通过 SkillManager 统一管理所有技能的生命周期。每个技能作为一个独立的功能单元，包含工具定义、系统提示和激活逻辑。

graph LR
    A[技能定义文件] --> B[技能加载器<br/>skill-load.ts]
    B --> C[技能管理器<br/>skill-manager.ts]
    C --> D[技能激活器<br/>skill-activation.ts]
    D --> E[工具注册]
    D --> F[上下文注入]
    D --> G[系统提示增强]

钩子系统架构

钩子系统基于发布-订阅模式，在关键执行节点注册回调函数，实现行为拦截和增强。

graph TB
    A[事件触发点] --> B{钩子类型检查}
    B -->|预执行钩子| C[Pre-Hook]
    B -->|后执行钩子| D[Post-Hook]
    B -->|失败钩子| E[Failure-Hook]
    
    C --> F[执行前置逻辑]
    D --> G[处理返回结果]
    E --> H[错误处理增强]
    
    F --> I[继续执行]
    G --> J[返回修改结果]
    H --> K[返回错误上下文]

核心组件

技能管理器 (SkillManager)

技能管理器是技能系统的中央协调器，负责维护技能注册表、协调加载流程和提供统一的访问接口。

资料来源：packages/core/src/skills/skill-manager.ts

技能加载器 (SkillLoader)

技能加载器负责从各种来源加载技能定义，包括本地文件系统、远程 URL 和内置技能包。

资料来源：packages/core/src/skills/skill-load.ts

技能激活器 (SkillActivator)

技能激活器负责将技能集成到运行时环境，包括工具注册、提示词注入和状态初始化。

资料来源：packages/core/src/skills/skill-activation.ts

钩子系统 (HookSystem)

钩子系统提供在关键执行节点插入自定义逻辑的能力，支持同步和异步钩子执行。

interface HookConfig {
  name: string;           // 钩子名称
  priority: number;       // 执行优先级，数值越小越先执行
  enabled: boolean;       // 是否启用
  handler: HookHandler;   // 钩子处理函数
}

资料来源：packages/core/src/hooks/hookSystem.ts

钩子注册表 (HookRegistry)

钩子注册表维护所有已注册的钩子实例，提供查询、排序和批量操作功能。

资料来源：packages/core/src/hooks/hookRegistry.ts

执行流程

技能激活流程

sequenceDiagram
    participant User as 用户
    participant SM as 技能管理器
    participant SL as 技能加载器
    participant SA as 技能激活器
    participant TS as 工具调度器

    User->>SM: 加载技能请求
    SM->>SL: 调用 loadFromPath()
    SL->>SL: 扫描技能目录
    SL-->>SM: 返回技能定义列表
    SM->>SA: 激活技能
    SA->>SA: 初始化技能状态
    SA->>TS: 注册技能工具
    TS-->>SA: 注册成功
    SA->>SA: 注入系统提示
    SA-->>SM: 激活完成
    SM-->>User: 返回激活结果

工具执行与钩子调用流程

sequenceDiagram
    participant Agent as AI代理
    participant HS as 钩子系统
    participant TS as 工具调度器
    participant Tool as 工具实现
    participant MB as 消息总线

    Agent->>TS: 请求执行工具
    TS->>HS: 触发 preToolUse 钩子
    HS->>HS: 执行前置钩子链
    HS-->>TS: 钩子执行结果
    
    alt 钩子允许执行
        TS->>Tool: 调用工具
        Tool-->>TS: 返回结果
        TS->>HS: 触发 postToolUse 钩子
        HS->>HS: 执行后置钩子链
        HS-->>TS: 处理后的结果
        TS-->>Agent: 返回最终结果
    else 钩子阻止执行
        HS-->>TS: 返回阻止信号
        TS-->>Agent: 返回错误响应
    end
    
    Note over TS,MB: 失败处理流程
    Tool-->>TS: 抛出异常
    TS->>MB: 触发 postToolUseFailure 钩子
    MB->>MB: 执行失败钩子链
    MB-->>TS: 错误增强结果
    TS-->>Agent: 返回带上下文的错误

数据模型

技能定义结构

interface SkillDefinition {
  id: string;                    // 唯一标识符
  name: string;                  // 显示名称
  version: string;               // 版本号
  description: string;          // 功能描述
  author?: string;               // 作者信息
  tools: SkillTool[];            // 工具定义列表
  systemPrompt?: string;         // 系统提示词片段
  activationConfig?: object;     // 激活配置
  resources?: string[];          // 依赖资源路径
  dependencies?: string[];       // 依赖的其他技能
}

工具结果结构

技能工具返回的结果遵循统一的结构规范，包含返回内容和显示信息：

interface SkillToolResult {
  returnDisplay: string;        // 返回值的文本表示
  modelOverride?: string;       // 模型覆盖指令
  error?: {
    message: string;            // 错误消息
    type: string;               // 错误类型
  };
}

资料来源：packages/core/src/core/coreToolScheduler.ts:25-35

钩子结果结构

interface HookResult {
  continue: boolean;            // 是否继续执行后续钩子/主流程
  modifiedContent?: string;     // 修改后的内容
  additionalContext?: string;   // 附加的上下文信息
  suppressError?: boolean;      // 是否抑制错误传播
}

钩子类型详解

工具执行钩子

工具执行钩子在工具调用的生命周期中提供多个拦截点，支持精细化的行为控制。

消息处理钩子

消息处理钩子拦截聊天消息的发送和接收过程，支持内容过滤和增强。

生命周期钩子

生命周期钩子监听会话和系统的重要状态变化。

集成与扩展

注册自定义技能

开发者可以通过扩展技能系统来添加自定义功能：

import { SkillManager } from '@qwen-code/core';

const skillManager = SkillManager.getInstance();

// 定义技能
const customSkill = {
  id: 'my-custom-skill',
  name: '自定义技能',
  version: '1.0.0',
  description: '演示自定义技能开发',
  tools: [
    {
      name: 'customTool',
      description: '自定义工具',
      execute: async (input) => {
        return { returnDisplay: `处理结果: ${input}` };
      }
    }
  ],
  systemPrompt: '你可以使用 customTool 工具来处理自定义任务。'
};

// 注册并激活
await skillManager.register(customSkill);
await skillManager.activate('my-custom-skill');

注册自定义钩子

开发者可以在关键执行点注入自定义逻辑：

import { HookRegistry } from '@qwen-code/core';

const registry = HookRegistry.getInstance();

// 注册前置钩子
registry.register({
  name: 'parameter-validator',
  type: 'preToolUse',
  priority: 100,
  enabled: true,
  handler: async (toolName, toolInput) => {
    // 参数验证逻辑
    if (!validateInput(toolInput)) {
      return {
        continue: false,
        additionalContext: '参数验证失败，请检查输入格式。'
      };
    }
    return { continue: true };
  }
});

失败钩子的高级用法

失败钩子支持在工具执行失败时添加上下文信息或执行重试逻辑：

registry.register({
  name: 'error-enhancer',
  type: 'postToolUseFailure',
  priority: 50,
  enabled: true,
  handler: async (toolName, toolInput, error, willRetry) => {
    let additionalContext = '';

    // 为网络错误添加重试建议
    if (error.message.includes('ECONNREFUSED')) {
      additionalContext = '建议检查网络连接和目标服务状态。';
    }

    // 为权限错误添加帮助信息
    if (error.message.includes('permission')) {
      additionalContext = '请确保具有必要的操作权限。';
    }

    return {
      continue: true,
      additionalContext,
      suppressError: false
    };
  }
});

资料来源：packages/core/src/core/coreToolScheduler.ts:45-70

配置选项

技能配置

技能系统支持通过配置文件进行初始化：

{
  "skills": {
    "enabled": true,
    "autoActivate": true,
    "loadPaths": [
      ".qwen/skills",
      "~/.qwen/skills"
    ],
    "excludedSkills": []
  }
}

钩子配置

钩子系统支持细粒度的启用/禁用控制：

{
  "hooks": {
    "enabled": true,
    "globalTimeout": 5000,
    "hooks": {
      "preToolUse": {
        "enabled": true,
        "timeout": 1000
      },
      "postToolUse": {
        "enabled": true,
        "timeout": 2000
      },
      "postToolUseFailure": {
        "enabled": true,
        "timeout": 3000
      }
    }
  }
}

最佳实践

技能开发规范

1. 单一职责：每个技能应专注于特定功能领域
2. 版本管理：遵循语义化版本规范，清晰标注兼容性
3. 依赖声明：明确声明技能依赖的其他技能或资源
4. 错误处理：为工具实现提供完整的错误处理和用户友好的错误信息
5. 资源清理：在技能停用时正确释放资源

钩子开发规范

1. 执行效率：钩子处理应尽可能高效，避免阻塞主流程
2. 错误安全：钩子内部应实现异常捕获，防止错误传播影响系统稳定性
3. 优先级规划：合理设置钩子优先级，确保执行顺序符合预期
4. 幂等性：确保钩子在重复执行时产生一致的结果
5. 超时控制：为可能耗时较长的操作设置合理的超时时间

安全注意事项

1. 输入验证：在钩子中始终验证输入参数的安全性
2. 权限检查：敏感操作应配合权限钩子进行访问控制
3. 日志审计：记录关键钩子的执行情况，便于问题排查
4. 沙箱隔离：自定义技能应在受限环境中执行，防止恶意代码

总结

技能与钩子系统为 Qwen Code 提供了强大而灵活的扩展机制。技能系统通过模块化的设计允许开发者以插件形式添加新功能，而钩子系统则提供了在关键执行点进行拦截和增强的能力。两者协同工作，使得框架能够在保持核心简洁的同时支持高度定制化的使用场景。

熟练掌握这两个系统的使用，将有助于开发者构建功能丰富、行为可控的 AI 编程辅助工具。

Pitfall Log / 踩坑日志

项目：QwenLM/qwen-code

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | host_targets=claude, claude_code, chatgpt

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium

5. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | No sandbox install has been executed yet; downstream must verify before user use.

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | release_recency=unknown