sanguo_moziplus_v2/docs/design/development-plan-v2.6.md

# v2.6 开发计划

**版本**: v2.6.0-plan
**基于**: technical-design-v2.6.md v2.6.3 + deployment-v2.6.md v2.6.3
**作者**: 庞统（副军师）🐦
**日期**: 2026-05-17
**状态**: 执行中

---

## 开发模式

- **分工**: 庞统编码（F1-F18 全部），司马懿测试+评审
- **流程**: 写完一个功能 → 单元测试 → 发司马懿评审 → 通过 → 下一个
- **参考实践**: superpowers（verify-before-complete）、oh-my-claudecode（Execution+Enhancement+Guarantee 三层）、hermes（僵尸检测+幻觉门控）
- **原则**: 每个功能一次做完，不分 phase；不确定的先记录待确认区，按 AI native + 最优实践方向先执行

---

## 开发顺序（按依赖拓扑）

```
Layer 0: F1 骨架 → F2 黑板
Layer 1: F3 多项目 → F4 CLI → F5 API
Layer 2: F6 Ticker → F7 Inbox → F8 健康检查
Layer 3: F9 调度器 → F10 Counter → F11 Bootstrap
Layer 4: F12 审查流水线 → F13 Guardrail → F14 反驳权
Layer 5: F15 经验沉淀 → F16 Skill
Layer 6: F17 SSE+Hook → F18 前端
```

### F1 项目骨架 + 配置体系

| 项目 | 内容 |
|------|------|
| **依赖** | 无 |
| **估计** | 1h |
| **产出** | `src/main.py`（FastAPI 空壳）+ `config/default.yaml` + `pyproject.toml` + `ecosystem.config.cjs` + `.gitignore` |
| **完成标准** | `pm2 start` 成功，`/api/daemon/status` 返回 200，`/docs` 自动文档可访问 |
| **测试** | `test_main.py`: 启动、健康端点、CORS |

### F2 黑板核心（DB + CRUD）

| 项目 | 内容 |
|------|------|
| **依赖** | F1 |
| **估计** | 3h |
| **产出** | `src/blackboard/{db,models,operations,queries}.py` + `schemas/*.json` |
| **完成标准** | 全部 9 表 CRUD 可用，WAL + busy_timeout + BEGIN IMMEDIATE，schema 校验通过 |
| **测试** | `test_blackboard.py`: create_task / claim / output / comment / decide / observe / review / events 写入 + 状态机转换 + 并发写入 |

### F3 多项目管理

| 项目 | 内容 |
|------|------|
| **依赖** | F1, F2 |
| **估计** | 2h |
| **产出** | `src/blackboard/registry.py` + `src/cli/admin.py`（project create/delete/list） |
| **完成标准** | CLI 创建项目 → per-project DB 自动创建 → `_registry.yaml` 更新 → list 显示正确 |
| **测试** | `test_registry.py`: create/delete/list + YAML 读写 + 并发注册 |

### F4 CLI 工具

| 项目 | 内容 |
|------|------|
| **依赖** | F1, F2 |
| **估计** | 2h |
| **产出** | `src/cli/blackboard.py`（8 个子命令） |
| **完成标准** | read / claim / output / comment / decide / observe / create / review 全部可用 |
| **测试** | `test_cli.py`: 每个子命令 happy path + 参数校验 + 错误处理 |

### F5 API 层

| 项目 | 内容 |
|------|------|
| **依赖** | F1, F2 |
| **估计** | 3h |
| **产出** | `src/api/{blackboard,daemon,project,sse}_routes.py` |
| **完成标准** | 全部 API 端点 curl 可用，Swagger 文档完整，SSE 端点可连接 |
| **测试** | `test_api.py`: 每个端点 CRUD + 状态码 + 参数校验 |

### F6 Daemon Ticker

| 项目 | 内容 |
|------|------|
| **依赖** | F2, F3, F5 |
| **估计** | 3h |
| **产出** | `src/daemon/ticker.py` |
| **完成标准** | 30s 循环运行，scan_tasks + 依赖推进 + events 写入正常，asyncio background task 与 FastAPI 共存 |
| **测试** | `test_ticker.py`: tick 循环 + 状态扫描 + 依赖推进 + 多项目轮询 |

### F7 Inbox JSONL Watcher

| 项目 | 内容 |
|------|------|
| **依赖** | F6 |
| **估计** | 1.5h |
| **产出** | `src/daemon/inbox.py` |
| **完成标准** | Agent 写 JSONL → 1s 内 Daemon 收到并处理 + truncate |
| **测试** | `test_inbox.py`: 写入+消费+truncate + 并发写入 + 损坏文件恢复 |

### F8 健康检查

| 项目 | 内容 |
|------|------|
| **依赖** | F6 |
| **估计** | 1h |
| **产出** | `src/daemon/health.py` |
| **完成标准** | 连续 20 tick 无变更 → observation 告警写入 |
| **测试** | `test_health.py`: 正常/僵尸/恢复 场景 |

### F9 Agent 调度器

| 项目 | 内容 |
|------|------|
| **依赖** | F6, F7 |
| **估计** | 3h |
| **产出** | `src/daemon/{dispatcher,spawner}.py` |
| **完成标准** | 三级调度（Daemon/Full/Sub）可用，`asyncio.create_subprocess_exec` spawn 不阻塞 event loop |
| **测试** | `test_dispatcher.py`: 三级决策树 + `test_spawner.py`: spawn + session 注册 + 超时 |

### F10 ActiveAgentCounter

| 项目 | 内容 |
|------|------|
| **依赖** | F9 |
| **估计** | 1h |
| **产出** | `src/daemon/counter.py` |
| **完成标准** | max_global=5 控制，per-agent 串行，acquire/release 正确 |
| **测试** | `test_counter.py`: 全局上限 + per-agent 串行 + 并发竞争 + release 恢复 |

### F11 Bootstrap 拼装

| 项目 | 内容 |
|------|------|
| **依赖** | F1, F2 |
| **估计** | 2h |
| **产出** | `src/daemon/bootstrap.py` + `prompt_templates/*.md` + `config/template_components.yaml` |
| **完成标准** | `build_bootstrap()` 按 role 拼装 L0-L3 四层，token 占用 < 4096 |
| **测试** | `test_bootstrap.py`: 各 role 拼装 + token 估算 + 缺失组件降级 |

### F12 审查流水线

| 项目 | 内容 |
|------|------|
| **依赖** | F9, F10, F11 |
| **估计** | 3h |
| **产出** | `src/daemon/review_flow.py` + `config/review_protocols/*.yaml` |
| **完成标准** | 4 级分级审查（high/standard/low/research）端到端可用，confidence 计算 + 升级逻辑正确 |
| **测试** | `test_review_flow.py`: 4 级分流 + confidence 阈值 + 升级庞统 |

### F13 Guardrail 系统

| 项目 | 内容 |
|------|------|
| **依赖** | F9, F11 |
| **估计** | 2h |
| **产出** | `src/daemon/guardrail.py` + `config/guardrails.yaml` |
| **完成标准** | L1 assert 自动执行 + L2 subagent 二次确认，配置驱动 |
| **测试** | `test_guardrail.py`: L1 通过/失败 + L2 触发 + 配置加载 + 误杀恢复 |

### F14 反驳权流程

| 项目 | 内容 |
|------|------|
| **依赖** | F12 |
| **估计** | 2h |
| **产出** | 集成在 `review_flow.py` + `prompt_templates/rebuttal.md` |
| **完成标准** | 审查不通过 → 反驳协商 → max_rounds → 庞统裁决 |
| **测试** | `test_rebuttal.py`: 反驳触发 + 轮次计数 + 超轮次升级 + 结果写入 |

### F15 经验沉淀

| 项目 | 内容 |
|------|------|
| **依赖** | F6, F2 |
| **估计** | 2h |
| **产出** | `src/daemon/experience.py` |
| **完成标准** | 任务完成 → 一级蒸馏 → experiences 表写入 → 二级蒸馏触发 → Skill 草稿生成 |
| **测试** | `test_experience.py`: 一级蒸馏 + tag 匹配 + 二级触发 + 过期清理 |

### F16 Skill 体系

| 项目 | 内容 |
|------|------|
| **依赖** | F15 |
| **估计** | 1.5h |
| **产出** | `src/daemon/skill_loader.py` + Skill 目录结构 |
| **完成标准** | Skill 四要素（name/description/triggers/actions）加载 + per-project 覆盖 + 生命周期管理 |
| **测试** | `test_skill_loader.py`: 加载 + 验证 + 覆盖 + 版本管理 |

### F17 SSE 推送 + Hook 系统

| 项目 | 内容 |
|------|------|
| **依赖** | F5, F6 |
| **估计** | 2h |
| **产出** | `src/api/sse_routes.py`（增强）+ `src/daemon/notifier.py` + Hook 触发点 |
| **完成标准** | SSE 4 级推送正常，降级轮询兜底，3 个 Hook 触发点工作 |
| **测试** | `test_sse.py`: 连接+推送+断线重连 + `test_hooks.py`: 触发+过滤 |

### F18 前端 Dashboard

| 项目 | 内容 |
|------|------|
| **依赖** | F5, F17 |
| **估计** | 8h |
| **产出** | `src/frontend/` 全部 5 页面 + 组件 |
| **完成标准** | TaskBoard + GlobalMonitor + ArtifactVault + SystemConfig + AIBriefing 全部可用，SSE 实时更新，项目切换器工作 |
| **测试** | `test_frontend.py`（E2E）: 页面渲染 + API 集成 + SSE 更新 + 项目切换 |

---

## 测试策略

### 单元测试（每个功能自带）

| 测试文件 | 覆盖模块 | 优先级 |
|----------|---------|--------|
| `test_main.py` | main.py 启动 + 配置 | P0 |
| `test_blackboard.py` | 黑板 CRUD + 并发 + WAL | P0 |
| `test_registry.py` | 多项目管理 | P0 |
| `test_cli.py` | CLI 8 子命令 | P0 |
| `test_api.py` | API 全端点 | P0 |
| `test_ticker.py` | Daemon tick 循环 | P0 |
| `test_inbox.py` | Inbox JSONL | P1 |
| `test_health.py` | 健康检查 | P1 |
| `test_dispatcher.py` | Agent 调度决策 | P0 |
| `test_spawner.py` | Agent spawn | P0 |
| `test_counter.py` | ActiveAgentCounter | P0 |
| `test_bootstrap.py` | Bootstrap 拼装 | P1 |
| `test_review_flow.py` | 审查流水线 | P0 |
| `test_guardrail.py` | Guardrail | P0 |
| `test_rebuttal.py` | 反驳权 | P0 |
| `test_experience.py` | 经验沉淀 | P1 |
| `test_skill_loader.py` | Skill 加载 | P1 |
| `test_sse.py` | SSE 推送 | P1 |
| `test_hooks.py` | Hook 系统 | P1 |
| `test_frontend.py` | 前端 E2E | P1 |

### 集成测试（F14 完成后）

端到端链路：用户提需求 → 庞统规划 → 任务写入 → Agent 执行 → Guardrail → 审查 → 反驳 → 完成 → 经验沉淀

### 司马懿职责

- 每个 F 编码完成后评审代码 + 审查测试覆盖
- F14 完成后执行集成测试
- F18 完成后执行 E2E 验收
- 发现问题写 Mail → 庞统修复 → 复审

---

## 进度追踪

| 序号 | 功能 | 状态 | 测试 | 评审 |
|------|------|------|------|------|
| F1 | 项目骨架+配置 | ✅ 完成 | ✅ 10/10 | ✅ 通过 |
| F2 | 黑板核心 | ✅ 完成 | ✅ 39/39 | ✅ 通过 |
| F3 | 多项目管理 | ✅ 完成 | ✅ 11/11 | ✅ 通过 |
| F4 | CLI 工具 | ✅ 完成 | ✅ 14/14 | ✅ 通过 |
| F5 | API 层 | ✅ 完成 | ✅ 23/23 | ✅ 通过 |
| F6 | Daemon Ticker | ✅ 完成 | ✅ 18/18 | ✅ 通过 |
| F7 | Inbox JSONL | ✅ 完成 | ✅ 16/16 | ✅ #277 |
| F8 | 健康检查 | ✅ 完成 | ✅ 16/16 | ✅ #277 |
| F9 | Agent 调度器 | ✅ 完成 | ✅ 29/29 | ✅ #278 |
| F10 | Counter | ✅ 完成 | ✅ 14/14 | ✅ #278 |
| F11 | Bootstrap | ✅ 完成 | ✅ 22/22 | ✅ #278 |
| F12 | 审查流水线 | ✅ 完成 | ✅ 20/20 | ✅ #278 |
| F13 | Guardrail | ✅ 完成 | (含F12) | ✅ #278 |
| F14 | 反驳权 | ✅ 完成 | (含F12) | ✅ #278 |
| F15 | 经验沉淀 | ✅ 完成 | ✅ 22/22 | ✅ #278 |
| F16 | Skill 体系 | ✅ 完成 | ✅ 24/24 | ✅ #278 |
| F17 | SSE+Hook | ✅ 完成 | ✅ 24/24 | ✅ #278 |
| F18 | 前端 Dashboard | ✅ 完成 | ✅ build | ✅ #279 |
| --- | **v2.8 状态增强 + M3 Checkpoint** | | | |
| v2.8 | 状态增强（paused/escalated/waiting_human + 归档 + 前端改造） | ✅ 设计完成 | ✅ 已完成 | ✅ #278-#280 |
| M3 | Checkpoint 机制 + Artifact 成果物面板 | ✅ 设计完成 | ✅ 已完成 | ✅ #280 |
| --- | **Agent 编排集成** | | | |
| F19 | Ticker 调度集成 | ✅ 设计完成 | ✅ 已完成 | ✅ 评审通过 |
| F20 | Spawner prompt 模板 | ✅ 设计完成 | ✅ 已完成 | ✅ 评审通过 |
| F21 | 审查流水线集成 | ✅ 设计完成 | ✅ 已完成 | ✅ 评审通过 |
| F22 | 前端 API 对接 | ✅ 设计完成 | ✅ 已完成 | ✅ 评审通过 |
| --- | **v3.0 集成 + 安全红线** | | | |
| G1 | HealthChecker → Ticker | ✅ 已完成 | ✅ 33/33 | ✅ #313 |
| G2 | BootstrapBuilder → Spawner | ✅ 已完成 | ✅ 测试通过 | ✅ #313 |
| G3 | InboxWatcher → Ticker | ✅ 已完成 | ✅ 33/33 | ✅ #313 |
| G4 | ExperienceDistiller → Ticker | ✅ 已完成 | ✅ 33/33 | ✅ #313 |
| G5 | 安全红线 Guardrails | ✅ 已完成 | ✅ 测试通过 | ✅ #316 |
| G6 | MorningPanel + ArtifactPanel 前端集成 | ✅ 已完成 | ✅ build | ✅ #313 |

---

## 待确认区

开发过程中遇到的设计决策，按 AI native + 最优实践方向先执行，记录于此，用户明早 review。

#### 2026-05-17 SQLite 3.51.0 CHECK 约束解析 bug

**发现**: SQLite 3.51.0 不允许 CHECK 约束作为列定义列表的中间项（带尾随逗号）。
```sql
-- ❌ 报错：near "foo": syntax error
CREATE TABLE t (status TEXT, CHECK (status IN ('a','b')), foo TEXT)
-- ✅ 正常：inline CHECK
CREATE TABLE t (status TEXT CHECK (status IN ('a','b')), foo TEXT)
```
**处理**: 所有 CHECK 约束改为内联方式（附在字段定义上）。
**影响**: 无功能影响，只是 SQL 写法不同。

#### 2026-05-17 BUG-1 修复：/api/daemon/status 端点重复注册

**发现**: 司马懿评审 F1-F5 时发现 main.py 和 daemon_routes.py 都注册了 `/api/daemon/status`，导致 Swagger 文档 Duplicate Operation ID warning。
**修复**: 删掉 main.py 中的定义，统一由 daemon_routes.py 提供。同时重构 main.py 将占位 ticker 替换为真实 Ticker 类。
**影响**: daemon_routes.py 新增 tick_count 字段，manual_tick 端点对接真实 Ticker。

---

## 参考实践来源

| 实践 | 来源项目 | 应用点 |
|------|---------|--------|
| verify-before-complete | superpowers (clawgator) | 每个 F 编码完必须测试通过才算 done |
| Execution+Enhancement+Guarantee | oh-my-claudecode | 三层质量保证：编码→增强→保障 |
| 僵尸检测+reclaim | hermes-agent | health.py 逻辑死循环检测 |
| 幻觉门控 | hermes-agent | Guardrail 产出物验证 |
| YAML frontmatter + preamble-tier | gstack | Skill 加载格式 |
| Wave Execution（新鲜上下文） | get-shit-done | Bootstrap 拼装不累积旧上下文 |