open-design 中 PPT Master 原生 PPTX 渲染桥接契约:Humanize 与可编辑 PowerPoint 的边界、语义映射与 OOXML 体检
open-design 中 PPT Master 原生 PPTX 渲染桥接契约:Humanize 与可编辑 PowerPoint 的边界、语义映射与 OOXML 体检
本文基于 open-design 仓库中 humanize-ppt 插件的
adapters/ppt-master-bridge-notes.md桥接契约文档展开,完整讲解"Humanize(演讲编排层)→ PPT Master(原生可编辑 PPTX 渲染层)"两条路线的职责边界、路由表、逐项语义映射规则、ppt-master-source.md语义源契约,以及渲染后基于 OOXML 静态扫描的演讲体检(QA)命令与 11 类 PPTX 专属失败模式。读完本文,你将掌握在 open-design / humanize-ppt 体系中如何以"brief-only"原则编排一个原生可编辑 PPTX 任务、如何在模板填充与主 SVG 管线两条路线之间正确选择参数,以及如何用--qa-from对导出的deck.pptx做可自动化的结构级质量验收。
一、背景:为什么需要一个 PPT Master 桥接层
humanize-ppt(插件目录 plugins/community/humanize-ppt)是一个"为演讲而生"的演示系统:它负责把原始素材(markdown / 文本 / 研究文档)加工成 AST(Audience-State-Transfer,听众状态转移)大纲、逐页媒体决策和一份下游可消费的生产简报(production brief),但它自己从不渲染幻灯片。渲染工作由下游技能(skill)承担,而 PPT Master 正是其中负责"原生可编辑 PowerPoint"(native editable PPTX)的那一条路线。
在 renderer_registry.json 中,ppt-master 的 support_level 为 full,其能力定位包括:原生 DrawingML 形状、speaker notes、原生转场与对象动画、可编辑表格与图表、以及 raw .pptx 模板原生填充。renderer_registry.json 记录了 2026-07-10 的真实验证证据:主 SVG 管线真实导出 10 页 / 399 个可编辑容器,模板填充路线真实导出 5 页 / 199 个可编辑容器,两条路线均通过 LibreOffice 打开渲染,并包含 notes、Fade transition 与 Humanize 的 OOXML 演讲体检。
adapters/ppt-master-bridge-notes.md(即本文主体,位于 plugins/community/humanize-ppt/adapters/ppt-master-bridge-notes.md)就是这两个系统之间的契约文档:它明确谁拥有什么、什么情况下走哪条路由、Humanize 的语义字段如何映射到 PPT Master 的原生概念,以及渲染完成后 Humanize 如何对 PPTX 做结构级体检。
二、职责边界(Boundary):谁拥有什么
桥接契约的第一条原则是清晰的双向边界,任何一方都不能越界:
| 系统 | 拥有 | 禁止 |
|---|---|---|
| Humanize | 听众状态转移故事(audience-state-transfer)、ppt-master-source.md、ppt-master-production-prompt.md |
不得导入 PPT Master 的模板、不得修补导出的 OOXML |
| PPT Master | 项目创建、强制的 Strategist 确认(mandatory Strategist confirmation)、design_spec.md、spec_lock.md、顺序 SVG 创作(sequential SVG authoring)、notes 打包、原生 DrawingML 导出、动画、模板填充 |
不得擅自改写 Humanize 冻结的页面故事 |
2.1 生产简报要求一个真实的 Python 解释器
契约特别强调:ppt-master-production-prompt.md 会解析一个真实的 Python 3.10+ 解释器,供所有下游脚本使用;--ppt-master-python 参数可以覆盖自动探测结果,且不能假设一个名字恰好叫 python3 的二进制就是兼容的。
这一约束在 humanize_ppt_v2.py 中落地:探测逻辑通过 sys.version_info >= (3, 10) 校验候选解释器,校验失败则继续尝试下一个;若用户显式传了 --ppt-master-python 且校验不通过,会直接抛出 ValueError("--ppt-master-python must be Python 3.10 or newer")。探测兜底返回 "python3", "unverified"。
2.2 语义所有权:Humanize 冻结故事,PPT Master 冻结视觉
从 write_ppt_master_source 的实现(humanize_ppt_v2.py)可以看到 ppt-master-source.md 的生成逻辑:
- 头部记录 Title、Language、原始素材绝对路径、计划页数;
- "Story authority" 段落明确:Humanize 拥有页序、页数、message 与 speaker intent,除非用户在 PPT Master 的强制确认关卡(confirmation gate)上显式修改;PPT Master 拥有视觉设计、布局、SVG 创作、原生 PowerPoint 对象、转场与导出;
- "Per-slide contract" 按页输出
slide_id、role、message、speaker_intent、非约束性layout_hint、可见内容(visible_content)与媒体需求。
该文件同时被复制一份到 outputs/ppt-master-handoff/ppt-master-source.md,并连带原始素材副本 original-source<ext>。这样 PPT Master 主路线执行 import-sources --move 规则时,不需要移动用户的原始文件。
三、路由表(Routes):三种入口怎么选
契约用一张表定义了 Humanize 输入到 PPT Master 路由的映射,以及各自的闸门(gate):
| Humanize 输入 | PPT Master 路由 | 闸门 |
|---|---|---|
Markdown / 文档 / 文本 + --renderer ppt-master |
主 SVG 管线(Main SVG pipeline) | PPT Master 的三阶段 Strategist 确认 |
--ppt-master-template <raw.pptx> + 内容 |
workflows/template-fill-pptx.md |
填充计划(Fill-plan)页面序列在用户审阅前保持 draft |
--style-gallery --renderer ppt-master |
PPT Master 原生 Confirm UI | 不创建猜测性的 Humanize 封面项目 |
关键规则:raw .pptx 模板永远不会被当作 PPT Master 的 SVG 模板目录处理。创建可复用的 SVG 模板始终是 PPT Master create-template 工作流的事,且必须显式给出最终的目录路径。
对应的 CLI 落地:在 humanize_ppt_v2.py 中,当用户提供 raw .pptx 模板时,primary renderer 被强制为 ppt-master,理由为"用户提供 raw .pptx template,按 PPT Master template-fill-pptx 路由原生填充"。--ppt-master-template <raw.pptx> 也会强制走 template-fill-pptx 路线(见 SPEC.md 的 CLI 说明)。
四、语义映射(Semantic mapping):Humanize 字段 → PPT Master 原生概念
这是桥接契约最核心的实操部分——Humanize 的产物不是直接喂给 PPT Master 的,而是逐字段翻译成 PPT Master 能理解的概念:
slide_plan.json的页序 / 页数 / message →ppt-master-source.md;除非用户在 PPT Master 的确认关卡上修改,否则必须原样保留;speaker_intent.md→ 主路线下写入notes/total.md;模板填充路线下写入fill_plan.json的slides[].notes;gpt-photo→ PPT Master 的Acquire Via: ai图片行(除非资源已存在);screenshot→ 用户 / 网页的事实性资源;绝不合成 UI 证据(never synthesize UI evidence);svg-html/html-table→ 确定性的 SVG 或原生表格 / 图表标记;- Humanize 视频槽位 → 显式的原生动效(native-motion)/ 静态关键帧(static-keyframe)/ 带旁白导出(narrated-export)回退;PPT Master 不承诺任意 MP4 内嵌(
--ppt-master不保证 arbitrary MP4 embedding); --presenter保持原生:内嵌 notes 供给 PowerPoint 的 Presenter View;Humanize 不再附加html-ppt渲染器;--export-adapter委托给 PPT Master 的原生 PPTX 导出与渲染清单(render manifest),而不是产出 Humanize 的 HTML/PDF 打包;- 模板填充路线的特例:原生表格 / 图表与模板幻灯片中已有的对象动画 XML 会被保留;该路线使用
apply --transition,不接受主 SVG 路线的-a或--native-objects参数; - 模板填充 v1 的边界:不能替换图片、不能新增或重排对象动画。这类请求必须:保留模板资源、换布局、变成单独批准的直接 PPTX 任务、或上报为
Needs-Manual。
4.1 媒体映射在源码中的落地
ppt-master-source.md 的 "Media mapping" 段(humanize_ppt_v2.py)逐条写死了这些规则:gpt-photo → Acquire Via: ai;screenshot → 用户/网页事实图,绝不伪造 UI;svg-html / html-table → 确定性 SVG / 原生表格;Remotion/HyperFrames 槽位只是意图记录(intent records),PPT Master 可以用原生 PowerPoint 动效、静态关键帧或带旁白导出路线来表示,且必须上报所选回退方案。
五、输出与体检(Output and checkup)
5.1 输出位置与真理来源
PPT Master 把它的项目导出作为真理来源(source of truth),并在 outputs/ppt-master-rendered/deck.pptx 放一份字节级一致(byte-identical)的副本。随后 Humanize 运行演讲体检:
python3 scripts/humanize_ppt.py \
--qa-from outputs/ppt-master-rendered/deck.pptx \
--out <humanize-run> \
--renderer ppt-master \
--ppt-master-transition fade \
--max-qa-iterations 3
各参数含义(对应 SPEC.md CLI 说明与 local-demo.md):
--qa-from <deck.pptx>:进入演讲体检(presentation checkup)模式,而非 brief 模式;与--source互斥;--out <dir>:必须指向专用运行目录。brief 模式每次会从零重建--out,但只有当它缺失、为空或已是上一次 Humanize 运行(根部存在run_manifest.json/style_gallery_plan.json/outline-preview.md/preview-confirmed.json)时才自动清空,否则会拒绝并要求--force;--renderer ppt-master:明确指定 PPTX 体检渲染器(PPTX QA 要求--renderer ppt-master或auto,humanize_ppt_v2.py);--ppt-master-transition fade:要求导出的 PPTX 带 Fade 原生转场;--max-qa-iterations 3:体检迭代上限(默认即为 3)。3 轮后仍有失败项,状态翻转为needs-human。
5.2 体检读取 OOXML 并验证什么
契约列出体检(checkup)读取 OOXML 后要核验的清单:包完整性(package integrity)、幻灯片数量(slide count)、占位符残留(placeholder residue)、非空可编辑页(non-empty editable slides)、演讲者备注(speaker notes)、AST/备注漂移(AST/notes drift)、关系(relationships)、请求的转场(requested transitions)、请求的原生表格/图表对象(requested native table/chart objects)。视觉碰撞 / 溢出(visual collision/overflow)则留给下游浏览器评审,不属于静态 OOXML 检查范围。
这套清单在 pptx_qa.py 中有完整的纯标准库实现(inspect_pptx,见 pptx_qa.py):
- 包完整性:
zipfile.testzip()CRC 校验;要求[Content_Types].xml与ppt/presentation.xml必须存在;[Content_Types].xml必须可解析且根命名空间正确——若使用带前缀的根命名空间,会触发pptx-package-invalid(该形态会被 LibreOffice 拒绝); - 幻灯片数量:通过
ppt/presentation.xml的sldIdLst与_rels/presentation.xml.rels解析有序幻灯片部件列表(_ordered_slide_parts,pptx_qa.py),与slide_plan.json的页数对比,触发pptx-slide-count-mismatch; - 占位符残留:正则
PLACEHOLDER_RE匹配<a href="https://link.gitcode.com/i/a0d7064b0c148726e6467582ba75a18b" target="_blank">必填...]、lorem ipsum、todo、tbd、SLIDES_HERE([pptx_qa.py); - 非空可编辑页:统计
p:sp(形状)、p:grpSp(组合形状)、p:graphicFrame(表格/图表框)数量,为 0 即判为被扁平化(flattened); - 备注:解析 notesSlide 关系,
_meaningful_note要求去除符号与数字后 ≥4 个有效字符,否则pptx-missing-speaker-notes;备注与speaker_intent语义重叠不足触发pptx-speaker-intent-drift(warn); - 内容漂移:
_semantic_match用去标点紧凑串与词元重叠(≥0.5)双重判据,核对页面文本与对应 AST 页的 title/message/visible_content,触发pptx-ast-content-drift(warn); - 关系完整性:逐条解析 slide 的
.rels,外部目标(External)跳过,其余目标必须存在于包内; - 转场:每页要求存在
p:transition,缺失触发pptx-transition-missing; - 原生对象:
a:graphicData的uri以/chart或/table结尾计为原生对象;当 slide_plan 的media.diagram.kind == "html-table"且要求原生对象而页内为 0 时,触发pptx-native-object-missing。
5.3 11 类 PPTX 专属失败模式
在 humanize_ppt_v2.py 的 FAILURE_MODES 中,scope: ["ppt-master"] 的规则共 11 条,与 renderer_registry.json 中 ppt-master.qa_failure_modes 一一对应:
| check_id | 严重度 | 含义 |
|---|---|---|
pptx-package-invalid |
fail | PPTX 不是可读 OOXML 包,或必需部件缺失 |
pptx-slide-count-mismatch |
fail | 原生 PPTX 页数与 slide_plan.json 不一致 |
pptx-placeholder-residue |
fail | 模板/草稿占位符残留在原生幻灯片文本中 |
pptx-slide-empty |
fail | 某页无任何可编辑可见文本 |
pptx-flattened-slide |
fail | 某页无任何可编辑形状/组/表格/图表对象(被扁平化成图片) |
pptx-missing-speaker-notes |
fail | 计划页缺演讲者备注 |
pptx-speaker-intent-drift |
warn | 原生备注与 Humanize speaker_intent 重叠弱 |
pptx-ast-content-drift |
warn | 原生页文本与对应 AST 页重叠弱 |
pptx-broken-relationship |
fail | 某关系指向缺失或无效的 OOXML 部件 |
pptx-transition-missing |
fail | 请求的原生转场缺失 |
pptx-native-object-missing |
fail | 应作为原生表格/图表的页被扁平化或省略 |
体检每轮产出 qa_report.md(面向人)、fix_prompt.md(面向下游技能的可执行修复指令)与 qa_iteration.json(轮次状态 iterate / pass / needs-human)。对 pptx-flattened-slide,修复提示明确要求"通过 PPT Master 的原生 SVG-to-PPTX 或 template-fill 路线重新生成该页,使其包含可编辑 DrawingML 对象而非扁平页图"(humanize_ppt_v2.py)。
六、从契约到实战:一份完整的工作流
结合 local-demo.md 与桥接契约,完整跑通一条 PPT Master 原生 PPTX 任务的推荐流程为:
- Brief 模式(Humanize 只写简报,不渲染):
python3 scripts/humanize_ppt.py \ --source <raw-material.md> \ --out <dedicated-run-dir> \ --title "演讲标题" \ --renderer ppt-master \ --ppt-master-transition fade - 语义源交付:Humanize 在运行目录写出
ppt-master-production-prompt.md、自包含的ppt-master-source.md与可丢弃的outputs/ppt-master-handoff/副本;下游 agent 从 production prompt 起步,遵循 PPT Master 强制的 Strategist 确认与原生导出流程; - 渲染:PPT Master 完成三阶段确认、顺序 SVG 创作、notes 打包与 DrawingML 导出,将字节级一致副本放到
outputs/ppt-master-rendered/deck.pptx; - 演讲体检(QA):
python3 scripts/humanize_ppt.py \ --qa-from outputs/ppt-master-rendered/deck.pptx \ --out <same-run-dir> \ --renderer ppt-master \ --ppt-master-transition fade \ --max-qa-iterations 3 - 迭代闭环:失败项 →
fix_prompt.md交给 PPT Master 重渲 → 再次--qa-from复检;最多 3 轮,超限翻转为needs-human,交回人类决策。视觉碰撞 / 溢出类问题不进入静态失败规则(遵循"只有代码中真实存在的规则才进目录"的目录纪律,SPEC.md §7),由下游浏览器评审兜底。
若用户提供了原生模板,则将第 1 步追加 --ppt-master-template <raw.pptx>,切换至 template-fill-pptx 路由;该路由只写页面转场,保留模板已有的原生表格/图表与对象动画 XML,且 v1 不支持替换图片或新增/重排对象动画(此类请求按边界规则处理或上报 Needs-Manual)。
七、边界纪律:什么不该做
- Humanize 从不导入 PPT Master 的模板,从不修补导出的 OOXML(adapters/ppt-master-bridge-notes.md 与 SKILL.md 的 v0.6.4 不变量均重申:brief-only、下游 100% 原生、体检最多 3 轮);
- 不要把
--source直接指向旧.ppt/.pptx文件(fail closed):先用scripts/pptx_qa.py的 dump/inspect 提取文本再作为--source传入;渲染好的.pptx一律走--qa-from; - 不要用
--style-gallery --renderer ppt-master期待 Humanize 产出封面 HTML:该组合委托给 PPT Master 原生 Confirm UI,写style_gallery_plan.json的mode: downstream-confirm-ui与commands/style-gallery/ppt-master-confirm-ui.md,不产生伪造封面产物(SPEC.md §6); - 不要假设
python3即 Python 3.10+——契约与代码都要求显式校验(--ppt-master-python可覆盖自动探测)。
参考资料与延伸阅读
- 桥接契约主体:adapters/ppt-master-bridge-notes.md
- 引擎技术规范(CLI 面、数据流、输出契约、风格画廊、体检、媒体模型、渲染器注册表):SPEC.md
- 技能触发文档与 OPC 工作流:SKILL.md
- 渲染器能力快照与验证证据(ppt-master
full,2026-07-10 主/模板填充双路线真实导出记录):registry/renderer_registry.json - OOXML 静态检查实现(
inspect_pptx):scripts/pptx_qa.py - 主引擎实现与
FAILURE_MODES/write_ppt_master_source/ Python 3.10+ 探测:scripts/humanize_ppt_v2.py - 完整 CLI 示例(brief 模式、体检、原生 PPTX、outline preview、legacy 入口):docs/local-demo.md