auto-sync: 2026-05-30 15:32:37

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

@@ -1,9 +1,9 @@
 # #04 黑板协作模型设计
 
-> 版本: v1.0  
+> 版本: v1.1  
 > 日期: 2026-05-30  
 > 作者: 庞统（副军师）  
-> 状态: 评审中  
+> 状态: v1.1 修订（司马懿评审意见已纳入）  
 > 前置: #02 Main Session + Delegation, #03 Prompt 进化  
 
 ---
@@ -90,36 +90,68 @@
 
 ## 三、设计方案
 
-### 3.1 统一路由：取消 assignee，用 @mention 统一
+### 3.1 统一路由：assignee 降级为显示字段，路由统一走 @mention
 
-**核心决策**：取消 `assignee` 字段的路由功能，统一用黑板 Comment + @mention 触发路由。
+**核心决策**：保留 `assignee` 字段作为「负责人」显示字段，但路由触发统一走 @mention。
 
 | 之前 | 之后 |
 |------|------|
-| 创建任务传 `assignee` → 确定性路由 | 创建任务时在 description 中 `@张飞` → daemon 自动路由 |
-| Agent 不知道用 assignee 还是 @mention | 只有一种方式：@ |
+| 创建任务传 `assignee` → 确定性路由 | 创建任务时在 description 中 `@zhangfei-dev` → daemon 自动推断 assignee + 路由 |
+| Agent 不知道用 assignee 还是 @mention | 只有一种路由入口：@ |
 | assignee 是单人的 | @ 可以 @ 多人 |
 
-**实现**：
-- `assignee` 字段保留但降级为**纯显示用途**（由 daemon 自动从 mention 中推断）
-- 创建任务时，daemon 扫描 description 和第一条 comment 中的 `@Agent` 模式
-- 匹配到的 Agent 作为确定性路由目标
-- 无 @ 匹配 → 广播认领
+**为什么保留 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",
-  "assignee": "zhangfei-dev"      # 谁来做
-}
-
-# 之后
-POST /tasks {
-  "title": "写 hello.py",
-  "description": "@zhangfei-dev 写一个 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 语义增强