PPT Master 生成管线失败恢复治理：跨路由停止/继续规则、恢复矩阵与断点续跑实战指南

PPT Master 的 Default Generate PPTX 是一条多阶段长链路：从源内容处理、两阶段用户确认、图像获取、逐页 SVG 创作，到质量门禁与原生 PPTX 导出。任何一个环节失败，若处理不当都会导致重复规划、丢状态或"静默降级"。本文以仓库治理文档 failure-recovery.md 为骨架，完整展开其三层治理模型——跨路由全局停止/继续规则（§2）、Generate PPTX 专用恢复矩阵（§1）与断点恢复指针（§3），并结合 generate-pptx.md、confirm_ui.md、executor-base.md 等源码与命令文档，给出可直接落地的命令、工件与判断依据。读完本文，你将掌握：什么故障必须阻断管线、什么故障自动降级即可；每类故障的自动恢复动作、何时需要用户介入，以及从哪个阶段入口续跑。

---

1. 治理模型总览：三层规则如何分工

该治理文档把停止/继续规则组织为三层，作用域严格区分：

章节	作用域	职责
§2 全局停止/继续规则	跨全部三条路由（Generate PPTX、Create Template、Edit Native PPTX）	通用兜底：门禁工件缺失、便利面故障、派生工件过期、静默降级禁令等
§1 Generate PPTX 恢复矩阵	仅 Generate PPTX	按故障点给出"是否阻断 / 自动恢复 / 用户介入 / 恢复入口"四元组
§3 Generate PPTX 恢复指针	仅 Generate PPTX	按"最后良好状态"给出精确续跑入口

文档还规定：拥有路由与阶段的文档可以添加更窄的处理，但绝不能削弱这些规则或重复矩阵内容——即本文件是停止/继续治理的唯一权威，其他文档只能引用。

两条贯穿全文的硬规则：

硬规则 1：失败的必要工件（required artifact）阻断下一个门禁（gate）；失败的便利面（convenience surface，如 Confirm UI、live preview）回退到规范通道（chat 或命令行）且不阻断路由。

硬规则 2：运行时路径必须在每次工具调用内从入口时的 SKILL_DIR 锚点展开，绝不改变 CWD 或继承先前 shell 的工作目录（见 generate-pptx.md）。

这与仓库的工件所有权规范一脉相承：每个事实只能从它的属主工件读取，绝不把多个通道合并成第二个事实源（见 artifact-ownership.md 的开篇硬规则）。

---

2. 全局停止/继续规则（跨路由，§2）

2.1 规则总表

条件	动作
必要门禁工件缺失（required gate artifact missing）	在该门禁处停止并点名该工件
可选阶段未被显式请求	不作为恢复动作运行它
便利 UI / 服务器失败	回退到聊天或无需该表面继续
派生工件过期（derived artifact stale）	从其属主源重新生成
必要人工工件缺失	暂停并点名确切工件；只有它们存在后才继续
校验或导出失败	修复属主源工件，然后只重跑失败及其受影响的下游操作
已确认的执行选择无法被满足	保持已确认需求可见；只按属主工作流允许的方式重试已确认的 provider、mode、voice、effect 或 path；仍不可用时停下、请求新决策，或使用属主工作流声明的恢复。Quick 的 AI 生成例外是一个显式的无 AI 重规划：保留沟通任务，绝不换用另一个图片来源

2.2 缺失值（Missing values）的边界

对于已有工件中的某个字段，只遵循其属主 schema 或工作流声明的三种规则之一：必填性（requiredness）、推断过程（inference procedure）或固定默认值（fixed default）。一个没有此类规则的活动性省略（active omission），在属主边界处停下。

同时明确禁止"按类比扩展回退"（do not extend a fallback by analogy）——空值、非激活条件字段、整个工件或派生工件、文件格式属性，都不能用类比方式套用回退。仓库中只存在两种回退术语：

• declared-inference / declared-procedure fallback：声明缺失条件 + 有界过程，不需要新的用户决策；
• fixed compatibility default：声明确切值，应用时给出一次警告。

2.3 禁止静默降级（Forbidden — silent downgrade）

绝不因为下游命令"可能容忍"缺失文件而跳过必需门禁；绝不为了保持路由前进而改动已确认的执行值。正确动作只有四种：修复、暂停、请求新决策、在属主边界应用显式的 profile 属主恢复。

这条规则在导出阶段有直接体现：svg_to_pptx.py 导出器要求当前匹配的 final 质量报告，缺少、不可读、不支持、非 final、阻断、过期或不可验证的报告都会导致非零退出（见 generate-pptx.md Step 7.3），这正是"下游可能容忍缺失文件"的倒置——导出器在技术上拒绝容忍，从而把"静默降级"堵死。

2.4 主动生产化解（Proactive production resolution）

对于生产字段（Speaker Notes / Custom Animations / Narration Audio），解决顺序固定为：

最新显式指令 → final Stage 2 主动值 → 工作流默认（enabled / disabled / disabled）

• 启用 Narration Audio 会抬高 Speaker Notes（只要 Notes 未被显式禁用）；
• 显式 notes-off / audio-on 冲突时，在 Generate 的单问题依赖门禁处停下询问；
• 结果与溯源（provenance）只记录在 design_spec.md §I，绝不进入 spec_lock.md。

这也与 strategist.md §6.2 的规划工件语法一致：Design Spec 是可读的人类决策，lock 是其执行子集，result.json 只消费一次且不再重开。

---

3. Generate PPTX 恢复矩阵（仅 Generate PPTX，§1）

这是治理文档的核心资产：一张 43 行、五列的恢复矩阵，每行给出"故障点 → 是否阻断 → 自动恢复 → 用户介入 → 恢复入口"。矩阵必须被完整继承，下面先原样呈现完整矩阵，再按故障族分组给出命令级展开。

Failure point	Blocking	Automatic recovery	User intervention	Resume entry
Confirm UI launch failure	No	Re-check confirm_ui/result.json once, then chat fallback	No	generate-pptx Step 4 chat confirmation
Confirm UI wait timeout	No, if no final result yet	Re-check result.json once; server cleanup stays mandatory	Only if the user still wants the page	Step 4 same stage or chat fallback
User switches from Confirm UI to chat mid-stage	Yes until the current stage is confirmed	Follow the in-run switch in confirm-surface.md: keep persisted confirmed stages, continue the current and remaining stages in chat, never relaunch UI	Confirm in chat unless delegated	Step 4 current chat stage
Stage 1 completed, then interrupted while UI remains selected	Yes until final Stage 2 is confirmed	Read Stage 1 result.json, derive a fresh recommendations.stage2.json without changing Stage 1, then --wait-only	Usually no	Step 4 final Stage 2 write/wait
Missing final confirmation	Yes	None	User confirms or changes the values	Step 4 final confirmation
Final confirmed value or later explicit override missing, changed, or weakened in design_spec.md	Yes	Repair from the retained final-confirmation object plus any newer explicit instruction; only a fresh recovery turn with no retained state reads persisted evidence once	Only when the value genuinely cannot be honored	Step 4 Gate 1
spec_lock.md changes confirmed identity or omits a required anchor/routing decision	Yes	Re-author the affected rows from the completed Design Spec and context; do not enumerate page-local literals	No unless the Design Spec is incomplete	Step 4 Gate 2
Execution exposes a missing Strategist-owned role/plan detail	Yes for the page	Repair the Design Spec/lock fragments under executor-base.md §2.1	Only if confirmed intent changes	Step 4 Gate 1/2 → Step 6 current page
Execution context is fresh, resumed, compacted, external, or unknown	Yes until rebuilt	Read the complete Design Spec, then lock, once; reload triggered inputs and the latest completed SVG when mid-deck	No	Step 6 current page
apply-template-workspace rejects a legacy or incomplete template	Yes	Stop template consumption; create a new workspace through Create Template from the original PPTX/reference and return with its exact root	Only when source evidence or template choices are unavailable	Create Template → Step 4 Stage 1
Native formula marker validation or LaTeX compilation failure	Yes for the page	Repair the marker or LaTeX and rerun the checker; no formula-image fallback	Clarify the equation only when the source is ambiguous	Active SVG authoring step
AI image generation failure	Default blocks at the recovery decision; Quick does not	Default auto: try A → B, then ask once to repair/retry, generate manually, or cancel/replan; explicit api / host-native: retry that path, then ask. Quick removes exhausted AI/dependent-slice jobs, replans with native text/SVG or prepared non-AI assets, and continues	Default chooses one outcome; manual files still required before export	Default: Step 5 decision, Step 4 plan repair, or Step 7 image readiness gate; Quick: current resource plan
Web image search/download failure	No	Adjust query/source per image-searcher rules, then Needs-Manual if unresolved	Only if required with no substitute	Step 5
Slice sheet missing	Yes for derived slice rows	Wait for the parent sheet; run slice_images.py; rerun image analysis	Yes when the sheet was manual/offline	Step 5 slice handling / Step 7 image readiness gate
Strict-alpha slice failure	Yes for every named output	Return the parent to preparation; correct an evidenced key/tolerance mismatch, then enlarge cells or split incompatible shape families and regenerate; a parent never substitutes for its slices	Only after automated recovery is exhausted	Quick §2 resource closure / Default Step 5
Residual Pending or Failed image row before Executor	Yes	Re-run the owning path; Default AI follows its three-outcome decision and reaches Needs-Manual only after manual confirmation; Quick follows its no-AI replan	Only when the owning rule requires a new choice or file	Step 5 terminal-state check
User replaces/adds images after analysis	No	Re-run analyze_images.py before reading image facts	No	Step 4/5/6 image-fact read
Live preview fails to start / closed by user	No	Continue generation; report unavailability	Only if the user requires browser preview	Step 6, or live-preview Step 1 on request
Browser annotations submitted during generation	No	Defer application until after Step 7	User asks to apply	live-preview Step 2
svg_quality_checker.py error	Yes	Review the complete issue set from one unfiltered run; fix all errors and selected warnings in one consolidated pass, then one verification rerun; a remaining failure is the next batch — never check between individual fixes	No unless a required asset is missing	Step 6 Visual Construction
svg_quality_checker.py warning	No	Continue without mandatory modification; preserve compatible user syntax, report material advice when useful	No	Step 6 advisory handling
Missing notes/total.md while Speaker Notes is enabled	Yes	Generate notes before Step 7	No	Step 6 Logic Construction
Step 7 image readiness missing manual files	Yes	None; list required filenames and prompts	Yes	Step 7 image readiness gate
total_md_split.py failure	Yes	Fix notes format/path, rerun Step 7.1	Usually no	Step 7.1
finalize_svg.py failure	Yes	Fix SVG/assets, rerun Step 7.2	Only if a source asset is missing	Step 7.2
svg_to_pptx.py failure	Yes	Without a current passing final report: get the complete blocking set from the final checker, fix, rerun the checker, proceed only after passed; otherwise fix the conversion issue and rerun Step 7.3	Only if a required artifact is missing	Step 6 final quality gate or Step 7.3
Export succeeds but the user wants browser edits re-exported	No	Rerun Step 7.2 and 7.3 after the edits	No	Post-export live-preview handling

注：为避免表内换行破坏可读性，上表保留了原始英文术语（Blocking / Resume entry 等），与治理文档原文一一对应；本文其余部分使用中文叙述展开。

3.1 确认面故障族：便利面回退，不阻断路由

矩阵前四行全部围绕 Confirm UI 与聊天切换。核心事实：

• 启动失败与等待超时都是"不阻断"——先重新检查一次 confirm_ui/result.json，然后走聊天回退；但服务器清理（--shutdown）是强制性的。
• 阶段中途从 UI 切到聊天是"阻断"的（直到当前阶段被确认）：遵循 confirm-surface.md 的 in-run switch——保留已持久化的已确认阶段，当前及剩余阶段在聊天中继续，绝不重新拉起 UI。

命令层证据来自 confirm_ui.md 与 generate-pptx.md Step 4：

python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon                      # 启动组合 Stage 1
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1  # 等待 Stage 1 回执
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --complete-template-selection # 安装/自由设计闭环后的握手
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only                   # 等待 final Stage 2
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown                    # Step 4 清理（幂等）

生命周期细节决定了"恢复"怎么写：

• 默认绑定 127.0.0.1:5050 起的第一个空闲端口，--port N 精确绑定；等待预算默认 590 s（--wait-timeout），超时后服务器仍存活，调用方在聊天回退前重新检查两个 Stage-1 回执；
• 空闲 900 s 自动关闭，--shutdown 幂等且优先走 /api/shutdown 优雅退出；
• 项目级锁位于 <project_path>/.confirm_ui.lock，重复启动被拒绝，陈旧锁（死 pid）会被覆盖；
• --reset-template-selection 只清除 template_options.json、template_selection.json、template_handoff.json 三个侧车文件，绝不触碰 Strategist 文件、已安装模板内容或 result.json。

3.2 规划工件族：Gate 1 / Gate 2 与"证据只读一次"

矩阵中"Final confirmed value … missing, changed, or weakened in design_spec.md"与"spec_lock.md changes confirmed identity"两行分别对应用户确认 → Design Spec → lock 的两道门禁：

• Gate 1（active-decision fidelity）：用保留的最终确认对象修复 design_spec.md；只有无保留状态的全新恢复轮次才被允许把持久化最终证据读一次。result.json 的最终对象（stage: final + status: confirmed）在 Step 4 被恰好读取一次并保留到 Design Spec 写作完成，之后不再重开（见 confirm_ui.md 的 final-result consumption contract）。
• Gate 2（lock context fidelity）：保持 Design Spec 不动，只重写不匹配的 lock 行；lock 可以规范化语法、补充有依据的重复角色，但绝不能改变身份、丢弃细化、引入方向或变成字段拷贝/允许清单（strategist.md §6.2）。

"执行上下文是 fresh / resumed / compacted / external / unknown"一行则给出了完整重载顺序：读完整 Design Spec，再读一次完整 lock；若处于 deck 中途，重载触发输入与最新一张已完成的 SVG——这正是 resume-execute.md 的核心机制：新会话里"继续生成 projects/"进入 Step 6 前，先做 design_spec.md + spec_lock.md 的存在性 sanity check，二者任一缺失即按 §3 恢复，绝不进入 Step 6 或把孤儿 lock 当作权威。

3.3 图像与切片故障族：三层恢复哲学

• AI 图像生成失败（Default vs Quick 分叉）：Default 的 auto 路径先 Path A 再 Path B，两者耗尽后问一次——修复重试同路径、手动生成、或取消相关 AI 图并修复计划；只有确认的 manual 才产生 Needs-Manual 行（见 image-base.md §3 的"自动耗尽先于阻断"硬规则）。Quick 则完全不同：耗尽自动化后进入显式 no-AI replan，移除耗尽的 AI/依赖切片任务，用原生文本/SVG 或已备好的非 AI 资产重规划并继续——绝不让另一个图片来源顶替（quick-generate.md §2）。
• 切片（slice）故障：父 sheet 缺失 → 等待父表、运行 slice_images.py、重跑图像分析；严格 alpha 切片失败 → 父图退回准备态，修正有证据的 key/tolerance 不匹配，或扩大单元格 / 拆分不兼容形状族后重新生成——父图绝不顶替其切片输出。命令形如：

  python3 ${SKILL_DIR}/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names ... --trim --alpha --bg KEY_HEX_FROM_PROMPT --strict-alpha
  

• 残留 Pending / Failed 图像行：Executor 开始前必须终结；Default AI 走其三结果决策，只有手动确认后才到达 Needs-Manual。
• 用户在分析后增删图片：不阻断，但读取图像事实前必须重跑 python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images——analysis/image_analysis.csv 是 images/ 的再生视图而非持久缓存（artifact-ownership.md §3 再生规则）。

3.4 质量检查器故障族：合并修复纪律

svg_quality_checker.py 的 error/warning 区分在矩阵中对应两行：error 阻断，warning 不阻断。error 的修复纪律极其严格（executor-base.md §3 Checkpoints）：

运行一次不过滤的 checker，审阅完整问题集，在一个合并修复轮里修掉全部 error 与选中的 warning，然后做一次验证重跑；仍失败的问题成为下一个批次——绝不在单个修复之间反复检查。

门禁命令（Generate Step 6，generate-pptx.md）：

python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --canonical-authoring --stage early --json   # P05 后、P06 前；≤6 页跳过
python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --canonical-authoring --stage final --json   # 全部页面存在后

--json 写报告文件（validation/svg_quality_early_report.json / validation/svg_quality_report.json），stdout 保持人类可读摘要且绝不被当作 JSON 解析；final 报告被导出器按指纹绑定到 svg_output/，这正是"报告过期 → 导出拒绝"的实现机制。checker 每次调用必须跟随"门禁点"或"一个合并修复轮"之一——"验证一个早期写作模式"不是理由（pacing violation）。

3.5 备注、后处理与导出故障族：严格串行子步骤

Step 7 是严格串行的三个子步骤，一条命令一个调用，前一个成功且满足成功判据后才进入下一个（generate-pptx.md Step 7）：

子步骤	命令	成功判据
7.1 演讲备注切分（仅启用时）	python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>	notes/ 下每页 Markdown 覆盖全部发布页
7.2 自包含 SVG 预览	python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>	svg_final/ 每页一份自包含预览；其缺失不阻断 7.3
7.3 原生 PPTX 导出	python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>（Notes disabled 时追加 --no-notes）	退出 0，产出 exports/<project_name>_<timestamp>.pptx 与 validation/<...>.report.json（passed / passed-with-warnings）

失败恢复遵循同一原则：修复属主源工件，从失败的子步骤续跑；绝不因源未变就重启规划。finalize_svg.py 失败 → 修 SVG/assets 重跑 7.2；total_md_split.py 失败 → 修备注格式/路径重跑 7.1；svg_to_pptx.py 失败 → 若无当前通过的报告，先取 final checker 的完整阻断集修复并重跑到 passed，否则修转换问题重跑 7.3。

"Step 7 图像就绪门禁"也是一个典型阻断点：任何必需行处于 Needs-Manual 时，images/ 下必须已存在每个预期文件与切片输出，否则暂停并列出确切文件名，绝不运行 finalize_svg.py 或 svg_to_pptx.py，绝不发布虚线占位符。

---

4. Generate PPTX 恢复指针（仅 Generate PPTX，§3）

4.1 "最终确认证据"的定义（关键前提）

Final confirmation evidence = 当前聊天中的显式最终确认，或 <project>/confirm_ui/result.json 中 status: confirmed + stage: final 的对象；仅靠规划工件不能证明任何东西。

在该门禁之后，一条更新的显式指令只更新其在 Design Spec 中的有效生产结果与溯源，从属主步骤续跑，不重开 Confirm UI。UI 等待条目只在 UI 仍是所选表面时适用；更新的聊天表面指令则走 in-run switch，在聊天中续跑。

4.2 断点续跑总表

Last good state	Resume from
Stage 1 confirmed, final Stage 2 missing or unconfirmed, UI selected	Derive a fresh recommendations.stage2.json from confirmed Stage 1 and current inputs, then confirm_ui/server.py <project> --wait-only
Final evidence exists; design_spec.md missing (with or without a surviving lock)	Step 4 and strategist.md §6.2: read final evidence once, read design_spec_reference.md, author the complete Design Spec from scratch, pass Gate 1; then read spec_lock_reference.md and re-author the complete lock, replacing any orphan. Never reconstruct the Design Spec from an orphan lock
Final evidence exists; Design Spec exists, lock missing	Step 4: read final evidence once to audit the Design Spec, then author the complete lock from it plus context
Both planning artifacts exist but Gate 1 fails	Read final evidence once, repair design_spec.md, re-author every affected lock row; do not reopen recommendations or infer from the lock
Gate 1 passes, Gate 2 fails	Keep the Design Spec; re-author only the mismatched lock rows
No final evidence	If result.json proves Stage 1, resume at final Stage 2; otherwise restart Step 4 at Stage 1. Never infer confirmed choices from partial artifacts
Both planning artifacts complete, split mode selected	resume-execute
Images acquired, SVGs not started	generate-pptx Step 6
SVGs complete and checker passed; Speaker Notes enabled, notes missing	Step 6 Logic Construction
SVGs complete; Speaker Notes disabled	Conditional motion handling, then Step 7.2 and export with --no-notes
SVGs and notes complete	Step 7.1
Step 7.1 complete	Step 7.2
Step 7.2 complete, PPTX missing	Step 7.3
Browser annotations saved after export	live-preview Step 2

4.3 默认原则

默认 — 从失败的属主步骤续跑：除非属主源发生变化，否则不重启规划、不重新生成先前的工件。

这条默认原则与 Step 7 的"严格串行"硬规则共同构成整条管线的恢复基石：状态以磁盘工件为准，能续跑就绝不重来。也正是这个原则，让 resume-execute.md 能够在全新聊天中仅凭 design_spec.md + spec_lock.md 的存在性检查就安全地接管 Step 6–7——上下文无关（context-independent）的恢复正是这套治理的最终形态。

---

5. 治理如何落地：源码级印证与相关文档导航

• 恢复矩阵的"属主工件"语义：每个工件由谁读写、何时可再生，见 artifact-ownership.md 的所有权矩阵（§1）与再生规则（§3）——analysis/image_analysis.csv 由 analyze_images.py 再生、notes/slide_*.md 由 total_md_split.py 从 notes/total.md 再生、svg_final/ 由 finalize_svg.py 从 svg_output/ 再生、validation/svg_quality_report.json 由 checker 从 svg_output/ 再生。
• 恢复入口对应的完整流程：Step 1–7 的门禁、角色切换与强制命令，见 generate-pptx.md；Quick 单遍简档的恢复差异（无 AI 重规划、无 spec/lock、lockless final checker），见 quick-generate.md。
• 确认面语义：surface 决策、in-run switch、recommendations.stage1.json / .stage2.json / result.json 的载荷形状，见 confirm-surface.md；服务器生命周期、端口/锁、模板选择侧车与进度守卫，见 confirm_ui.md。
• 执行上下文与修复纪律：Executor 的 §2.1 绑定规则（binding vs realization）与 §3 合并修复纪律，见 executor-base.md；上下文失效后的完整重载顺序，见 resume-execute.md。
• 模板工作区被拒的恢复路径：旧版或不完整模板包绝不原地迁移——通过 Create Template 新建工作区后带着确切 root 返回 Stage 1（apply-template-workspace.md §1 的 raw source boundary）。
• 路由归属：Generate PPTX / Create Template / Edit Native PPTX 三条顶级路由的划分与触发条件，见 routing.md——治理文档的 §2 正是这三条路由共享的停止/继续底线。

一句话总结：PPT Master 的失败恢复不是"出错了重来"，而是一张可执行的决策表——阻断与否由门禁工件决定，自动恢复遵循属主源再生，续跑入口永远指向磁盘工件对应的属主步骤；唯一必须停下请人拍板的，只有那些无法自动、无法推断、也无法降级的真实缺口。