73 lines
3.6 KiB
JSON
73 lines
3.6 KiB
JSON
{
|
||
"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 检测）"
|
||
]
|
||
}
|
||
}
|