后端代码 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 中集成 |
代码质量观察
正面
- Schema 迁移链设计优秀：v2.6.1 → v2.7 → v2.8 渐进式迁移，幂等安全（_safe_add_column）
- 状态机严格实现：VALID_TRANSITIONS + CHECK 约束双重保障
- Agent 友好 API：详细的错误响应含 hint + valid_values
- 并发控制完整：Semaphore + counter + BEGIN IMMEDIATE
- per-project SQLite 隔离：registry.db + 多 blackboard.db，架构清晰
需关注
- Ticker 缺少 HealthChecker 集成：僵尸项目无法自动告警
- BootstrapBuilder 和 Spawner 存在重复功能：两个系统各自构建 Agent prompt，需统一
- operations.py 中有冗余
return refreshed：ticker.py L343-344 出现两次 return
- checkpoint_routes.py 的 _bb() 实例化 ProjectRegistry 未传 root：
registry.get_db_path(project_id) 方法不存在（registry.py 只有 db_path 属性无 get_db_path 方法），运行时会报错
- 经验沉淀系统完全独立：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）。
cfdaily