{
  "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 文件"
    ]
  }
}
