确认优先、单步推进、先样张再逐张生成，不能一上来完整批量生成

references/delivery-rules.md

@@ -2,6 +2,8 @@
 
 本文件用于完整文章、配图、发布包、打包、一键下载和后续更新任务。只要用户没有明确说“只要文字”“不要图片”“不要打包”“先不要生成文件”“先只要大纲”，默认按完整交付模式执行。
 
+完整交付模式指“最终交付物必须完整”，不代表可以跳过确认一次性全量生成。执行时必须遵守 `SKILL.md` 的阶段门禁：先读资料和事实表，再确认标题 / 口径 / 大纲 / 素材映射 / 配图风格 / 生图后端，随后写文章、整理 prompts、先出一张样张，样张确认后再逐张生成剩余图片。
+
 ## 强制完整交付规则
 
 当用户请求包含以下任一表达时，必须默认进入“完整交付模式”：
@@ -19,13 +21,15 @@
 - “生成文章 + 配图”
 - “最终交付”
 
-完整交付模式必须一次性完成：
+完整交付模式最终必须完成以下交付物，但必须分阶段推进：
 
 1. 读取并核对用户提供的所有官方链接、PDF、参考文章和条款。
-2. 输出发布用 Markdown 文件，而不是只在聊天框展示正文。
-3. 生成或准备多张独立高清 PNG 配图，放入 `assets/` 目录。
-4. 将图片以相对路径插入 Markdown，例如 `![图片说明](assets/hsbc-mastercard-alipay-campaign-01-cover.png)`。
-5. 创建 ZIP 包，结构类似：
+2. 在写最终稿前给用户确认标题、核心口径、`outline.md` 大纲、来源缺口、必选素材映射和配图风格。
+3. 用户确认后输出发布用 Markdown 文件，而不是只在聊天框展示正文。
+4. 出图前把全部图片 prompt 写入 `prompts/` 或 manifest 文件，让用户可直接编辑。
+5. 先生成并确认一张样张，优先封面图；样张确认后再逐张生成剩余独立高清 PNG。
+6. 将通过 QA 的图片同步到 `assets/` 目录，并以相对路径插入 Markdown，例如 `![图片说明](assets/hsbc-mastercard-alipay-campaign-01-cover.png)`。
+7. 创建 ZIP 包，结构类似：
 
 ```text
 article_package.zip
@@ -36,7 +40,7 @@ article_package.zip
     hsbc-mastercard-alipay-campaign-03-timeline.png
 ```
 
-6. 最终回复只给下载链接和极简说明。
+8. 最终回复只给路径和极简说明，同时说明图片数量、生图后端、状态记录和已知限制。
 
 如果因为工具限制、图片生成失败、文件写入失败或资料缺失导致无法完成完整交付，必须明确说明失败点，并尽量交付已经完成的部分。不要只输出配图提示词代替图片文件，不要只输出文章正文代替 Markdown 文件。
 
@@ -59,14 +63,18 @@ article_package.zip
 当用户要求“配图也按 Skill”“高清配图”“精美配图”“生成配图”“文章和配图一起”时：
 
 - 必须生成独立 PNG 图片文件，而不是只给提示词。
+- 出图前必须先写入 prompt 文件，包含文件名、用途、放置位置、核心文案、完整 prompt、alt text、风格和依赖素材。
+- 必须先生成一张样张，优先封面图；用户确认前不得生成剩余图片。
+- 样张确认后，每张图按一个 job / 一次请求 / 一次 QA 推进；运行环境支持子 agent 时，可以一图一个子 agent 并发。
 - 不要只生成一张大长图替代所有配图。
 - 每张图必须有独立主题，例如封面图、活动总览图、时间线图、重点规则图、交易法图、避坑图、FAQ 图。
 - 不得使用未经用户提供的真实银行 Logo、券商 Logo 或支付品牌 Logo。
 - 不得伪造真实 App 截图。
 - 生成图应明确是“MAOMOMO 风格示意图 / 信息图”。
-- 生成后必须保存到 `assets/`，并插入 Markdown。
+- 生成后的原始最终图先保存到 `origin_image/`，通过 QA 后同步到 `assets/`，并插入 Markdown。
 - 图片文件名使用稳定英文小写命名，并包含主题前缀，例如 `hsbc-mastercard-alipay-campaign-01-cover.png`。
 - 不要使用中文文件名或缺少主题前缀的通用文件名作为最终 assets 文件名，避免站点路径兼容和多文章混淆问题。
+- 不要用 Playwright、HTML/CSS、SVG、Pillow、canvas、本地拼贴或手工覆盖文字替代 GPT Image2 / 图片 API 生成最终配图。
 
 ## 图片生成偏差处理
 
@@ -118,6 +126,11 @@ article_package.zip
 交付前必须逐项确认：
 
 - Markdown 文件已生成。
+- `outline.md` 已按用户确认版本保存。
+- `prompts/` 中每张图的 prompt 文件已保存，且与最终图片数量和顺序一致。
+- 一张样张已确认，后续图片继承同一生图后端和视觉系统。
+- `slide_jobs.json` / `slide_run_state.json` 已记录图片任务状态；如缺少记录，最终回复必须说明原因。
+- `origin_image/` 中最终原始图片存在。
 - `assets/` 目录已生成。
 - 所有 Markdown 图片路径都能对应到真实图片文件。
 - 图片是多张独立 PNG，不是一张大图代替全部。

references/image-generation.md

@@ -11,6 +11,15 @@
 
 不要因为脚本存在就强制使用脚本。若内置图片工具可用，仍优先使用内置工具生成独立 PNG，再保存到 `assets/`。
 
+生成第一张图前，必须向用户确认：
+
+- 已检查哪种内置图片生成工具是否可用。
+- 准备使用的生图后端。
+- 是否需要 `scripts/maomomo_image_gen.py` fallback，以及原因。
+- 当前会沿用环境变量或配置文件中的 baseURL、model、quality，不会擅自改成 `low`。
+
+确认后，整篇文章所有图片保持同一个生图后端和质量配置。只有用户明确要求切换，或当前后端无法完成必需能力时，才重新确认后端。
+
 ## 配置来源
 
 脚本按以下顺序读取配置：
@@ -27,7 +36,7 @@
 
 ```bash
 python3 scripts/maomomo_image_gen.py generate \
-  --out article/assets/hsbc-mastercard-alipay-campaign-01-cover.png \
+  --out article/origin_image/hsbc-mastercard-alipay-campaign-01-cover.png \
   --style warm-fintech-guide \
   --title "汇丰 Mastercard 支付宝活动" \
   --image-type "封面图" \
@@ -38,7 +47,7 @@ python3 scripts/maomomo_image_gen.py generate \
 
 ```bash
 python3 scripts/maomomo_image_gen.py generate \
-  --out article/assets/hsbc-mastercard-alipay-campaign-01-cover.png \
+  --out article/origin_image/hsbc-mastercard-alipay-campaign-01-cover.png \
   --style data-card-dashboard \
   --title "返现计算图" \
   --image-type "计算图" \
@@ -54,7 +63,7 @@ manifest 示例：
 {
   "images": [
     {
-      "file_name": "assets/hsbc-mastercard-alipay-campaign-01-cover.png",
+      "file_name": "origin_image/hsbc-mastercard-alipay-campaign-01-cover.png",
       "type": "封面图",
       "title": "汇丰 Mastercard 支付宝活动",
       "core_text": "先报名，再看门槛和封顶",
@@ -63,7 +72,7 @@ manifest 示例：
       "aspect_ratio": "16:9"
     },
     {
-      "file_name": "assets/hsbc-mastercard-alipay-campaign-02-calculation.png",
+      "file_name": "origin_image/hsbc-mastercard-alipay-campaign-02-calculation.png",
       "type": "计算图",
       "title": "怎么刷到刚刚好",
       "core_text": "HK$190 ÷ 9% ≈ HK$2112，超过部分没有额外收益",
@@ -81,7 +90,14 @@ python3 scripts/maomomo_image_gen.py batch \
   --base-dir article
 ```
 
-`file_name` 必须与 Markdown 中的相对路径一致，且最终文件必须真实存在。
+`file_name` 必须与本次生成目录一致，且最终文件必须真实存在。发布用 Markdown 默认引用 `assets/`，因此输出到 `origin_image/` 后要在 QA 通过时同步到同名 `assets/` 文件。
+
+重要限制：
+
+- 不要在样张确认前运行批量生成。
+- 默认用 `generate` 单张生成；`batch` 只用于用户明确授权的全量生成或 dry-run prompt 输出。
+- 即使使用 `batch`，脚本也是逐项请求图片接口；生成后仍要逐张 QA，并把通过的图片同步到 `assets/`。
+- 发布用 Markdown 默认引用 `assets/`，因此如果 manifest 输出到 `origin_image/`，必须在 QA 后复制到对应 `assets/` 路径。
 
 ## 内置风格名
 
@@ -111,3 +127,69 @@ python3 scripts/maomomo_image_gen.py styles
 - 接口失败：保留已生成图片，说明失败项，必要时用 `--dry-run` 交付 prompt 清单作为临时排查材料。
 - 图片文字乱码或金额错误：重新生成该单张图片；不要手工覆盖文字伪装成模型输出。
 - 图片不符合风格：先更新 manifest 的 `style` / `core_text` / `extra`，再重跑对应项。
+- 图片生成超时：可以对同一张图重试较长超时；不要为了快擅自降低 `quality`。
+- Playwright 只用于已有 HTML / SVG / 网页截图检查，不能替代 GPT Image2 / 图片 API 生成海报、OG 图、卡片图或文章配图。
+
+## 状态记录
+
+每张图片 job 的 dispatch、result 和 blocker 都要写入项目状态文件。推荐状态文件：
+
+```text
+{article_dir}/slide_jobs.json
+{article_dir}/slide_run_state.json
+```
+
+记录字段至少包括：
+
+- job id，例如 `hsbc-mastercard-alipay-campaign_01`
+- prompt 文件，例如 `prompts/hsbc-mastercard-alipay-campaign_01.json`
+- 输出原图，例如 `origin_image/hsbc-mastercard-alipay-campaign-01-cover.png`
+- 发布图，例如 `assets/hsbc-mastercard-alipay-campaign-01-cover.png`
+- 状态：`pending`、`dispatched`、`recorded`、`blocked`
+- 生图后端、agent id、QA note、失败原因
+
+使用 `scripts/maomomo_job_state.py` 更新状态，不要手工改 JSON 后声称完成。
+
+初始化状态：
+
+```bash
+python3 scripts/maomomo_job_state.py init article \
+  --selected-backend "built-in image tool"
+```
+
+查看状态：
+
+```bash
+python3 scripts/maomomo_job_state.py status article
+```
+
+记录 dispatch：
+
+```bash
+python3 scripts/maomomo_job_state.py dispatch article \
+  --job hsbc-mastercard-alipay-campaign_02 \
+  --agent-id "<agent id>" \
+  --prompt-file prompts/hsbc-mastercard-alipay-campaign_02.json
+```
+
+记录结果并同步到 `origin_image/` 和 `assets/`：
+
+```bash
+python3 scripts/maomomo_job_state.py result article \
+  --job hsbc-mastercard-alipay-campaign_02 \
+  --agent-id "<agent id>" \
+  --backend-used "built-in image tool" \
+  --selected-source /absolute/path/to/generated.png \
+  --qa-note "文字清楚，风格与样张一致。"
+```
+
+记录 blocker：
+
+```bash
+python3 scripts/maomomo_job_state.py blocker article \
+  --job hsbc-mastercard-alipay-campaign_02 \
+  --agent-id "<agent id>" \
+  --reason "选定图片后端在 worker 中不可用"
+```
+
+如果状态脚本失败，最终报告必须说明原因，并附上状态文件当前路径和未完成 job。

references/visual-assets.md

@@ -7,9 +7,15 @@
 - 完整文章默认配独立 PNG：短文章 4-6 张，普通攻略 6-8 张，长教程 / 多活动整理 8-12 张。
 - 不为凑数量硬加图；每张图必须服务正文。
 - 每张图独立生成或准备，不要用一张拼图、长图或总图代替全部。
+- 出图前先把全部图片 prompt 写入 `prompts/` 或 manifest 文件；不要在聊天里输出超长 prompt 代替文件。
+- 先只生成一张样张，优先封面图；用户确认样张前不得生成剩余图片。
+- 样张确认后，后续图片使用同一生图后端、同一视觉系统和同一质量配置。
+- 图片生成按“一张图一个 job / 一次请求 / 一次 QA”推进；运行环境支持子 agent 时，可以一图一个子 agent 并发，但不要一次请求多张图。
+- 最终原始图保存到 `origin_image/`，通过 QA 后同步到 Markdown 引用的 `assets/`。
 - 生成图必须是“示意图 / 信息图 / 教程视觉”，不得伪造真实 App 截图、账单或官方页面。
 - 用户提供真实截图时，优先用真实截图，并隐去姓名、账号、余额、地址、手机号、二维码、交易号等个人信息。
 - 每张图必须包含清晰可见的 `MAOMOMO` 标识。
+- 不要用 Playwright、HTML/CSS、SVG、Pillow、canvas、本地拼贴或手工覆盖文字替代图片生成后端。
 
 ## 风格选择
 
@@ -66,7 +72,7 @@ C. handdrawn-note：便签和手绘箭头更明显，适合避坑经验和保姆
 
 ## 图片清单格式
 
-生成图片前先规划清单：
+生成图片前先规划清单，并同步写入 `prompts/{article_slug}_XX.json` 或图片 manifest。每个 prompt 文件至少包含：文件名、类型、放置位置、核心文案、alt text、风格、依赖素材、输出路径和完整 prompt。
 
 ```markdown
 | 文件名 | 类型 | 放置位置 | 核心文案 | alt text | 风格 | 依赖素材 |
@@ -75,13 +81,35 @@ C. handdrawn-note：便签和手绘箭头更明显，适合避坑经验和保姆
 | hong-kong-bank-account-02-flow.png | 流程图 | 操作步骤前 | 三步完成账户活跃 | 港卡保号操作流程图 | handdrawn-note | 用户截图 1 |
 ```
 
-确认用户不需要先看清单时，可以直接执行，但最终必须让文件名、alt text 和插图位置与正文一致。
+确认用户不需要先看清单时，可以不在聊天里展开清单，但仍必须写入 prompt 文件，并遵守“先样张、后逐张生成”的门禁。最终必须让文件名、alt text 和插图位置与正文一致。
+
+推荐单图 prompt JSON：
+
+```json
+{
+  "id": "hsbc-mastercard-alipay-campaign_01",
+  "file_name": "hsbc-mastercard-alipay-campaign-01-cover.png",
+  "origin_out": "origin_image/hsbc-mastercard-alipay-campaign-01-cover.png",
+  "asset_out": "assets/hsbc-mastercard-alipay-campaign-01-cover.png",
+  "type": "封面图",
+  "placement": "标题下方",
+  "core_text": "先报名，再看门槛和封顶",
+  "alt_text": "MAOMOMO 汇丰 Mastercard 支付宝返现活动封面图",
+  "style": "warm-fintech-guide",
+  "required_assets": [],
+  "prompt": "完整图片生成 prompt，包含风格、文案、约束和禁止项"
+}
+```
 
 ## 文件命名
 
 图片文件名必须 SEO 友好，并包含主题前缀：
 
 ```text
+origin_image/
+  hsbc-mastercard-alipay-campaign-01-cover.png
+  hsbc-mastercard-alipay-campaign-02-overview.png
+
 assets/
   hsbc-mastercard-alipay-campaign-01-cover.png
   hsbc-mastercard-alipay-campaign-02-overview.png
@@ -120,6 +148,8 @@ assets/
 
 图片说明必须根据图片内容写，不要都写成“配图”。
 
+`origin_image/` 不直接写进 Markdown，除非用户明确要求引用原始图目录。发布用 Markdown 默认引用 `assets/`。
+
 ## 猫咪视觉识别
 
 基础方向：
@@ -163,10 +193,13 @@ MAOMOMO 风格中文金融教程信息图，干净明亮白色背景，暖橙色
 
 交付前检查：
 
+- 样张已被用户确认，后续图片没有切换生图后端或视觉风格。
 - 文件真实存在，格式为 PNG。
+- `origin_image/` 原始最终图和 `assets/` 发布图对应。
 - Markdown 路径能打开对应文件。
 - 图片文字清楚，无乱码、错字和过期金额。
 - 标题、金额、日期、规则与最终文章口径一致。
 - 没有真实个人信息。
 - 没有伪造官方 App 页面或未经授权的品牌 Logo 场景。
 - 每张图独立主题明确，不是同一画面的机械变体。
+- `slide_jobs.json` / `slide_run_state.json` 中没有未处理的 `pending`、`dispatched` 或 `blocked` job；如有，不能声称完整交付完成。