{
  "module": "health_service",
  "version": "2.0",
  "purpose": "Windows Service — xxm Bot Health Monitor。替代 Task Scheduler 方式的 health_check_xxm.py，通过 HTTP health check (GET :5807/health) 监控 xmpp bot 状态，自动重启失败的 bot。作为 Windows 服务运行（services.msc 管理），零控制台窗口。",
  "ui_location": "F 健康 tab → 定时任务区域 → agents-health-check",

  "human_help": {
    "title": "xxm Bot Health Service — Windows 健康监控",
    "description": [
      "health_service.py 是一个 Windows Service，替代旧的 Task Scheduler 调度方式。它通过 HTTP 健康检查监控 xmpp bot（端口 5807），当检测到 bot 不健康时自动重启它。",
      "与旧 health_check_xxm.py 的区别：① 零控制台窗口（纯 Windows Service）② 无 WMIC/tasklist 轮询，纯 HTTP 检查 ③ 通过 services.msc 统一管理 ④ PID 锁防重复。",
      "健康检查：每 30s 向 127.0.0.1:5807/health 发 GET 请求，检查 xmpp_connected 字段。如果请求失败或 xmpp_connected=false，触发重启。",
      "重启流程：用存储的 PID 杀旧进程 → 等 3s → subprocess.Popen 启动新 bot → 等 5s → 验证健康。"
    ],
    "usage": [
      "1. 安装: python health_service.py install（需要 Admin 权限）",
      "2. 启动: python health_service.py start 或 net start xxm-health",
      "3. 停止: python health_service.py stop 或 net stop xxm-health",
      "4. 管理: services.msc → 找到 'AgentsMeeting xxm Health Service' → 启停/禁用",
      "5. 卸载: python health_service.py remove",
      "6. 日志位置: gateway/logs/health_service.log"
    ],
    "troubleshooting": [
      "如果服务无法启动: 检查是否已有实例在运行（proc_guard PID 锁）→ 删除 temp/.health_service_xxm.pid",
      "如果 bot 反复重启: 检查 5807 端口健康端点是否可访问 — curl http://127.0.0.1:5807/health?key=xxm_bridge_8f3a2c",
      "如果服务安装失败: 确保以 Admin 身份运行 + win32serviceutil 已安装 (pywin32)",
      "如果日志为空: 检查 gateway/logs/health_service.log 文件权限",
      "端口从 5802 改为 5807: xmpp_bot HTTP bridge 独立运行在 5802，xxm bot health 在 5807"
    ]
  },

  "ai_spec": {
    "apis": [
      {"method": "GET", "path": "http://127.0.0.1:5807/health?key=<BRIDGE_KEY>", "returns": "JSON — xmpp_connected 字段", "note": "被监控端 — xmpp_agent_core.py 的 /health 端点"},
      {"method": "N/A (Windows Service CLI)", "path": "python health_service.py install|start|stop|remove", "returns": "Service 安装/启停", "note": "win32serviceutil.HandleCommandLine"}
    ],
    "dependencies": [
      "pywin32 (win32serviceutil, win32service, win32event, servicemanager) — Windows Service 框架",
      "Python 3.10 (C:\\Users\\hmo\\AppData\\Local\\Programs\\Python\\Python310\\python.exe)",
      "xmpp_agent_core.py — 被监控的 bot 脚本 (启动参数: --agent xxm)",
      "proc_guard.py — PID 锁 (guard('health_service_xxm'))",
      "xmpp_bot HTTP bridge (:5807) — health 端点 (通过 xmpp_agent_core.py 的 /health)"
    ],
    "architecture": {
      "flow": "Windows Service 启动 → proc_guard 锁 → 初始健康检查 → 30s 循环: WaitForSingleObject(30s) → HTTP 检查 5807/health → 不健康则 _restart_bot()",
      "restart_flow": "taskkill /f /pid <旧PID> → sleep 3s → subprocess.Popen(python xmpp_agent_core.py --agent xxm) → sleep 5s → 验证健康",
      "health_check": "urllib GET:5807/health?key=<BRIDGE_KEY> → 解析 JSON → 检查 xmpp_connected 字段",
      "pid_lock": "guard('health_service_xxm') — 确保只有一个 health_service 实例在运行",
      "port_change": "5802 → 5807 — xmpp_bot HTTP bridge 独立占用 5802，xxm bot health 移到 5807"
    },
    "constraints": [
      "必须是 Windows Service — 不能在 Linux 上运行（依赖 pywin32）",
      "必须以 Admin 权限安装/启动 — win32serviceutil 需要",
      "PID 锁名称固定为 'health_service_xxm' — 不要与 xmpp_bot 的 'xmpp_bot' 锁冲突",
      "BRIDGE_KEY 与 dashboard 的 _BRIDGE_KEY 必须一致",
      "bot 启动使用 CREATE_NO_WINDOW flag — 不弹出控制台窗口",
      "stdout/stderr 重定向到 DEVNULL — 所有输出通过 logging 记录"
    ],
    "must_not": [
      "不要用 tasklist/WMIC 轮询进程 — 改用 HTTP health check 替代",
      "不要修改 _BRIDGE_API_KEY 而不同步到 dashboard.py 和 xmpp_agent_core.py",
      "不要让 PID 锁与 xmpp_bot 或 watchdog 冲突 — 各用各的 guard name"
    ],
    "related_modules": [
      {"module": "dashboard", "relation": "dashboard 的 F 健康 tab 检查 health_service 的定时任务状态"},
      {"module": "health", "relation": "health_service 是 F 健康 tab 中 'agents-health-check' 定时任务的实际实现"},
      {"module": "xmpp_bot", "relation": "health_service 监控的 xmpp_bot 是 Windows XMPP 通信的核心"}
    ],
    "tests": [
      {"id": "HS01", "name": "健康端点可访问", "endpoint": "GET :5807/health → xmpp_connected 字段存在"},
      {"id": "HS02", "name": "服务安装成功", "endpoint": "python health_service.py install → 在 services.msc 中可见"},
      {"id": "HS03", "name": "PID 锁防重复", "endpoint": "两次启动 health_service → 第二次应被 proc_guard 拦截"},
      {"id": "HS04", "name": "不健康时自动重启", "endpoint": "手动杀 bot 进程 → 30s 内 health_service 应检测到并重启"}
    ],
    "known_issues": [
      "pywin32 依赖 — Python 3.10 需预先安装 pip install pywin32",
      "端口 5807 vs 5802 混乱 — xmpp_bot.py (独立 slixmpp bot) 用 5802，xmpp_agent_core.py (统一 core) 的 /health 在 5807",
      "仅 Windows 可用 — Linux 上 bot 健康由 systemd 管理的 watchdog 负责"
    ],
    "related_files": [
      "gateway/scripts/health_service.py — 本文件 (187行)",
      "gateway/scripts/proc_guard.py — PID 锁",
      "gateway/scripts/xmpp_agent_core.py — 被监控的 bot 核心 (项目根目录)",
      "gateway/scripts/specs/health_service.json — 本 spec",
      "gateway/logs/health_service.log — 服务日志"
    ]
  }
}
