long-agent/user-system
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
user-system/docs/team/WORKFLOW.md
long-agent 5b6bd93179 refactor: 整理项目根目录结构 
整理内容:
- 删除 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 ./... 通过
2026-04-07 18:10:36 +08:00

7.1 KiB
Raw Permalink Blame History

多智能体并行协作工作流

版本：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 任务模板

### 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/
Reference in New Issue View Git Blame Copy Permalink