design-export-repair

修复设计导出问题

修复 AI 生成的演示文稿／PDF 导出问题（针对 Claude Design 的导出流程构建，但检查的是通用 OOXML/PDF 规范问题，并非 Claude 特有问题）：这些导出内容在应用中看起来正常，导出后却会出问题——文本末尾的几个字符丢失、字体与原始设计不符，或者 .pptx 文件虽然能在 PowerPoint 中正常打开，却会让某些转换器报错。

针对一个真实的损坏导出文件，已发现并修复了四类缺陷；references/defect-classes.md 详细介绍了每类缺陷，包括如何确认问题，以及修复方案的取舍。在将这项技能扩展到尚未涵盖的情况之前，请先浏览该文档——尤其是其中的缺陷 #4，它很好地说明了为什么“形状几何看起来正确”并不等同于“渲染后的 PDF 看起来正确”。在认定新问题是几何问题之前，值得先读一读。

端到端：从 Claude Design 到干净的文件

这篇内容是写给运行 Claude Code 的人看的，不只是给 Claude 看的——先快速浏览一遍，了解实际要做什么。Design 项目进入 Claude Code 有两种不同的方式，它们的运行方式也不同。

**路径 A — 普通导出（适用于“我的演示文稿／PDF 看起来坏掉了”这种情况）：**在 Claude Design 中，使用 Export 并选择 PDF、PPTX 或 HTML。保存文件，然后将它交给你正在使用的 Claude Code——如果你的设置允许，可以在聊天中附加文件；或者将文件保存到磁盘，并把路径提供给 Claude。然后告诉 Claude 使用此技能：像“我导出成 PDF 后这份演示文稿看起来坏掉了，你能修复吗”这样的日常说法就足够了（此技能的描述就是按照这种说法编写的）；如果想说得更明确，也可以直接指定技能名（design-export-repair）。

**路径 B — “Send to Claude Code”按钮。**这是一个与普通导出相关、但并不相同的功能——它面向的是在代码中继续进行设计／原型开发，而不是修复导出的演示文稿；不过你可能还是会用到它。它提供两个选项，运行方式也不同：

• “Send to Claude Code Web” 会打开一个全新的 claude.ai/code 会话，设计包已经放在该会话的工作目录中——无需保存或附加文件，文件已经在那里了。在这个新会话中，告诉 Claude 检查工作目录中的内容，并对其使用此技能。
• “Send to local coding agent” 会提供一段提示词，让你粘贴到本地终端中的 Claude Code。请注意：截至本文撰写时，这段默认提示词依赖一个本地 Claude Code 未附带的“Claude Design connector”，而且经常会悄无声息地失败（详情请参阅 anthropics/claude-code#69246）。同一对话框中还有一个 “Download zip instead” 选项——这个选项确实有效：它会下载一个包含设计文件的实际 zip 文件。保存该 zip，将它提供给本地 Claude Code（或者先将其解压到项目文件夹中），然后告诉 Claude 对其使用此技能。

无论采用哪种路径，scripts/fix_export.py 都接受单个文件、zip 文件或整个目录——unpack.py 会判断它收到的内容，而不要求输入采用某种特定格式。关于路径 B，有一点值得了解：它的包格式是 Design 专用的 *.dc.html 画布文件，与此技能修复流程实际针对并验证过的 .pptx 完全不同（请参阅 references/defect-classes.md）——.dc.html 包会经由尽力处理的 HTML 路径（convert_html.py），而不是经过全面测试的路径。如果你要修复的是损坏的演示文稿／PDF 导出文件，应该选择路径 A。

完成任一路径后，Claude 会运行 scripts/fix_export.py，并交付修复后的 .pptx（路径 A）或 PDF，以及一份报告，准确说明问题所在和具体修改内容。如果你想继续在 PowerPoint／Keynote／Google Slides 中编辑，请打开修复后的 .pptx；如果 PDF 就是你需要的交付物，也可以直接使用 .pdf。

坦诚说明一点：Claude 产品中的按钮和流程会随时间变化；这里对路径 B 的描述是根据 Claude Code 自己的公开问题跟踪记录编写的，而不是基于对这项具体交接流程的亲自测试。如果你看到的情况与这里不符，不必纠结——通过任何可行的方式把实际设计文件交给 Claude Code，然后告诉 Claude 使用此技能即可；unpack.py 的设计目的就是判断它收到的内容。

修复内容速览

#	缺陷	症状	修复方法
1	[Content_Types].xml 声明了 zip 中不存在的部件	某些转换器会失败、丢弃幻灯片或输出乱码；PowerPoint 可能会悄悄“修复”文件并将其隐藏	通过 python-pptx 加载并重新保存（根据实际存在的内容重建清单）
2	形状的边界框超出幻灯片边缘	将幻灯片视为严格视口的渲染器可能会将其裁切	将形状移回边界内（如果形状本身比幻灯片还大，则缩小形状并重新缩放表格网格）
3	使用了自定义 Web 字体（实际发现有 Inter、Plus Jakarta Sans、JetBrains Mono），但未嵌入	不含这些字体的渲染器会替换成其他字体，导致外观错误、文字尺寸不同	转换前，在渲染器能找到的位置安装匹配的内置或获取的字体文件
4	LibreOffice 会裁掉任何带有字距的文本运行末尾（a:rPr spc）	字距拉开的标签、小标题、徽章会丢失末尾 1-4 个字符——即使同时存在缺陷 #2，这通常也是“文本被截断”的真正原因	仅通过 LibreOffice 渲染字距已中和的副本；返回的 .pptx 会保留原始字距，便于编辑

运行方法

所有操作都由一个脚本完成：

python3 scripts/fix_export.py <input> --out-dir <where to write results>

<input> 可以是：

• 直接传入的 .pptx（实际上 Claude Design 导出的文件就是这种格式——不要假定它必须打包在 zip 中）
• .zip——会先解压并搜索 .pptx，然后搜索 HTML/CSS/JS 资源包（index.html + 资源文件），最后搜索独立的 .pdf
• 独立的 .pdf——没有源文件时，修复能力有限；见下文

如果输入有任何不寻常之处，运行前请阅读脚本自身的文档字符串，了解完整的处理流程——文档字符串会与代码的实际行为保持同步。

运行后，请查看 <out-dir>/repair_report.md。报告会按顺序记录：包结构存在的问题、每个被重新定位或调整大小的形状（幻灯片、调整前后的坐标）、演示文稿中所用每种字体的状态（已安装 / 已获取 / 使用替代字体）、字距变通方法是否已应用，以及对最终 PDF 的验证结果（页数与幻灯片数量的对比、可能意外空白的页面、仍与页面边缘接触的文字）。请将报告内容告知用户——报告的设计目的就是供人查看，而不只是写入日志，因为这项技能的核心原则是“绝不悄悄更改”。

输出会保存在 <out-dir> 中：

• *.repaired.pptx——仍可完整编辑，结构干净，没有超出画布的形状，保留原始字距
• *.repaired.pdf——干净的 PDF，由字距已中和的渲染副本转换而来（见缺陷 #4），避免字距拉开的标签被裁切
• repair_report.md / repair_report.json

输入为没有源文件的独立 PDF 时

结构修复（包结构、形状几何、字体替换）需要可编辑的源文件——如果文件已经扁平化为固定矢量路径和栅格化文字，就无法移动形状或修复字体引用。fix_export.py 仍会执行同样的 PDF 验证流程（页数合理性检查、空白页检查、边缘溢出检查），让你至少能如实判断 PDF 本身看起来是否有问题；但请明确告知用户实际并未进行修复，而不要暗示修复已经完成：询问他们能否从 Design 重新导出为 .pptx/zip，因为只有这样才有实际修复的空间。

输入是 HTML/CSS/JS 打包文件时

这条路径（scripts/convert_html.py）只能尽力而为，不像 .pptx 路径那样基于真实缺陷调查——我们没有这类输入样本可供测试。它会应用最常见的通用修复，以避免 HTML 演示文稿在打印为 PDF 时出错（强制打印背景和颜色、取消隐藏依赖 overflow: hidden 和滚动的内容、避免在元素中间分页），并根据标记中的提示选择页面尺寸。如果遇到真实的 HTML 导出故障，请将其视为起点，并阅读 references/defect-classes.md 末尾关于如何诊断新问题的部分（渲染、比较、隔离，不要只凭标记猜测），而不是假定现有通用修复能够解决所有问题。

扩展此技能

如果演示文稿出现上表中未列出的缺陷，那么找到缺陷 #4 的方法也适用于此类情况：不要只根据 XML/CSS 调试，因为“结构看起来正常”和“渲染效果正常”是两回事，而用户报告的只有第二种情况。将未经修改的原始文件渲染为 PDF，再渲染一份只做了一项特定、独立修改的副本，并比较两者——几何和字体修复未能解决可见裁切问题后，正是通过这种方法确认了字母间距错误。scripts/validate_pdf.py 已经会检查页数、空白页和边缘溢出；如果发现其他值得在每次运行时自动检查的简单客观信号，也可以将其加入其中。