PPT Agent 状态机架构深度解析:Gate 校验如何做到只回退不跳过
PPT Agent 状态机架构深度解析:Gate 校验如何做到只回退不跳过
PPT Agent(ppt-agent-skills)是一个用"构建软件工程"的方式生成演示文稿的框架:它用严格的状态机驱动多 Agent 协作,每一步产物都必须通过 Gate 校验才能放行,失败时只允许重试或回退,绝不允许跳步。本文将拆解这套「只回退不跳过」机制的设计原理与落地细节,帮助你理解为什么它能从根源上避免大模型生成 PPT 时的幻觉、漏页与布局混乱。
一、为什么生成 PPT 需要一台"状态机"
直接让大模型"一口气"生成 20 页 PPT,常见结局是:漏页、前后风格漂移、图文重叠、做到一半中断后无法续跑。PPT Agent 的思路是把整个制作过程建模成一台有限状态机:
- 步骤是固定的:主链
P0 → P1 → (P2A|P2B) → P3 → P3.5 → P4 → P5禁止增删改名(见 SKILL.md 中的 Canonical Plan 定义); - 状态只信文件:每个步骤的进度不靠"口头记忆或 session 状态",而是由磁盘上的产物文件 + 校验脚本退出码决定;
- 迁移是受控的:两次状态迁移之间必须通过 Gate,Gate 不过,状态机就不往前走。
当前工作流版本由 scripts/workflow_versions.py 统一锁定(WORKFLOW_VERSION = 2026.04.09-v4.1),避免各环节对"版本"的理解漂移。
二、状态机主链:从需求到交付的 7 个状态
PPT Agent 的主链共 7 个 Step,每个 Step 内部再拆成编号子步骤(如 P2A.01~P2A.06),主 Agent 通过 CLI 原生的 plan 工具逐条追踪:
| Step | 核心动作 | 关键产物 | Gate 校验器 | 失败回退 |
|---|---|---|---|---|
| P0 | 采访并归一化需求 | requirements-interview.txt | contract_validator | 补问,不进 P1 |
| P1 | 识别输入、确认分支 | 分支字段写入需求文件 | 逻辑判断 + WAIT_USER | 等待用户 |
| P2A / P2B | 联网检索 / 本地资料压缩 | search-brief.txt / source-brief.txt | contract_validator | 回退当前步子步骤重跑 |
| P3 | 大纲构建(内部自审闭环) | outline.txt | contract_validator outline | 回退 P3.01 重建 subagent |
| P3.5 | 全局风格锁定 | style.json | contract_validator style | 回退 P3.5 |
| P4 | 逐页并行生产 | planningN.json / slide-N.html / slide-N.png | planning_validator + visual_qa | 只回退该页 |
| P5 | 导出交付 | 双 PPTX + delivery-manifest.json | contract_validator delivery-manifest | 只回退导出 |
两个细节值得注意:
- 硬等待点:
WAIT_USER/WAIT_AGENT是状态机中的阻塞态,未收到输入或 FINALIZE 信号前,禁止执行后续步骤。比如 P0 的采访阶段,即使用户第一句话给了大量信息,也严禁跳过。 - 分支二选一:P1 确认走 Research 分支(P2A)后,就绝对不能再跑 P2B,反之亦然——状态机里不存在"回头换条路"的模糊地带。
完整的步骤级命令手册在 references/cli-cheatsheet.md,主 Agent 在 Step 0 前必须读取它来建立接口认知。
三、Gate 校验:每一步之间的"入场券"
3.1 什么是 Gate
Gate 的定义只有一条:进入下一个 Step 前,前序 Gate 必须通过;当前步命令执行完毕且 Gate exit=0 后才能标记为 completed。它由一组 Python 校验脚本充当"门卫":
| 校验器 | 职责 | 主要守门位置 |
|---|---|---|
| scripts/contract_validator.py | 校验各阶段文本/JSON 产物是否满足"合同"(采访 17 个必填维度、大纲密度字段、风格字段、交付清单 schema 等) | P0 / P2 / P3 / P3.5 / P5 |
| scripts/planning_validator.py | 校验 Step 4 每页 planning JSON 的 schema 与资源引用 | P4 |
| scripts/visual_qa.py | 对 slide PNG 做纯像素级断言(16:9 比例、空白占比、装饰预算等),exit=1 致命、exit=2 警告 | P4 |
| scripts/milestone_check.py | 按里程碑阶段批量验收,串联上述校验器 | 断点恢复 / 阶段验收 |
脚本清单与依赖关系详见 scripts/README.md。
3.2 校验双保险:自审不等于放行
子代理(subagent)在 FINALIZE 前先自己跑一遍 validator 自审;主 Agent 回收产物后再跑同一 validator 复检——自审通过不等于主链放行。这是"子代理可能说谎、文件不会"的防御性设计。
3.3 Step 4 的三重防线
P4 是全流程最重的状态,每页产物要过三道关:
- 合同层:
planning_validator校验 planningN.json,三件套(planning + html + png)必须齐全; - 像素层:
visual_qa.py自动断言截图硬伤,exit=1 直接判定该页失败; - 人眼层:主 Agent 必须亲自看
slide-N.png,确认排版、内容完整性与视觉和谐度——自动校验不是人工审美的替代品。若开启人工审计模式(manual_audit_mode != off),review完成后还有强制的WAIT_USER放行点,用户明确"通过"前该页不得进入整页终检。
失败模式与修复顺序沉淀在 references/principles/runtime-failure-modes.md,审查细则在 references/playbooks/step4/page-review-playbook.md。
四、核心机制:为什么"只回退、不跳过"
4.1 失败时只允许两个动作
状态机对失败的处理被写死为二选一:
RETRY_CURRENT_STEP:原步重试;ROLLBACK→StepID:显式回退到指定步骤重做。
严禁"跳到后续步骤试试看"。这一步保证了:任何一步的缺陷不会被下游步骤"掩盖"后带进最终交付。
4.2 subagent 死亡 = 上下文全无
每个 Step 的正式产物必须由对应 subagent 生成(主 Agent 代写即合同违规)。一旦 subagent 会话失效,规则是:旧 session 一律视为不可续接,重建 subagent 整步重跑。例如 P3 大纲校验失败时,回退 P3.01 重新生成 prompt 并重建 Outline subagent,最多 2 轮仍失败则标记 BLOCKED_OUTLINE 呼叫用户裁决——而不是让主 Agent "顺手补一份大纲"。
4.3 回退粒度的自动升降级
P4 内部有一套精细的回退分级逻辑,避免"小修小补拖成大返工":
- 用户图审未通过 → 默认创建
PagePatchAgent-N从review重开,保留现有 planning 与 HTML,只修图审问题; - 同类 P0/P1 视觉问题连续 2 轮不收敛 → 说明病灶在预算/骨架层,强制回退 planning 重写密度合同;
- 单页连续 3 次失败 → 标记
BLOCKED_PAGE_N,先跳过推进其余页,最后集中处理,且必须向用户汇报失败摘要,由用户裁决手动修复/简化重试/跳过该页,禁止静默吞掉; - P5 导出失败 → 只回退导出,不回退内容生产。
五、无状态断点恢复:靠扫盘而不是进度文件
整套流程不写任何"进度状态文件"。中断后想继续,状态机通过里程碑探测从磁盘产物反推恢复点:
python3 SKILL_DIR/scripts/milestone_check.py <stage> --output-dir OUTPUT_DIR
探测从高到低依次尝试 delivery-manifest(P5)→ planning_validator(P4)→ style(P3.5)→ outline(P3)→ search-brief / source-brief(P2)→ requirements-interview(P0/P1),第一个 exit=0 就是最高自动通过点,然后从下一个未完成 step 继续;若某个前序 Gate 失败,则回退重做该步。
两条恢复红线:
- 自动探测通过后,主 Agent 仍需补跑
visual_qa并重新看图确认——旧 session 的"我觉得没问题"不算数; - 同一任务全程复用同一个 RUN_ID(
ppt-output/runs/<RUN_ID>/),恢复时绑定旧目录,不新建。
六、安装与上手:体验状态机驱动的 PPT 生成
git clone https://gitcode.com/gh_mirrors/ppt/ppt-agent-skills
或在支持 Skill 的代理环境中直接安装:
npx skills add sunbigfly/ppt-agent-skills
无需独立部署,一句话即可触发完整状态机:
"帮我生成一份关于 2026 年具身智能发展趋势的 15 页路演 Deck,暗色科技风格。"
主 Agent 会依次走完采访(P0)→ 分支确认(P1)→ 资料处理(P2)→ 大纲(P3)→ 风格锁定(P3.5)→ 逐页并行生产(P4)→ 双格式导出(P5),所有产物落盘到 ppt-output/runs/<RUN_ID>/,包含网页预览与 PNG/SVG 双 PPTX。
七、总结
PPT Agent 的"只回退不跳过"本质上是把软件工程里的三条铁律搬进了内容生产:
- 迁移受控:状态机主链固定,Gate(exit=0)是唯一的向前通道;
- 状态外置:进度只由磁盘产物与校验退出码表达,可中断、可恢复、可审计;
- 失败收敛:重试、定点回退、粒度升降级、BLOCKED 显式裁决——每种失败都有确定的归宿,没有"跳过去试试看"。
对使用者而言,这套机制的价值很直接:产出的每一页 PPT 都经过了合同校验、像素断言与人工审查三重关卡,而中途断电也能从断点精准续跑。想深入源码,推荐从 SKILL.md 的主控制台合同读起,再对照 references/cli-cheatsheet.md 中的 Gate 命令逐条验证。



