auto-sync: 2026-06-05 23:03:50

docs/test-plan-e2e-v27.md

@@ -1,141 +1,652 @@
-# v2.7/v2.8 端到端测试方案
+# v3.0 测试体系设计
 
-> 日期：2026-05-18（v2.7 初版）→ 2026-06-01 更新（v2.8 #07 系列 + Prompt v3.0）
-> 作者：司马懿（初版）→ 庞统（v2.8 更新）
-> 环境：真实部署（`~/.sanguo_projects/sanguo_moziplus_v2/`）+ 真实 Agent
+> **作者**: 庞统（综合） + 司马懿（v30 草案 + 背靠背审查）
+> **日期**: 2026-06-05（v3.0 合并版）
+> **状态**: 待主公确认
+> **覆盖设计文档**: #01 四相循环 / #07 Acquire-First / #08 Classify / #09 Rebuttal / #06 PM2 恢复 / #04 黑板协作 / #10 T3 需求探索 / #12 Pipeline / architecture-v3.0
+> **替代**: 本文档替代 `docs/test-plan-e2e-v27.md`（v2.7 初版，2026-05-18）
 
 ---
 
-## 一、测试策略
+## 〇、设计原则（主公三原则 + 仲达补充）
 
-- **框架**：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 分组统计验证
+- E2E 不搞独立 daemon、独立进程、独立数据
+- 最终汇聚点是真实 Agent，独立环境测不出真实链路
+- 正确做法：**真实环境跑测试 → 测完清掉测试数据**
 
-### 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`
+### 1.1 现有测试的致命缺陷
 
-### E11: Spawner Acquire-First Phase 0-4（6 个测试）
+| 缺陷 | 根因 | 后果 |
+|------|------|------|
+| E2E 全部写真实 data_root | TestClient 直连生产 DB，无隔离 | 每次跑 `pytest tests/` 残留 e2e-v27 项目，PM2 重启触发广播风暴 |
+| E9-E14 cleanup 调不存在的 API | `/projects/{pid}/archive` 未实现 | 异常被吞，数据不清理 |
+| 无分层 | 单文件 62K，所有测试混在一起 | 改个小 bug 要跑全量 |
+| Agent 无意义响应 | 残留 pending 任务被 daemon 广播 | 浪费 token + 干扰正常工作 |
+| 无数据清理能力 | 项目删不掉、测试邮件堆积 | 测试和生产数据混杂 |
 
-- **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
+### 1.2 Review 发现的额外问题
 
-### 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 自评
+| 问题 | 说明 |
+|------|------|
+| **E14 编号冲突** | 设计文档 E14="AgentBusyError 分类"（3 个测试），代码 E14="Rollback"（1 个测试），同名不同义 |
+| **设计文档严重滞后** | v31 新增 9 个测试类 + test_four_phase.py ~20 个测试未入文档 |
+| **E15.2/E15.3 完全缺失** | Executor prompt / Reviewer prompt 无任何层级测试 |
+| **E2E gate 不统一** | E1-E8 无 RUN_INTEGRATION gate，E9-E14 有。现已统一加 gate |
 
 ---
 
-## 四、通过标准
+## 二、分层架构
 
-- **P0 必须全部通过**：E1-E8 + E10 + E11-E14
-- **P1 通过率 ≥ 80%**：E9 + E15（依赖真实 Agent，可能受网络/环境干扰）
-- **总测试用例**：约 58 个（原 37 + 新增 19 + Prompt 集成 3 减去合并的 1）
+### 2.1 三层测试金字塔
 
-## 五、清理策略
+```
+          ┌─────────────────────────────────┐
+          │           E2E 测试              │  marker: e2e
+          │    场景测试（串行）+ 压力测试     │  gate: RUN_INTEGRATION=1
+          │    真实 daemon + 真实 Agent      │  测完清理
+          ├─────────────────────────────────┤
+          │          集成测试                │  marker: integration
+          │       API 端点 + DB 交互        │  TestClient + tmp_path 隔离
+          ├─────────────────────────────────┤
+          │          单元测试                │  marker: unit (default)
+          │         纯逻辑·快               │  mock 所有外部依赖
+          └─────────────────────────────────┘
+```
 
-测试完成后：
-1. 删除测试项目目录（`data/e2e-v27-*`）
-2. 清理 `_mail` 项目中测试数据
-3. 不影响已有项目数据
+**关键规则：只有 E2E 层 spawn 真实 Agent。Unit 和 Integration 层不 spawn。**
 
-## 六、变更记录
+### 2.2 各层定位
+
+| 维度 | 单元测试 | 集成测试 | E2E 测试 |
+|------|---------|---------|---------|
+| **目标** | 验证单个函数/类的逻辑正确性 | 验证 API 端点 + DB 交互 | 验证完整链路（真实 Daemon + Agent） |
+| **数据** | mock/fixture | tmp_path + 独立 SQLite | 真实 data_root + 测试前缀隔离 |
+| **Agent** | ❌ 不 spawn | ❌ 不 spawn | ✅ 真实 spawn |
+| **清理** | N/A（不产生数据） | tmp_path 自动清理 | 清理 API teardown 删除 |
+| **速度** | <1s/测试 | 1-5s/测试 | 30-300s/测试 |
+| **频率** | 每次提交 | 改了 API 层跑 | 部署前（手动触发） |
+
+### 2.3 改动 → 测试映射（原则一）
+
+**改了 X，应该跑哪些测试？**
+
+| 改动的模块 | 必跑测试 | pytest 命令 |
+|-----------|---------|------------|
+| `src/blackboard/db.py`（数据模型） | unit/test_models + integration | `pytest tests/unit/test_models.py tests/integration/` |
+| `src/blackboard/db.py`（状态机） | unit/test_state_machine + integration | `pytest -m state_machine` |
+| `src/daemon/spawner.py`（classify） | unit/test_classify_outcome | `pytest -m classify` |
+| `src/daemon/spawner.py`（acquire/release） | unit/test_spawner + integration | `pytest tests/unit/test_spawner.py tests/integration/test_spawner_integration.py` |
+| `src/daemon/ticker.py`（广播） | unit/test_broadcast_tracker + integration | `pytest -m broadcast` |
+| `src/daemon/ticker.py`（超时） | unit/test_timeout + integration | `pytest tests/integration/test_ticker_integration.py -k timeout` |
+| `src/daemon/router.py` | unit/test_router | `pytest tests/unit/test_router.py` |
+| `src/daemon/counter.py` | unit/test_counter | `pytest tests/unit/test_counter.py` |
+| `src/daemon/dispatcher.py` | unit/test_dispatcher + integration | `pytest tests/unit/test_dispatcher.py tests/integration/test_dispatcher_integration.py` |
+| `src/api/mail_routes.py` | integration/test_api_mail | `pytest -m mail` |
+| `src/api/blackboard_routes.py` | integration/test_api_tasks + reviews | `pytest tests/integration/ -k task` |
+| `src/daemon/review.py` | unit/test_rebuttal + integration | `pytest -m review` |
+
+**快速验证**：`pytest -m "not e2e"`（~2-5 分钟，不含 E2E）
+
+---
+
+## 三、E2E 执行策略（原则四展开）
+
+### 3.1 两大类别
+
+| 类别 | 目标 | 执行方式 | 文件 |
+|------|------|---------|------|
+| **场景测试** | 逐个验证每个场景的正确性 | **严格串行**：一个 case 跑完 → 收集结果 → 根因分析（如有问题）→ 修 → 再跑下一个 | `test_e2e_scenarios.py` |
+| **压力测试** | 验证并发控制、全局上限、资源竞争 | **并行**：多任务同时 broadcast/dispatch/spawn | `test_e2e_stress.py` |
+
+### 3.2 场景测试流程（串行）
+
+```
+┌─────────────────────────────────────────────────────┐
+│  对每个 E2E 场景：                                    │
+│                                                      │
+│  1. 创建测试任务（e2e- 前缀）                          │
+│  2. 等待任务完成（轮询状态直到终态）                     │
+│  3. 收集结果                                          │
+│     ├── ✅ 通过 → 记录 → 清理 → 执行下一个场景          │
+│     └── ❌ 失败 → 根因分析 → 修复 → 重跑当前场景         │
+│  4. 清理测试数据（与诊断分离）                          │
+│                                                      │
+│  关键：一个场景彻底完成（通过或确认不修）才进入下一个      │
+└─────────────────────────────────────────────────────┘
+```
+
+**实现方式**：
+- pytest 默认串行执行（不用 xdist）
+- 每个测试函数是独立场景
+- `scope="module"` 的 fixture 共享 daemon 连接
+- 测试间无共享状态，各自创建/清理数据
+
+### 3.3 压力测试流程（并行）
+
+```
+┌─────────────────────────────────────────────────────┐
+│  压力测试（单独执行，场景测试全通过后）：                 │
+│                                                      │
+│  1. 同时创建 N 个任务（e2e-stress- 前缀）              │
+│  2. 验证并发行为：                                     │
+│     - counter 竞争：同 agent 并发 acquire → 第二个 blocked │
+│     - 全局上限：5/5 满载 → 新任务排队                   │
+│     - broadcast 并发：多任务同时广播 → 无死锁           │
+│     - spawn 互斥：同 session 不重复 spawn              │
+│  3. 全部完成后清理                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+### 3.4 数据清理与诊断分离
+
+```
+测试执行阶段 → 结果记录 → [可选] 数据保留用于诊断 → 清理阶段
+
+- 测试执行时：记录所有创建的资源 ID（manifest）
+- 通过时：立即清理
+- 失败时：保留数据供诊断，诊断完成后手动/脚本清理
+- 兜底：session 结束时 atexit 全量清理 e2e- 前缀
+```
+
+### 3.5 前置依赖：数据清理 API
+
+E2E 测试能安全运行的前提：
+
+| 需求 | API | 状态 |
+|------|-----|------|
+| 项目物理删除 | `DELETE /api/projects/{pid}?physical=true` | 待实现 |
+| 邮件批量删除 | `DELETE /api/mail?prefix=e2e-` | 待实现 |
+
+---
+
+## 四、E2E 场景清单
+
+> 编号规则：S = Scenario（场景测试），ST = Stress（压力测试）
+> 原文档 E1-E15 重新编号，解决 E14 冲突
+
+### 4.1 场景测试（S1-S15，串行执行）
+
+#### S1: 项目管理（4 个测试）| 对应 design: architecture-v3.0 §5
+
+- S1.1 创建项目（POST /api/projects）
+- S1.2 项目列表（GET /api/projects）
+- S1.3 自动发现（含 blackboard.db 的目录自动注册）
+- S1.4 归档项目（status=archived，目录不移动）
+
+#### S2: Task CRUD + 状态机（5 个测试）| 对应 design: architecture-v3.0 §5.2
+
+- S2.1 创建 Task（POST /api/projects/{pid}/tasks）
+- S2.2 查询 Task（GET，expand=all）
+- S2.3 合法状态转换（pending → claimed → working → review → done）
+- S2.4 非法转换拒绝（409 + valid_transitions）
+- S2.5 列表筛选（status/assignee/parent_task）
+
+#### S3: SubTask 父子关系（4 个测试）| 对应 design: architecture-v3.0 §5
+
+- S3.1 创建父 Task + 3 个子 Task
+- S3.2 list_subtasks 验证
+- S3.3 top_level_tasks 排除子 Task
+- S3.4 子 Task 的 stage 字段
+
+#### S4: Stage 进度（3 个测试）| 对应 design: architecture-v3.0 §5
+
+- S4.1 带 stages_json 的父 Task → 子 Task 分配到各 stage → progress 端点
+- S4.2 空 stage 的父 Task 进度
+- S4.3 stage 分组统计验证
+
+#### S5: 父 Task 状态聚合（6 个测试）| 对应 design: architecture-v3.0 §6.1
+
+- S5.1 all done → 父 done
+- S5.2 has review → 父 review
+- S5.3 has working → 父 working
+- S5.4 all pending → 父 pending
+- S5.5 cancelled 子 Task 排除
+- S5.6 手动状态（cancelled 父 Task）不被覆盖
+
+#### S6: 依赖链（3 个测试）| 对应 design: architecture-v3.0 §6.1
+
+- S6.1 Task B depends_on Task A，A done 后 B 自动 pending（Ticker 推进）
+- S6.2 A 未完成时 B 保持 blocked
+- S6.3 多层依赖（A → B → C）
+
+#### S7: 超时回收（2 个测试）| 对应 design: architecture-v3.0 §6.1
+
+- S7.1 claimed 超时 → pending
+- S7.2 working 超时 → failed
+
+#### S8: Mail（7 个测试）| 对应 design: architecture-v3.0 §12
+
+- S8.1 发送 Mail（inform 类型 → 自动 done）
+- S8.2 发送 Mail（task-assign 类型 → pending）
+- S8.3 Mail 列表 + 筛选（from/to/unread）
+- S8.4 Mail 详情（含 comments）
+- S8.5 标记已读
+- S8.6 标记已执行
+- S8.7 Mail summary + agents 列表
+
+#### S9: 真实 Agent 调度（3 个测试）| 对应 design: #01 四相循环
+
+- S9.1 创建简单 Task → Ticker 调度 → Agent spawn → Agent 回写 working → 完成任务
+- S9.2 创建 review 类型 Task → 调度到 simayi-challenger → 回写 review 结果
+- S9.3 Guardrail 拦截（不合法任务 → Agent 拒绝执行）
+
+**Agent 任务内容**：简单的"echo hello"级别任务，10-30 秒完成
+
+#### S10: 全链路集成（2 个测试）| 对应 design: #01 四相循环
+
+- S10.1 逻辑链（创建项目 → 父 Task + 子 Task → Ticker tick → 依赖推进 → 聚合刷新 → Mail 通知 → 验证完整状态链）
+- S10.2 Agent 全链（含真实 Agent spawn + 执行 + 产出 + review）
+
+#### S11: Spawner Acquire-First（6 个测试）| 对应 design: #07
+
+- S11.1 Phase 0 Pre-acquire revive：任务 timeout/failed → Phase 0 自动 revive → Phase 1 acquire 成功
+- S11.2 Phase 0 假死检测：status=running + lock PID 死 → Phase 0 自动 revive
+- S11.3 Phase 1 Counter acquire 互斥：同 agent 并发 spawn → 第二个 AgentBusyError(reason=counter_blocked)
+- S11.4 Phase 2 Session check 锁保护：counter acquire 后 → session check 在锁保护下执行 → session locked → release counter → AgentBusyError(reason=session_locked)
+- S11.5 Phase 2 Blockers 收集：多 blocker 并列收集（locked + compact）→ 返回全部 blockers
+- S11.6 Phase 3 on_checks_passed 异常回滚：on_checks_passed 抛异常 → counter 自动 release
+
+#### S12: 超时统一处理（4 个测试）| 对应 design: #08 §3.7
+
+- S12.1 crash_limit 统一检查（working）：executor crash 3 次/30min → _check_timeouts 标 failed
+- S12.2 crash_limit 统一检查（review）：reviewer crash 3 次/30min → _check_timeouts 标 failed
+- S12.3 updated_at fallback：mail auto-working 无 started_at/claimed_at → updated_at fallback 生效 → 超时回收
+- S12.4 process_dead 对 review 状态：review agent 进程死 → 保持 review 状态 → 等 _dispatch_reviews 处理
+
+#### S13: Compact Hanging（3 个测试）| 对应 design: #07 §4.5
+
+- S13.1 compact_hanging release counter：compact 等超限 → compact_hanging → release counter → 任务保持 working
+- S13.2 compact_hanging 后 ticker 重新 dispatch：compact_hanging → ticker _check_timeouts 检测超时 → 推回 pending → 重新 dispatch
+- S13.3 retry 遇 session busy 释放 counter：_do_retry 遇 AgentBusyError → release counter → 任务保持 working → ticker 重新 dispatch
+
+#### S14: AgentBusyError 分类（3 个测试）| 对应 design: #07 §2
+
+> ⚠️ 原设计文档 E14="AgentBusyError 分类"与代码中 E14="Rollback" 冲突，此处统一修正
+
+- S14.1 counter_blocked：counter acquire 失败 → AgentBusyError(reason=counter_blocked)
+- S14.2 session_locked/running/compacting：Phase 2 各种 blocker → AgentBusyError 携带具体 reason + detail.blockers
+- S14.3 Dispatcher 错误区分：dispatcher 捕获 AgentBusyError → 日志记录具体原因 → 路由决策写入 routing_decisions
+
+#### S15: Crash Rollback（1 个测试）| 对应 design: #07 §4.5
+
+> ⚠️ 原代码中 E14="Rollback"，现独立编号为 S15
+
+- S15.1 crash 后 current_agent 回退验证：Agent crash → current_agent 指针回退 → 任务可被重新 dispatch
+
+#### S16: 广播认领扩展（2 个测试）| 对应 design: architecture-v3.0 §8.3
+
+- S16.1 不匹配 Agent 写 observation comment（非 NO_REPLY）
+- S16.2 匹配 Agent 正常认领
+
+#### S17: Pause/Resume（1 个测试）| 对应 design: architecture-v3.0 §5.2
+
+- S17.1 paused → resumed_from 状态流转
+
+#### S18: Cancelled Restart（1 个测试）| 对应 design: architecture-v3.0 §5.2
+
+- S18.1 cancelled → pending 重启
+
+#### S19: Retry Chain（1 个测试）| 对应 design: #08 §3.3
+
+- S19.1 failed → pending retry 链路
+
+#### S20: Full Lifecycle with Review（1 个测试）| 对应 design: #09
+
+- S20.1 创建 → 认领 → 执行 → review → rebuttal → done 全链路
+
+#### S21: Cache Headers（3 个测试）| 对应 design: architecture-v3.0 §7
+
+- S21.1 HTML 不缓存
+- S21.2 JS/CSS immutable 缓存
+
+**场景测试合计：58 个测试**
+
+### 4.2 压力测试（ST1-ST3）
+
+#### ST1: 并发 Counter 竞争
+
+- 同时创建多个任务指定同一 Agent → 验证 counter acquire 互斥 → 第二个 blocked
+- 验证 counter release 后下一个 acquire 成功
+
+#### ST2: 全局并发上限
+
+- 同时创建 5 个任务指定不同 Agent → 全部 acquire 成功
+- 第 6 个 → 被拒绝或排队
+
+#### ST3: Broadcast 并发
+
+- 同时广播多个任务 → 无死锁
+- 验证广播计数器正确递增
+
+**压力测试合计：3 个测试组**
+
+### 4.3 Prompt 集成测试（P1，延后）
+
+> 以下场景需要验证 Agent prompt 行为，标 P1 延后
+
+- P1.1 Executor prompt 任务式指挥：executor 不再收到步骤列表，收到意图+终态+约束 → 自主决策步骤
+- P1.2 Reviewer prompt 挑战者思维：reviewer 审查时用挑战者视角 + confidence 自评
+
+---
+
+## 五、测试文件组织
+
+### 5.1 目录结构
+
+```
+tests/
+├── conftest.py                          # 全局 fixture + marker 注册 + atexit 清理兜底
+├── unit/                                # 单元测试（不 spawn 真实 Agent）
+│   ├── test_state_machine.py            # 状态机转换（architecture-v3.0 §5.2）
+│   ├── test_classify_outcome.py         # Classify 场景（#08 §3）
+│   ├── test_spawner.py                  # Spawner + Acquire-First（#07 §2）
+│   ├── test_router.py                   # Router 确定性路由
+│   ├── test_counter.py                  # Counter 并发控制
+│   ├── test_broadcast_claim.py          # BroadcastRound 逻辑 + bug fix 回归
+│   ├── test_mail_validation.py          # 邮件 A1-A10 校验（后并入 test_api_mail）
+│   ├── test_dispatcher.py               # Dispatcher 调度逻辑
+│   ├── test_review.py                   # Review + Rebuttal 逻辑
+│   ├── test_inbox.py                    # Inbox JSONL 解析
+│   ├── test_models.py                   # 数据模型
+│   ├── test_experience.py               # 经验蒸馏
+│   ├── test_bootstrap.py                # Bootstrap 上下文
+│   ├── test_health.py                   # 健康检查
+│   ├── test_cli.py                      # CLI 命令
+│   ├── test_skill_system.py             # Skill 匹配/推荐
+│   └── test_guardrails.py               # Guardrail 规则
+├── integration/                         # 集成测试（不 spawn 真实 Agent）
+│   ├── test_api.py                      # 项目管理 + Daemon API
+│   ├── test_api_mail.py                 # 邮件 API（A1-A10 防御 + 功能）
+│   ├── test_main.py                     # 健康端点 + 配置
+│   ├── test_dispatcher_integration.py   # Dispatcher 回滚
+│   ├── test_review_integration.py       # Review pipeline + scoring
+│   ├── test_spawner_integration.py      # Spawner 超时/失败（RUN_INTEGRATION gate）
+│   ├── test_ticker_integration.py       # Ticker 主循环 + 广播 + 超时 + 依赖推进
+│   ├── test_sse.py                      # SSE broker + hook manager
+│   └── test_v27_subtasks.py             # 子任务集成
+└── e2e/                                 # E2E 测试（spawn 真实 Agent）
+    ├── conftest.py                      # E2E fixture：清理 API + atexit 兜底 + manifest
+    ├── test_four_phase.py               # #01 四相循环
+    ├── test_e2e_scenarios.py            # S1-S21 场景测试（串行）
+    ├── test_e2e_stress.py               # ST1-ST3 压力测试（并行）
+    └── test_spawner_e2e.py              # Spawner 进程管理（timeout kill + spawn failure）
+```
+
+### 5.2 现有测试迁移映射
+
+| 现有文件 | 去向 | 处理 |
+|---------|------|------|
+| test_e2e_v27.py E1-E8 | integration/ | 重写为 API 集成测试，用 tmp_path 隔离 |
+| test_e2e_v27.py E9-E14 | e2e/test_e2e_scenarios.py | 按 S9-S15 重新编号 |
+| test_e2e_v31.py E94-E98 | e2e/test_e2e_scenarios.py | 按 S16-S21 编号 |
+| test_e2e_v31.py E10c/E10d | e2e/test_e2e_scenarios.py | 按 S19-S20 编号 |
+| test_four_phase.py | e2e/test_four_phase.py | 加 RUN_INTEGRATION gate |
+| test_spawner_e2e.py | e2e/test_spawner_e2e.py | 已有 gate ✅ |
+| test_api.py | integration/ | 保持 |
+| test_api_mail.py | integration/ | 保持 |
+| test_main.py | integration/ | 保持 |
+
+### 5.3 pytest marker 定义
+
+```python
+# conftest.py
+def pytest_configure(config):
+    markers = {
+        "unit": "单元测试：纯逻辑，mock 外部依赖",
+        "integration": "集成测试：API 端点 + 隔离数据",
+        "e2e": "端到端测试：真实环境（RUN_INTEGRATION=1 触发）",
+        "slow": "慢测试（>5s）",
+        "broadcast": "广播认领相关",
+        "mail": "邮件系统相关",
+        "state_machine": "状态机转换",
+        "classify": "Classify Outcome 相关",
+        "review": "审查/Rebuttal 相关",
+    }
+    for name, desc in markers.items():
+        config.addinivalue_line("markers", f"{name}: {desc}")
+```
+
+### 5.4 Gate 保护
+
+| 层级 | Gate | 说明 |
+|------|------|------|
+| unit | 无 | 纯 mock，安全 |
+| integration | 无 | tmp_path 隔离，安全 |
+| e2e | `RUN_INTEGRATION=1` | 所有 e2e 测试统一 gate，`@skip_no_integration` |
+
+---
+
+## 六、设计文档 → 测试覆盖映射（原则二）
+
+### 6.1 覆盖矩阵
+
+| 设计文档 | 关键行为 | 单元测试 | 集成测试 | E2E 测试 |
+|---------|---------|---------|---------|---------|
+| **architecture-v3.0.md** | 状态机、数据模型、API 契约 | P0 | P0 | — |
+| **#01 四相循环** | spawn→execute→classify→retry/advance | P1 | — | P0（S9-S10） |
+| **#07 Acquire-First** | Phase 0-4、AgentBusyError 区分 | P0 | P1 | P1（S11-S15） |
+| **#08 Classify Outcome** | A0-A14 + B1-B4 场景 | P0 | P1 | P1（S12） |
+| **#09 Rebuttal** | 审查流水线、2 轮反驳 | P1 | P0 | P1（S20） |
+| **#06 PM2 恢复** | 崩溃后状态恢复、zombie 检测 | P1 | — | P0 |
+| **#04 黑板协作** | @mention、comment、产出、review | P1 | P0 | P1 |
+| **#10 T3 需求探索** | 苏格拉底式对话、需求规格化 | P1 | — | — |
+| **#12 Pipeline** | task_type 路由、状态机约束 | P2 | P2 | — |
+
+### 6.2 模块 → 测试层级 → 优先级
+
+| 模块 | 单元 | 集成 | E2E | 对应设计文档 |
+|------|------|------|-----|-------------|
+| 状态机转换 | P0 | P0 | — | architecture-v3.0 §5.2 |
+| Classify Outcome | P0 | P1 | P1 | #08 §3 |
+| 广播认领 | P0 | P1 | P0 | architecture-v3.0 §8.3 |
+| 邮件系统 | P1 | P0 | P1 | architecture-v3.0 §12 |
+| Acquire-First | P0 | P1 | P1 | #07 §2 |
+| 四相循环 | P1 | — | P0 | #01 §2 |
+| Spawner 进程管理 | P0 | P1 | P1 | architecture-v3.0 §6.3 |
+| Counter 并发控制 | P0 | P1 | — | architecture-v3.0 §8.2 |
+| Router 路由 | P0 | P1 | — | architecture-v3.0 §8.1 |
+| Review/Rebuttal | P1 | P0 | P1 | #09 §2 |
+| Guardrail | P0 | P1 | — | architecture-v3.0 §14 |
+| 数据模型 | P0 | P0 | — | architecture-v3.0 §5 |
+| 依赖推进 | P0 | P1 | — | architecture-v3.0 §6.1 |
+| 超时检测 | P0 | P1 | P1 | architecture-v3.0 §6.1 |
+| @mention / 协作 | P1 | P0 | P1 | #04 |
+| Inbox JSONL | P0 | P1 | — | architecture-v3.0 §15 |
+| SSE 推送 | P1 | P0 | — | architecture-v3.0 §15 |
+| Bootstrap 上下文 | P1 | P1 | — | architecture-v3.0 §10 |
+| PM2 恢复 | P1 | — | P0 | #06 |
+
+---
+
+## 七、E2E 数据隔离与清理
+
+### 7.1 各层隔离策略
+
+| 层级 | 策略 | 清理方式 |
+|------|------|---------|
+| 单元 | mock / 不涉及 IO | 无残留 |
+| 集成 | `tmp_path` + 独立 SQLite | fixture teardown 自动清理 |
+| E2E | 真实 data_root + `e2e-` 前缀隔离 | 清理 API + atexit 兜底 |
+
+### 7.2 E2E 清理机制
+
+```python
+# tests/e2e/conftest.py
+
+@pytest.fixture(scope="session")
+def e2e_session_prefix():
+    """Session 级唯一前缀"""
+    return f"e2e-{uuid.uuid4().hex[:6]}-"
+
+@pytest.fixture(autouse=True)
+def e2e_cleanup(request):
+    """每个测试后清理，与诊断分离"""
+    created_pids = []
+    
+    def _track(pid):
+        created_pids.append(pid)
+    
+    yield  # 测试执行
+    
+    # 清理阶段
+    for pid in created_pids:
+        requests.delete(f"http://localhost:8083/api/projects/{pid}?physical=true")
+
+@pytest.fixture(scope="session", autouse=True)
+def e2e_session_cleanup(e2e_session_prefix):
+    """Session 结束时兜底清理"""
+    yield
+    # 批量清理所有 e2e- 前缀
+```
+
+### 7.3 atexit 兜底
+
+```python
+# tests/conftest.py（全局）
+
+import atexit
+
+def _emergency_cleanup():
+    """进程崩溃时的最后防线"""
+    # 批量删除所有 e2e- 前缀的项目和邮件
+    pass
+
+atexit.register(_emergency_cleanup)
+```
+
+---
+
+## 八、通过标准
+
+| 类别 | 标准 |
+|------|------|
+| **场景测试（S1-S21）** | 58 个全部通过。失败必须分析根因并修复后才继续 |
+| **压力测试（ST1-ST3）** | 3 个全部通过。验证并发控制无死锁 |
+| **P0 必须全部通过** | S1-S8 + S10 + S11-S14 |
+| **P1 通过率 ≥ 80%** | S9 + S15-S21 + ST1-ST3（依赖真实 Agent，可能受网络/环境干扰） |
+| **P1 延后** | P1.1/P1.2（Prompt 集成，待 Agent prompt 稳定后补） |
+| **速度** | 单元 < 30s，集成 < 5min，E2E 场景 < 60min，E2E 压力 < 30min |
+| **零残留** | 测试运行前后，`GET /projects?search=e2e-` 返回 0 条 |
+
+---
+
+## 九、实施计划
+
+### Phase 0：数据清理 API（前置依赖）
+
+| 任务 | API | 优先级 |
+|------|-----|--------|
+| 项目物理删除 | `DELETE /api/projects/{pid}?physical=true` | P0 |
+| 邮件批量删除 | `DELETE /api/mail?prefix=e2e-` | P0 |
+
+### Phase 1：基础设施
+
+| 任务 | 说明 |
+|------|------|
+| conftest.py 更新 | marker 注册 + atexit 清理兜底 + tmp_path fixture |
+| E2E conftest | 清理 API fixture + session 兜底 + manifest |
+| Gate 统一 | 所有 E2E 文件加 `@skip_no_integration` |
+
+### Phase 2：P0 单元测试（已有 394 passed）
+
+| 任务 | 对应设计文档 |
+|------|------------|
+| test_state_machine.py | architecture-v3.0 §5.2 |
+| test_classify_outcome.py | #08 §3 |
+| test_spawner.py（含 Acquire-First） | #07 §2 |
+| test_broadcast_claim.py | architecture-v3.0 §8.3 |
+| test_counter.py | architecture-v3.0 §8.2 |
+| test_guardrails.py | architecture-v3.0 §14 |
+
+### Phase 3：集成测试（已有 155 passed）
+
+| 任务 | 说明 |
+|------|------|
+| test_api_mail.py | A1-A10 + 批量删除（已到位） |
+| test_ticker_integration.py | 广播 + 超时 + 依赖推进 |
+| test_spawner_integration.py | acquire/release + 监控 |
+| test_dispatcher_integration.py | Router + Guardrail 调度 |
+
+### Phase 4：E2E 场景测试（串行）
+
+| 任务 | 覆盖设计文档 |
+|------|------------|
+| S1-S8 API 层场景 | architecture-v3.0 |
+| S9-S10 Agent 调度 | #01 四相循环 |
+| S11-S15 Spawner/Acquire | #07 + #08 |
+| S16-S21 扩展场景 | 各设计文档 |
+
+### Phase 5：E2E 压力测试（并行）
+
+| 任务 | 说明 |
+|------|------|
+| ST1 Counter 竞争 | 同 agent 并发 |
+| ST2 全局上限 | 多 agent 并发 |
+| ST3 Broadcast 并发 | 多任务广播 |
+
+---
+
+## 十、约束和风险
+
+### 10.1 约束
+
+1. **只有 E2E spawn 真实 Agent**：Unit 和 Integration 层不 spawn
+2. **E2E 用真实环境**：真实 daemon + 真实 Agent，`e2e-` 前缀隔离
+3. **场景测试串行**：一个完成再下一个，用时间换可靠性
+4. **压力测试并行**：单独一轮，场景测试全通过后执行
+5. **测试不依赖执行顺序**：每个测试独立创建/清理数据
+6. **全量 E2E 手动触发**：`RUN_INTEGRATION=1 pytest tests/e2e/`
+7. **测试数据前缀规范**：所有 E2E 项目名以 `e2e-` 开头
+
+### 10.2 风险
+
+| 风险 | 缓解 |
+|------|------|
+| E2E 场景测试影响生产 Agent | `e2e-` 前缀项目，串行执行减少干扰 |
+| 清理 API 失败导致残留 | atexit + session fixture 双保险 |
+| E2E 测试不稳定（Agent 响应慢） | 充分 timeout + retry + 失败时保留数据供诊断 |
+| 迁移现有测试引入回归 | 先迁移后验证，不删旧文件直到新测试全绿 |
+
+---
+
+## 十一、变更记录
 
 | 日期 | 版本 | 变更 |
 |------|------|------|
-| 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、广播三级响应 |
+| 2026-05-18 | v2.7 | 初版 E1-E10（仲达） |
+| 2026-06-01 | v2.8 | 新增 E11-E15（庞统） |
+| 2026-06-05 | v3.0 | 全面重写：三层分离 + 主公四原则 + 背靠背 review 修正 + E14 编号冲突修复 + 场景/压力分离 + 串行执行策略（庞统综合，基于仲达 v30 草案） |
+
+### v3.0 vs v2.8 关键变化
+
+| 维度 | v2.8 | v3.0 |
+|------|------|------|
+| E2E 执行策略 | 无明确规定 | 串行场景 + 并行压力分离 |
+| 编号体系 | E1-E15（E14 冲突） | S1-S21 + ST1-ST3（无冲突） |
+| Agent spawn | E1-E8 无 gate | 统一 RUN_INTEGRATION gate |
+| 数据隔离 | 未提及 | 真实 data_root + 清理 API + atexit 兜底 |
+| 设计覆盖 | 只管 E2E | 全三层 + 设计文档正推映射 |
+| 文件组织 | 两大文件 | 按模块拆分 + 命名规范 |