diff --git a/docs/design/architecture-v3.0.md b/docs/design/architecture-v3.0.md index 801ba5c..685d1fa 100644 --- a/docs/design/architecture-v3.0.md +++ b/docs/design/architecture-v3.0.md @@ -1,802 +1,1232 @@ # AI Native DevOps Platform 架构设计 v3.0 -**版本**: v3.0（PRD 3.0 对齐 + 代码现状回溯） -**基于**: PRD-v3.0 + architecture-v2.6 + 实际代码 -**作者**: 庞统（副军师）🐦 +**版本**: v3.0（PRD 3.0 对齐版） +**基于**: PRD-v3.0 + architecture-v2.6 + v2.7~v3.0 增量设计 + 实际源码回溯 +**作者**: 庞统（副军师） **日期**: 2026-05-28 -**状态**: 初稿 -**准绳**: PRD-v3.0.md 是唯一准绳，设计矛盾以它为准 +**状态**: 回溯定稿 --- -## 变更历史 +## §1. 版本信息和变更历史 -| 版本 | 日期 | 变更 | -|------|------|------| -| v3.0 | 2026-05-28 | 基于 PRD-v3.0 + 代码现状，全面回溯。从 architecture-v2.6 继承并修正 | +### 1.1 版本演进 + +| 版本 | 日期 | 变更内容 | +|------|------|---------| +| v2.0 | 2026-05-04 | 初始版本：SQLite 4表 + 状态机 + DAG 引擎 | +| v2.6 | 2026-05-15 | 架构重构：Shared Workspace(Blackboard) 取代 DAG 引擎 | +| v2.6.1 | 2026-05-15 | 司马懿评审 + Mail 退役 + 质量门控 + 决策记录 | +| v2.6.2 | 2026-05-15 | 三层执行模型 + 续杯机制 + Guardrail 体系 | +| v2.6.3 | 2026-05-15 | 事件驱动 + Inbox JSONL + 依赖驱动 | +| v2.6.4 | 2026-05-15 | 分级审查流水线 + 反驳权 + reviews 表 | +| v2.6.5 | 2026-05-15 | 模板组件库 + 四层上下文架构 (L0-L3) | +| v2.6.7 | 2026-05-15 | 经验沉淀闭环 | +| v2.7 | 2026-05-18 | Card 层回滚 → Task 自引用 SubTask 模型 | +| v2.8 | 2026-05-18 | 3 新状态 (paused/escalated/waiting_human) + 归档机制 | +| v2.7.2 | 2026-05-26 | 防重复调用 & 防无限续杯 + counter v2.1 | +| v3.0 | 2026-05-28 | **本版**：PRD 3.0 对齐 + 源码回溯 + 完整现状记录 | + +### 1.2 v3.0 定位 + +本文档是基于 PRD-v3.0 和实际源码的回溯性架构文档。目的： + +1. **以 PRD 3.0 为准绳**，记录系统的设计目标 +2. **以代码实际状态为事实**，记录已实现和未实现的功能 +3. **记录所有设计矛盾和差异**，作为后续迭代的输入 +4. **不盲从旧设计（v2.6）**，以 7 条分类原则确定每项功能的真实状态 + +### 1.3 7 条分类原则 + +| # | 情况 | 处理 | 标记 | +|---|------|------|------| +| 1 | PRD ✅ + 代码 ✅ + 设计 ✅ | 直进 v3.0 | ✅ **已实现** | +| 2 | PRD ✅ + 代码 ❌ + 设计 ❌ | v3.0 标"待实现" | ❌ **未实现** | +| 3 | 调研/专题 ✅ + PRD ✅ + 代码 ❌ | v3.0 标"待实现" | ❌ **未实现** | +| 4 | 调研 ✅ + PRD ❌ | 标记为 PRD 新增项 | 📋 **PRD 待升级** | +| 5 | 代码 ✅ + PRD ❌ + 设计 ❌ | 找来源 → 归入1~3 或标"幽灵实现" | 👻 **幽灵实现** | +| 6 | 设计文档间矛盾 | 以 PRD 为准 | 🔀 **矛盾** | +| 7 | 调研有但 PRD 不值得进 | 归档保留，不进 v3.0 | 📦 **归档** | --- -## 实现状态标记 +## §2. 架构总览 -- ✅ **已实现** — 代码已落地 -- ⚠️ **部分实现** — 有代码但缺功能 -- ❌ **未实现** — 只有设计没有代码 -- 🔀 **矛盾** — 设计和代码/PRD不一致 +### 2.1 核心变革：从 DAG 状态机到 Shared Workspace ---- - -## 1. 架构总览 - -### 1.1 系统定位 - -moziplus v2 是 AI Native 的多 Agent 协作 DevOps 平台。核心理念（PRD B1~B4）： - -| 信念 | PRD 编号 | 架构体现 | -|------|----------|---------| -| B1: AI 参与每个决策层 | PRD §2.1 | Agent 自主认领、审查、裁决；Daemon 只投递不决策 | -| B2: 共享意识空间 | PRD §2.1 | SQLite 黑板 + 全量事件 + @mention + Handoff | -| B3: 人机协同而非人机对抗 | PRD §2.1 | Checkpoint/escalated/waiting_human 三级人工介入 | -| B4: 持续学习闭环 | PRD §2.1 | Experience 沉淀 + Skill 进化 | - -### 1.2 系统架构图 +v2.0 的核心是 **DAG 引擎 + 状态机 + 邮件通信**，本质是给 AI 团队做 ERP。v2.6+ 变革为 **Shared Workspace (Blackboard) + Agent 自主决策 + Daemon 投递**。 ``` -┌─────────────────────────────────────────────────────────────────────┐ -│ 用户层 │ -│ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ 前端(React)│ │ OpenClaw CLI │ │ Mail Tab │ │ -│ │ EdictBoard│ │ blackboard.py│ │ 三栏布局 │ │ -│ └─────┬─────┘ └──────┬───────┘ └──────┬───────┘ │ -│ │HTTP/SSE │HTTP │HTTP │ -├────────┼───────────────┼──────────────────┼──────────────────────────┤ -│ ▼ ▼ ▼ │ -│ ┌──────────────────────────────────────────────────┐ │ -│ │ API 层 (FastAPI, port 8083) │ │ -│ │ blackboard_routes / mail_routes / project_routes│ │ -│ │ daemon_routes / sse_routes / checkpoint_routes │ │ -│ └──────────────────────┬───────────────────────────┘ │ -│ │SQLite │ -├─────────────────────────┼───────────────────────────────────────────┤ -│ ▼ │ -│ ┌──────────────────────────────────────────────────┐ │ -│ │ Blackboard 层 │ │ -│ │ per-project blackboard.db (SQLite WAL) │ │ -│ │ tasks / comments / outputs / decisions / │ │ -│ │ observations / events / reviews / experiences / │ │ -│ │ agents / task_attempts / routing_decisions / │ │ -│ │ checkpoints │ │ -│ └──────────────────────┬───────────────────────────┘ │ -│ │ │ -├─────────────────────────┼───────────────────────────────────────────┤ -│ ▼ │ -│ ┌──────────────────────────────────────────────────┐ │ -│ │ Daemon 层 (PM2: sanguo-moziplus-v2) │ │ -│ │ │ │ -│ │ ┌─────────┐ ┌───────────┐ ┌──────────┐ │ │ -│ │ │ Ticker │ │ Dispatcher│ │ Spawner │ │ │ -│ │ │ 30s tick│ │ 任务调度 │ │ 进程管理 │ │ │ -│ │ └─────────┘ └───────────┘ └──────────┘ │ │ -│ │ ┌─────────┐ ┌───────────┐ ┌──────────┐ │ │ -│ │ │ Router │ │ Counter │ │ Inbox │ │ │ -│ │ │ 路由 │ │ 并发控制 │ │ JSONL事件│ │ │ -│ │ └─────────┘ └───────────┘ └──────────┘ │ │ -│ │ ┌──────────────┐ ┌──────────┐ ┌────────┐ │ │ -│ │ │ GuardrailEng │ │ ReviewPipe│ │ Health │ │ │ -│ │ │ 安全红线 │ │ 产出验证 │ │ 僵尸检测│ │ │ -│ │ └──────────────┘ └──────────┘ └────────┘ │ │ -│ │ ┌──────────────┐ ┌──────────┐ ┌────────┐ │ │ -│ │ │ BootstrapBld │ │ ExpStore │ │ SkillReg│ │ │ -│ │ │ 上下文构建 │ │ 经验沉淀 │ │ 技能注册│ │ │ -│ │ └──────────────┘ └──────────┘ └────────┘ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ SSEBroker │ │ │ -│ │ │ 实时推送 │ │ │ -│ │ └──────────────┘ │ │ -│ └──────────────────────────────────────────────────┘ │ -│ │ │ -│ ▼ openclaw agent --agent │ -│ ┌──────────────────────────────────────────────────┐ │ -│ │ Agent 层 (OpenClaw Gateway) │ │ -│ │ 张飞/关羽/赵云/姜维/司马懿/庞统 │ │ -│ │ 每个 Agent 独立 session，通过 API 读写黑板 │ │ -│ └──────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────────────┘ +┌─────────────────────────────────────────────────────────────┐ +│ 用户 / 触发器 │ +│ (Web Dashboard / CLI / Agent 对话) │ +└──────────────────────────┬──────────────────────────────────┘ + │ HTTP API / Agent 对话 +┌──────────────────────────▼──────────────────────────────────┐ +│ FastAPI (端口 8083) │ +│ ┌───────────────┐ ┌──────────────┐ ┌──────────────────┐ │ +│ │ blackboard │ │ mail_routes │ │ project_routes │ │ +│ │ _routes.py │ │ (Mail Tab) │ │ (项目管理) │ │ +│ └───────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │ +│ └────────────┬────┘ │ │ +└───────────────────────┼─────────────────────────┼───────────┘ + │ SQLite │ registry.db +┌───────────────────────▼─────────────────────────▼───────────┐ +│ Shared Workspace (黑板) │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ per-project blackboard.db (SQLite WAL) │ │ +│ │ tasks / comments / outputs / decisions / observations │ │ +│ │ events / reviews / task_attempts / checkpoints │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ ┌──────────────┐ │ +│ │ registry.db │ ← 多项目注册表 (ProjectRegistry) │ │ +│ └──────────────┘ │ +└──────────────────────────┬──────────────────────────────────┘ + │ Daemon tick (30s) + Inbox JSONL (1s) +┌──────────────────────────▼──────────────────────────────────┐ +│ Daemon (管家) │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ +│ │ Ticker │ │ Dispatcher │ │ Spawner │ │ +│ │ 30s 主循环 │ │ 路由决策+执行│ │ 进程管理+监控 │ │ +│ └──────┬───────┘ └──────┬───────┘ └──────┬───────────┘ │ +│ │ │ │ │ +│ ┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────────┐ │ +│ │ Router │ │ Counter │ │ Guardrails │ │ +│ │ 确定性路由 │ │ 并发控制 │ │ 安全红线引擎 │ │ +│ └──────────────┘ └──────────────┘ └──────────────────┘ │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ +│ │ Health │ │ Experience │ │ InboxWatcher │ │ +│ │ 僵尸检测 │ │ 经验蒸馏 │ │ 秒级事件推送 │ │ +│ └──────────────┘ └──────────────┘ └──────────────────┘ │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ +│ │ Bootstrap │ │ SSE Broker │ │ ReviewPipeline │ │ +│ │ 上下文构建 │ │ 实时推送 │ │ 产出验证流水线 │ │ +│ └──────────────┘ └──────────────┘ └──────────────────┘ │ +└──────────────────────────┬──────────────────────────────────┘ + │ openclaw agent --agent --session-id +┌──────────────────────────▼──────────────────────────────────┐ +│ Agent 层 (将军们) │ +│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ +│ │庞统 │ │司马懿│ │姜维 │ │关羽 │ │张飞 │ │赵云 │ │ +│ │策划 │ │质量 │ │平台 │ │风控 │ │编码 │ │数据 │ │ +│ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ +│ 每个 Agent: SOUL.md + IDENTITY.md + Skills + Workspace │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 2.2 核心原则 ✅ + +> **黑板是唯一真相源，所有 agent 读它、想、行动，写回结果。Daemon 是投递员，不是决策者。** + +| # | 原则 | 实现状态 | +|---|------|---------| +| 1 | Agent 决策，Daemon 执行 | ✅ 已实现 — Router 做确定性路由，模糊场景 delegate 庞统 | +| 2 | 产出在黑板，不在邮件 | ✅ 已实现 — outputs 表 + content_path 模式 | +| 3 | Daemon 不阻塞 Agent | ✅ 已实现 — async spawn + counter 并发控制 | +| 4 | Session 用完即清 | ⚠️ 部分实现 — spawn 隔离 session ✅，jsonl 存档和清理代码存在但未完全集成 | +| 5 | 双入口，对等地位 | ⚠️ 部分实现 — API ✅，Dashboard 前端存在但 AI Native 化未完成 | + +### 2.3 v2.0 vs v3.0 对比 + +| 维度 | v1.0 (v2.0 原型) | v3.0 现状 | +|------|-----------------|----------| +| 编排核心 | DAG 引擎 + 状态机 | Blackboard (Shared Workspace) | +| 决策者 | Daemon (状态机驱动) | Agent (确定性路由 + delegate 庞统) | +| Daemon 角色 | 调度器 | 投递员 + 路由 + 监控 | +| Agent 通信 | Sanguo Mail (异步邮件) | 黑板 Comment + Mail Tab (兼容保留) | +| 信息位置 | 分散 | 集中 (per-project SQLite) | +| 状态机 | 8 个状态 | 11 个状态 (v2.8) | +| 上下文 | 全量注入 | L0-L3 四层分层 | + +--- + +## §3. 核心原则（对齐 PRD 四条信念） + +### 3.1 B1: AI 帮人想清楚要什么 ⚠️ + +| 方面 | PRD 目标 | 实际状态 | +|------|---------|---------| +| 苏格拉底式对话 | 需求探索的核心入口 | ❌ 未实现 — 无独立的"需求探索"阶段，任务直接创建 | +| 多轮需求澄清 | 庞统通过对话帮用户梳理需求 | ⚠️ Agent 对话中可实现，但无专门机制 | + +**差距**: PRD 描述的四相循环（需求探索→动态规划→自主执行→主动汇报）中，Phase 1 需求探索完全依赖 Agent 对话能力，平台没有提供专门的需求探索 Skill 或流程。 + +### 3.2 B2: 编排层是 AI 指挥官 ✅ + +| 方面 | PRD 目标 | 实际状态 | +|------|---------|---------| +| AI 驱动决策 | 庞统全程指挥 | ✅ 已实现 — Router 模糊场景 delegate 庞统 (v3.0) | +| 确定性兜底 | 底层执行保障 | ✅ 已实现 — Ticker 30s 循环 + 状态机 | +| 动态规划 | 计划可演进 | ⚠️ 基础机制存在（任务创建/状态流转），但无活的计划调整 | + +### 3.3 B3: Agent 共享意识 ✅ + +| 方面 | PRD 目标 | 实际状态 | +|------|---------|---------| +| 共享状态空间 | Daemon HTTP API | ✅ 已实现 — FastAPI 端点齐全 | +| 实时感知 | Agent 按需查询黑板 | ✅ 已实现 — API 契约完整 | +| 不传消息 | 黑板评论替代邮件 | ✅ 已实现 — comments 表 + @mention | + +### 3.4 B4: 人退到系统边缘 ✅ + +| 方面 | PRD 目标 | 实际状态 | +|------|---------|---------| +| 安全红线拦截 | 危险操作强制人工确认 | ✅ 已实现 — GuardrailEngine 6 条红线 | +| 关键决策点介入 | escalated/waiting_human 状态 | ✅ 已实现 — v2.8 新增 3 个状态 | +| SSE 实时推送 | AI 主动汇报 | ✅ 已实现 — SSEBroker + 前端 EventSource | + +--- + +## §4. 系统架构图 + +### 4.1 数据流 + +``` +用户 (Web/对话) + │ + ├─ POST /api/projects/{pid}/tasks → 创建任务 → blackboard.db + ├─ POST /api/mail → 发送邮件 → _mail/blackboard.db + ├─ GET /api/projects/{pid}/tasks → 查看任务 + │ + ▼ +Daemon Ticker (30s 循环) + │ + ├─ 扫描 active 项目 + ├─ 依赖推进 (blocked → pending) + ├─ 超时检测 (claimed 5min → pending, working 30min → failed) + ├─ 调度 pending 任务 → Router → Dispatcher → Spawner + ├─ 调度 review 任务 → Router → 匹配审查者 + ├─ 僵尸检测 (HealthChecker) + ├─ 父 Task 聚合刷新 + └─ daemon_tick 事件写入 + + ▼ +Spawner (进程管理) + │ + ├─ counter acquire (per session key) + ├─ session state 检查 (防 webchat 冲突) + ├─ spawn openclaw agent 进程 + ├─ _monitor_process (630s 超时监控) + │ ├─ A1~A12: 进程退出场景分类 + │ └─ B1~B4: 进程不退出场景分类 + ├─ 续杯机制 (Gateway timeout → 复用 session) + └─ wrapped_on_complete → counter release + + ▼ +Agent 执行 + │ + ├─ 读黑板 (GET /tasks, GET /tasks/{id}?expand=all) + ├─ 认领任务 (POST /tasks/{id}/claim) — CAS 原子操作 + ├─ 写产出 (POST /tasks/{id}/outputs) + ├─ 写评论 (POST /tasks/{id}/comments) + ├─ 更新状态 (POST /tasks/{id}/status) + ├─ 写观察 (POST /tasks/{id}/observations — 通过 comments) + └─ 写决策 (POST /tasks/{id}/decisions — 通过 comments) +``` + +### 4.2 并发控制流 + +``` +Ticker._dispatch_pending() + │ + ├─ 确定性路径: + │ ├─ retry → 原执行者 + │ ├─ next_capability → 能力匹配 + │ ├─ 有 assignee → 直接分 + │ └─ review 生命周期 → 能力匹配 + │ + └─ 模糊路径 → delegate 庞统 ``` --- -## 2. 数据模型 +## §5. 数据模型 -### 2.1 实际 DB Schema（代码现状） +### 5.1 数据库架构 ✅ -✅ **已实现** — 14 张表 +**per-project SQLite**：每个项目独立 `blackboard.db`，全局 `registry.db` 管理项目注册表。 -| 表名 | 代码位置 | 用途 | -|------|----------|------| -| `tasks` | db.py:239 | 核心任务表 | -| `comments` | db.py:274 | 评论/讨论/@mention | -| `outputs` | db.py:288 | Agent 产出物 | -| `decisions` | db.py:303 | 决策记录 | -| `observations` | db.py:315 | 风险/异常观察 | -| `events` | db.py:327 | 事件日志 | -| `agents` | db.py:339 | Agent 注册信息 | -| `task_attempts` | db.py:349 | 任务尝试记录 | -| `reviews` | db.py:365 | 评审结果 | -| `experiences` | db.py:384 | 经验沉淀 | -| `experience_tags` | db.py:402 | 经验标签 | -| `routing_decisions` | db.py:410 | 路由决策记录 | -| `checkpoints` | db.py:117,433 | Checkpoint 数据（两处定义） | -| `tasks_v28` | db.py:70 | v2.8 迁移临时表 | -| `registry` (全局) | registry.py | Project 注册表（独立 DB） | - -**tasks 表字段（实际）**： +#### 5.1.1 tasks 表 ✅ ```sql -id, title, description, status, assignee, assigned_by, -depends_on, parent_task, priority, task_type, -created_at, updated_at, claimed_at, started_at, completed_at, -deadline, retry_count, max_retries, must_haves, risk_level, -estimated_duration_minutes, escalated, -- ⚠️ 布尔字段，已被 escalated 状态取代 -current_agent, previous_agent, next_capability, -- v2.6.1 路由扩展 -stage, stages_json, -- v2.7 SubTask -resumed_from, -- v3.1 暂停恢复 -archived, archived_at -- v2.8 归档（models.py 有，db.py DDL 无） +CREATE TABLE tasks ( + id TEXT PRIMARY KEY, + title TEXT NOT NULL, + description TEXT, + status TEXT NOT NULL DEFAULT 'pending', + CHECK (status IN ('pending','claimed','working','review','paused', + 'escalated','waiting_human','done','failed', + 'blocked','cancelled')), + assignee TEXT, + assigned_by TEXT, + depends_on TEXT, -- JSON array of task IDs + parent_task TEXT, -- 父任务 (Task 自引用) + priority INTEGER NOT NULL DEFAULT 5, + task_type TEXT, + created_at TEXT NOT NULL DEFAULT (datetime('now')), + updated_at TEXT NOT NULL DEFAULT (datetime('now')), + claimed_at TEXT, + started_at TEXT, + completed_at TEXT, + deadline TEXT, + retry_count INTEGER NOT NULL DEFAULT 0, + max_retries INTEGER NOT NULL DEFAULT 2, + must_haves TEXT, -- JSON + risk_level TEXT DEFAULT 'standard', + estimated_duration_minutes INTEGER, + escalated INTEGER DEFAULT 0, + current_agent TEXT, -- v2.6.1 路由扩展 + previous_agent TEXT, + next_capability TEXT, + stage TEXT, -- v2.7 所属 Stage 标签 + stages_json TEXT DEFAULT '[]', -- v2.7 动态 Stage 定义 + archived INTEGER DEFAULT 0, -- v2.8 归档 + archived_at TEXT +); ``` -**状态枚举（实际）**： +**实现状态**: +- ✅ 11 个状态完整实现 (db.py `VALID_STATUSES`) +- ✅ `VALID_TRANSITIONS` 完整状态机 (v3.1 扩展了 paused 的恢复) +- ✅ `stages_json` 字段 (v2.7 SubTask 模型) +- ✅ `archived` / `archived_at` (v2.8 归档) +- ✅ `resumed_from` 字段 (v3.1 暂停恢复，在 models.py 中) +- ⚠️ `escalated INTEGER` 保留但设计要求改用 `status == 'escalated'`（向后兼容） -``` -pending, claimed, working, review, paused, escalated, -waiting_human, done, failed, blocked, cancelled +#### 5.1.2 comments 表 ✅ + +```sql +CREATE TABLE comments ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + task_id TEXT NOT NULL, + author TEXT NOT NULL, + comment_type TEXT NOT NULL DEFAULT 'general', + CHECK (comment_type IN ('general', 'handoff', 'observation', 'rebuttal', + 'rebuttal_response', 'debate_argument', 'debate_rebuttal', 'debate_judgment')), + body TEXT NOT NULL, + mentions TEXT, -- JSON array + created_at TEXT NOT NULL DEFAULT (datetime('now')) +); ``` -### 2.2 设计差异 +- ✅ 8 种 comment_type 全部实现 +- ✅ @mention 支持 (JSON 数组) -| # | 差异 | PRD/设计 | 代码实际 | 标记 | -|---|------|----------|---------|------| -| D1 | archived 字段 | v2.8 设计要求 | models.py 有，db.py CREATE TABLE 无（需迁移脚本添加） | ⚠️ 部分 | -| D2 | tasks_v28 临时表 | 不应存在于正式 schema | db.py:70 有 CREATE TABLE tasks_v28 | 🔀 遗留 | -| D3 | checkpoints 表 | 两处定义 | db.py:117 和 db.py:433 重复定义 | ⚠️ 冗余 | -| D4 | verification_commands | architecture-v2.6 §15.1 借鉴1 | tasks 表无此字段 | ❌ 未实现 | -| D5 | max_ticks | architecture-v2.6 §15.1 借鉴3 Runaway Guard | tasks 表无此字段 | ❌ 未实现 | -| D6 | scope_declaration | architecture-v2.6 §9.3 方案审查 | decisions 表可承载但无专门 schema | ⚠️ 部分 | -| D7 | handoff schema | architecture-v2.6 §5.1 | comments 表无 handoff 类型校验 | ⚠️ 部分 | -| D8 | parent_task 聚合 | v2.7 设计 §2.2 | ticker.py _refresh_parent_statuses 已实现 | ✅ | +#### 5.1.3 outputs 表 ✅ -### 2.3 Project Registry - -✅ **已实现** — `ProjectRegistry`（registry.py） - -- 独立 `registry.db`（全局，非 per-project） -- 自动扫描 `~/.openclaw/sanguo_projects/sanguo_*` -- CRUD + archive + discover + migrate_from_yaml - ---- - -## 3. Daemon 设计 - -### 3.1 Ticker ✅ **已实现** - -**文件**: `ticker.py`（40399 bytes） - -**核心职责**： -- 30s 周期 tick -- 扫描任务状态 → 依赖推进 → 超时检测 → 调度 pending → 调度 review -- 父 Task 状态聚合（`_refresh_parent_statuses`） -- 广播认领（`_build_claim_prompt`） -- 僵尸/超时处理（claimed 5min → pending，working 30min → failed） -- Mail 检查回复（`_mail_check_reply`） - -**设计差异**： - -| # | 设计 | 代码实际 | 标记 | -|---|------|---------|------| -| T1 | Tick 30s + Inbox JSONL 加速 | 只实现 Tick，Inbox Watcher 已实现但未与 Ticker 集成加速 | ⚠️ | -| T2 | 连续 N tick 无变更告警 | `_check_timeouts` 有但无全局逻辑健康自检 | ⚠️ | -| T3 | Shadow Checkpoint（git commit） | 无 | ❌ | -| T4 | 暂停任务不参与调度/聚合 | 已实现（paused 跳过） | ✅ | - -### 3.2 Dispatcher ⚠️ **部分实现** - -**文件**: `dispatcher.py`（27278 bytes） - -**核心职责**： -- 任务调度决策（`decide()` → 分配 agent + spawn message） -- 支持 claim / retry / review / delegate / broadcast 五种模式 -- Mail 任务特殊处理（auto_working / auto_complete） - -**设计差异**： - -| # | 设计 | 代码实际 | 标记 | -|---|------|---------|------| -| D1 | "Agent 自主认领" | `_dispatch_pending` 仍走 Router 决定 → 强制 claimed → spawn | 🔀 v3.0-router-refactor.md 指出问题 | -| D2 | 广播认领路径 | `_build_claim_prompt` 已存在但未被主路径调用 | ⚠️ | -| D3 | 确定性交接路径 | next_capability / retry 已实现 | ✅ | -| D4 | Mail inform 自动完成 | `_mail_auto_complete` 已实现 | ✅ | - -### 3.3 Spawner ✅ **已实现** - -**文件**: `spawner.py`（52812 bytes，最大文件） - -**核心职责**： -- spawn Full Agent（`openclaw agent --agent --session-id `） -- 进程监控（stdout 解析 + 超时处理 + 退出分类） -- Session 注册/清理 -- Counter 集成（并发控制） -- 假死复活术（`_revive_session`） -- spawn 前检查（`_check_session_state`） -- 产出写入黑板（`_record_attempt`） - -**设计差异**： - -| # | 设计 | 代码实际 | 标记 | -|---|------|---------|------| -| S1 | Session 归档到 artifacts/{task}/archive | `_register_session` + `cleanup_session` 但归档逻辑简化 | ⚠️ | -| S2 | per-task 重试上限 | retry_count + max_retries 已实现 | ✅ | -| S3 | on_complete 回调 | 已实现（lambda 释放 counter） | ✅ | -| S4 | stdout JSON 解析 | `_parse_stdout_json` 已实现 | ✅ | -| S5 | 进程超时分类 | `_classify_outcome` 已实现 | ✅ | - -### 3.4 Router ⚠️ **部分实现** - -**文件**: `router.py`（7240 bytes） - -**核心职责**： -- Agent 路由决策（`route()` → 返回 agent_id + mode） -- 能力匹配（`_resolve_by_capability`） -- fallback 到庞统 - -**关键问题**（v3.0-router-refactor.md 已指出）： -- ~~`LLMDriver` 类用独立 OpenAI 客户端直连 API~~ **已移除**（config 注释 "v3.0: routing 配置已移除"） -- 仍使用 `_legacy_decide`（Router 决定分配）而非广播认领 - -### 3.5 Counter ✅ **已实现** - -**文件**: `counter.py`（5668 bytes） - -**核心职责**： -- 三层并发控制（global / per-agent / per-session-key） -- 冷却期（`is_cooling_down` / `set_cooldown`） -- 信号量实现 - -**配置**：`max_global=5, max_per_session=1, max_concurrent_sessions=3` - -### 3.6 Inbox ✅ **已实现** - -**文件**: `inbox.py`（10696 bytes） - -**核心职责**： -- JSONL 文件事件监听（`InboxWatcher`） -- 事件类型：agent_claim / agent_done / agent_spawned / output_written 等 -- 异步回调（`default_inbox_callback`） - -**设计差异**： - -| # | 设计 | 代码实际 | 标记 | -|---|------|---------|------| -| I1 | Inbox 加速 Ticker（即时 mini-tick） | InboxWatcher 已实现但未与 Ticker tick 集成 | ⚠️ | - -### 3.7 Health ✅ **已实现** - -**文件**: `health.py`（9590 bytes） - -**核心职责**： -- 僵尸任务检测（`zombie_threshold=20`） -- 告警写入黑板（`_write_alert`） -- 自动修复（`_write_resolution`） - -### 3.8 SSE ✅ **已实现** - -**文件**: `sse.py`（9205 bytes） - -**核心职责**： -- SSE 事件推送（`SSEBroker`） -- pub/sub 模式 -- 前端 EventSource 对接 - ---- - -## 4. Agent 交互设计 - -### 4.1 三层执行模型 ✅ **已实现** - -| 层级 | 方式 | 代码 | 用途 | -|------|------|------|------| -| L1 Daemon 直接操作 | SQLite/文件 | ticker/dispatcher | 状态更新、机械验证 | -| L2 spawn sub | 隔离 session | spawner._spawn_sub | 轻量检查 | -| L3 run agent | 完整参与者 | spawner.spawn_full_agent | 编码/审查/策略 | - -### 4.2 Agent 工具集 ✅ **已实现** - -**CLI**（`blackboard.py`）：read / create / claim / output / comment / decide / observe / review - -**API**（`blackboard_routes.py`）：完整 CRUD + claim + status + archive + events + summary - -### 4.3 Agent 交互流程 ⚠️ **部分实现** - -**设计**（architecture-v2.6 §5.1 五步）： -1. ✅ 读黑板（API + CLI） -2. ⚠️ 想自主决策 — 广播认领未完全启用 -3. ✅ 执行任务 -4. ✅ 写回黑板 -5. ⚠️ Handoff Comment — comments 表可承载但无 schema 校验 - -### 4.4 Handoff Comment ❌ **未实现** - -**设计**：结构化交接评论，CLI 校验 `schemas/handoff.schema.json`。 - -**代码实际**：`schemas/` 目录不存在。comments 表有 `comment_type` 字段但无 handoff 专用校验。 - ---- - -## 5. 路由与调度 - -### 5.1 当前实现 ⚠️ **与设计有差距** - -**v3.0-router-refactor.md 指出的问题**： -1. ~~LLMDriver 已移除~~ ✅ -2. `_dispatch_pending` 绕过认领机制 — **仍存在** -3. Daemon 替 Agent 做决策 — **仍存在** - -**当前流程**： -``` -pending → Router 决定 agent → 强制 claimed + spawn → Agent 被动执行 +```sql +CREATE TABLE outputs ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + task_id TEXT NOT NULL, + agent TEXT NOT NULL, + output_type TEXT NOT NULL, + title TEXT NOT NULL, + content_path TEXT, + summary TEXT, + metadata TEXT, -- JSON + attempt_number INTEGER DEFAULT 1, + created_at TEXT NOT NULL DEFAULT (datetime('now')) + -- v2.8 M3 扩展字段: + file_name TEXT, + file_size INTEGER, + file_path TEXT, + mime_type TEXT +); ``` -**设计目标流程**（v3.0-router-refactor.md）： -``` -pending → 确定性路径?(retry/handoff/assignee) → 直接 spawn - → 否 → 广播认领 → Agent 自主 claim -``` +- ✅ 核心字段全部实现 +- ✅ content_path 模式 (文件路径引用) +- ✅ content 直传模式 (后端自动写文件) +- ✅ M3 扩展字段 (file_name/file_size/file_path/mime_type) -### 5.2 调度模式 +#### 5.1.4 其他表 ✅ -| 模式 | 设计 | 代码 | 标记 | -|------|------|------|------| -| 确定性交接（retry/handoff） | ✅ 设计 | ✅ 实现 | ✅ | -| 广播认领 | ✅ 设计 | ⚠️ `_build_claim_prompt` 存在但未被主路径调用 | ⚠️ | -| 庞统兜底（delegate） | ✅ 设计 | ✅ 实现 | ✅ | -| 无人认领→escalated | ✅ 设计 | ✅ retry_count >= 3 逻辑 | ✅ | -| 用户介入链路 | ✅ 设计 | ✅ SSE + 前端按钮 | ✅ | - ---- - -## 6. 质量门控/审查体系 - -### 6.1 分级审查流水线 ⚠️ **部分实现** - -**设计**（architecture-v2.6 §9.2）： - -| 风险等级 | 流水线 | 实际 | -|---------|--------|------| -| high | 三阶段（方案+Guardrail+产出） | ❌ 无方案审查，ReviewPipeline 存在但简化 | -| standard | 二阶段（方案+产出） | ⚠️ ReviewPipeline 存在，但无方案审查 | -| low | 一阶段（Guardrail 自动） | ⚠️ ReviewPipeline 简化版 | -| research | 一阶段（庞统确认） | ❌ 无专门处理 | - -### 6.2 Review Pipeline ✅ **已实现（简化版）** - -**文件**: `review.py`（10335 bytes） - -**实际流程**： -1. ✅ 产出物存在性检查（`_check_existence`） -2. ✅ 格式合规检查（`_check_format`） -3. ✅ 内容质量检查（`_check_quality`） -4. ✅ Guardrail 门控（`_determine_gate`） -5. ✅ 综合评分 - -**缺失**： -- ❌ Investigation Protocol（五阶段） -- ❌ 多视角矩阵 -- ❌ 对抗性指令 - -### 6.3 Rebuttal Manager ✅ **已实现** - -**文件**: `review.py` `RebuttalManager` - -- `submit_rebuttal()` — 反驳提交 -- 审查 → 反驳 → 再审查 流转 - -### 6.4 审查协议注册表 ❌ **未实现** - -**设计**（architecture-v2.6 §9.4）： -- `review_protocols/` 目录（plan_review.yaml / output_review.yaml 等） -- 四维定义（审查维度/方法/多视角/对抗性指令） - -**代码实际**：`review_protocols/` 目录不存在。 - -### 6.5 反驳权 ⚠️ **部分实现** - -**设计**：分级触发（critical/major → spawn 反驳；minor → 自然修改；approved → 跳过）。 - -**代码实际**：`RebuttalManager` 存在但跳过条件/触发条件的分级逻辑未完整。 - ---- - -## 7. 上下文管理 - -### 7.1 Bootstrap Builder ✅ **已实现** - -**文件**: `bootstrap.py`（7631 bytes） - -**实际 L2 层结构**： - -| 层 | 设计 | 代码 | 标记 | -|----|------|------|------| -| L2a 操作规范 | role template | `_load_template(f"{role}.md")` | ⚠️ prompt_templates 目录不存在 | -| L2b 项目背景 | project_context | `_format_project_context` | ✅ | -| L2c 任务上下文 | task_context | `_format_task_context` | ✅ | -| L2d 前序产出 | depends_on outputs | `_format_depends_on` | ✅ | -| L2e Guardrail 规则 | guardrails.yaml | 代码有传入参数但调用方未注入 | ⚠️ | -| L2f 审查协议 | review_protocols/ | 代码有传入参数但目录不存在 | ❌ | -| L2g 经验注入 | experiences 表 | `_format_experiences` | ⚠️ 未接入自动沉淀 | -| L3 Skill descriptions | skills/*.json | `_format_skills` | ⚠️ skills 目录为空 | - -### 7.2 Context 预算 - -**设计**（architecture-v2.6 §11.3）：总计 35K~60K tokens。 - -**代码实际**：`max_tokens=4096`（远小于设计预算）。 - -### 7.3 prompt_templates 目录 ❌ **未实现** - -**设计**：每个 role 一个模板（executor.md / reviewer.md / planner.md / pangtong.md）。 - -**代码实际**：`prompt_templates/` 目录不存在。`_load_template` 返回 None。 - -### 7.4 Agent spawn 消息 - -**实际消息构建**：`spawner.build_spawn_message()` — 拼装黑板 API 信息 + Mail prompt。 - -**缺失**：未使用 `BootstrapBuilder.build()` 的完整四层构建。 - ---- - -## 8. 前端 - -### 8.1 已实现组件 ✅ - -| 组件 | 文件 | 状态 | +| 表名 | 状态 | 说明 | |------|------|------| -| EdictBoard（任务看板） | EdictBoard.tsx | ✅ | -| TaskModal（任务详情） | TaskModal.tsx | ✅ | -| MailPanel（飞鸽传书） | MailPanel.tsx | ✅ | -| CourtCeremony（朝堂议政） | CourtCeremony.tsx | ✅ | -| MonitorPanel（监控面板） | MonitorPanel.tsx | ✅ | -| MorningPanel（晨会） | MorningPanel.tsx | ✅ | -| NotificationCenter | NotificationCenter.tsx | ✅ | -| GlobalSearch | GlobalSearch.tsx | ✅ | -| Toaster | Toaster.tsx | ✅ | -| SettingsPanel | SettingsPanel.tsx | ✅ | -| SessionsPanel | SessionsPanel.tsx | ✅ | -| SkillsConfig | SkillsConfig.tsx | ✅ | -| ConfirmDialog | ConfirmDialog.tsx | ✅ | +| decisions | ✅ | 决策记录 (decider + decision + rationale + alternatives) | +| observations | ✅ | 观察记录 (observer + severity + body + resolved_by) | +| events | ✅ | 事件日志 (task_id + agent + event_type + detail JSON) | +| agents | ✅ | Agent 注册表 (agent_id + role + current_status + capabilities) | +| task_attempts | ✅ | 任务尝试记录 (attempt_number + outcome + exit_code + metadata) | +| reviews | ✅ | 审查记录 (review_type + verdict + confidence + round) | +| experiences | ✅ | 经验记录 (category + summary + confidence + tags) | +| experience_tags | ✅ | 经验标签 | +| checkpoints | ✅ | Checkpoint (M3: type + payload + status) | -### 8.2 已实现但代码已回滚的组件 +### 5.2 状态机 ✅ -| 组件 | 文件 | 状态 | -|------|------|------| -| ArtifactPanel | ArtifactPanel.tsx | ⚠️ 文件存在但 M3 未集成 | -| CheckpointPanel | CheckpointPanel.tsx | ⚠️ 文件存在但 M3 未集成 | - -### 8.3 前端架构 - -- React + TypeScript + Vite -- Zustand 状态管理（store.ts） -- Tailwind CSS -- SSE 实时推送 - -### 8.4 v2.8 设计要求 vs 实际 - -| 设计要求 | 实际 | 标记 | -|---------|------|------| -| 筛选栏两行布局 | 部分实现 | ⚠️ | -| 卡片快捷按钮 | 已实现 | ✅ | -| 项目下拉移入筛选栏 | 已实现 | ✅ | -| 状态筛选全覆盖（11 状态） | 已实现 | ✅ | -| 归档机制 | 前端有，后端 DDL 缺字段 | ⚠️ | - ---- - -## 9. Mail 系统 - -### 9.1 Mail Tab ✅ **已实现** - -**后端**（`mail_routes.py`）： -- `GET ""` — 列表（支持 from/status/unread 过滤） -- `GET /agents/list` — Agent 列表 -- `GET /summary` — 未读/总数 -- `GET /{mail_id}` — 详情 -- `POST ""` — 发送 -- `PATCH /{mail_id}` — 更新（标记已读等） - -**前端**（`MailPanel.tsx`）：三栏布局。 - -### 9.2 Mail 设计模式 - -- Mail = `_mail` 虚拟 Project -- 每封 Mail = 一个 Task（`must_haves` JSON 存 from/type/is_read/conversation_id） -- `inform` 类型自动标记 done - -### 9.3 已知问题 - -| 问题 | 标记 | -|------|------| -| list_mail from 过滤在内存层（量大时性能） | ⚠️ OBS-22 | -| send_mail from 字段冗余（assigned_by + must_haves.from） | ⚠️ OBS-25 | -| polling 不刷新 Mail | ⚠️ OBS-26 | -| inform 类型邮件超时重试 | ⚠️ MEMORY 记录 | - ---- - -## 10. 经验沉淀 - -### 10.1 Experience Store ✅ **已实现** - -**文件**: `experience.py`（9590 bytes） - -**功能**： -- ✅ CRUD（add / get / list_all / search / delete / count） -- ✅ 分类（ExperienceCategory） -- ✅ 标签（experience_tags 表） -- ✅ JSON 文件持久化 - -### 10.2 经验闭环 ⚠️ **部分实现** - -**设计**（课题6 DISCOVER→DISTILL→APPLY→IMPROVE）： - -| 阶段 | 设计 | 代码 | 标记 | -|------|------|------|------| -| DISCOVER | 任务完成后自动提取经验 | ❌ 无自动触发 | ❌ | -| DISTILL | 经验蒸馏（阈值触发） | ⚠️ Store 存在但无蒸馏逻辑 | ❌ | -| APPLY | Bootstrap 注入经验 | ✅ `_format_experiences` | ⚠️ | -| IMPROVE | Skill 升级 | ❌ | ❌ | - ---- - -## 11. Guardrail 体系 - -### 11.1 Guardrail Engine ✅ **已实现** - -**文件**: `guardrails.py`（5165 bytes）+ `guardrails.yaml` - -**六条安全红线**： - -| 规则 | 严重级别 | 动作 | 标记 | -|------|---------|------|------| -| 实盘交易拦截 | critical | block_and_notify | ✅ | -| 数据删除拦截 | critical | block_and_notify | ✅ | -| 系统配置变更拦截 | critical | block_and_notify | ✅ | -| 大额 Token 消耗 | warning | pause_and_notify | ✅ | -| Agent 不受控行为 | critical | terminate_and_escalate | ⚠️ TODO | -| 连续失败 | warning | pause_and_escalate | ✅ | - -**代码实现**： -- ✅ `check_task()` — 任务级模式匹配 -- ✅ `check_token_usage()` — Token 阈值 -- ✅ `check_consecutive_failure()` — 连续失败 - -### 11.2 设计差异 - -| 设计 | 代码 | 标记 | -|------|------|------| -| L1 机械+脚本验证 | 只有基础存在性检查，无 verification_commands | ⚠️ | -| L2 AI 轻量检查 | 无 subagent 检查 | ❌ | -| L3 安全红线 | GuardrailEngine 已实现 | ✅ | -| review_protocols/ YAML | 目录不存在 | ❌ | -| 输出型 guardrails（per task_type） | guardrails.yaml 只有全局红线 | ⚠️ | - ---- - -## 12. 事件驱动 - -### 12.1 Inbox JSONL ✅ **已实现** - -**文件**: `inbox.py` - -- ✅ 文件监听 + JSONL 格式 -- ✅ 多事件类型 -- ✅ 异步回调 - -### 12.2 事件类型 ✅ **已实现** - -events 表记录所有状态变更。 - -SSE 推送实时通知前端。 - -### 12.3 设计 vs 实际 - -| 设计 | 实际 | 标记 | -|------|------|------| -| Inbox 加速 Ticker（mini-tick） | InboxWatcher 运行但未与 Ticker 集成 | ⚠️ | -| 启动全量扫描 | Ticker 首次 tick 扫描所有任务 | ✅ | -| NODE_AFTER_EXECUTE Hook | 不存在 Hook 机制 | ❌ | -| Shadow Checkpoint Hook | 无 | ❌ | - ---- - -## 13. 多项目支持 - -### 13.1 Project Registry ✅ **已实现** - -- ✅ 自动扫描 `sanguo_*` 目录 -- ✅ per-project blackboard.db -- ✅ registry.db 全局索引 -- ✅ CRUD + archive + discover - -### 13.2 设计差异 - -| 设计（课题11） | 实际 | 标记 | -|---------------|------|------| -| per-project 线程并发 | Ticker 串行 tick 所有 project | ❌ | -| 全局 LLM 信号量 | Counter 有全局限制但无信号量 | ⚠️ | -| per-agent 互斥锁 | Counter per-agent 限制 | ✅ | -| 跨项目 bootstrap 注入 | build_for_task 不支持跨项目 | ❌ | -| Worktree 物理隔离 | 无 | ❌ | - ---- - -## 14. 状态机 - -### 14.1 完整状态定义 ✅ **已实现** - -11 个状态：`pending, claimed, working, review, paused, escalated, waiting_human, done, failed, blocked, cancelled` - -### 14.2 状态转换矩阵 - -**代码实际**（`db.py VALID_TRANSITIONS`）： +**v3.1 完整状态转换矩阵** (11 个状态): ```python VALID_TRANSITIONS = { - "pending": {"claimed", "cancelled"}, + "pending": {"claimed", "paused", "blocked", "cancelled"}, "claimed": {"working", "paused", "pending", "cancelled"}, - "working": {"review", "blocked", "failed", "paused", "escalated", "waiting_human", "cancelled"}, - "paused": {"working", "cancelled"}, - "review": {"done", "pending", "failed", "escalated", "waiting_human", "cancelled"}, + "working": {"review", "done", "blocked", "failed", "paused", + "escalated", "waiting_human", "cancelled"}, + "paused": {"working", "claimed", "review", "escalated", + "waiting_human", "cancelled"}, + "review": {"done", "pending", "failed", "paused", "escalated", + "waiting_human", "cancelled"}, "blocked": {"pending", "escalated", "cancelled"}, "failed": {"pending", "escalated", "cancelled"}, - "escalated": {"working", "pending", "cancelled"}, - "waiting_human": {"working", "done", "cancelled"}, - "done": set(), # 终态 - "cancelled": set(), # 终态 + "escalated": {"working", "pending", "paused", "cancelled"}, + "waiting_human": {"working", "done", "paused", "cancelled"}, + "done": {"cancelled"}, + "cancelled": {"pending"}, } ``` -### 14.3 差异 +**与 v2.8 设计的差异** 🔀: -| 设计（v3.0-router-refactor §5.6） | 代码实际 | 标记 | -|-----------------------------------|---------|------| -| cancelled 可重启动(→pending) | cancelled 是终态，无出口 | 🔀 | -| review 可暂停 | review 转换无 paused | ⚠️ | -| paused 恢复到暂停前状态 | `resumed_from` 字段存在 | ⚠️ | +| 状态 | v2.8 设计 | v3.1 代码 | 差异 | +|------|----------|----------|------| +| paused 恢复 | → working | → working/claimed/review/escalated/waiting_human | 代码更灵活：恢复到 `resumed_from` 记录的状态 | +| pending | → {claimed, cancelled} | → {claimed, paused, blocked, cancelled} | 代码多了 paused、blocked | +| done | → set() | → {cancelled} | 代码允许取消已完成任务 | +| cancelled | → set() | → {pending} | 代码允许重新启动已取消任务 | + +**手动状态** (不参与聚合): `cancelled`, `paused` + +**聚合优先级**: escalated > waiting_human > review > working/claimed > pending > failed > blocked + +### 5.3 项目注册表 ✅ + +- ✅ `registry.db` (SQLite) 管理多项目元数据 +- ✅ `ProjectRegistry` 类：CRUD + 自动发现 + YAML 迁移 +- ✅ 虚拟项目：`_mail` (飞鸽传书)、`_general` (一般任务) +- ✅ 自动发现：扫描含 `blackboard.db` 的目录 +- ✅ `discover_sanguo_projects()`：扫描 `sanguo_projects/` 下的正式项目 + +### 5.4 版本迁移 ✅ + +| 迁移 | 文件位置 | 说明 | +|------|---------|------| +| v2.6.1 | `db._migrate_v261()` | current_agent, previous_agent, next_capability 字段 | +| v2.7 | `db._migrate_v27()` | stages_json, stage 字段 | +| v2.8 | `db._migrate_v28()` | 3 新状态 CHECK 约束重建 + 归档字段 + checkpoints 表 + outputs M3 扩展 | --- -## 15. 待实现项汇总（原则 2/3） +## §6. Daemon 设计 -### 15.1 原则 2：PRD ✅ + 代码 ❌ + 设计 ❌ +### 6.1 Ticker 主循环 ✅ -| # | PRD 条目 | 说明 | -|---|---------|------| -| P2-1 | PRD §10.1 六条红线之"Agent 不受控行为" | guardrails.yaml 有定义但代码 TODO | -| P2-2 | PRD B4 持续学习闭环 | 经验沉淀闭环四阶段只实现存储 | +**文件**: `src/daemon/ticker.py` (~960 行) -### 15.2 原则 3：设计 ✅ + PRD ✅ + 代码 ❌ +``` +Ticker.tick() + ├─ 遍历 active 项目 (registry.list_projects()) + ├─ _tick_project(project_id, project_info): + │ ├─ init_db (首次) + │ ├─ 依赖推进 (blocked → pending) + │ ├─ _check_timeouts() + │ │ ├─ claimed 超时 (5min) → pending / escalated + │ │ ├─ working 超时 (30min) → failed + │ │ └─ 进程存活性检查 (PID alive) + │ ├─ _dispatch_pending() + │ │ └─ Dispatcher.dispatch() → Router → Spawner + │ ├─ _dispatch_reviews() + │ ├─ 僵尸检测 (HealthChecker.check()) + │ ├─ 经验蒸馏 (ExperienceDistiller) + │ ├─ 父 Task 聚合刷新 + │ └─ daemon_tick 事件写入 + ├─ 虚拟项目 _general (如果存在) + └─ 虚拟项目 _mail (如果存在) +``` -| # | 设计文档 | 功能 | 来源 | -|---|---------|------|------| -| P3-1 | v3.0-router-refactor | 广播认领路径替代 Daemon 决策 | §3 | -| P3-2 | architecture-v2.6 §9.4 | 审查协议注册表（review_protocols/） | §9.4 | -| P3-3 | architecture-v2.6 §15.1 | Verification Commands（L1 脚本验证） | 借鉴1 | -| P3-4 | architecture-v2.6 §15.1 | Runaway Guard（max_ticks） | 借鉴3 | -| P3-5 | architecture-v2.6 §15.1 | Shadow Checkpoint（产出 git commit） | 借鉴5 | -| P3-6 | architecture-v2.6 §9.9 | 对抗辩论模式（high 风险任务） | §9.10 | -| P3-7 | v2.7-subtask-model | 跨项目 bootstrap 注入 | §2.4 | -| P3-8 | architecture-v2.6 §11 | SkillRouter 检索 | §12 待推进 | -| P3-9 | architecture-v2.6 §12 | 课题11 多项目线程并发 | topic11 | -| P3-10 | v2.8-executor-prompt-design | prompt_templates 四层注入 | 全文 | -| P3-11 | v2.8-state-enhancement | Checkpoint 三种类型 | §4 | -| P3-12 | v2.8-state-enhancement | Artifact 成果物面板 | §5 | -| P3-13 | architecture-v2.6 §5.1 | Handoff Comment schema 校验 | §5.1 | -| P3-14 | architecture-v2.6 §9.4 | Investigation Protocol 五阶段 | §9.4 | +**配置**: +- `tick_interval`: 30s +- `claim_timeout_minutes`: 5.0 +- `default_task_timeout_minutes`: 30.0 +- `max_dispatch_per_tick`: 3 + +**实现状态**: +- ✅ 30s 主循环 +- ✅ per-project 扫描 +- ✅ 依赖推进 +- ✅ 超时检测 (claimed + working) +- ✅ 调度 pending/review 任务 +- ✅ 僵尸检测 +- ✅ 经验蒸馏调用 +- ✅ 父 Task 聚合 +- ✅ InboxWatcher 集成 +- ⚠️ `max_dispatch_per_tick` 限制已实现，但广播认领未实现 (v3.0 router-refactor 设计但未落地) + +### 6.2 Dispatcher 调度器 ✅ + +**文件**: `src/daemon/dispatcher.py` (~618 行) + +**职责**: +1. 从 Router 获取路由决策 +2. 执行 spawn (通过 Spawner) +3. 安全红线检查 (调度前拦截) +4. 写路由审计日志 (routing_decisions) + +**调度级别**: +| 级别 | 说明 | +|------|------| +| LOCAL | Daemon 本地执行 | +| FULL_AGENT | Full Agent spawn | +| ESCALATE | 升级庞统 | +| BLOCKED | 安全红线拦截 | + +**实现状态**: +- ✅ Router/Dispatcher 分层 +- ✅ Guardrail 安全红线前置检查 +- ✅ 路由审计日志 +- ✅ Mail 自动标 working (v2.7.1) +- ✅ 续杯 message 构建 + +### 6.3 Spawner 进程管理 ✅ + +**文件**: `src/daemon/spawner.py` (~1270 行) + +**核心能力**: +- ✅ `spawn_full_agent()`: 异步 spawn，含 counter acquire/release +- ✅ `_monitor_process()`: 630s 超时监控 +- ✅ 情况 A (进程退出) 12 个场景分类 (A0~A12) +- ✅ 情况 B (进程不退出) 4 个场景分类 (B1~B4) +- ✅ 续杯机制 (Gateway timeout → 复用 session_id) +- ✅ spawn 前 session state 检查 (防 webchat 冲突) +- ✅ Mail 专用 prompt 模板 (inform/request) +- ✅ Spawn prompt 模板 (含完整 API 操作指引) +- ✅ BootstrapBuilder 集成 + +**spawn_full_agent 生命周期** (v2.7.2): +``` +1. 分配 session_id +2. session state 检查 (main session 时) +3. counter.can_acquire() 三层检查 +4. counter.acquire() 占用 +5. spawn 进程 +6. wrapped_on_complete 闭包 → counter.release (try/finally 保证) +``` + +### 6.4 关键差异: 设计 vs 实现 + +| 设计文档 | 实际代码 | 状态 | +|---------|---------|------| +| 广播认领 (v3.0-router-refactor) | Router 模糊场景直接 delegate 庞统 | 🔀 广播认领设计未实现，改为确定性路由 + delegate | +| Session 存档清理 | spawner 有 `_sessions` 注册表但清理逻辑未完整集成 | ⚠️ | +| L2 Subagent spawn | `AgentSpawner` 注释了 Subagent 但未实现 | ❌ 只有 Full Agent spawn | +| `_parse_stdout_json` P0 修复 | 代码已修正为 `data["response"]["meta"]` 路径 | ✅ 已修复 | --- -## 16. PRD 新增建议（原则 4/5） +## §7. Agent 交互设计 -### 16.1 原则 4：调研有但 PRD 没有 +### 7.1 Agent-Backend API 契约 ✅ -| # | 调研来源 | 功能 | 建议 | -|---|---------|------|------| -| R4-1 | pipeline-architecture-research.md | Pipeline 多执行模式（parallel/loop/saga/interactive） | PRD 3.1 新增 Pipeline 执行模式条目 | -| R4-2 | spawner-monitor-design.md | spawn 前检查 + 假死复活术 | PRD 3.1 补充进程管理策略 | -| R4-3 | counter-lifecycle-fix v2.1 | per (agent, session) 粒度三层控制 | PRD 3.1 补充并发控制模型 | +**文件**: `src/api/blackboard_routes.py` (~478 行) -### 16.2 原则 5：代码有但 PRD/设计没有 +| API | 方法 | 状态 | 说明 | +|-----|------|------|------| +| `/api/projects/{pid}/tasks` | GET | ✅ | 任务列表，支持 status/assignee/parent_task 过滤 | +| `/api/projects/{pid}/tasks` | POST | ✅ | 创建任务，自动生成 ID 和 title | +| `/api/projects/{pid}/tasks/{tid}` | GET | ✅ | 任务详情，expand=all 含全部关联数据 | +| `/api/projects/{pid}/tasks/{tid}/claim` | POST | ✅ | 原子 CAS 认领 | +| `/api/projects/{pid}/tasks/{tid}/status` | POST | ✅ | 状态更新，含合法转换校验 + SSE 推送 | +| `/api/projects/{pid}/tasks/{tid}/outputs` | GET/POST | ✅ | 产出 CRUD | +| `/api/projects/{pid}/tasks/{tid}/comments` | GET/POST | ✅ | 评论 CRUD | +| `/api/projects/{pid}/tasks/{tid}/decisions` | GET/POST | ✅ | 决策记录 | +| `/api/projects/{pid}/tasks/{tid}/observations` | GET/POST | ✅ | 观察记录 | +| `/api/projects/{pid}/tasks/{tid}/reviews` | GET/POST | ✅ | 审查记录 | +| `/api/projects/{pid}/tasks/{tid}/experiences` | GET/POST | ✅ | 经验记录 | +| `/api/projects/{pid}/tasks/{tid}/progress` | GET | ✅ | Stage 进度 + 子 Task 统计 | +| `/api/projects/{pid}/tasks/{tid}/archive` | POST | ✅ | 归档/取消归档 | +| `/api/projects/{pid}/tasks/archive-done` | POST | ✅ | 一键归档 | +| `/api/projects/{pid}/tasks/{tid}/outputs/{oid}/download` | GET | ✅ | 产出物下载 | -| # | 代码位置 | 功能 | 判断 | -|---|---------|------|------| -| G5-1 | mail_routes.py | Mail 系统（PRD §2.6 有"通信"但无 Mail 专属条目） | PRD 3.1 新增 Mail 条目 | -| G5-2 | sse.py | SSE 实时推送 | 设计有（topic9），PRD 未明确 | -| G5-3 | checkpoint_routes.py | Checkpoint API 路由 | 设计有（M3），PRD 未明确 | -| G5-4 | task_attempts 表 | 任务尝试记录 | 设计无专门条目，补充 PRD | +**Agent 友好的错误响应** ✅: +```json +{ + "error": "invalid_transition", + "detail": "Cannot transition from claimed to review", + "valid_transitions": {"claimed": ["working", "pending", "cancelled"]}, + "hint": "From 'claimed', valid targets are: ['working', 'pending', 'cancelled']" +} +``` + +**Title 自动生成** ✅: 调用 zhipu GLM-4-flash 生成简短标题。 + +### 7.2 CLI 工具 ✅ + +**文件**: `src/cli/blackboard.py` (~330 行) + +支持的命令： +- `read` — 读取任务 +- `create` — 创建任务 +- `claim` — 认领任务 +- `output` — 写产出 +- `comment` — 写评论 +- `decide` — 记录决策 +- `observe` — 写观察 +- `review` — 写审查 + +### 7.3 Agent 被 Spawn 后的工作流 ✅ + +``` +1. 收到 spawn message (含 API 指引) +2. 标记 working (POST /tasks/{id}/status) +3. 执行任务 (编码/审查/数据等) +4. 写产出 (POST /tasks/{id}/outputs) +5. 写评论 (POST /tasks/{id}/comments) — 含 Handoff +6. 标记 review/done/failed +7. 进程退出 → Daemon 清理 +``` + +### 7.4 Handoff Comment ✅ + +- ✅ comment_type = "handoff" 支持 +- ✅ Schema 校验设计（schemas/ 目录定义）但 CLI 未集成校验 --- -## 17. 设计矛盾记录（原则 6） +## §8. 路由与调度 -### 6.1 广播认领 vs 强制分配 +### 8.1 AgentRouter 确定性路由 ✅ -- **PRD B1**："AI 参与每个决策层" → Agent 自主认领 -- **v3.0-router-refactor**：明确指出 `_dispatch_pending` 违背"Agent 决策"原则 -- **代码实际**：仍走 Router 决定 → 强制 claimed -- **结论**：以 PRD 为准，v3.0 需实施广播认领 +**文件**: `src/daemon/router.py` (~180 行) -### 6.2 escalated 字段 vs 状态 +**v3.0 核心变更**: 去掉独立 LLM (LLMDriver)，模糊场景 delegate 庞统。 -- **v2.8-state-enhancement**：`escalated` 应为独立状态，废弃布尔字段 -- **代码实际**：tasks 表有 `escalated INTEGER DEFAULT 0`（布尔）+ `status='escalated'`（状态）共存 -- **结论**：以 v2.8 设计为准，布尔字段做向后兼容 +**路由模式**: +``` +route(task_info, action_type): + ├─ LOCAL_ACTIONS → daemon 本地执行 + ├─ retry → 原执行者 + ├─ next_capability → 能力匹配 (排除当前 Agent) + ├─ 生命周期流转 (review → review capability) + ├─ 有 assignee → 直接分 + └─ 模糊场景 → delegate 庞统 (L3 spawn, 走 Gateway) +``` -### 6.3 Bootstrap 4096 vs 设计预算 35K~60K +**Agent 能力画像** ✅: -- **设计**（§11.3）：上下文预算 35K~60K tokens -- **代码实际**：`max_tokens=4096` -- **结论**：4096 偏小，需调大。但实际 BootstrapBuilder 未被主路径调用，差距暂无影响 +| Agent | 能力 | can_review | is_fallback | +|-------|------|-----------|------------| +| zhangfei-dev | coding, implementation, scripting | false | false | +| simayi-challenger | review, quality_check, debate | true | false | +| guanyu-dev | risk, compliance, position_check | true | false | +| zhaoyun-data | data, acquisition, cleaning, verification | false | false | +| jiangwei-infra | deploy, infrastructure, docker, vnpy | false | false | +| pangtong-fujunshi | planning, coordination, escalation, strategy | true | **true** | -### 6.4 cancelled 终态 vs 可重启 +**RouteDecision** ✅: +- `mode`: "deterministic" | "agent_handoff" | "delegate" | "fallback" +- `confidence`: 0.0~1.0 +- `latency_ms`: 路由耗时 -- **v3.0-router-refactor §5.6**：cancelled 可重启动（→pending） -- **代码实际**：cancelled 是终态（`set()`） -- **结论**：需确认 PRD 立场。当前代码 cancelled 不可逆 +### 8.2 并发控制 ✅ -### 6.5 Mail 完全退役 vs Mail Tab 存在 +**文件**: `src/daemon/counter.py` (~170 行) -- **architecture-v2.6 §8**："Sanguo Mail: 退役" -- **代码实际**：Mail Tab 完整实现（mail_routes.py + MailPanel.tsx） -- **结论**：Mail 在 v2.7 后重新引入为"飞鸽传书"功能，与 v2.6 的"退役"不矛盾（v2.6 指的是旧版 Sanguo Mail 服务，新版是黑板内的 Mail Tab） +**v2.1: per (agent, session) 粒度，三层控制**: + +| 层级 | 配置 | 默认值 | 作用 | +|------|------|--------|------| +| per session key | `max_per_session` | 1 | 同一 (agent, session) 不能并发 spawn | +| per agent | `max_concurrent_sessions` | 3 | 同一 agent 最多同时跑 N 个不同 session | +| global | `max_global_agents` | 5 | 全局总并发上限 | + +**冷却机制** ✅: +- `set_cooldown(agent_id, seconds=120)`: API 429 后冷却 +- `is_cooling_down(agent_id)`: 检查冷却状态 + +### 8.3 广播认领 ❌ + +**设计文档 (v3.0-router-refactor)**: +- 广播所有空闲 Agent → 自主 claim → 续杯兜底 + +**实际代码**: +- ❌ `_broadcast_claim` 未实现 +- ✅ 模糊场景直接 delegate 庞统 +- 🔀 设计要求"Agent 自主领活"，实际是"Router 决定 + delegate" --- -## 18. 技术选型 +## §9. 质量门控/审查体系 -| 需求 | 方案 | 来源 | +### 9.1 ReviewPipeline ✅ + +**文件**: `src/daemon/review.py` (~335 行) + +**验证链**: 产出物存在性 → 格式合规 → 内容质量 → 评分 + +| 步骤 | 检查内容 | 状态 | +|------|---------|------| +| Step 1: 存在性 | 产出文件是否存在 | ✅ | +| Step 2: 格式合规 | markdown/JSON 格式检查 | ✅ | +| Step 3: 内容质量 | 自定义检查 + 文件大小检查 | ✅ | +| Step 4: Guardrail 门控 | 低/中/高风险分级 | ✅ | + +**门控级别**: + +| 风险等级 | 门控 | 说明 | +|---------|------|------| +| low | automatic | 自动检查通过即完成 | +| standard | mandatory | 需人工审查 | +| high | dual | 双重审查 (对抗辩论) | +| extreme | dual | 双重审查 + 强制审批 | + +### 9.2 分级审查流水线 ⚠️ + +**设计 (v2.6.4)**: +- ✅ high/standard/low/research 四级 +- ✅ 三阶段: 方案审查 → Guardrail 自动 → 产出审查 +- ✅ 反驳权 (Rebuttal Phase) + +**实现状态**: +- ✅ ReviewPipeline 验证链 +- ✅ reviews 表 + verdict 字段 (approved/rejected/needs_revision) +- ❌ 方案审查 (plan_review) 协议未集成到 Daemon 流程 +- ❌ 反驳权 (Rebuttal Phase) 未自动化 +- ❌ 审查协议注册表 (review_protocols/) 未集成 +- ❌ 对抗辩论模式未实现 + +### 9.3 Guardrail 安全红线 ✅ + +**文件**: `src/daemon/guardrails.py` (~140 行) + `config/guardrails.yaml` + +**PRD §10.1 六条红线**: + +| 红线 | ID | 配置 | 代码 | 说明 | +|------|-----|------|------|------| +| 实盘交易 | live_trading | ✅ | ✅ | pattern 匹配 + task_type | +| 数据删除 | data_deletion | ✅ | ✅ | pattern 匹配 | +| 配置变更 | config_change | ✅ | ✅ | pattern 匹配 | +| 大额 Token | high_token_usage | ✅ | ✅ | token_threshold 检查 | +| Agent 不受控 | agent_uncontrolled | ✅ | ⚠️ | 规则定义在，但 step 超限检查未集成 | +| 连续失败 | consecutive_failure | ✅ | ✅ | consecutive_failures 检查 | + +**GuardrailEngine 能力**: +- ✅ `check_task()`: 任务调度前检查 +- ✅ `check_token_usage()`: Token 消耗检查 +- ✅ `check_consecutive_failure()`: 连续失败检查 +- ✅ pattern 正则匹配 + task_type 匹配 +- ✅ action 分级: block_and_notify / pause_and_notify / terminate_and_escalate + +--- + +## §10. 上下文管理 + +### 10.1 BootstrapBuilder 四层上下文 ✅ + +**文件**: `src/daemon/bootstrap.py` (~216 行) + +| 层 | 内容 | Token 估算 | 状态 | +|----|------|-----------|------| +| L0 铁律层 | Hook 注入，不占 bootstrap | ~500 | ❌ 未集成到 Daemon | +| L1 角色层 | SOUL.md / IDENTITY.md (Agent 自带) | ~2000 | ✅ Agent 自有 | +| L2 引擎注入 | 操作规范 + 任务上下文 + 前序信息 + Guardrail + 审查协议 | ~1500 | ✅ BootstrapBuilder | +| L3 被动参考 | Skill description | 按需 | ✅ SkillRegistry | + +**L2 注入内容 (按 role)**: + +| 角色 | 注入内容 | +|------|---------| +| executor | role_template + 项目背景 + 任务上下文 + 前序产出 + Guardrail + 审查协议 + 经验 | +| reviewer | role_template + 项目背景 + 任务上下文 + 审查协议 | +| planner | role_template + 项目背景 + 任务上下文 + 审查协议 | +| pangtong | role_template + 项目背景 + 任务上下文 + 审查协议 | + +**Token 预算**: +- `max_tokens`: 4096 (默认) +- 超限时自动截断 + +### 10.2 上下文预算 ✅ + +| 组件 | 预算 | 实际 | |------|------|------| -| 共享状态 | SQLite WAL + per-project DB | Hermes / Network-AI | -| 事件驱动 | Tick 30s + Inbox JSONL | open-multi-agent | -| 上下文传递 | L0~L3 四层注入 | Claude Code / GSD | -| 进程管理 | openclaw agent + subprocess.Popen | OpenClaw 原生 | -| 并发控制 | Counter 三层信号量 | 自研 | -| 前端 | React + TypeScript + Vite + Tailwind + Zustand | v1.0 技术栈 | -| 实时推送 | SSE (EventSource) | v2.0 新增 | -| 配置 | YAML (default.yaml + guardrails.yaml) | 简单可靠 | -| 安全红线 | GuardrailEngine + YAML 规则 | PRD §10.1 | +| System Prompt + SOUL.md | ~3000-5000 | Agent 自有 | +| L2 引擎注入 | ~1000-2000 | BootstrapBuilder | +| 工作空间 | ~30000-50000 | Agent 剩余 context | +| **总计** | **~35K-60K** | 远小于 128K，安全 | + +### 10.3 prompt_templates 目录 ⚠️ + +**设计**: `prompt_templates/executor.md`, `reviewer.md`, `planner.md` 等角色模板 + +**实现**: BootstrapBuilder 支持 `_load_template()` 加载模板文件，但实际的 prompt template 文件未完整创建。 --- -## 19. 代码规模统计 +## §11. 前端 -| 模块 | 文件数 | 总行数（约） | -|------|--------|------------| -| daemon/ | 14 | ~2500 | -| blackboard/ | 5 | ~1400 | -| api/ | 6 | ~800 | -| cli/ | 2 | ~500 | -| frontend/src/ | ~28 | ~5000 | -| config/ | 2 | ~120 | -| **总计** | ~57 | **~10320** | +### 11.1 现有前端 ✅ ---- +**目录**: `frontend/` (Vite + React + TypeScript) -## 20. 关键决策记录 - -| 决策 | 结论 | 来源 | +| 组件 | 状态 | 说明 | |------|------|------| -| Card 层去留 | 回滚，用 Task 自引用 | v2.7-subtask-model | -| SubTask 表 | 不建，复用 parent_task | v2.7-subtask-model | -| 路由方式 | 广播认领（待实施） | v3.0-router-refactor | -| LLMDriver | 已移除 | v3.0-router-refactor | -| Mail | 重新引入为 Tab | v2.7-subtask-model | -| Checkpoint | 设计完成，代码回滚待重新实施 | v2.8-state-enhancement | -| Bootstrap | 四层构建器存在但未接入主路径 | v2.8-executor-prompt-design | +| EdictBoard.tsx | ✅ | 任务看板 (卡片布局) | +| TaskModal.tsx | ✅ | 任务详情弹窗 | +| MailTab.tsx | ✅ | 邮件 Tab | +| SSE 集成 | ✅ | EventSource 实时推送 | +| 通知中心 | ✅ | SSE 事件通知 | +| CheckpointPanel.tsx | ⚠️ | 文件存在但未被引用 | +| ArtifactPanel.tsx | ⚠️ | 文件存在但未被引用 | + +### 11.2 v2.8 设计 vs 实现 🔀 + +| 设计 (v2.8-state-enhancement) | 实际前端 | 状态 | +|------|---------|------| +| 两行筛选栏 | 基础筛选 | ⚠️ | +| 项目下拉移入筛选栏 | 项目在 header | ⚠️ | +| 卡片快捷按钮 (⏸▶🚫) | 部分实现 | ⚠️ | +| 新状态颜色 (paused 紫/escalated 红/waiting_human 橙) | 需确认 | ⚠️ | +| 归档筛选 (活跃/归档/全部) | 需确认 | ⚠️ | + +### 11.3 Dashboard AI Native 化 ❌ + +**PRD 目标**: AI Briefing + 智能摘要 + 上下文感知布局 + +**实际**: 前端是传统的 CRUD 看板，无 AI Native 特性。 + +--- + +## §12. Mail 系统 + +### 12.1 Mail Tab ✅ + +**文件**: `src/api/mail_routes.py` (~240 行) + +**设计**: Mail 是特殊的 Project (`_mail`)，每封 Mail 是一个 Task。 + +| API | 方法 | 状态 | +|-----|------|------| +| `/api/mail` | GET | ✅ | 邮件列表 (时间倒序) | +| `/api/mail` | POST | ✅ | 发送邮件 (创建 Task) | +| `/api/mail/{id}` | GET | ✅ | 邮件详情 (含 comments 线程) | +| `/api/mail/agents/list` | GET | ✅ | 参与过 Mail 的 Agent 列表 | +| `/api/mail/summary` | GET | ✅ | 未读数 + 总数 | + +**特性**: +- ✅ `conversation_id` 自动管理 (回复继承) +- ✅ `in_reply_to` 关联 +- ✅ `type` 自动处理 (回复默认 inform 防循环) +- ✅ Mail spawn 时系统自动标 working +- ✅ Mail 续杯专用 prompt (不含状态转换指令) + +### 12.2 与 v2.6 设计的关系 🔀 + +**v2.6**: "Mail 完全退役，黑板替代所有功能" + +**实际**: Mail 作为 `_mail` 虚拟项目保留，功能完整。这是正确的工程决策——Mail 提供了 Agent 间的异步通信能力，黑板更适合任务级协作。 + +--- + +## §13. 经验沉淀 + +### 13.1 ExperienceDistiller ✅ + +**文件**: `src/daemon/experience.py` (~290 行) + +**经验分类**: + +| 类别 | 关键词 | +|------|--------| +| pitfall | bug/error/fail/陷阱/踩坑 | +| best_practice | should/recommend/最佳实践 | +| environment | install/configure/环境 | +| pattern | 通用模式 | +| decision | 决策记录 | + +**ExperienceStore** ✅: +- JSONL 持久化 +- add/get/search/delete/list_all + +**ExperienceDistiller** ✅: +- 从 review 结果提取 pitfall +- 从 task 产出提取 best_practice +- 模式关键词匹配 + +### 13.2 经验注入 ✅ + +**BootstrapBuilder** 支持 `experiences` 参数，在 L2 层注入最多 5 条相关经验。 + +### 13.3 经验闭环 ⚠️ + +**设计 (v2.6.7)**: DISCOVER → DISTILL → APPLY → IMPROVE 闭环 + +**实际**: +- ✅ DISTILL: ExperienceDistiller 自动蒸馏 +- ✅ APPLY: BootstrapBuilder 注入经验 +- ❌ IMPROVE: 经验使用后反馈/更新机制未实现 +- ❌ 一级蒸馏 (实时) + 二级蒸馏 (周期) 未区分 + +### 13.4 experiences 表 ✅ + +```sql +CREATE TABLE experiences ( + experience_id TEXT PRIMARY KEY, + source TEXT, + task_id TEXT, + summary TEXT, + category TEXT, + confidence REAL DEFAULT 0.8, + status TEXT DEFAULT 'active', + skill_id TEXT, + usage_count INTEGER DEFAULT 0, + last_used_at TEXT, + created_at TEXT, + created_by TEXT, + updated_at TEXT, + deprecated_reason TEXT +); +``` + +--- + +## §14. Guardrail 体系 + +### 14.1 GuardrailEngine ✅ + +详见 §9.3。补充架构层信息： + +**Guardrail 检查位置**: +1. **Dispatcher.dispatch()** — 调度前检查 ✅ +2. **ReviewPipeline** — 产出写入后检查 ✅ +3. **Ticker._check_timeouts()** — 超时触发检查 ✅ + +**违反后的行为**: + +| action | 行为 | +|--------|------| +| block_and_notify | 阻止调度 + 写黑板事件 | +| pause_and_notify | 暂停任务 + 通知 | +| terminate_and_escalate | 终止 Agent + 升级 | +| pause_and_escalate | 暂停 + 升级 | + +### 14.2 verification_commands ❌ + +**设计 (v2.6.9 借鉴1)**: 任务 Plan 中声明验证命令 (pytest, flake8 等)，Daemon Guardrail 自动执行。 + +**实际**: ❌ 未实现。tasks 表无 `verification_commands` 字段。 + +### 14.3 Runaway Guard ❌ + +**设计 (v2.6.9 借鉴3)**: 每个任务最大 tick 上限 (max_ticks=100)，超限暂停 + 告警。 + +**实际**: ❌ 未实现。tasks 表无 `tick_count` / `max_ticks` 字段。 + +--- + +## §15. 事件驱动 + +### 15.1 InboxWatcher ✅ + +**文件**: `src/daemon/inbox.py` (~306 行) + +- ✅ JSONL 文件监听 (1s 轮询) +- ✅ truncate 模式 (清空内容不删除文件) +- ✅ 原子追加写入 (OS 保证 append 原子性) +- ✅ 异步回调处理 +- ✅ 支持的事件: agent_output / agent_claim / agent_status / agent_heartbeat + +**与 Ticker 的关系**: +``` +Ticker.start() + ├─ InboxWatcher.start() → 1s 轮询 inbox/daemon.jsonl + └─ _loop() → 30s 全量 tick + +InboxWatcher 发现事件 → process_callback → mini-tick? + 实际: process_callback 由 Ticker 注入，触发针对性处理 +``` + +### 15.2 SSE 实时推送 ✅ + +**文件**: `src/daemon/sse.py` (~313 行) + +- ✅ SSEBroker: 发布/订阅模式 +- ✅ SSEEvent: 结构化事件 (id + type + data + timestamp) +- ✅ 100 条事件历史缓存 +- ✅ subscriber 队列 (maxsize=100) + +**Hook 系统** ✅: +- HookType: webhook / script / callback +- HookManager: 注册/注销/触发 +- 支持超时控制 (10s) + +### 15.3 事件类型 ✅ + +```python +SSEEventType: + TASK_CREATED, TASK_UPDATED, TASK_COMPLETED, TASK_FAILED, + OBSERVATION_ADDED, AGENT_SPAWNED, AGENT_COMPLETED, + DAEMON_TICK, REVIEW_RESULT, HOOK_TRIGGERED +``` + +--- + +## §16. 多项目支持 + +### 16.1 架构 ✅ + +**设计 (v2.6.10 方案C)**: 单 Daemon + 多数据库 + per-project 并发 + +**实际实现**: + +| 组件 | 状态 | 说明 | +|------|------|------| +| per-project blackboard.db | ✅ | 每个项目独立 SQLite | +| registry.db | ✅ | 全局项目注册表 | +| ProjectRegistry | ✅ | CRUD + 自动发现 + YAML 迁移 | +| 虚拟项目 | ✅ | `_mail`, `_general` | +| 任务跨项目移动 | ✅ | `POST /api/projects/{pid}/tasks/{tid}/move` | +| per-project 并发线程 | ❌ | 当前是 asyncio 单线程顺序处理 | + +### 16.2 项目管理 API ✅ + +| API | 方法 | 状态 | +|-----|------|------| +| `/api/projects` | GET | ✅ | 项目列表 (含实时任务统计) | +| `/api/projects` | POST | ✅ | 创建项目 | +| `/api/projects/{pid}` | GET | ✅ | 项目详情 | +| `/api/projects/{pid}` | PATCH | ✅ | 更新项目 | +| `/api/projects/{pid}/archive` | POST | ✅ | 归档项目 | +| `/api/projects/{pid}` | DELETE | ✅ | 逻辑删除 | +| `/api/projects/{pid}/tasks/{tid}/move` | POST | ✅ | 跨项目移动任务 | + +--- + +## §17. 待实现项汇总（原则 2/3） + +### 17.1 PRD 明确要求但未实现 + +| # | 功能 | PRD 来源 | 设计文档 | 优先级 | +|---|------|---------|---------|--------| +| 1 | **需求探索对话** (苏格拉底式) | PRD B1/C1 | — | P1 | +| 2 | **动态规划** (活计划, 全程可调) | PRD B2/C2 | — | P1 | +| 3 | **持续指挥** (庞统全程在线) | PRD B2/C3 | — | P1 | +| 4 | **主动汇报** (AI 推送自然语言摘要) | PRD B4/C7 | v2.6.11 | P2 | +| 5 | **工具链集成** (lint/test/build) | PRD C10 | toolchain-proposal.md | P3 | +| 6 | **经验闭环** (IMPROVE 阶段) | PRD C8 | v2.6.7 | P3 | + +### 17.2 设计文档有详细方案但未实现 + +| # | 功能 | 设计文档 | 优先级 | +|---|------|---------|--------| +| 7 | **广播认领** (自主 claim) | v3.0-router-refactor §3.3 | P2 | +| 8 | **方案审查** (plan_review 协议) | v2.6.4 §9.3 | P2 | +| 9 | **反驳权** (Rebuttal Phase 自动化) | v2.6.4 §9.5 | P2 | +| 10 | **审查协议注册表** (review_protocols/) | v2.6.4 §9.4 | P2 | +| 11 | **对抗辩论模式** (high 风险任务) | v2.6.4 §9.10 | P3 | +| 12 | **Checkpoint 机制** (M3: verify/decision/action) | v2.8 §4 | P2 | +| 13 | **Artifact 成果物面板** (M3) | v2.8 §5 | P2 | +| 14 | **verification_commands** (Guardrail 验证脚本层) | v2.6.9 借鉴1 | P2 | +| 15 | **Runaway Guard** (max_ticks 上限) | v2.6.9 借鉴3 | P3 | +| 16 | **Shadow Checkpoint** (git 自动 commit) | v2.6.9 借鉴5 | P3 | +| 17 | **Skill 生命周期** (draft→active→deprecated) | v2.6.7 | P3 | +| 18 | **prompt_templates 角色模板** (完整文件) | v2.6.5 | P2 | +| 19 | **CLI Schema 校验** (schemas/ 目录) | v2.6.3 §3.7 | P2 | +| 20 | **L2 Subagent spawn** | v2.6.2 §4.1 | P3 | +| 21 | **假死复活术** (集成到 ticker) | v2.7.2 §3.6 | P3 | +| 22 | **per-provider 冷却** | v2.7.2 §5 | P4 | + +--- + +## §18. PRD 新增建议（原则 4/5） + +### 18.1 调研有但 PRD 未涵盖（原则 4） + +| # | 内容 | 来源 | 建议 | +|---|------|------|------| +| 1 | Skill System (三层自由度: 原则/模板/脚本) | SkillRegistry 代码 | PRD 应补充 C11: 可插拔技能体系 | +| 2 | Hook 系统 (webhook/script/callback) | SSEBroker + HookManager | PRD 应补充事件扩展机制 | +| 3 | per-project 并发隔离 | v2.6.10 方案C | PRD 应明确多项目并发模型 | +| 4 | Mail 保留 (与 PRD "Mail 退役"矛盾) | 实际代码 | PRD 应更新: Mail 作为辅助通道保留 | + +### 18.2 幽灵实现（原则 5: 代码有但设计没提） + +| # | 内容 | 代码位置 | 分析 | +|---|------|---------|------| +| 1 | **Title LLM 自动生成** | blackboard_routes._generate_title() | 代码直接调 zhipu API 生成标题，不走 Gateway。类似 v3.0 删除的 LLMDriver 问题（不走 Gateway，需单独维护凭据） | +| 2 | **任务跨项目移动** | project_routes.move_task() | 完整实现含子任务一起移动，但无对应设计文档 | +| 3 | **Mail conversation_id 自动管理** | mail_routes.send_mail() | 自动继承回复的 conversation_id，无设计文档记录 | +| 4 | **routing_decisions 审计日志** | dispatcher._record_routing() | 路由审计写入 routing_decisions 表，但 db.py 中该表定义在 schema 但未在模型中暴露 | + +--- + +## §19. 设计矛盾记录（原则 6） + +### 19.1 状态机矛盾 🔀 + +| 状态 | v2.8 设计 | v3.1 代码 | 影响 | +|------|----------|----------|------| +| `pending` | → {claimed, cancelled} | → {claimed, paused, blocked, cancelled} | 代码允许直接暂停/阻塞 pending 任务 | +| `paused` | → {working, cancelled} | → {working, claimed, review, escalated, waiting_human, cancelled} | 代码支持恢复到暂停前的任意状态 | +| `done` | → set() (终态) | → {cancelled} | 代码允许取消已完成任务 | +| `cancelled` | → set() (终态) | → {pending} | 代码允许重新启动已取消任务 | +| `TERMINAL_STATUSES` | 设计定义了终态 | 代码中为空集 `frozenset()` | v3.1 取消了终态概念，全靠 VALID_TRANSITIONS 校验 | + +**评估**: 代码的 v3.1 版本更灵活实用（支持暂停恢复、取消后重启），但与 v2.8 设计文档不一致。**建议更新设计文档对齐代码**。 + +### 19.2 Mail 退役矛盾 🔀 + +**v2.6 设计**: "Mail 完全退役。黑板的两个操作替代了 Mail 的所有功能。" + +**实际**: Mail 作为 `_mail` 虚拟项目完整保留，有独立的 API 路由、前端 Tab、专用 spawn prompt。 + +**评估**: Mail 保留是正确的工程决策。**建议 PRD 更新**：Mail 降级为辅助通道（非主力），但保留。 + +### 19.3 广播认领 vs Delegate 庞统 🔀 + +**v3.0-router-refactor 设计**: 去掉独立 LLM，改为"广播认领 + 确定性交接"。广播所有空闲 Agent → 自主 claim。 + +**实际**: Router 的模糊场景直接 delegate 庞统（`mode="delegate"`），无广播机制。 + +**评估**: delegate 庞统更简单可靠。广播认领的复杂度（多 Agent spawn 竞争、claim 超时管理）当前不必要。**建议保留广播认领设计作为 v3.1+ 目标**。 + +### 19.4 续杯设计矛盾 🔀 + +**spawner-monitor-design**: 续杯只有 A2/A3 (Gateway timeout) 触发。 + +**实际 spawner 代码**: 续杯逻辑在 `_handle_exit` 中，但具体的 `_do_retry` 实现可能存在差异（需确认所有场景是否按设计处理）。 + +### 19.5 LLMDriver 残留 👻 + +**v3.0 设计**: 删除 LLMDriver 类。 + +**实际 router.py**: LLMDriver 已删除 ✅。但 `blackboard_routes._generate_title()` 仍然直接调 zhipu API（不走 Gateway），属于同类问题。 + +--- + +## §20. 技术选型 + +### 20.1 核心技术栈 ✅ + +| 需求 | 选型 | 理由 | +|------|------|------| +| Web 框架 | FastAPI (Python) | 异步 + 自动文档 + 类型安全 | +| 数据库 | SQLite (per-project) | 原子性 + WAL + 零外部依赖 | +| 前端 | React + Vite + TypeScript | SPA + 快速构建 | +| 进程管理 | asyncio.create_subprocess_exec | 异步非阻塞 spawn | +| 实时推送 | SSE (Server-Sent Events) | 单向推送，比 WebSocket 简单 | +| 事件加速 | Inbox JSONL | agent-chorus 模式，跨进程通信 | +| 配置 | YAML (default.yaml + guardrails.yaml) | 人可读 + 可版本化 | +| 进程守护 | PM2 (Node.js) | 自动重启 + 日志管理 | +| Agent CLI | openclaw agent | OpenClaw 原生能力 | +| LLM 路由 | OpenClaw Gateway | 统一模型路由 + fallback + 计费 | + +### 20.2 关键配置参数 + +```yaml +daemon: + tick_interval: 30 + max_global_agents: 5 + max_per_session: 1 + max_concurrent_sessions: 3 + max_dispatch_per_tick: 3 + claim_timeout_minutes: 5.0 + default_task_timeout_minutes: 30.0 + agent_timeout: 630 + gateway_timeout: 600 + max_retries: 3 + max_monitor_timeouts: 3 + api_host: "127.0.0.1" + api_port: 8083 + zombie_threshold: 20 +``` + +### 20.3 数据库连接配置 ✅ + +```python +PRAGMA journal_mode=WAL # 并发读写 +PRAGMA foreign_keys=ON # 外键约束 +PRAGMA busy_timeout=5000 # 写锁等待 5s +``` + +### 20.4 参考系统映射 + +| 参考系统 | 借鉴点 | 映射到 | +|---------|--------|--------| +| Hermes Kanban | SQLite + Dispatcher tick | 黑板 + Ticker 30s | +| agent-chorus | JSONL inbox 跨进程通信 | InboxWatcher | +| open-multi-agent | TaskQueue.complete() → unblockDependents | 依赖推进 | +| Claude Code | file reference 模式 | outputs.content_path | +| Opal-Bridge | Fidelity 三档 | L1/L2/L3 上下文分层 | +| GSD Wave Execution | 隔离 session + 新鲜 context | per-task session | +| TradingAgents | Bull vs Bear 对抗辩论 | 审查体系 (设计) | +| superpowers | 三种 reviewer 角色 | ReviewPipeline 分级 | +| Aider | lint→test→commit | verification_commands (设计) | +| claude-goal | Stop Hook + 完成审计 | Guardrail + Runaway Guard (设计) | +| Cline | Shadow Git Checkpoint | Shadow Checkpoint (设计) | + +--- + +## 附录 A: 文件清单 + +### A.1 后端源码 + +| 文件 | 行数(约) | 职责 | +|------|---------|------| +| `src/main.py` | 300 | FastAPI 入口 + 组件初始化 + 生命周期 | +| `src/blackboard/db.py` | 450 | DB schema + 迁移 + 状态机常量 | +| `src/blackboard/models.py` | 200 | 数据类 (Task/Comment/Output/...) | +| `src/blackboard/operations.py` | 830 | 黑板 CRUD 操作 | +| `src/blackboard/queries.py` | 357 | 黑板只读查询 | +| `src/blackboard/registry.py` | 326 | 多项目注册表 | +| `src/daemon/ticker.py` | 960 | Ticker 主循环 | +| `src/daemon/dispatcher.py` | 618 | 调度器 (路由+spawn) | +| `src/daemon/spawner.py` | 1270 | 进程管理 + 监控 + 续杯 | +| `src/daemon/router.py` | 180 | 确定性路由决策 | +| `src/daemon/bootstrap.py` | 216 | 上下文构建 (L0-L3) | +| `src/daemon/counter.py` | 170 | 并发控制 + 冷却 | +| `src/daemon/guardrails.py` | 140 | 安全红线引擎 | +| `src/daemon/review.py` | 335 | 产出验证流水线 | +| `src/daemon/inbox.py` | 306 | Inbox JSONL 监听 | +| `src/daemon/experience.py` | 290 | 经验蒸馏 | +| `src/daemon/health.py` | 160 | 僵尸检测 | +| `src/daemon/sse.py` | 313 | SSE + Hook 系统 | +| `src/daemon/skill_system.py` | 248 | Skill 注册/匹配/执行 | +| `src/api/blackboard_routes.py` | 478 | 黑板 API 路由 | +| `src/api/mail_routes.py` | 240 | Mail API 路由 | +| `src/api/project_routes.py` | 190 | 项目管理 API | +| `src/cli/blackboard.py` | 330 | CLI 工具 | + +### A.2 配置文件 + +| 文件 | 说明 | +|------|------| +| `config/default.yaml` | 全局配置 (daemon/agent_profiles/inbox/review/experience) | +| `config/guardrails.yaml` | 安全红线 6 条规则 | + +### A.3 设计文档 + +| 文档 | 说明 | +|------|------| +| `docs/PRD-v3.0.md` | 产品需求文档 | +| `docs/design/architecture-v2.6.md` | v2.6 架构设计 (~2070 行) | +| `docs/design/v2.7-subtask-model.md` | SubTask 模型 (Task 自引用) | +| `docs/design/v2.8-state-enhancement.md` | 状态增强 + 归档 + Checkpoint | +| `docs/design/v2.7.2-counter-lifecycle-fix.md` | 防重复调用 & 防无限续杯 | +| `docs/design/v3.0-router-refactor.md` | 路由重构 (去 LLM, 广播认领) | +| `docs/design/spawner-monitor-design.md` | Spawner Monitor 设计 | +| `docs/design/agent-api-contract.md` | Agent API 契约 | + +--- + +## 附录 B: 实现状态总览 + +| 模块 | 已实现 | 部分实现 | 未实现 | +|------|--------|---------|--------| +| **数据模型** | SQLite schema, 11 状态, Task 自引用, 归档, Checkpoint | — | — | +| **Daemon Ticker** | 30s 循环, 依赖推进, 超时, 僵尸检测 | — | 广播认领 | +| **路由调度** | Router 确定性路由, delegate 庞统 | — | 广播认领, L2 Subagent | +| **Spawner** | 进程管理, 监控, 续杯, counter | Session 清理集成 | 假死复活术 | +| **质量门控** | ReviewPipeline, Guardrails 6 红线 | — | 方案审查, 反驳权, 对抗辩论 | +| **上下文** | BootstrapBuilder L0-L3 | prompt_templates 文件 | — | +| **前端** | 任务看板, Mail Tab, SSE | 新状态 UI | AI Native, Checkpoint/Artifact | +| **Mail** | 完整 Mail Tab + API | — | — | +| **经验沉淀** | Distiller, Store, 注入 | — | 闭环 IMPROVE, 一/二级蒸馏 | +| **事件驱动** | InboxWatcher, SSE Broker, Hook | — | — | +| **多项目** | Registry, per-project DB, 移动 | — | per-project 并发线程 | +| **安全** | Guardrails 6 线, Counter 并发 | — | verification_commands, Runaway Guard | +| **Skill** | SkillRegistry 三层自由度 | — | Skill 生命周期 | +| **需求探索** | — | — | 苏格拉底对话, 动态规划 | +| **主动汇报** | SSE 推送 | — | 自然语言摘要 | + +**总计**: ✅ 已实现 21 项 | ⚠️ 部分实现 8 项 | ❌ 未实现 22 项