AgentsMeeting/gateway/scripts/specs/xmpp_watchdog.json

{
  "module": "xmpp_watchdog",
  "version": "2.0",
  "purpose": "多服务看门狗 — 每 30s 轮询监控 xmpp_agent_core + article_processor 等核心服务，检测进程存活 + 端口监听 + HTTP 健康端点，自动重启崩溃服务并执行日志轮转。PID 锁防重复，日志自动 rotate（5MB 阈值）。",
  "ui_location": "F 健康 tab → 全部服务 → 'watchdog' 行 + 定时任务",

  "human_help": {
    "title": "Watchdog — 多服务看门狗",
    "description": [
      "xmpp_watchdog.py 是多服务看门狗，监控 Windows 上运行的核心服务（xmpp_agent_core / article_processor），每 30 秒检查一次，发现崩溃自动重启。",
      "三重检测：① 进程存活（tasklist 查 PID）② 端口监听（netstat -ano 查 LISTENING）③ HTTP 健康端点（GET /health 查返回）。任一层失败即触发重启。",
      "日志轮转：每 15 分钟自动 rotate 所有被监控服务的日志文件（5MB 阈值），防止磁盘占满。",
      "服务定义：从 service_registry.py 读取 SERVICES 列表，配置灵活。当前配置监控 xmpp_agent_core (:5807) 和 article_processor (:5810)。"
    ],
    "usage": [
      "1. 启动: python xmpp_watchdog.py（后台进程，无控制台窗口）",
      "2. 自动发现: 遍历 SERVICES 列表，检查现有 PID/端口，不存在则自动启动",
      "3. 循环监控: 每 30s 检查进程+端口+HTTP 三方健康",
      "4. 状态报告: 每 5 分钟输出一次所有服务状态摘要",
      "5. 日志位置: gateway/logs/watchdog.log",
      "6. PID 文件: gateway/temp/.multi_watchdog.pid"
    ],
    "troubleshooting": [
      "如果看门狗不启动: 检查 PID 锁 — 删除 temp/.multi_watchdog.pid",
      "如果某服务反复重启: 看 watchdog.log 了解具体失败原因（HTTP 超时/端口不监听/进程崩溃）",
      "如果误杀服务: 401/403 HTTP 响应被当作服务正常（auth required = 服务活着），只有连接拒绝或超时才触发重启",
      "如果日志未轮转: 检查文件大小是否超过 5MB 阈值，文件权限是否正常"
    ]
  },

  "ai_spec": {
    "apis": [
      {"method": "N/A", "path": "内部监控循环 (30s)", "returns": "状态日志 + 自动重启", "note": "无外部 HTTP API — 纯监控进程"},
      {"method": "HTTP call", "path": "各服务的 /health 端点", "returns": "status 200 + JSON body", "note": "通过 urllib 调用各被监控服务的健康端点"}
    ],
    "dependencies": [
      "service_registry.py — SERVICES 列表定义（每个服务的 script/args/workdir/pid_file/port/health_url/log_files）",
      "proc_guard.py — PID 锁（间接使用，被监控服务各自也有）",
      "Python 3.10 (C:\\Users\\hmo\\AppData\\Local\\Programs\\Python\\Python310\\python.exe)",
      "Windows tasklist + netstat + wmic — 底层进程/端口检测工具",
      "被监控服务的 /health HTTP 端点 — URL 由 service_registry 配置"
    ],
    "architecture": {
      "flow": "启动 → 遍历 SERVICES → 检查现有 PID/端口 → 不存在则 start_service() → 主循环: 30s sleep → check_service() → 不健康则 restart",
      "detection_layers": [
        "Layer 1: tasklist /FI 'PID eq N' — 进程存活检测",
        "Layer 2: netstat -ano — 端口监听检测",
        "Layer 3: urllib GET /health — HTTP 健康端点检测",
        "401/403 special: HTTP auth 错误 ≠ 服务挂了 — 服务活着但需要认证"
      ],
      "restart_flow": "kill_service (taskkill all matching cmdlines) → sleep 3s → subprocess.Popen(script + args) → 写 PID 文件 → sleep 5s → 验证",
      "log_rotation": "每15分钟检查 — 单个日志 >5MB → 保留 .1 和 .2 两个历史备份",
      "health_grace": "401/403 响应当做服务正常 — 只有连接拒绝/超时/非200才重启",
      "multi_service": "所有服务在同一个 while True 循环中并行监控 — 一个挂了不影响其他"
    },
    "constraints": [
      "必须从 service_registry.py 读取服务定义 — 不要硬编码服务列表",
      "PID 锁文件路径由 service_registry 配置 — watchdog 本身用 .multi_watchdog.pid",
      "日志轮转阈值 5MB — 保留 .1 和 .2 两个备份文件再覆盖",
      "kill_service 使用 wmic 查 command line — 避免杀错同名进程",
      "状态报告间隔: 10个循环 (5min) 或 any_restart 触发"
    ],
    "must_not": [
      "不要修改 service_registry.SERVICES 而不更新 watchdog 的 SERVICES 字典",
      "不要用 tasklist 直接查进程名杀进程 — 必须通过 wmic 验证 command line 包含正确的脚本名",
      "不要同时运行两个 watchdog 实例 — PID 锁保证互斥"
    ],
    "related_modules": [
      {"module": "health", "relation": "watchdog 在 F 健康 tab 的 '全部服务' 中显示为 'watchdog' 行"},
      {"module": "dashboard", "relation": "dashboard 的 F 健康 tab 通过 /api/expected 检查 watchdog 进程是否存在"},
      {"module": "health_service", "relation": "health_service 专注监控 xmpp_bot，watchdog 监控更广泛的服务集合"},
      {"module": "api_proxy", "relation": "watchdog 也可能监控 api_proxy 服务 —— 在 service_registry 中配置"}
    ],
    "tests": [
      {"id": "WD01", "name": "进程存活检测正确", "endpoint": "is_process_alive: tasklist 查已知 PID → 返回 True"},
      {"id": "WD02", "name": "端口监听检测正确", "endpoint": "netstat -ano 查已知端口 → 检查 LISTENING"},
      {"id": "WD03", "name": "HTTP 健康检查正确处理 401", "endpoint": "GET /health 返回 401 → 不触发重启"},
      {"id": "WD04", "name": "挂掉的服务被重启", "endpoint": "手动 kill 某服务 → 30s 内 watchdog 应检测并重启"},
      {"id": "WD05", "name": "日志轮转触发", "endpoint": "日志文件 >5MB → 生成 .1 和 .2 备份"}
    ],
    "known_issues": [
      "wmic 命令在 Windows 11 可能已废弃 — 未来需切换到 Get-CimInstance 或 PowerShell",
      "kill_service 依赖准确的 script_match 字符串 — 如果脚本名变更但未更新 service_registry，会杀错进程",
      "watchdog 本身挂了的话没有其他进程监控它 — 这是一个鸡蛋问题（health_service 部分覆盖 xmpp_bot 监控）"
    ],
    "related_files": [
      "gateway/scripts/xmpp_watchdog.py — 本文件 (264行)",
      "gateway/scripts/service_registry.py — SERVICES 列表定义",
      "gateway/scripts/proc_guard.py — PID 锁（被各监控服务使用）",
      "gateway/scripts/specs/xmpp_watchdog.json — 本 spec",
      "gateway/logs/watchdog.log — 看门狗日志",
      "gateway/temp/.multi_watchdog.pid — PID 锁文件"
    ]
  }
}