微信运营素材生成（wechat-promo-materials）
什么时候用
用户要求生成微信小游戏（或 H5 游戏）的报备素材 / 推广素材 / 运营素材：封面图、详细推广图、推广视频、视频封面、分享图、宣传文案。规格通常由用户逐条给出（尺寸、格式、字节上限），平台基准规格见 references/mp-spec.md。
核心原则
- 不用直角屏幕截图：详细推广图与视频必须「局部放大、重新组合」（手机框、放大镜、标签芯片版式）。保证素材与真机渲染一致的办法是在浏览器里直读游戏真实模块绘制，不是截图后 PS。
- 先列验收数字再动手：把每项素材的尺寸、字节上限、时长、编码列成表，交付前逐项打勾。
- 无 ffmpeg 机器的视频方案：浏览器 WebCodecs（VideoEncoder H.264 + AudioEncoder AAC）+ mp4-muxer 封装；配乐程序化合成，无需任何音频素材。
- 红线零容忍：通用封面不得出现游戏 icon/logo/slogan/标题文字；素材不得含广告内容；视频必须 10–20s、有配乐、有玩法字幕、无片头。
工作流（五步）
- 读规格 —— 对照用户当次要求与 references/mp-spec.md，列出本次交付清单与验收数字（用户给出的数值永远优先）。
- 搭 harness —— 复制
assets/templates/harness.js到项目 dev 目录（如dev/promo/），按文件内 ADAPT 注释改模块表与游戏主类实例化。wx mock + CommonJS shim 让浏览器直读游戏真实渲染代码，rAF 手动步进保证帧采集确定性。 - 静态图 —— 新建 promo-maker 页面：每张图一个 draw 函数，重组版式（手机框合成 / 放大镜 / 标签芯片，技法见 references/pipeline.md §3）；JPEG 导出用质量参数把字节数压进上限。分享图优先复用游戏自身的分享海报绘制函数。
- 视频 —— 新建 encode 页面：AI 驱动真实状态机打演示关，逐帧合成横版（居中手机画面 + 氛围底 + 字幕）与竖版（满屏）；用
assets/templates/webcodecs-mp4.js编码（内置程序化 BGM 合成、落盘与回放校验 helper）；本地服务器挂assets/templates/promo-save-endpoint.js白名单端点接收产物；assets/vendor/mp4-muxer.min.js拷入项目。 - 验收 ——
node scripts/validate-mp4.js <file.mp4>查视频结构与合规项；图片逐张视觉走查（环境有视觉验收 agent 就用，没有就渲染成 PNG 自己逐张看）：文字不截断、标签不被遮挡、文案与画面一致、规格数字达标。不通过就改版式重新导出再走查，循环到全过。
资源索引
| 文件 | 用途 |
|---|---|
| references/mp-spec.md | 9 类素材完整规格、红线、常见驳回点、文案口径 |
| references/pipeline.md | 技术管线细节：harness 适配、版式技法、AI 录制、编码要点、验收清单、真实案例 |
assets/templates/harness.js |
wx mock + CommonJS shim 底座模板（拷入项目后按 ADAPT 注释适配） |
assets/templates/webcodecs-mp4.js |
浏览器 MP4 编码模块：H.264/AAC 探测、mp4-muxer 封装、程序化 BGM 合成、落盘与回放校验 |
assets/templates/promo-save-endpoint.js |
Node 静态服务器的白名单落盘端点模块（仅 127.0.0.1、目录+文件名双白名单） |
assets/vendor/mp4-muxer.min.js |
mp4-muxer UMD（MIT），浏览器全局 Mp4Muxer |
scripts/validate-mp4.js |
MP4 结构校验：fastStart、H.264/AAC 轨、时长、分辨率、体积 |
环境要求与降级
- 编码需 Chrome/Edge 94+（WebCodecs）；校验脚本与落盘端点需本机 Node。
- AAC 不可用时编码模块会回退 opus-in-MP4 并在返回值里标记
audioCompliant: false——该产物不满足报备音频规格，只能换有 AAC 的浏览器环境重编，不要交付。
