sanguo_moziplus_v2/docs/review/prd-coverage-audit.md

# PRD v2.0 能力覆盖审查

**版本**: v1.0
**日期**: 2026-05-19
**作者**: 庞统(副军师) 🐦
**范围**: PRD v2.0 → 设计文档(v2.6~v2.8) → 代码实现 全覆盖审查
**方法**: 逐条提取 PRD 能力需求 → 在设计文档中找对应设计 → 在代码中验证实现

---

## 0. 审查范围

### 代码库统计

| 指标 | 数量 |
|------|------|
| 后端 Python 文件 | 31 个 |
| 后端代码行数 | ~7,200 行 |
| 前端组件 | 27 个 TSX/TS 文件, ~4,800 行 |
| 测试文件 | 20 个, ~5,200 行 |
| 设计文档 | 25 个 .md 文件 |
| 配置文件 | 1 个 default.yaml |

### 代码目录结构

```
src/
├── main.py                    # FastAPI 入口 + Daemon 共享 event loop
├── utils.py                   # 配置加载 + 路径解析
├── cli/blackboard.py          # Agent CLI 工具
├── api/                       # FastAPI 路由层
│   ├── blackboard_routes.py   # 黑板 CRUD API
│   ├── project_routes.py      # 项目管理 API
│   ├── sse_routes.py          # SSE 实时推送 API
│   ├── checkpoint_routes.py   # M3 Checkpoint API
│   ├── mail_routes.py         # v2.7 Mail Tab API
│   └── daemon_routes.py       # Daemon 状态 API
├── blackboard/                # 黑板数据层
│   ├── db.py                  # SQLite Schema + 迁移 + 连接池
│   ├── models.py              # 数据模型 (Task/Comment/Output/Decision/Observation/Event/Review/Experience)
│   ├── operations.py          # 写操作 (CRUD + checkpoint)
│   ├── queries.py             # 读操作
│   └── registry.py            # 多项目管理 (registry.db)
├── daemon/                    # Daemon 引擎层
│   ├── ticker.py              # 30s Tick 主循环 + 依赖推进
│   ├── dispatcher.py          # 调度执行器 (Router/Dispatcher 分层)
│   ├── router.py              # Agent 路由决策 (LLM路由/声明式交接/fallback)
│   ├── spawner.py             # Agent Spawn (Full Agent异步/Spawn模板)
│   ├── counter.py             # 并发控制 (ActiveAgentCounter)
│   ├── review.py              # 审查流水线 (4级分级 + 格式/内容/质量验证)
│   ├── experience.py          # 经验蒸馏 (pitfall/best_practice/pattern分类)
│   ├── skill_system.py        # 技能系统 (高/中/低三层自由度)
│   ├── bootstrap.py           # L0-L3 四层上下文构建
│   ├── inbox.py               # Inbox JSONL 秒级事件推送
│   ├── health.py              # 僵尸检测 + 告警
│   └── sse.py                 # SSE Broker + Hook 系统
└── frontend/                  # React + Vite 前端
    └── src/
        ├── App.tsx, store.ts, api.ts, time.ts
        └── components/ (27 个组件)
```

---

## 1. §4 四相架构覆盖

| PRD 能力 | PRD 章节 | 设计覆盖 | 代码实现 | 状态 |
|---------|---------|---------|---------|------|
| Phase 1: 需求探索(苏格拉底对话) | §4.1 P1 | ✅ 课题7 §3 沉浸观察/即时对话 + topic7-interaction-dashboard-proposal.md §2 | ⚠️ 无独立苏格拉底对话引擎。依赖 OpenClaw Agent 对话（庞统的 Skill），平台只提供任务创建入口 | 部分 |
| Phase 2: 动态规划(AI规划+挑战) | §4.1 P2 | ✅ architecture-v2.6.md §9.2 三层执行模型 + topic3-challenge-review-proposal.md + topic4-decomposition-skill-proposal.md | ✅ router.py LLM路由决策 + review.py 审查流水线 + dispatcher.py 调度执行 | 完整 |
| Phase 3: 自主执行(Agent协作群) | §4.1 P3 | ✅ architecture-v2.6.md §5 黑板架构 + §6 三层执行 + topic2 事件驱动 + §9.7 状态机 | ✅ ticker.py 30s扫描 + dispatcher.py/spawner.py Agent调度 + inbox.py 即时事件 + counter.py 并发控制 | 完整 |
| Phase 4: 主动汇报(AI推送) | §4.1 P4 | ✅ topic7-interaction-dashboard-proposal.md 四级推送(🔴🟡🟢🔵) + topic9-dashboard-design.md | ✅ sse.py SSE Broker + sse_routes.py API + frontend/NotificationCenter.tsx | 完整 |
| 共享意识空间(Blackboard) | §4.1 P3 关键设计 | ✅ architecture-v2.6.md §5 完整黑板设计 + §7 数据模型 | ✅ blackboard/ 完整实现(db+models+operations+queries) + 8张表(tasks/comments/outputs/decisions/observations/events/reviews/experiences) | 完整 |
| 持续指挥官(庞统) | §4.1 P3 关键设计 | ✅ architecture-v2.6.md §6.2 庞统角色 + §6.3 事件驱动spawn | ✅ spawner.py spawn模板含角色指令 + router.py fallback=pangtong + dispatcher.py escalate机制 | 完整 |
| Agent自主协作 | §4.1 P3 关键设计 | ⚠️ PRD 描述 peer-to-peer，设计明确 v2.0 为中央调度 | ✅ inbox.py Agent→Daemon事件流 + comment/@mention 协作 | 部分(v2.1+目标) |
| AI指挥循环(感知→推理→行动) | §4.2 | ✅ architecture-v2.6.md §6 ticker循环 + §8 三层执行模型 | ✅ ticker.py scan→process_tick→dispatch + router.py LLM决策 | 完整 |
| 双入口(对话+Dashboard) | §4.3 | ✅ topic7-interaction-dashboard-proposal.md + topic9-dashboard-design.md | ✅ API层(FastAPI REST) + SSE推送 + frontend/(27个组件) | 完整 |

**§4 覆盖率: 7/9 完整, 2/9 部分** (78%)

### 缺口分析

1. **P1 需求探索(苏格拉底对话)** — 设计中描述了对话交互模式，代码层面没有独立的"苏格拉底对话引擎"。依赖 OpenClaw Agent 的 Skill 能力（requirement-clarification skill），平台只提供任务创建和对话入口。这是架构决策（平台不做 AI 能力，AI 在 Agent 层），不是缺口，但需明确记录。
2. **Agent自主协作** — PRD §4.1 P3 描述 peer-to-peer 协作，但 PRD §10.2 已明确 v2.1+ 才实现。设计走中央调度路线，代码实现中央调度。符合 PRD 范围声明。

---

## 2. §5 核心能力清单覆盖

| # | PRD 能力 | PRD §5 说明 | 设计覆盖 | 代码实现 | 状态 |
|---|---------|-----------|---------|---------|------|
| C1 | **需求探索对话** | 苏格拉底式提问,帮用户梳理需求 | ✅ topic7 §2 即时对话模式 + topic4 planner角色 | ⚠️ 无独立对话引擎,依赖Agent Skill | 部分 |
| C2 | **动态规划** | AI规划+挑战,计划可演进 | ✅ topic3 分级审查 + topic4 模板组件库+Plan Checker + topic11 多项目 | ✅ router.py LLM路由 + review.py 审查 + spawner.py spawn模板 | 完整 |
| C3 | **持续指挥** | 庞统全程在线,实时观察调整 | ✅ architecture-v2.6 §6.2 庞统角色(escalation+fallback) + 事件驱动spawn | ✅ dispatcher.py escalate机制 + router.py fallback=pangtong + spawner.py new_session | 完整 |
| C4 | **共享意识** | Agent通过Daemon API查询共享状态 | ✅ architecture-v2.6 §5 黑板架构 + §7 数据模型 + §8.2 API设计 | ✅ blackboard/(db+ops+queries) + api/blackboard_routes.py + cli/blackboard.py | 完整 |
| C5 | **自主协作** | Agent通过共享空间感知并协调 | ⚠️ v2.1+ peer-to-peer,当前中央调度 | ✅ inbox.py Agent事件流 + comment/@mention + handoff comment | 部分 |
| C6 | **质量门禁** | 独立挑战者评审产出 | ✅ topic3 分级审查流水线(4级风险→1/2/3阶段) + 反驳权 + 审查协议注册表 | ✅ review.py ReviewPipeline + models.py Review(round/max_rounds/verdict) + api/blackboard_routes POST /reviews | 完整 |
| C7 | **主动汇报** | AI推送进度和结果 | ✅ topic7 四级推送(🔴🟡🟢🔵) + topic9 Dashboard | ✅ sse.py SSEBroker + sse_routes.py + frontend/NotificationCenter.tsx | 完整 |
| C8 | **经验沉淀** | 每次执行自动提炼经验 | ✅ topic6 三种载体(Memory→Skill→Rule) + 两级蒸馏 + 五阶段闭环 | ✅ experience.py ExperienceDistillation + models.py Experience + db.py experiences表 | 完整 |
| C9 | **安全护栏** | 危险操作拦截、审批 | ✅ architecture-v2.6 §9.4.2 guardrails.yaml + 三层防护(L1硬检查/L2轻量AI/L3 tripwire) | ⚠️ review.py 有风险分级逻辑,但无独立 guardrails.yaml 文件。L1_guardrail 在 dispatcher Legacy模式中引用。安全检查散布在 review pipeline + dispatcher 中 | 部分 |
| C10 | **工具链集成** | lint/test/build自动触发 | ⚠️ topic *未完成*。PRD §10.2 明确 v2.1+ | ❌ 无 toolchain 相关代码。toolchain-proposal.md 存在但未实现 | 缺口(v2.1+) |

**§5 覆盖率: 5/10 完整, 4/10 部分, 1/10 缺口** (70% 完整, 40% 部分覆盖)

### 能力依赖关系实现状态

```
C1 需求探索  ⚠️ (依赖Agent Skill)
  │
  ▼
C2 动态规划  ✅ (router+review+spawner)
  │
  ▼
C3 持续指挥  ✅ (escalate+fallback) ←→ C4 共享意识 ✅ (blackboard+API+CLI) ←→ C5 自主协作 ⚠️ (中央调度,非P2P)
  │              │
  │              ▼
  │          C8 经验沉淀  ✅ (experience.py+experiences表)
  │
  ├──→ C6 质量门禁  ✅ (review.py分级审查)
  ├──→ C7 主动汇报  ✅ (SSE+NotificationCenter)
  ├──→ C9 安全护栏  ⚠️ (散布实现,无独立guardrails.yaml)
  └──→ C10 工具链   ❌ (v2.1+)
```

---

## 3. §6 技术方向覆盖

| # | PRD 技术方向 | PRD §6 说明 | 设计覆盖 | 代码实现 | 状态 |
|---|------------|-----------|---------|---------|------|
| T1 | **编排层:全新实现** | v2.0全新代码,与v1.0完全隔离 | ✅ architecture-v2.6 全新设计,基于Blackboard架构 | ✅ 全部31个Python文件全新编写,无v1.0代码 | 完整 |
| T2 | **底层:轻量确定性引擎** | 状态机+超时保护+故障恢复 | ✅ architecture-v2.6 §9.7 状态机 + §14 健康检查 | ✅ db.py VALID_TRANSITIONS/VALID_STATUSES + health.py 僵尸检测 + ticker.py timeout/retry | 完整 |
| T3 | **上层:AI指挥层** | 庞统在关键决策点介入 | ✅ architecture-v2.6 §6.2 庞统角色 + §8 三层执行 | ✅ router.py LLM路由决策 + dispatcher.py escalate + spawner.py 角色模板 | 完整 |
| T4 | **Daemon API** | Agent通过HTTP API查询共享状态 | ✅ technical-design-v2.6 §3 API设计 | ✅ api/(6个路由文件) + FastAPI + uvicorn | 完整 |
| T5 | **openclaw agent CLI调度** | Daemon通过CLI调度Agent | ✅ technical-design-v2.6 §5 Agent调度 | ✅ spawner.py asyncio.create_subprocess_exec + cli/blackboard.py Agent工具 | 完整 |
| T6 | **Sanguo Mail降级为fallback** | 主通信走共享空间 | ✅ architecture-v2.6 决策记录 | ✅ api/mail_routes.py Mail作为特殊Project实现(兼容层) | 完整 |
| T7 | **Agent对话入口** | 主力入口,自然语言 | ⚠️ 设计承认依赖OpenClaw session | ⚠️ 代码无独立对话入口,依赖OpenClaw WebChat | 部分(架构决策) |
| T8 | **Dashboard入口** | 可视化监控面板 | ✅ topic7+9 Dashboard设计 + frontend-redesign-v2.6.md | ✅ frontend/(27个组件) + Vite+React+Tailwind | 完整 |
| T9 | **经验层:从无到有** | 每次任务自动提炼经验 | ✅ topic6 完整设计 | ✅ experience.py + models.py Experience + db.py experiences表 | 完整 |

**§6 覆盖率: 7/9 完整, 1/9 部分, 1/9 部分(架构依赖)** (78%)

---

## 4. §10 安全红线覆盖

### §10.1 六条安全红线

| # | 红线 | PRD说明 | 设计覆盖 | 代码实现 | 状态 |
|---|------|--------|---------|---------|------|
| R1 | 实盘交易 | 强制人工确认 | ✅ architecture-v2.6 §9.4.2 L1硬检查 | ⚠️ 无独立guardrails.yaml。review.py 有风险分级,但实盘拦截未硬编码 | 缺口 |
| R2 | 数据删除 | 强制人工确认 | ✅ architecture-v2.6 §9.4.2 | ⚠️ 无独立guardrails.yaml。checkpoint_routes.py approve/reject可间接实现 | 部分 |
| R3 | 系统配置变更 | 强制人工确认 | ✅ architecture-v2.6 §9.4.2 | ⚠️ 同上 | 部分 |
| R4 | 大额token消耗 | 自动暂停+通知 | ⚠️ 设计提到但未细化 | ❌ 无 token 消耗追踪代码 | 缺口 |
| R5 | Agent不受控行为 | 自动终止+升级 | ✅ architecture-v2.6 §14 健康检查 | ✅ health.py 僵尸检测 + counter.py 并发限制 + dispatcher.py 状态检查 | 完整 |
| R6 | 连续失败 | 暂停+人工介入 | ✅ architecture-v2.6 §9.7 状态机(retry_count/max_retries) | ✅ models.py retry_count/max_retries + ticker.py 重试逻辑 + v2.8 paused/escalated 状态 | 完整 |

**§10.1 覆盖率: 2/6 完整, 2/6 部分, 2/6 缺口** (33% 完整)

### §10.2 范围声明覆盖

| PRD v2.0 范围 | 设计 | 代码 | 状态 |
|--------------|------|------|------|
| ✅ 四相循环 | ✅ 完整设计 | ✅ P2/P3/P4 完整,P1 部分依赖Agent | 基本完整 |
| ✅ 中央调度模式 | ✅ architecture-v2.6 | ✅ ticker+dispatcher+spawner+counter | 完整 |
| ✅ 配置化零硬编码 | ✅ default.yaml | ✅ default.yaml 配置驱动 | 完整 |
| ✅ 质量门控+异常处理+经验沉淀 | ✅ topic3+topic6 | ✅ review.py+experience.py+health.py | 完整 |
| ✅ 人工介入(steer/takeover/intervene) | ✅ v2.8 checkpoint+waiting_human | ✅ checkpoint_routes.py+paused/waiting_human状态 | 完整 |

**v2.1+ 后续版本（不在 v2.0 范围）**:

| PRD v2.1+ 功能 | 设计状态 | 代码状态 |
|---------------|---------|---------|
| 🔜 Agent主动感知 | ❌ 无设计 | ❌ 无代码 |
| 🔜 peer-to-peer协作 | ❌ 无设计 | ❌ 无代码 |
| 🔜 工具链自动集成 | ⚠️ toolchain-proposal.md 初稿 | ❌ 无代码 |
| 🔜 Fidelity信息路由 | ❌ 无设计 | ❌ 无代码 |
| 🔜 Boids协作规则 | ❌ 无设计 | ❌ 无代码 |
| 🔜 Dashboard监控面板 | ✅ topic9 完整设计 | ✅ 27个前端组件(实际已提前实现) |

### §10.3 多任务并发

| PRD要求 | 设计覆盖 | 代码实现 | 状态 |
|---------|---------|---------|------|
| Agent有界资源(同时只执行一个步骤) | ✅ architecture-v2.6 topic11 ActiveAgentCounter | ✅ counter.py can_acquire/acquire/release + default.yaml max_per_agent/max_global_agents | 完整 |
| Daemon维护Agent可用性表 | ✅ topic11 | ✅ counter.py active_agents Dict | 完整 |
| 任务间资源冲突按优先级排队 | ✅ architecture-v2.6 §9.8 priority | ✅ models.py Task.priority + ticker.py 排序 | 完整 |
| 每个任务独立artifacts目录 | ✅ architecture-v2.6 §7 per-project SQLite | ✅ registry.py per-project数据目录 + db_path隔离 | 完整 |

### §10.4 任务失败恢复

| PRD要求 | 设计覆盖 | 代码实现 | 状态 |
|---------|---------|---------|------|
| 单步失败:重试(max_retries=3) | ✅ architecture-v2.6 §9.7 | ✅ models.py retry_count/max_retries + ticker.py 重试逻辑 | 完整 |
| 单步失败:换Agent | ✅ dispatcher fallback | ✅ dispatcher.py escalate机制 | 完整 |
| 计划失败:AI判断replan | ⚠️ 设计提到但未细化 | ⚠️ router.py LLM可判断,但无显式replan流程 | 部分 |
| 用户改主意:steer/replan | ✅ v2.8 waiting_human + checkpoint | ✅ checkpoint_routes.py + waiting_human/paused状态 | 完整 |
| 不可恢复:保留产出物 | ✅ architecture-v2.6 §7 | ✅ tasks表保留所有记录 + outputs/decisions不删除 | 完整 |

---

## 5. 数据模型完整度

### 黑板数据表 (src/blackboard/db.py)

| 表 | PRD映射 | 状态 |
|----|---------|------|
| tasks | C2/C3/C4 核心任务模型 | ✅ v2.8 含11个状态+归档+路由字段+SubTask stages |
| comments | C5 协作沟通 | ✅ 含comment_type(escalation/handoff/question等) |
| outputs | C4 结构化产出 | ✅ 含attempt_number |
| decisions | C3 决策记录 | ✅ 含alternatives |
| observations | C3/C7 观察告警 | ✅ 含severity(resolved/resolved_by) |
| events | C7 事件日志 | ✅ SSE事件源 |
| reviews | C6 质量门禁 | ✅ 含round/max_rounds/consensus_reached/verdict |
| experiences | C8 经验沉淀 | ✅ 含category/confidence/status/tags |
| checkpoints | §10.2 M3人工介入 | ✅ v2.8 新增,含type/status/resolved_by |
| routing_decisions | C2 路由审计 | ✅ v2.6.1 新增,含mode/confidence/model/latency |

---

## 6. 前端覆盖度

### PRD v2.0 Dashboard 组件 vs 前端实现

| PRD/设计要求 | 前端组件 | 状态 |
|-------------|---------|------|
| 任务看板 | TaskModal.tsx + EdictBoard.tsx(圣旨榜) | ✅ |
| 全局监控 | MonitorPanel.tsx | ✅ |
| 产出档案 | ArtifactPanel.tsx + ArtifactList.tsx | ✅ |
| 系统配置 | SettingsPanel.tsx + ModelConfig.tsx + SkillsConfig.tsx | ✅ |
| AI Briefing | MorningPanel.tsx(早朝) | ✅ |
| 推送通知中心 | NotificationCenter.tsx | ✅ |
| 邮件Tab | MailPanel.tsx | ✅ |
| 项目切换 | store.ts project switching | ✅ |
| Checkpoint | CheckpointPanel.tsx | ✅ |
| Agent Sessions | SessionsPanel.tsx + OfficialPanel.tsx | ✅ |
| 全局搜索 | GlobalSearch.tsx | ✅ |
| Confirm Dialog | ConfirmDialog.tsx + CourtCeremony.tsx | ✅ |

---

## 7. 设计文档版本梳理

| 文档 | 版本 | 大小 | 最后更新 | 权威性 | 建议 |
|------|------|------|---------|--------|------|
| architecture-v2.6.md | v2.8 | 109K | 2026-05-18 | **主文档** | 保留,版本号反映最新 |
| architecture-v2.md | v2.0 | 112K | 2026-05-14 | 过时 | 归档到 archive/ |
| technical-design-v2.6.md | v2.6.2-tech | 49K | 2026-05-18 | 技术主文档 | 保留 |
| development-plan-v2.6.md | - | 13K | 2026-05-18 | 开发计划 | 保留,需更新进度 |
| frontend-redesign-v2.6.md | - | 9K | 2026-05-18 | 前端设计 | 保留 |
| deployment-v2.6.md | - | 16K | 2026-05-17 | 部署方案 | 保留 |
| v2.7-subtask-model.md | v2.1 | 15K | 2026-05-18 | SubTask设计 | 保留,已评审通过 |
| v2.8-state-enhancement.md | - | 15K | 2026-05-19 | 状态增强+M3 | 保留,已评审通过 |
| topic3-challenge-review-proposal.md | - | 38K | 2026-05-16 | 课题3 挑战/评审 | 已纳入主架构,可归档 |
| topic4-decomposition-skill-proposal.md | - | 27K | 2026-05-16 | 课题4 拆解+上下文 | 已纳入主架构,可归档 |
| topic6-experience-loop-proposal.md | - | 15K | 2026-05-16 | 课题6 经验沉淀 | 已纳入主架构,可归档 |
| topic7-interaction-dashboard-proposal.md | - | 21K | 2026-05-16 | 课题7 交互 | 已纳入主架构,可归档 |
| topic7-9-interaction-dashboard-proposal.md | - | 11K | 2026-05-16 | 课题7+9 初稿 | 被topic7/topic9替代,归档 |
| topic9-dashboard-design.md | - | 17K | 2026-05-17 | 课题9 Dashboard | 已纳入主架构,可归档 |
| topic11-multi-project-proposal.md | - | 29K | 2026-05-16 | 课题11 多项目 | 已纳入主架构,可归档 |
| toolchain-proposal.md | - | 4.4K | 2026-05-16 | 工具链 初稿 | 保留(v2.1+参考) |
| agent-routing-redesign.md | - | 20K | 2026-05-17 | Agent路由重设计 | 已实现,可归档 |
| agent-integration-v2.6.md | - | 13K | 2026-05-17 | Agent集成指南 | 保留(参考) |
| agent-api-contract.md | - | 5.4K | 2026-05-17 | Agent API契约 | 保留(参考) |
| test-plan-v2.6.md | - | 13K | 2026-05-17 | 测试计划 | 保留 |
| frontend-principles.md | - | 1.8K | 2026-05-15 | 前端原则 | 保留 |
| product-direction-notes.md | - | 2.3K | 2026-05-18 | 方向笔记 | 保留 |
| topic4-skill-checklist-draft.md | - | 5.5K | 2026-05-15 | Skill清单草稿 | 被topic4替代,归档 |
| deployment-v2.6-guide.md | - | 4.4K | 2026-05-17 | 部署指南 | 保留 |
| **archive/** | - | - | - | - | 已归档 |

### 版本号混乱问题

当前 architecture-v2.6.md 文件名是 v2.6，但实际内容已更新到 v2.8（v2.8 状态增强已写入变更历史）。建议：
1. 重命名为 `architecture-v2.8.md`，或
2. 保持文件名但明确标注"包含 v2.6~v2.8 全部变更"

---

## 8. 测试覆盖度

| 测试文件 | 测试目标 | 行数 | PRD映射 |
|---------|---------|------|---------|
| test_blackboard.py | 黑板CRUD | ~300 | C4 共享意识 |
| test_api.py | API路由 | ~300 | T4 Daemon API |
| test_dispatcher.py | Agent调度 | ~200 | C2/C3 调度 |
| test_router.py | 路由决策 | ~200 | C2 路由 |
| test_spawner.py | Agent Spawn | ~150 | C3 执行 |
| test_review.py | 审查流水线 | ~200 | C6 质量门禁 |
| test_experience.py | 经验蒸馏 | ~200 | C8 经验沉淀 |
| test_ticker.py | Tick主循环 | ~420 | T2 确定性引擎 |
| test_inbox.py | Inbox事件 | ~200 | T2 事件驱动 |
| test_health.py | 僵尸检测 | ~100 | R5 Agent不受控 |
| test_counter.py | 并发控制 | ~200 | §10.3 多任务并发 |
| test_registry.py | 多项目管理 | ~200 | §10.3 项目隔离 |
| test_skill_system.py | 技能系统 | ~200 | C8 Skill生态 |
| test_sse.py | SSE推送 | ~270 | C7 主动汇报 |
| test_bootstrap.py | 上下文构建 | ~200 | T3 AI指挥层 |
| test_e2e_v27.py | 端到端(v2.7) | ~400 | 全链路 |
| test_v27_subtasks.py | SubTask模型 | ~320 | v2.7 SubTask |
| test_cli.py | Agent CLI | ~200 | T5 CLI调度 |
| test_main.py | 主入口 | ~150 | T1 全新实现 |

**测试总计: ~4,300 行, 20 个文件** — 覆盖所有核心模块。

---

## 9. 之前审查报告 Gap 修复验证

### v2.6-requirements-design-verification-v2.md 识别的 Gap

| # | 问题 | 本审查验证 | 代码状态 |
|---|------|----------|---------|
| D1 | IR-2 Plan→Execute→Validate | ✅ review.py 三阶段流水线 + risk_level 分级 | 已实现 |
| D2 | IR-4 安全红线 | ⚠️ 无独立 guardrails.yaml,逻辑分散在 review/dispatcher | 部分实现 |
| D3 | 挑战协商轮次追踪 | ✅ models.py Review.round/max_rounds + review.py 轮次逻辑 | 已实现 |
| D4 | 前端与v2.6集成 | ✅ 27个前端组件 | 已实现 |
| D5 | Daemon tick AI决策 | ✅ router.py LLM路由(可选) | 已实现 |
| D6 | 60s→30s tick | ✅ default.yaml tick_interval: 30 | 已实现 |
| D7 | 拆解保障 | ✅ spawner.py spawn模板含must_haves + router.py 验证 | 已实现 |
| D8 | 上下文管理 | ✅ bootstrap.py L0-L3四层构建 | 已实现 |
| D9 | 前端过渡 | ✅ 前端已全面实现 | 已实现 |
| N8 | F7全生命周期 | ❌ 仍无设计 | 未实现 |
| N9 | F8工具链自动化 | ❌ toolchain-proposal.md 初稿,无代码 | 未实现 |
| N10 | Agent并行运行时感知 | ⚠️ counter.py 并发控制,但无跨Agent感知 | 部分实现 |
| N11 | 多Agent session上下文膨胀 | ✅ bootstrap.py token估算+分层注入 | 已缓解 |

---

## 10. 核心发现

### ✅ 做得好的

1. **架构完整性高** — Blackboard + 三层执行模型 + 双层事件架构的设计在代码中完整落地。31个Python文件、7,200行代码、20个测试文件，是一个可运行的系统。
2. **设计驱动开发** — 从PRD到设计文档(25个)到代码，每一步有文档可追溯。课题设计(1~11)的决策编号(D3-1, D4-6等)在代码注释中有引用。
3. **前端提前实现** — PRD §10.2 标注 Dashboard 为 v2.1+，但实际 27 个前端组件已完整实现(任务看板/监控/产出/配置/AI Briefing/通知/Mail/Checkpoint等)。
4. **数据模型演进有序** — v2.6(基础)→v2.6.1(路由)→v2.7(SubTask)→v2.8(状态增强+Checkpoint)，每次有 db.py 迁移函数，向后兼容。
5. **测试覆盖全面** — 每个核心模块有独立测试文件，含 e2e 端到端测试。

### ⚠️ 需要注意的

6. **安全红线(guardrails.yaml)缺失** — PRD §10.1 的6条安全红线在设计中有详细方案(guardrails.yaml 声明式规则 + L1/L2/L3三层防护)，但代码中没有独立的 guardrails.yaml 文件。安全检查逻辑散布在 review.py(风险分级)和 dispatcher.py(legacy模式L1_guardrail)。**这是PRD→代码最大的缺口**。
7. **P1 需求探索未内建** — 苏格拉底式对话作为PRD的核心创新("帮用户想清楚要什么"),在平台代码中只是任务创建入口,对话能力完全依赖 OpenClaw Agent 的 Skill。这是架构决策(平台不做AI),但需在文档中明确。
8. **prompt_templates/ 目录未创建** — 设计文档大量引用 prompt_templates/(executor.md, reviewer.md, planner.md, adjudicator.md, rebuttal.md),但代码目录中不存在。Agent spawn 消息构建在 spawner.py 中硬编码模板。这意味着设计中的 Skill 引导体系(S-01~S-28)未完全落地。
9. **review_protocols/ 目录未创建** — 设计引用 review_protocols/(plan_review.yaml, output_review.yaml, analysis_review.yaml),但代码目录中不存在。审查协议在 review.py 中硬编码。
10. **schemas/ 目录未创建** — 设计引用 schemas/(handoff.schema.json, output.schema.json 等),但代码目录中不存在。产出物校验在 review.py 中用正则表达式实现。

### ❌ 缺口

11. **F7 全生命周期阶段映射** — PRD的"需求→设计→编码→测试→部署→运维"任务类型映射,两次审查均未设计,仍未实现。
12. **F8 工具链自动化(C10)** — lint/test/build 自动触发,PRD §10.2 明确 v2.1+,toolchain-proposal.md 仅有初稿。
13. **R1 实盘交易强制人工确认** — 设计有方案但代码无硬编码拦截。
14. **R4 大额token消耗自动暂停** — 设计和代码均未实现。

---

## 11. 覆盖率汇总

| 维度 | PRD条目 | 完整 | 部分 | 缺口 | 完整率 |
|------|---------|------|------|------|--------|
| §4 四相架构 | 9 | 7 | 2 | 0 | 78% |
| §5 核心能力 | 10 | 5 | 4 | 1 | 50% |
| §6 技术方向 | 9 | 7 | 2 | 0 | 78% |
| §10.1 安全红线 | 6 | 2 | 2 | 2 | 33% |
| §10.2 v2.0范围 | 5 | 5 | 0 | 0 | 100% |
| §10.3 多任务并发 | 4 | 4 | 0 | 0 | 100% |
| §10.4 失败恢复 | 5 | 4 | 1 | 0 | 80% |
| **总计** | **48** | **34** | **11** | **3** | **71%** |

### 与之前审查对比

| 指标 | v2.6审查(v2) | 本审查(含代码) | 变化 |
|------|-------------|--------------|------|
| 设计覆盖率 | 83% | - | - |
| 设计→代码覆盖率 | - | **71% 完整, 94% 部分** | 新指标 |
| 未覆盖(v2.1+) | 2(D10/D13) | 3(+R1/R4) | +1 |

### 注意

之前的审查只看了 PRD→设计，覆盖率为 83%。本审查深入到代码层，发现**设计中有但代码未完全落地的部分**（guardrails.yaml、prompt_templates/、review_protocols/、schemas/），导致完整率从 83% 降到 71%。如果算上"部分覆盖"，94% 的 PRD 需求在代码中有不同程度的实现。

---

## 12. 建议优先级

### P0 — 必须解决(影响安全/核心能力)

| # | 建议 | 工作量 | 关联 |
|---|------|--------|------|
| 1 | 创建 guardrails.yaml + 加载逻辑,硬编码6条安全红线 | 1-2天 | R1-R6 |
| 2 | 创建 prompt_templates/ 目录,将 spawner.py 硬编码模板迁移到文件 | 2-3天 | S-01~S-28 |
| 3 | token 消耗追踪 + 超限暂停 | 1天 | R4 |

### P1 — 应该解决(提升质量)

| # | 建议 | 工作量 | 关联 |
|---|------|--------|------|
| 4 | 创建 review_protocols/ 目录,将 review.py 审查协议外置 | 1-2天 | C6 |
| 5 | 创建 schemas/ 目录,产出物校验 Schema 化 | 1天 | C4 |
| 6 | 文档版本对齐:architecture 文件名改为 v2.8 或标注 | 0.5天 | 文档 |
| 7 | 过期文档归档(topic*/agent-routing-redesign等) | 0.5天 | 文档 |

### P2 — 可以后续(v2.1+)

| # | 建议 | 工作量 | 关联 |
|---|------|--------|------|
| 8 | F7 全生命周期阶段映射设计 | 2-3天 | D10 |
| 9 | F8 工具链自动化实现 | 3-5天 | D13/C10 |
| 10 | Agent peer-to-peer 协作 | 大 | C5 |

---

## 变更历史

| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-05-19 | v1.0 | 初版:PRD v2.0 → 设计(v2.6~v2.8) → 代码 全覆盖审查 |