docs: kanban handler protocol v1 + merged API ref
This commit is contained in:
@@ -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 正常接收
|
||||
@@ -1,59 +1,52 @@
|
||||
# Kanban HTTP API — 跨机器任务协作
|
||||
|
||||
所有 Agent（mohe、zhiwei、xxm、xiao）通过 HTTP API 读写 kanban 任务卡片。
|
||||
不需要 Hermes，不需要 XMPP bot，只需要能 curl 到 `192.168.1.246:9580`。
|
||||
看板已合入 AgentsMeeting Dashboard（5803），不再独立于 9580 端口。
|
||||
|
||||
## 基础 URL
|
||||
|
||||
```
|
||||
http://192.168.1.246:9580/kanban
|
||||
http://192.168.1.246:5803
|
||||
```
|
||||
|
||||
## 操作
|
||||
## 浏览器查看
|
||||
|
||||
直接打开 `http://192.168.1.246:5803/` → 点顶栏 **📋 Kanban** tab。
|
||||
支持按状态和指派者筛选。
|
||||
|
||||
## REST API
|
||||
|
||||
### 列出任务
|
||||
|
||||
### 查看所有任务
|
||||
```bash
|
||||
curl -X POST http://192.168.1.246:9580/kanban/list -H "Content-Type: application/json" -d '{}'
|
||||
# 全部
|
||||
curl http://192.168.1.246:5803/api/kanban
|
||||
|
||||
# 按状态筛选
|
||||
curl "http://192.168.1.246:5803/api/kanban?status=ready"
|
||||
|
||||
# 按指派者筛选
|
||||
curl "http://192.168.1.246:5803/api/kanban?assignee=mohe"
|
||||
```
|
||||
|
||||
可以筛选：
|
||||
返回 JSON 数组，每项含 id / title / body / status / assignee / created_at。
|
||||
|
||||
### 查看单个任务（含评论）
|
||||
|
||||
```bash
|
||||
# 只看指派给自己的
|
||||
curl -X POST ... -d '{"assignee":"xxm"}'
|
||||
|
||||
# 只看待处理
|
||||
curl -X POST ... -d '{"status":"ready"}'
|
||||
curl http://192.168.1.246:5803/api/kanban/t_3adcf4a6
|
||||
```
|
||||
|
||||
### 查看单个任务
|
||||
```bash
|
||||
curl -X POST http://192.168.1.246:9580/kanban/show -d '{"id":"t_3adcf4a6"}'
|
||||
```
|
||||
返回 JSON，含 comments 数组。
|
||||
|
||||
### 添加评论（有问题或进展时用）
|
||||
```bash
|
||||
curl -X POST http://192.168.1.246:9580/kanban/comment \
|
||||
-d '{"id":"t_3adcf4a6","author":"xxm","body":"这里有个问题：..."}'
|
||||
```
|
||||
## 创建 / 更新 / 评论
|
||||
|
||||
评论会发到核心群通知所有人。
|
||||
|
||||
### 查看评论
|
||||
```bash
|
||||
curl -X POST http://192.168.1.246:9580/kanban/comments -d '{"id":"t_3adcf4a6"}'
|
||||
```
|
||||
|
||||
### 更新任务状态
|
||||
```bash
|
||||
curl -X POST http://192.168.1.246:9580/kanban/update \
|
||||
-d '{"id":"t_3adcf4a6","status":"done"}'
|
||||
```
|
||||
（走 kanban handler 流程，暂不开放 HTTP 写操作）
|
||||
|
||||
## 沟通流程
|
||||
|
||||
1. 创建任务 → 核心群收到通知
|
||||
2. 你有问题 → 加评论（curl comment）
|
||||
3. 评论被看到 → 有人回复评论
|
||||
4. 完成 → 更新状态为 done
|
||||
1. 创建任务 → Dashboard 事件 → XMPP DM 通知目标 agent
|
||||
2. agent 在 kanban-handler session 里处理
|
||||
3. 有疑问 → 评论卡片 → 触发新一轮通知
|
||||
4. 完成 → 更新 status=done → 可选汇报
|
||||
|
||||
**不需要在群里说话。** 评论代替讨论，通知代替 @。
|
||||
|
||||
Reference in New Issue
Block a user