feat: add module spec files for agents, kanban, infra tabs

gateway/scripts/specs/agents.json

@@ -0,0 +1,55 @@
+{
+  "module": "agents",
+  "version": "1.0",
+  "purpose": "Dashboard 'Agents' tab 展示所有注册 Agent 的在线状态、消息流量、服务列表和实时日志，支持远程启停操作。",
+  "ui_location": "主菜单 → Agents tab",
+
+  "human_help": {
+    "title": "Agents 总览",
+    "description": [
+      "本页面展示系统中所有注册 Agent 的实时状态。每个 Agent 卡片包含在线状态、消息速率（msg/5m）、运行平台，以及 Start/Stop/Restart 操作按钮。",
+      "Agent 卡片展开后可以查看其运行的服务列表和实时日志。",
+      "顶部概要卡片显示在线数/错误数/总数。"
+    ],
+    "usage": [
+      "1. 查看顶部概要卡片了解整体运行状态",
+      "2. 点击 Agent 卡片展开/收起服务和日志区域",
+      "3. 使用 Start/Stop/Restart 按钮管理 Agent 进程",
+      "4. 点击 Logs 查看实时日志（最近 50 行）"
+    ],
+    "troubleshooting": [
+      "如果 Agent 状态刷新慢：页面每 10s 自动刷新一次",
+      "如果 Start 按钮不可用：该 Agent 可能不支持远程启动，或已在运行中",
+      "如果 Agent 掉线：检查对应机器的网络和进程状态"
+    ],
+    "related": "F 健康 tab 查看系统整体服务健康状态，K 测试 tab 有各模块的细化测试"
+  },
+
+  "ai_spec": {
+    "apis": [
+      {"method": "GET", "path": "/api/agents", "returns": "[{id,name,display_name,jid,status,platform,host,message_count_5min,errors,restartable,services}] — 所有 Agent 详细状态"},
+      {"method": "POST", "path": "/api/agents/{id}/{action}", "params": "action=start|stop|restart", "returns": "{ok}"},
+      {"method": "GET", "path": "/api/agents/{id}/logs", "params": "lines=N", "returns": "{ok, lines[]}"}
+    ],
+    "dependencies": [
+      "dashboard.py 通过 /api/agents 端点聚合各 Agent 状态",
+      "Agent 启停操作依赖远程 SSH 或 systemd 权限",
+      "日志功能依赖 Agent 所在机器的日志文件访问"
+    ],
+    "constraints": [
+      "message_count_5min 是滑动窗口计数，页面每 5s 轮询刷新",
+      "agent 卡片使用 create-once/update-state pattern — 首渲染后只更新 class 和文本",
+      "日志区域使用 tgL() 切换展开/收起，fL() 加载内容"
+    ],
+    "tests": [
+      {"id": "AG01", "name": "/api/agents 返回所有 Agent 列表", "endpoint": "GET /api/agents"},
+      {"id": "AG02", "name": "Agent 启停操作返回正确状态", "endpoint": "POST /api/agents/{id}/start|stop|restart"},
+      {"id": "AG03", "name": "Agent 日志加载正常", "endpoint": "GET /api/agents/{id}/logs?lines=50"}
+    ],
+    "related_files": [
+      "gateway/scripts/templates/dashboard.html — fa() 渲染函数",
+      "gateway/scripts/dashboard.py — /api/agents 端点",
+      "gateway/scripts/specs/agents.json — 本 spec 文件"
+    ]
+  }
+}

gateway/scripts/specs/infra.json

@@ -0,0 +1,73 @@
+{
+  "module": "infra",
+  "version": "1.0",
+  "purpose": "Dashboard 'Infrastructure' tab 展示基础设施状态：Platform 进程、Ejabberd XMPP 服务、EasyTier VPN、RDP 远程桌面隧道、OpenCode Go 用量监控。",
+  "ui_location": "主菜单 → Infrastructure tab",
+
+  "human_help": {
+    "title": "Infrastructure 总览",
+    "description": [
+      "本页面展示系统基础设施的运行状态，分为多个区域：",
+      "• Platform — Windows/Linux 平台基础进程状态",
+      "• Ejabberd — XMPP 服务器心跳",
+      "• EasyTier VPN — P2P VPN 内网开关（连接两台机器）",
+      "• RDP Remote Desktop — SSH 反向隧道远程桌面",
+      "• OpenCode Go Usage — 四个订阅账号的 API 用量监控"
+    ],
+    "usage": [
+      "1. 检查 Platform 和 Ejabberd 的基础运行状态",
+      "2. EasyTier: 先 Turn On 建立 VPN 连接，确认 Connected 后再操作 RDP",
+      "3. RDP: Enable 启动 SSH 反向隧道，Disable 关闭",
+      "4. Usage: 查看各账号用量，点击 Refresh Now 手动采集最新数据"
+    ],
+    "troubleshooting": [
+      "EasyTier 和 RDP 有依赖关系 — RDP 需 EasyTier 先 Connected",
+      "Usage 数据自动每 30min 采集一次，也可手动 Refresh",
+      "如果某个区域一直 loading：检查对应后端 API 是否正常"
+    ],
+    "related": "F 健康 tab 查看服务级健康状态"
+  },
+
+  "ai_spec": {
+    "apis": [
+      {"method": "GET", "path": "/api/platform", "returns": "[{name,status}] — 平台进程状态"},
+      {"method": "GET", "path": "/api/ejabberd", "returns": "{alive, xmpp_bot_connected} — XMPP 服务器心跳"},
+      {"method": "GET", "path": "/api/easytier", "returns": "{status:{windows,246}, virtual_ips:{windows,246}}"},
+      {"method": "POST", "path": "/api/easytier/toggle", "body": "{action:start|stop}"},
+      {"method": "GET", "path": "/api/rdp", "returns": "{rdp_enabled, tunnel_running, public_endpoint}"},
+      {"method": "POST", "path": "/api/rdp/toggle", "body": "{action:start|stop}"},
+      {"method": "GET", "path": "/api/usage", "returns": "{ok, accounts[{name,usage,limit}], last_refresh}"},
+      {"method": "POST", "path": "/api/usage/refresh", "returns": "{ok}"}
+    ],
+    "dependencies": [
+      "EasyTier/RDP 依赖 xmpp_bot 的 HTTP bridge (Windows:5807)",
+      "Usage 依赖 CDP proxy 在 Chrome tab 内执行 fetch",
+      "Platform 状态通过 subprocess 本地检测"
+    ],
+    "constraints": [
+      "fI() 使用 create-once/update-state pattern — DOM 元素只创建一次，后续只更新 class/text",
+      "Platform 和 Ejabberd 部分在 stable wrapper (<div id=infra-pe>) 中全量重渲染",
+      "EasyTier/RDP/Usage section 各自独立创建，互不影响",
+      "Usage 数据采集后 10-15s 自动刷新"
+    ],
+    "must_not": [
+      "不要把 fI() 改成全量重渲染 — 会破坏 create-once pattern 导致 EasyTier/RDP 元素闪烁",
+      "不要删除 infra-pe wrapper — Platform 和 Ejabberd 内容全量重渲染，其他 section 增量更新"
+    ],
+    "tests": [
+      {"id": "IN01", "name": "Platform 状态正常返回", "endpoint": "GET /api/platform"},
+      {"id": "IN02", "name": "Ejabberd 心跳正常", "endpoint": "GET /api/ejabberd"},
+      {"id": "IN03", "name": "EasyTier toggle 操作正常", "endpoint": "POST /api/easytier/toggle"},
+      {"id": "IN04", "name": "RDP toggle 操作正常", "endpoint": "POST /api/rdp/toggle"},
+      {"id": "IN05", "name": "Usage 数据正常采集和展示", "endpoint": "GET /api/usage"}
+    ],
+    "related_files": [
+      "gateway/scripts/templates/dashboard.html — fI() 渲染函数",
+      "gateway/scripts/dashboard.py — 所有 /api/infra* 端点",
+      "gateway/scripts/specs/infra.json — 本 spec 文件",
+      "gateway/scripts/specs/easytier.json — EasyTier 详细 spec",
+      "gateway/scripts/specs/rdp.json — RDP 详细 spec",
+      "gateway/scripts/specs/usage_monitor.json — Usage monitor 详细 spec"
+    ]
+  }
+}

gateway/scripts/specs/kanban.json

@@ -0,0 +1,49 @@
+{
+  "module": "kanban",
+  "version": "1.0",
+  "purpose": "Dashboard 'Kanban' tab 展示看板任务列表，支持按状态(Ready/In Progress/Blocked/Done)和负责人筛选，实时刷新。",
+  "ui_location": "主菜单 → Kanban tab",
+
+  "human_help": {
+    "title": "Kanban 看板",
+    "description": [
+      "本页面展示系统中的看板任务卡片，每个任务包含标题、状态标签、负责人和创建日期。",
+      "顶部筛选器可按状态和负责人过滤任务列表。",
+      "任务卡片可点击展开/收起详细描述。"
+    ],
+    "usage": [
+      "1. 使用顶部筛选器（All Status / All）缩小任务范围",
+      "2. 点击任务卡片展开详情（支持 multi-line 描述）",
+      "3. 状态颜色标识：绿色=Ready、黄色=In Progress、红色=Blocked、灰色=Done",
+      "4. 页面每 15s 自动刷新任务列表"
+    ],
+    "troubleshooting": [
+      "如果任务列表为空：检查 Kanban API 是否正常运行",
+      "如果筛选器无反应：页面自动刷新后会重置筛选状态 — 请确保在刷新间隔内操作"
+    ],
+    "related": "G 规范定义开发流程和任务管理规范"
+  },
+
+  "ai_spec": {
+    "apis": [
+      {"method": "GET", "path": "/api/kanban", "returns": "{ok, tasks[{id,title,body,status,assignee,created_at}]}"}
+    ],
+    "dependencies": [
+      "看板数据由 dashboard.py 从后端 Kanban 服务/数据库获取"
+    ],
+    "constraints": [
+      "页面每 15s 轮询刷新 (setInterval(fK,15000))",
+      "筛选器状态通过 DOM 直接读取 (document.getElementById)",
+      "任务卡片展开使用 onclick 切换 expanded class — max-height 从 60px ↔ none 切换"
+    ],
+    "tests": [
+      {"id": "KB01", "name": "/api/kanban 返回任务列表", "endpoint": "GET /api/kanban"},
+      {"id": "KB02", "name": "筛选器过滤正确", "endpoint": "n/a (frontend)"}
+    ],
+    "related_files": [
+      "gateway/scripts/templates/dashboard.html — fK() 渲染函数",
+      "gateway/scripts/dashboard.py — /api/kanban 端点",
+      "gateway/scripts/specs/kanban.json — 本 spec 文件"
+    ]
+  }
+}