auto-sync: 2026-05-28 00:23:03

2026-05-28 00:23:03 +08:00
parent e891f72107
commit 381a9f2647
1 changed files with 802 additions and 0 deletions
@@ -0,0 +1,802 @@
+# AI Native DevOps Platform 架构设计 v3.0
+
+**版本**: v3.0（PRD 3.0 对齐 + 代码现状回溯）
+**基于**: PRD-v3.0 + architecture-v2.6 + 实际代码
+**作者**: 庞统（副军师）🐦
+**日期**: 2026-05-28
+**状态**: 初稿
+**准绳**: PRD-v3.0.md 是唯一准绳，设计矛盾以它为准
+
+---
+
+## 变更历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| v3.0 | 2026-05-28 | 基于 PRD-v3.0 + 代码现状，全面回溯。从 architecture-v2.6 继承并修正 |
+
+---
+
+## 实现状态标记
+
+- ✅ **已实现** — 代码已落地
+- ⚠️ **部分实现** — 有代码但缺功能
+- ❌ **未实现** — 只有设计没有代码
+- 🔀 **矛盾** — 设计和代码/PRD不一致
+
+---
+
+## 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 系统架构图
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        用户层                                        │
+│  ┌──────────┐  ┌──────────────┐  ┌──────────────┐                  │
+│  │ 前端(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 <id>                │
+│  ┌──────────────────────────────────────────────────┐               │
+│  │              Agent 层 (OpenClaw Gateway)          │               │
+│  │  张飞/关羽/赵云/姜维/司马懿/庞统                   │               │
+│  │  每个 Agent 独立 session，通过 API 读写黑板        │               │
+│  └──────────────────────────────────────────────────┘               │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 数据模型
+
+### 2.1 实际 DB Schema（代码现状）
+
+✅ **已实现** — 14 张表
+
+| 表名 | 代码位置 | 用途 |
+|------|----------|------|
+| `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 表字段（实际）**：
+
+```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 无）
+```
+
+**状态枚举（实际）**：
+
+```
+pending, claimed, working, review, paused, escalated,
+waiting_human, done, failed, blocked, cancelled
+```
+
+### 2.2 设计差异
+
+| # | 差异 | 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 已实现 | ✅ |
+
+### 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 <id> --session-id <uuid>`）
+- 进程监控（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 被动执行
+```
+
+**设计目标流程**（v3.0-router-refactor.md）：
+```
+pending → 确定性路径?(retry/handoff/assignee) → 直接 spawn
+       → 否 → 广播认领 → Agent 自主 claim
+```
+
+### 5.2 调度模式
+
+| 模式 | 设计 | 代码 | 标记 |
+|------|------|------|------|
+| 确定性交接（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 | ✅ |
+
+### 8.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`）：
+
+```python
+VALID_TRANSITIONS = {
+    "pending":       {"claimed", "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"},
+    "blocked":       {"pending", "escalated", "cancelled"},
+    "failed":        {"pending", "escalated", "cancelled"},
+    "escalated":     {"working", "pending", "cancelled"},
+    "waiting_human": {"working", "done", "cancelled"},
+    "done":          set(),  # 终态
+    "cancelled":     set(),  # 终态
+}
+```
+
+### 14.3 差异
+
+| 设计（v3.0-router-refactor §5.6） | 代码实际 | 标记 |
+|-----------------------------------|---------|------|
+| cancelled 可重启动(→pending) | cancelled 是终态，无出口 | 🔀 |
+| review 可暂停 | review 转换无 paused | ⚠️ |
+| paused 恢复到暂停前状态 | `resumed_from` 字段存在 | ⚠️ |
+
+---
+
+## 15. 待实现项汇总（原则 2/3）
+
+### 15.1 原则 2：PRD ✅ + 代码 ❌ + 设计 ❌
+
+| # | PRD 条目 | 说明 |
+|---|---------|------|
+| P2-1 | PRD §10.1 六条红线之"Agent 不受控行为" | guardrails.yaml 有定义但代码 TODO |
+| P2-2 | PRD B4 持续学习闭环 | 经验沉淀闭环四阶段只实现存储 |
+
+### 15.2 原则 3：设计 ✅ + PRD ✅ + 代码 ❌
+
+| # | 设计文档 | 功能 | 来源 |
+|---|---------|------|------|
+| 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 |
+
+---
+
+## 16. PRD 新增建议（原则 4/5）
+
+### 16.1 原则 4：调研有但 PRD 没有
+
+| # | 调研来源 | 功能 | 建议 |
+|---|---------|------|------|
+| 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 补充并发控制模型 |
+
+### 16.2 原则 5：代码有但 PRD/设计没有
+
+| # | 代码位置 | 功能 | 判断 |
+|---|---------|------|------|
+| 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 |
+
+---
+
+## 17. 设计矛盾记录（原则 6）
+
+### 6.1 广播认领 vs 强制分配
+
+- **PRD B1**："AI 参与每个决策层" → Agent 自主认领
+- **v3.0-router-refactor**：明确指出 `_dispatch_pending` 违背"Agent 决策"原则
+- **代码实际**：仍走 Router 决定 → 强制 claimed
+- **结论**：以 PRD 为准，v3.0 需实施广播认领
+
+### 6.2 escalated 字段 vs 状态
+
+- **v2.8-state-enhancement**：`escalated` 应为独立状态，废弃布尔字段
+- **代码实际**：tasks 表有 `escalated INTEGER DEFAULT 0`（布尔）+ `status='escalated'`（状态）共存
+- **结论**：以 v2.8 设计为准，布尔字段做向后兼容
+
+### 6.3 Bootstrap 4096 vs 设计预算 35K~60K
+
+- **设计**（§11.3）：上下文预算 35K~60K tokens
+- **代码实际**：`max_tokens=4096`
+- **结论**：4096 偏小，需调大。但实际 BootstrapBuilder 未被主路径调用，差距暂无影响
+
+### 6.4 cancelled 终态 vs 可重启
+
+- **v3.0-router-refactor §5.6**：cancelled 可重启动（→pending）
+- **代码实际**：cancelled 是终态（`set()`）
+- **结论**：需确认 PRD 立场。当前代码 cancelled 不可逆
+
+### 6.5 Mail 完全退役 vs Mail Tab 存在
+
+- **architecture-v2.6 §8**："Sanguo Mail: 退役"
+- **代码实际**：Mail Tab 完整实现（mail_routes.py + MailPanel.tsx）
+- **结论**：Mail 在 v2.7 后重新引入为"飞鸽传书"功能，与 v2.6 的"退役"不矛盾（v2.6 指的是旧版 Sanguo Mail 服务，新版是黑板内的 Mail Tab）
+
+---
+
+## 18. 技术选型
+
+| 需求 | 方案 | 来源 |
+|------|------|------|
+| 共享状态 | 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 |
+
+---
+
+## 19. 代码规模统计
+
+| 模块 | 文件数 | 总行数（约） |
+|------|--------|------------|
+| daemon/ | 14 | ~2500 |
+| blackboard/ | 5 | ~1400 |
+| api/ | 6 | ~800 |
+| cli/ | 2 | ~500 |
+| frontend/src/ | ~28 | ~5000 |
+| config/ | 2 | ~120 |
+| **总计** | ~57 | **~10320** |
+
+---
+
+## 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 |