# AI原生DevOps Platform 架构设计 v2.6

**版本**: v2.6(Shared Workspace + Blackboard 架构)
**基于**: architecture-v2.md + v2.0 AI Native 调研 + 技术验证
**作者**: 庞统(副军师)
**日期**: 2026-05-15

---

## 变更历史

| 版本 | 日期 | 变更内容 |
|------|------|---------|
| 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 | 课题1设计决策：三层执行模型、续杯机制、AI驱动retry、Guardrail体系、must_haves三件套、分级审查矩阵 |
| v2.6.2.1 | 2026-05-15 | 司马懿评审反馈：L2/L3区分标准、timeout修正、outputs关联attempt、Scope Guard异步、risk_level自动 |

---

## 1. v2.6 核心变革:从 DAG 状态机到 Shared Workspace

### 1.1 为什么变?

v2.0 的核心是 **DAG 引擎 + 状态机 + 邮件通信**,本质是给 AI 团队做了一套 ERP:
- 编排是确定性状态机(固定流程)
- 交互是点按钮(Dashboard)
- Agent 间靠邮件异步通信(信息分散在 mail 目录)
- 人的参与密度不变(全程驾驶)

v2.6 的核心是 **Shared Workspace(Blackboard)+ Agent 自主决策 + Daemon 投递**:
- 编排是 AI agent 在黑板上自主领活(动态协作)
- 交互是自然语言对话
- Agent 间通过黑板共享一切(信息集中在任务空间)
- 人只做方向决策和验收

### 1.2 核心原则

> **黑板是唯一真相源,所有 agent 读它、想、行动,写回结果。Daemon 是投递员,不是决策者。**

1. **Agent 决策,Daemon 执行** - 庞统做 plan、张飞领任务、关羽发现风险,都写在黑板上。Daemon 读黑板,执行 spawn/通知。
2. **产出在黑板,不在邮件** - 所有任务产出、讨论、观察都在任务的黑板空间里,Sanguo Mail 不介入任务协作。
3. **Daemon 不阻塞 Agent** - Daemon 是常驻管家,定期 tick 检查黑板,spawn agent 执行,不占用任何 agent 的主 session。
4. **Session 用完即清** - Agent 通过 `openclaw agent --agent <id> --session-id <uuid>` spawn 隔离 session,执行完 daemon 存档 jsonl 并清理 sessions.json。

---

## 2. 架构总览

```
┌─────────────────────────────────────────────────────────────┐
│                      用户 / 触发器                            │
│                   (Web / CLI / Cron)                         │
└──────────────────────────┬──────────────────────────────────┘
                           │ 写入黑板或触发 daemon
┌──────────────────────────▼──────────────────────────────────┐
│                    Shared Workspace(黑板)                    │
│                                                               │
│  ┌────────────────────────────────────────────────────────┐  │
│  │              SQLite (blackboard.db)                     │  │
│  │  tasks / comments / outputs / agents / events          │  │
│  │  原子读写(propose→validate→commit 或 SQLite 事务)     │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ 任务列表  │ │ 评论线程  │ │ 产出空间  │ │ 讨论区域  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└──────────────────────────┬──────────────────────────────────┘
                           │ daemon tick 读写
┌──────────────────────────▼──────────────────────────────────┐
│                    Daemon(管家)                              │
│                                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ Tick 循环    │  │ Session 管理  │  │ 健康检查          │  │
│  │ (60s 轮询)   │  │ spawn/archive │  │ zombie/reclaim   │  │
│  │ 读黑板→决策  │  │ /cleanup      │  │ /stale 任务      │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────────────┘  │
│         │                 │                                   │
│  Daemon 只做三件事:       │                                   │
│  1. 读黑板,发现需要介入的  │                                   │
│  2. Spawn 对应 agent       │                                   │
│  3. 清理完成的 session     │                                   │
└──────────────────────────┬──────────────────────────────────┘
                           │ openclaw agent --agent <id> --session-id <uuid>
                           │ 执行完 → 存档 jsonl → 清理 sessions.json
┌──────────────────────────▼──────────────────────────────────┐
│                   Agent 层(将军们)                          │
│                                                               │
│  Agent 不常驻。被 spawn 时:                                   │
│  1. 读黑板 → 了解全局状态                                     │
│  2. 想和做 → 根据职责自主决策                                  │
│  3. 写回黑板 → 产出、评论、领任务                              │
│  4. 退出 → session 被 daemon 清理                             │
│                                                               │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐    │
│  │庞统  │ │司马懿│ │姜维  │ │关羽  │ │张飞  │ │赵云  │    │
│  │策划  │ │质量  │ │平台  │ │风控  │ │编码  │ │数据  │    │
│  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘    │
│                                                               │
│  每个 Agent: SOUL.md + IDENTITY.md + Skills + Workspace      │
│  Agent 主 session 不参与任务执行(不被污染)                     │
└─────────────────────────────────────────────────────────────┘
```

### 关键区别:v2.0 vs v2.6

| 维度 | v2.0 | v2.6 |
|------|------|------|
| 编排核心 | DAG 引擎 + 状态机 | Blackboard(Shared Workspace) |
| 决策者 | Daemon(状态机驱动) | Agent(在黑板上自主决策) |
| Daemon 角色 | 调度器(决定谁干什么) | 投递员(执行黑板上的决策) |
| Agent 通信 | Sanguo Mail(异步邮件) | 黑板 Comment 线程(共享空间) |
| 信息位置 | 分散(mail + task目录 + session) | 集中(黑板 SQLite) |
| Agent 生命周期 | 固定节点执行 | Spawn 隔离 session,用完即清 |
| 通知机制 | Mail 轮询 | Daemon tick + spawn |
| 协作模式 | 指令式(庞统分配→将军执行) | 自主式(看黑板→领活→写回) |

---

## 3. Shared Workspace(黑板)设计

### 3.1 参考系统对比

| 系统 | 存储 | 原子性 | 讨论 | 状态机 | 发现 |
|------|------|--------|------|--------|------|
| Claude Code Agent Teams | JSON 文件 | 无(last-write-wins) | inbox 点对点 | pending/in_progress/completed | Agent 轮询 |
| Hermes Kanban v0.13 | SQLite | SQLite 事务 | Comment 线程 | 7 状态完整机 | Dispatcher 60s tick |
| Network-AI | Markdown 文件 | flock 三阶段提交 | signal key | 无 | Agent 主动读 |
| agent-blackboard | SQLite + Ontology | SQLite 事务 | 本体条目 | 无 | Coordinator 分发 |
| **我们的方案** | **SQLite** | **SQLite 事务** | **Comment 线程** | **简化状态机** | **Daemon tick** |

### 3.2 SQLite Schema

```sql
-- ===== 任务表 =====
CREATE TABLE IF NOT EXISTS tasks (
    id TEXT PRIMARY KEY,                    -- task-001
    title TEXT NOT NULL,
    description TEXT,
    status TEXT NOT NULL DEFAULT 'pending',
    CHECK (status IN ('pending','claimed','working','review','done','failed','blocked','cancelled')),

    -- 分配(谁领了或被指派)
    assignee TEXT,                          -- agent id: zhangfei-dev
    assigned_by TEXT,                       -- 谁分配的:pangtong-fujunshi / user

    -- 依赖
    depends_on TEXT,                        -- JSON array of task IDs
    parent_task TEXT,                       -- 父任务(子任务分解时)

    -- 优先级和类型
    priority INTEGER NOT NULL DEFAULT 5,   -- 1(最高)-10(最低)
    task_type TEXT,                         -- coding/review/data/deploy/research/discuss

    -- 时间
    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 与风险等级（课题1设计决策）
    must_haves TEXT,                          -- JSON: {truths: [], artifacts: [], constraints: []}
    risk_level TEXT DEFAULT 'standard',       -- high/standard/low/research
    estimated_duration_minutes INTEGER        -- 预估工时（续杯硬上限 = 3x 此值）
);

CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
CREATE INDEX IF NOT EXISTS idx_tasks_assignee ON tasks(assignee);
CREATE INDEX IF NOT EXISTS idx_tasks_parent ON tasks(parent_task);

-- ===== 评论线程表 =====
-- 参考 Hermes kanban_comment:追加写入,所有参与者可见
CREATE TABLE IF NOT EXISTS comments (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id TEXT NOT NULL,
    author TEXT NOT NULL,                   -- agent id 或 'user'
    body TEXT NOT NULL,
    mentions TEXT,                          -- JSON array: ["zhangfei-dev", "guanyu-dev"]
    created_at TEXT NOT NULL DEFAULT (datetime('now')),

    FOREIGN KEY (task_id) REFERENCES tasks(id)
);

CREATE INDEX IF NOT EXISTS idx_comments_task ON comments(task_id);
CREATE INDEX IF NOT EXISTS idx_comments_author ON comments(author);
-- 注意:mentions 是 JSON 数组,无法直接建索引。daemon tick 查询用 json_each(mentions)。
-- 数据量小时够用,后续可拆 comment_mentions 关联表优化。

-- ===== 产出表 =====
CREATE TABLE IF NOT EXISTS outputs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id TEXT NOT NULL,
    agent TEXT NOT NULL,                    -- 谁写的
    output_type TEXT NOT NULL,              -- code/document/data/config/other
    title TEXT NOT NULL,
    content_path TEXT,                      -- 文件路径(产出物在 task 目录下)
    summary TEXT,                           -- 一句话摘要
    metadata TEXT,                          -- JSON: {files_changed, lines_added, ...}
    attempt_number INTEGER DEFAULT 1,       -- 关联 task_attempts.attempt_number
    created_at TEXT NOT NULL DEFAULT (datetime('now')),

    FOREIGN KEY (task_id) REFERENCES tasks(id)
);

CREATE INDEX IF NOT EXISTS idx_outputs_task ON outputs(task_id);

-- ===== 决策记录表 =====
-- Agent 执行过程中的关键决策必须记录。哪怕是自己做的决策也要填一条。
CREATE TABLE IF NOT EXISTS decisions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id TEXT NOT NULL,
    decider TEXT NOT NULL,                  -- 谁做的决策
    decision TEXT NOT NULL,                 -- 决策内容:"选 A 方案"
    rationale TEXT NOT NULL,                -- 为什么:"B 方案内存开销更大"
    alternatives TEXT,                      -- JSON array: 被排除的选项
    created_at TEXT NOT NULL DEFAULT (datetime('now')),

    FOREIGN KEY (task_id) REFERENCES tasks(id)
);

CREATE INDEX IF NOT EXISTS idx_decisions_task ON decisions(task_id);

-- ===== 观察表 =====
-- Agent 执行过程中发现的问题、风险、建议
CREATE TABLE IF NOT EXISTS observations (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id TEXT NOT NULL,
    observer TEXT NOT NULL,                 -- 谁观察到的
    severity TEXT NOT NULL DEFAULT 'info',
    CHECK (severity IN ('blocking','warning','info','audit')),
    body TEXT NOT NULL,
    resolved_by TEXT,                       -- 谁处理的
    resolved_at TEXT,                       -- 何时处理的
    created_at TEXT NOT NULL DEFAULT (datetime('now')),

    FOREIGN KEY (task_id) REFERENCES tasks(id)
);

-- ===== 事件日志(审计追踪)=====
CREATE TABLE IF NOT EXISTS events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id TEXT,
    agent TEXT,
    event_type TEXT NOT NULL,
    detail TEXT,                            -- JSON
    created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE INDEX IF NOT EXISTS idx_events_task ON events(task_id);
CREATE INDEX IF NOT EXISTS idx_events_time ON events(created_at);

-- 合法 event_type 清单:
-- 任务:task_created, task_claimed, task_started, task_completed, task_failed,
--       task_blocked, task_unblocked, task_reviewed, task_cancelled, task_retried
-- 协作:comment_added, output_written, observation_added, decision_recorded
-- Agent:agent_spawned, agent_completed, agent_zombie_detected
-- Session:session_spawned, session_archived, session_cleanup
-- 系统:daemon_tick, daemon_manual_tick

-- ===== Agent 注册表 =====
CREATE TABLE IF NOT EXISTS agents (
    agent_id TEXT PRIMARY KEY,
    role TEXT,
    current_status TEXT DEFAULT 'idle',     -- idle/working/offline
    current_task TEXT,
    last_active TEXT,
    capabilities TEXT                       -- JSON array: ["coding", "review", "deploy"]
);

-- ===== 任务尝试记录（参考 Hermes task_runs）=====
CREATE TABLE IF NOT EXISTS task_attempts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id TEXT NOT NULL,
    attempt_number INTEGER NOT NULL,
    agent TEXT NOT NULL,
    outcome TEXT NOT NULL,  -- completed/blocked/crashed/timed_out/spawn_failed/reclaimed
    exit_code INTEGER,
    log_path TEXT,
    summary TEXT,
    metadata TEXT,  -- JSON: {duration_seconds, token_count, ...}
    started_at TEXT NOT NULL DEFAULT (datetime('now')),
    completed_at TEXT,
    
    FOREIGN KEY (task_id) REFERENCES tasks(id)
);

CREATE INDEX IF NOT EXISTS idx_attempts_task ON task_attempts(task_id);

-- agents 表更新规则：
-- Agent claim 任务时：自己更新 current_status='working', current_task=task_id
-- Agent 完成退出时：daemon 更新 current_status='idle', current_task=NULL
-- Daemon tick 检测到 zombie：daemon 更新 current_status='offline'
```

**连接配置:**

```python
def get_connection():
    conn = sqlite3.connect(str(DB_PATH))
    conn.row_factory = sqlite3.Row
    conn.execute("PRAGMA journal_mode=WAL")
    conn.execute("PRAGMA foreign_keys=ON")
    conn.execute("PRAGMA busy_timeout=5000")
    return conn
```

### 3.3 简化状态机

```
pending → claimed → working → review → done
  ↑         │          ├→ blocked ──┘  ├→ failed
  │         │          └→ failed       └→ cancelled
  └─────────┘
  (review→pending: 审核不通过,打回重做)
  (blocked→pending: 阻塞解除)
  (failed→pending: 重试)
```

**与 v2.0 的区别:** v2.0 有 9 个状态(spawning, ready, reporting 等),v2.6 简化为 8 个。原因是 spawn 逻辑从状态机移到了 daemon--daemon tick 发现黑板需要某人介入就 spawn,不需要 spawning/ready 这些中间状态。

| 状态 | 含义 | 谁触发 |
|------|------|--------|
| pending | 待领取 | 任何 Agent 或用户创建 |
| claimed | 已认领 | Agent 自己或被指派 |
| working | 执行中 | Agent |
| review | 待审核 | Agent 完成产出 |
| blocked | 需要帮助 | Agent |
| done | 完成 | **审核通过且所有问题达成一致** |
| failed | 失败 | Agent 或 daemon |
| cancelled | 取消 | 用户 |

**完整合法流转矩阵:**

```python
VALID_TRANSITIONS = {
    "pending":   {"claimed", "cancelled"},
    "claimed":   {"working", "pending", "cancelled"},      # pending: 放弃认领
    "working":   {"review", "blocked", "failed", "cancelled"},
    "review":    {"done", "pending", "failed", "cancelled"},  # pending: 审核不通过打回
    "blocked":   {"pending", "cancelled"},                   # pending: 阻塞解除
    "done":      set(),                                       # 终态
    "failed":    {"pending"},                                 # pending: 重试
    "cancelled":  set(),                                       # 终态
}
```

### 3.4 原子操作

**任务认领(claim)** - 原子 CAS,防止两个人同时领:

```python
def claim_task(task_id: str, agent_id: str) -> bool:
    conn = get_connection()
    try:
        cursor = conn.execute(
            "UPDATE tasks SET status='claimed', assignee=?, claimed_at=datetime('now') "
            "WHERE id=? AND status='pending' AND (assignee IS NULL OR assignee=?)",
            (agent_id, task_id, agent_id)
        )
        conn.commit()
        return cursor.rowcount > 0  # 0 表示被别人抢了或不是指定分配给自己的人
    finally:
        conn.close()
```

**产出写入** - SQLite 事务保证原子:

```python
def write_output(task_id: str, agent_id: str, output: dict):
    conn = get_connection()
    try:
        conn.execute("BEGIN IMMEDIATE")  # 立即获取写锁
        conn.execute(
            "INSERT INTO outputs (task_id, agent, output_type, title, content_path, summary, metadata) "
            "VALUES (?, ?, ?, ?, ?, ?, ?)",
            (task_id, agent_id, output['type'], output['title'],
             output['path'], output['summary'], json.dumps(output.get('metadata', {})))
        )
        conn.execute(
            "INSERT INTO events (task_id, agent, event_type, detail) VALUES (?, ?, 'output_written', ?)",
            (task_id, agent_id, json.dumps({'output_id': output['title']}))
        )
        conn.commit()
    finally:
        conn.close()
```

### 3.5 评论线程(讨论机制)

参考 Hermes 的 `kanban_comment` 模式:

```python
def add_comment(task_id: str, author: str, body: str, mentions: list = None):
    conn = get_connection()
    try:
        conn.execute(
            "INSERT INTO comments (task_id, author, body, mentions) VALUES (?, ?, ?, ?)",
            (task_id, author, body, json.dumps(mentions or []))
        )
        conn.execute(
            "INSERT INTO events (task_id, agent, event_type, detail) VALUES (?, ?, 'commented', ?)",
            (task_id, author, json.dumps({'body_preview': body[:100], 'mentions': mentions}))
        )
        conn.commit()
    finally:
        conn.close()
```

**讨论示例:**

```
[16:30 庞统] 张飞,你的实现方案我看了,回测数据量大时内存会爆。
              关羽,从风控角度也看看? @关羽 @张飞
[16:35 关羽] 同意。建议加分批加载机制,单批不超过 50 万条。
[16:40 张飞] 收到,改成分批加载。预计 30 分钟。
[16:55 庞统] @张飞 注意止损逻辑也需要同步改,分批后止损触发时机变了。
[17:10 张飞] 完成。产出在 output-zhangfei-v2.md。
```

**核心原则:评论都在黑板上,不在任何 agent 的 session 里。Agent 的 session 是临时的。**

### 3.6 竞态解决

任务认领的竞态通过 SQLite 原子 CAS 解决(先到先得)。

职责冲突的解决(张飞和关羽都认为自己该做某个任务):
1. **默认:先到先得** - SQLite CAS,谁先 claim 谁做
2. **升级:庞统仲裁** - 如果争议,评论中 @庞统 请求仲裁
3. **最终:用户拍板** - @user 请求用户决定

不需要复杂的分布式共识--职责分工已经自然避免了大部分冲突。

---

## 4. Daemon(管家)设计

### 4.1 Daemon 的角色定位

> **Daemon 是投递员,不是决策者。所有决策发生在黑板上,daemon 只执行。**

Daemon 做三件事：
1. **读黑板** — 定期 tick，检查黑板状态
2. **Spawn Agent** — 根据黑板上的指示，spawn 对应的 agent
3. **清理 Session** — agent 执行完后，存档 jsonl + 清理 sessions.json

Daemon **不做**：
- ❌ 不决定谁做什么（agent 自己决定或庞统在黑板上分配）
- ❌ 不维护状态机（黑板就是状态）
- ❌ 不做业务逻辑（不解析产出、不做评审）

**三层执行模型**：Daemon 的操作按成本和复杂度分为三层：

| 层级 | 方式 | 成本 | 适用场景 | 例子 |
|------|------|------|---------|------|
| **L1 Daemon 直接操作** | SQLite 读写、文件操作 | 几乎为零 | 纯机械动作 | 更新状态、记录事件、机械验证（文件存在、JSON格式、字段非空） |
| **L2 spawn sub** | `openclaw agent --agent <id> --session-id <uuid>` | 轻量（隔离 session，单任务） | 轻量 AI 判断 | scope guard、格式校验、快速评估、假死 reminder |
| **L3 run agent** | spawn 完整 Agent 到黑板上工作 | 完整（读黑板+思考+写回） | 重度 AI 工作 | 庞统拆解、张飞编码、司马懿 review、庞统纠错 |

关键区别：
- L2 的 sub 是一次性、单任务的（"帮我检查这个输出是否在 scope 内"），执行完就退出
- L3 的 agent 是完整的黑板参与者（读全局、自主决策、写回多个表）

**L2 与 L3 的区分标准**：是否读黑板全局。
- L2：不读黑板全局上下文，只拿当前任务的特定字段做判断。spawn 时传递局部数据（如 scope_declaration 文本 + task.truths），sub 返回结果后退出。
- L3：读黑板全局（tasks + comments + outputs + decisions + observations），做全局决策。spawn 时只传任务 ID + 触发原因，Agent 自己读黑板。

这个区分决定了 spawn 时的消息内容——L2 传数据，L3 传指针。

### 4.2 Daemon Tick 循环

参考 Hermes Dispatcher,但更轻量:

**Tick 频率:60 秒(默认),可通过 CLI 手动触发立即执行。**

```bash
# 手动触发一次 tick（用于需要立即响应的场景）
python3 ~/.sanguo_projects/sanguo_moziplus/cli/daemon.py tick
```

**§4.2.1 Tick 循环中的 L1/L2/L3 标注说明：**
- L1（几乎零成本）：健康检查、状态回收、session 清理、SQLite 查询、文件存档
- L2（轻量）：spawn 单任务 sub，如 @mention 通知、待领取任务通知、scope guard
- L3（完整）：spawn 完整 Agent，如庞统仲裁 blocked 任务、AI 纠错协商、审核

```python
async def daemon_tick():
    """每 60 秒执行一次"""

    # 1. 健康检查（L1: Daemon 直接操作）
    #    详见 §4.5 续杯与心跳
    check_agent_heartbeats()    # L1: 检查 observations 有无新进展
    reclaim_stale_tasks()        # L1: 超时的 working 任务回收（硬上限 = 3x 预估工时）
    detect_zombie_sessions()     # L1: 进程死了但 session 还在的

    # 2. 读黑板（L1: SQLite 查询）
    board = read_blackboard()    # SQLite 查询

    # 3. 处理评论中的 @mention（L2/L3: spawn agent）
    #    Agent A 在评论中 @AgentB → daemon spawn AgentB 来看评论
    for comment in board.get_unprocessed_mentions():
        target_agent = comment.mentioned_agent
        if not is_agent_active(target_agent):
            async_spawn_agent(target_agent,
                        message=f"黑板上有给你的新评论(task-{comment.task_id}),请查看。")
            mark_comment_processed(comment.id)

    # 4. 处理待领取的任务（L2: spawn agent）庞统在黑板上分配了但 agent 还没领）
    for task in board.get_assigned_unclaimed():
        if not is_agent_active(task.assignee):
            async_spawn_agent(task.assignee,
                        message=f"黑板上有分配给你的任务({task.title}),请查看并认领。")

    # 5. 处理 blocked 任务（L3: spawn 庞统决策）agent 请求帮助）
    for task in board.get_blocked_tasks():
        mentions = get_latest_comment_mentions(task.id)
        if mentions:
            # 评论中 @ 了某人 → spawn 那个人
            for agent_id in mentions:
                if not is_agent_active(agent_id):
                    async_spawn_agent(agent_id,
                                message=f"任务 {task.id} 被 block,需要你的协助。")
        else:
            # 没有 @ → spawn 庞统来决定找谁帮忙
            async_spawn_agent('pangtong-fujunshi',
                        message=f"任务 {task.id} 被 block,没有指定协助者,请决定如何处理。")

    # 6. 清理完成的 session（L1: 文件操作）
    for session in get_completed_sessions():
        archive_session(session)         # mv jsonl → task 目录
        cleanup_sessions_json(session)   # 编辑 sessions.json 删除记录
```

### 4.3 Session 生命周期

```
1. Daemon spawn
   openclaw agent --agent zhangfei-dev --session-id <uuid> \
     --message "请检查黑板 task-001..."
   ↓
2. Agent 执行
   - 读黑板(SQLite 查询)
   - 做任务(编码/审核/数据分析)
   - 写回黑板(产出、评论、状态更新)
   ↓
3. Agent 退出(自然结束)
   ↓
4. Daemon 清理
   - mv <session_id>.jsonl → task-001/archive/
   - mv <session_id>.trajectory.jsonl → task-001/archive/
   - 编辑 sessions.json 删除该 session 记录
```

**技术验证结论:**
- `openclaw agent --agent <id> --session-id <uuid>` 可创建完全隔离的 session ✅
- 直接编辑 `sessions.json` 可安全删除 session 记录 ✅(已验证)
- Gateway WS `sessions.delete` 需要 `operator.admin` scope(token 模式不授予,不可用)❌
- 回退方案:直接编辑 `sessions.json` 是安全可靠的 ✅

### 4.4 Agent Spawn 后的消息内容

Agent 被 spawn 时,daemon 传递的消息应包含足够的上下文让 agent 知道该做什么:

```python
def build_spawn_message(task_id: str, trigger_reason: str, comments_since: str = None):
    task = get_task(task_id)

    msg = f"黑板任务通知:\n"
    msg += f"- 任务:{task.title}({task.id})\n"
    msg += f"- 状态:{task.status}\n"
    msg += f"- 触发原因:{trigger_reason}\n"

    if comments_since:
        recent = get_comments_since(task_id, comments_since)
        if recent:
            msg += f"\n最近评论:\n"
            for c in recent:
                msg += f"  [{c.created_at} {c.author}] {c.body[:200]}\n"

    msg += f"\n请读取黑板获取完整信息。"
    return msg
```

### 4.5 续杯与心跳

参考 v1.0 实践 + Hermes v0.13 Claim TTL。

**正常流（大多数情况）：**
1. Agent spawn → 开始工作
2. Agent 每个关键进展写黑板 observation（既是进度汇报，也是心跳信号）
3. Daemon tick 看到 working 状态 + 有新 observation → 不干预（健康状态）
4. Agent 完成产出 → 写 output + 状态流转 → Daemon 检测到继续下一步

**异常流：**

| 情况 | Daemon 检测到 | 行为 | 层级 |
|------|-------------|------|------|
| Agent 有进展 | 黑板有新 observations | 不干预（无限续） | L1 |
| Agent 没进展但 session 活跃 | 无新 observations 但 session 还在 | 不干预（可能正在思考） | L1 |
| timeout（agent run 返回超时）+ 产出达标 | agent run 返回超时 + outputs 表有内容 | 幻觉门控验证产出 → 通过则继续流转 | L1→L2 |
| timeout（agent run 返回超时）+ 产出不达标 | agent run 返回超时 + outputs 为空 | L2 spawn sub 发 reminder 让 Agent 继续（假死处理） | L2 |
| timeout + 产出不达标 + reminder 后仍无进展 | 二次 timeout | 回收到 pending，记录 failure_detail | L1 |
| 非timeout 错误（进程退出） | 进程已死 | 进入 AI 纠错流程 | L3 |
| 硬上限超时 | working 状态超过 3x 预估工时 | 强制回收，记录事件 | L1 |

**设计推导**：
- v1.0 实践证明：看结果不看过程（即使 CLI 报错/超时，产出文件存在且有效就算成功）
- 续命和重试是两个独立预算：续命（Agent有进度→无限续），重试（Agent真挂→有限次）
- Hermes 的 Claim TTL（默认15分钟）提供了超时回收的参考值

### 4.6 AI 驱动的 Retry（纠错协商）

参考 v1.0 _handle_blocked_node() + Hermes task_runs + Claude Code Teams "before retrying, answer what failed"。

**核心原则**：Retry 原因由 AI 判断，Daemon 只执行。

**流程：**

1. Agent 失败（产出 status=failed 或 Daemon 检测到异常终止）
2. Daemon 不判断原因，只在黑板上记录这次 attempt（task_runs 模式，每次 attempt 独立记录）
3. Daemon spawn 庞统（L3）看黑板上的失败记录 + 之前所有 attempts
4. 庞统在黑板上写决策（四种选择之一）：
   - "同一 Agent 重试" + 失败原因分析 + 改进建议
   - "换 Agent 重试" + 为什么换 + 新 Agent 优势
   - "任务需要用户介入" + 卡在哪 + 建议
   - "任务无法完成，建议取消" + 为什么
5. Daemon 读庞统决策，执行对应操作
6. 如果重试后仍失败 → 新 attempt 记录 → 再次 spawn 庞统
7. Circuit breaker：同一 task 连续失败 N 次（默认3次）→ 自动 block + 通知用户

**失败记录**：谁记录什么？

| 记录者 | 记录内容 | 黑板位置 |
|--------|---------|---------|
| Daemon | 机械类失败（进程退出码、超时） | events 表，event_type=task_failed |
| 司马懿 | 内容类失败（评审不通过） | reviews 表（verdict=needs_revision + issues） |
| 庞统 | 方向类失败（需求偏离） | decisions 表（重规划原因） |

| Agent（重试时） | 新 attempt 的产出 | outputs 表（带 attempt_number） |

**Agent 重试时能看到什么**：黑板上的 events（失败记录）+ reviews（评审意见）+ comments（讨论）。全部在黑板上，spawn 时自然读到。

**设计推导**：
- v1.0 实践：庞统分析原因 → 司马懿 challenge → 三轮协商 → 执行，方向正确但由引擎硬编码调用
- v2.6 改进：Agent 在黑板上自主协商（需要事件驱动支持，见课题2），Daemon 只 spawn 不调度
- Hermes task_runs：每次 attempt 独立记录（attempt_number, outcome, log_path, exit_code），可追溯可审计

### 4.7 Guardrail 体系（吹哨人机制）

参考 OpenAI Agent SDK OutputGuardrail + GSD must_haves + v1.0 M4 Guard 机制。

**核心原则**：Guardrail 是吹哨人不是终结者。检测到问题写黑板（observation），触发后续 AI 判断链。决策权在黑板上，执行权在 Daemon。

**三个 Guardrail：**

| Guardrail | 触发时机 | 检测方式 | 发现问题后 |
|-----------|---------|---------|-----------|
| **Scope Guard** | Agent claim 任务后在工作过程中写 decisions（scope 相关）时 | L2 sub 异步对比 scope_declaration vs task.truths | 写 observation（severity=warning），Daemon 下次 tick 触发庞统判断 |
| **Output Guard** | Agent 写 output 时 | L1 机械检查（文件存在、格式正确、字段非空）+ L2 语义检查 | 机械失败直接打回，语义问题写 observation |
| **Format Guard** | Agent 写任何结构化数据时 | L1 JSON Schema 校验 | 格式错误直接打回重做 |

**后续动作链（问题升级）：**

```
Guardrail 检测到问题 → 写黑板 observation
  ↓
Daemon tick 读到 observation
  ↓
根据 severity 分级处理：
  - blocking → L3 立即 spawn 庞统
  - warning → L3 spawn 庞统（下次 tick 统一处理）
  - info → 只记录，不触发
  ↓
庞统在黑板上写决策：
  - "确认偏离，打回" → Daemon 改状态回 pending
  - "方向扩展合理，批准继续" → 继续
  - "需要用户判断" → 通知用户
```

**设计推导**：
- OpenAI Agent SDK：Guardrail 本身是轻量 AI Agent（并行运行，专门做检查），不是 if-else 规则
- GSD must_haves truths：面向可观测行为，不是实现步骤
- v1.0 M4 Guard：entry/exit guard + skill 化检查逻辑，方向正确但绑定在 DAG 节点上

---

## 5. Agent 与黑板的交互

### 5.1 Agent 被_spawn_后的工作流程

```
Agent 被 spawn
    ↓
1. 读黑板 → 了解任务全局状态
   - 读 tasks 表:当前任务的状态、描述、依赖
   - 读 comments 表:讨论历史
   - 读 outputs 表:已有产出
   - 读 observations 表:已知风险
    ↓
2. 想 → 根据自己的职责自主决策
   - 我是编码先锋，这个 pending 任务适合我 → claim
   - 我是风控守将，这个 comment @ 我 → 回复
   - 我是副军师，这个任务需要分解 → 创建子任务
   - Agent claim 任务后、开始工作前，写 scope_declaration 到 decisions 表：
     "我计划做什么，产出什么"
     Scope Guard（L2 sub）会对比 scope_declaration vs task.truths
    ↓
3. 做 → 执行任务
   - 编码、审核、数据分析等
   - 过程中发现风险 → 写 observation
   - 需要其他人协助 → 写 comment @mention
    ↓
4. 写回黑板 → 产出、评论、状态更新、决策记录
   - 写 outputs 表：产出文件路径 + 摘要
   - 写 comments 表：完成说明
   - 写 decisions 表：关键决策（哪怕自己的决策也要填一条）
   - 更新 tasks 表：status → done/review
   - must_haves 三件套（任务创建时由庞统定义）：
     - truths：用户视角的可观测行为（"用户能看到回测结果"），不是实现步骤（"编写回测脚本"）
     - artifacts：必须存在的产出文件
     - constraints：继承的约束（如"不超过500行"、"必须用vnpy"）
    ↓
5. 退出 → daemon 自动清理 session
```

### 5.2 Agent 工具集

Agent 通过 `exec` 工具调用 CLI 命令操作黑板:

```bash
# 读黑板(全部)
python3 ~/.sanguo_projects/sanguo_moziplus/cli/blackboard.py read --task task-001

# 读黑板(过滤:只读和自己相关的)
python3 ~/.sanguo_projects/sanguo_moziplus/cli/blackboard.py read --task task-001 --agent zhangfei-dev

# 读黑板(过滤:只读最近 20 条)
python3 ~/.sanguo_projects/sanguo_moziplus/cli/blackboard.py read --task task-001 --last 20

# 读黑板(过滤:只读特定类型)
python3 ~/.sanguo_projects/sanguo_moziplus/cli/blackboard.py read --task task-001 --type comments

# 认领任务
python3 ~/.sanguo_projects/sanguo_moziplus/cli/blackboard.py claim --task task-001 --agent zhangfei-dev

# 写产出
python3 ~/.sanguo_projects/sanguo_moziplus/cli/blackboard.py output --task task-001 --agent zhangfei-dev \
  --type code --title "分批加载实现" --path task-001/output-zhangfei.md \
  --summary "实现分批加载,单批50万条"

# 写评论
python3 ~/.sanguo_projects/sanguo_moziplus/cli/blackboard.py comment --task task-001 --author zhangfei-dev \
  --body "完成分批加载实现" --mentions "[]"

# 写观察
python3 ~/.sanguo_projects/sanguo_moziplus/cli/blackboard.py observe --task task-001 --observer guanyu-dev \
  --severity warning --body "止损逻辑需适配分批模式"

# 记录决策
python3 ~/.sanguo_projects/sanguo_moziplus/cli/blackboard.py decide --task task-001 --decider zhangfei-dev \
  --decision "使用分批加载而非流式" --rationale "流式需要改底层框架,分批只需改回测模块"

# 创建任务(任何 Agent 都可以创建)
python3 ~/.sanguo_projects/sanguo_moziplus/cli/blackboard.py create --title "分钟线数据下载" \
  --creator zhaoyun-data --task-type data
```

---

## 6. 关键场景流程

### 6.1 庞统规划 + Agent 领任务

```
用户 → 庞统(主session):"设计一个动量因子策略"
    ↓
庞统在黑板上写:
  - 创建 task-001(数据准备,pending)
  - 创建 task-002(因子计算,pending,depends_on: [task-001])
  - 创建 task-003(回测验证,pending,depends_on: [task-002])
  - 评论:"建议赵云领 001,张飞领 002 和 003"
    ↓
Daemon tick 发现 task-001 pending + 庞统评论建议赵云
    ↓
Daemon spawn 赵云 → 赵云读黑板 → claim task-001 → 执行 → 写产出 → 退出
    ↓
Daemon tick 发现 task-001 done → task-002 depends_on 满足
    ↓
Daemon spawn 张飞 → 张飞读黑板 → claim task-002 → 执行 → 写产出 → 退出
    ↓
(同理 task-003)
```

### 6.2 Agent 间协作讨论

```
张飞执行 task-002 时发现需要分钟线数据
    ↓
张飞写评论:"@赵云 task-002 需要分钟线数据,能帮忙下载吗?"
张飞更新任务状态 → blocked
    ↓
Daemon tick 发现 task-002 blocked + 评论 @ 赵云
    ↓
Daemon spawn 赵云 → 赵云读黑板 → 看到评论 → 下载数据
赵云写评论:"分钟线数据已下载到 /path/to/data" + 写产出
赵云写评论:"@张飞 数据就绪,可以继续"
    ↓
Daemon tick 发现评论 @ 张飞
    ↓
Daemon spawn 张飞 → 张飞读黑板 → 看到数据就绪 → 继续 task-002
```

### 6.3 Agent 发现风险

```
张飞在 task-002 中发现止损逻辑有 bug
    ↓
张飞写 observation(severity: warning):
  "止损逻辑在分批模式下可能漏触发"
张飞写评论:"@关羽 止损逻辑需要你从风控角度确认"
    ↓
Daemon tick 发现 observation + 评论 @ 关羽
    ↓
Daemon spawn 关羽 → 关羽读黑板 → 审查 → 写评论 + observation
```

### 6.4 用户直接参与

```
用户读黑板 → 发现 task-002 进度慢
    ↓
用户在黑板上写评论:"task-002 优先级提高,需要今天完成"
    ↓
Daemon tick 发现用户评论 → 如果张飞未 active → spawn 张飞通知
```

---

## 7. Session 隔离与清理

### 7.1 技术实现

```python
class SessionManager:
    def async_spawn_agent(self, agent_id: str, message: str) -> str:
        """异步 spawn 隔离 session,不等待完成。返回 session_id。"""
        session_id = str(uuid.uuid4())
        cmd = [
            "openclaw", "agent",
            "--agent", agent_id,
            "--session-id", session_id,
            "--message", message,
            "--json"
        ]
        # Popen 异步启动,不阻塞 daemon tick
        subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
        log_event(agent=agent_id, event_type='agent_spawned', detail={'session_id': session_id})
        return session_id

    def cleanup_session(self, agent_id: str, session_id: str, archive_dir: str):
        """存档 jsonl + 文件锁保护下清理 sessions.json"""
        sessions_dir = f"/Users/chufeng/.openclaw/agents/{agent_id}/sessions"
        store_path = f"{sessions_dir}/sessions.json"
        lock_path = f"{sessions_dir}/.cleanup.lock"

        # 1. 存档 jsonl 文件
        os.makedirs(archive_dir, exist_ok=True)
        for ext in ['.jsonl', '.trajectory.jsonl', '.trajectory-path.json']:
            src = f"{sessions_dir}/{session_id}{ext}"
            if os.path.exists(src):
                shutil.move(src, f"{archive_dir}/{session_id}{ext}")

        # 2. 文件锁保护下编辑 sessions.json(防止和 Gateway 并发写入冲突)
        with open(lock_path, 'w') as lock_file:
            fcntl.flock(lock_file, fcntl.LOCK_EX)
            try:
                with open(store_path) as f:
                    store = json.load(f)

                keys_to_remove = [k for k in store if session_id in k]
                for k in keys_to_remove:
                    del store[k]

                with open(store_path, 'w') as f:
                    json.dump(store, f, indent=2)
            finally:
                fcntl.flock(lock_file, fcntl.LOCK_UN)
                os.unlink(lock_path)
```

### 7.2 验证结论

| 验证项 | 结果 |
|--------|------|
| `openclaw agent --session-id <uuid>` 创建隔离 session | ✅ 通过 |
| 连续 spawn 多个 session 互不干扰 | ✅ 通过 |
| 并行 spawn 成功 | ✅ 通过 |
| 直接编辑 sessions.json 删除记录安全 | ✅ 通过 |
| jsonl 存档后从原目录删除 | ✅ 通过 |
| Gateway WS sessions.delete(需 admin scope) | ❌ 不可用 |
| `openclaw sessions cleanup --fix-missing --enforce` | ❌ 对 agent main session 报错 |
| Agent 主 session 对 CLI spawn 的 sub 完全无感 | ✅ 确认(设计如此)|

---

## 8. Sanguo Mail:退役

v2.6 中 Mail 完全退役。黑板的两个操作替代了 Mail 的所有功能:

| Mail 功能 | 黑板替代 |
|----------|--------|
| 庞统分配任务 | 庞统在黑板创建 task + 评论 @指定 agent |
| Agent 间通信 | 评论 @mention |
| 结果回传 | 产出写入 outputs 表 + 评论通知 |
| 讨论 | 评论线程 |

黑板比 Mail 更可靠:信息集中在 SQLite(不分散在 mail 目录)、有状态追踪、评论线程保持上下文完整、SQLite 读写比 Mail poller 更可靠。

如果需要系统级通知(daemon 异常、Gateway 状态),在黑板上创建 `system` 类型任务处理。

---

## 9. 质量门控(任务完成标准)

### 9.1 任务完成 = 司马懿评审通过 + 所有问题达成一致 + 修改完成

一个任务要标记为 `done`,必须满足:

1. **产出已提交** - Agent 写入 outputs 表
2. **决策已记录** - 关键决策写入 decisions 表(哪怕是自己的决策也要填一条)
3. **司马懿审核通过** - spawn 司马懿审核产出,评论中明确写"通过"
4. **所有问题达成一致** - 审核中提出的问题全部解决,讨论达成共识
5. **修改已完成** - 审核问题对应的修改已写入产出

### 9.2 达成一致的原则

- **以用户意图为导向** - 任何人(包括司马懿、庞统)说的都不一定对,最终以用户的原始意图为准
- **讨论达成共识** - 不同意见通过黑板评论讨论解决,不是谁职位高谁说了算
- **用户有最终裁量权** - 讨论无法达成一致时,@user 请用户裁定

### 9.3 流程

```
Agent 完成产出 → status: review
    ↓
Daemon tick → spawn 司马懿审核
    ↓
司马懿读黑板(产出 + 决策 + 观察)
    ↓
司马懿写评论:
  - "通过" → status: done
  - "不通过,原因:XXX" → status: pending(打回重做)+ 评论说明问题
    ↓
如果有争议:
  - 评论中讨论
  - 讨论不清 → @user 请求裁定
```

### 9.4 决策记录

Agent 执行过程中的每个关键决策都必须记录在黑板的 decisions 表中:

| 字段 | 含义 |
|------|------|
| decider | 谁做的决策 |
| decision | 决策内容(选了什么) |
| rationale | 为什么这样选 |
| alternatives | 被排除的选项 |

**哪怕是自己做的决策也要填一条。** 目的：
- 后续复盘时能追溯"当时为什么这样选"
- 审核时司马懿能理解决策背后的思考
- 经验沉淀的原始素材

### 9.5 分级审查矩阵

不是所有任务都值得同等深度的审查。按任务风险等级决定审查深度。

| 风险等级 | 任务类型 | 审查深度 | 参与者 |
|---------|---------|---------|--------|
| **高风险** | 量化策略、生产部署、数据删除 | 三阶段审查（方案审查→Output Guardrail→产出审查）+ 可选多视角对抗 | 庞统+司马懿+对应执行者 |
| **标准** | 编码、数据处理、配置修改 | 二阶段（Output Guardrail + 产出审查） | 司马懿+执行者 |
| **低风险** | 调研报告、文档更新、日志查看 | 一阶段（Output Guardrail 机械检查） | Daemon 自动 |
| **调研** | 技术调研、方案探索 | 一阶段（庞统确认方向） | 庞统 |

**风险等级**：庞统创建任务时标注。默认值为 `standard`。庞统的 Skill 中内置规则：创建 task_type 为 `strategy` 或 `deploy` 的任务时自动设为 `high`，`research` 类型自动设为 `research`。无需庞统手动判断。

**设计推导**：
- v1.0 实践：每个节点都要司马懿审查，简单任务过重
- superpowers：三阶段审查（implementer → spec reviewer → code quality reviewer），不同阶段不同深度
- Hermes：per-task retry budget，任务级别差异化

---

## 10. 产出物目录约定

```
~/.sanguo_projects/sanguo_moziplus/artifacts/
└── {task-id}/
    ├── outputs/          # Agent 产出物(代码、文档、数据)
    ├── archive/          # session jsonl 存档
    └── data/             # 数据文件
```

Agent 写产出时,`content_path` 指向此目录。Daemon 存档 session jsonl 时也写入 `archive/` 子目录。

---

## 11. 保留 v2.0 的设计

以下 v2.0 的设计在 v2.6 中保留:

1. **SQLite WAL 模式** - 黑板数据库同样使用 WAL
2. **结构化产出规范** - output.md frontmatter + 结论 JSON(写在黑板 outputs 表中)
3. **观察机制** - v2.0 Report Watcher 的思路升级为 observations 表
4. **证据原则** - 结论必须有证据(代码行号、日志、文件内容)
5. **审核流程** - 可通过黑板评论 + 状态机实现

---

## 12. Phase 规划(v2.6)

### Phase 1: 黑板基础设施
1. SQLite blackboard.db(5 表 + WAL)
2. blackboard.py CLI(读写操作)
3. Daemon tick 循环(读黑板 + spawn + 清理)
4. Session 管理(spawn + 存档 + 清理)

### Phase 2: Agent 交互
5. Agent 黑板操作 Skill
6. 评论 + @mention 通知链路
7. 任务依赖自动推进
8. 健康检查(stale reclaim + zombie 检测)

### Phase 3: 智能化
9. 庞统 AI 规划(读需求 → 创建任务 + 分配建议)
10. Agent 自主领活(读黑板 → 匹配职责 → claim)
11. 产出验证门禁
12. 经验沉淀(observation → knowledge base)

---

## 13. 技术选型

| 需求 | 参考系统 | 我们的方案 | 理由 |
|------|---------|-----------|------|
| 共享状态 | Hermes SQLite + Network-AI flock | SQLite WAL + 事务 CAS | 原子性 + 无外部依赖 |
| 讨论 | Hermes kanban_comment | comments 表 + @mention | 简单追加写入,所有人可见 |
| 调度 | Hermes Dispatcher 60s tick | Daemon 60s tick | 同设计,更轻量 |
| 通知 | Claude Code idle notification | Daemon spawn + message | OpenClaw 原生能力 |
| 通信 | Hermes kanban_comment + Claude Code inbox | 黑板 comments + @mention | 替代 Sanguo Mail |
| 竞态 | Network-AI propose→validate→commit | SQLite CAS(first-commit-wins) | SQLite 事务足够 |
| Session | Hermes process-per-worker | openclaw agent --session-id | OpenClaw 原生隔离 |
| 清理 | 无参考 | 编辑 sessions.json | 已验证可行 |

---

## 14. 风险和缓解

| 风险 | 概率 | 缓解 |
|------|------|------|
| Agent 上下文不足(隔离 session 没有历史)| 中 | spawn 时传递黑板关键信息 + agent 可主动读黑板 |
| Daemon 单点故障 | 低 | PM2 自动重启 + tick 无状态 |
| SQLite 并发写入 | 中 | WAL + busy_timeout + BEGIN IMMEDIATE |
| 黑板膨胀(大量评论/产出)| 低 | 定期 archive + agent 只读最近 N 条 |
| Agent 不知道该做什么 | 中 | Skill 指导 + 庞统 plan 评论 + daemon 消息含上下文 |
| Sanguo Mail 退役后的系统通知 | 低 | 黑板 system 类型任务替代 |