ppt-craft-editable

name

ppt-craft-editable

description

端到端 PPT 全流程，单技能自包含。用户首次触发本 skill 时，agent 必须默默跑 scripts/preflight.py 做环境自检 + 自动安装缺失的 Python 包；FAIL 才打断用户。 环境通过后走 conversation-first + image-first 工作流：多阶段对话、内容补强、风格预览、规划锁定、出每页定稿图，并在用户驱动下做图像级 retouch（去水印 / 去瑕疵，内置 IOPaint 自动安装）。最终交付高完成度图片型 PPTX。 Phase A 结束后必须主动询问用户是否要可编辑文字版（Phase C）；若同意，进入 Phase C：以 Phase A 定稿图作为视觉参考，重新生成"带装饰、留白文字区"的无字背景图 + HTML 编辑器调文字 → 一键渲染原生可编辑 PPTX。 用户明确要求"只做可编辑版 / 只跑 Phase C / 跳过图片版"时，直接进入 Phase C-only 模式，不执行 Phase A 的任何生成、预览、review、retouch。 ★ Phase D - PDF PPT编辑分支：用户上传 PDF 幻灯片时，自动判断每页是矢量文本还是图片型，用多模态模型抽取文案结构，在 HTML 预览页让用户确认后，生成无字背景 + 可编辑文字框，最终输出原生可编辑 PPTX。 ★ 当对话中出现 ===PPT-CRAFT-EDITABLE / DECK FROM EDITOR===、===PHASE-D / CONTENT EXTRACTION CONFIRMED===、旧标记 ===PPT-IMAGE-FIRST-EDITABLE / DECK FROM EDITOR=== 或 ===DECK JSON BEGIN/END=== 标记时，agent 必须立刻把标记之间的 JSON 原样写入对应文件并跑相应脚本，不解读不修改不追问。 当用户需要做汇报 / 答辩 / 路演 / 提案 PPT，或只丢一个主题想要完整成品，或上传 PDF 想转可编辑版时使用。

ppt-craft-editable — 一条龙 PPT 技能（自包含）

---

★★★ Stage 0 — 用户首次触发本 skill，agent 默认自动跑环境自检 + 自动修复 ★★★

这是本 skill 最高优先级的规则，覆盖一切其他规则。

用户首次说要做 PPT、首次触发本 skill 时，agent 不需要问用户，直接默默跑：

python3 scripts/preflight.py

preflight.py 会：

1. 检查 Python 版本（不够则停，让用户处理）
2. 检查 4 个必备 Python 包，缺的自动 pip install（含 --user fallback；首次可能 2-5 分钟，OpenCV 较大）
3. 装完后自动调 doctor.py 做完整体检（字体 / 磁盘 / 网络 / IOPaint 状态 / skill 完整性）
4. 全部通过 → 退码 0 → agent 进入 Stage 1
5. 仍有阻塞 → 退码 1 → agent 把缺什么和怎么修念给用户听，等用户处理

preflight 自动会做的事 vs 不会做的事

类别	preflight 会自动做	不会做（请求用户处理）
Python 包	✅ pip install python-pptx pillow numpy opencv-python	—
Python 版本	—	❌ 不替用户装新 Python（动用户系统太危险）
系统字体	—	❌ 跨平台不一致 + 需要 sudo
IOPaint	—	❌ 那是 ~3GB / 5-10 分钟的活，只在 Stage 5.5 真正用到时再装
磁盘空间	✅ 早期就查并按三档处理（见下）	❌ 不会自动清磁盘
imagegen 通道	—	❌ 那是 agent harness 的事，preflight 探不到

磁盘空间的三档处理

preflight 在装任何东西之前就先查磁盘。这一项很重要——磁盘满会导致 pip 装包到一半失败、生成图片时写盘失败、IOPaint 模型下载失败，错误信息往往很难懂。

磁盘剩余	preflight 行为	agent 该怎么说
< 0.5 GB	直接 ❌ 退码 1 阻塞	念给用户："您的磁盘只剩 X GB，连基础依赖都装不下。请清理出至少 4 GB 后再用本 skill。可以删的常见目录：下载目录、回收站、~/.cache、不用的 Docker 镜像。"
0.5 – 2 GB	⚠️ 警告但继续	装包前告诉用户："您的磁盘只剩 X GB，能装但很紧张。如果后面要修瑕疵（用 IOPaint），还要再 3GB。建议现在清出更多空间。"
2 – 4 GB	✅ 通过 + 提示 IOPaint 需要 3GB	一笔带过
≥ 4 GB	✅ 通过	不用特别提

如果 agent 在 Phase A / Phase C 跑到一半看到 No space left on device、OSError: [Errno 28]、Could not write file 这类错误，立刻停下告诉用户磁盘满了，别重试浪费 imagegen 调用。

agent 的行为对照表

preflight 退出码	屏幕上看到	agent 怎么办
0	末尾"✅ 环境就绪"	简短报告"环境就绪"，进入 Stage 1（不要再问用户）
0 + 中间有⚠️	末尾"✅ 环境就绪"但 doctor 段有 WARN	同上 + 顺带提一句"有 N 个可选项缺失，影响 XXX，要不要现在修？"
1	末尾"❌ 自检仍有阻塞项"	必须停，把 FAIL 项和修复命令念给用户听

跑 preflight 的反模式（不要做）

• ❌ 不跑 preflight 直接进 Stage 1
• ❌ 跑 preflight 之前先问用户"要不要装 Python 包"——用户不一定知道答案；自动装是默认行为
• ❌ preflight 报 FAIL 还硬着头皮走下去（迟早卡在 Stage 2 或 Phase C 渲染）
• ❌ 把 preflight 当成"每轮都要跑一次"（只在用户首次触发或环境变更后跑）

何时算"首次触发"

• 用户在当前对话里第一次说要做 PPT
• 或者用户明说"换了机器 / 重装了环境 / 重跑一次自检"
• 或者上次跑 preflight 后已经过了很长时间（agent 自行判断）

后续轮次只要环境没变，不需要重跑——浪费时间。

给用户的"我在装东西"提示

如果 preflight 真的在装包（首次场景，可能 2-5 分钟），agent 在等待之前应当告诉用户：

第一次使用，正在自动安装 4 个 Python 依赖包（python-pptx / Pillow / numpy / opencv-python）。 首次安装可能需要 2-5 分钟，OpenCV 单独就 ~100MB，期间终端会看起来在卡，请稍等。 装完会自动继续，您不用做任何操作。

这样用户不会以为卡死了去 Ctrl+C。

imagegen 通道的额外验证

preflight 和 doctor 都无法直接探测 agent harness 的 imagegen 通道。所以在 Stage 2 出第一张真实预览之前，agent 还要再做一次"出图通道可用性测试"：用最小 prompt 出一张极小尺寸的图，确认通道通。这一步失败不算 preflight 失败，但必须停在 Stage 2 之前，告诉用户出图通道不可用、不能继续。

---

★★★ Phase A HTML 硬门禁（agent 必须自检，不可跳过）★★★

Phase A 流程中必须有两次让用户在浏览器里看 HTML——这是这条 skill 区别于"只在对话里贴图说说"的根本动作。 agent 在长对话里很容易忘记打开壳子，所以下面这两个动作是硬门禁，跑漏了视同 Phase A 没做完：

门禁	时机	必须打开的文件	注入命令
G-Preview	Stage 2 风格预览出图后、用户做"风格确认"前	phaseA/previews/preview_filled.html	python3 scripts/inject_shell_images.py preview --shell assets/preview_shell/index.html --data phaseA/previews/preview_data.json --out phaseA/previews/preview_filled.html
G-Review	Stage 5 全页定稿图出来后、用户做"终图批准"前	phaseA/review/review_filled.html	python3 scripts/inject_shell_images.py review --shell assets/review_shell/index.html --data phaseA/review/review_data.json --out phaseA/review/review_filled.html
G-Candidate（条件触发）	Stage 4 用户选了"多候选 picker"模式时	phaseA/candidates/picker_filled.html	python3 scripts/inject_shell_images.py candidate --shell assets/candidate_picker_shell/index.html --data phaseA/candidates/candidate_data.json --out phaseA/candidates/picker_filled.html

每个门禁的最小自检（agent 跑完必须勾选）

• *_filled.html 已生成在上表列的精确路径
• 已经尝试用 open / xdg-open / start 主动为用户打开它（失败再退路径）
• 在对话里显式告诉用户"已在浏览器打开 <filename>，请在里面确认 / 选图 / 给反馈"
• 等用户反馈（确认 / 复制粘贴回 JSON / 选图编号）后才进入下一 Stage

反模式（一旦发生立刻自我纠正）

• ❌ 出完图直接在对话里贴几张缩略图、问"喜欢哪套？" —— 跳过了 G-Preview，不算过门禁
• ❌ "我已经生成了 9 张预览图在 phaseA/previews/，请查看" —— 用户不会打开原图；必须开壳子
• ❌ 出完终图直接说"以下是 N 页定稿，您看看？" —— 跳过了 G-Review
• ❌ 打开了 assets/preview_shell/index.html 或 assets/review_shell/index.html（裸壳，里面是占位 SVG / 示例数据）—— 必须打开 *_filled.html
• ❌ 跑了 build_*.py 当成"已经注入" —— build_*.py 只还原模板不注入数据，跑完图还是占位
• ❌ G-Preview 还没过就跳到 Stage 3 写 design_spec.md —— 风格没经过浏览器确认，规划文件作废
• ❌ G-Review 还没过就导出图片型 PPTX 或主动询问 Phase C —— 终图没经过浏览器评审，交付作废

如果环境真的打不开浏览器

只在三件事都成立时才允许跳过"自动打开"动作：

1. agent 真的试过 open / xdg-open / start 都报错
2. 已经在对话里明确说明为什么打不开
3. 已经把 *_filled.html 的绝对路径给到用户，提示他自己双击打开

即使浏览器打不开，注入步骤本身不能跳（*_filled.html 仍然必须生成）。

---

Phase C-only 入口

当用户明确说出以下任一意图时，默认进入 Phase C-only：

• 只做可编辑版
• 只跑 Phase C
• 跳过图片版
• 直接给我文字可编辑 PPTX

Phase C-only 必守

• 不执行 Phase A：不跑 Stage 1-5，不做风格预览，不做图片型 PPTX
• 优先复用现有成果：如果用户已经给了 Phase A 产物，直接拿来用
• 必须先过页大纲确认门禁：不管有无 Phase A 产物，C-only 路径也必须先写 slide_outline.md，并同步写一份同内容的 ppt大纲.md 方便用户查找；等用户确认后才进 C0/C1。若用户已有完整内容稿且页面结构清晰，可由 agent 直接梳理给用户确认，不需要反复追问细节
• 缺输入先补最小集：如果缺 design_spec.md / slide_blueprint.md / deck.json，先收齐再进 C1-C6
• 必须先过 C0 轻量预览门禁：没有 Phase A 图作为视觉证据时，先做 1-2 页”重新生成的无字背景 + 可编辑文字预览”，并落地 phaseC/c0/deck.json、phaseC/c0/editor.html、phaseC/c0/preview/slide_*.png；让用户确认视觉基准后再批量生成全套背景
• 不再主动询问 Phase C：因为当前会话已经在 Phase C 路径里
• Phase C 完成即终态：拿到可编辑 PPTX 后结束，不折返到其他路径

Phase C-only 的最小输入

• 主题或已有报告稿
• 页数 / 受众 / 目的
• 可复用的内容稿或页面结构
• 如已存在，优先直接使用 design_spec.md、slide_blueprint.md、spec_lock.md

Phase C-only 的视觉基准

• design_spec.md 是视觉基准，不依赖 Phase A 成品图；它必须锁定明暗、色彩角色、字体气质、背景材质、装饰语言、留白规则和页面类型语法
• slide_blueprint.md 决定每页哪些元素进入背景、哪些内容必须保持为可编辑 TextBox
• spec_lock.md 必须写清：背景只承载氛围、结构、装饰和非编辑性视觉元素；标题、正文、数字、日期、署名等后期可能改的内容必须进入 deck.json.text_boxes
• C0 预览只用于确认视觉基准，不产出图片型 PPTX，也不折返 Phase A；用户确认 C0 前，slide_outline.md / ppt大纲.md 以及 phaseC/c0/ 三类预览产物必须真实存在

---

把三套互补能力融成一个 skill：

• Phase A — 对话式定稿 + retouch（默认主路径） Conversation-first + image-first 工作流：多阶段对话 → 内容基底 → 风格预览 → 风格反演确认 → 规划文件 → 每页定稿图 → 用户驱动的图像级 retouch（去水印 / 去瑕疵）。
• Phase C — 分层生成 + HTML 文字编辑（可编辑路径） Phase A 完成后主动询问用户是否要可编辑文字版。若用户同意，Phase C 会以 Phase A 定稿图作为视觉参考，重新生成不含可编辑文字的背景层，再把文字作为外挂图层在 HTML 编辑器里调整 → 一键渲染成原生可编辑 PPTX。注意这不是从 Phase A 图片中精确抠掉文字，背景可能与 Phase A 定稿有细微差异；若直接编辑不干净，再回退到重生成背景 + 擦字稿。文字始终是真 TextBox（PPT 里可改）。 如果用户一开始就明确要求只做可编辑版，则直接走 Phase C-only，不进入 Phase A。
• Phase D — PDF PPT 编辑分支（PDF 导入路径） 用户上传 PDF 幻灯片时，自动判断每页是矢量文本（可直接提取）还是图片型（需多模态理解）。用多模态模型抽取文案结构、角色、位置，生成 extraction.json 并在 HTML 预览页让用户确认。确认后按背景策略（clean 擦字 / rebuild 重建）生成无字背景，写入 phaseC/deck.json，接入 Phase C 编辑器（C4-C6）最终输出可编辑 PPTX。

[用户的模糊需求]
        │
        ▼
┌── Phase A（默认主路径）─────────────────┐
│  Stage 1     Intake + 需求确认           │
│  Stage 1.25  content_report.md          │
│  Stage 1.4   ★ 页大纲确认门禁           │
│              slide_outline.md → 用户确认 │
│  Stage 1.5   风格边界（3 个短问题）       │
│  Stage 2     多套风格预览（首/目/正）     │
│  Stage 2.5   风格 refinement             │
│  Stage 2.75  风格反演 + 风格确认          │
│  Stage 3     design_spec /              │
│              slide_blueprint /          │
│              spec_lock + 生成前确认       │
│  Stage 4     全页定稿图                  │
│  Stage 5     review + 用户批准           │
│  Stage 5.5   ★ retouch（可选，用户驱动）  │
└──────────────┬──────────────────────────┘
               │
               ▼   交付：图片型 PPTX + 全页定稿图 + 规划文档
               │
   ┌───────────┴───────────┐
   │ ★ 必须主动询问用户 ★    │
   │ "PPT 已交付。是否需要   │
   │  可编辑文字版（Phase C）│
   │  ——文字能在 PPT 里直接   │
   │  改？这会参考定稿图重生  │
   │  成无字背景，可能有细微 │
   │  差异；                 │
   │  每页约 2 张 imagegen。" │
   └─────────┬─────────────┘
             │
        用户同意 → 进 Phase C
             │
             ▼
┌── Phase C（可编辑文字版）─────────────────┐
│  C0  Phase C-only 轻量预览门禁（条件触发）│
│  C1  双轨生成背景                         │
│      (完整稿 → imagegen 擦字稿)           │
│  C2  detect_reserved_zones 校验           │
│  C3  写 deck.json                         │
│  C4  inject_editor_deck.py 注入编辑器     │
│  C5 ★ 统一编辑 + 背景反馈门禁（必跑）     │
│      文字模式 改字 / 拖框 / 调样式         │
│      背景反馈模式 矩形/画笔/注释点 + 意见  │
│      → 导出包贴回（含可选 BG REVIEW 段）   │
│      → 有 BG REVIEW: 修背景 → 重出编辑器   │
│      → 无 BG REVIEW: 进 C6                 │
│  C6  校验 deck.json → 渲染 PPTX           │
└──────────────┬──────────────────────────┘
               ▼
[追加交付：文字可编辑 PPTX + deck.json + backgrounds/]

---

I/O Contract

Phase A 必交付（默认）

• content_report.md（用户没给完整内容稿时）
• slide_outline.md（Stage 1.4 页大纲确认，用户已批准）
• design_spec.md / slide_blueprint.md / spec_lock.md
• 每页定稿图 phaseA/slides/NN-*.png
• 图片型 .pptx（高完成度视觉稿，用于汇报/展示——这是默认终交付物）
• phaseA/imagegen-manifest.json

Phase C 追加交付（用户同意走可编辑路径时）

• 每页背景图 phaseC/backgrounds/NN.png（+ 第 1 稿 NN-full.png 备查）
• phaseC/deck.json（单一真相源，编辑器 / 渲染器共同消费）
• 每页 phaseC/NN-zones.json + phaseC/NN-zones.report.json
• 文字可编辑 .pptx（背景 = Picture，文字 = 真 TextBox，跨平台稳定）
• 可选 phaseC/preview/slide_NN.png 近似对照图

Phase D 交付（PDF 导入路径）

• phaseD/extraction.json（初版抽取结果）
• phaseD/extraction_review.html（HTML 预览页）
• phaseD/extraction_confirmed.json（用户确认后的版本）
• 每页背景图 phaseC/backgrounds/NN.png（clean 擦字或 rebuild 重建）
• phaseC/deck.json（从 extraction 转换而来）
• 文字可编辑 .pptx（最终产物，接入 Phase C 渲染管道）

输入

PPT 主题 / 粗略目标 / 零散材料 / 已有报告稿 / PDF 幻灯片；可选锚点（受众、页数、身份锚点、用途场景、参考图、风格倾向）。

确认门禁

• 5 个必有门禁（Phase A）：需求确认 → 页大纲确认 → 风格确认 → 生成前确认 → 终图评审
• 第 4 个门禁（强制主动询问）：Phase A 终图交付后必须主动问用户是否需要 Phase C 可编辑文字版
• Phase C 内的门禁：用户在 HTML 编辑器里点 "导出 deck.json" 表示满意
• Phase D 内的门禁（G-D-ContentConfirm）：用户在 extraction_review.html 里确认/修改文案后点"导出确认"

比例

默认 16:9。Phase A/C/D 全程必须同一比例，禁止中途切换。

---

★ 主动询问 Phase C 的规则（最关键的行为）

Phase A 全部交付完成后，必须主动询问一次用户是否要走 Phase C。这是这条 skill 的硬约束。

询问时机

• Phase A Stage 5（review）通过 + Stage 5.5 retouch 处理完（如果跑了）
• 已经把图片型 PPTX 和所有定稿图给到用户
• 在结束对话前

询问话术（参考，可调措辞）

图片版 PPT 已经做好了：

• 图片型 PPTX：<path>
• 全 N 页定稿图：<path>
• 规划文档：<paths>

现在的成品是图片版，每页是一整张图——好处是视觉密度最高、跨平台不会跑版；缺点是文字不能在 PowerPoint 里直接改。

如果您后续可能要改文字（比如换日期、换名字、换关键数字、改标题措辞），我可以继续走 Phase C 给您出一份文字可编辑版：

• 参考当前定稿图重新生成无字背景（保留整体风格和装饰，预留文字区；不是从原图里精确抠字，可能有细微差异）
• 文字作为独立图层，在浏览器编辑器里调
• 一键渲染成原生可编辑 PPTX
• 大致成本：每页约 2 张 imagegen（背景完整稿 + 擦字稿），N 页约 X 次调用

要不要进 Phase C？（不需要也可以，图片版本身就能直接拿去汇报）

询问后的分支

• 用户说要 / 好 / 进 Phase C / 我后期还要改字 → 按 references/phaseC/workflow.md 跑 C1-C6
• 用户说不用 / 这样就够了 / 先这样 → 结束对话，不要再追问
• 用户没正面回答（比如继续聊别的） → 不要打断，等用户自己提

反模式（不要这样做）

• ❌ 不询问就直接进入 Phase C
• ❌ 不询问就直接结束对话（用户可能不知道有可编辑选项）
• ❌ 反复追问、施压让用户走 Phase C
• ❌ 把"是否进 Phase C"作为 confirmation gate 强卡用户（它是一个开放问题，不是必跨门禁）

---

★ 用户从编辑器贴回内容时的处理规则（极重要）

Phase C editor.html 里用户点”导出 / 继续生成”后会得到一段带 sentinel 的”指令包”，现在有两种格式：

格式 A（只有文字改动，没有背景反馈）

===PPT-CRAFT-EDITABLE / DECK FROM EDITOR===
...
===DECK JSON BEGIN===
{ ... 完整 deck.json ... }
===DECK JSON END===

格式 B（文字改动 + 背景反馈，同一次导出）

===PPT-CRAFT-EDITABLE / DECK FROM EDITOR===
...
===DECK JSON BEGIN===
{ ... 完整 deck.json ... }
===DECK JSON END===

===PHASEC BACKGROUND REVIEW BEGIN===
{ ... phasec-background-review-v1 ... }
===PHASEC BACKGROUND REVIEW END===

当 agent 在对话里看到这两种标记时，必须：

格式 A（只有 DECK JSON）→ 直接渲染

1. 把 ===DECK JSON BEGIN/END=== 之间内容原样写入 phaseC/deck.json（覆盖旧版）
2. 跑 python3 scripts/json_to_pptx.py phaseC/deck.json -o phaseC/edited.pptx --preview-dir phaseC/preview
3. 把 phaseC/edited.pptx 路径告诉用户，结束

格式 B（还有 PHASEC BACKGROUND REVIEW）→ 先修背景，再重开编辑器

1. 同样先把 ===DECK JSON BEGIN/END=== 之间内容写入 phaseC/deck.json（保留文字改动）
2. 读取 ===PHASEC BACKGROUND REVIEW BEGIN/END=== 里的 pages[]，按 requested_action + page_comment / markup 修 phaseC/backgrounds/*.png：
   • retouch-local → IOPaint 局部修补当前背景
   • regenerate-background → 以反馈为依据重生成该页背景
   • adjust-text-zones → 调整背景留白区，必要时同步 phaseC/*-zones.json；文字框位置等后续在编辑器里调
   • approved → 该页背景通过，不修
3. 背景修完后，重新注入编辑器：scripts/inject_editor_deck.py（用刚保存的 deck.json + 新背景）
4. 打开新的 editor.html 让用户再确认一次，不要直接渲染 PPTX

不变的规则（格式 A / B 共同遵守）

• 不要”解读” / “总结” / “评论” JSON 内容——数据已定稿，只搬运
• 不要修改 deck.json 任何字段——不改字号字色不重排版
• 以这一份 deck.json 为最新真相源——不用旧版本

反模式（不要做）

• ❌ 格式 B 有背景反馈却直接渲染 PPTX —— 用户的修背景意见会被丢掉
• ❌ 格式 A 收到又去问”要不要渲染” —— sentinel 已写明，直接渲染
• ❌ 用之前生成的 deck.json 老版本渲染 —— 必须用贴回来的这一份
• ❌ 把 phasec-background-review-v1 段当成 Phase A review 去跑 render_review_markup.py
• ❌ 用背景反馈的意见直接改 deck.json.text_boxes（绕过背景问题）

用户行为提示（agent 该告诉用户的）

当 Phase C 编辑器打开时，agent 应明确告诉用户：

编辑器已打开。

• 改完文字后：点右上角 ”导出 / 继续生成” → 复制整段（带 === 标记）→ 粘贴回对话框，我会直接渲染 PPTX
• 发现背景要改：点 ”🖊 背景反馈” 切换到标注模式，对背景框选/画笔/写意见，然后同样导出整段贴回来，我会先修背景再重新打开编辑器给你确认

两件事可以同时做：先在文字模式调好字，再切到背景反馈模式标注，最后统一导出一次即可。

失败兜底

• 用户只粘了裸 JSON（无 sentinel）→ 仍保存为 phaseC/deck.json 并渲染，但提醒下次复制整段
• 用户粘了 sentinel 但 JSON 有错（缺 slides 等）→ 报错，让用户回编辑器修后重新导出，不自动猜补

---

何时使用本技能 / 何时只走 Phase A / 何时上 Phase C / 何时走 Phase D

用户场景	路径
只要好看的视觉稿、做完汇报就结束	Phase A（默认）
没明确点名，只丢主题、要完整成品	Phase A（默认）
Phase A 出图有水印 / 小瑕疵想擦掉	Phase A + Stage 5.5 retouch
Phase A 完成后用户说要可编辑	Phase A → Phase C（按上面"主动询问"规则）
用户一开始就说"要可编辑 / 后期改字"	Phase C-only（先补最小输入，再跑 C1-C6）
用户明确说"只做可编辑版 / 跳过图片版"	Phase C-only
用户上传 PDF 幻灯片想转可编辑版	Phase D（PDF 导入路径）
用户说"把这个 PDF PPT 转成可以改字的"	Phase D
用户提供 PDF + 明确说要编辑文字	Phase D

---

★ Phase D 入口与 Sentinel 处理规则

触发条件

当用户满足以下任一条件时，进入 Phase D：

• 上传或提供 PDF 文件路径，并提到"转成可编辑" / "想改文字" / "PPT 编辑"
• 明确说"把 PDF 转成 PPTX" / "PDF 转可编辑 PPT"
• 提供 PDF 并询问能否编辑其中内容

Phase D Sentinel 标记

当对话中出现以下标记时：

===PHASE-D / CONTENT EXTRACTION CONFIRMED===

本次从 PDF 提取了 N 页内容，已在预览页确认。

===EXTRACTION JSON BEGIN===
{ ... }
===EXTRACTION JSON END===

agent 必须：

1. 把 ===EXTRACTION JSON BEGIN/END=== 之间的内容原样写入 phaseD/extraction_confirmed.json
2. 不解读、不修改、不追问 JSON 内容
3. 直接进入 D3 背景处理：
   • 简单页（strategy: "clean"）→ 擦字保留原背景
   • 复杂页（strategy: "rebuild"）→ 仿照重建背景
4. 生成 phaseC/backgrounds/*.png
5. 把 extraction.json 转成 phaseC/deck.json
6. 接入 Phase C 编辑器（C4-C6）

Phase D 不做的事

• ❌ 不主动询问是否进入 Phase C（Phase D 本身就是为可编辑而生）
• ❌ 不跑 Phase A 的任何阶段（风格预览、规划文件、定稿图）
• ❌ 不生成图片型 PPTX（Phase D 直接输出可编辑版）

---

Progressive Loading

按需读，不要一上来全读：

何时读	文件
★ 用户首次触发本 skill（agent 默默跑）	scripts/preflight.py（自动装 pip 包 + 调 doctor；不需要问用户）
单纯环境检查（不动用户系统）	scripts/doctor.py（不会自动装东西，纯报告）
路由 / 决定本技能怎么跑（必读）	本 SKILL.md
跑 Phase A 总流程	references/phaseA/workflow.md
Phase A intake / 对话框架	references/phaseA/conversation_framework.md
Phase A 出风格预览、候选选图、review 页面	references/phaseA/preview-flow.md
Phase A 三个壳子的图片/数据注入（必读）	references/phaseA/shell-injection.md
Phase A 风格提案卡 / V1-V8 内部	references/phaseA/style-system.md
Stage 5.5 retouch（去水印 / IOPaint / ImageMagick 兜底）	references/phaseA/retouch.md
写 content_report.md	templates/content_report_reference.md
写 slide_outline.md（Stage 1.4 页大纲）	templates/slide_outline_reference.md
写 design_spec.md	templates/design_spec_reference.md
写 slide_blueprint.md	templates/slide_blueprint_reference.md
写 spec_lock.md	templates/spec_lock_reference.md
Phase C 总流程（用户同意进 Phase C 时）	references/phaseC/workflow.md
Phase D 总流程（用户上传 PDF 时）	references/phaseD/workflow.md
Phase D extraction.json schema	references/phaseD/extraction-schema.md
端到端运行手册 + 失败排错	references/pipeline.md

---

内置工作流壳子（assets/）

Phase A 必须使用以下 3 个本技能自带的 HTML 壳子，不要替换或自造同类页面：

• assets/preview_shell/index.html — 风格预览比较（Stage 2）
• assets/candidate_picker_shell/index.html — 多候选选图（Stage 4 多候选模式）
• assets/review_shell/index.html — 评审与返修（Stage 5）

Phase C 增加一个：

• assets/editor_shell/index.html — 文字编辑器（C4-C5）

⚠️ 四个壳子的 index.html 默认是空架子 / 示例数据：preview_shell 的 9 张图是写死的 SVG 占位图；candidate / review / editor 都带示例数据。真正使用之前必须显式注入真实数据，否则用户打开页面看到的会是占位。

统一注入命令（强制）：

# Stage 2 风格预览
python3 scripts/inject_shell_images.py preview \
  --shell assets/preview_shell/index.html \
  --data  preview_data.json \
  --out   phaseA/previews/preview_filled.html

# Stage 4 多候选选图
python3 scripts/inject_shell_images.py candidate \
  --shell assets/candidate_picker_shell/index.html \
  --data  candidate_data.json \
  --out   phaseA/candidates/picker_filled.html

# Stage 5 评审
python3 scripts/inject_shell_images.py review \
  --shell assets/review_shell/index.html \
  --data  review_data.json \
  --out   phaseA/review/review_filled.html

# Phase C 文字编辑器
python3 scripts/inject_editor_deck.py \
  --shell assets/editor_shell/index.html \
  --deck  phaseC/deck.json \
  --out   phaseC/editor.html

• 各 data JSON 的 schema 见对应脚本顶部 docstring。
• 打开时必须打开 *_filled.html / editor.html，不要打开 assets/.../index.html 原模板。
• 默认保留相对路径，配合 HTML 与背景图同目录使用；要打包分发再加 --inline 把图片 base64 嵌入 HTML，或加 --file-url 改成绝对 file://。
• editor.html 默认应与 phaseC/backgrounds/ 旁置，避免把背景内嵌成 7MB+ 的单文件。
• build_*.py 三个脚本只是把壳子从内嵌 base64 还原成 index.html，它们不注入真实数据，不要把 build 和 inject 搞混。

---

Phase A 规则（Conversation-first + Image-first）

按 references/phaseA/workflow.md 跑完所有 Stage。这里只列死规则。

Working Principles

• 把用户当成甲方，本技能当作提出方向的设计侧。
• 不强迫用户填一堆设计参数；把自然语言意图翻译成设计决策。
• 默认展示 baseline judgment / proposal cards / 预览 / review 界面；规划文件原文按需出示。
• 标注 user_provided / inferred / needs_confirmation；不擅自编造未授权事实、数据、引用、机构结论。

Hard Rules（Phase A 必守）

• Preview-first：最终风格确认必须基于真实生成的「首页 + 目录页 + 正文页」预览，不能用文字 mockup / ASCII 草图 / 占位壳代替。
• Shells are mandatory：必须使用 assets/preview_shell/index.html、assets/candidate_picker_shell/index.html、assets/review_shell/index.html。打开前必须先用 scripts/inject_shell_images.py 把真实图注入到 *_filled.html，不要直接打开壳子原模板。
• Image-first 不退化：定稿出图必须 image-first，不允许悄悄退化到"用 PPT shape 拼页面"或"代码画图"兜底。
• 用户要"加字 / 改字 / 补字"也仍然属于图像生成/编辑任务；不要默认用 PIL / Canvas / SVG / HTML 截图 / PPT 原生文本框去后期补字（除非用户明确要求这种 workaround）。
• 生成 ID 不入 prompt：slide id / candidate code / 文件名 / 批次标签等可以出现在规划文件、文件名、映射表、review UI、对话里，但不要拼进发给图像模型的 prompt 文本。
• 不要在第一轮就导出最终 PPT；只有 review 通过后才导出。
• slide_blueprint.md 不能在风格反演确认之前写。
• 生成前必须问：单图直出 / 多候选 picker。
• Phase A 交付后必须主动询问 Phase C（见上面"主动询问"段）。

内置工作流的 5+ 个 Stage（极简版索引）

1. Stage 1 — Intake + baseline judgment → 需求确认
2. Stage 1.25 — 风格前内容研究 → content_report.md（除非用户已给完整稿）
3. Stage 1.4 ★ — 页大纲确认门禁：写 slide_outline.md，逐页列出将要出现在 PPT 上的可见文字 + claim_status，贴摘要给用户，等用户确认后才进 Stage 1.5
4. Stage 1.5 — 风格边界对齐（3 个短问题）
5. Stage 2 — 风格提案与真实预览（首页 / 目录页 / 正文页），打开 preview_shell；可选 Stage 2.5 refinement；必跑 Stage 2.75 风格反演确认 → 风格确认
6. Stage 3 — 顺序写 design_spec.md → slide_blueprint.md → spec_lock.md → 生成前确认
7. Stage 4 — 单图直出 / 多候选 picker（若多候选先打开 candidate_picker_shell）出齐全页定稿图
8. Stage 5 — 打开 review_shell 做评审；不通过则用 scripts/render_review_markup.py 渲染标注图 + 文本反馈再喂回去返修
9. Stage 5.5 — ★ 图像级 retouch（用户驱动，可选）：详见 references/phaseA/retouch.md
10. 交付 + 主动询问 Phase C — 把图片型 PPTX + 定稿图 + 规划文档交给用户，主动问是否要可编辑文字版

---

Stage 5.5 Retouch（默认提供，按需使用）

Phase A 出图被叠加了工具水印（典型如 Qoder 的 "Qoder AI生成"）、或某页角落有想擦掉的小瑕疵时，默认提供以下两个工具：

# 工具 1：批量去固定位置的角落水印（最省事，适合工具水印）
python3 scripts/remove_corner_watermark.py phaseA/slides/ -o phaseA/slides_clean/ --batch

# 工具 2：IOPaint 手工 inpaint（任意位置 / 复杂背景；效果最强）
# 首次自动调 setup_iopaint.py 装 IOPaint + LaMa（约 5–10 分钟、~3GB）
python3 scripts/launch_iopaint.py --slides-dir phaseA/slides

关键性质（agent 必须遵守）：

• 绝不在用户没要求时强制启动 IOPaint。Phase A 走完先告诉用户图在哪、PPTX 在哪、有没有发现水印 / 瑕疵，再问要不要进 Stage 5.5。
• 首次启动 IOPaint 会等待 5–10 分钟装环境 + 下模型，这点必须事先告诉用户。
• 安装完全幂等：标记文件在 ~/.cache/ppt-craft-editable/.lama-installed，二次启动秒开。
• 装失败不阻塞 Phase A 主路径：launch_iopaint.py / setup_iopaint.py 都内置失败兜底（重试 / remove_corner_watermark.py / ImageMagick 矩形遮罩）。
• retouch 不替代 review：实质内容 / 视觉改动应回 Stage 5 重出图；Stage 5.5 只解决"图整体没问题，那一小块要擦掉"。
• IOPaint 在 Phase C 里也能用——擦字稿不合规时局部涂抹擦干净比让 imagegen 重出整页省钱：python3 scripts/launch_iopaint.py --slides-dir phaseC/backgrounds。

完整工具说明、操作流程、何时该用 / 不该用，详见 references/phaseA/retouch.md。

---

Phase C 规则（可编辑文字路径）

仅当用户在 Phase A 交付后的"主动询问"中同意进入时才执行。完整流程在 references/phaseC/workflow.md，这里只列死规则。

Hard Rules（Phase C 必守）

• 沿用 Phase A 的 Stage 1-3：需求 / 内容 / 风格 / 规划文件全部走 Phase A 已经做好的成果，不要重做。
• 以 Phase A 定稿作视觉参考：Phase C 的用户承诺是参考 Phase A 结果重新生成无字背景，再叠加可编辑文字；不要把对外描述写成“从 A 图里精确抠掉文字”。背景可能与 Phase A 定稿有细微差异。
• 优先直编 Phase A 成品图：内部执行上仍默认先把 Phase A 定稿图作为 imagegen edit target 去字；如果去字后不干净或留白不合规，再回退到重生成背景 + 擦字稿。对用户说明时强调“参考定稿重新生成无字背景”，避免误解为像素级抠字。
• 回退时再走两稿：只有在直编失败时，才先出"完整稿"再以完整稿为 edit target 出"擦字稿"。不要把两稿逻辑当成默认必走。
• edit target 先看 Phase A 图：默认先 view_image Phase A 定稿图，再调 imagegen，prompt 写"以刚刚显示的这张图片作为唯一编辑目标"。不要只写本地路径。
• detect_reserved_zones 不可跳：每页擦字稿必须用 scripts/detect_reserved_zones.py 校验。不合规 → 重出 / IOPaint 局部擦。
• 统一编辑器门禁不可跳：deck.json 写好后，必须先注入编辑器打开给用户确认，再等用户把导出包贴回才能渲染 PPTX。不能跳过编辑器直接渲染。编辑器同时支持文字编辑和背景框选反馈，用户做了背景反馈 → agent 先修背景 → 重出编辑器，不能直接渲染。
• 不要再插入独立背景审计门禁：背景图反馈统一在 C5 编辑器的 🖊 背景反馈 模式里完成；本 skill 不再提供独立背景审计壳子。
• deck.json 是单一真相源：编辑器 / 渲染器都消费 deck.json。不要在 PPTX 渲染后再单独改 PPTX——回到 deck.json 改，重出 PPTX。
• 渲染前必须校验 deck.json：json_to_pptx.py 会自动调用 scripts/validate_deck_json.py；若缺 background、坐标越界、颜色格式错误或背景路径不可访问，必须先修 deck.json，不要猜补。
• 字体限定 SAFE_FONT_SET：见 scripts/json_to_pptx.py 顶部。不在集合里会有警告，跨平台可能掉 fallback。可用：PingFang SC / Microsoft YaHei / Hiragino Sans GB / Arial / Helvetica 等系统字体。
• 坐标用 fraction：所有 x/y/w/h 都是 0-1，跟 HTML 编辑器和 PPTX 渲染器同语义。
• 字号用 pt：直接写 font_size_pt，不要算像素。
• 背景引用可为相对路径 / 绝对路径 / file:// / data:：编辑器导出的 deck 可能带这些形式，json_to_pptx.py 必须直接兼容。
• 编辑器默认走旁置文件模式：inject_editor_deck.py 默认保留相对路径，editor.html 与 phaseC/backgrounds/ 放同一目录；只有明确需要时才用 --inline。
• 背景图固化、文字外挂：背景一旦生成就不再改（除非重出该页）；文字始终是外挂层。
• 编辑器是单文件 HTML：关闭浏览器不会自动保存。改完一定要先点"导出 deck.json"再关。
• Phase C 完成 = 终态：拿到可编辑 PPTX 后不要再追问 / 折返到其他路径。

Phase C 流程极简版（C1-C6）

1. C1 以 Phase A 定稿作视觉参考生成无字背景；内部先尝试直编，不干净再回退到完整稿 → imagegen 擦字稿
2. C2 scripts/detect_reserved_zones.py 校验预留区
3. C3 写 phaseC/deck.json（每页 background + text_boxes 初稿）
4. C4 scripts/inject_editor_deck.py 注入编辑器，生成 editor.html
5. C5 ★ 必跑 打开 editor.html，用户在统一编辑器里完成：
   • 文字编辑模式：改字 / 拖框 / 调样式
   • 背景反馈模式（按 🖊 背景反馈 切换）：矩形/画笔/注释点标注背景要改的位置
   • 导出完整指令包贴回对话框
   • 若有 BG REVIEW 段 → agent 修背景 → 重出 editor.html → 用户再确认
   • 无 BG REVIEW 段 → 进 C6 渲染
6. C6 scripts/json_to_pptx.py 渲染 → 可编辑 PPTX

---

关键命令（脚本都在 scripts/）

# ─── Stage 0：用户首次触发，agent 默默跑（无需问用户）──────

python3 scripts/preflight.py
# 自动安装缺失的 4 个 pip 包（首次 2-5 分钟），装完调 doctor
# 退出码 0 = 可继续；退出码 1 = 有不可自动修的项目，让用户处理

# 单纯想看环境状态（不动用户系统）
python3 scripts/doctor.py

# ─── 基础依赖（preflight 失败时手动装的兜底方案）─────────
pip3 install python-pptx pillow numpy opencv-python

# ─── Phase A ───────────────────────────────────────────────

# 把真实图注入工作流壳子（每个 Stage 出图后必跑）
python3 scripts/inject_shell_images.py preview   --shell assets/preview_shell/index.html           --data preview_data.json   --out phaseA/previews/preview_filled.html
python3 scripts/inject_shell_images.py candidate --shell assets/candidate_picker_shell/index.html  --data candidate_data.json --out phaseA/candidates/picker_filled.html
python3 scripts/inject_shell_images.py review    --shell assets/review_shell/index.html            --data review_data.json    --out phaseA/review/review_filled.html

# review markup 渲染（用户在 review_shell 给的坐标标注 → 标注图）
python3 scripts/render_review_markup.py <review.json> --out-dir <dir>

# ─── Stage 5.5 Retouch（用户驱动，可选）────────────────────

# 批量去角落水印
python3 scripts/remove_corner_watermark.py phaseA/slides/ -o phaseA/slides_clean/ --batch

# IOPaint：首次自动装环境 + 下 LaMa（5–10 分钟、~3GB），之后秒开
python3 scripts/launch_iopaint.py --slides-dir phaseA/slides
# Phase C 也可以用（擦字稿不合规时局部涂抹）
python3 scripts/launch_iopaint.py --slides-dir phaseC/backgrounds

# 单独管理 IOPaint
python3 scripts/setup_iopaint.py --check-only     # 检查
python3 scripts/setup_iopaint.py                  # 装
python3 scripts/setup_iopaint.py --reinstall      # 强制重装

# ─── Phase C（用户同意可编辑后才跑）─────────────────────────

# C2 校验擦字稿的预留区是否真的留白
python3 scripts/detect_reserved_zones.py phaseC/backgrounds/01.png phaseC/01-zones.json --report phaseC/01-zones.report.json

# C4 把 deck.json 注入编辑器壳子（C5 用户在里面调文字 + 提背景反馈）
python3 scripts/inject_editor_deck.py \
    --shell assets/editor_shell/index.html \
    --deck  phaseC/deck.json \
    --out   phaseC/editor.html

# C6 deck.json → 可编辑 PPTX（+ 可选 PIL 近似预览图）
python3 scripts/validate_deck_json.py phaseC/deck.json
python3 scripts/json_to_pptx.py phaseC/deck.json -o phaseC/<topic>.pptx --preview-dir phaseC/preview

---

输出目录结构（建议）

<topic-slug>/
├── content_report.md                    # 仅当 Stage 1.25 生成
├── slide_outline.md                     # Stage 1.4 页大纲确认门禁（必有）
├── design_spec.md
├── slide_blueprint.md
├── spec_lock.md
│
├── phaseA/                              # Phase A 产物（默认交付）
│   ├── previews/                        # 各阶段风格预览（保留备查）
│   ├── candidates/                      # 多候选模式时使用
│   ├── slides/NN-*.png                  # 评审通过的终图
│   ├── slides_clean/                    # Stage 5.5 retouch 后的图（可选）
│   ├── review/                          # 评审产物
│   ├── imagegen-manifest.json
│   └── <topic>-image-deck.pptx          # 图片型 PPTX
│
└── phaseC/                              # Phase C 产物（用户同意才出现）
    ├── backgrounds/
    │   ├── NN-full.png                  # 第 1 稿（完整稿，备查）
    │   └── NN.png                       # 第 2 稿（擦字稿，实际背景）
    ├── NN-zones.json                    # 每页预留区声明
    ├── NN-zones.report.json             # 校验报告
    ├── deck.json                        # 单一真相源
    ├── editor.html                      # 注入后的编辑器
    ├── preview/slide_NN.png             # PIL 近似预览图（可选）
    └── <topic>-editable.pptx            # 文字可编辑 PPTX

外置缓存（IOPaint 用，不在本目录里）：

~/.cache/ppt-craft-editable/
├── venv/                                # IOPaint 专属 venv
├── .lama-installed                      # 安装标记 + 元数据
└── setup.log                            # 安装日志

---

安装 / 依赖

把整个 ppt-craft-editable/ 复制到 agent 的 skills 目录即可。完全自包含，不依赖其他外部 skill。

# Codex
cp -R ppt-craft-editable "${CODEX_HOME:-$HOME/.codex}/skills/ppt-craft-editable"

Python 依赖（基础）：

pip3 install python-pptx pillow numpy opencv-python

Stage 5.5 IOPaint 是用户首次触发时自动安装：

• 装到专属 venv ~/.cache/ppt-craft-editable/venv/，不污染系统
• 自动 + 预下 LaMa 模型
• 国内默认走 hf-mirror 镜像
• 首次约 5–10 分钟、~3GB 磁盘；之后秒启
• 装失败有明确兜底（remove_corner_watermark.py / ImageMagick）

图像生成路径：依赖运行环境内可用的 imagegen 通道（Codex 用内置 imagegen / GPT Image 2）。如果运行时不可用，必须停在该 Stage 并向用户说明阻塞原因，不允许用 PIL/SVG/Canvas/PPT shapes 兜底。

---

致谢

本技能起源于：

• ppt-image-first（Phase A 工作流、references、templates、assets 部分原型） — Linux.do 社区

编排层、Stage 5.5 retouch 工具链、IOPaint 自动安装与启动器、Phase C 全套（双轨生成 + detect_reserved_zones + HTML 编辑器 + json_to_pptx 渲染器）—— 本 skill 自有。商用时请同时标明上述来源。