feat: XMPP observability — logger, monitor endpoints, clean dead xiaoguo refs

specs/scanner.json

@@ -0,0 +1,56 @@
+{
+  "module": "scanner",
+  "version": "1.0",
+  "purpose": "全市场自动选股机制。纯数据驱动（不依赖 LLM），定期从 A 股热门板块筛选符合条件的候选股。",
+
+  "human_help": {
+    "title": "全市场选股扫描",
+    "description": [
+      "自动化选股管线，每 15 分钟运行一次。纯数据驱动，不依赖外部 LLM。",
+      "流程：读热门板块 → 拉腾讯实时行情 → 涨幅>3%+有量 → 评分 → 写入 candidates 表 → 高分推送 XMPP。",
+      "候选股在 Dashboard 市场 Tab 的「主力建仓候选」面板展示。"
+    ],
+    "usage": [
+      "Dashboard 市场 Tab → 🎯 主力建仓候选 → 查看最近 50 只候选股",
+      "Dashboard 信号 Tab → 查看全市场扫描统计",
+      "cron: market_scanner.py（每 15 分钟，交易日 9-15）"
+    ],
+    "troubleshooting": [
+      "候选池为空 → 检查 market_scanner.py cron 是否运行，sector_snapshots 表是否有数据",
+      "行情不更新 → 检查腾讯行情 API 是否可达（qt.gtimg.cn）"
+    ]
+  },
+
+  "ai_spec": {
+    "apis": [
+      {"method": "GET", "path": "/api/candidates", "returns": "[{code, name, reason, score_2nd..score_5th, score_final, pass_s2..pass_s5, promoted, promoted_at, log, created_at}] — 最近 50 只候选股"}
+    ],
+    "dependencies": [
+      "market_scanner.py — 选股主脚本（cron: */15 9-15 1-5）",
+      "mofin_db.py — candidates 表（code, name, price, change_pct, score, entry_low, entry_high, stop_loss, take_profit, source, sector, reason）",
+      "market_watch.py — 提供 sector_snapshots 板块数据",
+      "腾讯行情 API: http://qt.gtimg.cn/q="
+    ],
+    "architecture": {
+      "pipeline": "sector_snapshots → market_scanner.scan_hot_sectors() → 腾讯行情 → 过滤(涨>3%+有量) → 评分 → candidates 表 → XMPP 推送(高分)",
+      "scoring": "score = min(10, round(3 + change% * 0.5 + (amount/1e8) * 0.1))"
+    },
+    "constraints": [
+      "纯数据驱动，不调 LLM（区别于旧 xiaoguo_scanner 和 market_screener）",
+      "只扫描 A 股（6 位代码以 5/6/9 开头）",
+      "板块涨幅 >2% 才纳入热门板块",
+      "个股涨幅 >3% 才进入候选",
+      "高分候选(score>=6)推送到 XMPP（知微 bot :5805）"
+    ],
+    "must_not": [
+      "不要调小果 LLM API（node122:18003）",
+      "不要写 candidate_pool.json（旧格式，已废弃）"
+    ],
+    "related_files": [
+      "scripts/market_scanner.py — 选股脚本",
+      "server.py — /api/candidates",
+      "mofin_db.py — candidates 表",
+      "market_watch.py — 板块数据源"
+    ]
+  }
+}

specs/signals.json

@@ -1,43 +1,49 @@
 {
   "module": "signals",
   "version": "1.0",
-  "purpose": "信号与扫描数据。提供市场信号查询和小果扫描统计。",
+  "purpose": "信号数据。提供市场信号查询，数据来自趋势检测（macro_context_collector/divergence_detector）和全市场扫描（market_scanner）。",
 
   "human_help": {
     "title": "信号与扫描",
     "description": [
-      "展示系统产生的交易信号和小果 LLM 扫描结果。",
-      "信号来自多个来源：xiaoguo_scanner（全市场）、macro_context_collector（宏观）、divergence_detector（背离）。",
-      "所有信号存储在 signal_news 表中。"
+      "展示系统产生的交易信号，包括趋势检测信号和全市场扫描候选股。",
+      "趋势信号来自 macro_context_collector（宏观）和 divergence_detector（背离检测）。",
+      "全市场扫描由 market_scanner.py 纯数据驱动（不依赖 LLM），每 15 分钟从热门板块筛选候选股。",
+      "所有信号存储在 signal_news 表中，候选股存储在 candidates 表中。"
     ],
     "usage": [
-      "GET /api/signals — 获取最近 20 条信号（含板块信号关联）",
-      "GET /api/xiaoguo-scan — 获取小果扫描统计（扫描总数/发现信号数/近期记录/今日来源分布）"
+      "GET /api/signals — 获取最近 20 条信号（含趋势和扫描信号）",
+      "GET /api/candidates — 获取候选股池（最近 50 只，市场扫描产出）"
     ],
     "troubleshooting": [
-      "信号为空 → 检查 xiaoguo_scanner 和 macro_context_collector cron 状态",
-      "小果扫描数据停更 → 检查小果 LLM API 是否可达"
+      "信号为空 → 检查 macro_context_collector 和 market_scanner cron 状态",
+      "候选池为空 → 确认 sector_snapshots 有数据，market_scanner cron 在运行"
     ]
   },
 
   "ai_spec": {
     "apis": [
       {"method": "GET", "path": "/api/signals", "returns": "[{id, sector, overall_sentiment, summary, source, created_at, signal_type, severity}] — 最近 20 条信号"},
-      {"method": "GET", "path": "/api/xiaoguo-scan", "returns": "{total_scanned, found_signals, recent[{code, name, last_scanned_at, found_count}], source_today{source:cnt}}"}
+      {"method": "GET", "path": "/api/candidates", "returns": "[{code, name, reason, score_2nd..score_5th, score_final, pass_s2..pass_s5, promoted, log, created_at}] — 候选股池（由 market_scanner 产出）"}
     ],
     "dependencies": [
-      "mofin_db.py — signal_news / xiaoguo_scan_tracker 表",
-      "xiaoguo_scanner.py — 全市场扫描 cron（*/5 9-15）",
+      "mofin_db.py — signal_news / candidates 表",
       "macro_context_collector.py — 宏观信号采集 cron",
-      "divergence_detector.py — 背离检测 cron"
+      "divergence_detector.py — 背离检测 cron",
+      "scripts/market_scanner.py — 全市场扫描 cron（*/15 9-15 1-5，纯数据驱动）"
     ],
     "constraints": [
       "signal_news 和 sector_signals 通过 LEFT JOIN 关联",
-      "xiaoguo_scan_tracker 的 source 统计只取最近 24 小时"
+      "candidates 表由 market_scanner 写入，纯数据驱动不调 LLM",
+      "旧 xiaoguo_scanner 已废弃，不再使用"
+    ],
+    "must_not": [
+      "不要调小果 LLM API",
+      "不要依赖 xiaoguo_scan_tracker 表（已废弃）"
     ],
     "related_files": [
-      "server.py — /api/signals, /api/xiaoguo-scan",
-      "xiaoguo_scanner.py",
+      "server.py — /api/signals, /api/candidates",
+      "scripts/market_scanner.py — 全市场扫描",
       "macro_context_collector.py"
     ]
   }

specs/xmpp_monitor.json

@@ -0,0 +1,72 @@
+{
+  "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 检测）"
+    ]
+  }
+}