{
  "module": "xmpp_monitor",
  "version": "1.0",
  "purpose": "XMPP 通信通道全链路可观测性。记录消息收发日志、LLM 调用追踪、异常检测与自动修复。",

  "human_help": {
    "title": "XMPP 通信监控",
    "description": [
      "实时监控 MoFin 的 XMPP 通信通道健康状态。",
      "追踪范围：知微 Bot ↔ XMPP 群聊、cron 报告推送、市场扫描推送、策略通知。",
      "当消息流中断或异常时，Dashboard 自动告警并展示失败原因。"
    ],
    "usage": [
      "Dashboard 📊 仪表盘 → 查看消息流实时状态",
      "Dashboard 🏥 健康 → 查看 XMPP 通道健康指标（最后消息时间、错误率）",
      "GET /api/xmpp/messages — 查询消息历史（支持按时间/Agent/状态筛选）",
      "GET /api/xmpp/health — XMPP 通道健康检查"
    ],
    "troubleshooting": [
      "消息推送失败 → 查看 xmpp_messages.jsonl 中的错误信息",
      "ejabberd 挂了 → Dashboard 自动检测，手动 docker restart ejabberd",
      "知微 Bot 离线 → 检查 systemctl status xmpp-zhiwei"
    ]
  },

  "ai_spec": {
    "apis": [
      {"method": "GET", "path": "/api/xmpp/messages", "returns": "{messages[{timestamp, direction, from, to, body_preview, status, error, latency_ms}], total} — 支持 ?since=&agent=&status=&limit=50 参数"},
      {"method": "GET", "path": "/api/xmpp/health", "returns": "{status, last_message_age_sec, error_rate_1h, queue_depth, ejabberd_status}"},
      {"method": "GET", "path": "/api/xmpp/stats", "returns": "{today{sent, failed, latency_avg}, week{sent, failed}}"}
    ],
    "dependencies": [
      "xmpp_logger.py — 消息日志采集（写入 gateway/logs/xmpp_messages.jsonl）",
      "ejabberd Docker 容器 — XMPP 服务器（:5222）",
      "cron_to_xmpp.py — 报告推送到 XMPP（send 函数写入 xmpp_logger）",
      "market_scanner.py — 选股结果推送 XMPP（:5805）",
      "知微 Bot — xmpp-zhiwei systemd 服务"
    ],
    "architecture": {
      "log_format": "JSONL, 每行一条: {timestamp, direction(in/out), from_jid, to_jid, body_preview(前100字), status(ok/error/timeout), error, latency_ms}",
      "health_checks": [
        "最后消息年龄 >10min → 🔴 告警",
        "最近1小时错误率 >50% → 🟡 告警",
        "ejabberd 容器不在运行 → 🔴 严重",
        "知微 Bot 进程不在 → 🔴 严重"
      ]
    },
    "constraints": [
      "xmpp_logger.py 通过 hook 方式接入 cron_to_xmpp.send()，不动现有业务逻辑",
      "消息日志保留最近 7 天，自动轮转",
      "Dashboard 每 10 秒自动刷新消息流",
      "错误信息脱敏：不记录完整消息体，只记录前 100 字预览"
    ],
    "must_not": [
      "不要在消息日志中记录 API Key 或密码",
      "不要修改 cron_to_xmpp.py 的业务逻辑（只加 hook）",
      "不要在 xmpp_monitor 中重复实现已有的 system_health_check 逻辑"
    ],
    "tests": [
      {"id": "XM01", "name": "/api/xmpp/health 返回 ejabberd 状态", "endpoint": "GET /api/xmpp/health"},
      {"id": "XM02", "name": "/api/xmpp/messages 返回消息列表", "endpoint": "GET /api/xmpp/messages"},
      {"id": "XM03", "name": "xmpp_logger 写入 JSONL 格式正确", "endpoint": "file check"}
    ],
    "related_files": [
      "xmpp_logger.py — 消息日志采集",
      "cron_to_xmpp.py — 报告推送（send 函数）",
      "scripts/market_scanner.py — 选股推送",
      "server.py — /api/xmpp/* 端点",
      "agents_health_check.py — Tier1 健康检查（含 XMPP 检测）"
    ]
  }
}