# #04 黑板协作模型设计

> 版本: v1.1  
> 日期: 2026-05-30  
> 作者: 庞统（副军师）  
> 状态: ✅ 已完成（@mention + mention_queue 已实现）  
> 前置: #02 Main Session + Delegation, #03 Prompt 进化  

---

## 一、问题陈述

当前黑板有 7 种信息类型（Task/Comment/Output/Event/Review/Decision/Observation），全部通过 `task_id` 平铺关联。E2E 测试暴露了三个设计缺陷：

### 问题 1：assignee 和 @mention 功能重叠

| 机制 | 触发方式 | 路由行为 |
|------|---------|---------|
| assignee 字段 | 创建任务时传 `assignee: "zhangfei-dev"` | 确定性路由 |
| @mention | Comment 中 `mentions: ["zhaoyun-data"]` | mention_queue → spawn |

**问题**：两者都能触发"找人做事"，语义不同但边界模糊。
- Agent 不知道什么时候用 assignee，什么时候用 @
- assignee 是单人的，但任务可能需要多人协作
- @mention 需要额外传 `mentions` 数组，容易遗漏

### 问题 2：一个任务只能有一个 assignee

当前 `assignee` 是单个字符串。但现实中：
- 一个数据准备任务可能需要赵云（获取）+ 关羽（风控审核）
- 一个部署任务可能需要姜维（部署）+ 关羽（安全检查）
- 庞统创建子任务时需要同时指定多人

### 问题 3：信息组织是平铺的，缺乏结构化视图

当前 `expand=all` 只展开当前 task 的子表，不递归子任务。用户想看"数据准备子任务的所有 comments 和成果物"，需要：
1. 先查父任务，找到子任务 ID
2. 再逐个查每个子任务的 `expand=all`

信息之间的关联（比如 Output #3 是 Comment #2 的结果）无法表达。

---

## 二、优秀实践调研

### 2.1 项目管理工具的共识

**Jira / Linear / Asana 共同模式**：

| 洞察 | 来源 | 启示 |
|------|------|------|
| 单表存所有任务 + 类型字段区分 | Jira `issuetype` | 不需要为不同任务类型建不同表 |
| `parent_id` + `topmost_id` 实现层级 | Jira | 父子关系用指针，不是嵌套 |
| Project 是逻辑隔离边界 | Jira/Linear | 一个 Project 一个黑板 DB |
| 一个 Task 可属于多个 Project | Asana | 多对多关系（cross-project） |

### 2.2 AI Agent 编排系统的共识

**LangGraph / CrewAI / AutoGen 共同模式**：

| 洞察 | 来源 | 启示 |
|------|------|------|
| 子任务隔离 + 结果摘要回传 | LangGraph Subgraph | 子任务有独立状态，完成后折叠 |
| 共享 Memory + Crew 边界 | CrewAI | 同一 Crew 共享记忆 |
| 对话历史即上下文 | AutoGen | 不需要额外机制，消息本身就是上下文 |
| 扁平 Handoff + Context Variables | OpenAI Swarm | 最简模型，适合简单场景 |

### 2.3 学术和实践前沿

| 洞察 | 来源 | 启示 |
|------|------|------|
| **共享产出物 > 共享消息** | O'Reilly 2026 | 围绕 artifact 协作，不是围绕消息 |
| **Phase gates + shared artifacts + final supervisor** | O'Reilly 2026 | 2026 存活系统的共同特征 |
| **共享工作区 + 结构化产出 > 消息传递** | Claude Code 实践 | 文件系统 + JSON 接口 |
| **对话历史传递 surprisingly effective** | OpenAI Handoff | 转交时携带完整上下文 |
| **bMAS 迭代收敛到共识** | arXiv:2507.01701 | Agent 轮流行动直到黑板达成共识 |
| **propose→validate→commit 原子写入** | Network-AI | 消除 split-brain |
| **Auftragstaktik 任务式指挥** | ClawTeam #10 | Intent→End State→Constraints，不指定步骤 |

### 2.4 核心设计原则（从调研提炼）

1. **黑板是唯一真相源** — 所有 Agent 通过黑板共享信息
2. **产出物 > 消息** — 围绕共享产出物协作，不是围绕消息传递
3. **结构对称** — 不把任何 Agent 当"主"，Canonical IR 原则
4. **单一职责** — 每种信息类型只表达一件事
5. **可追溯** — 不可变事件日志，写入即审计
6. **任务式指挥** — Intent→End State→Constraints，Agent 自主决定怎么做

---

## 三、设计方案

### 3.1 统一路由：assignee 降级为显示字段，路由统一走 @mention

**核心决策**：保留 `assignee` 字段作为「负责人」显示字段，但路由触发统一走 @mention。

| 之前 | 之后 |
|------|------|
| 创建任务传 `assignee` → 确定性路由 | 创建任务时在 description 中 `@zhangfei-dev` → daemon 自动推断 assignee + 路由 |
| Agent 不知道用 assignee 还是 @mention | 只有一种路由入口：@ |
| assignee 是单人的 | @ 可以 @ 多人 |

**为什么保留 assignee 字段（不取消）**：
1. **前端展示**：「这个任务谁负责」是刚需
2. **Mail 特殊处理**：Mail 的 assignee 是收件人，不能取消
3. **向后兼容**：存量任务已有 assignee 值
4. **查询效率**：`WHERE assignee=?` 比扫描 description 中的 @ 快

**assignee 从「路由入口」变为「路由结果」**：
- API 调用方不再直接设置 assignee（废弃）
- daemon 从 description/comment 中的 @mention 自动推断 assignee
- router 快速路径保持不变（仍然读 assignee 字段，只是赋值来源变了）

#### 迁移方案

**阶段 1（#04 Phase 1）**：双轨并行
- 创建任务时仍接受 `assignee` 参数（向后兼容，标记为 deprecated）
- 新增：daemon 从 description 中提取 @mention → 如果有匹配 → 自动覆盖 assignee
- router 快速路径保持不变（读 assignee 字段路由）
- 无 assignee 且无 @mention → 广播认领

**阶段 2（#04 Phase 2）**：全面切换
- API 不再接受 `assignee` 参数（返回 deprecation warning）
- assignee 完全由 daemon 从 @mention 推断
- router 快速路径不变（仍然读 assignee 字段，只是赋值来源变了）

**阶段 3（未来）**：清理
- 移除 API 的 assignee 参数
- 存量任务：assignee 值保留不动（已经是正确的负责人信息）

**代码影响评估**：
| 文件 | 影响 | 改动 |
|------|------|------|
| router.py L155-160 | assignee 快速路径 | ✅ 保持不变（仍然读 assignee 字段） |
| dispatcher.py L427-446 | assignee 作为 dispatch 依据 | ✅ 保持不变 |
| ticker.py _transition_status | pending 时清空 assignee | ✅ 保持不变 |
| API POST /tasks | 接受 assignee 参数 | Phase 1 保留，Phase 2 废弃 |
| ticker.py _tick_project | 新增：创建后扫描 description 提取 @mention | 新代码 |

**API 变化**：
```python
# Phase 1：两种方式都支持，@mention 优先
POST /tasks {
  "title": "写 hello.py",
  "description": "@zhangfei-dev 写一个 hello.py"
}
# daemon 自动提取 assignee=zhangfei-dev
# 也可以旧方式：assignee="zhangfei-dev"（deprecated）

# Phase 2：只用 @mention
POST /tasks {
  "title": "写 hello.py",
  "description": "@zhangfei-dev 写一个 hello.py"
}
```

### 3.2 @mention 语义增强

**当前问题**：Comment 需要**同时**写 `body` 中的 `@zhaoyun-data` **和** `mentions` 数组。Agent 容易遗漏。

**改进方案**：daemon 自动从 `body` 中提取 `@Agent` 模式，自动填充 `mentions`。

```python
# Agent 只需要写 body
POST /comments {
  "author": "pangtong-fujunshi",
  "body": "@zhaoyun-data 你来获取沪深300行情数据，@guanyu-dev 数据到了你做风控检查"
}

# daemon 自动提取 → mentions: ["zhaoyun-data", "guanyu-dev"]
# 写入 mention_queue → 两人都收到 mention spawn
```

**提取规则**（D4 决策：只支持 @agent-id 格式）：
- 正则 `@([a-z]+-[a-z]+-[a-z]+)` 匹配已知 Agent ID 列表
- 匹配到的 Agent 写入 `mentions` 字段（如果前端也传了 `mentions`，取并集）
- 不认识的 @ 目标忽略（可能是 @文档 @链接）
- **不支持中文昵称**（@张飞）—— agent-id 是系统唯一标识，无歧义。未来如需支持，加 alias 映射即可

### 3.3 多人协作模式

@ 多人 ≠ 多人同时执行同一任务。而是**每人收到 mention spawn，自主协调**：

| @ 模式 | 含义 | Daemon 行为 |
|--------|------|------------|
| `@zhangfei-dev` | 指定张飞做这个任务 | 确定性路由给张飞 |
| `@zhaoyun-data @guanyu-dev` | 需要两人协作 | 创建两个子任务，分别路由 |
| `@所有人` | 不知道谁合适 | 广播认领 |
| 无 @ | 不需要特定人 | 广播认领 |

**@多人 → 自动拆子任务**（Phase 2，暂不实现）：

```
庞统创建任务：@zhaoyun-data 获取数据，@zhangfei-dev 写策略代码

Daemon 自动拆解：
├── 子任务 1: 获取数据 → assignee: zhaoyun-data
└── 子任务 2: 写策略代码 → assignee: zhangfei-dev, depends_on: [子任务 1]
```

Phase 1 只做：@多人 → 每个人收到 mention spawn，各自决定如何协作。

### 3.4 信息关联模型重构

**当前**：7 种信息平铺挂在 `task_id` 上，互相之间无关联。

**改进**：引入 `parent_id` 串联信息流。

#### Output 关联 Comment

```python
# 当前
POST /outputs {agent, content_type, summary}
# 产出物和讨论没有关联

# 改进：output 关联到触发它的 comment
POST /outputs {
  agent: "zhaoyun-data",
  content_type: "data",
  summary: "沪深300日频行情",
  triggered_by_comment: 42    # ← 新字段，关联到 @赵云 的那条 comment
}
```

#### 反向索引

```sql
CREATE INDEX IF NOT EXISTS idx_outputs_triggered_by ON outputs(triggered_by_comment);
```

支持查询「这条 comment 触发了哪些 outputs」。

#### Review 关联 Output

当前 `Review.output_id` 已有关联，保持不变。

#### 信息流视图

```
Comment #1: "@zhaoyun-data 获取沪深300行情"
  └── mention_queue → spawn 赵云
       └── Comment #2: "数据已获取，见附件"
            └── Output #1: content_path=/data/market.csv, triggered_by_comment=#1
                 └── Review #1: verdict=approved, output_id=#1
```

### 3.5 层级查询 API

**当前痛点**：想看"数据准备子任务的所有信息"需要多次查询。

**改进**：新增聚合查询 API（D3 决策：Phase 2 实施，含子任务的完整版 Phase 3）。

#### Phase 2：单任务 timeline

```
GET /api/projects/{pid}/tasks/{task_id}/timeline?limit=50&offset=0

返回：
{
  "task": {...},
  "timeline": [
    {
      "task": {...},
      "comments": [...],
      "outputs": [...],
      "reviews": [...]
    }
  ],
  "timeline": [
    {"ts": "...", "type": "comment", "author": "pangtong", "body": "@zhaoyun-data ..."},
    {"ts": "...", "type": "mention", "agent": "zhaoyun-data", "status": "notified"},
    {"ts": "...", "type": "status", "from": "pending", "to": "claimed"},
    {"ts": "...", "type": "comment", "author": "zhaoyun-data", "body": "数据已获取"},
    {"ts": "...", "type": "output", "agent": "zhaoyun-data", "summary": "沪深300行情"},
    {"ts": "...", "type": "review", "verdict": "approved"}
  ],
  "total": 42,
  "has_more": true
}
```

- 只聚合当前任务（不含子任务）的 comments + outputs + reviews + events + mentions
- 支持 `limit` + `offset` 分页
- 按 `created_at` DESC 排序

#### Phase 3：含子任务的完整 timeline

聚合子任务信息，考虑 materialized view 或 cache 优化性能（WARN-3）。

---

## 四、实施计划

### Phase 1（与 #02/#03 一起验证）

| 改动 | 影响 |
|------|------|
| daemon 自动从 body 提取 @mention | Agent 不再需要手动传 `mentions` 数组 |
| claim prompt 补充完整 API（RC-2） | Agent 知道怎么写产出物 |
| assignee 保留但降级为显示字段 | 向后兼容 |

### Phase 2（#04 独立实施）

| 改动 | 影响 |
|------|------|
| 创建任务时从 description 提取 @ → 自动 assignee | 统一路由入口 |
| API assignee 参数废弃（返回 deprecation warning） | 向后兼容过渡 |
| @mention 自动提取（blackboard_routes.py） | Agent 不再需要手动传 mentions |
| Output 新增 triggered_by_comment 字段 + 索引 | 信息关联 |
| /timeline 聚合查询 API（单任务版） | 结构化视图 |

### Phase 3（未来）

| 改动 | 影响 |
|------|------|
| @多人自动拆子任务（LLM 辅助） | 复杂协作 |
| @所有人 广播语法 | 统一广播入口 |
| /timeline 含子任务完整版 + materialized view | 全景视图 |
| Context Folding（子任务完成后折叠） | 上下文管理 |
| Fidelity 三档信息路由 | 按 Agent 角色分档展示 |

---

## 五、设计决策（已确认）

| # | 决策 | 结论 | 理由 |
|---|------|------|------|
| D1 | assignee 是否完全取消？ | **保留为显示字段，路由统一走 @mention** | 前端展示/Mail/向后兼容/查询效率 |
| D2 | @多人 Phase 1 是否自动拆子任务？ | **不自动拆，Phase 3 再做** | daemon 无法可靠推断依赖关系 |
| D3 | timeline API 是否 Phase 1 就做？ | **Phase 2 做（单任务版）** | 先让 E2E 跑通 |
| D4 | @ 模式支持中文昵称？ | **只支持 @agent-id** | 无歧义，低维护成本 |

---

## 附录：调研来源

- Jira 数据库设计（单表 + issuetype + parent_id）
- Linear/Asana 层级模型（Workspace 隔离 + 逻辑分组）
- LangGraph Subgraph 模式（子任务隔离 + State 映射回传）
- CrewAI 共享 Memory（Crew 边界）
- bMAS 黑板架构（Control Unit 动态路由 + 迭代收敛）
- O'Reilly 2026（共享产出物 > 共享消息 + Phase gates）
- OpenAI Handoff（对话历史传递 surprisingly effective）
- Network-AI（propose→validate→commit 原子写入）
- ClawTeam #10（Auftragstaktik 任务式指挥）
- Opal-Bridge（Canonical IR + Fidelity 三档）