# AI Native DevOps Platform 架构设计 v3.0

**版本**: v3.0（PRD 3.0 对齐版）
**基于**: PRD-v3.0 + architecture-v2.6 + v2.7~v3.0 增量设计 + 实际源码回溯
**作者**: 庞统（副军师）
**日期**: 2026-05-28
**状态**: v3.0 正式版（T1 清理完成）

---

## §1. 版本信息和变更历史

### 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. 架构总览

### 2.1 核心变革：从 DAG 状态机到 Shared Workspace

v2.0 的核心是 **DAG 引擎 + 状态机 + 邮件通信**，本质是给 AI 团队做 ERP。v2.6+ 变革为 **Shared Workspace (Blackboard) + Agent 自主决策 + Daemon 投递**。

```
┌─────────────────────────────────────────────────────────────┐
│                      用户 / 触发器                            │
│               (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 <id> --session-id <uuid>
┌──────────────────────────▼──────────────────────────────────┐
│                   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 目标 | 实际状态 |
|------|---------|---------|
| 苏格拉底式对话 | 需求探索的核心入口 | ✅ 已有 skill — `requirement-clarification`（加权模糊度评分 + 节奏守卫 + 停止守卫） |
| 多轮需求澄清 | 庞统通过对话帮用户梳理需求 | ✅ 已有 skill — `requirements-analysis`（需求规格化 + 假设标注 + 交付物定义） |
| 需求探索自动触发 | PRD Phase 1 自动启动 | ❌ 未实现 — Skill 存在但无 Daemon 自动触发机制 |

**现状**: Skill 层面完备（`requirement-clarification` + `requirements-analysis` 覆盖需求澄清全流程），但编排层面缺少自动触发。当前依赖 Agent 手动加载 Skill 或用户显式触发。

**差距**: 需要一个"需求探索"入口，当用户提一个模糊方向时，自动触发苏格拉底式对话。可在庞统主 session 通过 Skill 匹配实现，或在 Dashboard 新建任务时自动引导。

### 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 庞统
```

---

## §5. 数据模型

### 5.1 数据库架构 ✅

**per-project SQLite**：每个项目独立 `blackboard.db`，全局 `registry.db` 管理项目注册表。

#### 5.1.1 tasks 表 ✅

```sql
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'`（向后兼容）

#### 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'))
);
```

- ✅ 8 种 comment_type 全部实现
- ✅ @mention 支持 (JSON 数组)

#### 5.1.3 outputs 表 ✅

```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
);
```

- ✅ 核心字段全部实现
- ✅ content_path 模式 (文件路径引用)
- ✅ content 直传模式 (后端自动写文件)
- ✅ M3 扩展字段 (file_name/file_size/file_path/mime_type)

#### 5.1.4 其他表 ✅

| 表名 | 状态 | 说明 |
|------|------|------|
| 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) |

### 5.2 状态机 ✅

**v3.1 完整状态转换矩阵** (11 个状态):

```python
VALID_TRANSITIONS = {
    "pending":       {"claimed", "paused", "blocked", "cancelled"},
    "claimed":       {"working", "paused", "pending", "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", "paused", "cancelled"},
    "waiting_human": {"working", "done", "paused", "cancelled"},
    "done":          {"cancelled"},
    "cancelled":     {"pending"},
}
```

**与 v2.8 设计的差异** 🔀:

| 状态 | 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 扩展 |

---

## §6. Daemon 设计

### 6.1 Ticker 主循环 ✅

**文件**: `src/daemon/ticker.py` (~960 行)

```
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 (如果存在)
```

**配置**:
- `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) | ticker.py `_broadcast_claim()` 已完整实现 | ✅ |
| Session 存档清理 | spawner 有 `_sessions` 注册表但清理逻辑未完整集成 | ⚠️ |
| L2 Subagent spawn | `spawner.spawn_subagent()` 存在但标注 TODO: F17 | ⚠️ 骨架已有 |
| `_parse_stdout_json` P0 修复 | 代码已修正为 `data["response"]["meta"]` 路径 | ✅ 已修复 |

---

## §7. Agent 交互设计

### 7.1 Agent-Backend API 契约 ✅

**文件**: `src/api/blackboard_routes.py` (~478 行)

| 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 | ✅ | 产出物下载 |

**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 自动生成** ⚠️ TODO: `blackboard_routes._generate_title()` 直接用 OpenAI client 调 zhipu API 生成标题（不走 Gateway），绕过了 Gateway 统一路由 + 计费。保留此函数，待未来替换为本地 LLM 调用。当前前端已支持传 title，LLM 生成只是 fallback。

### 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 未集成校验

---

## §8. 路由与调度

### 8.1 AgentRouter 确定性路由 ✅

**文件**: `src/daemon/router.py` (~180 行)

**v3.0 核心变更**: 去掉独立 LLM (LLMDriver)，模糊场景 delegate 庞统。

**路由模式**:
```
route(task_info, action_type):
    ├─ LOCAL_ACTIONS → daemon 本地执行
    ├─ retry → 原执行者
    ├─ next_capability → 能力匹配 (排除当前 Agent)
    ├─ 生命周期流转 (review → review capability)
    ├─ 有 assignee → 直接分
    └─ 模糊场景 → delegate 庞统 (L3 spawn, 走 Gateway)
```

**Agent 能力画像** ✅:

| 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** |

**RouteDecision** ✅:
- `mode`: "deterministic" | "agent_handoff" | "delegate" | "fallback"
- `confidence`: 0.0~1.0
- `latency_ms`: 路由耗时

### 8.2 并发控制 ✅

**文件**: `src/daemon/counter.py` (~170 行)

**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 §3.3)**:
- 确定性路径：已知下一步谁做 → 直接 spawn
- 广播认领路径：不确定 → spawn 所有空闲 Agent → 自主 claim
- 无人认领 → retry 3 次后升级庞统兜底

**实际代码 (ticker.py L540 `_broadcast_claim()`)**:
- ✅ 完整实现，包含：全局并发检查（counter.is_near_limit）、空闲 Agent 列表（_get_idle_agents）、批量广播（攒一批任务一次广播）、spawn 广播、无人认领检测（retry_count >= 3 → escalated）、审计事件记录（events 表 broadcast_claim 类型）
- ✅ 确定性路径也完整（Router → Dispatcher → Spawner）

**注**: 庞统初版误判为"未实现"，因检查 router.py/spawner.py 时未查 ticker.py。司马懿评审纠正。

---

## §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) — reviews 表支持 plan_review 类型 (db.py REVIEW_TYPES)，但 Daemon 流程未自动触发方案审查
- ✅ 反驳权 — RebuttalManager (review.py) + 8 种 comment_type 含 rebuttal/debate 系列 + 前端 UI 支持
- ❌ 审查协议注册表 (review_protocols/) 未实现 — bootstrap.py 有 `_load_review_protocols` 但 review_protocols/ 目录不存在
- ❌ 对抗辩论模式未实现 — 无自动 spawn 正反方辩论

### 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 上下文预算 ✅

| 组件 | 预算 | 实际 |
|------|------|------|
| 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 文件未完整创建。

---

## §11. 前端

### 11.1 现有前端 ✅

**目录**: `frontend/` (Vite + React + TypeScript)

| 组件 | 状态 | 说明 |
|------|------|------|
| EdictBoard.tsx | ✅ | 任务看板 (卡片布局) |
| TaskModal.tsx | ✅ | 任务详情弹窗 |
| MailTab.tsx | ✅ | 邮件 Tab |
| SSE 集成 | ✅ | EventSource 实时推送 |
| 通知中心 | ✅ | SSE 事件通知 |
| CheckpointPanel.tsx | ✅ | Checkpoint 交互面板，集成到 TaskModal (waiting_human 状态) |
| ArtifactPanel.tsx | ✅ | 成果物预览/下载面板，集成到 TaskModal outputs tab |

### 11.2 v2.8 设计 vs 实现 ⚠️

| 设计 (v2.8-state-enhancement) | 实际前端 | 状态 |
|------|---------|------|
| 两行筛选栏 | 项目下拉 + 状态/搜索筛选 | ✅ 已实现 |
| 卡片快捷按钮 (⏸▶🚫) | TaskActionButtons 组件 | ✅ 已实现（含 resumed_from 恢复逻辑） |
| 新状态颜色 | STATUS_STYLES 映射表 | ✅ 已实现（11 个状态各有颜色标签） |
| 归档筛选 | 活跃/归档/全部三档 | ✅ 已实现 |
| Checkpoint 面板 | CheckpointPanel 集成 | ✅ 已实现 |
| Artifact 成果物 | ArtifactPanel 集成 | ✅ 已实现 |

### 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 指的是 **sanguo_mail**（旧邮件系统），已被 v2.0 黑板完全替代。

**当前 Mail Tab**: 是 moziplus v2 内置的飞鸽传书功能（`_mail` 虚拟项目），是全新的实现，与 sanguo_mail 无关。两者不是同一个系统。

---

## §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)，超限暂停 + 告警。

**实际**: ⚠️ 部分实现。Ticker 有 `max_ticks` 参数（当前用于测试，限制 Ticker 自身运行次数），但不是 per-task 的 Runaway Guard。tasks 表无 `tick_count` / `max_ticks` 字段。需要扩展为 per-task 粒度。

---

## §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）

> ⚠️ 以下为庞统初判 + 用户复查 + 司马懿评审后的修正版本（v3）。
>
> **已清理的问题**（不在此列表中）：
> - ~~P3 遗留 (404/4xx 响应码)~~: 已修复
> - ~~续杯设计矛盾~~: 已验证代码与设计一致
> - ~~广播认领矛盾~~: 已验证完整实现
> - ~~BUG-22 (list_mail from 内存过滤)~~: T1 修复，改为 SQL WHERE (assigned_by 参数)
> - ~~OBS-25 (send_mail from 冗余存储)~~: T1 修复，from 统一用 assigned_by，must_haves 不再存 from
> - ~~OBS-26 (polling 不刷新 Mail)~~: T1 修复，loadAll 在 mail tab 时调 loadMails()

### 17.1 PRD 明确要求但未实现

| # | 功能 | PRD 来源 | 当前状态 | 优先级 |
|---|------|---------|---------|--------|
| 1 | **需求探索自动触发** | PRD B1/C1 | ⚠️ Skill 已有（requirement-clarification + requirements-analysis），但缺少 Daemon 自动触发机制 | P2 |
| 2 | **动态规划** (活计划, 全程可调) | PRD B2/C2 | ❌ 基础机制存在（任务创建/状态流转），但无活的计划调整 | P1 |
| 3 | **持续指挥** (庞统全程在线) | PRD B2/C3 | ❌ 庞统只在 delegate 时被 spawn，无持续指挥 session | P1 |
| 4 | **主动汇报** (AI 推送自然语言摘要) | PRD B4/C7 | ⚠️ SSE 推送已有，但推送的是原始事件，不是 AI 生成的自然语言摘要 | P2 |
| 5 | **工具链集成** (lint/test/build) | PRD C10 | ❌ 未实现，toolchain-proposal.md 处于信息收集阶段 | P3 |
| 6 | **经验闭环 IMPROVE** | PRD C8 | ⚠️ DISTILL + APPLY 已实现，IMPROVE（使用后反馈/更新）未实现 | P3 |

### 17.2 设计文档有详细方案但未实现（经复查）

| # | 功能 | 设计文档 | 复查结果 | 优先级 |
|---|------|---------|---------|--------|
| 7 | ~~**广播认领** (自主 claim 调度)~~ | v3.0-router-refactor §3.3 | ✅ 已完整实现（ticker.py `_broadcast_claim()`），司马评审确认。移至 §17.3 | ~~P2~~ |
| 8 | **方案审查自动流程** | v2.6.4 §9.3 | ⚠️ reviews 表支持 plan_review 类型，但 Daemon 不会自动触发方案审查流程 | P2 |
| 9 | **审查协议注册表** (review_protocols/) | v2.6.4 §9.4 | ❌ bootstrap.py 有 `_load_review_protocols` 但 review_protocols/ 目录不存在 | P2 |
| 10 | **对抗辩论模式** (high 风险任务) | v2.6.4 §9.10 | ❌ 无自动 spawn 正反方辩论。comment_type 支持 debate 系列但无自动编排 | P3 |
| 11 | **verification_commands** (验证脚本层) | v2.6.9 借鉴1 | ❌ tasks 表无 verification_commands 字段，Guardrail 无脚本执行 | P2 |
| 12 | **Shadow Checkpoint** (git 自动 commit) | v2.6.9 借鉴5 | ❌ 无 git 集成 | P3 |
| 13 | **Skill 生命周期** (draft→active→deprecated) | v2.6.7 | ❌ SkillRegistry 只有注册/匹配，无生命周期管理 | P3 |
| 14 | **prompt_templates 角色模板** (完整文件) | v2.6.5 | ⚠️ BootstrapBuilder 支持 `_load_template()` 加载模板文件，但 prompt_templates/ 目录不存在 | P2 |
| 15 | **CLI Schema 校验** (schemas/ 目录) | v2.6.3 §3.7 | ❌ schemas/ 目录不存在 | P2 |
| 16 | **per-provider 冷却** | v2.7.2 §5 | ❌ Counter 只有 per-agent 冷却，无 per-provider 粒度 | P4 |

### 17.3 已确认实现（从待实现列表移除）

| # | 功能 | 证据 | 移除原因 |
|---|------|------|---------|
| — | **反驳权 (Rebuttal)** | ✅ RebuttalManager (review.py:273) + comment_type 含 rebuttal/debate_* + 前端 UI | 用户复查确认 |
| — | **Checkpoint 机制** | ✅ checkpoint_routes.py (6 端点) + CheckpointPanel.tsx + db.py checkpoints 表 | 用户复查确认 |
| — | **Artifact 成果物面板** | ✅ ArtifactPanel.tsx + ArtifactList.tsx + API 预览/下载端点 | 用户复查确认 |
| — | **广播认领** | ✅ ticker.py `_broadcast_claim()` 完整实现（全局并发检查 + 批量广播 + retry 3 次 + 庞统兜底） | **司马懿评审纠正** |
| — | **L2 Subagent spawn** | ⚠️ 骨架已有：spawner.spawn_subagent() 存在但标注 TODO: F17 | 部分实现 |
| — | **假死复活术** | ⚠️ health.py zombie 检测 + spawner._revive_session() | 部分实现 |
| — | **Runaway Guard** | ⚠️ Ticker 有 max_ticks（测试用），但不是 per-task 粒度 | 部分实现 |

---

## §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 设计 vs v3.1 代码 ✅（已解决，以代码为准）

**决策**: 以代码实际实现为准，v2.8 设计文档已归档至 `archive-2.0/v2.8-state-enhancement.md`。

**代码实际状态机**（§5.2 已完整记录）:
- 11 个状态，VALID_TRANSITIONS 完整定义
- `TERMINAL_STATUSES = frozenset()` — 无终态，全靠转换矩阵校验
- `MANUAL_STATUSES = {cancelled, paused}` — 不参与聚合推导
- paused 恢复通过 `resumed_from` 字段记录暂停前状态
- done → cancelled、cancelled → pending 支持"反悔"操作

**与 v2.8 设计的关键差异**（已归档，不再维护）:
- v2.8 定义了终态（done/cancelled），代码取消终态概念
- v2.8 paused 只能恢复到 working，代码支持恢复到任意 paused 前状态
- v2.8 pending 只能到 claimed/cancelled，代码多了 paused/blocked

这些差异都是工程实践中的合理扩展，代码更灵活实用。

### 19.2 广播认领 vs Delegate 庞统 ✅（已解决，非矛盾）

**v3.0-router-refactor 设计**: 双路径调度
- 确定性路径：已知下一步谁做 → 直接 spawn
- 广播认领路径：不确定 → spawn 所有空闲 Agent → 自主 claim
- 无人认领 → retry 3 次 → 庞统兜底

**实际代码 (已确认实现)**:
- ✅ 确定性路径：Router → Dispatcher → Spawner
- ✅ 广播认领路径：ticker.py `_broadcast_claim()` 完整实现
- ✅ 庞统兜底：retry_count >= 3 → escalated → delegate

**结论**: 设计和代码一致，双路径都完整实现。从矛盾列表移除。

**纠正记录**: 庞统初版只检查了 router.py/spawner.py，遗漏了 ticker.py L540。司马懿评审纠正。

### 19.3 `_generate_title()` 绕过 Gateway ⚠️ TODO（保留，待替换本地 LLM）

**现状**: `blackboard_routes._generate_title()`（line 138-175）直接用 OpenAI client 调 zhipu API，不走 Gateway。

**决策**: 保留此函数，不删除。未来替换为本地 LLM 调用。

**替换方向**: 本地 LLM（如 Ollama）或走 Gateway API。当前前端已支持传 title，LLM 只是 fallback，不影响正常使用。

### 19.4 续杯设计 ✅（已验证一致）

**spawner-monitor-design v2.0**: 续杯只有 A2/A3（Gateway timeout）触发。

**实际 spawner 代码**: `_handle_exit` 中 `cls["should_retry"]` 为 True 时才走 `_do_retry`，注释明确 "只有 A2/A3（gateway_timeout）触发续杯，其他都不 retry"。

**结论**: 代码和设计一致，不存在矛盾。删除此矛盾项。

---

## §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 推送 | — | 自然语言摘要 |

**总计**: ✅ 已实现 25 项 | ⚠️ 部分实现 8 项 | ❌ 未实现 12 项

> 上述数据经 2026-05-28 用户复查 + 司马懿评审修正。广播认领从未实现移至已实现。