QwenPaw 源码学习指南

版本 : v1.1.9 | 许可证 : Apache 2.0 | 仓库 : agentscope-ai/QwenPaw

1. 项目概述

QwenPaw （全称 Qwen Personal Agent Workstation ，原名 CoPaw）是一个开源个人 AI 助手平台 ，由 AgentScope 团队开发和维护。

核心定位

一个可在本地或云端部署的 AI 助手，支持通过多种即时通讯渠道与用户交互，通过"技能（Skills）"系统无限扩展能力。

核心特性

特性	说明
本地部署	数据完全存储在用户机器上，无需第三方托管
多 Agent 协作	可创建多个独立 Agent，各有独立角色，通过 `chat_with_agent` 等工具实现协作
多通道/渠道接入	支持 15+ 种 IM 平台（钉钉、飞书、微信、QQ、Discord、Telegram、iMessage、Matrix 等）
技能扩展	内置 PDF/Office 处理、新闻摘要等技能，支持从 ClawHub/GitHub/LobeHub/ModelScope 安装
Coding Mode	三面板 Web IDE（文件树 + 标签页编辑器 + Git），含 LSP 和 AST 搜索、inline diff review
数据主控	所有数据存储在本地，不经过第三方
记忆进化	基于 ReMe 的长期记忆系统，Agent 从交互中学习、反思经验、主动服务
定时任务	内置 APScheduler Cron 调度、新闻摘要、心跳签到
桌面应用	Tauri 打包的原生 macOS/Windows 应用，无需安装 Python
语音交互	Whisper 语音输入 / Twilio SIP 语音通道（可选依赖）
MCP 支持	Model Context Protocol 集成（stdio / HTTP / SSE 传输，含 OAuth 2.1）
多层安全	Tool Guard、File Access Guard、Skill Scanner 三层防护 + Web 认证

2. 整体架构

架构总览图

graph TD %% 样式定义 classDef layerFill fill:#fcfcfc,stroke:#333,stroke-width:1.5px,font-weight:bold; classDef componentFill fill:#fff,stroke:#666,stroke-width:1px,font-size:12px; classDef highlightFill fill:#f0f7ff,stroke:#0066cc,stroke-width:1px; %% ==================== 1. 用户交互层 ==================== subgraph UI_LAYER ["用户交互层"] direction LR UI1["Web 控制台 (React)"] --- UI2["桌面应用 (Tauri)"] --- UI3["IM 渠道 (钉钉/飞书)"] --- UI4["API 直接调用 (HTTP/ACP)"] end class UI_LAYER layerFill; class UI1,UI2,UI3,UI4 componentFill; %% ==================== 2. FastAPI 应用层 ==================== subgraph API_LAYER ["FastAPI 应用层 (Port 8088)"] subgraph MID ["中间件层 (横向并排)"] direction LR M1["AuthMiddleware"] --- M2["AgentContextMiddleware"] --- M3["CORSMiddleware"] end subgraph ROUTER ["路由层 (34+ 路由器并排)"] direction LR R1["/api/agent/* /api/chats/*"] --- R2["/api/skills/* /api/providers/*"] --- R3["/api/channels/* /api/cron/*"] --- R4["/api/mcp/* /api/coding-mode/*"] end end class API_LAYER layerFill; class MID,ROUTER highlightFill; class M1,M2,M3,R1,R2,R3,R4 componentFill; %% ==================== 3. 多 Agent 管理层 ==================== subgraph MGR_LAYER ["MultiAgentManager (多 Agent 管理)"] direction LR WS1["Workspace 1 (Agent A)"] --- WS2["Workspace 2 (Agent B)"] --- WS3["Workspace 3 (Agent C)"] --- WS_MORE["..."] end class MGR_LAYER layerFill; class WS1,WS2,WS3,WS_MORE componentFill; %% ==================== 4. Workspace 运行时 ==================== subgraph RUNTIME_LAYER ["Workspace (Agent 运行时)"] direction LR RUN["【Runner 引擎】"] --- MEM["Memory Mgr"] --- CTX["Context Mgr"] --- MCP["MCP Mgr"] --- CHAT["Chat Mgr"] --- CHN["Channel Mgr"] --- CRN["Cron Mgr"] --- TSK["Task Tracker"] end class RUNTIME_LAYER layerFill; class RUN highlightFill; class MEM,CTX,MCP,CHAT,CHN,CRN,TSK componentFill; %% ==================== 5. AI 模型层 ==================== subgraph AI_LAYER ["AI 模型层"] direction LR M_OAI["OpenAI 兼容 API"] --- M_QW["DashScope (千问)"] --- M_GEM["Gemini"] --- M_CLD["Claude"] --- M_LLM["Ollama 本地"] end class AI_LAYER layerFill; class M_OAI,M_QW,M_GEM,M_CLD,M_LLM componentFill; %% ==================== 纵向连接关系 ==================== UI_LAYER --> MID MID --> ROUTER ROUTER --> MGR_LAYER MGR_LAYER --> RUNTIME_LAYER RUNTIME_LAYER --> AI_LAYER %% 颜色美化 style UI_LAYER fill:#f4f5f7,stroke:#7a869a style API_LAYER fill:#eae6ff,stroke:#6554c0 style MGR_LAYER fill:#e3fcef,stroke:#00875a style RUNTIME_LAYER fill:#fffae6,stroke:#ffab00 style AI_LAYER fill:#ffebe6,stroke:#de350b

能力层展开

复制代码

┌──────────────────────────────────────────────────────────┐
│                     能力层                                 │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌───────┐ │
│  │Skills  │ │ Tools  │ │  MCP   │ │Plugins │ │Plan   │ │
│  └────────┘ └────────┘ └────────┘ └────────┘ └───────┘ │
└──────────────────────────────────────────────────────────┘

架构分层

层级	职责	关键组件
用户交互层	多渠道用户接入	Web 控制台、Tauri 桌面端、15+ IM 渠道、API
应用服务层	HTTP 请求路由、中间件、认证	FastAPI app, 34 个路由器, 中间件链
Agent 管理层	多 Agent 生命周期、工作区路由	MultiAgentManager, Workspace, 热重载
Agent 运行时	单 Agent 执行环境	Runner, Memory, Context, MCP, Channel, Cron
能力层	Agent 可调用的扩展能力	Skills, Tools, MCP, Plugins, Plan
模型调用层	多模型提供商抽象	ProviderManager, 15 种模型提供商

3. 技术栈

后端

技术	版本/说明
语言	Python 3.10 - 3.13
Web 框架	FastAPI + Uvicorn
Agent 框架	AgentScope 1.0.20 + AgentScope-Runtime 1.1.6
CLI 框架	Click（懒加载子命令）
包管理	setuptools + uv
配置管理	Pydantic + JSON
数据库	文件系统（workdir）+ 可选 AnalyticDB PostgreSQL
任务调度	APScheduler
浏览器自动化	Playwright (Chromium)
语音	Whisper（可选）
测试	pytest + pytest-asyncio + pytest-cov
代码质量	black, flake8, pre-commit

前端

技术	版本/说明
框架	React 18 + TypeScript 5.8 (strict)
构建	Vite 6
UI 库	Ant Design 5 + @agentscope-ai/design/chat
图标	@agentscope-ai/icons
样式	Less + CSS Modules + antd-style
路由	React Router DOM v7
状态管理	Zustand v5 (persist)
国际化	i18next (6 种语言)
代码编辑器	Monaco Editor (@monaco-editor/react)
图表	@ant-design/plots (AntV/G2)
拖拽	@dnd-kit
Markdown	react-markdown + @ant-design/x-markdown
图表渲染	Mermaid
桌面	Tauri v2 (Rust)
测试	Vitest 4 + Testing Library

文档站

技术	版本/说明
框架	React 18 + TypeScript
构建	Vite 6
样式	Tailwind CSS 4 + shadcn/ui
路由	react-router-dom 7
国际化	i18next
搜索	Fuse.js（本地全文搜索）
动画	Motion (Framer Motion)
代码高亮	rehype-highlight + react-syntax-highlighter
图表	Mermaid

4. 目录结构

bash 复制代码

QwenPawGuide/
├── src/                          # Python 后端源码
│   └── qwenpaw/
│       ├── __init__.py           # 包初始化、环境变量加载
│       ├── __main__.py           # python -m 入口
│       ├── __version__.py        # 版本号
│       ├── constant.py           # 全局常量 (373行)
│       ├── envs.py               # 环境变量管理
│       ├── exceptions.py         # 自定义异常
│       ├── cli/                  # CLI 命令层 (30+ 子命令)
│       │   └── main.py          #    Click 懒加载入口
│       ├── app/                  # 应用服务层
│       │   ├── _app.py          #    FastAPI 应用创建 (733行)
│       │   ├── multi_agent_manager.py  # 多 Agent 管理器 (537行)
│       │   ├── agent_context.py #    Agent 上下文 (ContextVar)
│       │   ├── auth.py          #    Web 认证中间件
│       │   ├── migration.py     #    配置迁移逻辑
│       │   ├── routers/         #    API 路由 (34个)
│       │   ├── runner/          #    Agent 运行引擎
│       │   │   ├── runner.py    #      AgentRunner (36KB, 981行)
│       │   │   ├── command_dispatch.py  # 命令分发
│       │   │   ├── mission_dispatch.py  # 任务模式调度
│       │   │   └── session.py   #      SafeJSONSession 会话管理
│       │   ├── channels/        #    渠道系统 (27个渠道)
│       │   ├── mcp/             #    MCP 协议支持
│       │   ├── crons/           #    定时任务
│       │   └── workspace/       #    Agent 工作区
│       ├── agents/              # Agent 核心
│       │   ├── react_agent.py   #    ReAct 循环核心 (56KB)
│       │   ├── coding_mode_mixin.py  # Coding Mode 混入
│       │   ├── tool_guard_mixin.py   # 工具安全守卫混入
│       │   ├── command_handler.py #  命令处理
│       │   ├── model_factory.py #   模型工厂
│       │   ├── prompt.py        #   系统提示词构建
│       │   ├── hooks.py         #   Agent 生命周期钩子
│       │   ├── context/         #   上下文管理器
│       │   ├── memory/          #   记忆管理器
│       │   ├── mission/         #   Mission Mode 工作流
│       │   ├── tools/           #    工具系统 (19个工具)
│       │   └── skill_system/    #    技能系统
│       ├── providers/           # 模型提供商
│       │   └── provider_manager.py  # 提供商管理器 (71KB)
│       ├── local_models/        # 本地模型管理
│       ├── market/              # 模型市场
│       ├── config/              # 配置管理
│       │   └── config.py        #    配置核心 (74KB)
│       ├── security/            # 安全系统
│       │   ├── tool_guard/      #    命令拦截
│       │   ├── skill_scanner/   #    技能扫描
│       │   └── secret_store.py  #    密钥存储
│       ├── plugins/             # 插件框架
│       │   ├── loader.py        #    插件加载器
│       │   ├── registry.py     #    插件注册表
│       │   └── api.py          #    插件 API
│       ├── backup/              # 备份系统
│       ├── plan/                # 任务计划
│       ├── token_usage/         # Token 用量追踪
│       ├── tauri/               # 桌面集成
│       └── utils/               # 工具函数集
├── console/                     # React 前端控制台
│   ├── src/
│   │   ├── main.tsx            #    应用入口
│   │   ├── App.tsx             #    根组件
│   │   ├── api/                #    API 通信层 (26个模块)
│   │   ├── pages/              #    页面组件
│   │   ├── components/         #    通用组件
│   │   ├── contexts/           #    React Context
│   │   ├── stores/             #    Zustand 状态管理
│   │   ├── layouts/            #    布局组件
│   │   ├── hooks/              #    自定义 Hooks
│   │   ├── plugins/            #    前端插件系统
│   │   ├── locales/            #    国际化 JSON
│   │   ├── styles/             #    全局样式
│   │   └── utils/              #    工具函数
│   ├── src-tauri/              #    Tauri Rust 后端
│   ├── package.json
│   └── vite.config.ts
├── plugins/                     # 插件分发目录
│   ├── bundle/                 #    完整插件 (前后端)
│   │   ├── cloudpaw/           #      CloudPaw 云编排
│   │   └── qwenpaw-pet/        #      桌面宠物
│   └── tool/                   #    工具插件 (纯后端)
│       ├── gpt-image2/         #      GPT Image 2
│       ├── qwen-image/         #      Qwen-Image
│       └── wan27/              #      Wan 2.7 视频生成
├── website/                     # 文档站 (React + Vite + Tailwind)
├── scripts/                     # 构建/安装/打包脚本
├── deploy/                      # Docker 部署配置
├── tests/                       # 测试套件
│   ├── unit/                   #    单元测试
│   ├── integration/            #    集成测试
│   ├── contract/               #    合约测试
│   └── e2e/                    #    端到端测试
├── notes/                       # 学习笔记
├── README.md / README_zh.md     # 多语言 README
├── pyproject.toml               # 项目元数据与依赖
├── setup.py                     # Setuptools 入口
├── Makefile                     # 构建命令
├── docker-compose.yml           # Docker Compose 部署
└── start_server.py              # 快速启动脚本 (开发用)

5. 后端模块详解（Python）

5.1 应用核心 (`app/`)

入口文件 : src/qwenpaw/app/_app.py

应用核心是整个后端的控制中心，负责 FastAPI 服务器的创建、生命周期管理、路由注册和中间件配置。

关键类与函数

类/函数	文件	职责
`DynamicMultiAgentRunner`	`_app.py`	动态多 Agent 运行器，根据请求中的 `X-Agent-Id` 头路由到正确的 Workspace Runner
`lifespan()`	`_app.py`	FastAPI 生命周期管理器，分为 Phase 1（快速同步初始化）和 Phase 2（后台异步初始化）
`MultiAgentManager`	`multi_agent_manager.py`	多 Agent 管理器，支持延迟加载、生命周期管理、热重载和平行启动
`Workspace`	`workspace/workspace.py`	工作区实例，封装单个 Agent 的完整运行环境（Runner、ChannelManager、MCPManager、TaskTracker）
`AgentRunner`	`runner/runner.py`	Agent 运行器，继承 `agentscope_runtime.Runner`，处理查询、命令分发、技能注入、计划模式、任务模式

启动流程 (lifespan)

scss 复制代码

阶段1 (同步, <100ms)
├── cleanup_startup_restore_artifacts()
├── auto_register_from_env() (自动注册认证)
├── 遥测初始化
└── 旧版数据迁移

阶段2 (后台异步)
├── multi_agent_manager.start_all_configured_agents()
│   └── 并行启动每个 Agent 的 Workspace
│       ├── ChannelManager 初始化
│       ├── MCPClientManager 初始化
│       └── AgentRunner 初始化
├── 本地模型恢复
├── 加载插件
│   ├── 加载插件提供者
│   ├── 注册控制命令
│   └── 执行启动钩子
├── 注册模型提供商
└── 启动审批服务

关闭流程
├── 插件关闭钩子
├── 停止本地模型服务器
├── 停止所有 Agent
├── 停止 Token 用量管理器
└── 停止浏览器实例

路由注册

路由前缀	用途
`/api`	主 API 路由（agents、MCP、tools、skills、plugins、channels、workspace、plan、providers）
`/api/agent`	AgentApp 流式任务路由
`/api/agents/{agentId}/*`	Agent 作用域路由（chats、sessions）
`/api/approval`	审批路由
`/api/coding-mode`	Coding Mode 路由
`/voice/*`	Twilio 语音通道
`/`	SPA 回退路由

MultiAgentManager (`multi_agent_manager.py`, 537行)

管理多个 Agent 工作区的生命周期：

方法	说明
`get_or_create_workspace(agent_id)`	懒加载获取/创建工作区，并发去重
`reload_agent(agent_id)`	零停机热重载（原子交换旧实例）
`start_all_configured_agents()`	并行启动所有已启用的 Agent
`stop_all_agents()`	优雅关闭所有 Agent

热重载流程：加锁 → 创建新 Workspace → 原子交换 → 解锁 → 优雅停止旧实例（60s 超时）

Workspace (`workspace/workspace.py`, 467行)

完整的单 Agent 运行时容器，包含所有服务的声明式注册：

优先级	服务	说明
10	`runner`	AgentRunner 实例创建
20	`memory_manager`	记忆管理器
20	`context_manager`	上下文管理器
20	`mcp_manager`	MCP 客户端管理器
20	`chat_manager`	对话管理器
25	`runner.start()`	Runner 启动
30	`channel_manager`	渠道管理器
40	`cron_manager`	定时任务管理器
50	`agent_config_watcher`	Agent 配置监听
51	`mcp_config_watcher`	MCP 配置监听

Agent 上下文 (`agent_context.py`, 201行)

使用 Python ContextVar 实现的请求级上下文传递：

变量/函数	说明
`_current_agent_id`	当前请求的 Agent ID
`_current_session_id`	当前会话 ID
`_current_root_session_id`	根会话 ID（跨会话审批用）
`get_agent_for_request()`	从 HTTP 头/状态/配置解析 Agent 工作区
`get_coding_dir()`	获取活跃的编码项目目录

关键文件清单

文件	职责
`_app.py`	FastAPI 应用创建、生命周期、路由注册
`multi_agent_manager.py`	多 Agent 工作区管理
`workspace/workspace.py`	Workspace 定义与初始化
`runner/runner.py`	Agent 查询处理核心
`runner/command_dispatch.py`	命令分发（`/` 命令）
`runner/mission_dispatch.py`	任务模式（`/mission`）调度
`runner/session.py`	SafeJSONSession 会话管理
`agent_context.py`	Agent 上下文（当前 Agent ID、Session ID）
`auth.py`	Web 认证中间件
`migration.py`	配置迁移逻辑

5.2 CLI 命令行 (`cli/`)

入口文件 : src/qwenpaw/cli/main.py

CLI 基于 Click 框架构建，通过 LazyGroup 实现子命令的延迟加载，显著加快 CLI 启动速度。

核心类

类/函数	文件	说明
`LazyGroup(click.Group)`	`main.py`	懒加载 Click 命令组，子命令只在首次调用时加载
`main_cli()`	`main.py`	顶级命令入口，兼容 `qwenpaw` 和 `copaw` 两个命令名

子命令一览 (30+)

命令	文件	功能
`init`	`init_cmd.py`	交互式/默认初始化项目配置
`app`	`app_cmd.py`	启动 FastAPI 应用服务器
`agents`	`agents_cmd.py`	Agent 管理（创建、列表、删除）
`channels`	`channels_cmd.py`	通道配置管理
`chats`	`chats_cmd.py`	管理对话
`cron`	`cron_cmd.py`	定时任务管理（增删改查）
`skills`	`skills_cmd.py`	技能管理（安装、列表、启用/禁用）
`models`	`providers_cmd.py`	模型提供者管理
`plugin`	`plugin_commands.py`	插件管理
`daemon`	---	守护进程
`doctor`	`doctor_cmd.py`	诊断工具
`update`	`update_cmd.py`	更新检查
`auth`	`auth_cmd.py`	认证管理
`desktop`	`desktop_cmd.py`	桌面应用启动
`acp`	`acp_cmd.py`	ACP 代理管理
`task`	---	任务管理
`shutdown`	`shutdown_cmd.py`	关闭运行中的服务
`clean`	`clean_cmd.py`	清理工具
`env`	`env_cmd.py`	环境变量管理
`uninstall`	`uninstall_cmd.py`	卸载

5.3 配置系统 (`config/`)

核心文件 : src/qwenpaw/config/config.py (74KB)

配置系统基于 Pydantic 模型，支持 JSON 配置文件的加载、验证、迁移和缓存。

关键配置模型

模型	说明
`Config`	根配置（config.json），包含 channels、MCP、tools、agents、security、acp、plugins
`AgentProfileConfig`	Agent 完整配置（workspace/agent.json），包含所有 Agent 级别设置
`AgentsConfig`	多 Agent 引用管理（active_agent、agent_order、profiles）
`ChannelConfig`	所有通道配置的聚合
`MCPConfig`	MCP 客户端配置
`ToolsConfig`	内置工具配置
`SecurityConfig`	安全配置（tool_guard、file_guard、skill_scanner）
`AgentsRunningConfig`	Agent 运行时参数（max_iters、LLM 重试策略、并发控制等）
`HeartbeatConfig`	心跳检查配置

配置加载流程

scss 复制代码

config.json (根配置)
  └── agents.profiles["default"].workspace_dir
        └── workspace/agent.json (Agent 配置，mtime 缓存)

load_config() --- 加载根 config.json，使用文件锁保证安全读写
load_agent_config(agent_id) --- 加载 Agent 完整配置，使用 mtime 缓存优化
save_agent_config(agent_id, config) --- 保存 Agent 配置并失效缓存

5.4 Agent 引擎 (`agents/`)

核心文件 : src/qwenpaw/agents/react_agent.py (56KB)

Agent 引擎基于 AgentScope 的 ReActAgent 构建，集成了工具、技能、记忆管理和安全防护。

关键类

类	文件	职责
`QwenPawAgent`	`react_agent.py`	主 Agent 类，继承 ReActAgent，集成所有能力
`CodingModeMixin`	`coding_mode_mixin.py`	Coding Mode 混入（LSP、AST 搜索等）
`ToolGuardMixin`	`tool_guard_mixin.py`	工具安全守卫混入
`CommandHandler`	`command_handler.py`	命令处理器（`/` 命令路由）
`ModelFactory`	`model_factory.py`	模型工厂（创建 LLM 实例和 formatter）

Agent 初始化流程

从 agent.json 加载配置
创建 LLM 模型和 formatter
构建系统提示词（AGENTS.md、SOUL.md、PROFILE.md）
注册内置工具（execute_shell_command、read_file、write_file 等 20+ 个）
注册 MCP 工具（来自 MCP 客户端）
注册技能内联工具（materialize_skill）
初始化记忆管理器（ReMeLight / ADBPG）
初始化上下文管理器（LightContextManager）
应用安全策略（Tool Guard 过滤）

命令系统

命令	功能
`/skill <name>`	激活指定技能
`/tool <name>`	查看工具详情
`/help`	显示帮助信息
`/reset`	重置对话上下文
`/system`	显示系统信息
`/memory`	管理记忆
`/plan`	计划模式
`/mission`	任务模式

子模块

模块	职责
`agents/command_handler.py`	命令处理器（`/` 命令路由）
`agents/context/`	上下文管理器（LightContextManager，支持压缩和剪枝）
`agents/memory/`	记忆管理器（ReMeLight、ADBPG）
`agents/model_factory.py`	模型工厂（创建 LLM 实例和 formatter）
`agents/prompt.py`	系统提示词构建
`agents/hooks.py`	Agent 生命周期钩子
`agents/mission/`	Mission Mode（编排式工作流执行）

Runner 执行流程

scss 复制代码

用户查询
  → query_handler() / stream_query()
    → 创建/获取 Session
    → 检查是否为 / 命令 → run_command_path()
    → 检查是否为 /mission → maybe_handle_mission_command()
    → 检查 /plan → PlanNotebook
    → 检查 /skill → 技能注入
    → 构建上下文（记忆、系统提示、对话历史）
    → 创建 QwenPawAgent
    │   ├── 构建系统提示词
    │   ├── 注册工具（内置 + MCP + 技能）
    │   ├── 加载记忆
    │   └── 加载上下文
    → ReAct 循环:
        ├── LLM 推理 (think)
        ├── 工具调用 (act) ← Tool Guard 检查
        ├── 结果处理 (observe)
        └── 循环或终止
    → 保存记忆
    → 返回响应

5.5 技能系统 (`agents/skill_system/`)

核心文件 : src/qwenpaw/agents/skill_system/hub.py

技能系统允许用户扩展 Agent 的能力。技能以 SKILL.md 文件定义，包含参考文档（references）和脚本（scripts）。

技能来源

来源	标识	说明
ClawHub	`clawhub`	官方技能市场
GitHub	`github`	GitHub 仓库中的技能目录
LobeHub	`lobehub`	LobeHub 技能市场
ModelScope	`modelscope`	魔搭社区技能
Aliyun	`aliyun`	阿里云 AgentExplorer
skills.sh	`skills-sh`	skills.sh 平台
SkillsMP	`skillsmp`	SkillsMP 平台

关键函数

函数	职责
`install_skill_from_hub()`	从 Hub 安装技能到工作区
`search_hub_skills()`	搜索 Hub 技能
`import_pool_skill_from_hub()`	导入技能到共享技能池
`ensure_skills_initialized()`	确保默认技能已初始化
`resolve_effective_skills()`	解析当前通道的有效技能列表

技能目录结构

bash 复制代码

workspaces/<agent>/skills/<skill_name>/
├── SKILL.md          # 技能定义（frontmatter + markdown body）
├── references/       # 参考文档
└── scripts/          # 技能脚本

技能生命周期

bash 复制代码

发现 → 扫描安全 → 安装 → 注册 → Agent 激活(/skill <name>) → 执行 → 卸载

内置技能示例

alicloud_cli --- 阿里云 CLI 操作
terraform-cli-setup --- Terraform 基础设施即代码
terraform-skill --- Terraform 最佳实践

5.6 工具系统 (`agents/tools/`)

内置工具是 Agent 执行任务的核心手段。所有工具在 ToolsConfig 中管理，可在 Console 中启用/禁用。共 19 个工具文件。

内置工具清单

工具名	文件	功能	默认启用
`execute_shell_command`	`shell.py`	执行 shell 命令	✅
`read_file`	`file_io.py`	读取文件内容	✅
`write_file`	`file_io.py`	写入文件	✅
`edit_file`	`file_io.py`	编辑文件（查找替换）	✅
`grep_search`	`file_search.py`	文件内容搜索	✅
`glob_search`	`file_search.py`	文件名模式匹配	✅
`browser_use`	`browser.py` (160KB)	Playwright 驱动的浏览器自动化（浏览、点击、填表）	✅
`desktop_screenshot`	`screenshot.py`	桌面截图	✅
`view_image`	`image_analysis.py`	加载图片到 LLM 上下文	✅
`view_video`	---	加载视频到 LLM 上下文	✅
`send_file_to_user`	---	发送文件给用户	✅
`get_current_time`	---	获取当前时间	✅
`set_user_timezone`	---	设置用户时区	✅
`get_token_usage`	---	获取 Token 用量	✅
`list_agents`	`agent_management.py`	列出配置的 Agent	✅
`chat_with_agent`	`agent_management.py`	与其他 Agent 对话	✅
`submit_to_agent`	`agent_management.py`	提交后台任务给其他 Agent	✅
`check_agent_task`	`agent_management.py`	检查后台任务状态	✅
`delegate_external_agent`	---	委托给外部 ACP Agent	❌

其他工具文件

工具	文件	说明
LSP	`lsp.py`	Language Server Protocol 代码分析
AST 搜索	`ast_search.py`	代码 AST 结构化搜索
Git	`git.py`	Git 操作
代码执行	`code_execution.py`	Python/Node 沙箱执行
知识库	`knowledge.py`	RAG 知识检索
Web 搜索	`web_search.py`	联网搜索
文档解析	`document.py`	PDF/Office 文档解析

5.7 模型提供者 (`providers/`、`market/`、`local_models/`)

ProviderManager

核心文件: src/qwenpaw/providers/provider_manager.py (71KB)

单例模式管理所有模型提供者
支持云模型和本地模型
动态注册/注销提供者
模型能力缓存

支持的云模型提供商

提供商	类型
OpenAI (兼容 API)	云端
DashScope (通义千问)	云端
Google Gemini	云端
Anthropic Claude	云端
OpenRouter	云端代理
DeepSeek	云端
Moonshot (月之暗面)	云端
ZhipuAI (智谱)	云端
Baidu Qianfan	云端
ByteDance Volcengine	云端

本地模型支持

后端	说明
llama.cpp	跨平台本地推理，Web UI 一键下载
Ollama	需提前安装 Ollama 服务
LM Studio	需提前安装 LM Studio
Local HuggingFace	本地 HuggingFace 模型

模型市场

提供者	路径	说明
DashScope（通义千问）	`providers/`	阿里云模型服务
OpenAI	`providers/`	OpenAI API 兼容
Gemini	`providers/`	Google GenAI
ModelScope	`market/providers/modelscope.py`	魔搭社区模型
Aliyun AgentExplorer	`market/providers/aliyun.py`	阿里云 Agent 市场
Volcano Engine	`market/providers/`	火山引擎模型

5.8 MCP 协议支持 (`app/mcp/`)

核心文件 : src/qwenpaw/app/mcp/manager.py

支持 Model Context Protocol (MCP)，允许 Agent 连接外部工具服务。

关键类

类	职责
`MCPClientManager`	MCP 客户端生命周期管理（初始化、热重载、关闭）
`HttpStatefulClient`	HTTP/SSE 传输的 MCP 客户端
`StdIOStatefulClient`	标准输入输出传输的 MCP 客户端

支持的传输方式

stdio --- 通过进程标准输入输出通信
streamable_http --- 通过 HTTP 流式传输
sse --- 通过 Server-Sent Events

配置示例

json 复制代码

{
  "mcp": {
    "clients": {
      "tavily_search": {
        "name": "tavily_mcp",
        "enabled": true,
        "command": "npx",
        "args": ["-y", "tavily-mcp@latest"],
        "env": {"TAVILY_API_KEY": "your-key"}
      }
    }
  }
}

5.9 安全模块 (`security/`)

多层安全防护机制，保护用户数据和系统安全。

三层防护

层	路径	功能
Tool Guard	`security/tool_guard/engine.py`	拦截危险 shell 命令（rm -rf /、fork bomb、反弹 shell 等），支持自定义规则
File Guard	配置项 `security.file_guard`	限制 Agent 访问敏感路径（~/.ssh、密钥文件、系统目录）
Skill Scanner	`security/skill_scanner/scanner.py`	安装技能前自动扫描，检测 prompt 注入、命令注入、硬编码密钥、数据外泄等风险

审批级别

级别	说明
`STRICT`	所有工具都需要审批
`SMART`	低风险工具自动允许
`AUTO`	仅受保护的工具触发守卫（默认）
`OFF`	关闭守卫

Web 认证

可选登录保护（QWENPAW_AUTH_ENABLED=true）
默认允许 localhost 无认证访问（127.0.0.1、::1）

密钥存储

类	文件	说明
`SecretStore`	`secret_store.py`	API 密钥安全存储

5.10 通道系统 (`app/channels/`)

基类 : base.py (61KB)

通道系统将不同即时通讯平台的消息统一转换为 Agent 可处理的格式。支持 15+ 种即时通讯平台。

支持的通道

通道	配置类	模块	协议/依赖
Console	`ConsoleConfig`	`console.py`	Web 控制台（默认开启）
DingTalk	`DingTalkConfig`	`dingtalk.py`	dingtalk-stream，支持流式卡片
Feishu/Lark	`FeishuConfig`	`feishu.py`	lark-oapi，支持 CardKit 流式卡片
WeChat	`WeChatConfig`	`wechat.py`	itchat/gewechat iLink Bot
WeCom	`WecomConfig`	`wecom.py`	wecom-aibot-python-sdk
QQ	`QQConfig`	`qq.py`	OneBot 协议
Discord	`DiscordConfig`	`discord.py`	discord.py
Telegram	`TelegramConfig`	`telegram.py`	python-telegram-bot，支持流式输出
iMessage	`IMessageChannelConfig`	`imessage.py`	AppleScript + SQLite (macOS)
Matrix	`MatrixConfig`	`matrix.py`	matrix-nio
MQTT	`MQTTConfig`	`mqtt.py`	paho-mqtt 物联网协议
Mattermost	`MattermostConfig`	`mattermost.py`	mattermost-driver
OneBot	`OneBotConfig`	---	OneBot v11（NapCat/go-cqhttp）
Voice	`VoiceChannelConfig`	---	Twilio 语音通道
SIP	`SIPChannelConfig`	`sip.py`	pyVoIP/LiveKit/pjsua2
XiaoYi	`XiaoYiConfig`	`xiaoyi.py`	华为小艺 A2A 协议

关键类

类	文件	职责
`ChannelManager`	`channels/manager.py`	通道管理器，注册、初始化、管理所有通道
`BaseChannel`	`channels/base.py`	通道抽象基类
`ChannelRegistry`	`channels/registry.py`	通道注册中心

基类接口

python 复制代码

class BaseChannel:
    async def start()          # 启动渠道监听
    async def stop()           # 停止渠道
    async def send_message()   # 发送消息
    async def handle_message() # 处理接收到的消息

5.11 定时任务 (`app/crons/`)

基于 APScheduler 的定时任务系统，支持 Cron 表达式调度。

功能

Cron 任务: 按 Cron 表达式定时执行 Agent 查询
心跳任务: 定期的 Agent 状态检查和摘要（HEARTBEAT.md）
ReMe Dream : 定时记忆优化任务（reme_light_memory_config.dream_cron）
隔离执行: Cron 任务在无上下文环境中独立执行，节省 Token

CLI 命令

bash 复制代码

qwenpaw cron add "0 8 * * *" "每日新闻摘要"
qwenpaw cron list
qwenpaw cron delete <id>

5.12 插件系统 (`plugins/`)

插件系统允许第三方开发者扩展 QwenPaw 的功能。

关键类

类	职责
`PluginLoader`	从插件目录加载插件
`PluginRegistry`	插件注册中心（管理提供者、工具、钩子、控制命令）
`RuntimeHelpers`	运行时辅助工具（注入 ProviderManager 等依赖）

插件能力

模型提供者: 注册新的 LLM 提供商
工具: 注册新的工具函数
启动钩子: 在应用启动时执行自定义逻辑
关闭钩子: 在应用关闭时执行清理逻辑
控制命令 : 注册 /<command> 格式的用户命令
HTTP 应用: 注册自定义 FastAPI 子应用

5.13 备份模块 (`backup/`)

提供配置和数据的备份与恢复能力，支持安全交换（safe swap）机制。

5.14 计划模式 (`plan/`)

计划模式（/plan 命令）使 Agent 在执行复杂任务前先制定计划和待办事项。

关键类

类	职责
`PlanNotebook`	计划笔记本（来自 AgentScope）
`SimplePlanToHint`	将计划转换为 Agent 提示
`plan_to_response()`	将计划转换为前端可渲染的格式
`broadcast_plan_update()`	通过 SSE 广播计划更新

5.15 Token 用量追踪 (`token_usage/`)

记录每次 LLM 调用的 Token 消耗
后台批量写入，避免阻塞请求
通过 get_token_usage 工具让 Agent 可查询用量

5.16 工具函数 (`utils/`)

通用工具函数集合：

logging.py --- 日志系统设置
telemetry.py --- 匿名遥测数据收集
system_info.py --- 系统信息摘要
startup_display.py --- 启动信息展示

6. 前端模块详解（React + Tauri）

入口文件 : console/src/main.tsx

6.1 技术栈

类别	技术
框架	React 18 + TypeScript 5.8 (strict)
构建工具	Vite 6
UI 组件库	Ant Design 5 + @agentscope-ai/design/chat
图标	@agentscope-ai/icons
状态管理	Zustand 5
路由	react-router-dom 7
国际化	i18next + react-i18next (6 种语言)
代码编辑器	Monaco Editor (@monaco-editor/react)
图表	@ant-design/plots (AntV/G2)
拖拽	@dnd-kit
Markdown	react-markdown + @ant-design/x-markdown
图表渲染	Mermaid
桌面壳	Tauri 2.x (Rust)
测试	Vitest 4 + Testing Library

6.2 目录结构

bash 复制代码

console/src/
├── main.tsx              # 应用入口
├── App.tsx               # 根组件（路由、主题、认证、插件）
├── api/                  # API 通信层
│   ├── index.ts          #   统一导出 api 对象
│   ├── request.ts        #   通用 fetch 封装
│   ├── config.ts         #   API URL 构建
│   ├── authHeaders.ts    #   认证头构建
│   ├── modules/          #   26 个业务 API 模块
│   │   ├── agents.ts
│   │   ├── auth.ts
│   │   ├── channels.ts
│   │   ├── chats.ts
│   │   ├── mcp.ts
│   │   ├── providers.ts
│   │   ├── skills.ts
│   │   └── ...
│   └── types/            #   TypeScript 类型定义
├── components/           # 通用组件 (15个)
│   ├── AgentSelector/    #   Agent 选择器
│   ├── ChatMessage/      #   聊天消息渲染
│   ├── SkillCard/        #   技能卡片
│   └── ...
├── contexts/             # React Context
│   ├── ThemeContext.tsx   #   主题（亮/暗）
│   └── ApprovalContext.tsx #  审批状态
├── hooks/                # 自定义 Hooks
│   ├── useAppMessage.ts  #   消息通知
│   └── ...
├── layouts/
│   └── MainLayout/       #   主布局（Sidebar + Header + Content）
├── pages/                # 页面组件
│   ├── Chat/             #   聊天页面（核心）
│   ├── Agent/            #   Agent 管理
│   │   ├── Config/       #     Agent 配置
│   │   ├── Skills/       #     技能管理
│   │   ├── Tools/        #     工具管理
│   │   └── ...
│   ├── Coding/           #   编码 IDE 页面
│   ├── Control/          #   控制面板
│   │   ├── Channels/     #     通道管理
│   │   ├── Cron/         #     定时任务管理
│   │   ├── MCP/          #     MCP 管理
│   │   └── Plugins/      #     插件管理
│   ├── Settings/         #   系统设置
│   │   ├── Models/       #     模型配置
│   │   ├── Environment/  #     环境变量
│   │   └── ...
│   └── Login/            #   登录页
├── plugins/
│   └── PluginContext.tsx  #   前端插件系统
├── stores/               # Zustand 状态管理
│   ├── agentStore.ts     #   Agent 状态
│   ├── chatStore.ts      #   聊天状态
│   └── ...
├── locales/              # 国际化 (6种语言)
├── styles/               # 全局样式
└── utils/                # 工具函数

6.3 核心组件与页面

主应用 (`App.tsx`)

ThemeProvider > PluginProvider > AppInner
路由结构：/login → 登录页，/* → MainLayout
AuthGuard: 前置认证守卫，检查 QWENPAW_AUTH_ENABLED
支持多语言（zh/en/ja/ru/id），从后端同步语言偏好
主题色 #FF7F16（橙色）

页面清单

页面	路径	功能
Chat	`/`	主聊天界面，多会话管理
Agent Config	`/agents/:id/config`	Agent 配置（模型、参数等）
Agent Skills	`/agents/:id/skills`	技能管理（安装、启用/禁用）
Agent Tools	`/agents/:id/tools`	工具启用/禁用管理
Channels	`/control/channels`	通信通道配置
Cron	`/control/cron`	定时任务管理
MCP	`/control/mcp`	MCP 客户端管理
Plugins	`/control/plugins`	插件管理
Models	`/settings/models`	模型提供者配置
Environment	`/settings/environment`	环境变量管理
Coding Mode	`/coding-mode`	三栏 IDE（文件树、编辑器、Git 面板）
Login	`/login`	登录页

运行模式

模式	入口	说明
Web	`index.html`	浏览器中运行
Tauri 桌面	`tauri.html`	使用 `BackendReadyGate` 等待本地后端就绪

6.4 状态管理

使用 Zustand 进行全局状态管理：

Store	用途
`agentStore`	Agent 选择、列表、最近聊天 ID（双存储：sessionStorage + localStorage）
`chatStore`	聊天会话、消息列表
`codingModeStore`	编码模式 IDE 状态
`codingTabsStore`	编码标签页管理
`codeFileCacheStore`	代码文件缓存
其他 stores	主题、通道状态等

6.5 API 层

基于 axios 的 HTTP 客户端
统一请求/响应拦截器
API Token 认证支持
自动处理 /api 前缀和 baseURL
26 个业务 API 模块聚合为统一 api 对象

6.6 Tauri 桌面应用

配置文件 : console/src-tauri/tauri.conf.json

基于 Tauri 2.x 构建原生桌面应用
支持 Windows（NSIS 安装器）和 macOS
窗口尺寸：1280×800（最小 960×600）
CSP 安全策略：限制脚本、样式、连接源
捆绑 Python 后端到桌面应用中（无需手动安装 Python）
支持简体中文、英文、印尼语、日语、俄语、葡萄牙语安装界面

7. 文档站 (`website/`)

目录 : website/

项目官方文档站（qwenpaw.agentscope.io/），基于 React + Vite 构建。

技术栈

类别	技术
框架	React 18 + TypeScript
构建	Vite 6
样式	Tailwind CSS 4 + shadcn/ui
路由	react-router-dom 7
国际化	i18next
搜索	Fuse.js（本地全文搜索）
动画	Motion (Framer Motion)
代码高亮	rehype-highlight + react-syntax-highlighter
图表	Mermaid

文档内容

涵盖 Quick Start、Console、Models、Channels、Skills、Plugins、MCP、Memory、Context、CLI、FAQ 等完整文档。

8. 插件系统详解

插件分类

类型	目录	说明	示例
bundle	`plugins/bundle/`	前后端完整插件	CloudPaw, QwenPaw Pet
tool	`plugins/tool/`	纯后端工具注册	GPT Image 2, Qwen-Image, Wan 2.7

插件注册模式

每个插件包含：

plugin.json --- 声明 id、版本、入口点、依赖、最低版本
入口 Python 文件 --- 包含 Plugin 类，实现 register(self, api) 方法
模块级实例 --- plugin = MyPlugin() 导出

Plugin API

python 复制代码

class PluginApi:
    def register_startup_hook(callback, priority)     # 启动钩子
    def register_shutdown_hook(callback, priority)    # 关闭钩子
    def register_tool(name, func, config_schema)      # 注册工具
    def register_http_router(router)                  # 注册 HTTP 路由

已发布插件

插件	类型	版本	功能
CloudPaw	bundle	0.0.2	阿里云部署编排、多 Agent 协作、Terraform 集成
QwenPaw Pet	bundle	0.1.1	桌面宠物，实时展示 Agent 状态
GPT Image 2	tool	1.1.1	OpenAI 图像生成/编辑
Qwen-Image	tool	1.0.0	通义千问图像生成/编辑 (10 种模型)
Wan 2.7	tool	1.0.0	阿里云视频生成（文生/图生/参考生）

9. API 接口参考

所有 API 路由挂载在 /api/ 路径下。

核心 API 模块

路径前缀	模块	说明
`/api/agent/*`	Agent 管理	Agent 创建、配置、监控
`/api/agents/{agentId}/*`	Agent 作用域	Agent 级 chats、sessions
`/api/chats/*`	聊天	会话创建、消息发送、流式响应
`/api/skills/*`	技能	技能发现、安装、管理
`/api/providers/*`	模型提供商	提供商注册、模型列表
`/api/channels/*`	渠道	渠道配置、状态管理
`/api/cron-jobs/*`	定时任务	Cron 作业管理
`/api/mcp/*`	MCP	Model Context Protocol 集成
`/api/workspace/*`	工作区	工作区文件浏览、操作
`/api/auth/*`	认证	登录、注册、Token 管理
`/api/plugins/*`	插件	插件安装、管理
`/api/backups/*`	备份	数据备份与恢复
`/api/coding-mode/*`	编码模式	IDE 功能 API
`/api/git/*`	Git	Git 操作
`/api/token-usage/*`	Token 用量	用量统计
`/api/approval/*`	审批	工具调用审批
`/api/timezone`	时区	用户时区同步
`/api/console/*`	控制台	控制台管理

请求认证

makefile 复制代码

Authorization: Bearer <token>
X-Agent-Id: <agent_id>

流式响应 (SSE)

聊天接口支持 Server-Sent Events 流式响应，事件类型包括：

text --- 文本内容
tool_call --- 工具调用开始
tool_result --- 工具调用结果
error --- 错误信息
done --- 完成

10. 关键类与函数说明

10.1 入口与初始化

符号	位置	签名	说明
`qwenpaw.__init__`	`__init__.py`	---	加载持久化环境变量，设置日志
`qwenpaw.__main__`	`__main__.py`	---	`python -m qwenpaw` 入口，委托给 CLI
`VERSION`	`__version__.py`	`str`	版本字符串 `"1.1.10b1"`
`WORKING_DIR`	`constant.py`	`Path`	工作目录路径
`PLUGIN_DIRS`	`constant.py`	`list[Path]`	插件搜索路径列表
`DEFAULT_PORT`	`constant.py`	`int`	默认端口 `8088`

10.2 应用核心

符号	位置	签名	说明
`AgentApp`	`app/_app.py`	`AgentScope Runtime App`	核心 AgentScope 应用实例
`DynamicMultiAgentRunner`	`app/_app.py`	`class`	动态路由到对应 Agent Runner
`DynamicMultiAgentRunner.stream_query()`	`app/_app.py`	`async def stream_query(query, headers) -> AsyncGenerator`	流式查询入口
`DynamicMultiAgentRunner.query_handler()`	`app/_app.py`	`async def query_handler(query, headers) -> dict`	同步查询入口
`lifespan()`	`app/_app.py`	`async def lifespan(app: FastAPI) -> AsyncContextManager`	应用生命周期管理
`create_app()`	`app/_app.py`	`def create_app() -> FastAPI`	创建 FastAPI 应用实例

10.3 多 Agent 管理

符号	位置	签名	说明
`MultiAgentManager`	`app/multi_agent_manager.py`	`class`	多 Agent 生命周期管理
`MultiAgentManager.get_or_create_workspace()`	`app/multi_agent_manager.py`	`async def get_or_create_workspace(agent_id) -> Workspace`	懒加载获取工作区
`MultiAgentManager.reload_agent()`	`app/multi_agent_manager.py`	`async def reload_agent(agent_id)`	零停机热重载
`MultiAgentManager.start_all_configured_agents()`	`app/multi_agent_manager.py`	`async def start_all_configured_agents()`	并行启动所有 Agent

10.4 Workspace

符号	位置	签名	说明
`Workspace`	`app/workspace/workspace.py`	`class`	Agent 运行时容器 (467行)
`Workspace.start()`	`app/workspace/workspace.py`	`async def start()`	按优先级顺序启动所有服务
`Workspace.stop()`	`app/workspace/workspace.py`	`async def stop()`	按逆序关闭所有服务
`Workspace.set_reusable_components()`	`app/workspace/workspace.py`	`def set_reusable_components(old)`	从旧实例注入可复用组件（热重载用）

10.5 Agent Runner

符号	位置	签名	说明
`AgentRunner`	`app/runner/runner.py`	`class`	Agent 执行引擎
`AgentRunner.query_handler()`	`app/runner/runner.py`	`async def query_handler(query, session_id) -> dict`	处理用户查询
`AgentRunner.stream_query()`	`app/runner/runner.py`	`async def stream_query(query, session_id) -> AsyncGenerator`	流式处理查询
`AgentRunner.stop_query()`	`app/runner/runner.py`	`async def stop_query(session_id)`	停止查询
`Session`	`app/runner/session.py`	`class`	SafeJSONSession 会话管理
`TaskTracker`	`app/runner/task_tracker.py`	`class`	异步任务追踪

10.6 Agent 核心

符号	位置	签名	说明
`QwenPawAgent`	`agents/react_agent.py`	`class`	ReAct 循环 Agent (56KB)
`QwenPawAgent.run()`	`agents/react_agent.py`	`async def run(query) -> str`	执行推理-行动循环
`CodingModeMixin`	`agents/coding_mode_mixin.py`	`class`	Coding Mode 混入
`ToolGuardMixin`	`agents/tool_guard_mixin.py`	`class`	工具安全守卫混入
`CommandHandler`	`agents/command_handler.py`	`class`	命令处理
`ModelFactory`	`agents/model_factory.py`	`class`	模型工厂

10.7 渠道系统

符号	位置	签名	说明
`BaseChannel`	`app/channels/base.py`	`class`	渠道抽象基类 (61KB)
`ChannelManager`	`app/channels/manager.py`	`class`	渠道生命周期管理
`ChannelRegistry`	`app/channels/registry.py`	`class`	渠道注册中心

10.8 安全系统

符号	位置	签名	说明
`ToolGuard`	`security/tool_guard/`	`class`	命令安全检查
`SkillScanner`	`security/skill_scanner/`	`class`	技能安全扫描
`SecretStore`	`security/secret_store.py`	`class`	密钥安全存储

10.9 MCP 系统

符号	位置	签名	说明
`MCPClientManager`	`app/mcp/manager.py`	`class`	MCP 客户端生命周期管理
`HttpStatefulClient`	`app/mcp/manager.py`	`class`	HTTP/SSE 传输 MCP 客户端
`StdIOStatefulClient`	`app/mcp/manager.py`	`class`	stdio 传输 MCP 客户端

10.10 插件系统

符号	位置	签名	说明
`PluginLoader`	`plugins/loader.py`	`class`	插件加载器
`PluginRegistry`	`plugins/registry.py`	`class`	插件注册中心
`PluginApi`	`plugins/api.py`	`class`	插件 API 接口
`RuntimeHelpers`	`plugins/`	`class`	运行时辅助工具

10.11 前端核心

符号	位置	说明
`App`	`console/src/App.tsx`	根组件：路由、主题、认证、插件
`MainLayout`	`console/src/layouts/MainLayout/index.tsx`	主布局：Sidebar + Header + Content
`api`	`console/src/api/index.ts`	统一 API 对象（26 个模块聚合）
`useAgentStore`	`console/src/stores/agentStore.ts`	Agent 状态管理 Hook
`ChatPage`	`console/src/pages/Chat/`	核心聊天页面

11. 依赖关系图

11.1 后端模块依赖

scss 复制代码

CLI (click)
  │
  ├──► app (FastAPI)
  │      ├──► routers (34 个 API 路由)
  │      ├──► runner (AgentRunner)
  │      │      └──► agents/react_agent (QwenPawAgent / ReActAgent)
  │      │             ├──► providers (模型调用)
  │      │             ├──► agents/tools (工具系统)
  │      │             ├──► agents/skill_system (技能系统)
  │      │             ├──► agents/context (上下文管理)
  │      │             └──► agents/memory (记忆管理)
  │      ├──► channels (27 个渠道)
  │      ├──► mcp (MCP 协议)
  │      ├──► crons (定时任务)
  │      ├──► workspace (Workspace)
  │      └──► multi_agent_manager (MultiAgentManager)
  │
  ├──► config (配置管理)
  ├──► providers (模型提供商管理)
  ├──► local_models (本地模型管理)
  ├──► market (模型市场)
  ├──► security (安全系统)
  ├──► plugins (插件框架)
  ├──► backup (备份系统)
  ├──► plan (计划模式)
  ├──► token_usage (Token 用量)
  └──► utils (工具函数)

11.2 前后端通信

11.3 核心外部依赖

ini 复制代码

QwenPaw
├── agentscope >= 1.0.20          # Agent 框架
│   └── ReActAgent (agent 基类)
├── agentscope-runtime >= 1.1.6   # 运行时框架
│   ├── FastAPI App (AgentApp)
│   ├── Runner (任务运行器)
│   └── Session (会话管理)
├── reme-ai == 0.3.1.8            # ReMe 记忆系统
│   └── ReMeLight (长期记忆管理)
├── fastapi >= 0.110              # Web 框架
├── uvicorn                       # ASGI 服务器
├── click                         # CLI 框架
├── pydantic                      # 数据验证
├── apscheduler                   # 定时任务调度
├── playwright                    # 浏览器自动化
├── httpx                         # HTTP 客户端
├── aiofiles                      # 异步文件 IO
└── (渠道依赖按需安装)
    ├── dingtalk-stream           # 钉钉
    ├── lark-oapi                 # 飞书
    ├── discord.py                # Discord
    ├── python-telegram-bot       # Telegram
    ├── matrix-nio                # Matrix
    ├── paho-mqtt                 # MQTT
    ├── twilio                    # 语音
    ├── wecom-aibot-python-sdk    # 企业微信
    └── agent-client-protocol     # ACP

11.4 前端依赖链

scss 复制代码

Console (React)
├── @agentscope-ai/chat (聊天组件)
├── @agentscope-ai/design (设计系统/主题)
├── @agentscope-ai/icons (图标)
├── antd 5 (UI 组件库)
├── zustand (状态管理)
├── react-router-dom (路由)
├── @monaco-editor/react (代码编辑)
├── @dnd-kit (拖拽)
├── mermaid (图表)
├── @tauri-apps/api (桌面壳 API)
├── i18next (国际化)
└── @ant-design/plots (图表)

12. 项目运行方式

12.1 系统要求

Python: 3.10 - 3.13
Node.js: >= 18（仅前端开发需要）
操作系统: Linux / macOS / Windows

12.2 安装方式

方式一：pip 安装（推荐）

bash 复制代码

pip install qwenpaw
qwenpaw init --defaults
qwenpaw app

方式二：一键安装脚本（无需 Python）

bash 复制代码

# Linux / macOS
curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash

# Windows (PowerShell)
iwr -useb https://qwenpaw.agentscope.io/install.ps1 | iex

方式三：Docker

bash 复制代码

# Docker 直接运行
docker pull agentscope/qwenpaw:latest
docker run -p 127.0.0.1:8088:8088 \
  -v qwenpaw-data:/app/working \
  -v qwenpaw-secrets:/app/working.secret \
  agentscope/qwenpaw:latest

# Docker Compose
docker-compose up -d

方式四：从源码构建

bash 复制代码

git clone https://github.com/agentscope-ai/QwenPaw.git
cd QwenPaw

# 构建前端
cd console
npm ci
npm run build
cd ..

# 复制构建产物
mkdir -p src/qwenpaw/console
cp -R console/dist/. src/qwenpaw/console/

# 安装后端
pip install -e .

# 开发依赖
pip install -e ".[dev,full]"

# 启动
qwenpaw init --defaults
qwenpaw app

方式五：桌面应用（Beta）

从 GitHub Releases 下载对应平台的安装包：

Windows: .exe / .msi
macOS: .dmg

12.3 启动后访问

Web 控制台 : http://127.0.0.1:8088/
API 文档 (Swagger) : http://127.0.0.1:8088/docs
默认端口 : 8088 (可通过 --port 参数修改)

12.4 常用命令

bash 复制代码

# 启动服务
qwenpaw app                          # 前台运行
qwenpaw app --port 9090              # 指定端口
start_server.py                      # 快速后台启动（开发用）

# Agent 管理
qwenpaw agents list                  # 列出所有 Agent
qwenpaw agents create <name>         # 创建 Agent
qwenpaw agents start <id>            # 启动 Agent
qwenpaw agents stop <id>             # 停止 Agent

# 渠道管理
qwenpaw channels list                # 列出所有渠道
qwenpaw channels add dingtalk        # 添加钉钉渠道

# 技能管理
qwenpaw skills list                  # 列出已安装技能
qwenpaw skills install <name>        # 安装技能

# 模型管理
qwenpaw models list                  # 列出已配置模型
qwenpaw models add                   # 添加模型提供商

# 定时任务
qwenpaw cron add "0 8 * * *" "每日新闻摘要"
qwenpaw cron list
qwenpaw cron delete <id>

# 插件管理
qwenpaw plugin list                  # 列出插件
qwenpaw plugin install <path>        # 安装插件

# 系统诊断
qwenpaw doctor                       # 运行系统诊断

# 更新
qwenpaw update                       # 检查并执行更新

12.5 前端开发

bash 复制代码

cd console
npm ci
npm run dev          # 启动开发服务器（需要先启动后端 qwenpaw app）

可用脚本

命令	说明
`npm run dev`	启动 Vite 开发服务器
`npm run build`	构建生产版本
`npm run build:tauri-bootstrap`	构建 Tauri 版本
`npm run lint`	ESLint 检查
`npm run format`	Prettier 格式化
`npm run test`	运行 Vitest 测试

12.6 Docker Compose 配置

yaml 复制代码

version: '3.8'
services:
  qwenpaw:
    image: agentscope/qwenpaw:latest
    ports:
      - "8088:8088"
    volumes:
      - qwenpaw-data:/app/working
      - qwenpaw-secrets:/app/working.secret
    environment:
      - QWENPAW_PORT=8088
    restart: unless-stopped

volumes:
  qwenpaw-data:
  qwenpaw-secrets:

12.7 更新注意事项（源码安装）

bash 复制代码

git pull
cd console && npm ci && npm run build && cd ..
mkdir -p src/qwenpaw/console
cp -R console/dist/. src/qwenpaw/console/
pip install -e .
qwenpaw app
# 清除浏览器缓存: Ctrl+Shift+R

13. 数据流与请求生命周期

13.1 完整请求链路 (Web Console → Agent 响应)

13.2 IM 渠道请求链路

bash 复制代码

IM Platform (钉钉/飞书/Telegram...)
     │
1. ChannelManager 启动渠道监听
     │
2. 渠道收到用户消息
     │
3. BaseChannel.handle_message()
     │  解析消息格式（文本、图片、文件）
     │  访问控制检查（白名单/黑名单）
     ▼
4. Workspace.runner.query_handler()
     │  (与 Web Console 相同的处理流程)
     ▼
5. BaseChannel.send_message()
     │  格式化并发送回复到 IM 平台
     │  （钉钉流式卡片 / 飞书 CardKit / Telegram 流式等）
     ▼
6. 用户收到 AI 回复

13.3 定时任务执行链路

scss 复制代码

CronManager 调度 (APScheduler)
     │
1. 触发已注册的 Cron Job
     │  例如：每日新闻摘要、心跳签到、ReMe Dream
     ▼
2. 构建任务描述
     │
3. Workspace.runner.query_handler()
     │  当做用户查询处理（无上下文隔离执行，节省 Token）
     ▼
4. 处理结果（可推送到指定渠道）

13.4 启动流程

graph LR %% 样式定义 classDef initFill fill:#f5f5f5,stroke:#333,stroke-width:1.5px,font-weight:bold; classDef phase1Fill fill:#fff0f0,stroke:#ff4d4f,stroke-width:1px; classDef phase2Fill fill:#f6ffed,stroke:#52c41a,stroke-width:1px; classDef compFill fill:#fff,stroke:#666,stroke-width:1px,font-size:12px; %% 1. 入口 START["CLI: qwenpaw app"] --> APP["app_cmd.py (uvicorn 启动)"] APP --> LIFESPAN["FastAPI Lifespan 挂钩"] class START,APP,LIFESPAN initFill; %% 2. Phase 1 分支 LIFESPAN --> P1["Phase 1: 同步初始化 (轻量级 <100ms)"] subgraph PHASE_1 [" "] direction LR P1_1["清理历史伪影"] --- P1_2["环境变零注册"] --- P1_3["遥测数据收集"] --- P1_4["配置平滑迁移"] end P1 --> P1_1 class P1 initFill; class P1_1,P1_2,P1_3,P1_4 compFill; style PHASE_1 fill:#fff1f0,stroke:#ffa39e,stroke-dasharray: 5 5; %% 3. 服务器就绪产生式 P1_4 --> READY["打印就绪横幅 【服务器 Ready 开放端口】"] class READY fill:#e6f7ff,stroke:#1890ff,font-weight:bold; %% 4. Phase 2 后台分支 LIFESPAN -->|asyncio.create_task| P2["Phase 2: 后台异步链 (非阻塞并行并发)"] subgraph PHASE_2 ["Agent 运行时拉起"] direction LR A1["ChannelManager (渠道监听)"] === A2["MCPClientManager (MCP握手)"] === A3["AgentRunner (引擎就绪)"] end subgraph PHASE_2_OTHER ["其他系统恢复"] direction LR O1["本地模型权重检查"] === O2["插件动态加载 (提供者/命令/钩子)"] === O3["审批服务初始化"] end P2 --> PHASE_2 P2 --> PHASE_2_OTHER class P2 initFill; class A1,A2,A3,O1,O2,O3 compFill; style PHASE_2 fill:#f6ffed,stroke:#b7eb8f; style PHASE_2_OTHER fill:#f6ffed,stroke:#b7eb8f; %% 逻辑连线：就绪后后台继续运行 READY -.-> P2

css 复制代码

1. CLI: qwenpaw app
   └── app_cmd.py → uvicorn 启动 FastAPI

2. FastAPI lifespan 启动
   ├── Phase 1 (< 100ms): 同步初始化
   │   ├── cleanup_startup_restore_artifacts()
   │   ├── auto_register_from_env()
   │   ├── 遥测数据收集
   │   ├── 配置迁移
   │   └── 创建核心管理器
   │
   ├── Phase 2 (后台): 异步初始化
   │   ├── multi_agent_manager.start_all_configured_agents()
   │   │   └── 并行启动每个 Agent 的 Workspace
   │   │       ├── ChannelManager 初始化
   │   │       ├── MCPClientManager 初始化
   │   │       └── AgentRunner 初始化
   │   ├── 本地模型恢复
   │   ├── 插件系统加载
   │   │   ├── 加载插件提供者
   │   │   ├── 注册控制命令
   │   │   └── 执行启动钩子
   │   └── 审批服务初始化
   │
   └── 打印就绪横幅

3. 服务器就绪，开始接受请求

14. 扩展与开发指南

14.1 扩展方式总览

扩展类型	方法	文档
添加通道	实现 `BaseChannel`，在 `ChannelConfig` 注册	Channels
添加模型提供者	实现 Provider 接口，在 `ProviderManager` 注册	Models
添加技能	创建 SKILL.md 并安装	Skills
添加 MCP	配置 MCP 客户端	MCP
添加插件	实现插件接口	Plugins
添加工具	在 `_default_builtin_tools()` 注册	内置工具系统

14.2 添加新的模型提供商

在 src/qwenpaw/providers/ 创建新的提供商模块

实现提供商接口：

python 复制代码

class MyProvider:
    async def chat_completion(messages, **kwargs) -> str
    async def chat_completion_stream(messages, **kwargs) -> AsyncGenerator

在 provider_manager.py 中注册

14.3 添加新的 IM 渠道

在 src/qwenpaw/app/channels/ 创建新的渠道模块

继承 BaseChannel 并实现：

python 复制代码

class MyChannel(BaseChannel):
    async def start()
    async def stop()
    async def handle_message(message)
    async def send_message(message)

在 ChannelConfig 中注册

14.4 创建工具插件

创建 plugins/tool/my-tool/ 目录

创建 plugin.json：

json 复制代码

{
  "id": "my-tool",
  "version": "1.0.0",
  "type": "tool",
  "entry": { "backend": "my_tool.py" },
  "min_version": "1.1.6",
  "meta": {
    "tools": [{
      "name": "my_function",
      "description": "工具描述",
      "config": { "api_key": { "type": "string" } }
    }]
  }
}

实现 my_tool.py 中的 Plugin 类

14.5 创建完整的 Bundle 插件

创建 plugins/bundle/my-plugin/ 目录
实现前后端入口
使用 PluginApi 注册 hooks、路由、工具

14.6 开发环境配置

bash 复制代码

# 后端开发
pip install -e ".[dev]"

# 前端开发
cd console
npm ci
npm run dev            # 启动 Vite 开发服务器

# 运行测试
pytest tests/ -v       # 后端测试
cd console && npm test # 前端测试

# 代码格式化
make format            # black + isort
make lint              # flake8
cd console && npm run lint    # ESLint
cd console && npm run format  # Prettier

14.7 打包发布

bash 复制代码

# Python Wheel
bash scripts/wheel_build.sh

# Docker 镜像
bash scripts/docker_build.sh

# 前端构建
cd console && npm run build

# 桌面应用打包
bash scripts/pack/build_macos.sh    # macOS
bash scripts/pack/build_windows.ps1 # Windows

15. 附录

A. 配置文件位置

配置项	位置
工作目录	`~/.qwenpaw/working/`
根配置	`{working}/config.json`
Agent 配置	`{working}/agents/{id}/config.json`
Agent 工作区配置	`{working}/agents/{id}/workspace/agent.json`
渠道配置	`{working}/channels.json`
模型配置	`{working}/providers.json`
技能目录	`{working}/skills/`
插件目录	`{working}/plugins/`
环境变量	`{working}/envs.json`
日志目录	`{working}/logs/`
备份目录	`{working}/backups/`
密钥存储	`{working}.secret/`

B. 环境变量

变量	说明	默认值
`QWENPAW_PORT`	服务端口	`8088`
`QWENPAW_HOST`	绑定地址	`127.0.0.1`
`QWENPAW_WORKING_DIR`	工作目录	`~/.qwenpaw/working`
`QWENPAW_LOG_LEVEL`	日志级别	`INFO`
`QWENPAW_AUTH_ENABLED`	是否启用 Web 认证	`false`
`OPENAI_API_KEY`	OpenAI API 密钥	---
`DASHSCOPE_API_KEY`	通义千问 API 密钥	---

C. 相关链接

GitHub : github.com/agentscope-...
文档站点 : qwenpaw.agentscope.io/
PyPI : pypi.org/project/qwe...
AgentScope : github.com/agentscope-...
联系方式 : copaw@agentscope.io

QwenPaw 源码学习指南

1. 项目概述

核心定位

核心特性

2. 整体架构

架构总览图

能力层展开

架构分层

3. 技术栈

后端

前端

文档站

4. 目录结构

5. 后端模块详解（Python）

5.1 应用核心 (app/)

关键类与函数

启动流程 (lifespan)

路由注册

MultiAgentManager (multi_agent_manager.py, 537行)

Workspace (workspace/workspace.py, 467行)

Agent 上下文 (agent_context.py, 201行)

关键文件清单

5.2 CLI 命令行 (cli/)

核心类

子命令一览 (30+)

5.3 配置系统 (config/)

关键配置模型

配置加载流程

5.4 Agent 引擎 (agents/)

关键类

Agent 初始化流程

命令系统

子模块

Runner 执行流程

5.5 技能系统 (agents/skill_system/)

技能来源

关键函数

技能目录结构

技能生命周期

内置技能示例

5.6 工具系统 (agents/tools/)

内置工具清单

其他工具文件

5.7 模型提供者 (providers/、market/、local_models/)

ProviderManager

支持的云模型提供商

本地模型支持

模型市场

5.8 MCP 协议支持 (app/mcp/)

关键类

支持的传输方式

配置示例

5.9 安全模块 (security/)

三层防护

审批级别

Web 认证

密钥存储

5.10 通道系统 (app/channels/)

支持的通道

关键类

基类接口

5.11 定时任务 (app/crons/)

功能

CLI 命令

5.12 插件系统 (plugins/)

关键类

插件能力

5.13 备份模块 (backup/)

5.14 计划模式 (plan/)

关键类

5.15 Token 用量追踪 (token_usage/)

5.16 工具函数 (utils/)

6. 前端模块详解（React + Tauri）

6.1 技术栈

6.2 目录结构

6.3 核心组件与页面

主应用 (App.tsx)

页面清单

运行模式

6.4 状态管理

5.1 应用核心 (`app/`)

MultiAgentManager (`multi_agent_manager.py`, 537行)

Workspace (`workspace/workspace.py`, 467行)

Agent 上下文 (`agent_context.py`, 201行)

5.2 CLI 命令行 (`cli/`)

5.3 配置系统 (`config/`)

5.4 Agent 引擎 (`agents/`)

5.5 技能系统 (`agents/skill_system/`)

5.6 工具系统 (`agents/tools/`)

5.7 模型提供者 (`providers/`、`market/`、`local_models/`)

5.8 MCP 协议支持 (`app/mcp/`)

5.9 安全模块 (`security/`)

5.10 通道系统 (`app/channels/`)

5.11 定时任务 (`app/crons/`)

5.12 插件系统 (`plugins/`)

5.13 备份模块 (`backup/`)

5.14 计划模式 (`plan/`)

5.15 Token 用量追踪 (`token_usage/`)

5.16 工具函数 (`utils/`)

主应用 (`App.tsx`)

7. 文档站 (`website/`)