open-design 中 PPT Master 原生 PPTX 渲染桥接契约:Humanize 与可编辑 PowerPoint 的边界、语义映射与 OOXML 体检

原创2026-10-10 02:07:391,837 阅读
文章标签:AI 应用AI Agent人工智能AI 技能MCP 服务Agent 编排媒体生成设计系统桌面应用前端后端插件系统dsh-plugin

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 任务的推荐流程为:

  1. Brief 模式(Humanize 只写简报,不渲染):
    python3 scripts/humanize_ppt.py \
      --source <raw-material.md> \
      --out <dedicated-run-dir> \
      --title "演讲标题" \
      --renderer ppt-master \
      --ppt-master-transition fade
    
  2. 语义源交付:Humanize 在运行目录写出 ppt-master-production-prompt.md、自包含的 ppt-master-source.md 与可丢弃的 outputs/ppt-master-handoff/ 副本;下游 agent 从 production prompt 起步,遵循 PPT Master 强制的 Strategist 确认与原生导出流程;
  3. 渲染:PPT Master 完成三阶段确认、顺序 SVG 创作、notes 打包与 DrawingML 导出,将字节级一致副本放到 outputs/ppt-master-rendered/deck.pptx;
  4. 演讲体检(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
    
  5. 迭代闭环:失败项 → 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 可覆盖自动探测)。

参考资料与延伸阅读

登录后查看全文
open-design