docs: kanban handler protocol v1 + merged API ref

2026-06-22 10:43:08 +08:00
parent 08f04e773b
commit 20389a40ac
2 changed files with 128 additions and 37 deletions
@@ -0,0 +1,98 @@
+# Kanban Handler Protocol v1
+
+看板任务通知的跨 Agent 处理规范。定义 XMPP bot 收到看板通知后如何路由、处理、反馈。
+
+---
+
+## 1. 通知链路
+
+```
+Kanban Dashboard (5803)
+  │  事件触发（create / assign / comment）
+  │
+  ├─ POST /api/kanban → 写 DB
+  │
+  └─ state_meta 写事件 + XMPP DM 通知目标 agent
+       │
+       └─ bot 收到 DM → 识别 [Kanban] 前缀
+            │
+            └─ 路由到 kanban-handler session
+```
+
+## 2. Session 路由规则
+
+| 触发方式 | 路由目标 | 说明 |
+|---------|---------|------|
+| XMPP DM 通知（`[Kanban]` 开头） | `kanban-handler` 专用 session | 系统自动派卡，不打断当前对话 |
+| 老爸在群/私信 @agent "把那张卡做了" | 当前 session | 人为指定上下文 |
+| 老爸私信 "t_xxx 帮我看看" | 当前 session | 同上 |
+
+**核心原则：专用 session 不猜路由。** handler session 不需要判断"这个 task 应该属于哪个活跃 session"。卡片 body 就是上下文，不够就去 API 拉。
+
+## 3. Handler Session
+
+每个 agent 维护一个名为 `kanban-handler` 的 session。这个 session：
+
+- **预载 kanban-handler skill**（见 skill 定义）
+- **继承 agent 原有的 SOUL 和工具链**——不改身份，只加工作流
+- **保持待命**，处理完一个通知后不退出
+- **不做 DM 主动联系**，除非任务完成需要汇报
+
+## 4. 事件处理流程
+
+### 4.1 事件类型与动作
+
+| 事件 | Agent 动作 |
+|------|-----------|
+| `card.assigned` | 拉详情 → 三叉判断（执行/追问/转派）→ 更新 |
+| `card.commented` | 拉最新评论 → 判断是否需要回应 |
+| `card.status_changed` | 只记录，不行动 |
+
+### 4.2 三叉判断
+
+```
+收到 card.assigned
+  │
+  ├─ A: 这是我的活，body 清晰
+  │    → 直接执行
+  │    → 评论结果 + 更新 status=done
+  │    → 分配类任务完成 → DM 汇报摘要
+  │
+  ├─ B: 需要更多信息
+  │    → 评论卡片提问
+  │    → 更新 status=blocked
+  │    → 不 DM
+  │
+  └─ C: 不是我的领域
+       → 评论说明原因
+       → 转派给正确 agent（如果能判断）
+       → 不 DM
+```
+
+### 4.3 汇报规则
+
+- **分配类任务完成** → 简短 DM 给老爸摘要
+- **评论类通知** → 不汇报
+- **状态变更** → 不汇报
+- **转派/追问** → 不汇报
+
+## 5. 卡片上下文约定
+
+卡片 `body` 应包含足够让 agent 独立执行的上下文。如果一张卡的 body 只写了标题没有详情，agent 的处理方式是：
+
+```
+Step 1: 读 body + 评论
+Step 2: session_search("相关关键词") 查历史
+Step 3: 仍然不够 → 评论追问，blocked
+```
+
+**卡片写得好 = handler 不需要猜。**
+
+## 6. 加载方式
+
+handler session 启动时自动预载 `kanban-handler` skill。不写进 SOUL，不修改 agent 身份定义，可独立版本迭代。
+
+每个 agent 的部署者负责：
+- 创建 skill 文件（或从仓库同步）
+- 配置 bot 的 kanban 通知路由逻辑
+- 验证 handler session 正常接收