long-agent
5b6bd93179
整理内容: - 删除 60+ 临时测试输出文件 (*.txt) - 移动二进制文件到 bin/ 目录 - 移动 Shell 脚本到 scripts/ 目录 - scripts/dev/: check_gitea.sh, check_sub2api.sh, run_tests.sh - scripts/deploy/: deploy_*.sh, simple_deploy.sh - scripts/ops/: fix_nginx.sh, fix_ssl.sh, install_docker.sh - scripts/test/: test_*.sh, test_*.bat - 移动批处理文件到 scripts/ - 移动 Python 脚本到 tools/ - 清理临时日志文件 保留根目录必要文件: - go.mod, go.sum, go.work - Makefile, docker-compose.yml - .env.example, .gitignore - README.md, AGENTS.md, DEPLOY_GUIDE.md 验证: go build ./... && go test ./... 通过
282 lines
7.1 KiB
Markdown
282 lines
7.1 KiB
Markdown
# 多智能体并行协作工作流
|
||
|
||
版本：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/`
|