89 lines
6.1 KiB
JSON
89 lines
6.1 KiB
JSON
{
|
||
"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 — 服务日志"
|
||
]
|
||
}
|
||
}
|