sanguo_moziplus_v2/docs/review/backend-audit.md

# 后端代码 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）。*