# 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 正常接收