diff --git a/docs/KANBAN-HANDLER-PROTOCOL.md b/docs/KANBAN-HANDLER-PROTOCOL.md new file mode 100644 index 0000000..559f6e6 --- /dev/null +++ b/docs/KANBAN-HANDLER-PROTOCOL.md @@ -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 正常接收 diff --git a/docs/kanban-api-reference.md b/docs/kanban-api-reference.md index 8f8b59c..1d90399 100644 --- a/docs/kanban-api-reference.md +++ b/docs/kanban-api-reference.md @@ -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 → 可选汇报 **不需要在群里说话。** 评论代替讨论，通知代替 @。