sanguo_moziplus_v2/docs/design/04-blackboard-collaboration-model.md

#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 变化：

# 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。

# 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

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

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

反向索引

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 三档）