auto-sync: 2026-05-17 05:42:52

docs/design/test-plan-v2.6.md

@@ -0,0 +1,305 @@
+# v2.6 测试计划
+
+**版本**: v2.6.0-test-plan
+**作者**: 司马懿（质量总监）🗡️
+**日期**: 2026-05-17
+**状态**: F1-F5 已评审，F6-F18 待编码
+
+---
+
+## 一、测试基础设施
+
+### 1.1 当前配置
+
+- **框架**: pytest（已有 `tests/` 目录，97 个用例全部通过）
+- **Fixture**: `tmp_path`（SQLite 临时数据库）、`TestClient`（FastAPI）
+- **Mock 策略**: 目前无 mock，全部用真实 SQLite 内存/临时文件
+- **运行方式**: `python3 -m pytest tests/ -q`
+
+### 1.2 测试分层
+
+| 层级 | 覆盖范围 | 何时执行 |
+|------|---------|---------|
+| **单元测试** | 每个 F 的内部逻辑 | 每写完一个 F |
+| **集成测试** | F1-F14 端到端链路 | F14 完成后 |
+| **E2E 验收** | 完整系统含前端 | F18 完成后 |
+
+### 1.3 测试规范
+
+- 每个 F 必须有对应的 `test_*.py`，测试文件与模块同名
+- 测试类按功能分组：`class TestTaskCRUD`、`class TestTransitions` 等
+- P0 测试必须有，P1 测试建议有但不强阻塞
+- 测试必须可重复运行（不依赖外部状态、不依赖时序）
+- 新增测试必须在 `tests/` 目录下，不放在 `src/` 内
+
+---
+
+## 二、F1-F5 单元测试评审（已完成）
+
+### 现有覆盖情况
+
+| F | 测试文件 | 用例数 | P0 覆盖 | 评审 |
+|---|---------|--------|---------|------|
+| F1 骨架 | `test_main.py` | 10/10 | ✅ 启动、健康端点、配置、Swagger | 通过 |
+| F2 黑板 | `test_blackboard.py` | 39/39 | ✅ CRUD、状态机、并发、WAL、事件 | 通过（附 2 条意见） |
+| F3 多项目 | `test_registry.py` | 11/11 | ✅ 创建/删除/归档/持久化/黑板的联动 | 通过 |
+| F4 CLI | `test_cli.py` | 14/14 | ✅ 8 子命令 + admin + 错误处理 | 通过 |
+| F5 API | `test_api.py` | 23/23 | ✅ 全端点 CRUD + 状态码 + SSE 连接 | 通过（附 1 条意见） |
+
+**总计**: 97/97 通过，质量合格。
+
+### 评审意见（F1-F5）
+
+#### BUG-1 [P1] `/api/daemon/status` 端点重复注册
+- **位置**: `main.py` 第 99-111 行直接定义了 `daemon_status` 端点，同时 `daemon_routes.py` 也定义了同名路由
+- **现象**: pytest 输出 `Duplicate Operation ID daemon_status` warning
+- **修复**: 删除 `main.py` 中的 `/api/daemon/status` 端点定义，统一由 `daemon_routes.py` 提供
+- **影响**: 不影响功能，但 Swagger 文档会混乱
+
+#### OBS-1 [P2] `operations.py` 的 `_conn()` 每次操作都新建连接
+- **位置**: `operations.py` 全文，每次方法调用 `self._conn()` → `sqlite3.connect()`
+- **现状**: 单次操作用完即关，连接不池化
+- **评估**: v2.6 阶段可接受（SQLite WAL + busy_timeout 足够），但如果后续 F6 ticker 30s 轮询 + 多项目并发，建议 F6 阶段引入连接池或 `per-thread` 连接复用
+- **行动**: 不阻塞当前进度，F6 编码时再评估性能
+
+#### OBS-2 [P2] `queries.py` 的 `blocked_tasks_with_deps()` 和 `pending_dispatchable()` 存在 SQL 注入风险
+- **位置**: `queries.py` 第 52 行和第 71 行，使用 `f-string` 拼接 SQL
+- **现象**: `f"SELECT ... WHERE id IN ({','.join('?' * len(deps))})"` — 虽然 `deps` 来自数据库的 `depends_on` 字段（不是用户输入），且用了参数化占位符，但 `f-string` 拼接 SQL 是坏习惯
+- **评估**: 当前实际安全（因为值都来自参数化 `?`），但风格不好
+- **行动**: 不阻塞，但后续统一改为纯参数化写法
+
+---
+
+## 三、F6-F18 测试计划（逐模块）
+
+### F6 Daemon Ticker — `test_ticker.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | tick 循环正常运行 | ✅ | 30s 间隔（测试中加速），不阻塞 event loop |
+| T2 | scan_tasks 检测 pending | ✅ | pending → 触发调度 |
+| T3 | 依赖推进 | ✅ | blocked → pending（依赖 done 后） |
+| T4 | events 写入 | ✅ | 每次 tick 写 `daemon_tick` 事件 |
+| T5 | 多项目轮询 | ✅ | tick 遍历所有 active 项目 |
+| T6 | tick 异常不中断 | P1 | 单次 tick 抛异常 → 下次 tick 继续 |
+| T7 | 手动 tick 端点 | P1 | POST /api/daemon/tick 触发即时 tick |
+
+### F7 Inbox JSONL Watcher — `test_inbox.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | 写入+消费 | ✅ | Agent 写 JSONL → 1s 内 Daemon 读取并处理 |
+| T2 | truncate | ✅ | 消费后清空文件 |
+| T3 | 并发写入 | ✅ | 多 Agent 同时写不同行 |
+| T4 | 损坏行恢复 | P1 | 非法 JSON 行跳过不崩溃 |
+| T5 | 空文件处理 | P1 | 空文件不触发处理 |
+
+### F8 健康检查 — `test_health.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | 正常场景 | ✅ | 有变更 → 无告警 |
+| T2 | 僵尸检测 | ✅ | 连续 N tick 无变更 → observation 写入 |
+| T3 | 恢复场景 | ✅ | 僵尸后有变更 → 告警解除 |
+| T4 | 多项目独立检测 | P1 | 项目 A 僵尸不影响项目 B |
+
+### F9 Agent 调度器 — `test_dispatcher.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | 三级决策树 | ✅ | Daemon task → Full task → Sub task 正确分流 |
+| T2 | 调度不阻塞 | ✅ | spawn 用 `asyncio.create_subprocess_exec` |
+| T3 | 队列满拒绝 | ✅ | active agent 数达上限 → 不调度 |
+| T4 | 任务优先级排序 | P1 | 高优先级先调度 |
+
+### F9 Agent Spawner — `test_spawner.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | spawn 成功 | ✅ | 子进程启动 + session 注册 |
+| T2 | 超时处理 | ✅ | 超时后 kill + task_attempt 记录 |
+| T3 | spawn 失败 | ✅ | 命令不存在 → task_attempt 记录 spawn_failed |
+| T4 | session 清理 | P1 | 子进程结束后 session 归档 |
+
+### F10 ActiveAgentCounter — `test_counter.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | 全局上限 | ✅ | max_global=5 时第 6 个 acquire 失败 |
+| T2 | per-agent 串行 | ✅ | 同一 agent 第二个 acquire 排队 |
+| T3 | release 恢复 | ✅ | release 后等待中的 acquire 成功 |
+| T4 | 并发竞争 | P1 | 多 agent 同时 acquire 不超限 |
+
+### F11 Bootstrap 拼装 — `test_bootstrap.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | 各 role 拼装 | ✅ | 不同 role 得到不同 L0-L3 四层 |
+| T2 | token 估算 | ✅ | 拼装结果 < 4096 tokens |
+| T3 | 缺失组件降级 | P1 | 某层文件不存在 → 跳过不崩溃 |
+| T4 | 模板变量替换 | P1 | `{{task_id}}` 等占位符正确替换 |
+
+### F12 审查流水线 — `test_review_flow.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | 4 级分流 | ✅ | high/standard/low/research 正确路由 |
+| T2 | confidence 计算 | ✅ | 分值在 0-1 区间，阈值逻辑正确 |
+| T3 | 升级到庞统 | ✅ | confidence < 阈值 → 升级 |
+| T4 | 审查通过 → done | ✅ | verdict=approved → 状态变 done |
+| T5 | 审查拒绝 → 重新执行 | P1 | verdict=rejected → 回到 working |
+
+### F13 Guardrail — `test_guardrail.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | L1 assert 通过 | ✅ | 合规产出 → 放行 |
+| T2 | L1 assert 失败 | ✅ | 不合规产出 → 拦截 |
+| T3 | L2 subagent 触发 | ✅ | 高风险 → 二次确认 |
+| T4 | 配置加载 | P1 | `guardrails.yaml` 正确解析 |
+| T5 | 误杀恢复 | P1 | L2 确认通过 → 放行 |
+
+### F14 反驳权 — `test_rebuttal.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | 反驳触发 | ✅ | review rejected → 反驳协商开始 |
+| T2 | 轮次计数 | ✅ | round 递增正确 |
+| T3 | 超轮次升级 | ✅ | 超过 max_rounds → 庞统裁决 |
+| T4 | 结果写入 | ✅ | 最终裁决写入 reviews 表 |
+
+### F15 经验沉淀 — `test_experience.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | 一级蒸馏 | ✅ | 任务完成 → experiences 表写入 |
+| T2 | tag 匹配 | ✅ | 相似 tag 的经验可被查询到 |
+| T3 | 二级触发 | P1 | N 条同类经验 → Skill 草稿生成 |
+| T4 | 过期清理 | P1 | deprecated 经验不被查询 |
+
+### F16 Skill 体系 — `test_skill_loader.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | 加载 + 验证 | ✅ | 四要素完整才加载 |
+| T2 | per-project 覆盖 | ✅ | 项目级 Skill 覆盖全局 Skill |
+| T3 | 缺要素拒绝 | P1 | 缺少 name/description/triggers/actions → 拒绝 |
+| T4 | 版本管理 | P1 | 同名 Skill 版本号正确比较 |
+
+### F17 SSE + Hook — `test_sse.py` / `test_hooks.py`
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | SSE 连接 | ✅ | 客户端连接 → 收到初始事件 |
+| T2 | SSE 4 级推送 | ✅ | task/agent/daemon/system 四级 |
+| T3 | 断线重连 | P1 | 断线后重连 → 收到后续事件 |
+| T4 | 降级轮询 | P1 | SSE 不可用 → 轮询兜底 |
+| T5 | Hook 触发 | ✅ | 3 个触发点正确执行 |
+| T6 | Hook 过滤 | P1 | 条件不满足 → 不触发 |
+
+### F18 前端 Dashboard — `test_frontend.py`（E2E）
+
+| # | 测试用例 | P0 | 验证点 |
+|---|---------|-----|-------|
+| T1 | 页面渲染 | ✅ | 5 个页面均可加载 |
+| T2 | API 集成 | ✅ | 页面操作 → API 调用正确 |
+| T3 | SSE 实时更新 | ✅ | 后端事件 → 前端 UI 更新 |
+| T4 | 项目切换 | ✅ | 切换项目 → 数据刷新 |
+
+---
+
+## 四、集成测试计划（F14 完成后）
+
+### 端到端链路测试
+
+```
+用户提需求 → 庞统规划 → 任务写入黑板 → Agent 执行 → 
+Guardrail 检查 → 审查流水线 → 反驳协商 → 完成 → 经验沉淀
+```
+
+| # | 场景 | 关键验证 |
+|---|------|---------|
+| I1 | 正常流程（happy path） | 全链路无阻断，最终 done |
+| I2 | 依赖链 | A→B→C，A done 后 B 自动 pending，B done 后 C 自动 pending |
+| I3 | 审查拒绝 → 反驳 → 通过 | review rejected → rebuttal → verdict 翻转 |
+| I4 | 审查拒绝 → 反驳 → 超轮次 → 庞统裁决 | max_rounds 后升级 |
+| I5 | Guardrail 拦截 → L2 确认 → 放行 | L1 fail → L2 confirm → proceed |
+| I6 | Agent 僵尸检测 | 无 heartbeat → observation → reclaim |
+| I7 | 多项目并行 | 项目 A/B 同时运行，互不干扰 |
+| I8 | 失败重试 | failed → pending（retry_count +1）→ 再次执行 |
+
+### 集成测试基础设施
+
+```python
+# conftest.py 需要的 fixture
+@pytest.fixture
+def full_stack(tmp_path):
+    """完整系统：FastAPI + Ticker + Dispatcher + Spawner(mock)"""
+    ...
+
+@pytest.fixture
+def mock_spawner():
+    """Mock spawner，模拟 Agent 执行"""
+    ...
+```
+
+---
+
+## 五、E2E 验收场景（F18 完成后）
+
+| # | 场景 | 验收标准 |
+|---|------|---------|
+| E1 | 创建项目 → 提交任务 → 查看任务板 | Dashboard 实时更新 |
+| E2 | 全局监控页 | 所有项目状态汇总、活跃 Agent 数、最近事件 |
+| E3 | 产物仓库页 | 任务产出物可浏览、可下载 |
+| E4 | 系统配置页 | 运行时配置可查看、Skill 列表可管理 |
+| E5 | AI 简报页 | 项目级 AI 总结可生成 |
+| E6 | SSE 实时 | 所有页面操作后 SSE 实时反映 |
+
+---
+
+## 六、测试通过标准
+
+### 每个 F 的单元测试通过标准
+
+1. **全部 P0 用例通过**（硬性要求）
+2. **P1 用例通过率 ≥ 80%**（可协商）
+3. **无 crash / 无未捕获异常**
+4. **测试可重复运行**（跑 3 次结果一致）
+
+### 集成测试通过标准
+
+1. **I1-I8 全部场景通过**
+2. **无死锁、无资源泄漏**
+3. **并发测试无数据竞争**
+
+### E2E 验收标准
+
+1. **E1-E6 全部场景通过**
+2. **前端无 console error**
+3. **SSE 延迟 < 2s**
+
+---
+
+## 七、进度追踪
+
+| F | 测试计划 | 用例设计 | 编码 | 执行 | 评审 |
+|---|---------|---------|------|------|------|
+| F1 | ✅ | ✅ 10 | ✅ | ✅ 10/10 | ✅ 通过 |
+| F2 | ✅ | ✅ 39 | ✅ | ✅ 39/39 | ✅ 通过（附 2 条意见） |
+| F3 | ✅ | ✅ 11 | ✅ | ✅ 11/11 | ✅ 通过 |
+| F4 | ✅ | ✅ 14 | ✅ | ✅ 14/14 | ✅ 通过 |
+| F5 | ✅ | ✅ 23 | ✅ | ✅ 23/23 | ✅ 通过（附 1 条意见） |
+| F6 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F7 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F8 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F9 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F10 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F11 | ✅ 本文档 | ⬜ 本文档 | ⬜ | — | — |
+| F12 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F13 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F14 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F15 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F16 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F17 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |
+| F18 | ✅ 本文档 | ⬜ 待设计 | ⬜ | — | — |