auto-sync: 2026-05-30 15:34:26

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

@@ -171,10 +171,11 @@ POST /comments {
 # 写入 mention_queue → 两人都收到 mention spawn
 ```
 
-**提取规则**：
-- 正则 `@([a-z]+-[a-z]+)` 匹配已知 Agent ID
+**提取规则**（D4 决策：只支持 @agent-id 格式）：
+- 正则 `@([a-z]+-[a-z]+-[a-z]+)` 匹配已知 Agent ID 列表
 - 匹配到的 Agent 写入 `mentions` 字段（如果前端也传了 `mentions`，取并集）
 - 不认识的 @ 目标忽略（可能是 @文档 @链接）
+- **不支持中文昵称**（@张飞）—— agent-id 是系统唯一标识，无歧义。未来如需支持，加 alias 映射即可
 
 ### 3.3 多人协作模式
 
@@ -221,6 +222,14 @@ POST /outputs {
 }
 ```
 
+#### 反向索引
+
+```sql
+CREATE INDEX IF NOT EXISTS idx_outputs_triggered_by ON outputs(triggered_by_comment);
+```
+
+支持查询「这条 comment 触发了哪些 outputs」。
+
 #### Review 关联 Output
 
 当前 `Review.output_id` 已有关联，保持不变。
@@ -239,15 +248,17 @@ Comment #1: "@zhaoyun-data 获取沪深300行情"
 
 **当前痛点**：想看"数据准备子任务的所有信息"需要多次查询。
 
-**改进**：新增聚合查询 API。
+**改进**：新增聚合查询 API（D3 决策：Phase 2 实施，含子任务的完整版 Phase 3）。
+
+#### Phase 2：单任务 timeline
 
 ```
-GET /api/projects/{pid}/tasks/{task_id}/timeline
+GET /api/projects/{pid}/tasks/{task_id}/timeline?limit=50&offset=0
 
 返回：
 {
   "task": {...},
-  "children": [
+  "timeline": [
     {
       "task": {...},
       "comments": [...],
@@ -262,11 +273,19 @@ GET /api/projects/{pid}/tasks/{task_id}/timeline
     {"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
 }
 ```
 
-`timeline` 把一个任务（含子任务）的所有事件按时间线排列，一目了然。
+- 只聚合当前任务（不含子任务）的 comments + outputs + reviews + events + mentions
+- 支持 `limit` + `offset` 分页
+- 按 `created_at` DESC 排序
+
+#### Phase 3：含子任务的完整 timeline
+
+聚合子任务信息，考虑 materialized view 或 cache 优化性能（WARN-3）。
 
 ---