2.5 office-export-pdf 与 office-render：交付与视觉把关

两个技能，一个共同主题：让成果可验证

office-docx / office-xlsx / office-pptx 负责“做出来”，这一节的两个技能负责“确认做对了”。一个管最终交付格式，一个管排版效果，合起来覆盖交付前的最后两关。

技能 官方描述 解决的问题
office-export-pdf 用 LibreOffice 把 Office 文档转成指定 PDF 交付格式固化，跨设备一致
office-render 渲染请求的文档图片，或检查视觉布局 排版到底好不好看，眼见为实

office-export-pdf

转换走的是 LibreOffice，不是虚拟打印。这个区别很实际：

维度 LibreOffice 转换 虚拟打印
文字层 保留可选可搜 变成图像
书签 / 目录 可保留 丢失
跨平台一致性 依赖 LibreOffice 版本 依赖打印机驱动

文字层这一条决定了 PDF 能不能被检索、被复制、被后续工具处理；书签决定了长文档的导航体验。虚拟打印出来的 PDF 本质上是一叠图片，这两样全丢。

前置条件：运行环境里必须已安装 LibreOffice。 这个技能调用的是已安装的 Kit CLI，不会替你准备引擎。如果转换失败，排查顺序是先确认 LibreOffice 装没装、路径通不通，再怀疑技能本身。同一份配置里 cli 字段就是干这个用的：设为 false 可以直接禁用操作执行。

典型任务：

用 office-export-pdf 技能把 report.docx 转成 PDF，
要求保留标题书签，纸张 A4，转完报告页数。

“转完报告页数”这句值得保留：转换是批处理动作，页数是判断有没有丢内容的最快信号。

office-render

这个技能的定位是“视觉检查器”：把文档渲染成图片，让人（或模型）直接看排版结果。结构校验能告诉你 XML 合不合规，渲染才能告诉你标题是不是压住了图表。

官方为它写了一条容易忽视的规则，值得完整理解：

用户要求的外观修改，包括电子表格单元格填充和文本对齐，即使没有明确要求视觉检查，也需要渲染；用户明确要求跳过渲染时以该要求为准。

翻译成实操语言：

场景 要不要渲染
改了一段文字 不必
改了单元格填充色 要
调了文本对齐 要
换了模板母版 要
用户明说“不用看效果” 不必

这条规则的要点是默认值反直觉：外观改动的默认动作是渲染，不需要你提醒。两个细节值得注意。第一，它明确点名了电子表格的单元格填充和文本对齐——最容易被当成“不算视觉问题”的改动，恰恰在覆盖范围内。填充色错一行、对齐差一列，打印出来就是明面上的事故。第二，唯一例外是用户明确要求跳过，此时以该要求为准；除此之外没有第二个出口。

渲染出来的图有两个用途：给你看，也给模型看。后者更重要——让它描述看到的问题，才能形成“改 → 看 → 再改”的闭环。

典型任务：

用 office-render 技能渲染 deck.pptx 的第 1、6、8 页，
检查有没有文字溢出或遮挡，只报告问题不要改。

“只报告问题不要改”是把检查和修复拆成两轮：先让问题全部暴露，再决定修哪些。

渲染检查清单

让模型看图之前，先给它一张检查清单，它才不会只说“看起来没问题”：

检查项 典型问题
文字溢出 文本框装不下，最后一个字被切掉
元素遮挡 标题压住图表、页脚压住正文
图片缺失 只剩一个占位框或空白
对齐混乱 同级元素左边缘对不齐
页码页眉 漏页、错页、页码从第二页才出现

两者如何串起来

一个完整的交付流水线通常长这样：

office（路由）
  └─ office-docx / office-xlsx / office-pptx   创作与编辑
        └─ office-render                       视觉检查，发现问题回去改
              └─ office-export-pdf             定稿输出 PDF
                    └─ office-recalculate      仅表格：确认公式结果正确

流水线里有两个分叉要点：

文档类型 走哪条
Word / PPT 创作 → 渲染检查 → 导出 PDF
Excel 创作 → 重算公式 → 渲染检查 → 导出 PDF

表格比文档多一步 office-recalculate，因为公式缓存不过一遍，导出的 PDF 里可能是旧数字——这个错误会直接印在交付物上，连“回去改”的机会都没有。

还有个顺序细节：渲染检查放在导出之前。PDF 是定稿格式，导出后再发现排版问题，要么重导，要么改源文件再来一遍。

失败排查

现象 先查什么
转换直接失败 环境里有没有装 LibreOffice，CLI 路径通不通
PDF 里文字选不中 是不是走了虚拟打印而不是 LibreOffice 转换
PDF 没有书签 源文档标题有没有用真正的 Heading 样式
渲染出来是空白页 指定的页码是否存在，文件是不是损坏
渲染图和文档对不上 渲染的是缓存中的旧版，先重存再渲染

什么时候不需要这两个技能

只给自己看的中间稿、还要大改的草稿，不必走渲染和导出。这两个技能是交付前的动作，改稿阶段每跑一次都是浪费。等结构定稿、内容冻结，再一次性渲染检查、导出 PDF。

实践建议

建议一：PDF 是交付动作，不是中间动作。 中间过程保留源格式，最后一次转 PDF，否则后续每次小改都要重转，而每次转换都依赖 LibreOffice 环境状态。

建议二：渲染要指定页码。 让模型渲染全部页面既慢又贵，挑关键页：封面、数据页、结尾页。

建议三：渲染结果要给模型看。 如果只是渲染出来给你自己看，模型学不到任何反馈；让它描述看到的问题，才能形成闭环。

建议四：导出前确认 LibreOffice 可用。 转换失败先查环境，再查技能。

建议五：表格交付把重算放在导出前。 顺序反了，旧值就固化在 PDF 了。

建议六：源格式和 PDF 各留一份。 PDF 给对方看，源文件留着自己改，两者都别删。

小结

  • office-export-pdf 走 LibreOffice 转换，保留文字层，需要环境已装 LibreOffice。
  • office-render 负责视觉把关，外观类改动默认必须渲染，除非用户明确要求跳过。
  • 交付流水线：创作 → 渲染检查 → 导出 PDF →（表格）重算公式。
  • 渲染要指定页码，渲染结果要让模型看，才能形成闭环。

延伸阅读