71 lines
4.6 KiB
JSON
71 lines
4.6 KiB
JSON
{
|
||
"module": "kanban",
|
||
"version": "1.1",
|
||
"purpose": "看板任务系统。两个接口层：(1) kanban_api.py (:9580) 提供跨机器 Agent 完整读写 REST API；(2) dashboard.py (:5803) 'Kanban' tab 只读展示看板任务列表，支持按状态和负责人筛选，实时刷新。",
|
||
"ui_location": "主菜单 → Kanban tab (dashboard :5803)",
|
||
|
||
"human_help": {
|
||
"title": "Kanban 看板",
|
||
"description": [
|
||
"本页面展示系统中的看板任务卡片，每个任务包含标题、状态标签、负责人和创建日期。",
|
||
"顶部筛选器可按状态和负责人过滤任务列表。",
|
||
"任务卡片可点击展开/收起详细描述。"
|
||
],
|
||
"usage": [
|
||
"1. 使用顶部筛选器（All Status / All）缩小任务范围",
|
||
"2. 点击任务卡片展开详情（支持 multi-line 描述）",
|
||
"3. 状态颜色标识：绿色=Ready、黄色=In Progress、红色=Blocked、灰色=Done",
|
||
"4. 页面每 15s 自动刷新任务列表"
|
||
],
|
||
"troubleshooting": [
|
||
"如果任务列表为空：检查 Hermes kanban.db 是否存在（~/.hermes/kanban.db）",
|
||
"如果筛选器无反应：页面自动刷新后会重置筛选状态 — 请确保在刷新间隔内操作"
|
||
],
|
||
"related": "G 规范定义开发流程和任务管理规范；Agent 处理卡片流程见 docs/KANBAN-HANDLER-PROTOCOL.md"
|
||
},
|
||
|
||
"ai_spec": {
|
||
"service_ports": [
|
||
{"port": 9580, "service": "kanban_api.py", "host": "0.0.0.0", "purpose": "跨机器 Agent 完整读写 API（直接操作 ~/.hermes/kanban.db）"},
|
||
{"port": 5803, "service": "dashboard.py", "host": "246", "purpose": "Dashboard Kanban tab 只读展示"}
|
||
],
|
||
"apis": [
|
||
{"method": "GET", "path": "/api/kanban", "port": 5803, "returns": "{ok, tasks[{id,title,body,status,assignee,created_at}]}", "description": "Dashboard 只读：返回全部任务列表"},
|
||
{"method": "POST", "path": "/kanban/create", "port": 9580, "returns": "{ok, task_id, raw}", "description": "创建卡片 (title 必填, assignee/body 可选)"},
|
||
{"method": "POST", "path": "/kanban/create_xmpp", "port": 9580, "returns": "{ok, task_id, notified}", "description": "创建卡片并 XMPP 通知核心群 (coregroup@conference.yoin.fun)"},
|
||
{"method": "POST", "path": "/kanban/list", "port": 9580, "returns": "{tasks[]}", "description": "列表 (可选 status/assignee 筛选)"},
|
||
{"method": "POST", "path": "/kanban/show", "port": 9580, "returns": "{id,title,body,status,assignee,created_by,created_at}", "description": "单卡详情"},
|
||
{"method": "POST", "path": "/kanban/update", "port": 9580, "returns": "{ok}", "description": "更新 status/assignee (id 必填)"},
|
||
{"method": "POST", "path": "/kanban/comment", "port": 9580, "returns": "{ok}", "description": "评论卡片 (id/body 必填, author 可选) + XMPP 通知"},
|
||
{"method": "POST", "path": "/kanban/comments", "port": 9580, "returns": "{comments[]}", "description": "读某卡片评论 (id 必填)"}
|
||
],
|
||
"dependencies": [
|
||
"看板数据存于 ~/.hermes/kanban.db (SQLite, 表: tasks / task_comments)",
|
||
"dashboard.py 直接读同一 kanban.db 做只读展示",
|
||
"kanban_api.py 的 create/comment 通过 hermes CLI 或 XMPP 桥 (127.0.0.1:5804) 通知核心群"
|
||
],
|
||
"constraints": [
|
||
"页面每 15s 轮询刷新 (setInterval(fK,15000))",
|
||
"筛选器状态通过 DOM 直接读取 (document.getElementById)",
|
||
"任务卡片展开使用 onclick 切换 expanded class — max-height 从 60px ↔ none 切换",
|
||
"Agent 处理卡片：拉详情用 POST /kanban/show（不是 GET /api/kanban/t_xxx，该端点不存在）",
|
||
"kanban_api.py 全部端点均为 POST（含 list/show/comments 这类读操作）"
|
||
],
|
||
"tests": [
|
||
{"id": "KB01", "name": "/api/kanban 返回任务列表", "endpoint": "GET /api/kanban (:5803)"},
|
||
{"id": "KB02", "name": "筛选器过滤正确", "endpoint": "n/a (frontend)"},
|
||
{"id": "KB03", "name": "kanban_api 创建任务", "endpoint": "POST /kanban/create (:9580)"},
|
||
{"id": "KB04", "name": "kanban_api 更新状态", "endpoint": "POST /kanban/update (:9580)"},
|
||
{"id": "KB05", "name": "kanban_api 评论", "endpoint": "POST /kanban/comment (:9580)"}
|
||
],
|
||
"related_files": [
|
||
"scripts/kanban_api.py — :9580 完整读写 API",
|
||
"gateway/scripts/templates/dashboard.html — fK() 渲染函数",
|
||
"gateway/scripts/dashboard.py — /api/kanban 只读端点",
|
||
"gateway/scripts/specs/kanban.json — 本 spec 文件",
|
||
"docs/KANBAN-HANDLER-PROTOCOL.md — Agent 处理卡片协议",
|
||
"skills/kanban-handler/SKILL.md — handler session 工作流"
|
||
]
|
||
}
|
||
}
|