[AI]qwenpaw 实战拆解一

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

CoPaw / QwenPaw 项目组成与框架分析

CoPaw，项目已正式更名为 QwenPaw（PyPI 包名 qwenpaw，CLI 同时保留 copaw 别名）。这是阿里巴巴 AgentScope 团队开源的个人 AI 助理 / Agent OS。

1. 项目定位

QwenPaw 是一个本地或自托管的个人 AI 助理，核心特点：

• 一次安装可托管多个隔离智能体（每个智能体一个工作区）
• 通过 Skills + 插件 扩展能力
• 连接 钉钉、飞书、微信、Discord、Telegram 等 IM 频道
• 数据留在本机，带沙箱、治理、工具守卫等安全层

官方文档：https://qwenpaw.agentscope.io/

2. 整体架构（分层）

#mermaid-svg-W8G9M5PTBVeYRuLp{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-W8G9M5PTBVeYRuLp .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-W8G9M5PTBVeYRuLp .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-W8G9M5PTBVeYRuLp .error-icon{fill:#552222;}#mermaid-svg-W8G9M5PTBVeYRuLp .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-W8G9M5PTBVeYRuLp .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-W8G9M5PTBVeYRuLp .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-W8G9M5PTBVeYRuLp .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-W8G9M5PTBVeYRuLp .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-W8G9M5PTBVeYRuLp .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-W8G9M5PTBVeYRuLp .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-W8G9M5PTBVeYRuLp .marker{fill:#333333;stroke:#333333;}#mermaid-svg-W8G9M5PTBVeYRuLp .marker.cross{stroke:#333333;}#mermaid-svg-W8G9M5PTBVeYRuLp svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-W8G9M5PTBVeYRuLp p{margin:0;}#mermaid-svg-W8G9M5PTBVeYRuLp .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-W8G9M5PTBVeYRuLp .cluster-label text{fill:#333;}#mermaid-svg-W8G9M5PTBVeYRuLp .cluster-label span{color:#333;}#mermaid-svg-W8G9M5PTBVeYRuLp .cluster-label span p{background-color:transparent;}#mermaid-svg-W8G9M5PTBVeYRuLp .label text,#mermaid-svg-W8G9M5PTBVeYRuLp span{fill:#333;color:#333;}#mermaid-svg-W8G9M5PTBVeYRuLp .node rect,#mermaid-svg-W8G9M5PTBVeYRuLp .node circle,#mermaid-svg-W8G9M5PTBVeYRuLp .node ellipse,#mermaid-svg-W8G9M5PTBVeYRuLp .node polygon,#mermaid-svg-W8G9M5PTBVeYRuLp .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-W8G9M5PTBVeYRuLp .rough-node .label text,#mermaid-svg-W8G9M5PTBVeYRuLp .node .label text,#mermaid-svg-W8G9M5PTBVeYRuLp .image-shape .label,#mermaid-svg-W8G9M5PTBVeYRuLp .icon-shape .label{text-anchor:middle;}#mermaid-svg-W8G9M5PTBVeYRuLp .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-W8G9M5PTBVeYRuLp .rough-node .label,#mermaid-svg-W8G9M5PTBVeYRuLp .node .label,#mermaid-svg-W8G9M5PTBVeYRuLp .image-shape .label,#mermaid-svg-W8G9M5PTBVeYRuLp .icon-shape .label{text-align:center;}#mermaid-svg-W8G9M5PTBVeYRuLp .node.clickable{cursor:pointer;}#mermaid-svg-W8G9M5PTBVeYRuLp .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-W8G9M5PTBVeYRuLp .arrowheadPath{fill:#333333;}#mermaid-svg-W8G9M5PTBVeYRuLp .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-W8G9M5PTBVeYRuLp .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-W8G9M5PTBVeYRuLp .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-W8G9M5PTBVeYRuLp .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-W8G9M5PTBVeYRuLp .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-W8G9M5PTBVeYRuLp .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-W8G9M5PTBVeYRuLp .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-W8G9M5PTBVeYRuLp .cluster text{fill:#333;}#mermaid-svg-W8G9M5PTBVeYRuLp .cluster span{color:#333;}#mermaid-svg-W8G9M5PTBVeYRuLp div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-W8G9M5PTBVeYRuLp .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-W8G9M5PTBVeYRuLp rect.text{fill:none;stroke-width:0;}#mermaid-svg-W8G9M5PTBVeYRuLp .icon-shape,#mermaid-svg-W8G9M5PTBVeYRuLp .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-W8G9M5PTBVeYRuLp .icon-shape p,#mermaid-svg-W8G9M5PTBVeYRuLp .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-W8G9M5PTBVeYRuLp .icon-shape .label rect,#mermaid-svg-W8G9M5PTBVeYRuLp .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-W8G9M5PTBVeYRuLp .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-W8G9M5PTBVeYRuLp .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-W8G9M5PTBVeYRuLp :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

基座

驱动层

MCP 连接器

加密凭据

工作区（每 Agent 隔离）

记忆

Skills

工具

治理 + 沙箱

运行时层

请求路由

生命周期钩子

ReAct 智能体循环

ACP 外部 Agent 适配

入口层

Web Console

Tauri 桌面

终端 TUI

CLI / doctor

IM 频道

AgentScope 2.0

核心设计思想：把 QwenPaw 当作小型 Agent 操作系统——AgentScope 提供进程内 ReAct 循环、消息/会话、工具层；QwenPaw 在其上管理工作区、记忆、Skills、频道、治理、沙箱等资源维度。

3. 仓库组成（Monorepo）

4. 后端框架与依赖

4.1 核心基座：AgentScope 2.0

dependencies = [
"agentscope==2.0.4",

复用 AgentScope 的：

• ReAct 智能体循环
• 消息格式（agentscope.message.Msg）与会话状态
• 工具调用层
• 工作目录抽象（agentscope.workspace）

4.2 Web 服务：FastAPI + Uvicorn

from fastapi import FastAPI, HTTPException

• 默认端口 8088
• 静态托管 Console 前端
• REST + SSE 流式 API
• DynamicMultiAgentRunner 按请求路由到对应 Agent 工作区

4.3 CLI：Click + Textual

• 入口：qwenpaw / copaw → qwenpaw.cli.main:cli
• TUI 基于 Textual（终端 Markdown 流式 UI）
• 子命令：init、app、doctor、频道/Skills/定时任务管理等

4.4 其他关键依赖

5. Python 核心模块结构

src/qwenpaw/
├── app/ # FastAPI 应用、频道、路由、工作区
├── runtime/ # 请求生命周期、ReAct 执行、流式输出
├── agents/ # 智能体、工具、Skills、记忆、ACP
├── services/ # 工作区注册与管理
├── hooks/ # 生命周期钩子（会话、Cron、可观测性等）
├── modes/ # Coding / Mission / Goal 等运行模式
├── providers/ # 14+ 模型供应商（OpenAI、Gemini、DashScope 等）
├── local_models/ # Ollama / LM Studio / llama.cpp 本地推理
├── drivers/ # MCP 连接器、凭据、策略
├── plugins/ # 插件加载与注册 API
├── governance/ # 治理策略（允许/拒绝/询问/沙箱）
├── security/ # Tool Guard、Skill Scanner
├── sandbox/ # OS 级沙箱（seatbelt/bubblewrap/AppContainer）
├── config/ # JSON 配置模型
├── cli/ # CLI + TUI
├── market/ # 插件/Skill 市场
├── backup/ # 工作区备份恢复
├── observability/ # Langfuse 等链路追踪
└── loop/ # Loop 工程（长任务编排）

请求生命周期（Runtime）

固定流水线 + 钩子点：

6. 前端框架

Console（主 UI）

• React 18 + Vite + TypeScript
• Ant Design 5 + @agentscope-ai/chat / design 组件
• Monaco Editor（Coding 模式代码编辑）
• Zustand 状态管理
• react-router-dom 路由
• 构建产物打包进 Python 包 qwenpaw/console/

Desktop

• Tauri 2（Rust）包装 Console
• Python FastAPI 作为 sidecar 子进程运行
• 支持托盘、自动更新、端口持久化

Website

• React + Vite + Tailwind + shadcn/radix
• 多语言文档（中/英等）

7. 频道（Channels）——内置 IM 接入

src/qwenpaw/app/channels/ 下约 17 个频道实现：

插件可扩展，例如 plugins/channel/azure_bot/。

8. Skills 与插件体系

Skills（能力层）

• 每个 Skill = 一个文件夹（SKILL.md + 可选脚本）
• 内置约 18 种 × 中英双语，例如：
  • cron、pdf/docx/xlsx/pptx、news、browser_cdp
  • multi_agent_collaboration、file_reader、himalaya（邮件）等
• 安装时经 Skill Scanner 静态扫描

插件（Plugin API）

插件可向注册表注入：

• 模型 Provider
• 工具（Tool）
• 频道（Channel）
• 钩子（Hook）
• 魔法命令、提示词片段
• HTTP 路由、Agent 中间件

官方插件示例：

9. 模型与记忆

模型 Provider

providers/provider_manager.py 聚合大量供应商，包括：

• OpenAI、Anthropic、Google Gemini、DashScope（Qwen）
• OpenRouter、Azure、智谱、MiniMax、Kimi 等
• 本地：Ollama、LM Studio、llama.cpp（QwenPaw-Flash 2B/4B/9B）

记忆 vs 上下文

10. 安全与治理（Trust Spine）

每次工具调用必经：

11. 测试与部署

• 测试：pytest（unit / contract / integration / e2e），Makefile 提供快捷目标
• 部署：docker-compose.yml + deploy/Dockerfile
• CI：.github/workflows/ 含 Tauri/macOS/Windows 构建验证

12. 总结：

┌─────────────────────────────────────────────────────────┐
│ 入口: Console(React) | Tauri(Rust) | TUI(Textual) | IM │
├─────────────────────────────────────────────────────────┤
│ 服务: FastAPI + Uvicorn (Python 3.11+) │
├─────────────────────────────────────────────────────────┤
│ 运行时: QwenPaw Runtime (钩子 + 模式 + 多 Agent 路由) │
├─────────────────────────────────────────────────────────┤
│ 智能体: AgentScope 2.0 ReAct + Tools + Skills + Memory │
├─────────────────────────────────────────────────────────┤
│ 扩展: Plugin API | MCP Drivers | ACP 外部 Agent │
├─────────────────────────────────────────────────────────┤
│ 安全: Governance | Sandbox | Tool Guard | Skill Scan │
└─────────────────────────────────────────────────────────┘

概括：QwenPaw（CoPaw）是以 AgentScope 2.0 为内核、FastAPI 为服务层、React/Tauri 为交互层的个人 Agent 操作系统；通过工作区隔离多智能体，用 Skills/插件扩展能力，用频道连接 IM，用治理+沙箱保障本地安全运行。