fix: recover WeChat page thumbnail delivery

2026-07-22 11:51:15 +08:00
parent 57d2c14fca
commit cb62b36cd5
13 changed files with 366 additions and 26 deletions
@@ -0,0 +1,27 @@
+# 2026-07-22 微信服务号页面缩略图交付失败
+
+## 现象
+
+微信服务号用户要求生成带主题图片的页面。页面和候选图片已经生成，但服务号最终回复“没有完成本轮新缩略图”，未发送页面链接，并要求用户重新描述完整需求。
+
+## 根因
+
+这是两个连续问题叠加后的结果：
+
+1. 首轮图片语义审核未达阈值后，Agent 更换提示词再次调用图片工具，却复用了同一个服务号页面缩略图幂等键。`image_make` 对同键不同请求返回冲突，后续被表现为图片服务不可用。
+2. 后续重试已经生成并落盘合格 hero 图，但页面交付校验在页面文件与本轮工具写入快照不同步时得到 `missing_generated_cover`，形成假阴性，没有使用唯一的本轮 hero 图恢复 `mindspace-cover.cover`。
+
+## 修复
+
+- 仅对 `wechat-<消息>-page-<序号>-thumbnail` 且 `purpose=hero` 的请求，把提示词摘要加入 `image_make` 幂等键；同提示词仍可幂等，不同提示词不会冲突。其它图片调用的幂等行为不变。
+- 明确要求 Agent 对同一正式页面只调用一次图片工具；语义重试由图片服务内部完成。
+- 增加默认关闭的 `H5_WECHAT_MP_FRESH_THUMBNAIL_REPAIR`。开启后，只有“一个正式页面 + 一张本轮 hero 图”且页面已有合法 `mindspace-cover` 元数据时，才原子写回 cover 并重新执行完整校验。任何多页、多图、缺图或无效元数据情况继续 fail closed。
+- 增加结构化失败诊断，记录校验原因、页面、cover 和本轮生成资产，不记录图片提示词或用户正文。
+- 失败文案不再要求重述完整需求；页面内容保留，用户可回复“重试上次页面”。
+- 页面生成提示增加禁止杜撰产品指标、客户数、SLA、认证、案例、排名和承诺的约束。
+
+## 影响边界与回滚
+
+- 正常页面生成、H5 聊天、非服务号图片、服务号普通聊天和多页/多图 fail-closed 行为不变。
+- 确定性修复默认关闭；生产验证后显式设置 `H5_WECHAT_MP_FRESH_THUMBNAIL_REPAIR=1` 才启用。
+- 如需回滚修复分支，只需将该变量设为 `0` 或移除；新缩略图硬门仍保持开启。