diff --git a/docs/design/development-plan-v2.6.md b/docs/design/development-plan-v2.6.md new file mode 100644 index 0000000..98f4472 --- /dev/null +++ b/docs/design/development-plan-v2.6.md @@ -0,0 +1,296 @@ +# 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 | 项目骨架+配置 | ⬜ 待开始 | — | — | +| F2 | 黑板核心 | ⬜ 待开始 | — | — | +| F3 | 多项目管理 | ⬜ 待开始 | — | — | +| F4 | CLI 工具 | ⬜ 待开始 | — | — | +| F5 | API 层 | ⬜ 待开始 | — | — | +| F6 | Daemon Ticker | ⬜ 待开始 | — | — | +| F7 | Inbox JSONL | ⬜ 待开始 | — | — | +| F8 | 健康检查 | ⬜ 待开始 | — | — | +| F9 | Agent 调度器 | ⬜ 待开始 | — | — | +| F10 | Counter | ⬜ 待开始 | — | — | +| F11 | Bootstrap | ⬜ 待开始 | — | — | +| F12 | 审查流水线 | ⬜ 待开始 | — | — | +| F13 | Guardrail | ⬜ 待开始 | — | — | +| F14 | 反驳权 | ⬜ 待开始 | — | — | +| F15 | 经验沉淀 | ⬜ 待开始 | — | — | +| F16 | Skill 体系 | ⬜ 待开始 | — | — | +| F17 | SSE+Hook | ⬜ 待开始 | — | — | +| F18 | 前端 Dashboard | ⬜ 待开始 | — | — | + +--- + +## 待确认区 + +开发过程中遇到的设计决策,按 AI native + 最优实践方向先执行,记录于此,用户明早 review。 + +> (暂无) + +--- + +## 参考实践来源 + +| 实践 | 来源项目 | 应用点 | +|------|---------|--------| +| 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 拼装不累积旧上下文 |