# 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 |
| 2026-06-01 | v2.8.1 | 新增 E11-E14 真实 Agent E2E（6 个集成测试）+ E15 Prompt v3.0 E2E（2 个集成测试），覆盖 Acquire-First 真实调度、crash_limit 真实回收、updated_at fallback、compact_hanging 不标 failed、crash rollback、广播三级响应 |