SlidePatch 是做什么的?
使用本技能所需的脚本。相对于此文件解析它们的路径,无论宿主代理的工作目录在哪里。宿主需要本地命令执行和图像查看能力;本技能没有 DSH 特定的 API 或模型 API 密钥。
对于新安装,请运行 python <skill>/scripts/slidepatch.py doctor(添加 --charts 用于图表迁移或 --equations 用于公式转换)。此命令会检查依赖项和 Office 注册状态,但不会打开任何应用程序。就绪结果不能替代原生验证。
原生方程转换
对于将独立公式文本、图片或 MathType/OLE 方程转换为原生 PowerPoint 方程的请求,请使用 inspect-equations 和 convert-equations。阅读 references/equations.md 以了解计划、转录和验证协议。此模式除需要 Windows/PowerPoint 外,还需要 Pandoc;其他模式不需要 Pandoc。它会保留演示文稿的布局、页数和未指定的对象,不使用模板,也不会重新转换现有的原生方程。显式的整个对象 LaTeX 会产生候选;Agent 会审核并转录图片和缓存的 OLE 预览,而不会激活 OLE 或解析 MathType 二进制数据。将不明确的对象保持原样并报告。模板迁移目前拒绝原生方程以防止数学结构丢失;不要将转换视为自动支持迁移结果方程。
整个演示文稿迁移与分页
对于迁移整个演示文稿或允许分页的请求,请优先使用 migrate。阅读 references/batch.md 以了解覆盖范围和证据格式。
python <skill>/scripts/slidepatch.py migrate <source.pptx> --template <template.pptx> --output <new-output.pptx> --evidence <fresh-evidence-directory>
引擎会按顺序访问每个源幻灯片。它会识别封面、目录、编号章节和常规内容页面;优先匹配模板页面类型;并复用原生模板背景、图形和布局。当没有专门目录模板时,目录页面可以使用内容页面样式。在 plan.json 中检查分类和回退;这是基于几何/字体的推断,而非无限制的图像理解。
保留模板字体族、大小、粗细和颜色。原生文本测量决定容量。尽可能将完整的组保持在一起;在多个等长的整组分页中平衡文本量。如果单个组过大,则在正文对象、段落或句子边界处拆分,并精确保留字符切片。过大的组延续页面将内容对齐到顶部。标题、组标题和页脚作为显式上下文重复;正文切片必须精确重建源文本一次且按顺序。永不重写源编号或默默重新编号目录。任何不能在不改变模板排版的前提下容纳的句子都会导致整个操作失败。
此模式支持普通可编辑文本、受支持的源文本占位符以及结构清晰的嵌入式图片/原生图表。源占位符的限制见 references/plan.md。对于媒体页面,请阅读 references/media.md:图像及其裁剪保持原生,图表保留嵌入式工作簿,关联标题在布局和分页期间与其资产保持在一起。媒体页面使用内容模板。非文本装饰、不支持的占位符、组、动画、外部链接和模糊结构仍然不受支持。任何页面上的失败都会阻止整个输出的发布;绝不交付不完整的演示文稿。每个生成的页面都会被重新打开、渲染,并根据其模板字体/背景进行检查,并在单独的证明副本中进行实际编辑和保存。仅在所有页面、文本和媒体检查通过后,输出才会发布。
审查每个 after-N.png,尤其关注封面/章节标题、目录页面回退和分页边界。在 report.json 中阅读每页检查和可编辑性页面列表。交付经过验证的 PPTX、预览以及简要的源到输出页面摘要。当页面被拆分时,说明重复的上下文是故意的。原始文件保持不变。
同文件模式 (plan v1)
- 输入是现有的
.pptx;源幻灯片和参考幻灯片是该文件中的不同幻灯片,具有相同的设计和布局,并且隐藏了母版图形。 - 源:普通形状、线条和水平文本框。参考:这些内容加上装饰性图片。两个选定的幻灯片上均不能有组、占位符、图表、SmartArt、动画、过渡、超链接或旋转对象。
- 每个源文本对象恰好映射到一个参考文本对象,反之亦然。源的 non-text 形状必须被明确识别为要替换的装饰。如果某个对象可能包含有意义的视觉证据,请停止并要求澄清。
- 该操作会用参考对象的原生副本替换源幻灯片的本地对象,并使用确切的源字符串填充它们。它会采用参考排版,包括对强调格式的更改;但不保证保留源的字符格式。
- 不支持内容摘要、页面拆分、自动缩小字体或图片到可编辑文本的重建。如果选定的幻灯片不符合这些限制,请解释具体的限制,而不是通过不相关的工具重建演示文稿。
分离模板模式 (plan v2)
对于源幻灯片和模板位于不同 PPTX 文件中的情况,请使用 apply-template。此模式会生成一张新的幻灯片,其尺寸与模板相同;它不会重写源演示文稿,也不会包含其他模板幻灯片。当用户需要保留源演示文稿的其他幻灯片时,请选择 v1。
检查两个文件,包括现在列在 inheritance 下的继承布局/母版图形。查看实际的预览,并选择一个内容页面,而不是假定幻灯片 2 是合适的模板。保留品牌元素和装饰。明确分类每个本地模板对象是保留的装饰还是移除的示例内容;不要保留无关的模板照片作为源内容的证据。
为每个源文本对象创建一个放置项。每个放置项命名一个普通的文本承载模板形状作为样式提供者,并给出以磅为单位的边界。同一个提供者可以服务于多个放置项,因此源和模板的文本数量可能不同。引擎会在模板内部复制原生对象,保留其布局/母版和主题。文本直接来自源;计划中不包含替换字符串。字体缩小和内容重写仍然不支持。
源的限制与 v1 相同,但 v2 也接受受支持的源文本占位符。空的、安全的文本槽位会被明确记录为已丢弃;活动的继承源文本会导致拒绝,而不是被默默忽略。样式提供者必须是普通的、未旋转的水平文本形状,而不是占位符/组。模板布局/母版装饰保持原生,包括继承的图片和未使用的布局占位符。保留的本地装饰必须没有文本。计划记录哪些对象被移除;自动规划可以提出这些决策,而 Agent 审核其含义。
自动布局(分离模板的首选)
对于具有清晰标题和正文(包括受支持的源文本占位符)的纯文本源,首先运行:
python <skill>/scripts/slidepatch.py plan-template <source.pptx> --template <template.pptx> --source-slide 1 --out <fresh-planning-directory>
这会生成一个正常的 v2 plan.json,无需手动提供目标页面、形状 ID 或坐标。selection.json 记录了推断的源角色、候选模板页面、基于几何的装饰决策、候选布局、适配度量和拒绝原因。状态 planned 意味着计划存在,并不代表 PPTX 已通过最终验证。
规划器使用字体层次结构和空间邻近度来关联标题和正文;它不使用形状名称或模板页码。它需要一个明显的顶部标题,识别短字体底部页脚,并支持分组行/列或无标题段落。它搜索行式、堆叠式、双列和三列布局,使用 PowerPoint 的原生文本边界和原始模板字体大小。文本自动换行;没有字符串重写或字体缩小。候选框不能相互重叠或与保留的装饰重叠。全页背景和未使用的布局占位符从障碍物检查中排除。
阅读 selection.json,查看 source.png 和选定的 template-N.png,并检查角色关联和示例图片移除是否合理。自动图片分类使用几何和附近的标题,而不是图像理解。不要声称通用的语义匹配。对于明确的结果,直接使用生成的计划进行 apply-template,然后检查渲染输出。用户无需提供坐标或批准其请求中已涵盖的常规选择。
如果单页规划拒绝了模糊的角色、不确定的装饰、不支持的对象或超容量的内容,请阅读记录的原因。当授权分页时,请使用 migrate。否则,在使用经过审核的显式 v2 计划之前,先检查实际对象。切勿偷偷省略内容、缩小字体或更改授权的页面范围。包含图片、非文本装饰、混合/不清晰的层次结构、图表或组的源仍然需要显式或不受支持的内容工作流程。
运行
将 requirements.txt 安装到 Python 3.10+ 虚拟环境中。对每个命令都要使用该解释器。桌面版 PowerPoint 必须在已登录的 Windows 会话中可用。首先检查:
python <skill>/scripts/slidepatch.py inspect <source.pptx> --out <fresh-inspection-directory>
阅读 inventory.json 并查看相关的 slide-N.png 预览。使用实际对象和外观匹配内容角色。切勿根据形状的顺序推断其 ID,或从内存中重建受保护的文本。
对于同文件模式,使用 references/plan.md 中的模式创建一个 JSON 计划。对于分离模板,优先使用 plan-template;当自动推断不合适时,使用人工审核过的 v2 计划。从当前清单中复制哈希和 ID。保留用户预期的范围。明确的授权请求和明确的映射可以直接进行;只有当无法从文件解决实质性的内容歧义时才提问。
python <skill>/scripts/slidepatch.py apply <source.pptx> --plan <plan.json> --output <new-output.pptx> --evidence <fresh-evidence-directory>
对于分离模板,也要检查它,然后使用 v2 计划:
python <skill>/scripts/slidepatch.py inspect <template.pptx> --out <fresh-template-inspection>
python <skill>/scripts/slidepatch.py apply-template <source.pptx> --template <template.pptx> --plan <v2-plan.json> --output <new-output.pptx> --evidence <fresh-evidence-directory>
引擎会暂存编辑后的演示文稿,在 PowerPoint 中重新打开并渲染它,比较精确的文本对象和数字,检查非目标幻灯片,并在一个单独的证明副本上测试真实的文本编辑和形状移动。只有通过这些检查后,它才会发布输出。它从不调用 PowerPoint Quit 或关闭不相关的演示文稿。原生复制/粘贴使用系统剪贴板。
模板模式则检查单张幻灯片结果、两个原始哈希值、所有本地源字符串、保存的原生对象以及前后相同的渲染装饰层。允许现有的装饰性渗透;新内容必须合适。它使用原生 Duplicate,不依赖剪贴板。PPTX 可能仍包含未使用的模板布局、母版或媒体;此原型不会清理隐藏的包内资产。
审查并交付
阅读 report.json;退出状态和报告都必须指示成功。查看 before-<source>.png、before-<reference>.png 和 after-<source>.png。检查样式是否匹配,没有裁剪、意外重叠或不正确的阅读顺序。几何检查不能替代视觉审查。
对于模板模式,查看 source-before.png、template-before.png、after-1.png,以及 template-shell.png 和 output-shell.png。对照模板的视觉语言检查新的合成;仅匹配文本字符串是不够的。
交付新的 PPTX 以及预览和一份包含检查和范围的简明摘要。editability-proof.pptx 故意包含编辑标记,是证据而非最终交付物。如果任何检查失败,请报告问题;切勿将暂存或证明文件作为最终演示文稿交付。重试时选择新的路径,并保留失败证据。