ai-exchange/docs/AI_ICT_盯盘告警技术设计稿_v1.md

AI ICT 盯盘告警技术设计稿 v1

1. 文档目标

本文档基于当前仓库目录，细化“AI 盯盘 + 主动告警”方案需要新增的模块、文件、接口、数据流和落地顺序。

目标不是推翻现有交易主链，而是在当前结构化交易运行时之上补齐：

• 外发消息告警
• 视觉复核
• 截图与证据留存
• 告警回执与人工反馈

2. 当前代码基线

已存在核心模块：

• src/services/runtime/trading_runtime_service.py
• src/services/market_state/market_state_service.py
• src/services/trade_plan_candidates/setup_watcher_service.py
• src/services/trade_plan_candidates/confirmation_service.py
• src/services/decision/decision_packet_service.py
• src/repositories/decision_packet_repository.py
• src/api/server.py
• src/web/app.js

当前系统已经具备：

• runtime 调度
• market truth gate
• active trading plan 生成
• trade plan candidate 生成
• decision packet 构建
• decision alerts 落库
• operator notes

缺口主要在“告警真正发出去”和“高价值时刻的视觉复核”。

3. 设计目标

3.1 本轮新增目标

1. 把 queued alerts 真正发到外部消息通道
2. 给高优先级机会附加截图和视觉摘要
3. 让 dashboard 可查看截图、告警发送结果、视觉结论
4. 支持人工对告警进行反馈标记

3.2 明确不做

1. 不让视觉层替代 candidate 生成
2. 不让视觉层绕过 risk governor
3. 不让视觉层直接自动触发真实下单
4. 不做全时全量高频截图

4. 建议新增目录与文件

以下按当前仓库结构给出建议。

---

4.1 services 层

A. 新增 src/services/alerts/

用途：负责消息编排、分发、模板、重试和发送状态回写。

建议文件：

src/services/alerts/__init__.py

导出告警服务。

src/services/alerts/alert_dispatcher_service.py

核心职责：

• 拉取 decision_alerts 中 status=queued 的记录
• 根据 channel policy 发送
• 回写 delivered / failed / skipped
• 支持冷却时间与重复抑制

建议类：

• AlertDispatcherService
• AlertDispatchResult

建议方法：

• dispatch_pending(limit: int = 50) -> dict
• dispatch_alert(alert_id: int) -> dict
• select_channel(alert: dict) -> str
• should_skip(alert: dict) -> tuple[bool, str]

src/services/alerts/message_template_service.py

职责：把 decision packet / visual summary 组装成用户可读消息。

建议方法：

• build_actionable_message(alert: dict, packet: dict, visual: dict | None) -> str
• build_blocked_message(...) -> str
• build_system_warning_message(...) -> str

src/services/alerts/channel_router_service.py

职责：根据 alert type / priority 决定发送到哪个通道。

例如：

• candidate_actionable -> Telegram + 企业微信
• candidate_blocked -> dashboard only
• runtime_degraded -> Telegram + dashboard

2026-05-12 P19 已落地：当前 channel router 保持现有 workbench/webhook 行为，同时输出结构化 channel_route、channel capability 与 channel health summary。WeCom / Email 已预留为 disabled adapter；凭据缺失时暴露 credential_missing，凭据存在但 adapter 未实现时暴露 adapter_not_implemented，不会把未配置通道伪装为成功发送。dispatcher、delivery summary、runtime 与 workbench 均可查看 per-channel 状态。

src/services/alerts/operator_digest_service.py

职责：把 recent alerts、delivery history、visual reviews、alert/visual feedback 和 alert quality summary 聚合成 operator digest。

2026-05-12 P20 已落地：digest 输出 high-value alerts、suppressed deliveries、failed/retry deliveries、visual mismatches、pending feedback items、quality flags 与 bounded review queue。该服务只做复盘聚合与 operator 可观测性，不改变 execution allowed、real live readiness、risk governor、trust bucket 或 operator confirmation protocol。

src/services/runtime/runtime_incident_journal_service.py

职责：把 runtime status、watchdog、blocker/warning/noisy incident 规范化为可持久化 incident journal。

2026-05-12 P21 已落地：runtime_incidents 使用 incident_key 做去重聚合，并保存 severity、source、reason、subject、first/last seen、occurrence_count、recommended_action 与 payload。GET /trading/runtime-incidents、scripts/run_runtime_incident_journal.py、runtime_status.incident_summary 与 workbench runtime panel 均可查看当前 incident summary；该层只做可观测性与恢复建议，不改变任何交易权限或 operator confirmation protocol。

src/services/maintenance/maintenance_summary_service.py

职责：只读汇总 storage / delivery / feedback / runtime 维护健康状态，为无人值守 harness 提供断言输入。

2026-05-12 P22 已落地：maintenance summary 会 dry-run visual capture retention，读取 alert quality summary、runtime watchdog 与 runtime incident journal，输出 checks、blockers、warnings、maintenance_actions 与 p23_assertions。该 summary 不执行删除；自动清理动作只作为可用 action 暴露，未纳入 retention policy 的业务数据不会被删除。

src/services/maintenance/unattended_harness_service.py

职责：把 P15-P22 的自动化执行层关键能力聚合成可一条命令运行的 unattended smoke harness。

2026-05-12 P23 已落地：unattended harness 以 analysis/decision-only 模式验证 policy suppression、dispatch retry contract、runtime watchdog、visual capture fallback、feedback rollup、visual media/channel rollup、operator digest、maintenance summary 与 runtime environment，并输出单一 JSON 报告。该 harness 不使用外部通道、不要求真实成交，环境不可用时以 environment blocker 暴露，不改变 execution allowed、real live readiness、risk governor、trust bucket 或 operator confirmation protocol。

src/services/alerts/delivery_policy_service.py

职责：

• 冷却时间
• 同一 alert_key 去重策略
• 升级策略
• 夜间静默策略（如需要）
• alert noise policy matrix：按 alert type / severity / channel / duty mode / operator mode / silent window / cooldown 输出 workbench_only、external_allowed、suppressed_noise_policy、suppressed_silent_window 等结构化策略结果

2026-05-12 P15 已落地：evaluate_alert_delivery_policy() 会把 policy result 写入 dispatcher delivery payload，并在 alert quality summary、runtime alert_dispatch details 与 workbench Alert Quality 面板中暴露 policy counters。

---

B. 新增 src/services/notifications/

用途：各具体消息通道适配器。

建议文件：

src/services/notifications/__init__.py

src/services/notifications/telegram_notifier.py

建议类：TelegramNotifier

建议方法：

• send_text(chat_id: str, text: str) -> dict
• send_photo(chat_id: str, text: str, image_path: str) -> dict

src/services/notifications/wecom_notifier.py

建议类：WecomNotifier

src/services/notifications/webhook_notifier.py

建议类：WebhookNotifier

src/services/notifications/email_notifier.py

可选，优先级较低。

---

C. 新增 src/services/visual_watch/

用途：高价值时刻截图、视觉复核、结果回写。

补充吸收点：

• 研发验证阶段允许先使用现有手工页面、browser/computer use、截图工具验证视觉触发 ROI
• 正式产品阶段必须切换到系统内建浏览器自动化与截图闭环，不能依赖人工开着工具会话
• 视觉数据源不只包含 chart，也应包含新闻日历页、交易所公告/异常页、本地 workbench 页面

建议文件：

src/services/visual_watch/__init__.py

src/services/visual_watch/visual_watch_service.py

总控服务。

职责：

• 接收 symbol / timeframe / candidate / packet
• 选择数据源
• 触发截图
• 调用视觉复核
• 生成 visual summary
• 写入数据库

建议类：

• VisualWatchService
• VisualWatchRequest
• VisualWatchResult

建议方法：

• review_candidate(candidate_id: int) -> dict
• review_decision_packet(packet_id: int) -> dict
• review_runtime_incident(symbol: str, incident_code: str) -> dict

src/services/visual_watch/chart_source_adapter.py

职责：统一不同图表来源。

建议适配：

• TradingView
• OKX Web
• 本地 workbench

建议类：

• ChartSourceAdapter
• TradingViewChartAdapter
• OkxChartAdapter
• LocalWorkbenchAdapter

建议方法：

• build_chart_url(symbol: str, timeframe: str) -> str
• build_capture_spec(...) -> dict

src/services/visual_watch/snapshot_capture_service.py

职责：截图执行层。

生产建议基于 Playwright；研发期可保留兼容抽象。

建议方法：

• capture_page(url: str, viewport: dict, clip: dict | None = None) -> dict
• capture_chart(symbol: str, timeframe: str, source: str) -> dict

输出建议：

• image_path
• html_path
• screenshot_path
• captured_ts
• source
• browser_capture_status
• meta

2026-05-12 P16 已落地：当前实现优先使用本机 Edge/Chrome headless 截取 review-packet HTML 或指定 capture URL，成功时输出 PNG；浏览器不可用或截图失败时返回结构化 browser_capture_status=unavailable，并保留 HTML/JSON artifact 作为 advisory fallback。

src/services/visual_watch/vision_review_service.py

职责：把截图和结构化上下文融合为视觉摘要。

建议方法：

• review_snapshot(image_path: str, context: dict) -> dict
• summarize_candidate_visual_state(...) -> dict

输出字段建议：

• visual_state: confirm | caution | mismatch | unavailable
• visual_confidence
• visual_notes
• ui_anomalies

src/services/visual_watch/visual_trigger_policy_service.py

职责：控制何时启动视觉层。

建议规则：

• action_recommendation in {build_execution_ticket, confirm_ticket}
• candidate.status == executable
• runtime incident 高优先级
• session 切换
• candidate 临近 entry zone
• candidate 从 blocked 进入接近 actionable
• news window 激活后需要页面级复核
• reconciliation 发现异常后需要人工式视觉巡检

建议触发类型枚举：

• candidate_actionable_watch
• candidate_block_reason_review
• market_anomaly_review
• session_focus_watch
• news_window_review
• reconciliation_review

这些触发类型建议贯穿 visual watch run、snapshot、review、alert payload，便于后续统计 ROI。

2026-05-12 P17 已落地：evaluate_visual_trigger_policy() 现在输出 triggered / skipped、trigger_types、primary_trigger_type、reason_codes、skip_reason 与 ROI 友好的基础字段。普通 observe/monitoring 不再触发视觉复核，actionable、blocked、market degraded、broker/reconciliation degraded 与 council watch item 会创建 policy-backed visual watch request；runtime、alert quality summary、脚本与 workbench 均可查看 trigger/skip/ROI 统计。

src/services/visual_watch/visual_media_evidence_service.py

职责：把视觉复核结果转换成 alert/workbench 均可消费的媒体证据块。

输出建议：

• status: media_attached | media_linked | media_unavailable
• items: screenshot / html / metadata artifact 列表
• primary_item: 首选截图或路径证据
• mime_type
• browser_capture_status
• fallback_reason

2026-05-12 P18 已落地：workbench 通道可将本地截图路径作为 media_attached 消费；webhook 等文本通道在不支持文件上传时降级为 media_linked，并把路径、mime type、browser capture status 与 fallback reason 写入 delivery payload，不把媒体能力缺失误报为 dispatch 失败。

---

D. 新增 src/services/feedback/

用途：人工对 alert / visual review 做反馈。

建议文件：

src/services/feedback/__init__.py

src/services/feedback/alert_feedback_service.py

建议方法：

• record_feedback(alert_id: int, label: str, note: str | None = None) -> dict
• list_feedback(alert_id: int) -> list[dict]

可选标签：

• useful
• too_early
• too_late
• false_positive
• visual_helpful
• visual_misleading
• actionable

---

4.2 repositories 层

A. 新增 src/repositories/alert_delivery_repository.py

职责：

• 写入每次实际发送结果
• 查询失败记录
• 查询最近发送统计

建议方法：

• insert_delivery(...) -> int
• fetch_recent_deliveries(alert_id: int, limit: int = 20) -> list[dict]
• fetch_failed_deliveries(limit: int = 100) -> list[dict]

B. 新增 src/repositories/visual_snapshot_repository.py

职责：

• 记录截图元数据
• 记录 visual review 结果
• 按 candidate / packet 查询最近截图

建议方法：

• insert_snapshot(...) -> int
• insert_visual_review(...) -> int
• fetch_latest_snapshot_for_candidate(candidate_id: int) -> dict | None
• fetch_reviews_for_packet(packet_id: int, limit: int = 10) -> list[dict]

C. 新增 src/repositories/alert_feedback_repository.py

职责：

• 保存人工反馈标签和备注

---

4.3 api 层

在 src/api/ 下建议新增或扩展以下文件。

A. 新增 src/api/alerts.py

职责：告警与发送结果查询。

建议函数：

• get_recent_alerts(instrument_id: int, limit: int = 20) -> list[dict]
• dispatch_pending_alerts(limit: int = 50) -> dict
• get_alert_deliveries(alert_id: int, limit: int = 20) -> list[dict]
• get_alert_quality_summary(instrument_id: int, limit: int = 50, visual_limit: int = 50) -> dict

B. 新增 src/api/visual_watch.py

职责：视觉触发和结果查询。

建议函数：

• run_visual_candidate_review(candidate_id: int) -> dict
• run_visual_packet_review(packet_id: int) -> dict
• get_visual_reviews(candidate_id: int | None = None, packet_id: int | None = None, limit: int = 20) -> list[dict]

C. 新增 src/api/feedback.py

职责：人工反馈接口。

建议函数：

• create_alert_feedback(alert_id: int, label: str, note: str | None = None) -> dict
• get_alert_feedback(alert_id: int) -> list[dict]

D. 扩展 src/api/trading_runtime.py

建议新增：

• run_trading_alert_dispatch() -> dict
• run_visual_watch_for_candidate(candidate_id: int) -> dict
• get_trading_visual_status(...) -> dict

E. 扩展 src/api/server.py

建议增加路由：

告警

• GET /trading/alerts?instrument_id=1&limit=20
• POST /trading/alerts/dispatch
• GET /trading/alerts/{alert_id}/deliveries
• GET /trading/alerts/quality-summary?instrument_id=1&limit=50&visual_limit=50

视觉复核

• POST /trading/candidates/{candidate_id}/visual-review
• POST /trading/decision-packets/{packet_id}/visual-review
• GET /trading/visual-reviews?candidate_id=...&limit=20

人工反馈

• POST /trading/alerts/{alert_id}/feedback
• GET /trading/alerts/{alert_id}/feedback

---

4.4 runtime 层

建议扩展：

文件：src/services/runtime/trading_runtime_service.py

现有 tasks：

• market_state
• broker_sync
• reconciliation
• watch
• decision_packet
• plan

建议新增两个 task：

A. visual_watch

职责：

• 只在触发策略命中时执行
• 对高价值事件生成截图和视觉摘要

B. alert_dispatch

职责：

• 定时扫描 queued alerts
• 发送并回写结果

需要新增状态字段

在 RuntimeTaskState.details 中补充：

• alerts_dispatched
• visual_reviews_created
• failed_delivery_count
• last_visual_state

---

4.5 web 层

A. 扩展 src/web/app.js

建议新增 UI 模块：

1. Recent Alerts 面板
2. Alert Delivery 状态面板
3. Visual Review 面板
4. Snapshot Gallery
5. Alert Feedback 面板

B. 扩展 src/web/index.html

增加以下区域：

• 告警列表
• 截图证据区
• 视觉总结区
• 反馈标记按钮

---

4.6 scripts 层

建议新增脚本：

scripts/run_alert_dispatcher.py

用途：单独运行告警发送流程。

scripts/run_visual_review.py

用途：对指定 candidate / packet 手动触发视觉复核。

scripts/run_monitoring_cycle.py

用途：做一轮“运行时 + 视觉 + 告警”的调试型总入口。

---

4.7 migrations 层

建议新增迁移，至少补三张表。

A. visual_snapshots

建议字段：

• id
• instrument_id
• candidate_id
• decision_packet_id
• source
• image_path
• captured_ts
• meta jsonb

B. visual_watch_runs

建议字段：

• id
• instrument_id
• trigger_type
• source_name
• status
• started_ts
• completed_ts
• candidate_id
• decision_packet_id
• meta jsonb

C. visual_reviews

建议字段：

• id
• watch_run_id
• snapshot_id
• instrument_id
• candidate_id
• decision_packet_id
• visual_state
• visual_confidence
• visual_bias
• visual_location
• sweep_visible
• mss_visible
• fvg_visible
• entry_zone_valid
• invalidation_intact
• summary
• notes jsonb
• anomalies jsonb
• payload jsonb
• created_ts

D. alert_deliveries

建议字段：

• id
• alert_id
• channel
• status
• attempted_ts
• delivered_ts
• external_message_id
• error
• payload jsonb

D. alert_feedback

建议字段：

• id
• alert_id
• label
• note
• created_by
• created_ts

---

5. 接口契约建议

5.1 visual review 输出契约

{
  "id": 101,
  "instrument_id": 1,
  "candidate_id": 88,
  "decision_packet_id": 55,
  "snapshot": {
    "image_path": "/data/visual/btc_1m_20260508_101500.png",
    "source": "tradingview",
    "captured_ts": "2026-05-08T10:15:00Z"
  },
  "visual_state": "confirm",
  "visual_confidence": 0.82,
  "summary": "结构与候选一致，回踩较干净，未见明显失效。",
  "notes": [
    "Sweep 后价格已回到区间内部",
    "MSS 后 pullback 较浅",
    "FVG 回踩仍在有效区"
  ],
  "anomalies": [],
  "payload": {}
}

5.2 alert delivery 输出契约

{
  "alert_id": 301,
  "channel": "telegram",
  "status": "delivered",
  "attempted_ts": "2026-05-08T10:15:05Z",
  "delivered_ts": "2026-05-08T10:15:06Z",
  "external_message_id": "998877"
}

5.3 feedback 输出契约

{
  "alert_id": 301,
  "label": "useful",
  "note": "提醒时机合适，截图也有帮助",
  "created_by": "local_operator"
}

---

6. 触发策略建议

6.1 哪些事件触发视觉层

首批建议：

1. candidate.status == executable
2. action_recommendation in {build_execution_ticket, confirm_ticket}
3. market_state 进入 degraded
4. session 切换到重点时段

6.2 哪些事件直接发消息

首批建议：

1. actionable candidate
2. ticket ready
3. runtime degraded
4. visual mismatch（高风险提示）

6.3 哪些只写 dashboard 不推送

1. blocked candidate
2. 低质量 observe 状态
3. 重复告警冷却期间事件

---

7. 建议配置项

建议在 settings 中补充：

• ALERTS_ENABLED
• ALERT_DISPATCH_INTERVAL_SECONDS
• ALERT_DEFAULT_CHANNEL
• TELEGRAM_BOT_TOKEN
• TELEGRAM_CHAT_ID
• WECOM_WEBHOOK_URL
• VISUAL_WATCH_ENABLED
• VISUAL_WATCH_SOURCE
• VISUAL_WATCH_VIEWPORT_WIDTH
• VISUAL_WATCH_VIEWPORT_HEIGHT
• VISUAL_WATCH_STORAGE_DIR
• VISUAL_REVIEW_ON_ACTIONABLE_ONLY
• VISUAL_CAPTURE_RETENTION_HOURS
• VISUAL_CAPTURE_CLEANUP_INTERVAL_SECONDS
• VISUAL_CAPTURE_CLEANUP_MAX_DELETE_FILES
• RUNTIME_TASK_STALE_MULTIPLIER
• RUNTIME_TASK_STUCK_MIN_SECONDS
• ALERT_SILENT_WINDOW_ENABLED
• ALERT_SILENT_WINDOW_START_HOUR
• ALERT_SILENT_WINDOW_END_HOUR
• ALERT_SILENT_WINDOW_TIMEZONE
• ALERT_RETRY_FAILED_ENABLED
• ALERT_RETRY_MAX_ATTEMPTS
• ALERT_RETRY_BACKOFF_SECONDS
• ALERT_WEBHOOK_TRANSPORT_RETRIES
• ALERT_WEBHOOK_RETRY_BACKOFF_SECONDS

---

8. 分阶段落地计划

Phase 1：先打通消息外发

目标：

• 新增 alert dispatcher
• 接入 Telegram 或 Webhook
• 把现有 decision_alerts 真正发出去

Phase 2：加入截图证据

目标：

• 对 actionable alert 生成截图
• 告警附上 image_path 和视觉摘要占位

Phase 3：加入视觉复核

目标：

• 生成 visual_state / confidence / notes
• dashboard 展示 visual review

Phase 4：加入反馈回流

目标：

• alert feedback 标记
• delivery 成功率统计
• visual helpfulness 统计
• dashboard / review packet 质量简报

---

9. 风险与边界

1. 视觉层不能成为唯一真相源
2. 截图成本和延迟必须受 trigger policy 控制
3. 消息发送失败不能阻塞 runtime 主循环
4. 所有视觉结论都必须带 candidate / packet 关联关系
5. 实盘执行边界继续保持，盯盘增强不等于放开自动交易

---

10. 最小可用版本定义

最小可用版本建议只做：

• AlertDispatcherService
• TelegramNotifier
• alert_deliveries 表
• POST /trading/alerts/dispatch
• runtime 新增 alert_dispatch task

这样先让系统具备：

候选机会出现 -> 决策包生成 -> 告警落库 -> 实际发消息

之后再叠加视觉层，是最稳的推进路线。