通知能力基线

本文档记录通知能力 P0-P7 终态：渠道、配置 key、GitHub Actions 映射、Web 设置元数据、CLI 诊断口径、Web 一键测试、自定义 Webhook Body 模板语义、通知路由策略、降噪机制、聚合报告失败隔离、ntfy / Gotify 一等渠道、WebPush / Apprise 评估，以及本地 / Docker / GitHub Actions / Desktop 场景化配置说明。P0 只做基线与只读诊断；P1 增加 Web 单渠道真实测试；P2 产品化现有 Body 模板；P3 增加 report / alert / system_error 路由；P4 增加进程内降噪；P5 强化测试诊断和聚合报告逐渠道失败隔离；P6-A 新增 ntfy；P6-C 新增 Gotify；P6-D 只评估 WebPush / Apprise；P7 收口文档与 Actions env 对照表自动化，不新增运行时依赖、配置入口、per-URL 模板、跨进程持久化、真实每日摘要或重试循环。

渠道基线

Minimal / Advanced 分层

• Minimal key：足以启用一个通知渠道的最小配置。
• Advanced key：只影响认证、安全、格式、线程、群组、证书校验或展示行为，不能单独启用渠道。
• P3 的 NOTIFICATION_*_CHANNELS 属于 Advanced key：只收窄已启用渠道，不会单独启用渠道。
• P4 的 NOTIFICATION_DEDUP_TTL_SECONDS、NOTIFICATION_COOLDOWN_SECONDS、NOTIFICATION_QUIET_HOURS、NOTIFICATION_TIMEZONE、NOTIFICATION_MIN_SEVERITY、NOTIFICATION_DAILY_DIGEST_ENABLED 属于 Advanced key：只影响已启用静态渠道的发送策略，不会单独启用渠道。
• REPORT_SHOW_LLM_MODEL 是报告展示开关：默认 true 时在通知报告底部显示本次分析使用的 LLM 模型，设为 false 时隐藏。该参数仅影响报告渲染，不会更改运行时的 provider/model/Base URL、LiteLLM 路由、模型保存、迁移或清理逻辑；回退方式为改回 true 或删除该变量。
• WEBHOOK_VERIFY_SSL 是读取该配置的 webhook-style HTTPS 通知请求共用的证书校验开关。
• WebPush、Apprise、更细粒度路由、跨进程降噪和真实每日摘要暂不进入运行时实现；相关配置如未来引入，应先更新本文档、.env.example、Web 元数据与回归测试。
• Bark 保持 custom webhook 基线，不新增 BARK_* 一等配置。

GitHub Actions 映射

仓库自带 .github/workflows/daily_analysis.yml 只显式导入固定变量名。P0/P3/P4/P6 已把 Body 模板、安全项、PushPlus topic、路由、降噪、ntfy 和 Gotify 等通知 key 纳入默认 workflow。下面的表格由 scripts/generate_notification_actions_env_table.py 从 workflow env: 和通知诊断元数据生成，避免手写对照表和真实 Actions 映射继续漂移。

默认 workflow 仍不映射 MARKDOWN_TO_IMAGE_CHANNELS 与 MERGE_EMAIL_NOTIFICATION。它们是发送形态或聚合行为开关，不是渠道凭证；在 Actions 中自动开始读取同名 Secret/Variable 会引入额外行为变化。

CLI 诊断

python main.py --check-notify

该命令只读配置，不发送通知，不写入 .env。它会在配置加载和日志初始化后立即执行，完成后直接退出，不再进入 Web、调度、大盘复盘或默认分析流程。

• 返回码 0：没有 error 级诊断。
• 返回码 1：存在 error，例如 0 个静态通知渠道已配置，或成对 key 只配置了一半。

Web 一键测试

Web 设置页的“通知渠道”分类提供单渠道测试入口。测试会使用当前页面草稿值合成临时配置，发送一条真实测试通知，但不会保存 .env，也不会修改运行时全局配置。

• 测试范围：13 个静态通知渠道，不包含 UNKNOWN 和运行时上下文渠道。
• 普通渠道：返回单次发送结果、耗时和通用错误码。
• 自定义 Webhook：按 URL 顺序返回 attempts，展示每个 URL 的成功/失败、HTTP 状态、耗时和错误码；多个 URL 部分成功时，顶层 message 会标出成功数 / 总数。
• 返回结果会脱敏 token、secret、password、Bearer、完整 webhook query 和疑似 path token。
• 配置缺失或发送失败返回 success=false，不会影响已保存配置和默认分析流程。

自定义 Webhook Body 模板

CUSTOM_WEBHOOK_BODY_TEMPLATE 是自定义 Webhook 的全局 JSON body 模板。配置后，它会先于 URL 自动识别生效，因此会覆盖 Bark、Slack、Discord、钉钉等自动 payload。未配置时仍使用原有 URL 自动识别；渲染后不是合法 JSON object 时会记录错误并回退默认 payload，不中断主通知流程。

可用占位符：

• $content_json：JSON 转义后的通知正文，推荐默认使用。
• $title_json：JSON 转义后的通知标题，推荐默认使用。
• $content / $title：原始字符串，不做 JSON 转义。正文含双引号、反斜杠或换行时可能导致 JSON 无效并触发 fallback。

通用 webhook 示例：

CUSTOM_WEBHOOK_BODY_TEMPLATE={"title":$title_json,"content":$content_json}

Bark 通过 custom webhook 使用时，直接把 Bark endpoint 放入 CUSTOM_WEBHOOK_URLS，不需要额外 BARK_* 配置。未配置全局模板时，系统会按 api.day.app 自动生成 title / body / group；如果配置全局模板，需要自己写出 Bark body：

CUSTOM_WEBHOOK_URLS=https://api.day.app/YOUR_BARK_KEY

CUSTOM_WEBHOOK_BODY_TEMPLATE={"title":$title_json,"body":$content_json,"group":"stock"}

AstrBot 已是一等通知渠道，优先使用 ASTRBOT_URL 和可选的 ASTRBOT_TOKEN。只有需要把 AstrBot 兼容端点放入 CUSTOM_WEBHOOK_URLS 时，才使用 custom webhook 模板，例如：

CUSTOM_WEBHOOK_BODY_TEMPLATE={"content":$content_json}

ntfy 已是一等通知渠道，优先使用 NTFY_URL 和可选的 NTFY_TOKEN。NTFY_URL 表示完整 topic endpoint，例如 https://ntfy.sh/my-topic 或 https://self-hosted:port/my-topic；系统会解析最后一个 path segment 作为 topic，并向 server root 发送 JSON publish：

NTFY_URL=https://ntfy.sh/my-topic
NTFY_TOKEN=

Gotify 已是一等通知渠道，优先使用 GOTIFY_URL 和 GOTIFY_TOKEN。GOTIFY_URL 表示 Gotify server base URL，可包含反向代理 path prefix，但不包含 /message；系统发送时会拼接固定 /message API，并通过 X-Gotify-Key Header 发送 application token。NTFY_URL 是完整 topic endpoint，而 GOTIFY_URL 是 server base URL，这是两个服务 API 设计差异导致的刻意选择：

GOTIFY_URL=https://gotify.example
GOTIFY_TOKEN=app-token

# 反向代理 path prefix 示例；实际请求会发送到 https://example.com/gotify/message
GOTIFY_URL=https://example.com/gotify
GOTIFY_TOKEN=app-token

NapCat / OneBot HTTP API 需要按实际 endpoint 和目标类型调整。下面只是常见 body 形态示例，user_id、group_id、URL 路径和鉴权方式都应以你的 NapCat 配置为准：

# 私聊：CUSTOM_WEBHOOK_URLS=http://127.0.0.1:3000/send_private_msg
CUSTOM_WEBHOOK_BODY_TEMPLATE={"user_id":123456,"message":$content_json}

# 群聊：CUSTOM_WEBHOOK_URLS=http://127.0.0.1:3000/send_group_msg
CUSTOM_WEBHOOK_BODY_TEMPLATE={"group_id":123456789,"message":$content_json}

通知路由策略

P3 新增三类通知路由配置：

配置值为逗号分隔渠道枚举：wechat,feishu,telegram,email,pushover,ntfy,gotify,pushplus,serverchan3,custom,discord,slack,astrbot。

• 留空或未配置：保持旧行为，发送到所有已配置静态渠道。
• 非空：只发送到路由列表与已配置渠道的交集；交集为空时不会 fallback 到全渠道。
• send_to_context() 不受路由限制，机器人会话上下文仍会收到触发任务的回复。
• 路由过滤发生在 Markdown 转图片前，MARKDOWN_TO_IMAGE_CHANNELS 只对路由后的渠道子集生效。
• MERGE_EMAIL_NOTIFICATION 不需要额外配置；只要 email 仍在 report 路由后的渠道中，现有合并邮件行为保持不变。
• --check-notify 会把未知渠道值报为 error，把合法但未启用的路由目标报为 warning。

聚合报告失败隔离

P5 强化聚合报告通知路径的失败边界：_send_notifications() 在 report 路由过滤后对每个静态通知渠道单独发送。某个渠道抛异常会记录日志并视为该渠道失败，但不会跳过后续渠道，也不会中断分析主流程。

• 邮件按 receiver group 单独隔离；某个收件人分组失败时，后续分组仍会继续发送。
• 任一静态渠道发送成功时，P4 降噪 reservation 会写入正式记录；全部静态渠道失败或抛异常时，会释放 reservation。
• send_to_context() 仍独立于静态渠道 route 和降噪记录，用于回复触发任务的 Bot 会话上下文。

通知降噪机制

P4 新增进程内降噪，只影响静态配置渠道，不影响 send_to_context() 的机器人触发会话回执。默认所有配置关闭，未设置时保持旧行为。

严重级别默认值：

• report：info
• alert：warning
• system_error：error
• 未知或未设置路由：info

实现边界：

• 去重 / 冷却状态是当前 Python 进程内 dict，适用于 main.py 单进程和 --serve 单 worker。
• uvicorn --workers N、多容器或多台机器场景下状态不共享，降噪为 per-worker 近似生效。
• pipeline 单股和聚合报告路径使用稳定 key，避免报告内生成时间变化击穿去重；其他未显式传入 dedup_key 的 report 通知按内容 hash 去重。
• 未显式传入 cooldown_key 的调用按路由和严重级别共享默认冷却槽位，例如 report / info 的普通通知会共用同一个槽位。
• 同一进程内相同 key 的并发发送会先占用短生命周期 in-flight 槽位，避免突发重复发送；静态渠道全部失败时释放该槽位，不写入正式去重 / 冷却状态。
• 降噪判断异常时 fail-open：记录日志并继续发送静态渠道。
• NOTIFICATION_TIMEZONE 留空时使用 datetime.now().astimezone() 解析到的运行时本地时区；Actions / Docker 场景建议显式配置 NOTIFICATION_TIMEZONE 以避免时区歧义。

WebPush / Apprise 评估

P6-D 只做设计评估，不新增依赖、.env 配置或运行时通知路径。结论是两者都不适合在本轮直接混入渠道实现 PR。

WebPush 后续如要实现，需要先单独设计订阅生命周期与安全边界：

• 需要 Web 前端注册 Service Worker；Service Worker / PushManager.subscribe() 依赖 secure context，生产环境通常必须走 HTTPS，本地开发可使用 localhost。
• 需要 VAPID 公私钥；订阅时要下发 public key，服务端发送时要持有 private key 并保护好密钥轮换策略。
• 需要浏览器权限交互，订阅必须由用户手势触发，不能在后台静默开启。
• PushSubscription 包含 endpoint 和加密 key，endpoint 属于 capability URL，应按 secret 处理并脱敏展示。
• 需要持久化订阅、处理订阅失效和设备解绑；当前 .env / 单进程配置模型不适合直接塞多个用户/设备订阅。
• 提交、删除、更新订阅的 API 要有认证和 CSRF 防护，不能只靠前端隐藏入口。

Apprise 后续如要引入，应先作为可选依赖评估，而不是默认依赖：

• Apprise 是通用通知库，覆盖面广，但会与当前已有 WeChat、Telegram、Discord、Slack、ntfy、Gotify、Pushover 等一等渠道重叠。
• 需要评估依赖体积、安装失败路径、Docker 镜像膨胀、GitHub Actions 依赖缓存和可选 extras 策略。
• secret 传递不能直接暴露完整 Apprise URL；需要统一脱敏、Web 测试目标遮罩和错误日志过滤。
• 发送失败应隔离在 Apprise 渠道内，不能影响已有渠道的失败隔离语义。
• 如果采用 Apprise，建议先新增单独 experimental channel 或 CLI-only spike，再决定是否纳入 Web 设置页和 Actions env。

本地配置

本地运行优先使用项目根目录 .env。复制 .env.example 后填写至少一个 minimal key 即可启用对应静态通知渠道；advanced key 只改变认证、安全、格式、路由或降噪行为，不会单独启用渠道。

python main.py --check-notify

--check-notify 是只读诊断：不发送通知、不写 .env、不进入分析流程。配置好 WebUI 后，也可以在系统设置页用单渠道测试发送真实测试消息；该测试只使用页面草稿临时配置，不保存 .env。

Docker

Docker 场景可通过 --env-file .env / Compose env_file 注入运行时环境变量，也可以挂载 .env 让 Web 设置页和后端读写同一份配置文件。只注入环境变量但不挂载 .env 时，Web 设置页保存后的值在容器重启后可能被部署环境再次覆盖。

降噪静默时段建议显式配置 NOTIFICATION_TIMEZONE，避免容器默认时区与预期不一致。自签名内网 webhook 可临时使用 WEBHOOK_VERIFY_SSL=false，但不要在公网链路关闭证书校验。

GitHub Actions

默认 daily_analysis.yml 只读取表格中显式映射的 Secret / Variable。新增 repository Secret 或 Variable 后，只有变量名已经出现在 workflow env: 中才会进入运行进程；STOCK_GROUP_N / EMAIL_GROUP_N 这类任意编号变量不会自动导入。

Secret 适合 token、password、webhook URL 等敏感项；Variable 适合 WECHAT_MSG_TYPE、EMAIL_SENDER_NAME、路由、降噪窗口和时区这类非敏感行为配置。MARKDOWN_TO_IMAGE_CHANNELS 与 MERGE_EMAIL_NOTIFICATION 默认不映射，如需在自己的 fork 中使用，应显式修改 workflow 并补充对应测试。

Desktop

桌面端复用 Web 设置页的通知配置和单渠道测试入口。通知测试会发送真实测试消息，但只使用当前页面草稿值，不会自动保存；需要持久化时仍需点击保存配置。

桌面端可通过配置导出 / 导入恢复 .env。回滚某个通知渠道时，清空该渠道 minimal key 并保存即可；advanced key 留存不会单独启用渠道，但建议同步清理以减少后续排障噪音。

回滚方式

• 本地 / Docker：恢复旧 .env，或删除对应渠道 minimal key 后重启进程。
• GitHub Actions：清空或删除对应 Secret / Variable；未映射的 key 不会进入 workflow 运行进程。
• Desktop：使用配置备份导入旧 .env，或在设置页清空对应渠道配置并保存。
• 版本回退：P6/P7 新增的 NTFY_*、GOTIFY_*、路由和降噪 key 在旧版本中会被忽略；若要避免误导，应同时从 .env 或 Actions 配置中移除。