ai-exchange/docs/AI_ICT_盯盘告警开发任务清单_v1.md

AI ICT 盯盘告警开发任务清单 v1

1. 文档目标

本文档把 docs/AI_ICT_盯盘告警技术设计稿_v1.md 进一步拆成可执行开发任务清单，并按 P0 / P1 / P2 排优先级。

设计原则：

• 先打通最短闭环，再叠加视觉增强
• 优先做“真正能发消息”的能力
• 不让视觉层抢主判断权
• 自动化执行尽量持续推进，只有遇到重大 blocker 才停

---

2. 总体优先级

P0：最小可用盯盘告警闭环

目标：

candidate / decision alert 已经落库的前提下，让系统真正把告警发出去，并可观测、可回执、可重试。

P1：视觉证据与工作台增强

目标：

给高优先级机会附加截图与视觉总结，并让 dashboard 能看到这些证据。

补充原则：

• 原型验证阶段可先用现有人工页面或 browser 工具验证触发 ROI
• 正式产品实现不得依赖人工开着外部工具会话
• 视觉层除了 chart，也应覆盖新闻日历页、公告异常页、workbench 页面
• 所有视觉结论必须结构化回写，不能只留截图
• 告警最终目标是让人 30 秒内完成判断

P2：反馈回流与自动化运营增强

目标：

让系统具备反馈标记、统计、调优与长期自动化运转能力。

---

3. P0 任务清单

P0-1 数据库与仓储补齐

目标

补齐告警真正发送所需的数据存储。

任务

• 新增 alert_deliveries 表
• 为告警发送结果建立 repository
• 如需要，扩展 decision_alerts 查询字段

建议文件

• migrations/*_create_alert_deliveries.sql
• src/repositories/alert_delivery_repository.py

验收

• 可写入一条 delivery 记录
• 可按 alert_id 查询 delivery 历史

---

P0-2 消息通道基础设施

目标

先打通一个可靠通道，建议 Telegram 或 Webhook。

任务

• 新增 src/services/notifications/telegram_notifier.py
• 新增 src/services/notifications/webhook_notifier.py
• 新增 src/services/notifications/__init__.py
• 在 settings 中增加 bot token / chat id / webhook url

建议接口

• send_text(...)
• send_photo(...)
• send_json(...)

验收

• 用测试脚本能成功发出一条测试消息
• 失败时能返回明确错误而不是静默吞掉

---

P0-3 告警模板与分发策略

目标

把落库 alert 转成真正适合人查看的消息。

任务

• 新增 src/services/alerts/message_template_service.py
• 新增 src/services/alerts/channel_router_service.py
• 新增 src/services/alerts/delivery_policy_service.py
• 定义三类模板：
  • actionable
  • blocked / watch
  • runtime degraded

建议输出

• 标的
• timeframe
• 当前 action recommendation
• why blocked / why allowed
• entry / stop / targets（若存在）

验收

• 能根据 alert type 正确输出不同文案
• 冷却策略能避免重复刷屏

---

P0-4 Alert Dispatcher 主闭环

目标

打通：decision_alerts -> dispatcher -> notifier -> deliveries。

任务

• 新增 src/services/alerts/alert_dispatcher_service.py
• 实现：
  • dispatch_pending(limit=50)
  • dispatch_alert(alert_id)
  • 发送成功回写 delivered
  • 发送失败写入 failed
  • dashboard only 类型标记 skipped
• 新增 src/services/alerts/__init__.py

依赖

• P0-1
• P0-2
• P0-3

验收

• queued alert 可以成功变成 delivered / failed / skipped
• 重复执行 dispatcher 不会重复发送同一条已成功告警

---

P0-5 API 与脚本接入

目标

让本地和 runtime 都能手动或自动触发 dispatcher。

任务

• 新增 src/api/alerts.py
• 扩展 src/api/server.py
• 新增脚本 scripts/run_alert_dispatcher.py
• 增加接口：
  • POST /trading/alerts/dispatch
  • GET /trading/alerts/{alert_id}/deliveries

验收

• 可通过脚本单次发送 pending alerts
• 可通过 API 查看某条 alert 的 delivery 历史

---

P0-6 runtime 接入自动分发

目标

让运行时在不遇到重大 blocker 的情况下持续自动发送提醒。

任务

• 扩展 src/services/runtime/trading_runtime_service.py
• 新增 runtime task：alert_dispatch
• 在 task details 中记录：
  • alerts_dispatched
  • delivery_failures
  • last_dispatch_status

验收

• runtime run once 时能顺带执行一次 alert dispatch
• /trading/runtime-status 可看到 alert dispatch task 状态

---

P0-7 P0 验证与最小上线标准

验证项

• decision packet 能持续落库 alert
• dispatcher 能把 queued alerts 发到外部通道
• delivery 结果可查
• runtime 状态里能看到 dispatch task
• workbench 仍然正常工作

建议命令

• .venv/bin/python scripts/run_alert_dispatcher.py
• .venv/bin/python scripts/run_decision_packet.py
• .venv/bin/python scripts/run_trading_runtime.py
• .venv/bin/python scripts/run_offline_checks.py

P0 完成定义

当以下闭环成立时，P0 完成：

candidate -> decision alert -> dispatcher -> 外部消息 -> delivery record

---

4. P1 任务清单

P1-1 截图存储模型

目标

为视觉增强准备持久化结构。

任务

• 新增 visual_watch_runs 表
• 新增 visual_snapshots 表
• 新增 visual_reviews 表
• 新增 src/repositories/visual_snapshot_repository.py
• 将 trigger_type、source_name、watch_run_id 作为主关联字段贯穿视觉链路
• 为后续统计预留 candidate_actionable_watch / candidate_block_reason_review / market_anomaly_review / session_focus_watch 等触发类型

验收

• 可保存截图元数据
• 可保存一次 visual review 结果

---

P1-2 截图采集服务

目标

对高价值时刻生成可回放截图。

任务

• 新增 src/services/visual_watch/snapshot_capture_service.py
• 新增 src/services/visual_watch/chart_source_adapter.py
• 支持至少一个源：
  • local workbench 或 TradingView

验收

• 对指定 symbol/timeframe 生成截图文件
• 截图路径、时间、source 可持久化

---

P1-3 视觉复核摘要

目标

不是只留图，而是生成结构化视觉摘要。

任务

• 新增 src/services/visual_watch/vision_review_service.py
• 新增 src/services/visual_watch/visual_watch_service.py
• 输出：
  • visual_state
  • visual_confidence
  • visual_notes
  • ui_anomalies

验收

• 对指定 candidate 生成 visual review 记录
• review 与 candidate / packet 有关联关系

---

P1-4 视觉触发策略

目标

只在高价值时刻启用视觉层。

任务

• 新增 src/services/visual_watch/visual_trigger_policy_service.py
• 触发条件首批支持：
  • candidate.status == executable
  • action_recommendation in {build_execution_ticket, confirm_ticket}
  • runtime degraded

验收

• 普通 observe 状态不触发视觉层
• 高优先级事件触发视觉层

---

P1-5 告警与视觉结果融合

目标

让消息里带视觉证据，而不是结构化信息孤立存在。

任务

• 扩展 message_template_service.py
• 告警支持附带：
  • screenshot path 或图片发送
  • visual summary
  • visual caution / mismatch 提示

验收

• actionable alert 可带图或带视觉摘要
• visual mismatch 能提升为更高优先级警告

---

P1-6 API 与 Workbench 增强

目标

让前端能看到视觉证据与发送结果。

任务

• 新增 src/api/visual_watch.py
• 扩展 src/api/server.py
• 扩展 src/web/app.js
• 扩展 src/web/index.html
• 新增页面区块：
  • Recent Alerts
  • Delivery Status
  • Snapshot Gallery
  • Visual Review

验收

• workbench 能显示最近 visual review
• 能查看 alert delivery 历史

---

P1-7 runtime 接入视觉层

目标

把视觉复核纳入运行时自动化，但只在策略命中时触发。

任务

• runtime 新增 visual_watch task
• task details 记录：
  • visual_reviews_created
  • last_visual_state
  • last_snapshot_source

验收

• runtime run once 时，在高优先级时刻自动产出 visual review

---

5. P2 任务清单

P2-1 人工反馈回流

目标

让告警与视觉增强可被持续调优。

任务

• 新增 alert_feedback 表
• 新增 src/repositories/alert_feedback_repository.py
• 新增 src/services/feedback/alert_feedback_service.py
• 新增 src/api/feedback.py

标签建议

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

验收

• 可为 alert 添加反馈
• 可查询 alert 的反馈记录
• 2026-05-11 P8 实现已扩展到 visual review feedback：可为视觉复核添加 visual_helpful / visual_misleading / actionable 标签。
• 2026-05-11 P8 实现已让 alert dispatch 在现有 workbench/webhook payload 中附带最新 visual evidence；额外图片通道属于后续增强，不作为 P8 阻塞。

---

P2-2 统计与复盘面板

目标

让系统不只是会发，还能衡量质量。

任务

• 统计 delivery success rate
• 统计 alert usefulness rate
• 统计 visual helpfulness rate
• 在 review packet 或 dashboard 增加简报视图

验收

• 能看到最近一段时间的发送成功率与反馈标签分布
• 2026-05-11 P9 实现已新增 AlertQualitySummaryService，聚合 recent alerts / deliveries / alert feedback / visual feedback / visual review states。
• 2026-05-11 P9 实现已新增 GET /trading/alerts/quality-summary、review_packet.alert_quality_summary 和 dashboard Alert Quality 面板。
• 2026-05-11 P9 本地闭环已验证：全量 tests/unit 通过，runtime smoke 无 blocker，本地 API/workbench smoke 可见质量摘要。

---

P2-3 自动化运维增强

目标

让这套能力适合长期 unattended 运行。

任务

• 增强自动恢复与重试
• 增加静默窗口 / 降噪策略
• 增加 stuck task 检测
• 增加 screenshot 存储清理策略

当前进展

• 2026-05-12 P10 已完成 screenshot 存储清理闭环：新增 VisualCaptureRetentionService、scripts/run_visual_capture_cleanup.py、POST /trading/visual-watch/cleanup-captures、runtime visual_capture_cleanup 任务，以及 workbench 手动触发入口。
• 2026-05-12 P10 本地闭环已验证：cleanup 脚本可删除过期临时文件，runtime smoke 无 blocker，本地 API/workbench smoke 可见 cleanup 路径。
• 2026-05-12 P11 已完成 stuck task 检测闭环：新增 RuntimeTaskWatchdogService、scripts/run_runtime_task_watchdog.py、GET /trading/runtime-watchdog、runtime_status.runtime_watchdog，以及 runtime 面板 stalled-task 呈现。
• 2026-05-12 P11 本地闭环已验证：watchdog 脚本返回 stalled_task_count=0，runtime/API/workbench smoke 可见 watchdog 路径与状态输出。
• 2026-05-12 P12 已完成 silent window / noise control 基础闭环：新增 AlertSilentWindowService、scripts/run_alert_silent_window_status.py、GET /trading/alerts/silent-window-status，并将静默窗口状态接入 dispatcher、alert quality summary、runtime alert_dispatch 细节和 workbench 面板。
• 2026-05-12 P12 本地闭环已验证：silent-window 脚本与 API 可返回 active=true，quality-summary 与 dashboard 可见静默窗口状态与 suppression 统计。

验收

• 非重大错误不打断主循环
• delivery 失败可重试
• 存储不会无限膨胀

---

P2-4 多通道与多场景扩展

目标

从单通道提升为多场景编排。

任务

• 增加 WeCom / Email
• 区分系统健康告警与交易机会告警
• 区分值班模式 / 静默模式

验收

• 可按 alert type 路由到不同通道

---

6. 推荐实施顺序

按最小闭环优先，推荐顺序：

1. P0-1 数据库与仓储补齐
2. P0-2 消息通道基础设施
3. P0-3 告警模板与分发策略
4. P0-4 Alert Dispatcher 主闭环
5. P0-5 API 与脚本接入
6. P0-6 runtime 接入自动分发
7. P0-7 P0 验证
8. P1-1 ~ P1-7 视觉增强
9. P2-1 ~ P2-4 反馈与运营增强

---

7. 重大 blocker 定义

自动化执行脚本只有遇到以下情况才应暂停：

1. 缺失外部凭据
2. 需要人工授权的外部通道配置
3. 数据库迁移失败且无法安全回滚
4. 浏览器/截图依赖缺失且无法自动安装
5. 会导致真实交易风险的边界不明确

除此之外，应持续自动推进。

---

8. 最小可用版本定义

最小可用版本只要求完成 P0：

• alert 能真正发出
• 有 delivery 记录
• runtime 能持续分发
• workbench 与 API 可观察

达到这一点后，这个系统就已经从“只会生成数据库内提醒”升级成“真正可用的盯盘主动通知系统”。