99 lines
3.0 KiB
Markdown
99 lines
3.0 KiB
Markdown
# 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 正常接收
|