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 统计。
• 2026-05-12 P13 已完成 delivery failure retry 闭环：failed alerts 现在可以通过 bounded retry attempts + retry backoff 自动重试，并在 dispatcher payload、delivery summary 与 runtime alert_dispatch 细节中暴露可观测计数。
• 2026-05-12 P13 本地闭环已验证：focused retry/backoff 单测通过，dispatcher 脚本返回 retry counters，runtime smoke 无 blocker 且 alert_dispatch 详情带 retry 字段。
• 2026-05-12 P14 已完成 webhook transport retry 闭环：单次 outbound webhook 发送现在可以在 AlertDispatcherService 内部做 bounded transport retries，并在 dispatcher payload、delivery summary 与 runtime alert_dispatch 细节中暴露 transport retry 计数。
• 2026-05-12 P14 本地闭环已验证：focused transport retry 单测通过，tests/unit 全量通过；脚本级 smoke 因本地 PostgreSQL 未监听 127.0.0.1:5432 而未能在最后重跑，但代码路径已被全量单测覆盖。
• 2026-05-12 已新增 docs/AI_ICT_自动化执行层_P15-PXX闭环任务清单_v1.md：P15-PXX 被收敛为有限队列，从 alert noise policy matrix 继续推进到 browser screenshot capture、visual ROI、media dispatch、multi-channel routing、operator digest、runtime incident journal、maintenance rollup、unattended harness、remote smoke 与 PXX closure gate。
• 2026-05-12 P15 已完成 alert noise policy matrix 本地闭环：外部发送现在可按 alert type / severity / channel / duty mode / operator mode / silent window / cooldown 形成结构化策略结果，并在 dispatcher、delivery summary、runtime alert_dispatch 与 workbench Alert Quality 中暴露降噪计数。
• 2026-05-12 P16 已完成 browser screenshot capture adapter 本地闭环：visual snapshot capture 现在在保留 HTML/JSON artifact 的同时，可通过本机 Edge/Chrome headless 生成 PNG screenshot，并把 browser capture status、HTML path、screenshot path 接入脚本、API 与 workbench Visual Reviews。
• 2026-05-12 P17 已完成 visual trigger ROI router 本地闭环：视觉触发策略现在区分 triggered / skipped，普通 observe/monitoring 状态不触发视觉复核，actionable、blocked、market degraded、broker/reconciliation degraded 与 council watch item 会输出可审计 trigger type / reason codes，并在 runtime、alert quality summary、脚本和 workbench 中暴露 trigger/skip/ROI 计数。
• 2026-05-12 P18 已完成 visual evidence media dispatch 本地闭环：visual review 现在会生成稳定 media_evidence block，外部文本通道不支持文件时降级为 media_linked，workbench 可消费本地截图路径时标记 media_attached，无视觉证据时标记 media_unavailable；dispatcher、delivery summary、runtime、脚本和 workbench 均可见媒体证据状态。
• 2026-05-12 P19 已完成 multi-channel alert routing 本地闭环：channel router 现在输出 workbench/webhook/WeCom/Email capability 与 health summary，WeCom/Email 在凭据缺失或 adapter 未实现时会以 disabled adapter 形式返回 credential_missing / adapter_not_implemented，dispatcher、delivery summary、runtime、脚本和 workbench 均可见 per-channel 状态。
• 2026-05-12 P20 已完成 operator digest / review queue 本地闭环：operator digest 会把高价值告警、被抑制 delivery、失败/重试 delivery、视觉 mismatch 与待反馈项聚合成 bounded review queue，并通过脚本、API 和 workbench Alert Quality 面板暴露。
• 2026-05-12 P21 已完成 runtime incident journal 本地闭环：runtime/watchdog/blocker/noisy incident 现在可聚合写入 runtime_incidents，每条 incident 带 severity、source、reason、first/last seen 与 recommended action，并通过脚本、API、runtime status 和 workbench runtime panel 暴露。
• 2026-05-12 P22 已完成 maintenance / retention rollup 本地闭环：maintenance summary 以只读方式聚合 visual capture retention dry-run、delivery/feedback、runtime watchdog 与 incident journal，输出 P23 harness 可复用的 checks/blockers/warnings/p23_assertions，不执行未纳入 retention policy 的业务数据删除。
• 2026-05-12 P23 已完成 end-to-end unattended harness 本地闭环：UnattendedHarnessService、脚本与 API 会在 analysis/decision-only 模式下一次性验证 P15-P22 关键路径，输出单一 JSON blockers/warnings/passed-checks 报告，不使用外部通道、不要求真实成交。

验收

• 非重大错误不打断主循环
• 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 可观察

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