sanguo_moziplus_v2/docs/test-plan-e2e-v27.md

v2.7/v2.8 端到端测试方案

日期：2026-05-18（v2.7 初版）→ 2026-06-01 更新（v2.8 #07 系列 + Prompt v3.0） 作者：司马懿（初版）→ 庞统（v2.8 更新） 环境：真实部署（~/.sanguo_projects/sanguo_moziplus_v2/）+ 真实 Agent

---

一、测试策略

• 框架：pytest + FastAPI TestClient（直接挂载 app，绕过网络层，但走完整业务逻辑）
• 数据隔离：每个测试 class 用独立项目 ID，测试前创建、测试后清理
• Agent 策略：E1-E8 不启动真实 Agent（只验证 API + DB），E9-E10 启动真实 Agent 执行简单任务
• Ticker：手动调用 ticker.tick() 而非等待 30s 循环
• 测试项目：统一前缀 e2e-v27-，便于识别和清理

二、场景清单

E1: 项目管理（4 个测试）

• E1.1 创建项目（POST /api/projects）
• E1.2 项目列表（GET /api/projects）
• E1.3 自动发现（含 blackboard.db 的目录）
• E1.4 归档项目（status=archived，目录不移动）

E2: Task CRUD + 状态机（5 个测试）

• E2.1 创建 Task（POST /api/projects/{pid}/tasks）
• E2.2 查询 Task（GET，expand=all）
• E2.3 合法状态转换（pending → claimed → working → review → done）
• E2.4 非法转换拒绝（409 + valid_transitions）
• E2.5 列表筛选（status/assignee/parent_task）

E3: SubTask 父子关系（4 个测试）

• E3.1 创建父 Task + 3 个子 Task
• E3.2 list_subtasks 验证
• E3.3 top_level_tasks 排除子 Task
• E3.4 子 Task 的 stage 字段

E4: Stage 进度（3 个测试）

• E4.1 带 stages_json 的父 Task → 子 Task 分配到各 stage → progress 端点
• E4.2 空 stage 的父 Task 进度
• E4.3 stage 分组统计验证

E5: 父 Task 状态聚合（6 个测试）

• E5.1 all done → 父 done
• E5.2 has review → 父 review
• E5.3 has working → 父 working
• E5.4 all pending → 父 pending
• E5.5 cancelled 子 Task 排除
• E5.6 手动状态（cancelled 父 Task）不被覆盖

E6: 依赖链（3 个测试）

• E6.1 Task B depends_on Task A，A done 后 B 自动 pending（Ticker 推进）
• E6.2 A 未完成时 B 保持 blocked
• E6.3 多层依赖（A → B → C）

E7: 超时回收（2 个测试）

• E7.1 claimed 超时 → pending
• E7.2 working 超时 → failed

E8: Mail Tab 6 端点（7 个测试）

• E8.1 发送 Mail（inform 类型 → 自动 done）
• E8.2 发送 Mail（task-assign 类型 → pending）
• E8.3 Mail 列表 + 筛选（from/to/unread）
• E8.4 Mail 详情（含 comments）
• E8.5 标记已读
• E8.6 标记已执行
• E8.7 Mail summary + agents 列表

E9: 真实 Agent 调度（2 个测试）

• E9.1 创建简单 Task → Ticker 调度 → Agent spawn → Agent 回写 working → 完成任务
• E9.2 创建 review 类型 Task → 调度到 simayi-challenger → 回写 review 结果
• Agent 任务内容：简单的"echo hello"级别任务，10-30 秒完成

E10: 全链路集成（1 个测试）

• E10.1 创建项目 → 创建父 Task（stages_json）+ 3 个子 Task → Ticker tick → 依赖推进 → 聚合刷新 → Mail 通知 → 验证完整状态链

---

三、v2.8 新增测试场景（#07 Spawner Acquire-First + Prompt v3.0）

日期：2026-06-01 对应设计：docs/design/07-spawner-acquire-first.md、docs/design/03-prompt-evolution.md

E11: Spawner Acquire-First Phase 0-4（6 个测试）

• E11.1 Phase 0 Pre-acquire revive：任务 timeout/failed 状态 → Phase 0 自动 revive → Phase 1 acquire 成功
• E11.2 Phase 0 假死检测：status=running + lock PID 死 → Phase 0 自动 revive
• E11.3 Phase 1 Counter acquire 互斥：同 agent 并发 spawn → 第二个 AgentBusyError(reason=counter_blocked)
• E11.4 Phase 2 Session check 锁保护：counter acquire 后 → session check 在锁保护下执行 → session locked → release counter → AgentBusyError(reason=session_locked)
• E11.5 Phase 2 Blockers 收集：多 blocker 并列收集（locked + compact）→ 返回全部 blockers
• E11.6 Phase 3 on_checks_passed 异常回滚：on_checks_passed 抛异常 → counter 自动 release

E12: _check_timeouts 统一超时（4 个测试）

• E12.1 crash_limit 统一检查（working）：executor crash 3 次/30min → _check_timeouts 标 failed
• E12.2 crash_limit 统一检查（review）：reviewer crash 3 次/30min → _check_timeouts 标 failed（不再走 _dispatch_reviews 的 crash_limit）
• E12.3 updated_at fallback：mail auto-working 无 started_at/claimed_at → updated_at fallback 生效 → 超时回收
• E12.4 process_dead 对 review 状态：review agent 进程死 → 保持 review 状态（不推 pending）→ 等 _dispatch_reviews 处理

E13: Compact Hanging 不标 failed（3 个测试）

• E13.1 compact_hanging release counter：compact 等超限 → compact_hanging → release counter → 任务保持 working
• E13.2 compact_hanging 后 ticker 重新 dispatch：compact_hanging → ticker _check_timeouts 检测超时 → 推回 pending → 重新 dispatch
• E13.3 retry 遇 session busy 释放 counter：_do_retry 遇 AgentBusyError → release counter → 任务保持 working → ticker 重新 dispatch

E14: AgentBusyError 分类（3 个测试）

• E14.1 counter_blocked：counter acquire 失败 → AgentBusyError(reason=counter_blocked)
• E14.2 session_locked/running/compacting：Phase 2 各种 blocker → AgentBusyError 携带具体 reason + detail.blockers
• E14.3 Dispatcher 错误区分：dispatcher 捕获 AgentBusyError → 日志记录具体原因 → 路由决策写入 routing_decisions

E15: Prompt v3.0 验证（3 个测试）

这些是集成测试，需要真实 Agent。标记为 P1。

• E15.1 Claim prompt 三级响应：broadcast → Agent 不匹配 → 写 observation comment（非 NO_REPLY）
• E15.2 Executor prompt 任务式指挥：executor 不再收到步骤列表，收到意图+终态+约束 → 自主决策步骤
• E15.3 Reviewer prompt 挑战者思维：reviewer 审查时用挑战者视角 + confidence 自评

---

四、通过标准

• P0 必须全部通过：E1-E8 + E10 + E11-E14
• P1 通过率 ≥ 80%：E9 + E15（依赖真实 Agent，可能受网络/环境干扰）
• 总测试用例：约 58 个（原 37 + 新增 19 + Prompt 集成 3 减去合并的 1）

五、清理策略

测试完成后：

1. 删除测试项目目录（data/e2e-v27-*）
2. 清理 _mail 项目中测试数据
3. 不影响已有项目数据

六、变更记录

日期	版本	变更
2026-05-18	v2.7	初版，E1-E10 共 37 个测试
2026-06-01	v2.8	新增 E11-E15 共 19 个测试，覆盖 #07 Acquire-First、_check_timeouts 统一、Compact Hanging、AgentBusyError 分类、Prompt v3.0