1|# TeamClaw 系统架构设计文档 V1.0
2|
3|> 最后更新：2026-04-16
4|> 状态：已确认，待开发
5|
6|---
7|
8|## 1. 产品定位
9|
10|TeamClaw 是一个**桌面客户端**（Windows + macOS），定位为多 Agent 协作的项目交付平台。用户通过微信或桌面端与系统交互，由 Main Agent 主管调度多个专业 Agent（PM、Designer、Architect、Coder、DBA、DevOps）协同完成软件开发任务。
11|
12|### 核心理念
13|- **不造轮子**：Agent 编排能力内嵌 OpenClaw，复用其成熟框架
14|- **人机协作**：关键节点需用户审核确认，Agent 不自行决定重大事项
15|- **微信优先**：通过 OpenClaw Bot 桥接微信，文字交互为主
16|
17|---
18|
19|## 2. 技术选型
20|
21|| 层级 | 技术方案 | 说明 |
22||------|---------|------|
23|| 桌面框架 | **Tauri 2.0** | 轻量、安全、跨平台，Rust 后端 |
24|| 前端 UI | **React + TypeScript** | Tauri webview 渲染 |
25|| 本地数据库 | **SQLite** (via Drizzle ORM) | 零配置，数据存本地 |
26|| Agent 引擎 | **OpenClaw** | 内嵌调用，负责 Agent 编排与执行 |
27|| 微信桥接 | **OpenClaw Bot** → 微信适配层 | 文字交互，审核二次确认 |
28|| 向量存储 | **ChromaDB**（本地） | 知识库 RAG 检索 |
29|| 实时通信 | **本地事件总线** | Agent 状态推送、任务进度更新 |
30|| 包管理 | **pnpm** | Monorepo 工作区管理 |
31|
32|---
33|
34|## 3. 系统架构图
35|
36|```
37|┌─────────────────────────────────────────────────────┐
38|│ 用户交互层 │
39|│ ┌──────────┐ ┌──────────────────────────┐ │
40|│ │ 微信端 │◄───►│ OpenClaw Bot (桥接层) │ │
41|│ │ (文字) │ │ - 消息收发 │ │
42|│ └──────────┘ │ - 审核确认 │ │
43|│ └──────────┬───────────────┘ │
44|│ ┌──────────────────────────┐│ │
45|│ │ 桌面客户端 (Tauri) ││ │
46|│ │ ┌───────────────────┐ ││ │
47|│ │ │ React UI │ ││ │
48|│ │ │ - 项目管理 │◄──┘│ │
49|│ │ │ - 对话管理 │ │ │
50|│ │ │ - Agent 监控 │ │ │
51|│ │ │ - 任务看板 │ │ │
52|│ │ └────────┬──────────┘ │ │
53|│ └───────────┼───────────────┘ │
54|└──────────────┼──────────────────────────────────────┘
55| │
56|┌──────────────┼──────────────────────────────────────┐
57|│ ▼ 核心引擎层 │
58|│ ┌───────────────────────────────────────────┐ │
59|│ │ Main Agent (主管) │ │
60|│ │ - 任务接收与拆解 │ │
61|│ │ - Agent 调度与编排 │ │
62|│ │ - 问题汇总与统一提问 │ │
63|│ │ - 状态管理与进度汇报 │ │
64|│ └───────────────────┬───────────────────────┘ │
65|│ │ │
66|│ ┌────────────┼────────────┐ │
67|│ ▼ ▼ ▼ │
68|│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
69|│ │ PM │ │ Designer │ │ Architect│ ... │
70|│ │ Agent │ │ Agent │ │ Agent │ │
71|│ └──────────┘ └──────────┘ └──────────┘ │
72|│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
73|│ │ CoderA │ │ CoderB │ │ DBA │ │
74|│ │ Agent │ │ Agent │ │ Agent │ │
75|│ └──────────┘ └──────────┘ └──────────┘ │
76|│ ┌──────────┐ │
77|│ │ DevOps │ OpenClaw Agent Runtime │
78|│ │ Agent │ │
79|│ └──────────┘ │
80|└─────────────────────────────────────────────────────┘
81| │
82|┌──────────────┼──────────────────────────────────────┐
83|│ ▼ 数据存储层 │
84|│ ┌────────────┐ ┌──────────┐ ┌────────────┐ │
85|│ │ SQLite │ │ChromaDB │ │ 文件系统 │ │
86|│ │ (结构化) │ │(向量检索) │ │ (代码/产物) │ │
87|│ └────────────┘ └──────────┘ └────────────┘ │
88|└─────────────────────────────────────────────────────┘
89|```
90|
91|---
92|
93|## 4. Agent 角色定义
94|
95|| Agent | 职责 | 输入 | 输出 |
96||-------|------|------|------|
97|| **Main** | 主管，接收任务、拆解、调度、汇总提问 | 用户需求 | 任务分配、进度汇报 |
98|| **PM** | 需求分析、PRD 编写 | 需求描述 | PRD 文档 |
99|| **Designer** | UI/UX 设计 | PRD | HTML/CSS 前端代码 |
100|| Architect | 技术架构、API 设计 | PRD | 架构文档、API Schema | 101|| CoderA | 前端开发 | 设计稿 + 架构 | 前端代码 | 102|| CoderB | 后端开发 | 架构文档 | 后端代码 | 103|| DBA | 数据库设计、迁移 | 架构文档 | Schema、Migration | 104|| DevOps | 部署、CI/CD、环境配置 | 架构文档 | 配置文件、部署脚本 | 105| 106|### Agent 编排模式 — DAG 107|- 任务以 DAG（有向无环图） 方式编排 108|- 可并行的 Agent 同时执行，有依赖关系的串行执行 109|- 用户可在关键节点干预：暂停、修改、跳过、回滚、中止、插入 110| 111|--- 112| 113|## 5. 数据模型（核心实体） 114| 115| 116|Project 117| ├── id, name, description, status, created_at 118| │ 119| ├── Conversation (1:N) 120| │ ├── id, project_id, title, status, created_at 121| │ │ status: creating | clarifying | splitting | 122| │ │ executing | reviewing | iterating | 123| │ │ delivering | archived 124| │ │ 125| │ └── Message (1:N) 126| │ ├── id, conversation_id, role, content, agent, timestamp 127| │ │ role: user | agent | system 128| │ │ 129| │ └── Attachment (1:N) 130| │ ├── id, message_id, type, path 131| │ 132| ├── Task (1:N) 133| │ ├── id, project_id, parent_id, title, status 134| │ │ status: pending | assigned | in_progress | 135| │ │ blocked | reviewing | done | failed 136| │ │ assignee: agent_role 137| │ │ depends_on: [task_id] 138| │ │ 139| │ └── Artifact (1:N) 140| │ ├── id, task_id, type, path, version 141| │ 142| └── Knowledge (1:N) 143| ├── id, project_id, source, embedding, metadata 144| 145| 146|--- 147| 148|## 6. 模块划分与优先级 149| 150|### P0 — 核心功能（MVP） 151|| # | 模块 | 说明 | 152||---|------|------| 153|| 1 | 项目导入 | 创建项目、导入已有代码仓库、配置 Agent | 154|| 2 | 多 Agent 编排 | DAG 编排、Agent 调度、并行/串行执行、用户干预点 | 155|| 3 | 任务体系 | 任务拆分、状态流转、依赖管理、产物关联 | 156| 157|### P1 — 增强功能 158|| # | 模块 | 说明 | 159||---|------|------| 160|| 4 | 外围能力 | 微信桥接、消息推送、文件管理 | 161|| 5 | 知识库 | RAG 检索、项目上下文积累、文档管理 | 162|| 6 | 对话生命周期 | 8 阶段完整流程、归档/解冻、上下文保持 | 163| 164|### P2 — 完善功能 165|| # | 模块 | 说明 | 166||---|------|------| 167|| 7 | 用户角色 | 多用户、权限管理、操作审计 | 168|| 8 | 产物版本 | 代码版本、设计稿版本、diff 对比 | 169|| 9 | Token 计费 | 用量统计、配额管理、成本分析 | 170| 171|### P3 — 运维功能 172|| # | 模块 | 说明 | 173||---|------|------| 174|| 10 | 埋点报警 | 运行监控、异常报警、性能分析 | 175|| 11 | 客户端更新 | 自动更新、版本管理 | 176| 177|--- 178| 179|## 7. 微信交互规范 180| 181|### 消息流程 182| 183|用户(微信) → OpenClaw Bot → TeamClaw Main Agent → 分发给专业 Agent 184| ↓ 185|用户(微信) ← OpenClaw Bot ← Main Agent(汇总) ← Agent 结果收集 186| 187| 188|### 交互规则 189|- 仅文字交互，不做语音消息 190|- 审核二次确认：所有需要用户确认的操作，微信端需回复「确认」才能执行 191|- Agent 并发提问：多个 Agent 的问题由 Main Agent 汇总后统一提问，避免轰炸用户 192|- 消息格式：结构化卡片 + 关键信息摘要 193| 194|--- 195| 196|## 8. 安全与约束 197| 198|- 本地数据优先，敏感信息不上云 199|- Agent 执行代码在沙箱环境中运行 200|- 所有代码修改需用户审核后才写入项目 201|- 微信端操作有操作频率限制 202|- 对话上下文有长度上限，超出部分归档到知识库 203| 204|--- 205| 206|## 9. 里程碑 207| 208|| 阶段 | 时间 | 目标 | 209||------|------|------| 210|| M1 | 第 1-2 周 | 架构搭建 + 项目导入模块 | 211|| M2 | 第 3-4 周 | Agent 编排 + 任务体系 | 212|| M3 | 第 5-6 周 | 微信桥接 + 对话生命周期 | 213|| M4 | 第 7-8 周 | 知识库 + 美化 + 内测 | 214|| M5 | 第 9-10 周 | P2/P3 功能 + 公测 | 215| 216|--- 217| 218|文档维护者：TeamClaw 项目组 219|