docs #1200: 产品化自定义 Webhook Body 模板 P2

[massif-01]

PR Type

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

Background And Problem

Issue #1200 的 P2 要求将已有的 CUSTOM_WEBHOOK_BODY_TEMPLATE 能力产品化：明确全局 Body 模板会先于 Bark / Slack / Discord 等 URL 自动识别 payload 生效，补齐 JSON 占位符使用说明、Bark 冲突处理方案，以及 AstrBot / NapCat / 通用 webhook 示例。

本 PR 不重写通知框架，不新增配置，不改变通知发送行为，只补齐当前实现语义的文档、Web 设置提示和回归测试。

Scope Of Change

• 更新自定义 Webhook Body 模板的配置说明：src/core/config_registry.py、apps/dsa-web/src/utils/systemConfigI18n.ts、.env.example。
• 增加回归测试：锁定 Bark URL 配置全局模板时模板优先，以及 $content_json / $title_json 的 JSON 转义行为。
• 更新通知专题文档和中英文完整指南：补充全局模板优先级、fallback 语义、Bark / AstrBot custom / NapCat 示例。
• 更新 docs/CHANGELOG.md 的 [Unreleased] 扁平条目。

Issue Link

Refs #1200

Verification Commands And Results

python -m pytest tests/test_notification_sender.py::TestCustomWebhookSender tests/test_config_registry.py -q
cd apps/dsa-web && npm run test -- src/components/settings/__tests__/SettingsField.test.tsx
cd apps/dsa-web && npm run lint
cd apps/dsa-web && npm run build
git diff --check
./scripts/ci_gate.sh

关键输出/结论：

• tests/test_notification_sender.py::TestCustomWebhookSender tests/test_config_registry.py：31 passed。
• SettingsField.test.tsx：3 passed。
• npm run lint：通过。
• npm run build：通过；Vite 输出既有 chunk size warning。
• git diff --check：通过。
• ./scripts/ci_gate.sh：1733 passed, 2 deselected, backend-gate all checks passed。

Compatibility And Risk

不改变运行时发送逻辑、不新增环境变量、不修改 API schema、不迁移或改写用户 .env。已有用户未配置 CUSTOM_WEBHOOK_BODY_TEMPLATE 时仍走原 URL 自动识别 payload；配置错误模板时仍回退默认 payload。

主要风险是用户直接复制 NapCat / OneBot 示例到不同部署，因此文档中已明确 endpoint、user_id、group_id 和鉴权方式需要按实际 NapCat 配置调整。

Rollback Plan

最小回滚方式是 revert this PR；无需额外数据或配置迁移。用户侧如需恢复原自动 payload 行为，只需清空 CUSTOM_WEBHOOK_BODY_TEMPLATE。

EXTRACT_PROMPT Change (if applicable)

未修改 src/services/image_stock_extractor.py 中的 EXTRACT_PROMPT。

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]

🤖 自动审查报告

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

📁 修改的文件

• 📝 .env.example (+1/-1)
• 📝 apps/dsa-web/src/components/settings/__tests__/SettingsField.test.tsx (+33/-0)
• 📝 apps/dsa-web/src/utils/systemConfigI18n.ts (+2/-0)
• 📝 docs/CHANGELOG.md (+1/-0)
• 📝 docs/full-guide.md (+14/-2)
• 📝 docs/full-guide_EN.md (+19/-2)
• 📝 docs/notifications.md (+42/-2)
• 📝 src/core/config_registry.py (+4/-2)
• 📝 tests/test_notification_sender.py (+41/-0)

---

🧠 AI 代码审查意见

结论

Ready to Merge

结构化审查结果

• 必要性：通过。本 PR 旨在将已有的 CUSTOM_WEBHOOK_BODY_TEMPLATE 功能产品化，通过完善文档、Web 设置界面提示和增加回归测试来明确其语义和使用方式。这解决了 Issue [Feature] DSA 后续开发规划：[通知渠道网关] 渠道基线、测试、Body 模板、路由、降噪与长尾渠道扩展 #1200 的 P2 阶段需求，有明确的业务价值和用户体验提升。

• 关联性：通过。PR 描述中明确指出 Refs #1200，与 Issue 有清晰的关联。

• 类型：通过。PR Type 选择了 docs 和 test，这与实际的修改内容高度匹配。主要变更集中在文档更新、Web UI 提示的本地化以及新增回归测试，以确保现有行为的正确性与清晰度。

• 描述完整性：完整。

  • 背景与问题：清晰阐述了 Issue [Feature] DSA 后续开发规划：[通知渠道网关] 渠道基线、测试、Body 模板、路由、降噪与长尾渠道扩展 #1200 P2 的需求和本 PR 的范围。
  • 变更范围：详尽列出了受影响的文件和变更内容类型。
  • 验证命令与结果：提供了详细的验证命令和通过结果，包括 pytest、npm test、npm lint、npm build、git diff --check 和 ./scripts/ci_gate.sh，验证充分。上方 CI 检查状态也确认了 py_compile 和 flake8 的通过。
  • 兼容性与风险：对兼容性进行了评估，明确表示不改变运行时发送逻辑，主要风险已在文档中通过说明进行缓解。
  • 回滚方案：提供了明确的回滚方案。
  • 用户可见变更：CHANGELOG.md 和相关文档（docs/full-guide.md, docs/full-guide_EN.md, docs/notifications.md）已同步更新。
  • 微小不一致：PR 描述的 "Scope Of Change" 中提到了 .env.example，但在 "修改文件列表" 和实际 diff 中并未显示对该文件的修改。考虑到 CUSTOM_WEBHOOK_BODY_TEMPLATE 是一个环境变量，更新 .env.example 会有助于新用户发现和理解此配置。此为建议项。

• 风险级别：低。本 PR 不涉及核心逻辑重写、不新增配置项、不改变通知发送行为，而是对现有能力的文档化和测试增强。主要风险在于用户可能未仔细阅读文档而直接复制 NapCat / OneBot 示例，但文档中已明确提醒用户根据实际情况调整，风险已得到有效缓解。

• 必改项：无。代码正确性、安全性、CI 检查、PR 描述与改动一致性以及回滚方案均符合要求，无阻断合入的问题。

• 建议项：

  1. 更新 .env.example：PR 描述的 "Scope Of Change" 中提到了更新 .env.example，但实际 diff 未显示此变更。建议在 .env.example 中增加 CUSTOM_WEBHOOK_BODY_TEMPLATE 的示例配置和简要说明，以便新用户更容易发现和理解此功能。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过。本 PR 围绕 #1200 补齐既有 CUSTOM_WEBHOOK_BODY_TEMPLATE 能力的用户可见说明、Web 设置提示和回归测试，符合产品化文档诉求。
• 是否有对应 issue：有，Refs #1200。
• PR 类型：docs/test。主体是文档与配置说明更新，同时补充通知发送和 Web 设置展示的回归测试。
• description 完整性：完整。已说明背景、范围、验证命令与结果、兼容性风险、回滚方式，并符合 AGENTS.md 对用户可见变更同步 docs/CHANGELOG.md 的要求。
• 是否可直接合入：可。当前 CI 为 success，改动范围与描述一致；mergeable_state=blocked 更像受分支保护规则限制，不构成本身不可合入理由。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过。围绕 #1200 补齐既有 CUSTOM_WEBHOOK_BODY_TEMPLATE 的产品化说明、Web 设置提示和回归测试，符合用户可见能力文档化要求。
• 是否有对应 issue：有，Refs #1200。
• PR 类型：docs/test。主体是文档与配置说明更新，同时补充通知发送和 Web 设置展示的回归测试。
• description 完整性：完整。已说明背景、范围、验证命令与结果、兼容性风险、回滚方式，并同步 docs/CHANGELOG.md；未更新 README.md 符合 AGENTS.md 对首页级信息的约束。
• 是否可直接合入：可。当前 CI 为 success；本地 diff 未看到运行时发送逻辑、API schema、模型/provider/Base URL 或用户配置清理迁移变更，mergeable_state=blocked 属保护策略状态，本身不构成合入阻断。

---

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

[ZhuLinsen]

@massif-01 佬解下冲突

[ZhuLinsen]

跟进结论

• 结论：部分接受 + 前序“可直接合入”需要收缩；当前文档/测试对全局模板优先级和 JSON 占位符语义的说明成立，但 PR 当前仍有合并冲突。
• 是否仍有阻断：有 + 阻断点是当前 merge 状态存在冲突，需先解冲突后再合入；CI 本身已通过。

说明

1. docs/notifications.md、docs/full-guide.md、docs/full-guide_EN.md 已覆盖全局 CUSTOM_WEBHOOK_BODY_TEMPLATE 会先于 Bark / Slack / Discord 等自动 payload 生效、非法 JSON object fallback、裸 $content / $title 不做 JSON 转义，以及 Bark / NapCat 示例，之前若按“文档缺失”扩大为阻断，应收窄为已补齐。
2. tests/test_notification_sender.py 已新增 Bark URL 下全局模板优先、$content_json / $title_json 转义行为测试，能覆盖本 PR 声明的核心语义。
3. 结构化提示里的“运行时配置迁移/清理风险”在当前 diff 中未看到对应行为变更；src/core/config_registry.py 和 apps/dsa-web/src/utils/systemConfigI18n.ts 主要是配置元数据与展示文案，不涉及静默清空、迁移或重置用户运行时配置。
4. 当前 CI 摘要为 success，包括 ai-governance、backend-gate、docker-build、web-gate；剩余阻断仅来自冲突状态，不是测试失败或实现语义问题。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过。围绕 #1200 将既有 CUSTOM_WEBHOOK_BODY_TEMPLATE 语义产品化，补齐用户可见说明、Web 设置提示和回归测试，符合 AGENTS.md 对用户可见能力变更同步文档与 CHANGELOG 的要求。
• 是否有对应 issue：有，Refs #1200。
• PR 类型：docs/test。主体是通知文档、完整指南、配置说明文案与 .env.example 更新，同时补充通知发送和 Web 设置展示测试。
• description 完整性：完整。已覆盖背景、范围、验证命令与结果、兼容性风险、回滚方式和 EXTRACT_PROMPT 未变更说明；未更新 README 符合 AGENTS.md 中“细节优先写入 docs、README 不膨胀”的约束。
• 是否可直接合入：可。当前 CI 为 success，结构化事实显示代码可合并；mergeable_state=blocked 更像受分支保护/权限策略影响，不构成单独阻断。当前 diff 未看到会静默清空、迁移或重置用户运行时模型/provider/Base URL 配置的改动，主要变更集中在 Webhook 模板文档、配置元数据和回归测试。

---

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