拆解开源项目 OfficeCLI：PPT 处理器为什么比 Word 难做
本文基于 OfficeCLI 仓库 commit 459b1a4（2026-08-04）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/iOfficeAI/OfficeCLI 最新代码与文档为准。
**如果你打算让 Agent 直接改 .pptx，最该提前知道的一件事是：幻灯片上你看到的那行字，格式很可能一个字节都不在这张幻灯片里。**它散落在版式、母版、主题、演示文稿默认样式这四层之上，而且每一层都可能只写了其中一半属性。Word 和 Excel 也有继承，但没有 PPT 这么深、这么容易让人拿到“空值”就以为“没设置”。
OfficeCLI 是 GitHub 上 iOfficeAI/OfficeCLI 这个开源项目，Apache-2.0 许可证，NOTICE 里写明 Copyright 2026 OfficeCLI，由 goworm 创建维护。它是一个单二进制的命令行工具，不装 Office 也能读写 .docx/.xlsx/.pptx，定位是给 AI Agent 当文档读写手。这里要说清楚两点：它不是“用命令行操作 Office”这类做法的泛称，也和微软没有任何从属或授权关系——文中提到 Word/Excel/PowerPoint 时，指的是文件格式和对应的桌面应用，不是这个项目的归属。仓库 README 把自己定位成“面向 AI Agent 的 Office 套件”，还用了 first and best 这样的说法，那是项目自己的表述，本文不替它背书，只看代码。
本篇只拆 PowerPoint 这一块的代码分工。想看“工具接口该怎么设计给模型用”，去读 Agent 工具设计；想看另一个项目里“节点定义”这种数据建模是怎么落地的，去读 Pascal Editor 的节点定义；想看“结构化输出不稳”这类模型侧问题，去读 结构化输出不稳怎么治。这三篇讲的是 Agent 侧和其它项目，本篇讲的是文档格式侧：为什么同一套 CLI 里，PPT 那部分代码量最大、坑最密。
一、先看体量：三套处理器摆在一起
.pptx 本质上是一个 zip 压缩包，里面按 OOXML（Office Open XML）规范放着一堆 XML 分片，每个分片叫一个 part：演示文稿主干一个 part，每张幻灯片一个 part，每个版式、每个母版、主题各一个 part，图片和视频作为二进制 part 挂在旁边，part 之间靠关系文件（rels）用 rId 串起来。所谓“读写 PPT”，就是在这张关系图上做增删改。
在 src/officecli/Handlers/ 下，三种文档各占一套。我在本地快照里数过（ls *.cs | wc -l，不递归）：Handlers/Word/ 有 54 个 .cs，Handlers/Excel/ 有 47 个，Handlers/Pptx/ 有 64 个；再加上各自目录外那个主文件 WordHandler.cs、ExcelHandler.cs、PowerPointHandler.cs，PPT 这一侧一共 65 个 C# 文件。单看主文件大小也能看出偏斜：PowerPointHandler.cs 约 276 KB，WordHandler.cs 约 135 KB，ExcelHandler.cs 约 25 KB。另外 Handlers/Pptx/EffectTemplates/ 下还躺着 31 个 .xml 动画效果模板。
这些文件全部是同一个类的不同片段。C# 里有个语法叫分部类（partial class）：同一个类可以拆到多个文件里写，编译时合成一个。所以 PowerPointHandler.Add.Slide.cs、PowerPointHandler.Resolve.cs、PowerPointHandler.StyleList.cs 打头都写着 public partial class PowerPointHandler，它们共享 _doc（打开的演示文稿包）这些私有字段，只是按职责切开了。对读代码的人来说这是好事：文件名就是路标。
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 主文件 | 打开/保存包、原始 XML 层、母版与版式的稳定排序 | src/officecli/Handlers/PowerPointHandler.cs | 关心落盘时机、原子写、part 枚举时 |
| 加一页 | 新建 slide part、挂版式、写标题/正文、插入到 sldIdLst | src/officecli/Handlers/Pptx/PowerPointHandler.Add.Slide.cs | 每次 add ... --type slide |
| 路径解析 | 把 /slide[1]/shape[2] 这类路径落到具体 XML 元素 | src/officecli/Handlers/Pptx/PowerPointHandler.Resolve.cs | 定位失败、索引对不上时 |
| 选择器解析 | 解析类 CSS 的选择器语法，判定哪些组合子不支持 | src/officecli/Handlers/Pptx/PowerPointHandler.Selector.cs | 批量按条件改一组形状时 |
| 节点树构建 | 遍历 spTree（幻灯片的形状树，页面上所有元素按声明顺序排在里面）生成结构化节点，供 get/query 输出 | src/officecli/Handlers/Pptx/PowerPointHandler.NodeBuilder.cs | 读回来的 JSON 少东西、顺序不对时 |
| 继承解析 | 走八层样式级联，产出 effective.* 与来源 .src | src/officecli/Handlers/Pptx/PowerPointHandler.StyleList.cs | 想知道“这个字号到底谁定的” |
| HTML 预览 | 把幻灯片渲染成 HTML，含版式/母版继承的形状 | src/officecli/Handlers/Pptx/PowerPointHandler.HtmlPreview.cs | 用 view html / watch 看效果时 |
| 动画与切换 | 时间轴、媒体节点、平滑切换的命名处理 | src/officecli/Handlers/Pptx/PowerPointHandler.Animations.cs | 加过场动画、发现别的幻灯片被改了 |
二、加一页幻灯片：8 KB 代码在防什么
PowerPointHandler.Add.Slide.cs 只有八千多字节，是 Pptx 目录里最小的几个文件之一，但它的每一段几乎都是在挡一种误用。
第一段挡的是父路径。方法一进来就检查 parentPath，只要不是 / 或空字符串，直接抛异常，错误消息写得很直白：幻灯片只能加在 /，因为它挂在演示文稿根上，不挂在别的元素下面。代码注释解释了为什么要这么严：早期版本遇到 /slide[1]、/section[2]、/bogus 这类父路径会静默退回根，结果是路径打错了照样“成功”，只是幻灯片跑到了别处。对 Agent 来说，静默容错比报错危险得多——模型看到成功就继续往下走了。
第二段是挂版式。新 part 建出来后要调 ResolveSlideLayout 找一个 SlideLayoutPart 关联上，注释里写着这是 PowerPoint 要求的。有意思的是这个解析函数放在 PowerPointHandler.Resolve.cs 里，被 Add（新建幻灯片）和 Set（给已有幻灯片换版式）共用，匹配顺序写在文档注释里：先按版式显示名或 MatchingName 精确匹配，再按 OOXML 枚举原文匹配（像 objTx、blank、title、twoObj），再按一批友好别名匹配（titlecontent、twocontent、section、comparison、caption、pictxt、titleonly 等），再按 1 起始的数字下标，最后才是显示名的大小写不敏感子串模糊匹配。全都没中，抛异常并把可选版式列表格式化出来，形如 [1] 名称 (类型)。这个“把可选项列在错误里”的做法值得抄：Agent 拿到这条错误就能自己纠正，不用再发一轮探查请求。
第三段是形状 ID 与占位符（placeholder，版式上预先留好的内容槽位；幻灯片里的形状绑到某个槽位上，就继承它的位置和格式）。新幻灯片的形状树里先放一个 id 为 1 的组，所以后续形状 ID 从 2 开始递增。如果传了 title，就建一个带标题占位符的形状；如果传了 text，注释说明它刻意做成对称的：标题带 <p:ph type="title"/>，正文带 <p:ph type="body" idx="1"/>，两者都绑到版式的槽位上，这样读回来的时候一个报 type=title、一个报 type=placeholder 加 phType=body，而不是一个占位符、一个裸文本框的错配。文本在写进去之前都过 XmlTextValidator.ValidateOrThrow。
剩下的分支处理背景、背景引用（background.ref 取 1001–1004 / 1025–1028，可选配 background.refColor）、切换效果、自动换页时间、点击换页、隐藏、cSld（幻灯片的公共数据容器，形状树就挂在它下面）上的 name。最后一段做插入：新的 slide id 从已有最大值加一算起，一张幻灯片都没有时取 256；如果调用方给了 index 且落在现有范围内，就插到对应位置前面，否则追加到末尾；返回值不是“成功”，而是插入后实际所在的位置 /slide[N]。这个返回值设计很关键，因为插入会让后面所有幻灯片的下标顺移，Agent 必须以返回的路径为准，不能沿用自己以为的编号。
三、定位一个形状：三套索引空间和一次隐蔽的写入
PowerPointHandler.Resolve.cs 是本篇最该细看的文件，它决定了“你说的那个东西”到底是哪个 XML 节点。
先说一个容易翻车的事实：ResolveShape 只在形状树里数 Elements<Shape>()，也就是纯 <p:sp> 元素。表格和图表走 ResolveTable、ResolveChart，它们数的是 GraphicFrame（表格看有没有 a:tbl 后代或匹配的 graphicData URI，图表看有没有图表引用），图片则是另一类元素。**所以 shape[2] 不是“这页上的第二个东西”，而是“这页上第二个纯形状”。**同一张幻灯片上，shape、table、chart、picture、connector、group 各自有独立的编号空间。文件里还有个 DescribeSlideInventory，专门在错误消息里报“3 shape(s), 1 table(s), 2 picture(s)”这样的清单，就是为了让人第一时间看出自己数错了哪一类。
除了位置下标，路径还支持按属性定位。PowerPointHandler.Helpers.Path.cs 里能看到 @id= 和 @name= 两种选择器，例如 /slide[1]/shape[@id=5]；BuildElementPathSegment 在生成路径时会优先用 @id=，只有元素没有 cNvPr id 时才退回位置下标。原因也好理解：位置会因为增删而漂移，OOXML 里的形状 id 不会。占位符还多一套：ResolveLogicalPath 用正则识别 /slide[N]/placeholder[X] 和 /slide[N]/table[M]/... 两种逻辑路径，占位符那一段既接数字，也接类型名。
数字那一段藏着一个已修的坑，注释写得很清楚：数字是“文档序”的第 1 起始序号，不是 OOXML 里 <p:ph idx="..."> 那个 idx 属性。这两者会撞——正文的 idx 是 1，标题根本没有 idx——早先按属性匹配，导致 set /placeholder[1] 打到正文、get /placeholder[1] 却返回标题，同一个路径在读写两端指向不同的东西。这种 bug 在人手操作时很容易被当成偶发，在 Agent 循环里则会稳定地把内容写错位置。
真正需要警惕的是按类型解析占位符时的兜底逻辑。如果幻灯片上找不到该类型的占位符，代码会去版式里找；找到了，就把版式里那个形状克隆一份、清空其中的提示文字、插到幻灯片的形状树里。插入位置也不是随便追加——它按版式里占位符的排列顺序算出一个“名次”，找到已经落地的、名次在它之前的最后一个占位符，插在它后面，没有就插到最前面。注释解释了动机：OOXML 里形状树的顺序就是层叠顺序（z-order），如果直接追加，“先设标题再设正文”和“先设正文再设标题”会得到不同的层叠结果，哪怕最终内容一模一样。
结论是：**一次看起来像“定位”的操作，可能会往你的文件里加一个形状。**这跟 改动边界约定 是同一类问题——你得先知道哪些调用是纯读、哪些带副作用，才谈得上给 Agent 划范围。
同一个文件里还有两处值得注意的错误处理。图表引用的 rId 在关系文件里找不到时（手工改过 zip、或者导入了半截的演示文稿），SDK 只会抛一个不带上下文的越界异常，这里把它接住换成带稳定错误码 broken_chart_relationship 的异常，并把出问题的 rId 写进消息。删图片时则做引用计数：先收集这个图片元素引用的所有 rId（图片本体、视频链接、音频链接、p14 媒体嵌入），再扫同一页其它图片有没有共用，只删没人再引用的那些。少了这一步，删一张图会连带把另一张图的资源删掉。
四、解析继承下来的格式：八层级联和它的来源标注
PowerPointHandler.StyleList.cs 是我认为整套 PPT 代码里最有参考价值的一个文件，它把“这段文字最终是多大、什么字体、什么颜色”这个问题做成了可追溯的。
文件顶部的注释直接列出了级联顺序，从低优先级到高：主题的 majorFont/minorFont/配色方案在最底层，往上是演示文稿的 defaultTextStyle，再往上是母版的 titleStyle/bodyStyle/otherStyle，再往上是母版里匹配同类型占位符的 lvlNpPr，再往上是版式里对应占位符的 lvlNpPr，再往上是形状自己的 lstStyle，最顶上是“直接层”——段落自己的 pPr（含其中的 defRPr）和文本运行自己的 rPr。代码按从低到高的顺序依次覆盖，所以高层自然赢。
解析结果不是一个值，而是一个值加一条来源路径。内部类 ResolvedEffective 里除了 Size、Color、Bold、Italic、Underline、Strike、三个字体槽（latin / ea / cs）、对齐和三种间距之外，还有一个 Sources 字典，每写一次值就同时记下是哪一层写的。来源路径长这样：/master[1]/ph[@type=body][@idx=1]/lvl1pPr、/theme/minorFont、/presentation/defaultTextStyle、/direct。
输出时有两条抑制规则，注释里写明是跟 docx 那一侧对齐的：节点上已经有直接值时不再输出对应的 effective.X；来源是 /direct 时不输出 .src。也就是说，你在读回来的格式里看到 effective.size 和 effective.size.src，就说明这个字号是继承来的，且 .src 告诉你去哪一层改它。这比“给你一个数字”有用得多——Agent 想改字号，是该改这个形状，还是该改版式，答案就在 .src 里。
两个细节值得单独拎出来。一个是字体的主题引用：OOXML 里字体名可以写成 +mj-lt、+mn-ea 这种以加号开头的引用，mj/mn 表示主要字体还是次要字体，后缀表示拉丁/东亚/复杂文种槽位。代码会把它解回主题里的具体字体名，并把来源标成 /theme/majorFont 或 /theme/minorFont，而不是把这个引用字符串原样吐给你、或者干脆跳过。另一个是规格默认值兜底：如果整条级联下来占位符都没有显式字号（空白模板的标题就是这种情况），代码按 ECMA-376 的默认补上——标题 44pt、副标题 32pt、正文 24pt——并把来源标成 /spec-default。这样读回来至少有个数，而不是一个 null 让调用方自己猜。
渲染那一侧走的是另一条路但同一套规矩。PowerPointHandler.HtmlPreview.cs 里的 GetTextDefaults 沿主题字体 → 演示文稿默认样式 → 母版 otherStyle 的链条拼出一组 CSS 默认值；RenderLayoutPlaceholders 负责把幻灯片没覆盖的版式和母版形状也画出来（页脚、页码、日期、logo、装饰图形），并遵守 <p:sld showMasterSp="0"> 这个“不显示母版形状”的开关。这里有条规则写得很好：版式和母版上的占位符一律不贡献文字，因为那里面装的是“单击此处添加标题”这类提示语；唯一例外是日期、页脚、页眉、页码这四个元数据槽。注释还提到过一个真实 issue：版式里一个没写 type 属性的正文占位符，因为 SDK 把“未设置”暴露成 HasValue == false，绕过了按类型判断的逻辑，结果提示文字漏到了幻灯片上。
五、边界与代价：它明确不管的那部分
这套设计不是免费的，几个取舍在代码里都看得见。
**它不是排版引擎，不做换行与溢出计算。**HTML 预览是“用浏览器的排版能力尽量还原”，不是复刻 PowerPoint 的排版算法。同一段文字在预览里是两行、在 PowerPoint 里是三行，这种差异不属于它承诺解决的范围。真正要确认版面，仍然得看渲染出来的图或在 PowerPoint 里打开。
**结构化读回是有损的。**主文件里 EnumeratePartUris 那段注释直说，批量导出时会扫描 part 列表，对不能完整往返的 part 发警告，点名的包括 tableStyles、viewProps、handoutMasters、printerSettings、customXml、嵌入字体、tags、用户自定义文档属性。NodeBuilder 里对特效列表也维护了一份“能压成字符串的子元素”白名单（外阴影、内阴影、发光、填充叠加、倒影、柔化边缘、模糊），名单之外的一律回退成原始 XML 直通。这套做法的含义是：**它优先保证“不弄丢”，其次才保证“能用结构化方式描述”。**你拿到的结构化视图不等于文件的全部。
**幻灯片只能加在根上，形状索引按类型分空间。**这两条前面说过，属于刻意的严格。好处是路径含义唯一、错误早报；代价是路径不能像自然语言那样随手写，Agent 侧必须严格用返回值里的路径。
平滑切换（morph，PowerPoint 里靠同名形状在两页之间做补间的过场效果）会改上一页。AutoPrefixMorphNames 的逻辑是：给当前页和上一页所有具名形状的名字前面加 !! 前缀，好让 morph 即使在文字内容变了的情况下也能配对；已经有前缀的跳过，TextBox N、Content N 这类自动生成的默认名也跳过；处理完两页都保存。这意味着“我只是给第 3 页加了个切换效果”，第 2 页的形状名也变了。批量脚本里如果有别的步骤按名字找形状，就会突然找不到。
远程资源是可以拉的，但有护栏。picture=（走 Core/ImageSource.cs）和表格 data=、model3d=、media=（走 Core/FileSource.cs）都能接 URL。Core/SsrfGuard.cs 给所有远程抓取统一加了 SSRF 防护（SSRF 即服务端请求伪造：外部传进来的 URL 诱使执行方去访问它本不该碰的内网地址）：在连接回调里校验实际要连的 IP，非公网地址（回环、私网、链路本地、云厂商元数据端点）一律拒绝，重定向保持开启但每一跳都校验，最多 10 跳。注释写明了动机——URL 可能来自不可信输入，包括文档里嵌的指令。这条护栏挡的是网络层，挡不住“公网上一张恶意图片被写进你的交付文件”，所以 URL 白名单还是得在你自己这一层做，思路可参考 提示注入防御。
六、上手与避坑清单
别拿“上一次看到的编号”当路径。 插入幻灯片会让后面所有下标顺移，AddSlide 之所以返回 /slide[N] 而不是布尔值，就是这个原因。避法：每次改完都以返回值为准，需要长期稳定引用某个形状时改用 @id= 形式，因为 BuildElementPathSegment 生成路径时本来就优先给你 id 形式。
别把 shape[N] 当“第 N 个元素”。 解析器只在纯形状里数，表格、图表、图片、连接线、组各有各的编号。避法：先用 get 或 query 把这一页的节点树拿回来，照它给出的 path 用；解析失败时错误里那句“3 shape(s), 1 table(s)”就是在提示你数错了类别。
别把“读占位符”当成只读操作。 按类型解析占位符时，幻灯片上没有就会从版式克隆一个进来，还会按版式顺序决定插入位置。避法：如果只想探查有没有这个槽位，用返回节点树的读接口看；确实要写内容再走占位符路径。涉及原文件的操作，先复制一份再动。
别忽略 effective.* 和 .src 的区别。 直接值和继承值在输出里是两组键，直接值存在时继承值会被抑制。避法：判断“用户是不是显式设过字号”，看有没有 size；判断“最终显示成多大”，看 effective.size；决定“该去哪一层改”，看 effective.size.src——它会明确告诉你是 /theme/minorFont 还是 /master[1]/bodyStyle/lvl1pPr，甚至可能是 /spec-default（意味着谁都没设，是按规范补的）。
别在常驻模式下让别的程序直接读文件。 可编辑会话是在内存副本上改的，保存走临时文件加 File.Replace 的原子替换，所以原文件不会被就地重写、写一半崩掉也不会留下截断的文件；但 README 明确写了，常驻会话会延后落盘，空闲后自适应 2–10 秒才自动刷。避法：在非本工具的程序（python-docx、openpyxl、PowerPoint、渲染器、上传流程）读文件之前，显式执行 officecli save 刷盘保留常驻，或 officecli close 刷盘并释放；每条命令都要求落盘的流水线，用环境变量 OFFICECLI_RESIDENT_FLUSH=each。
别假设批量操作失败会自动回到起点。 主文件里有 DiscardOnDispose 这个开关，作用是原子批处理回滚：不序列化被污染的内存 DOM，先关掉后端流，磁盘上保留最后一次刷盘的状态。也就是说“最后一次刷盘之后”的改动会一起丢，“最后一次刷盘之前”已经落盘的改动仍在。避法：批量改之前先留副本，并明确记录你的刷盘点在哪。
别把 watch 当成安全的只读预览。 它会在本机起一个 HTTP 服务（README 里给的地址是 http://localhost:26315 ），每次 add/set/remove 都刷新浏览器。这是个真实的监听端口，在共享机器或容器里要当成暴露面看待。
收尾：一条自检清单
读完这些，如果你要接入这个项目，可以按这个顺序自检：路径是不是都来自返回值而不是自己拼的？改的是原文件还是副本？下游程序读文件之前有没有显式刷盘？涉及远程 URL 的参数有没有在你这一层再过一遍白名单？加了平滑切换之后，有没有确认上一页的形状名变化不影响后续步骤？
接着该读哪个文件，取决于你卡在哪一层：路径对不上就看 src/officecli/Handlers/Pptx/PowerPointHandler.Resolve.cs 和 PowerPointHandler.Helpers.Path.cs；读回来的 JSON 缺东西或顺序不对，看 PowerPointHandler.NodeBuilder.cs 里那段按形状树声明顺序单趟遍历的注释；格式说不清是谁定的，看 PowerPointHandler.StyleList.cs 顶部注释里那份八层级联清单；想知道某个属性键叫什么，去 schemas/help/pptx/ 翻，那里有 34 份 json，shape.json、slide.json、placeholder.json、transition.json 都在。这些文件都在公开仓库里，随时可以自己核一遍——本文所有描述也都应该按这个标准去验证。
本篇属于一个把开源Office 文档读写套件 OfficeCLI逐层拆开讲的系列，整体地图见 OfficeCLI 是什么：给 AI Agent 用的开源文档读写套件；沿着这条线往下，还可以看 开源项目 OfficeCLI 的图表体系：两条线、七套预设与一个渲染器 和 拆解开源项目 OfficeCLI：让 Agent 做出不土的 PPT 动画与平滑切换。