收口 Issue #1200 通知能力文档与 Actions 映射校验 P7

[massif-01]

PR Type

• fix
• feat
• refactor
• docs
• chore
• test

Background And Problem

Issue #1200 已按阶段完成通知能力基线、Web 测试、Body 模板、路由、降噪、聚合报告失败隔离、ntfy / Gotify 一等渠道，以及 WebPush / Apprise 评估。

P7 是整个 issue 的收尾阶段：把通知专题文档补齐到本地 / Docker / GitHub Actions / Desktop 四类使用场景，并把 GitHub Actions 通知 env 对照表改成可自动生成和校验，避免后续 workflow env 与文档手写表格继续漂移。

本 PR 不新增运行时依赖、不新增配置项、不修改通知发送逻辑、不修改 API / Web schema / workflow env。

Scope Of Change

• 新增 scripts/generate_notification_actions_env_table.py
  • 从 src.services.notification_diagnostics.KEY_SPECS 读取通知 key 元数据。
  • 复用 P0_ACTIONS_ENV_KEYS、P3_ROUTE_ENV_KEYS、P4_NOISE_ACTIONS_ENV_KEYS、P6_CHANNEL_ACTIONS_ENV_KEYS 校验默认 daily workflow 必需映射。
  • 从 .github/workflows/daily_analysis.yml 的 执行股票分析 step env: 生成 GitHub Actions 通知 env 表。
  • 支持 --write 更新文档 marker 区块，支持 --check 检查文档是否漂移。
• 更新 docs/notifications.md
  • 收口为 P0-P7 终态说明。
  • 保留 Actions 映射设计说明，并在 HTML marker 内放置自动生成表格。
  • 扩充本地、Docker、GitHub Actions、Desktop、回滚方式说明。
• 更新 tests/test_daily_analysis_workflow_notification_env.py
  • 校验 docs/notifications.md marker 表格与脚本生成结果一致。
  • 使用 P4 Actions 专用常量，避免把非 Actions 映射语义混入测试。
• 更新 docs/full-guide.md / docs/full-guide_EN.md
  • 同步通知专题文档入口文案。
• 更新 docs/CHANGELOG.md
  • 在 [Unreleased] 增加扁平格式文档条目。

Issue Link

Fixes #1200

Verification Commands And Results

python -m py_compile scripts/generate_notification_actions_env_table.py tests/test_daily_analysis_workflow_notification_env.py
python scripts/generate_notification_actions_env_table.py --check
python -m pytest tests/test_daily_analysis_workflow_notification_env.py tests/test_notification_diagnostics.py -q
PATH=.venv/bin:$PATH ./scripts/ci_gate.sh
git diff --check

关键输出/结论：

• py_compile：通过。
• generate_notification_actions_env_table.py --check：通过，文档表格与 workflow/env 元数据一致。
• targeted pytest：22 passed。
• ci_gate.sh：1925 passed, 2 deselected, 42 warnings, 166 subtests passed，backend-gate: all checks passed。
• git diff --check：通过。

Compatibility And Risk

兼容性影响：无运行时兼容性变化。本 PR 只改文档、生成脚本和文档一致性测试，不修改通知发送、配置加载、API、Web schema、workflow env 或默认行为。

风险：

• 表格生成脚本依赖 .github/workflows/daily_analysis.yml 中 执行股票分析 step 名称；如果后续 workflow 重命名该 step，--check 和测试会明确失败，提示维护者同步脚本或 workflow。
• --check 只校验通知相关 key 的 Actions 映射与文档表格一致，不会改变 workflow 行为。

Rollback Plan

Revert this PR 即可回滚。无需数据迁移、配置清理或运行时回滚；如已在本地使用 --write 更新文档，只需恢复 docs/notifications.md 对应 diff。

EXTRACT_PROMPT Change (if applicable)

不适用。本 PR 未修改 src/services/image_stock_extractor.py 或 EXTRACT_PROMPT。

展开 / Expand: Full EXTRACT_PROMPT

N/A

Checklist

• 本 PR 有明确动机和业务价值 / This PR has a clear motivation and value
• 已提供可复现的验证命令与结果 / Reproducible verification commands and results are included
• 已评估兼容性与风险 / Compatibility and risk have been assessed
• 已提供回滚方案 / A rollback plan is provided
• 若涉及用户可见变更，已同步更新相关文档与 docs/CHANGELOG.md；README.md 仅在首页级信息变化时更新，细节优先写入 docs/*.md / If user-visible changes are included, relevant docs and docs/CHANGELOG.md are updated; README.md is updated only for homepage-level changes, with details kept in docs/*.md

[github-actions]

🤖 自动审查报告

项目	结果
📊 变更文件	6 个
➕ 新增行数	342 行
➖ 删除行数	41 行
🔍 静态检查	✅ 通过
🧠 AI 审查	✅ 已完成

📁 修改的文件

• 📝 docs/CHANGELOG.md (+1/-0)
• 📝 docs/full-guide.md (+3/-3)
• 📝 docs/full-guide_EN.md (+3/-3)
• 📝 docs/notifications.md (+82/-33)
• 🆕 scripts/generate_notification_actions_env_table.py (+238/-0)
• 📝 tests/test_daily_analysis_workflow_notification_env.py (+15/-2)

---

🧠 AI 代码审查意见

结论： Ready to Merge

---

结构化审查结果：

• 必要性： 通过

  • 理由： 本 PR 是 Issue [Feature] DSA 后续开发规划：[通知渠道网关] 渠道基线、测试、Body 模板、路由、降噪与长尾渠道扩展 #1200 (通知能力专项) 的 P7 收尾阶段，旨在补齐通知专题文档，覆盖本地、Docker、GitHub Actions、Desktop 四类使用场景，并自动化 GitHub Actions 通知环境变量对照表的生成和校验，以解决文档与实际 workflow 漂移的问题。这些都是明确且有价值的需求。

• 关联性： 通过

  • 证据： PR 描述明确指出 Fixes #1200，并详细说明了其作为该 Issue 收尾阶段 (P7) 的背景和目标。

• 类型： docs, test

  • 建议： PR 提交的类型 docs 和 test 与变更内容完全匹配。主要工作是文档更新，以及新增一个生成文档内容和验证文档一致性的脚本及对应的测试。

• 描述完整性： 完整

  • 缺失项： 无。PR 描述包含了所有必要部分：背景与问题、变更范围、验证命令与结果、兼容性与风险评估、回滚方案、用户可见变更同步、以及完整的 Checklist。
  • ./scripts/ci_gate.sh 的执行结果已在“Verification Commands And Results”中明确给出，且通过。

• 风险级别： 低

  • 关键风险：
    • 本 PR 不修改运行时逻辑、不新增依赖、不修改 API 或默认行为，仅涉及文档、文档生成脚本及其测试，因此运行时兼容性风险极低。
    • 文档中明确指出了生成脚本对 daily_analysis.yml 中 执行股票分析 step 名称的依赖。如果该 step 被重命名，--check 和测试将明确失败，提示维护者进行同步。这种主动的风险识别和应对机制是良好的实践。
    • validate_required_mappings 函数的存在确保了关键通知环境变量在 workflow 中的映射不会缺失，从而避免了未来的漂移风险。

必改项： 无。

建议项： 无。本次 PR 质量很高，文档清晰，逻辑严谨，自动化校验机制设计得当。

---

💡 提示: 请确保代码已通过本地测试，并遵循项目代码规范。

[ZhuLinsen]

评审结论

• 必要性：通过 + P7 收口通知专题文档，并把 Actions env 对照表纳入生成与校验，能降低文档和 workflow 映射漂移风险。
• 是否有对应 issue：有，Fixes #1200。
• PR 类型：docs/test + 主要是文档收口，同时新增生成脚本和静态测试保障文档一致性。
• description 完整性：完整 + 已说明背景、范围、兼容性、风险、验证命令与结果、回滚方案，并符合 AGENTS.md 对文档变更和 changelog 的要求。
• 是否可直接合入：可 + 当前 CI 成功，改动范围集中在文档、生成脚本与测试，未发现行为/兼容性阻断点。

---

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

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. More of your lovely PRs please.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".