refactor(issue-1200): [feature]-dsa-后续开发规划：[通知渠道网关]-渠道基线、测试、bo

Author: ZhuLinsen

docs/CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - [修复] 收紧 ntfy 结构化校验，避免 URL 编码空白 topic 被误判为有效通知端点。
 - [文档] 补充 Bark custom webhook 示例和 WebPush / Apprise 通知渠道评估，明确本轮不新增运行时依赖或配置入口。
 - [修复] 聚合报告通知按静态渠道隔离发送失败，并补充自定义 Webhook 部分成功诊断与脱敏测试。
+- [文档] P7 收口：`docs/notifications.md` 补齐场景化章节，并接入 `scripts/generate_notification_actions_env_table.py` 的 Actions env 对照表自动生成/校验来源，保留与 workflow 的映射一致性。
 - [修复] 未配置 Tushare / Longbridge 凭据时不再实例化对应可选 fetcher，避免缺失凭据的数据源进入候选集。
 - [修复] Longbridge 遇到连接关闭类异常后会进入冷却期，并在美股/港股实时与日线请求中临时跳过该数据源，避免请求级频繁重连。
 - [修复] Pytdx 股票名称查询在全部服务器不可达时会短暂冷却，并在冷却期内跳过重复探测，减少无效拨号与告警噪音。

docs/notifications.md

@@ -35,43 +35,70 @@
 
 ## GitHub Actions 映射
 
-仓库自带 `.github/workflows/daily_analysis.yml` 只显式导入固定变量名。P0 补齐以下已存在发送链路所需的映射：
+仓库自带 `.github/workflows/daily_analysis.yml` 只显式透传固定变量，下面表直接来源于 `analyze` step 的 `env:`。更新 workflow 后先运行：
 
-- `CUSTOM_WEBHOOK_BODY_TEMPLATE`
-- `WEBHOOK_VERIFY_SSL`
-- `FEISHU_WEBHOOK_SECRET`
-- `FEISHU_WEBHOOK_KEYWORD`
-- `PUSHPLUS_TOPIC`
-
-P3 补齐以下通知路由映射：
-
-- `NOTIFICATION_REPORT_CHANNELS`
-- `NOTIFICATION_ALERT_CHANNELS`
-- `NOTIFICATION_SYSTEM_ERROR_CHANNELS`
-
-P4 补齐以下通知降噪映射：
-
-- `NOTIFICATION_DEDUP_TTL_SECONDS`
-- `NOTIFICATION_COOLDOWN_SECONDS`
-- `NOTIFICATION_QUIET_HOURS`
-- `NOTIFICATION_TIMEZONE`
-- `NOTIFICATION_MIN_SEVERITY`
-- `NOTIFICATION_DAILY_DIGEST_ENABLED`
-
-P6-A / P6-C 补齐以下 ntfy / Gotify 渠道映射：
+```bash
+python scripts/generate_notification_actions_env_table.py
+```
 
-- `NTFY_URL`
-- `NTFY_TOKEN`
-- `GOTIFY_URL`
-- `GOTIFY_TOKEN`
+<!-- GENERATED: notifications-actions-env-table -->
+| 通知环境变量 | workflow 映射表达式 |
+| --- | --- |
+| `WECHAT_WEBHOOK_URL` | `${{ secrets.WECHAT_WEBHOOK_URL }}` |
+| `WECHAT_MSG_TYPE` | `${{ vars.WECHAT_MSG_TYPE \|\| secrets.WECHAT_MSG_TYPE \|\| 'markdown' }}` |
+| `FEISHU_WEBHOOK_URL` | `${{ secrets.FEISHU_WEBHOOK_URL }}` |
+| `FEISHU_WEBHOOK_SECRET` | `${{ secrets.FEISHU_WEBHOOK_SECRET }}` |
+| `FEISHU_WEBHOOK_KEYWORD` | `${{ vars.FEISHU_WEBHOOK_KEYWORD \|\| secrets.FEISHU_WEBHOOK_KEYWORD }}` |
+| `TELEGRAM_BOT_TOKEN` | `${{ secrets.TELEGRAM_BOT_TOKEN }}` |
+| `TELEGRAM_CHAT_ID` | `${{ secrets.TELEGRAM_CHAT_ID }}` |
+| `TELEGRAM_MESSAGE_THREAD_ID` | `${{ secrets.TELEGRAM_MESSAGE_THREAD_ID }}` |
+| `EMAIL_SENDER` | `${{ vars.EMAIL_SENDER \|\| secrets.EMAIL_SENDER }}` |
+| `EMAIL_PASSWORD` | `${{ secrets.EMAIL_PASSWORD }}` |
+| `EMAIL_RECEIVERS` | `${{ vars.EMAIL_RECEIVERS \|\| secrets.EMAIL_RECEIVERS }}` |
+| `EMAIL_SENDER_NAME` | `${{ vars.EMAIL_SENDER_NAME \|\| secrets.EMAIL_SENDER_NAME \|\| 'daily_stock_analysis股票分析助手' }}` |
+| `PUSHOVER_USER_KEY` | `${{ secrets.PUSHOVER_USER_KEY }}` |
+| `PUSHOVER_API_TOKEN` | `${{ secrets.PUSHOVER_API_TOKEN }}` |
+| `NTFY_URL` | `${{ secrets.NTFY_URL }}` |
+| `NTFY_TOKEN` | `${{ secrets.NTFY_TOKEN }}` |
+| `GOTIFY_URL` | `${{ secrets.GOTIFY_URL }}` |
+| `GOTIFY_TOKEN` | `${{ secrets.GOTIFY_TOKEN }}` |
+| `PUSHPLUS_TOKEN` | `${{ secrets.PUSHPLUS_TOKEN }}` |
+| `PUSHPLUS_TOPIC` | `${{ vars.PUSHPLUS_TOPIC \|\| secrets.PUSHPLUS_TOPIC }}` |
+| `CUSTOM_WEBHOOK_URLS` | `${{ secrets.CUSTOM_WEBHOOK_URLS }}` |
+| `CUSTOM_WEBHOOK_BEARER_TOKEN` | `${{ secrets.CUSTOM_WEBHOOK_BEARER_TOKEN }}` |
+| `CUSTOM_WEBHOOK_BODY_TEMPLATE` | `${{ vars.CUSTOM_WEBHOOK_BODY_TEMPLATE \|\| secrets.CUSTOM_WEBHOOK_BODY_TEMPLATE }}` |
+| `DISCORD_WEBHOOK_URL` | `${{ secrets.DISCORD_WEBHOOK_URL }}` |
+| `DISCORD_BOT_TOKEN` | `${{ secrets.DISCORD_BOT_TOKEN }}` |
+| `DISCORD_MAIN_CHANNEL_ID` | `${{ secrets.DISCORD_MAIN_CHANNEL_ID }}` |
+| `FEISHU_APP_ID` | `${{ secrets.FEISHU_APP_ID }}` |
+| `FEISHU_APP_SECRET` | `${{ secrets.FEISHU_APP_SECRET }}` |
+| `FEISHU_FOLDER_TOKEN` | `${{ secrets.FEISHU_FOLDER_TOKEN }}` |
+| `ASTRBOT_URL` | `${{ secrets.ASTRBOT_URL }}` |
+| `ASTRBOT_TOKEN` | `${{ secrets.ASTRBOT_TOKEN }}` |
+| `SERVERCHAN3_SENDKEY` | `${{ secrets.SERVERCHAN3_SENDKEY }}` |
+| `SLACK_WEBHOOK_URL` | `${{ secrets.SLACK_WEBHOOK_URL }}` |
+| `SLACK_BOT_TOKEN` | `${{ secrets.SLACK_BOT_TOKEN }}` |
+| `SLACK_CHANNEL_ID` | `${{ secrets.SLACK_CHANNEL_ID }}` |
+| `NOTIFICATION_REPORT_CHANNELS` | `${{ vars.NOTIFICATION_REPORT_CHANNELS \|\| secrets.NOTIFICATION_REPORT_CHANNELS }}` |
+| `NOTIFICATION_ALERT_CHANNELS` | `${{ vars.NOTIFICATION_ALERT_CHANNELS \|\| secrets.NOTIFICATION_ALERT_CHANNELS }}` |
+| `NOTIFICATION_SYSTEM_ERROR_CHANNELS` | `${{ vars.NOTIFICATION_SYSTEM_ERROR_CHANNELS \|\| secrets.NOTIFICATION_SYSTEM_ERROR_CHANNELS }}` |
+| `NOTIFICATION_DEDUP_TTL_SECONDS` | `${{ vars.NOTIFICATION_DEDUP_TTL_SECONDS \|\| secrets.NOTIFICATION_DEDUP_TTL_SECONDS \|\| '0' }}` |
+| `NOTIFICATION_COOLDOWN_SECONDS` | `${{ vars.NOTIFICATION_COOLDOWN_SECONDS \|\| secrets.NOTIFICATION_COOLDOWN_SECONDS \|\| '0' }}` |
+| `NOTIFICATION_QUIET_HOURS` | `${{ vars.NOTIFICATION_QUIET_HOURS \|\| secrets.NOTIFICATION_QUIET_HOURS }}` |
+| `NOTIFICATION_TIMEZONE` | `${{ vars.NOTIFICATION_TIMEZONE \|\| secrets.NOTIFICATION_TIMEZONE }}` |
+| `NOTIFICATION_MIN_SEVERITY` | `${{ vars.NOTIFICATION_MIN_SEVERITY \|\| secrets.NOTIFICATION_MIN_SEVERITY }}` |
+| `NOTIFICATION_DAILY_DIGEST_ENABLED` | `${{ vars.NOTIFICATION_DAILY_DIGEST_ENABLED \|\| secrets.NOTIFICATION_DAILY_DIGEST_ENABLED \|\| 'false' }}` |
+<!-- END GENERATED: notifications-actions-env-table -->
+
+脚本也可用于 CI 校验：
 
-默认 workflow 仍不映射 `MARKDOWN_TO_IMAGE_CHANNELS` 与 `MERGE_EMAIL_NOTIFICATION`。它们是发送形态或聚合行为开关，不是渠道凭证；在 Actions 中自动开始读取同名 Secret/Variable 会引入额外行为变化。
+```bash
+python scripts/generate_notification_actions_env_table.py --check
+```
 
 ## CLI 诊断
 
-```bash
-python main.py --check-notify
-```
+`python main.py --check-notify`
 
 该命令只读配置，不发送通知，不写入 `.env`。它会在配置加载和日志初始化后立即执行，完成后直接退出，不再进入 Web、调度、大盘复盘或默认分析流程。
 
@@ -230,9 +257,30 @@ Apprise 后续如要引入，应先作为可选依赖评估，而不是默认依
 - 发送失败应隔离在 Apprise 渠道内，不能影响已有渠道的失败隔离语义。
 - 如果采用 Apprise，建议先新增单独 experimental channel 或 CLI-only spike，再决定是否纳入 Web 设置页和 Actions env。
 
-## 场景占位
+`MARKDOWN_TO_IMAGE_CHANNELS` 与 `MERGE_EMAIL_NOTIFICATION` 仍属于运行时行为开关，不在默认 `daily_analysis.yml` env 中显式映射。
+
+## 场景化接入
+
+### 本地配置
+
+- 以 `.env` 为主，优先级低于运行时环境变量。
+- 以 `python main.py --check-notify` 做首次一次性诊断，不会发送通知，不会写 `.env`。
+- 通知设置页可触发单渠道测试；`CUSTOM_WEBHOOK_URLS` 支持多 URL，结果返回每 URL 级别 attempts 聚合。
+
+### Docker
+
+- Docker 场景沿用同一配置加载路径，可直接复用 `.env`。
+- 建议通过 compose / 启动脚本将通知相关 env 全量注入，避免依赖默认值导致高级选项静默生效。
+- 若需 `WEBHOOK_VERIFY_SSL=false`，请仅在可信内网链路中开启。
+
+### GitHub Actions
+
+- 默认 workflow 只会读取 `analyze` step 下 `env:` 的显式变量；新增通知变量后要同时修改 workflow 映射。
+- 路由/降噪键建议放到 Variables；敏感值建议放 Secrets。
+- 非映射行为键（如 `MARKDOWN_TO_IMAGE_CHANNELS`）仍不会默认生效，除非同步扩展 workflow。
+
+### Desktop
 
-- Local：优先使用 `.env`，可用 `python main.py --check-notify` 做本地诊断。
-- Docker：配置来源与本地一致，需确保容器环境变量已注入。
-- GitHub Actions：只会读取 workflow `env:` 中显式映射的 Secret/Variable。
-- Desktop：桌面端内嵌 Web 设置页可复用同一通知测试入口；测试仍只使用临时配置，不写入 `.env`。
+- 桌面端直接复用 Web 设置页与通知测试面板，不会新增后端接口。
+- 本地运行和内嵌服务端行为一致，`send_to_context`、路由过滤和降噪都按同一后端配置解释。
+- 若需排障，优先使用 `--check-notify` 的 CLI 输出与同一 `NotificationTestPanel` 的 attempts 聚合结果核对。

scripts/generate_notification_actions_env_table.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Generate the notification env mapping table for docs from workflow metadata."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from pathlib import Path
+from typing import Dict, Iterable, List
+
+import yaml
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+WORKFLOW_PATH = ROOT_DIR / ".github/workflows/daily_analysis.yml"
+DOCS_PATH = ROOT_DIR / "docs/notifications.md"
+
+START_MARKER = "<!-- GENERATED: notifications-actions-env-table -->"
+END_MARKER = "<!-- END GENERATED: notifications-actions-env-table -->"
+
+NOTIFICATION_ENV_PREFIXES = (
+    "WECHAT_",
+    "FEISHU_",
+    "TELEGRAM_",
+    "EMAIL_",
+    "PUSHOVER_",
+    "NTFY_",
+    "GOTIFY_",
+    "PUSHPLUS_",
+    "CUSTOM_WEBHOOK_",
+    "DISCORD_",
+    "SLACK_",
+    "SERVERCHAN3_",
+    "ASTRBOT_",
+    "NOTIFICATION_",
+)
+
+
+def _load_workflow_env(path: Path = WORKFLOW_PATH) -> Dict[str, str]:
+    workflow = yaml.safe_load(path.read_text(encoding="utf-8"))
+    steps = workflow["jobs"]["analyze"]["steps"]
+    analyze_step = next(
+        (step for step in steps if step.get("name") == "执行股票分析"),
+        None,
+    )
+    assert analyze_step is not None, (
+        "Expected daily_analysis.yml job analyze to include a step named "
+        "'执行股票分析'."
+    )
+    return dict(analyze_step["env"])
+
+
+def _is_notification_env_key(key: str) -> bool:
+    return key.startswith(NOTIFICATION_ENV_PREFIXES)
+
+
+def extract_notification_env(env: Dict[str, str]) -> List[tuple[str, str]]:
+    return [(key, str(value)) for key, value in env.items() if _is_notification_env_key(key)]
+
+
+def _clean_mapping_cell(value: str) -> str:
+    escaped = value.replace("|", "\\|")
+    return f"`{escaped}`"
+
+
+def build_actions_env_table(
+    notification_items: Iterable[tuple[str, str]],
+) -> str:
+    rows = [
+        "| 通知环境变量 | workflow 映射表达式 |",
+        "| --- | --- |",
+    ]
+
+    for key, value in notification_items:
+        rows.append(f"| `{key}` | {_clean_mapping_cell(value)} |")
+
+    return "\n".join(rows)
+
+
+def build_marked_table_block(notification_items: Iterable[tuple[str, str]]) -> str:
+    return "\n".join(
+        [
+            START_MARKER,
+            build_actions_env_table(notification_items),
+            END_MARKER,
+        ]
+    )
+
+
+def _extract_marked_block(text: str) -> str:
+    start = text.index(START_MARKER)
+    end = text.index(END_MARKER)
+    if end < start:
+        raise ValueError("Invalid marker order in docs.")
+    return text[start + len(START_MARKER) : end].strip("\n")
+
+
+def sync_docs(
+    *,
+    docs_path: Path = DOCS_PATH,
+    workflow_path: Path = WORKFLOW_PATH,
+    check_only: bool = False,
+) -> int:
+    workflow_env = _load_workflow_env(workflow_path)
+    notification_items = extract_notification_env(workflow_env)
+    expected_block = build_marked_table_block(notification_items)
+
+    docs_text = docs_path.read_text(encoding="utf-8")
+    if START_MARKER not in docs_text or END_MARKER not in docs_text:
+        raise ValueError(
+            f"Docs file {docs_path} is missing table markers:"
+            f"\n{START_MARKER}\n{END_MARKER}"
+        )
+
+    old_block_with_markers = f"{START_MARKER}\n{_extract_marked_block(docs_text)}\n{END_MARKER}"
+    if old_block_with_markers == expected_block:
+        return 0
+
+    if check_only:
+        return 1
+
+    new_text = docs_text.replace(old_block_with_markers, expected_block)
+    docs_path.write_text(new_text, encoding="utf-8")
+    return 0
+
+
+def _build_parser() -> ArgumentParser:
+    parser = ArgumentParser(
+        description="Render/同步每日分析 workflow 的通知环境变量对照表到 docs。"
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="检查 docs 表与 workflow 提取结果是否一致，不写文件。")
+    parser.add_argument(
+        "--workflow", default=str(WORKFLOW_PATH), help="daily_analysis workflow 路径。"
+    )
+    parser.add_argument(
+        "--docs", default=str(DOCS_PATH), help="通知文档路径。"
+    )
+    return parser
+
+
+def main(argv: List[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    return sync_docs(
+        docs_path=Path(args.docs),
+        workflow_path=Path(args.workflow),
+        check_only=args.check,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_daily_analysis_workflow_notification_env.py

@@ -2,6 +2,7 @@
 """Static checks for notification env mappings in daily_analysis.yml."""
 
 from pathlib import Path
+from scripts.generate_notification_actions_env_table import sync_docs
 
 import yaml
 
@@ -67,3 +68,7 @@ def test_daily_analysis_keeps_deferred_behavior_switches_unmapped() -> None:
 
     for key in P0_EXCLUDED_BEHAVIOR_SWITCHES:
         assert key not in env
+
+
+def test_daily_analysis_notification_actions_env_table_sync() -> None:
+    assert sync_docs(check_only=True) == 0