maomomo-article-writer/references/delivery-rules.md

MAOMOMO 完整交付规则

本文件用于完整文章、配图、发布包、打包、一键下载、GitHub 分批推送和后续更新任务。只要用户没有明确说“只要文字”“不要图片”“不要打包”“先不要生成文件”“先只要大纲”，默认按完整交付模式执行。用户提到“小红书”“卡片”“多图”“3:4”“9:16”时，默认进入小红书卡片模式，不默认生成完整文章、Markdown 或 ZIP。

完整交付模式指“最终交付物必须完整”，不代表可以跳过确认一次性全量生成。执行时必须遵守 SKILL.md 的阶段门禁：先读资料和事实表，再确认标题 / 口径 / 大纲 / 素材映射 / 配图风格 / 生图后端，随后写文章、整理 prompts、先出一张样张，样张确认后再逐张生成剩余图片。

强制完整交付规则

当用户请求包含以下任一表达时，必须默认进入“完整交付模式”：

• “使用 skill 生成文章”
• “按 skill 生成”
• “配图也是按 skill”
• “配图也按 SKILL”
• “完整文章”
• “发布用 Markdown”
• “打包”
• “一键下载”
• “给我文件”
• “文章和配图一起”
• “生成文章 + 配图”
• “最终交付”

完整交付模式最终必须完成以下交付物，但必须分阶段推进：

1. 读取并核对用户提供的所有官方链接、PDF、参考文章和条款。
2. 在写最终稿前给用户确认标题、核心口径、outline.md 大纲、来源缺口、必选素材映射和配图风格。
3. 用户确认后输出发布用 Markdown 文件，而不是只在聊天框展示正文。
4. 出图前把全部图片 prompt 写入 prompts/ 或 manifest 文件，让用户可直接编辑。
5. 先生成并确认一张样张，优先封面图；样张确认后再逐张生成剩余独立高清 PNG。
6. 将通过 QA 的图片同步到 assets/ 目录，并以相对路径插入 Markdown，例如 ![图片说明](assets/hsbc-mastercard-alipay-campaign-01-cover.png)。
7. 用脚本检查 Markdown 中所有本地图片路径真实存在。
8. 创建 ZIP 包，结构类似：

article_package.zip
  article.md
  assets/
    hsbc-mastercard-alipay-campaign-01-cover.png
    hsbc-mastercard-alipay-campaign-02-overview.png
    hsbc-mastercard-alipay-campaign-03-timeline.png

9. 最终回复只给路径和极简说明，同时说明图片数量、生图后端、状态记录和已知限制。

如果因为工具限制、图片生成失败、文件写入失败或资料缺失导致无法完成完整交付，必须明确说明失败点，并尽量交付已经完成的部分。不要只输出配图提示词代替图片文件，不要只输出文章正文代替 Markdown 文件。

多渠道交付策略

完整文章交付默认生成 Markdown、assets 和 ZIP；小红书卡片和大图片交付默认生成 assets/、final_manifest.json 和 GitHub 分批链接。最终发送方式按渠道和用户要求调整。

• 本地 / Web：完整文章可给 Markdown + ZIP；小红书卡片给 assets/、final_manifest.json 和 GitHub 链接。
• GitHub：图片较多、文件较大、Telegram 可能失败或用户要求最终交付时，先读 references/github-delivery.md，确认交付仓库、专用 KEY / token / deploy key、仓库隐私级别和目标路径；配置就绪后按批次推送，例如 batch-01-cover、batch-02-content-cards、batch-03-final-assets。每批推送后记录 GitHub 文件路径、commit、release 或下载链接。
• Telegram / 聊天：只负责通知进度和给 GitHub 链接；不要依赖 Telegram 直接承载 ZIP 或大图片包。少量小文件附件只能作为补充，不作为唯一交付证据。
• Email：按用户要求选择 ZIP 或独立附件。
  • 用户说“打包发我 email”：发送 ZIP。
  • 用户说“不打包”“分多个附件”：发送 Markdown 和图片作为多个独立附件，不再附 ZIP。
• 若附件发送失败，不要反复重复发送同一批附件；改用更稳定的渠道或分批发送，并说明只保留最后版本。
• 发送前确认附件对应的是最后确认版，不要把旧图、旧 Markdown 或临时文件发出。

小红书卡片交付模式

触发词包括“小红书”“卡片”“多图”“4 图看完”“发小红书”“3:4”“9:16”。

执行规则：

1. 不默认走完整文章 + Markdown + ZIP；除非用户明确要求，只交付小红书标题、正文、话题标签和多张独立 PNG。
2. 出图前确认比例 3:4 或 9:16，确认视觉方向 2D 扁平风 或 3D 轻拟物风。用户没指定时推荐 2D 扁平风。
3. 每张图 prompt 必须包含原生竖版防压扁规则：native portrait composition、no squeezed elements、no stretched card / logo / text、vertical layout redesigned for Xiaohongshu。
4. 每张图按一个 job / 一次请求 / 一次 QA 推进，状态文件记录 prompt 文件、生成结果、QA 状态、是否进入 assets/、是否已推送 GitHub。
5. QA 通过后生成 final_manifest.json，只包含最终图；推送或打包只能读取该 manifest 或状态文件里标记为 final 的 assets。
6. GitHub 分批推送前必须按 references/github-delivery.md 完成或确认仓库和专用凭据配置。缺少配置时先输出本机配置步骤并暂停 push，不生成假链接。
7. GitHub 分批推送建议：
   • batch-01-cover：封面图和封面 prompt。
   • batch-02-content-cards：内容卡、流程卡、避坑卡。
   • batch-03-final-assets：final_manifest.json、全部 final assets、状态文件。
8. 每批推送后立即回报 GitHub 文件路径、commit、release 或下载链接，并写入 github_batches.json 或状态文件。
9. 最终回复固定包含 GitHub 链接、图片数量、风格：2D / 3D、比例：3:4 / 9:16、批次数量、QA 是否完成、已知限制。

GitHub 交付配置门禁

GitHub 交付前必须先完成以下检查：

• 已读取 references/github-delivery.md。
• 已确认目标仓库，例如 OWNER/maomomo-delivery。
• 仓库默认是私有；公开仓库必须经用户明确确认。
• 已确认认证方式：gh auth login、GH_TOKEN fine-grained PAT，或 SSH deploy key。
• 凭据必须是专用且最小权限：fine-grained PAT 只给交付仓库 Contents: Read and write；deploy key 只授权单仓库 write access。
• 不要求用户在聊天里粘贴 token 或私钥；不把密钥写入项目文件、manifest、状态文件、日志或 commit。
• github_batches.json 只记录 batch、文件路径、commit、release / url 和备注。

配图执行规则

具体视觉风格、图片清单、文件命名、Markdown 插图和图片 QA 规则见 references/visual-assets.md。本节只规定完整交付时的执行边界。

当用户要求“配图也按 Skill”“高清配图”“精美配图”“生成配图”“文章和配图一起”时：

• 必须生成独立 PNG 图片文件，而不是只给提示词。
• 出图前必须先写入 prompt 文件，包含文件名、用途、放置位置、核心文案、完整 prompt、alt text、风格和依赖素材。
• 必须先生成一张样张，优先封面图；用户确认前不得生成剩余图片。
• 样张确认后，每张图按一个 job / 一次请求 / 一次 QA 推进；运行环境支持子 agent 时，可以一图一个子 agent 并发。
• 不要只生成一张大长图替代所有配图。
• 每张图必须有独立主题，例如封面图、活动总览图、时间线图、重点规则图、交易法图、避坑图、FAQ 图。
• 银行、券商、支付品牌、卡组织或支付网络 Logo 只要已由官方材料、用户素材或用户明确口径核对正确，就可以作为辅助识别出现；用户未提供素材时，应主动尽力从官方活动页、条款 PDF、品牌资源页、官网 / App 截图等来源查找准确 Logo。无法核对时使用通用符号。
• 出现信用卡、支付卡、卡组织、支付网络或机构 Logo 时，必须按官方材料或用户素材核对，并在 prompt、manifest 或 deck_spec.json 记录参考素材、卡组织、allowed_brand_marks 和 brand_mark_sources；不得把银联 / UnionPay 画成 Mastercard、Visa 等其他卡组织。
• 第三方 Logo 必须尺寸克制、位置辅助，不能抢占、替代或压过 MAOMOMO 主标识。
• 不得伪造真实 App 截图。
• prompt 中的视觉风格只能写成后台画面描述，不要写容易被模型照抄的中文风格标签；可见文字只允许出现指定业务文案、MAOMOMO 和已核对允许出现的品牌 / 支付标识。
• 小红书 3:4 / 9:16 图片必须原生竖版重新构图，不能把横版设计压进竖图；prompt 必须包含防压扁和防拉伸英文约束。
• 生成图应明确是 MAOMOMO 示意图 / 信息图，不伪装成真实截图或官方页面。
• 生成后的原始最终图先保存到 origin_image/，通过 QA 后同步到 assets/，并插入 Markdown。
• 港币金额在发布稿、图片文案、prompt、manifest 和 deck_spec.json 中统一写 HKD，来源原文抽取文件除外。
• 图片文件名使用稳定英文小写命名，并包含主题前缀，例如 hsbc-mastercard-alipay-campaign-01-cover.png。
• 不要使用中文文件名或缺少主题前缀的通用文件名作为最终 assets 文件名，避免站点路径兼容和多文章混淆问题。
• 不要用 Playwright、HTML/CSS、SVG、Pillow、canvas、本地拼贴或手工覆盖文字替代 GPT Image2 / 图片 API 生成最终配图。

图片生成偏差处理

• 每张图应独立生成高清 PNG；不要主动生成一张拼图再裁切。
• 如果图片工具意外只返回一张拼图或长图，应视为不合格结果。
• 除非用户接受临时方案，否则应重新生成独立图片。
• 若临时裁切拼图，必须明确说明这是临时补救，并尽快补独立版本。
• 用户要求加入参考图元素时，应把参考图作为视觉元素来源，但不要复制真实卡号、个人信息或伪造 App 截图。

禁止半成品交付

以下都属于半成品，除非用户明确只要求这样做：

• 只输出文章正文，不给 .md 文件。
• 只输出配图提示词，不生成图片文件。
• 只生成图片，不插入 Markdown。
• 只生成一张总图，不生成多张独立配图。
• 完整文章模式只给 assets，不打 ZIP。
• 小红书卡片只扫描目录交付，未生成 final_manifest.json，导致草稿、失败图、旧比例图混入最终包。
• Telegram 发送失败后仍反复传大 ZIP，而不是改用 GitHub 分批链接。
• 只给一段新增内容，不输出更新后的完整文章。
• 只给旧文件链接，没有确认文件内容已更新。
• 修改了正文，但没有同步更新标题、摘要、配图清单、来源区和 ZIP 包。
• 用户要求“输出完整文章”时，只输出新增片段。
• 用户要求“打包给我”时，只给 Markdown 或只给图片。

当用户说“输出完整文章”“别只给一段”“打包给我”“文章和配图一起”时，必须交付完整文件，而不是片段。

改稿更新检查

用户在已有文章上连续修改时，执行最小变更并同步验证。

1. 先定位用户指定范围：标题、TLDR、某节、某句、某几个字、图片、来源区或附件。
2. 只修改指定范围；不要因为用户说“删掉 X”就删除整条信息。
3. 若修改影响编号、目录、图片 alt、来源区或 ZIP，才同步更新相关部分。
4. 修改完成后读取相关片段验证，而不是只凭替换命令结果回复。
5. 最终回复只说明改了什么，不要重复发送不必要附件。

更新任务规则

当用户在已有文章基础上提出修改，例如“删掉 One+”“增加 BOXX 交易法”“不要用 Week”“输出完整文章”“再打包”：

1. 不要只输出修改片段，除非用户明确要求“只给新增段落”。
2. 默认更新完整 Markdown 文件。
3. 如果修改影响配图或配图清单，必须同步更新对应图片引用和 assets 文件名。
4. 如果用户要求文件或打包，必须重新生成 ZIP。
5. 最终回复给出最新 Markdown 和 ZIP 链接，避免继续给旧文件。

远程图片路径替换

当用户提供 WordPress / CDN 上传后的 <img ... src="..."> 片段或远程图片 URL，并要求替换文章图片路径时：

1. 只替换 Markdown 中的图片 URL，不改正文、alt text、图片顺序和本地 assets 文件。
2. 优先按文件名或 title 中的序号 / 语义匹配，例如 01-cover 对封面图，04-rebate-card 对到账截图卡片；不要按用户粘贴顺序机械替换，除非用户明确说按粘贴顺序。
3. 替换后用 rg 或等效检查确认没有残留本地 assets/ / origin_image/ 引用。
4. 若文章已全部改为远程图，Markdown 本地图片路径检查可以跳过本地资产存在性要求，但仍要检查远程 URL 已写入正确位置。
5. 如果需要重新打包，ZIP 至少包含最新 article.md；是否继续附本地 assets/ 取决于用户要“发布稿”还是“完整归档包”，最终回复要说明包内内容。

最终交付前检查清单

交付前必须逐项确认：

• Markdown 文件已生成。
• outline.md 已按用户确认版本保存。
• prompts/ 中每张图的 prompt 文件已保存，且与最终图片数量和顺序一致。
• 一张样张已确认，后续图片继承同一生图后端和视觉系统。
• slide_jobs.json / slide_run_state.json 已记录图片任务状态；如缺少记录，最终回复必须说明原因。
• 每张图的状态记录包含 prompt 文件、生成结果、QA 状态、是否进入 assets/、是否已推送 GitHub。
• final_manifest.json 已生成，并且最终交付只读取 manifest 中列出的 final assets。
• 需要 GitHub 交付时，已确认 references/github-delivery.md 中的仓库、专用凭据、隐私级别和目标路径；缺失时最终回复说明配置阻塞项。
• origin_image/ 中最终原始图片存在。
• assets/ 目录已生成。
• 已运行 uv run python scripts/maomomo_check_markdown_assets.py article/article.md 或等效脚本，确认所有 Markdown 图片路径都能对应到真实图片文件。
• 图片是多张独立 PNG，不是一张大图代替全部。
• 图片文件名包含文章主题前缀，未沿用旧文章文件名。
• 图片可见文字没有出现风格标签、prompt 描述、额外 slogan 或无关文案；除业务文案、MAOMOMO 和已核对允许出现的品牌 / 支付标识外，没有多余文字。
• 图片日期、金额、公式、卡组织 / 支付网络 / 机构 Logo 和禁用分支都已核对。
• 用户未提供 Logo / 卡面素材时，已尽力查找准确标识，并在 sources/、prompt、manifest 或 deck_spec.json 记录素材来源和核对结论；无法核对时没有凭记忆画真实 Logo。
• 第三方 Logo 没有抢占、替代或压过 MAOMOMO 主标识。
• 发布稿、图片文案、prompt、manifest、deck_spec.json 和 speech.md 中港币金额统一使用 HKD。
• 文末来源区只包含实际使用的来源。
• 正文没有 contentReference、oaicite、调试标记或工具残留。
• 用户要求删除的分支，标题、正文、配图清单和来源区都已删除干净。
• 完整文章模式下 ZIP 包已创建；小红书卡片模式下 final_manifest.json 和 GitHub 批次记录已创建。
• 用户最后确认的标题是否已同步到 frontmatter 和 H1。
• 用户要求删除的词是否只删除指定词，未误删整条信息。
• 正文是否残留编辑指令或模型解释。
• 用户不喜欢的模糊词，例如“更像”“可能”“大致”，是否已按上下文清理。
• 用户提供的明确实测结论是否写成确定语气，未被改软成“可能 / 疑似 / 大概”。
• 用户提供的“以往惯例 / 过往尿性 / 过往经验”是否写成“大概率 / 按过往案例判断”的强概率语气，并保留合理边界。
• TLDR 是否过长，是否适合当前平台。
• 小红书图是否为用户确认的 3:4 或 9:16，是否每张都有 MAOMOMO 标识，是否为原生竖版重构，是否没有压扁或拉伸。
• 小红书图是否全组保持同一 2D / 3D 视觉方向。
• 图片是否匹配最终文章口径，未残留旧规则、旧金额、旧标题。
• 邮件/聊天附件是否按用户要求选择 ZIP、多个独立附件或 GitHub 分批链接；Telegram 是否只承载通知和链接。
• 若已发送过旧版本，最终回复要明确这是最后版本，避免重复发同一批图片。
• 完整文章最终回复包含 Markdown 下载链接和 ZIP 或 GitHub 链接；小红书卡片最终回复包含 GitHub 链接、图片数量、风格、比例、批次数量、QA 是否完成和已知限制。