docs: kanban handler protocol v1 + merged API ref

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

docs/kanban-api-reference.md

@@ -1,59 +1,52 @@
 # Kanban HTTP API — 跨机器任务协作
 
-所有 Agent（mohe、zhiwei、xxm、xiao）通过 HTTP API 读写 kanban 任务卡片。
+看板已合入 AgentsMeeting Dashboard（5803），不再独立于 9580 端口。
-不需要 Hermes，不需要 XMPP bot，只需要能 curl 到 `192.168.1.246: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 http://192.168.1.246:5803/api/kanban/t_3adcf4a6
-curl -X POST ... -d '{"assignee":"xxm"}'
-
-# 只看待处理
-curl -X POST ... -d '{"status":"ready"}'
 ```
 
-### 查看单个任务
+返回 JSON，含 comments 数组。
-```bash
-curl -X POST http://192.168.1.246:9580/kanban/show -d '{"id":"t_3adcf4a6"}'
-```
 
-### 添加评论（有问题或进展时用）
+## 创建 / 更新 / 评论
-```bash
-curl -X POST http://192.168.1.246:9580/kanban/comment \
-  -d '{"id":"t_3adcf4a6","author":"xxm","body":"这里有个问题：..."}'
-```
 
-评论会发到核心群通知所有人。
+（走 kanban handler 流程，暂不开放 HTTP 写操作）
-
-### 查看评论
-```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"}'
-```
 
 ## 沟通流程
 
-1. 创建任务 → 核心群收到通知
+1. 创建任务 → Dashboard 事件 → XMPP DM 通知目标 agent
-2. 你有问题 → 加评论（curl comment）
+2. agent 在 kanban-handler session 里处理
-3. 评论被看到 → 有人回复评论
+3. 有疑问 → 评论卡片 → 触发新一轮通知
-4. 完成 → 更新状态为 done
+4. 完成 → 更新 status=done → 可选汇报
 
 **不需要在群里说话。** 评论代替讨论，通知代替 @。