From d40a38fc4a17062ba40d353a753f3a668bf32463 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Tue, 19 May 2026 22:26:22 +0800 Subject: [PATCH] auto-sync: 2026-05-19 22:26:22 --- docs/review/backend-audit.md | 456 +++++++++++++++++++++++++++++++++++ 1 file changed, 456 insertions(+) create mode 100644 docs/review/backend-audit.md diff --git a/docs/review/backend-audit.md b/docs/review/backend-audit.md new file mode 100644 index 0000000..557488a --- /dev/null +++ b/docs/review/backend-audit.md @@ -0,0 +1,456 @@ +# 后端代码 vs 设计文档对照审查报告 + +> 审查人：庞统（副军师）🐦 +> 日期：2026-05-19 +> 代码版本：v2.7.0（main.py 声明） +> 设计文档版本：architecture-v2.6 + v2.7-subtask-model + v2.8-state-enhancement 等 + +--- + +## 后端模块审查 + +### main.py (文件: src/main.py, 253行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| FastAPI + Daemon ticker 共享 asyncio event loop | architecture-v2.6 §2 架构总览; technical-design §5.3 | ✅ 已实现 | lifespan() 中启动 Ticker，yield 时 stop | +| YAML 配置加载 | technical-design §2.1 | ✅ 已实现 | config/default.yaml, L42-52 | +| Ticker 全局实例 | architecture-v2.6 §4 | ✅ 已实现 | get_ticker() 全局访问器 | +| ProjectRegistry 初始化 | v2.7-subtask-model §3 | ✅ 已实现 | get_registry(), L82 | +| YAML 迁移 + 自动发现 | v2.7-subtask-model §3 | ✅ 已实现 | registry.migrate_from_yaml() + discover_projects(), L76-82 | +| Agent Profiles 配置驱动 | agent-routing-redesign §4 | ✅ 已实现 | 从 daemon.agent_profiles 构建 AgentProfile, L97-106 | +| LLM Driver 构建（Mode A 路由） | agent-routing-redesign §4.2 | ✅ 已实现 | 从 daemon.routing 构建 LLMDriver, L109-120 | +| Router + Dispatcher + Spawner + Counter 组件装配 | agent-integration-v2.6 §4.1 | ✅ 已实现 | L122-142 | +| CORS 中间件 | technical-design §9 | ✅ 已实现 | L171-177 | +| 6 组 API 路由注册 | technical-design §9 | ✅ 已实现 | blackboard/checkpoint/daemon/project/sse/mail, L181-192 | +| /api/projects 兼容端点 | 无 | ✅ 已实现(超前) | 兼容旧前端, L197-201 | +| 前端静态文件服务 | architecture-v2.6 §11 | ✅ 已实现 | DIST_DIR mount, L208-210 | +| 版本号 2.7.0 | v2.7-subtask-model | ✅ 已实现 | FastAPI(version="2.7.0"), L166 | +| 日志配置 | technical-design §5 | ✅ 已实现 | _setup_logging(), L31-46 | + +### blackboard/models.py (文件: src/blackboard/models.py, 182行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| Task dataclass | architecture-v2.6 §3.2 | ✅ 已实现 | 包含全部设计字段 + v2.6.1/v2.7/v2.8 扩展 | +| Task.from_row() 安全构造 | 无设计文档 | ✅ 已实现(超前) | 防止 DB 新增字段导致构造失败 | +| Comment dataclass | architecture-v2.6 §3.2 | ✅ 已实现 | 含 comment_type、mentions | +| Output dataclass | architecture-v2.6 §3.2 | ✅ 已实现 | 含 attempt_number、metadata | +| Decision dataclass | architecture-v2.6 §3.2 | ✅ 已实现 | 含 alternatives | +| Observation dataclass | architecture-v2.6 §3.2 | ✅ 已实现 | 含 severity、resolved_by/at | +| Event dataclass | architecture-v2.6 §3.2 | ✅ 已实现 | task_id 可选（全局事件） | +| Review dataclass | architecture-v2.6 §9.6 | ✅ 已实现 | 含 round、max_rounds、consensus_reached、confidence | +| Experience dataclass | architecture-v2.6 §9.6 / v2.6.7 | ✅ 已实现 | 含 tags（独立查询）、skill_id、usage_count | +| Task v2.6.1 路由扩展字段 | agent-routing-redesign §5 | ✅ 已实现 | current_agent, previous_agent, next_capability | +| Task v2.7 SubTask 字段 | v2.7-subtask-model §2.1 | ✅ 已实现 | stage, stages_json | +| Task v2.8 归档字段 | v2.8-state-enhancement §二 | ✅ 已实现 | archived, archived_at | + +### blackboard/db.py (文件: src/blackboard/db.py, 444行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| tasks 表 Schema | architecture-v2.6 §3.2 | ✅ 已实现 | 完整匹配设计，含 CHECK 约束 | +| comments 表 Schema | architecture-v2.6 §3.5 | ✅ 已实现 | 含 comment_type CHECK | +| outputs 表 Schema | architecture-v2.6 §3.2 | ✅ 已实现 | 含 output_type CHECK | +| decisions 表 Schema | architecture-v2.6 §3.2 | ✅ 已实现 | | +| observations 表 Schema | architecture-v2.6 §3.2 | ✅ 已实现 | 含 severity CHECK | +| events 表 Schema | architecture-v2.6 §3.2 | ✅ 已实现 | 索引 on task_id + created_at | +| agents 表 Schema | technical-design §4.2 | ✅ 已实现 | | +| task_attempts 表 Schema | architecture-v2.6 §4.3 | ✅ 已实现 | 含 outcome CHECK | +| reviews 表 Schema | architecture-v2.6 §9.6 | ✅ 已实现 | 含 review_type + verdict CHECK | +| experiences + experience_tags 表 | architecture-v2.6 §9.6 / v2.6.7 | ✅ 已实现 | 含 source/category/status CHECK | +| routing_decisions 表 | agent-routing-redesign §5 | ✅ 已实现 | 含 mode CHECK, 3 索引 | +| checkpoints 表 | v2.8-state-enhancement §四.4 | ✅ 已实现 | 含 type + status CHECK, M3 | +| 11 状态 + CHECK 约束 | v2.8-state-enhancement §1.2 | ✅ 已实现 | pending/claimed/working/review/paused/escalated/waiting_human/done/failed/blocked/cancelled | +| 状态机 VALID_TRANSITIONS | v2.8-state-enhancement §1.2 | ✅ 已实现 | 完全匹配设计文档的状态转换表 | +| TERMINAL_STATUSES | v2.8-state-enhancement §1.2 | ✅ 已实现 | {done} — cancelled 已从终态移除? | +| MANUAL_STATUSES | v2.7-subtask-model §2.2 | ✅ 已实现 | {cancelled, paused} — 不参与聚合 | +| WAL + busy_timeout + foreign_keys | technical-design §2.2 | ✅ 已实现 | _connect() L284-287 | +| v2.6.1 数据迁移 | agent-routing-redesign | ✅ 已实现 | _migrate_v261(): current_agent 等字段 | +| v2.7 数据迁移 | v2.7-subtask-model §2.1 | ✅ 已实现 | _migrate_v27(): stages_json + stage | +| v2.8 数据迁移（重建表） | v2.8-state-enhancement §二.3 | ✅ 已实现 | _migrate_v28(): CHECK 更新 + 归档字段 + checkpoints + outputs 扩展 | +| COMMENT_TYPES | architecture-v2.6 §3.5 / §9.5 | ✅ 已实现 | 含 debate 系列 | +| EVENT_TYPES | architecture-v2.6 §4.2 | ✅ 已实现 | 含 v2.8 的 archived/unarchived | +| outputs 扩展字段（M3） | v2.8-state-enhancement §五.1 | ✅ 已实现 | file_name/file_size/file_path/mime_type | + +**⚠️ 注意**: TERMINAL_STATUSES 只有 `{done}`，cancelled 设计文档中也是终态（`cancelled: []`），但代码中 cancelled 不在 TERMINAL_STATUSES 里。实际上 VALID_TRANSITIONS 中 cancelled 的目标为空集，效果等价，但语义上应加入。 + +### blackboard/operations.py (文件: src/blackboard/operations.py, 823行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| Blackboard 类 | architecture-v2.6 §3.4 | ✅ 已实现 | per-project SQLite | +| create_task | architecture-v2.6 §3.4 | ✅ 已实现 | 含事件写入 | +| get_task | architecture-v2.6 §3.4 | ✅ 已实现 | | +| update_task_status | architecture-v2.6 §3.3/§3.4 | ✅ 已实现 | 校验合法转换 + 事件写入 + 时间戳 | +| claim_task（原子 CAS） | architecture-v2.6 §3.6 | ✅ 已实现 | BEGIN IMMEDIATE + WHERE status='pending' | +| list_tasks | architecture-v2.6 §3.4 | ✅ 已实现 | 支持 status/assignee/parent_task 过滤 | +| add_comment | architecture-v2.6 §3.5 | ✅ 已实现 | 含 comment_type 校验 + 事件 | +| get_comments | architecture-v2.6 §3.5 | ✅ 已实现 | 支持 comment_type 过滤 | +| write_output | architecture-v2.6 §3.2 | ✅ 已实现 | 含 output_type 校验 + 事件 | +| get_outputs | architecture-v2.6 §3.2 | ✅ 已实现 | | +| add_decision | architecture-v2.6 §3.2 | ✅ 已实现 | 含事件 | +| add_observation | architecture-v2.6 §3.2 | ✅ 已实现 | 含 severity | +| add_review | architecture-v2.6 §9.6 | ✅ 已实现 | 含 review_type + verdict 校验 | +| add_experience | architecture-v2.6 §9.6 / v2.6.7 | ✅ 已实现 | 含 tags 处理 | +| query_experiences | architecture-v2.6 §9.6 | ✅ 已实现 | 支持 tag 过滤 + usage_count 排序 | +| touch_experience | architecture-v2.6 v2.6.7 | ✅ 已实现 | 引用计数 +1 | +| add_task_attempt | architecture-v2.6 §4.3 | ✅ 已实现 | | +| Agent CRUD（upsert/get/update_status） | architecture-v2.6 §3.2 | ✅ 已实现 | | +| archive_task / unarchive_task | v2.8-state-enhancement §二.1 | ✅ 已实现 | 含事件写入 | +| archive_done_tasks | v2.8-state-enhancement §二.1 | ✅ 已实现 | 一键归档 done 任务 | +| Checkpoint CRUD | v2.8-state-enhancement §四 | ✅ 已实现 | create/list/get/resolve | +| Checkpoint approve/reject 状态推进 | v2.8-state-enhancement §四.3 | ✅ 已实现 | verify→done, 其他→working; reject→working | +| BUG-32 安全校验（waiting_human） | v2.8-state-enhancement §四.3 | ✅ 已实现 | resolve_checkpoint() 校验 task_status | +| BUG-33 payload 结构校验 | v2.8-state-enhancement §四.4 | ✅ 已实现 | version 字段必须存在 | +| update_must_haves | architecture-v2.6 §9 | ✅ 已实现 | 用于 Mail 元数据 | + +### blackboard/queries.py (文件: src/blackboard/queries.py, 356行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| task_summary | architecture-v2.6 §3.4 | ✅ 已实现 | GROUP BY status | +| tasks_by_assignee | architecture-v2.6 §3.4 | ✅ 已实现 | | +| blocked_tasks_with_deps | architecture-v2.6 §4.2 | ✅ 已实现 | 依赖链查询 | +| pending_dispatchable | architecture-v2.6 §4.2 | ✅ 已实现 | 依赖全部满足的 pending 任务 | +| recent_events | architecture-v2.6 §4.2 | ✅ 已实现 | | +| task_detail 聚合 | architecture-v2.6 §5.2 | ✅ 已实现 | comments_count + outputs_count + review_status | +| list_subtasks | v2.7-subtask-model §2.1 | ✅ 已实现 | parent_task 过滤 | +| top_level_tasks | v2.7-subtask-model §2.6 | ✅ 已实现 | parent_task IS NULL | +| compute_parent_status | v2.7-subtask-model §2.2 | ✅ 已实现 | 聚合优先级：escalated > waiting_human > review > working > pending > failed > blocked | +| MANUAL_STATUSES 不参与聚合 | v2.7-subtask-model §2.2 | ✅ 已实现 | cancelled + paused 跳过 | +| parent_task_progress | v2.7-subtask-model §2.6 | ✅ 已实现 | 按 stage 分组统计 + active_stage | + +### blackboard/registry.py (文件: src/blackboard/registry.py, 286行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| ProjectRegistry（registry.db SQLite） | architecture-v2.6 §10/v2.6.10 | ✅ 已实现 | 替代原 YAML 方案 | +| projects 表 Schema | technical-design §4.2 | ✅ 已实现 | 含 config_json、source、archived_at | +| create_project | v2.7-subtask-model §3 | ✅ 已实现 | 含目录创建 + project.yaml 骨架 | +| get/list/update/archive/delete | technical-design §9.4 | ✅ 已实现 | | +| 自动发现（扫描含 blackboard.db 的目录） | v2.7-subtask-model §3 | ✅ 已实现 | discover_projects() | +| YAML 迁移 | v2.7-subtask-model §3 | ✅ 已实现 | migrate_from_yaml() | + +### daemon/ticker.py (文件: src/daemon/ticker.py, 580行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| Tick 循环（可配置间隔） | architecture-v2.6 §4.1 | ✅ 已实现 | 默认 30s | +| 遍历所有 active 项目 | architecture-v2.6 v2.6.10 | ✅ 已实现 | _tick_project per project | +| 依赖推进（blocked → pending） | architecture-v2.6 §4.2 D2-2 | ✅ 已实现 | _advance_dependencies() | +| 僵尸/超时处理 | architecture-v2.6 §4.1 | ✅ 已实现 | _check_timeouts(): claimed 超时→pending, working 超时→failed | +| Pending 任务调度 | agent-integration-v2.6 §4.1 | ✅ 已实现 | _dispatch_pending(): Dispatcher → Spawner | +| Review 任务调度 | agent-routing-redesign §1.1 | ✅ 已实现 | _dispatch_reviews(): 无产出→failed, 有产出→派审查者 | +| 父 Task 状态聚合 | v2.7-subtask-model §2.5 | ✅ 已实现 | _refresh_parent_statuses() | +| daemon_tick 事件 | architecture-v2.6 §4.2 | ✅ 已实现 | | +| max_dispatch_per_tick 并发控制 | technical-design §5.4 | ✅ 已实现 | | +| claim_timeout / task_timeout | architecture-v2.6 §4.5 | ✅ 已实现 | 可配置 | +| per-task 超时（deadline 优先） | architecture-v2.6 §4.5 | ✅ 已实现 | deadline > default_task_timeout | +| 手动 tick API | technical-design §9.2 | ✅ 已实现 | manual_tick() | +| 防重复 dispatch（_check_recent_routing） | agent-routing-redesign | ✅ 已实现 | 5 分钟内同 task 不重复 dispatch | + +**⚠️ 注意**: Ticker 未集成 HealthChecker（health.py 存在但未被 Ticker 调用）。设计文档 §14 + v2.6.9.1 要求"Daemon 逻辑健康自检纳入"。 + +### daemon/dispatcher.py (文件: src/daemon/dispatcher.py, 402行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| Dispatcher 类（执行层） | agent-routing-redesign §1 | ✅ 已实现 | Router 做决策，Dispatcher 做执行 | +| decide() 委托给 Router | agent-routing-redesign §4 | ✅ 已实现 | | +| dispatch() 完整流程 | agent-integration-v2.6 §4.1 | ✅ 已实现 | 决策 + 并发检查 + spawn + 审计日志 | +| DispatchLevel 四级 | agent-routing-redesign §4 | ✅ 已实现 | LOCAL/FULL_AGENT/SUB_AGENT/ESCALATE | +| 路由审计日志（routing_decisions） | agent-routing-redesign §5 | ✅ 已实现 | _record_routing() 写入项目 DB | +| 并发控制检查 | technical-design §5.4 | ✅ 已实现 | counter.can_acquire() | +| spawn 消息构建 | agent-integration-v2.6 §4.2 | ✅ 已实现 | _build_spawn_message() 含 retry context | +| Legacy 兼容模式 | 无 | ✅ 已实现(超前) | 无 Router 时降级旧逻辑 | +| 批量决策接口 | 无 | ✅ 已实现(超前) | dispatch_pending() | + +### daemon/router.py (文件: src/daemon/router.py, 376行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| AgentRouter 决策层 | agent-routing-redesign §4 | ✅ 已实现 | 三种路由模式 | +| Mode A LLM 路由 | agent-routing-redesign §4.2 | ✅ 已实现 | LLMDriver: OpenAI API 调用, ~200 token | +| Mode B Agent 声明式交接 | agent-routing-redesign §4.3 | ✅ 已实现 | next_capability 匹配 | +| AgentProfile 能力画像 | agent-routing-redesign §4 | ✅ 已实现 | capabilities, can_review, max_concurrent, is_fallback | +| RouteDecision 数据结构 | agent-routing-redesign §5 | ✅ 已实现 | agent_id, reason, mode, confidence, model, latency_ms | +| 快速路径（确定性路由） | agent-routing-redesign §4 | ✅ 已实现 | 本地 action + retry + 生命周期查表 + 直接 assignee | +| LLM 合法性校验 | agent-routing-redesign §4.2 | ✅ 已实现 | agent_id 必须在 profiles 中 | +| LLM 低置信度 fallback | agent-routing-redesign §4.2 | ✅ 已实现 | confidence < 0.7 → fallback 庞统 | +| BUG-2 next_capability 校验 | agent-routing-redesign | ✅ 已实现 | _validate_capability() 白名单 | +| 负载均衡（多候选选最低负载） | agent-routing-redesign §4 | ✅ 已实现 | counter.active_agents | + +### daemon/spawner.py (文件: src/daemon/spawner.py, 367行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| AgentSpawner 类 | architecture-v2.6 §4.3 | ✅ 已实现 | | +| spawn_full_agent | agent-integration-v2.6 §4.1 | ✅ 已实现 | openclaw agent CLI 异步非阻塞 | +| spawn_subagent | agent-integration-v2.6 | ⚠️ 占位 | spawn_subagent() 为 placeholder, TODO F17 | +| Spawn prompt 模板 | agent-api-contract §1 | ✅ 已实现 | SPAWN_PROMPT_TEMPLATE 含完整状态机 + API 引导 | +| 进程监控 + 超时 kill | architecture-v2.6 §4.3 | ✅ 已实现 | _monitor_process(): wait_for + TimeoutError | +| task_attempts 记录 | architecture-v2.6 §4.3 | ✅ 已实现 | _record_attempt() | +| Session 注册表 | architecture-v2.6 §4.3 | ✅ 已实现 | _sessions dict | +| on_complete 回调 | agent-integration-v2.6 §4.1 | ✅ 已实现 | 释放 counter | +| dry_run 测试模式 | 无 | ✅ 已实现(超前) | | +| API host/port 配置 | agent-api-contract | ✅ 已实现 | 供 Agent 回写 | + +### daemon/counter.py (文件: src/daemon/counter.py, 73行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| ActiveAgentCounter 异步计数器 | architecture-v2.6 v2.6.10 / technical-design §5.4 | ✅ 已实现 | | +| 全局上限 + per-agent 串行 | technical-design §5.4 | ✅ 已实现 | max_global=5, max_per_agent=1 | +| 延迟创建 Semaphore | 无 | ✅ 已实现(超前) | 兼容 Python 3.9 | +| active_agents 属性 | technical-design §5.4 | ✅ 已实现 | 供 Router 负载均衡 | + +### daemon/bootstrap.py (文件: src/daemon/bootstrap.py, 215行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| BootstrapBuilder 四层上下文 | architecture-v2.6 v2.6.5 / technical-design §5.5 | ✅ 已实现 | L0-L3 四层 | +| L2a 角色模板 | architecture-v2.6 v2.6.5 | ✅ 已实现 | 按 role 加载 {role}.md | +| L2b 项目背景 | architecture-v2.6 v2.6.5 | ✅ 已实现 | | +| L2c 任务上下文 | architecture-v2.6 v2.6.5 | ✅ 已实现 | | +| L2d 前序产出（depends_on） | architecture-v2.6 v2.6.5 | ✅ 已实现 | | +| L2e Guardrail 规则（仅执行者） | architecture-v2.6 v2.6.5 | ✅ 已实现 | role == "executor" | +| L2f 审查协议 | architecture-v2.6 v2.6.5 | ✅ 已实现 | executor/reviewer/pangtong | +| L2g 经验注入 | architecture-v2.6 v2.6.7 | ✅ 已实现 | 最多 5 条 | +| L3 Skill 描述 | architecture-v2.6 v2.6.5 | ✅ 已实现 | 最多 10 条 | +| Token 估算 + 截断 | technical-design §5.5 | ✅ 已实现 | estimate_tokens(), max_tokens=4096 | +| build_for_task 便捷方法 | 无 | ✅ 已实现(超前) | | + +**⚠️ 注意**: BootstrapBuilder 未被 Ticker/Spawner 实际调用。当前 Spawner 用自己的 SPAWN_PROMPT_TEMPLATE 构建 prompt，未走 BootstrapBuilder。这是一个设计意图与实现的偏差。 + +### daemon/sse.py (文件: src/daemon/sse.py, 312行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| SSEBroker 订阅/发布 | technical-design §9.3 | ✅ 已实现 | asyncio.Queue per subscriber | +| SSE 事件格式 | technical-design §9.3 | ✅ 已实现 | id + event + data | +| HookManager 可插拔事件处理 | technical-design §10 | ✅ 已实现 | webhook / script / callback 三种 | +| Hook 超时控制 | technical-design §10 | ✅ 已实现 | 默认 10s | +| 事件历史 | technical-design §9.3 | ✅ 已实现 | 最大 100 条 | + +### daemon/inbox.py (文件: src/daemon/inbox.py, 305行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| InboxWatcher JSONL 监听 | architecture-v2.6 §4.2 D2-1 | ✅ 已实现 | 轮询 + truncate | +| 原子追加写入 | architecture-v2.6 §4.2 | ✅ 已实现 | write_event() append 模式 | +| 事件类型：agent_output/agent_status/agent_claim/agent_heartbeat | architecture-v2.6 §4.2 | ✅ 已实现 | | +| default_inbox_callback 翻译黑板操作 | architecture-v2.6 §4.2 | ✅ 已实现 | 4 种事件类型处理 | + +**⚠️ 注意**: InboxWatcher 未被 Ticker 实际启动。Ticker 目前直接走 API（Agent 通过 HTTP 回写黑板），Inbox JSONL 作为备用通道未集成。 + +### daemon/review.py (文件: src/daemon/review.py, 334行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| ReviewPipeline 四步验证 | architecture-v2.6 §9.2 | ✅ 已实现 | existence → format → quality → gate | +| Guardrail 四级门控 | architecture-v2.6 §9.2 | ✅ 已实现 | auto/optional/mandatory/dual | +| RebuttalManager 反驳权 | architecture-v2.6 §9.5 | ✅ 已实现 | 最多 2 轮, 升级目标: simayi → pangtong | +| 自定义质量检查 | architecture-v2.6 §9.3 | ✅ 已实现 | custom_checks dict | + +### daemon/experience.py (文件: src/daemon/experience.py, 291行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| ExperienceDistiller 经验蒸馏 | architecture-v2.6 v2.6.7 | ✅ 已实现 | 模式识别 + 分类 | +| ExperienceStore JSONL 持久化 | architecture-v2.6 v2.6.7 | ✅ 已实现 | | +| 模式关键词映射 | architecture-v2.6 v2.6.7 | ✅ 已实现 | pitfall/best_practice/environment | +| recommend() 推荐经验 | architecture-v2.6 v2.6.7 | ✅ 已实现 | | + +**⚠️ 注意**: ExperienceDistiller 未被 Ticker 集成调用。经验蒸馏是独立模块，未接入自动流程。 + +### daemon/health.py (文件: src/daemon/health.py, 158行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| HealthChecker 僵尸检测 | architecture-v2.6 §14 / v2.6.9.1 | ✅ 已实现 | 连续 N tick 无变更 → 告警 | +| 告警 observation 写入 | architecture-v2.6 §14 | ✅ 已实现 | severity=warning | +| 恢复自动解除 | architecture-v2.6 §14 | ✅ 已实现 | | + +**⚠️ 注意**: HealthChecker 未被 Ticker 实例化和调用。设计文档 v2.6.9.1 明确要求"Daemon 逻辑健康自检纳入§14"。 + +### daemon/skill_system.py (文件: src/daemon/skill_system.py, 247行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| SkillRegistry 技能注册 | architecture-v2.6 v2.6.5 / technical-design §8 | ✅ 已实现 | JSON 文件加载 | +| Skill 三层自由度（high/medium/low） | architecture-v2.6 v2.6.5 | ✅ 已实现 | SkillFreedom 枚举 | +| SkillExecutor 构建 prompt | architecture-v2.6 v2.6.5 | ✅ 已实现 | 按自由度构建 | +| Skill match 关键词匹配 | technical-design §8 | ✅ 已实现 | 名称/描述/标签权重 | +| Skill 生命周期（draft/active/deprecated） | architecture-v2.6 v2.6.7 | ⚠️ 部分实现 | models.py 中有 status 字段，但 SkillExecutor 未检查生命周期 | + +### cli/blackboard.py (文件: src/cli/blackboard.py, 332行) + +| 功能点 | 设计文档位置 | 代码实现状态 | 备注 | +|--------|------------|------------|------| +| read 命令 | architecture-v2.6 §5.2 | ✅ 已实现 | | +| create 命令 | architecture-v2.6 §5.2 | ✅ 已实现 | | +| update-status 命令 | architecture-v2.6 §5.2 | ✅ 已实现 | | +| output 命令 | architecture-v2.6 §5.2 | ✅ 已实现 | | +| comment 命令 | architecture-v2.6 §5.2 | ✅ 已实现 | | +| review 命令 | architecture-v2.6 §9.6 | ✅ 已实现 | | +| experience 命令 | architecture-v2.6 v2.6.7 | ✅ 已实现 | | + +--- + +## 数据库 Schema 审查 + +### 表 vs 设计文档对照 + +| 表名 | 设计文档 | 代码实现 | 状态 | +|------|---------|---------|------| +| tasks | architecture-v2.6 §3.2 + v2.7 + v2.8 | db.py L321-350 | ✅ 完全匹配（含 v2.8 全部扩展） | +| comments | architecture-v2.6 §3.5 | db.py L355-366 | ✅ 完全匹配 | +| outputs | architecture-v2.6 §3.2 + v2.8 M3 | db.py L368-380 | ✅ 含 v2.8 扩展字段 | +| decisions | architecture-v2.6 §3.2 | db.py L382-392 | ✅ | +| observations | architecture-v2.6 §3.2 | db.py L394-406 | ✅ | +| events | architecture-v2.6 §3.2 | db.py L408-416 | ✅ | +| agents | technical-design §4.2 | db.py L418-424 | ✅ | +| task_attempts | architecture-v2.6 §4.3 | db.py L426-439 | ✅ | +| reviews | architecture-v2.6 §9.6 | db.py L441-457 | ✅ | +| experiences | architecture-v2.6 v2.6.7 | db.py L459-476 | ✅ | +| experience_tags | architecture-v2.6 v2.6.7 | db.py L478-483 | ✅ | +| routing_decisions | agent-routing-redesign §5 | db.py L485-503 | ✅ | +| checkpoints | v2.8-state-enhancement §四.4 | db.py L505-520 | ✅ | + +### 迁移链完整性 + +| 迁移 | 目的 | 状态 | +|------|------|------| +| _migrate_v261 | current_agent 等路由字段 | ✅ | +| _migrate_v27 | stages_json + stage | ✅ | +| _migrate_v28 | CHECK 更新 + 归档 + checkpoints + outputs 扩展 | ✅ | + +--- + +## API 端点审查 + +### 黑板 CRUD (blackboard_routes.py) + +| API | 设计文档 | 代码行 | 状态 | +|-----|---------|-------|------| +| GET /tasks | architecture-v2.6 §5.2 | L40-45 | ✅ | +| GET /tasks/{id} | architecture-v2.6 §5.2 + expand=all | L48-68 | ✅ | +| POST /tasks | architecture-v2.6 §5.2 | L71-94 | ✅ 含 v2.8 title 自动生成 | +| GET /tasks/{id}/progress | v2.7-subtask-model §2.6 | L97-102 | ✅ | +| POST /tasks/{id}/claim | architecture-v2.6 §3.6 | L105-109 | ✅ | +| POST /tasks/{id}/status | agent-api-contract §2 | L112-147 | ✅ 含详细错误信息 | +| GET/POST /tasks/{id}/comments | architecture-v2.6 §3.5 | L151-166 | ✅ | +| GET/POST /tasks/{id}/outputs | agent-api-contract §1 | L170-225 | ✅ 含 content 直传 + content_path | +| GET/POST /tasks/{id}/decisions | architecture-v2.6 §3.2 | L229-239 | ✅ | +| POST /tasks/{id}/observations | architecture-v2.6 §3.2 | L243-247 | ✅ | +| GET/POST /tasks/{id}/reviews | architecture-v2.6 §9.6 | L251-266 | ✅ | +| GET /tasks/{id}/events | architecture-v2.6 §4.2 | L270-273 | ✅ | +| GET /tasks/{id}/experiences | architecture-v2.6 v2.6.7 | L276-278 | ✅ | +| GET /events | architecture-v2.6 §4.2 | L282-284 | ✅ | +| GET /summary | architecture-v2.6 §3.4 | L288-290 | ✅ | +| POST /tasks/{id}/archive | v2.8-state-enhancement §二.1 | L295-305 | ✅ | +| POST /tasks/archive-done | v2.8-state-enhancement §二.1 | L308-311 | ✅ | + +### Checkpoint API (checkpoint_routes.py) + +| API | 设计文档 | 代码行 | 状态 | +|-----|---------|-------|------| +| GET /checkpoints | v2.8-state-enhancement §四.5 | L48-52 | ✅ | +| POST /checkpoints | v2.8-state-enhancement §四.5 | L55-73 | ✅ | +| POST /checkpoints/{id}/approve | v2.8-state-enhancement §四.5 | L76-83 | ✅ | +| POST /checkpoints/{id}/reject | v2.8-state-enhancement §四.5 | L86-93 | ✅ | + +### Daemon API (daemon_routes.py) + +| API | 设计文档 | 代码行 | 状态 | +|-----|---------|-------|------| +| GET /daemon/status | technical-design §9.2 | L10-21 | ✅ | +| POST /daemon/tick | technical-design §9.2 | L24-29 | ✅ | + +### Project API (project_routes.py) + +| API | 设计文档 | 代码行 | 状态 | +|-----|---------|-------|------| +| GET /projects | technical-design §9.4 | L16-20 | ✅ | +| POST /projects | technical-design §9.4 | L23-31 | ✅ | +| GET /projects/{id} | technical-design §9.4 | L34-39 | ✅ | +| POST /projects/{id}/archive | technical-design §9.4 | L42-46 | ✅ | + +### SSE API (sse_routes.py) + +| API | 设计文档 | 代码行 | 状态 | +|-----|---------|-------|------| +| GET /api/events | technical-design §9.3 | L26-47 | ✅ 含 heartbeat | + +### Mail API (mail_routes.py) + +| API | 设计文档 | 代码行 | 状态 | +|-----|---------|-------|------| +| GET /api/mail | v2.7-subtask-model §2.6 | L56-87 | ✅ | +| GET /api/mail/agents/list | 无 | ✅(超前) | 筛选用 | +| GET /api/mail/summary | 无 | ✅(超前) | | +| GET /api/mail/{id} | 无 | ✅(超前) | 含 comments | +| POST /api/mail | v2.7-subtask-model §2.6 | L110-135 | ✅ | +| PATCH /api/mail/{id} | 无 | ✅(超前) | 标记已读/已执行 | + +--- + +## 超前实现清单 + +> 代码已实现但设计文档中未记录（或仅隐含）的功能 + +| # | 功能 | 文件 | 说明 | +|---|------|------|------| +| 1 | Mail Tab 完整后端 API | mail_routes.py | v2.7-subtask-model 仅提到"后续独立实现"，代码已完整实现 | +| 2 | Legacy 兼容路由模式 | dispatcher.py | _legacy_decide/_legacy_dispatch 完整保留，设计文档未提及保留策略 | +| 3 | dispatch_pending() 批量决策 | dispatcher.py | 无设计文档，但作为调试/诊断工具有价值 | +| 4 | dry_run 模式 | spawner.py | 测试用，设计文档未提及 | +| 5 | _check_recent_routing 防重复 | ticker.py | 设计未明确记录，但属于必要工程措施 | +| 6 | Mail 元数据存在 must_haves 字段 | mail_routes.py | 复用 must_haves 字段存 JSON，设计未明确记录 | +| 7 | outputs content 直传自动写文件 | blackboard_routes.py | 设计只提 content_path，代码额外支持 content → 自动存文件 | +| 8 | Project delete（从注册表移除） | registry.py | 设计只提 archive，代码额外实现了 delete | +| 9 | /api/projects 兼容旧端点 | main.py | 旧前端兼容，设计未记录 | + +## 缺口清单 + +> 设计文档已设计但代码未实现的功能 + +| # | 功能 | 设计文档位置 | 严重度 | 说明 | +|---|------|------------|--------|------| +| 1 | **HealthChecker 未集成到 Ticker** | architecture-v2.6 §14 / v2.6.9.1 | 🔴 高 | health.py 完整实现但 Ticker 未调用，僵尸检测不生效 | +| 2 | **BootstrapBuilder 未集成到 Spawner** | architecture-v2.6 v2.6.5 / technical-design §5.5 | 🔴 高 | bootstrap.py 完整实现但 Spawner 用自己的 SPAWN_PROMPT_TEMPLATE，L0-L3 四层上下文未生效 | +| 3 | **InboxWatcher 未集成到 Ticker** | architecture-v2.6 §4.2 D2-1 | 🟡 中 | inbox.py 完整实现但 Ticker 未启动 InboxWatcher，事件驱动降级为纯轮询 | +| 4 | **ExperienceDistiller 未集成** | architecture-v2.6 v2.6.7 | 🟡 中 | experience.py 完整实现但未接入 Ticker 自动蒸馏流程 | +| 5 | **Skill 生命周期管理** | architecture-v2.6 v2.6.7 | 🟢 低 | SkillExecutor 未检查 draft/active/deprecated 状态 | +| 6 | **Guardrail YAML 解析** | architecture-v2.6 §9.8 | 🟡 中 | 声明式 guardrails.yaml 配置未实现，review.py 中硬编码了门控逻辑 | +| 7 | **Review Protocol 模板文件** | architecture-v2.6 §9.4 | 🟡 中 | prompt_templates/reviewer.md + review_protocols/*.yaml 未在代码中加载 | +| 8 | **outputs download API** | v2.8-state-enhancement §五.1 | 🟢 低 | GET /outputs/{oid}/download 未实现 | +| 9 | **TERMINAL_STATUSES 应包含 cancelled** | v2.8-state-enhancement §1.2 | 🟢 低 | cancelled 转换表为空集（等价），但未加入 TERMINAL_STATUSES | +| 10 | **对抗辩论模式** | architecture-v2.6 §9.10 | 🟢 低 | 设计标注为"P3 仅用户明确要求时启用"，未实现符合预期 | +| 11 | **Subagent spawn** | agent-integration-v2.6 | 🟡 中 | spawn_subagent() 为 placeholder（TODO F17），当前只走 Full Agent | +| 12 | **Handoff Comment Schema 校验** | architecture-v2.6 §3.7 | 🟡 中 | schemas/handoff.schema.json 校验未在 CLI 中集成 | + +--- + +## 代码质量观察 + +### 正面 + +1. **Schema 迁移链设计优秀**：v2.6.1 → v2.7 → v2.8 渐进式迁移，幂等安全（_safe_add_column） +2. **状态机严格实现**：VALID_TRANSITIONS + CHECK 约束双重保障 +3. **Agent 友好 API**：详细的错误响应含 hint + valid_values +4. **并发控制完整**：Semaphore + counter + BEGIN IMMEDIATE +5. **per-project SQLite 隔离**：registry.db + 多 blackboard.db，架构清晰 + +### 需关注 + +1. **Ticker 缺少 HealthChecker 集成**：僵尸项目无法自动告警 +2. **BootstrapBuilder 和 Spawner 存在重复功能**：两个系统各自构建 Agent prompt，需统一 +3. **operations.py 中有冗余 `return refreshed`**：ticker.py L343-344 出现两次 return +4. **checkpoint_routes.py 的 _bb() 实例化 ProjectRegistry 未传 root**：`registry.get_db_path(project_id)` 方法不存在（registry.py 只有 db_path 属性无 get_db_path 方法），运行时会报错 +5. **经验沉淀系统完全独立**：db.py 中 experiences 表 + experience.py 中 Experience 类 + operations.py 中 Experience dataclass 三套 Experience 定义并存，可能造成混淆 + +--- + +*审查完毕。核心模块（黑板 CRUD + 状态机 + Daemon Ticker + Router/Dispatcher + Spawner）与设计文档高度一致，v2.7 SubTask 和 v2.8 状态增强均已完整实现。主要缺口集中在辅助系统集成（HealthChecker/BootstrapBuilder/InboxWatcher/ExperienceDistiller）。*