user-system/docs/team/WORKFLOW.md

# 多智能体并行协作工作流

版本：1.0  
更新时间：2026-04-02

本文档描述基于 Gitea 远程仓库的多智能体并行协作工作流。

## 1. 工作流总览

```
需求/问题 → 规划智能体 → 任务拆分 → 方案对比(可选) → 并行实现 → 并行验证 → PR合并 → 文档同步
```

## 2. 角色定义

### 2.1 规划智能体 (Planner)

- **职责**：需求分析、任务拆分、依赖识别、方案对比组织
- **输出**：任务清单、依赖图、方案对比报告（如需要）
- **触发条件**：收到新功能需求或复杂问题

### 2.2 实现智能体 (Implementer)

- **职责**：编码实现、单元测试编写
- **输出**：代码变更、测试用例
- **触发条件**：收到明确的任务描述和验收标准

### 2.3 验证智能体 (Verifier)

- **职责**：执行验证矩阵、生成验证报告
- **输出**：验证报告（通过/失败/阻塞）
- **触发条件**：实现智能体完成编码后

### 2.4 审查智能体 (Reviewer)

- **职责**：代码审查、安全审查、性能审查
- **输出**：审查报告（问题清单+优先级）
- **触发条件**：PR 创建后

## 3. 任务拆分规则

### 3.1 拆分原则

- 每个任务必须是独立的、可并行执行的单元
- 任务粒度：每个任务应在 30-120 分钟内可完成
- 前后端分离的任务必须拆分为独立任务
- 数据库变更必须单独作为一个任务

### 3.2 依赖标注

- 任务之间如果有依赖，必须明确标注：
  - `依赖: TASK-XXX`
  - 执行顺序：`先执行 TASK-XXX，再执行 TASK-YYY`
- 无依赖的任务标记为 `独立`

### 3.3 任务模板

```markdown
### TASK-XXX: 任务名称
**优先级**: P0/P1/P2  
**工作量**: S(1h)/M(2h)/L(4h)  
**依赖**: 无 / TASK-XXX  
**负责人**: 实现智能体-A  

**任务描述**:
- 要做什么
- 为什么做

**验收标准**:
- [ ] 标准1
- [ ] 标准2

**验证命令**:
- 命令1
- 命令2
```

## 4. 方案对比流程

### 4.1 触发条件

- 新增核心功能
- 架构变更
- 存在多种可行实现路径
- 性能优化涉及重大权衡

### 4.2 对比流程

1. 规划智能体识别需要方案对比的任务
2. 分配 2-3 个智能体并行输出不同方案
3. 每个方案必须包含：
   - 实现思路
   - 优缺点分析
   - 预估工作量
   - 风险评估
4. 决策者根据对比维度选择最优方案
5. 记录决策原因和否决原因

### 4.3 对比维度

| 维度 | 说明 |
|------|------|
| 实现复杂度 | 人天/智能体时 |
| 性能影响 | 对现有性能的影响 |
| 可维护性 | 后续维护成本 |
| 架构兼容性 | 与现有架构的匹配度 |
| 测试难度 | 测试覆盖的难易程度 |

## 5. 并行实现模式

### 5.1 无依赖并行

```
TASK-A (前端) ──┐
                ├── 并行执行
TASK-B (后端) ──┘
```

### 5.2 有依赖串行

```
TASK-A (后端API) ──→ TASK-B (前端对接)
```

### 5.3 混合模式

```
TASK-A (数据模型) ──┬─→ TASK-B (后端Service) ──┐
                    │                           ├── TASK-E (集成测试)
                    └─→ TASK-C (前端页面) ──────┘
                    │
TASK-D (独立任务) ──┘
```

## 6. 冲突解决机制

### 6.1 文件冲突预防

- 任务拆分阶段识别可能被多个任务修改的文件
- 协调修改顺序或分配不同的修改区域
- 共享文件（如路由配置、类型定义）由单一智能体统一修改

### 6.2 合并冲突处理

- 优先保留功能完整的版本
- 手动合并差异，不自动解决
- 合并后必须重新运行验证矩阵

## 7. 验证策略

### 7.1 本地验证（实现智能体）

- 每次提交前运行受影响的最小测试集
- 确保代码可编译、lint 通过

### 7.2 并行验证（验证智能体）

- 后端测试、前端 lint/build、E2E 测试并行执行
- 生成统一的验证报告

### 7.3 PR 验证（审查智能体）

- 代码审查
- 安全审查
- 性能审查
- 生成审查报告

## 7. E2E 测试流程

### 7.1 E2E 测试架构

- **Playwright CDP E2E**（主验收路径）：
  - 命令：`cd frontend/admin && npm.cmd run e2e:full:win`
  - 协议：Playwright 通过 CDP 连接真实浏览器
  - 数据库：隔离测试数据库（临时 SQLite 文件）
  - 邮件：本地 SMTP 捕获服务（验证邮件发送）
  - 信号收集：console errors、dialogs、popups、request failures、401 responses
  - 多视口：desktop 1440x960、tablet 820x1180、mobile 390x844
- **覆盖场景**：
  - 管理员引导（admin-bootstrap）
  - 公开注册（public-registration）
  - 邮箱激活（email-activation）
  - 登录表面验证（login-surface）
  - 认证工作流（auth-workflow）
  - 响应式登录（responsive-login）
  - 桌面/移动端导航（desktop-mobile-navigation）

### 7.2 E2E 测试规则

- 必须启动真实后端进程（隔离测试数据库）
- 必须启动真实前端开发服务器
- 必须通过真实浏览器（CDP 协议）执行用户操作
- 必须验证真实 API 响应（非 mock）
- 必须验证真实数据库状态变化
- 禁止使用 mock 响应替代真实 API 调用
- 禁止在测试中硬编码预期结果而不走真实业务链路
- 禁止跳过认证、权限校验等安全环节直接断言页面状态

### 7.3 未来 E2E 增强方向

- 引入 `agent-browser`（bb browse）等浏览器自动化工具
- 补充 Playwright 未覆盖的交互场景：
  - 设备信任管理
  - 批量操作
  - 系统设置页
  - 管理员管理页
  - 登录日志导出
- 增加复杂业务流程的端到端验证

## 8. 文档同步规则

### 8.1 必须更新的文档

| 变更类型 | 必须更新的文档 |
|----------|----------------|
| 功能变更 | `docs/status/REAL_PROJECT_STATUS.md` |
| API 变更 | `docs/API.md` |
| 规则变更 | `docs/team/QUALITY_STANDARD.md` |
| 经验沉淀 | `docs/team/PROJECT_EXPERIENCE_SUMMARY.md` |
| 架构决策 | `docs/decisions/` |

### 8.2 文档更新时机

- 代码合并后立即更新相关文档
- 文档更新作为 PR 的一部分

## 9. 迭代节奏

### 9.1 迭代周期

- 每个迭代周期不超过 2 小时
- 小步快跑，持续验证

### 9.2 迭代流程

1. **规划阶段**（10-15 分钟）
   - 任务拆分
   - 依赖分析
   - 智能体分配

2. **实现阶段**（60-90 分钟）
   - 并行编码
   - 本地验证

3. **验证阶段**（15-30 分钟）
   - 并行验证
   - 代码审查
   - PR 合并

4. **总结阶段**（5-10 分钟）
   - 文档同步
   - 经验沉淀

## 10. 阻塞处理

### 10.1 阻塞识别

- 智能体无法继续执行任务
- 验证持续失败
- 依赖任务未完成

### 10.2 阻塞处理流程

1. 记录阻塞原因和影响范围
2. 寻找替代方案
3. 阻塞超过 30 分钟上报
4. 调整任务优先级或拆分方式

## 11. 知识沉淀

### 11.1 必须记录的内容

- 解决方案（每次解决的问题）
- 避免方法（每次踩过的坑）
- 验证结果（每次验证通过的命令）

### 11.2 沉淀位置

- 短期经验：`docs/sprints/`
- 长期经验：`docs/team/PROJECT_EXPERIENCE_SUMMARY.md`
- 架构决策：`docs/decisions/`