[Feature] DSA 后续开发规划：[通知渠道网关] 渠道基线、测试、Body 模板、路由、降噪与长尾渠道扩展

[massif-01]

Summary

本 issue 只解决图片中的「通知渠道网关」规划，不实现「首次启动与配置体验」。但通知测试 UI、通知 key 分层、文档场景化结构会为后续首次启动向导预留复用点。

目标不是重写现有通知框架，而是在当前 NotificationService、各 sender、custom webhook、系统配置和 Web 设置页基础上，补齐产品化管理能力：可测试、可诊断、可路由、可降噪、可文档化，并逐步扩展长尾渠道。

当前基线：

• 当前 NotificationChannel 有 11 个实际发送渠道：WECHAT、FEISHU、TELEGRAM、EMAIL、PUSHOVER、PUSHPLUS、SERVERCHAN3、CUSTOM、DISCORD、SLACK、ASTRBOT；UNKNOWN 仅为检测兜底，不作为可配置渠道。
• 此外还有非枚举上下文渠道：钉钉会话 Webhook、飞书 Stream 回复等，通过 send_to_context() 独立于枚举渠道循环发送。
• CUSTOM_WEBHOOK_BODY_TEMPLATE 基础能力已由 #1173 合入。
• #1134 是 Body 模板相关需求，仓库内无代码引用，需以 GitHub Issue 页面为准。
• #1155 是 bot 分析失败 / 队列满反馈 PR，本地 Git 历史与 CHANGELOG 无此编号，需以 GitHub PR 页面为准；它不等同于通用通知网关失败隔离。
• Bark 已可通过 custom webhook 的 api.day.app 自动 payload 适配使用，不作为“从零新增渠道”处理。
• AstrBot 已是一等 NotificationChannel，拥有独立 sender；但 ASTRBOT_URL / ASTRBOT_TOKEN 需要补齐 .env.example 与 config_registry 显式注册。
• NotificationService.send() 已逐渠道捕获异常；custom webhook 已逐 URL 隔离失败。

默认兼容规则：

• 未配置新路由或降噪规则时，保持当前“所有已配置渠道都推送”的行为。
• 新增配置默认关闭，不静默迁移或改写用户 .env。
• 单一通知渠道失败不得影响分析主流程，除非调用方显式要求 fail-fast。
• send_to_context() 默认作为“触发会话回执”保留，不受普通渠道路由限制。

Key Changes

P0：通知能力基线、配置审计与回归快照

先建立真实基线，不做框架重写。

• 创建 docs/notifications.md 骨架，包含目录、渠道基线表和场景分节占位。
• 基线表覆盖 11 个发送渠道、UNKNOWN 兜底、上下文渠道、对应 sender、配置 key、Actions env、Web 设置页状态。
• 梳理 config_registry 通知类 key 与 .env.example、.github/workflows/daily_analysis.yml 的一致性。
• 修复已知配置缺口：CUSTOM_WEBHOOK_BODY_TEMPLATE、WEBHOOK_VERIFY_SSL、FEISHU_WEBHOOK_SECRET、FEISHU_WEBHOOK_KEYWORD 的 Actions 映射；ASTRBOT_URL / ASTRBOT_TOKEN 的 .env.example 与 config_registry 显式注册。
• 对每个通知 key 标注 minimal / advanced 分层；路由、降噪、Body 模板、SSL 校验等高级项不得进入首次启动必填检查。
• 新增轻量 CLI 诊断：main.py --check-notify，用于 CLI / Actions / Docker 用户在无 Web 情况下检查通知配置、路由和降噪配置合法性。
• P0 测试只做现有行为快照：逐渠道异常隔离、custom webhook 多 URL 部分失败、Bark 自动 payload、Body template fallback。

P1：Web 一键通知测试

参考现有 POST /api/v1/system/config/llm/test-channel 的 Schema、临时配置和错误处理模式，新增通知测试能力。

• 新增 POST /api/v1/system/config/notification/test-channel。
• Request 使用 channel、items、title、content、timeout_seconds。
• items 复用系统配置更新项结构，只合成临时配置，不写入 .env。
• Response 返回 success、message、error_code、stage、retryable、latency_ms、attempts。
• attempts 表达 custom webhook 多 URL、部分成功、失败原因和耗时。
• 返回内容必须脱敏，不回显 token、完整 webhook URL、邮箱密码、bot secret。
• Web UI 封装为独立 NotificationTestPanel 组件，设置页引用；后续首次启动向导的“通知步骤”可直接复用，不重复建设。

P2：Body 模板产品化

基于 #1173 和 #1134 完善 Body 模板，不重复实现模板引擎。

• 明确当前实现中 CUSTOM_WEBHOOK_BODY_TEMPLATE 先于 Bark api.day.app 自动识别执行，配置模板会覆盖 Bark 专用 payload。
• 处理方案先采用最小策略：文档和 Web 提示明确“全局 Body 模板会覆盖 Bark / Slack / Discord 等自动 payload”；per-URL 模板或 Bark 自动跳过模板另拆 follow-up。
• 确认 CUSTOM_WEBHOOK_BODY_TEMPLATE 与 WEBHOOK_VERIFY_SSL 已映射到 daily_analysis.yml；若 P0 未完成，P2 必须补齐。
• AstrBot 作为一等渠道单独说明配置；如通过 custom webhook 兼容模式使用，再提供 Body 示例。
• NapCat 作为 QQ 机器人框架 / custom webhook 目标说明使用前提和 payload 预期。
• Bark、NapCat、通用 webhook 示例使用 $content_json / $title_json，避免换行和引号破坏 JSON。
• invalid JSON、非 object JSON、变量转义失败时 fallback 到默认 payload，不中断主通知流程。

P3：通知路由策略

第一版只实现已有事件源能稳定表达的路由类型。

初始实现：

• NOTIFICATION_REPORT_CHANNELS
• NOTIFICATION_ALERT_CHANNELS
• NOTIFICATION_SYSTEM_ERROR_CHANNELS

预留但不实现：

• NOTIFICATION_COST_ALERT_CHANNELS
• NOTIFICATION_PORTFOLIO_RISK_CHANNELS

规则：

• 配置为空或未设置时，沿用当前全部已配置渠道发送。
• 配置后只向对应逗号分隔枚举渠道发送。
• send_to_context() 不受路由规则约束，始终发送到触发会话。
• 路由过滤发生在 Markdown 转图判断前。
• MARKDOWN_TO_IMAGE_CHANNELS 只对路由后的渠道子集生效；若目标渠道不在图片渠道列表中，不做 Markdown 转图。
• MERGE_EMAIL_NOTIFICATION 不受路由影响；只要 email 在路由渠道列表中，合并邮件行为保持不变。
• 新增 key 在 config_registry 中标注 advanced 或等效元数据，不进入 setup/status 首次启动必填检查。

P4：降噪机制

按最小可落地顺序实现，不一次性引入复杂持久化。

配置：

• NOTIFICATION_DEDUP_TTL_SECONDS：默认 0，关闭去重。
• NOTIFICATION_COOLDOWN_SECONDS：默认 0，关闭冷却。
• NOTIFICATION_QUIET_HOURS：默认空，格式 HH:MM-HH:MM。
• NOTIFICATION_TIMEZONE：默认空，跟随 TZ 或系统本地时区。
• NOTIFICATION_MIN_SEVERITY：默认空，保持现状。
• NOTIFICATION_DAILY_DIGEST_ENABLED：默认 false。

存储与时区：

• 去重 / 冷却状态默认使用进程内 dict，适用于 main.py 单进程和 --serve 单 worker。
• uvicorn --workers N 场景下状态不共享，降噪为 per-worker 近似生效。
• 精确跨进程降噪、文件锁、SQLite、每日摘要持久化均拆 follow-up。
• GitHub Actions 默认 UTC；用户需设置 TZ 或在文档中按 UTC 配置静默时段。
• 所有 P4 新 key 标注为 advanced，不进入首次启动必填检查。

P5：失败隔离补强

P0 与 P5 边界明确：

• P0 = 回归快照测试，验证当前已有逐渠道 / 逐 URL 隔离行为不被破坏。
• P5 = 新边界补强，覆盖超时、重试、partial failure 聚合结果、每个 attempt 独立返回、Web 测试展示。

P5 覆盖：

• 通知测试接口中的 timeout、异常 sender、partial failure、敏感信息脱敏。
• 路由后单一渠道失败不影响其他渠道和主流程。
• 降噪判断异常时默认不阻断主通知。
• feat: add bot error notification for failed analysis tasks #1155 若合并，只在 bot 失败反馈维度标记关联，不算通用网关完成。

P6：新增和评估渠道

在测试、模板、路由、降噪基础稳定后再扩展渠道。

• AstrBot：已是一等渠道，不视为新增渠道；补齐显式注册、.env.example、Web 设置、文档和测试缺口。
• Bark：保留 custom webhook 基线，优先补 Web preset、测试、模板冲突提示和文档；只有确认需要独立配置体验时再升为一等渠道。
• ntfy：新增一等渠道 sender、配置、测试、文档。
• Gotify：新增一等渠道 sender、配置、测试、文档。
• WebPush：先评估订阅存储、VAPID key、浏览器权限、部署模式；若需要持久化订阅，单独 PR。
• Apprise：只做评估，不默认引入依赖；评估依赖体积、可选安装、secret 传递、Docker/Actions 影响、错误隔离和已有渠道重叠度。

P7：通知专题文档与 Actions 示例

docs/notifications.md 从 P0 建骨架，P7 做完整收口。

文档按场景分节：

• ## 本地配置
• ## Docker
• ## GitHub Actions
• ## Desktop

内容覆盖：

• 完整渠道基线表。
• minimal / advanced 配置分层。
• GitHub Actions secrets / variables 对照表。
• custom webhook Body template 语义和示例。
• Bark 与全局 Body template 冲突说明。
• AstrBot 一等渠道配置说明。
• NapCat custom webhook 适配前提和示例。
• Web 一键测试说明。
• CLI --check-notify 诊断说明。
• 路由策略与上下文渠道关系。
• 降噪状态范围和时区规则。
• Markdown 转图与合并邮件交互。
• 失败隔离语义。
• 回滚方式。

Actions 对照表不纯手写：新增脚本或 CI 检查，从 daily_analysis.yml 的 env: 块提取通知相关 env，生成或校验 docs 表格，避免后续 Actions 配置助手上线后重复维护。

Progress

Phase	状态	PR	说明
Baseline	已合并	#1173	custom webhook Body 模板基础能力
Related	Open	#1134	webhook Body 选项需求，适配 AstrBot、NapCat
Related	Open	#1155	bot 分析失败 / 队列满反馈，仅局部关联
P0	已合并	#1205	通知能力基线、配置审计、CLI 诊断、快照测试、文档骨架
P1	已合并	#1218	Web 一键通知测试与 NotificationTestPanel
P2	已合并	#1226	Body 模板产品化
P3	已合并	#1248	report / alert / system_error 路由策略
P4	已合并	#1260	降噪机制
P5	已合并	#1269	新边界失败隔离补强
P6	已合并	#1271 #1275	AstrBot/Bark 补强，ntfy / Gotify / WebPush / Apprise
P7	已合并	#1276	docs/notifications.md 完整收口与 Actions 表自动化

Acceptance Criteria

• [P0] 渠道基线表覆盖全部 11 个枚举发送渠道 + 上下文渠道，config/env/Actions 一致性缺口已修复。
• [P0] 每个通知 key 已标注 minimal / advanced 分层。
• [P0] main.py --check-notify 可用于 CLI / Actions / Docker 通知配置诊断。
• [P1] Web 可对至少现有渠道和 custom webhook 执行一键测试，组件可被后续向导复用。
• [P1] 测试结果展示成功、失败、耗时、错误，且脱敏。
• [P2] Body template 覆盖 AstrBot、NapCat、Bark、通用 webhook 示例。
• [P2] Body 模板与 Bark 自动识别的冲突已有明确处理方案。
• [P2] CUSTOM_WEBHOOK_BODY_TEMPLATE 与 WEBHOOK_VERIFY_SSL 已补入 daily_analysis.yml env 映射。
• [P3] 路由策略默认不改变现有全部渠道推送行为，上下文渠道不受路由控制。
• [P3] MARKDOWN_TO_IMAGE_CHANNELS 与 MERGE_EMAIL_NOTIFICATION 的交互已实现或文档化。
• [P4] 降噪配置默认关闭，启用后有可解释日志，时区语义明确。
• [P4] 去重 / 冷却状态存储范围已明确，多 worker 限制已文档化。
• [P5] 单一渠道失败不影响分析主流程。
• [P6] ntfy、Gotify、WebPush 分别以独立 PR 增量实现；AstrBot 配置缺口已补齐。
• [P6] Apprise 先完成评估，未评估通过前不引入默认依赖。
• [P7] docs/notifications.md 按场景分节，Actions 对照表有自动化来源。
• [全局] .env.example、config registry、Web 设置页、Actions env、docs、CHANGELOG 同步。
• [全局] 每个 PR 使用 Refs #<issue>，不在单个 Phase PR 中关闭 umbrella issue。

Test Plan

• Backend：./scripts/ci_gate.sh。
• Notification tests：渠道检测、单渠道异常隔离、custom webhook 多 URL 部分失败、Bark payload、Body template fallback、AstrBot 配置检测。
• CLI tests：main.py --check-notify 覆盖未配置、部分配置、无效路由、降噪配置错误。
• API tests：通知测试接口 200/422/500、临时配置不落盘、敏感信息脱敏、attempts 聚合。
• Routing tests：report / alert / system_error 默认全渠道、显式路由过滤、上下文渠道默认保留、Markdown 转图只对路由后渠道生效。
• Noise tests：去重、冷却、静默时段、严重级别、per-worker 限制说明。
• Web：cd apps/dsa-web && npm ci && npm run lint && npm run build。
• Docs：git diff --check，确认 docs/CHANGELOG.md [Unreleased] 扁平格式。
• Workflow：改 .github/workflows/daily_analysis.yml 时，补 env 映射静态测试或生成表校验。
• New dependency：若引入 WebPush/Apprise 相关依赖，补 import smoke、Docker 构建风险说明和可选依赖降级测试。

Non-goals

• 不重写通知框架。
• 不实现首次启动向导；只提供可复用组件、key 分层和文档结构。
• 不自动创建或修改 GitHub Secrets。
• 不在本 issue 第一版实现成本告警和持仓风险分析器；它们只作为后续路由类型预留。
• 不把 Lark/企业微信交互机器人 issue 混入通知网关主线，除非它们明确落到渠道 sender 或 webhook 模板适配。
• 不在 README 扩写通知细节；详细内容进入 docs/notifications.md。
• 不在一个 PR 中完成所有 Phase。

[ZhuLinsen]

结论
可以按现有 NotificationService、sender、custom webhook 和 Web 设置页增量推进，不需要重写通知框架。建议把这个 umbrella issue 保持为规划跟踪项，每个 Phase 独立 PR，并统一使用 Refs #<issue> 关联。

建议排查

• P0 先落地基线：补 docs/notifications.md 骨架，审计 .env.example、daily_analysis.yml、config_registry，优先修复 CUSTOM_WEBHOOK_BODY_TEMPLATE、WEBHOOK_VERIFY_SSL、FEISHU_WEBHOOK_SECRET、FEISHU_WEBHOOK_KEYWORD、ASTRBOT_URL、ASTRBOT_TOKEN 的配置缺口。
• main.py --check-notify 建议只做只读诊断：检测已启用渠道、缺失必填 key、无效路由、降噪配置格式和敏感项脱敏，不发送真实通知，不写 .env。
• P1 的通知测试接口可复用现有 LLM test-channel 的临时配置模式，重点保证 items 不落盘、custom webhook 多 URL 返回 attempts、错误信息脱敏，并由 NotificationTestPanel 复用于设置页和后续启动向导。
• P2/P3/P4 要保持默认兼容：未配置路由或降噪时继续全渠道推送；send_to_context() 不参与普通路由；CUSTOM_WEBHOOK_BODY_TEMPLATE 覆盖 Bark/Slack/Discord 自动 payload 的行为先文档化，per-URL 模板另拆 follow-up。
• 验证建议按改动面拆开：后端跑 ./scripts/ci_gate.sh，Web 改动跑 npm run lint 和 npm run build，文档同步 docs/CHANGELOG.md 的 [Unreleased] 扁平条目；涉及 daily_analysis.yml 时补通知 env 映射的静态校验，避免文档表和 Actions 配置继续漂移。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[ZhuLinsen]

结论
这条规划可以继续作为通知网关 umbrella issue 保留；P0 已由 PR #1205 覆盖但仍处于 open/blocked，合并前不要把 P0 视为完成，也不建议关闭当前 issue。

建议排查

• PR fix: 建立通知能力 P0 基线 (#1200) #1205 先聚焦 P0 收口：docs/notifications.md、.env.example、config_registry、daily_analysis.yml、Web 设置页元数据和回归测试需要保持一致。
• 配置缺口优先核对 CUSTOM_WEBHOOK_BODY_TEMPLATE、WEBHOOK_VERIFY_SSL、FEISHU_WEBHOOK_SECRET、FEISHU_WEBHOOK_KEYWORD、ASTRBOT_URL、ASTRBOT_TOKEN，避免后续 P1-P7 继续基于漂移状态开发。
• P1 可复用 POST /api/v1/system/config/llm/test-channel 的临时配置模式：只测试、不写入 .env，返回 attempts、耗时和脱敏后的错误信息。
• P2/P3 需要保持兼容默认值：Body 模板冲突先文档化，路由为空仍发送到全部已配置渠道，send_to_context() 不受普通渠道路由限制。
• P4/P5 建议先落最小闭环：进程内去重/冷却、静默时段解析、单渠道失败隔离、custom webhook partial failure 聚合，并用 ./scripts/ci_gate.sh 和通知专项测试覆盖。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[ZhuLinsen]

结论
PR #1205 已合并，合入 SHA 是 f9549c7，因此 P0 基线可以按已完成处理。当前 issue 还不建议关闭，因为 P1 到 P7 仍是后续通知网关能力的跟踪范围。

建议排查

• 下一步优先做 P1：复用现有 LLM 测试接口模式，新增通知测试接口和 NotificationTestPanel，重点保证临时配置不写入 .env、结果脱敏、custom webhook 多 URL attempts 可诊断。
• P2 不需要重写模板引擎，先把 CUSTOM_WEBHOOK_BODY_TEMPLATE 的覆盖语义、Bark 自动 payload 冲突、AstrBot / NapCat 示例补到 docs/notifications.md 和 Web 提示里。
• P3 路由建议先只落 NOTIFICATION_REPORT_CHANNELS、NOTIFICATION_ALERT_CHANNELS、NOTIFICATION_SYSTEM_ERROR_CHANNELS，默认空值继续保持“所有已配置渠道推送”。
• P4 降噪先用进程内状态即可，NOTIFICATION_DEDUP_TTL_SECONDS、NOTIFICATION_COOLDOWN_SECONDS、NOTIFICATION_QUIET_HOURS 等都保持默认关闭，并明确多 worker 只近似生效。
• P6 长尾渠道建议拆小 PR：AstrBot 先补配置和 Web 设置缺口，Bark 继续走 custom webhook preset，ntfy / Gotify 再作为独立一等渠道增量实现。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[ZhuLinsen]

结论
PR #1205 已合并（f9549c7），P0 可以视为完成；P1 目前仍以 draft PR #1218 为准，尚未合并，因此这个 umbrella issue 还不建议关闭。当前 issue 应继续跟踪 P2-P7，P1 的完成状态建议等 #1218 合并后再更新，避免进度表与实际状态不一致。

建议排查

• P1 优先收口 feat: 支持 P1 Web 通知渠道一键测试 (#1200) #1218：核对通知测试接口、临时配置不写入 .env、敏感信息脱敏、custom webhook 多 URL attempts，以及 Web NotificationTestPanel 复用边界。
• P2 基于 feat: support custom webhook body templates #1173 继续做产品化，不重写模板引擎；重点补 docs/notifications.md 中 Bark 自动 payload 与 CUSTOM_WEBHOOK_BODY_TEMPLATE 覆盖关系、AstrBot / NapCat 示例。
• P3/P4 新增配置默认关闭，NOTIFICATION_REPORT_CHANNELS、NOTIFICATION_DEDUP_TTL_SECONDS 等应标为 advanced，不进入首次启动必填检查。
• P5 测试重点放在路由后失败隔离、timeout、partial failure 聚合、降噪异常不阻断主流程，避免把 feat: add bot error notification for failed analysis tasks #1155 的 bot 局部反馈误算成通用通知网关完成。
• P6/P7 建议拆独立 PR 推进：AstrBot/Bark 先补齐体验与文档，ntfy/Gotify 再新增一等渠道，Actions 对照表尽量用脚本校验 daily_analysis.yml，减少后续漂移。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[ZhuLinsen]

结论
P0 已由 PR #1205 合入（f9549c7），P1 已由 PR #1218 合入（a4a619d），当前进度可以更新为 P0/P1 完成；#1217 是已关闭 draft，不应再作为 P1 状态依据。这个 umbrella issue 仍建议保持打开，用于继续跟踪 P2-P7。

建议排查

• 下一步优先推进 P2：在 docs/notifications.md 补 AstrBot、NapCat、Bark、通用 webhook 示例，并明确 CUSTOM_WEBHOOK_BODY_TEMPLATE 会覆盖 Bark / Slack / Discord 等自动 payload。
• P3 实现时保持默认兼容：NOTIFICATION_REPORT_CHANNELS、NOTIFICATION_ALERT_CHANNELS、NOTIFICATION_SYSTEM_ERROR_CHANNELS 未配置时仍走全部已配置渠道，send_to_context() 不受路由限制。
• P4 降噪配置建议全部标为 advanced，默认关闭；去重/冷却先用进程内状态，并在文档中说明 uvicorn --workers N 下是 per-worker 生效。
• P5 重点补通知测试与发送链路的边界测试：timeout、partial failure、敏感信息脱敏、单渠道失败不影响主流程、降噪异常不阻断通知。
• P6/P7 建议继续拆独立 PR：AstrBot/Bark 先补强现有能力，ntfy/Gotify 再新增 sender；文档收口时同步 .env.example、daily_analysis.yml、config registry、Web 设置页和 docs/CHANGELOG.md。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。