diff --git a/docs/review/prd-coverage-audit.md b/docs/review/prd-coverage-audit.md new file mode 100644 index 0000000..f425523 --- /dev/null +++ b/docs/review/prd-coverage-audit.md @@ -0,0 +1,417 @@ +# 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) → 代码 全覆盖审查 |