使用 ZCode 改造 PPT 模板：实践复盘与能力边界
本文复盘一次真实的「用 ZCode（AI 编码助手）改造 PowerPoint/WPS 演示模板」任务，总结得失、注意事项，以及当前 ZCode 在此类任务上的能力边界。
适用场景：把一份已有的 .pptx 改造成可复用模板（.potx / .dpt），涉及删除 OLE 对象、统一母版样式、把页面布局提升为版式（slideLayout）、并导出两种模板格式。
写作日期：2026-08
一、任务概览
输入：一份包含 4 张幻灯片的 模板.pptx（封面、目录、内容、致谢），内嵌 think-cell 插件的隐藏 OLE 元数据对象。
目标：把 4 页全部提升为母版里的 4 个可复用版式（slideLayout），文字转为占位符提示语，并输出 .potx（PowerPoint 模板）和 .dpt（WPS 演示模板）两种格式。
二、ZCode 做得好的地方（得）
1. OOXML XML 级的精确控制
这是 ZCode 改造 PPT 模板最大的优势。.pptx/.potx 本质是 ZIP 包，内部是一组 OOXML 文件。ZCode 能直接读写 PowerPoint 界面不允许触碰的底层结构：
slideLayout*.xml------ 版式定义<p:ph type="title"/>------ 占位符声明.rels------ 部件间关系[Content_Types].xml------ 内容类型注册
手工在 PowerPoint UI 里改版式繁琐且受限；XML 直改效率高、能做 UI 做不到的事。
2. 多格式自动导出
通过调用 WPS 演示的 COM 自动化对象（kwpp.Application）的 SaveAs，一次性导出：
.potx：SaveAs(path, 26)（ppSaveAsOpenXMLPresentationTemplate）.dpt：SaveAs(path)，靠 WPP 按扩展名推断为 WPS 私有模板格式
并通过文件头字节 （magic bytes）验证：.potx = 50 4B（PK/ZIP），.dpt = D0 CF 11 E0（OLE2 复合文档），确认是真实格式而非改后缀的伪文件。
3. 依赖关系清理准确
删除 think-cell OLE 对象时，准确定位三层依赖并完整清理：
| 层级 | 处理 |
|---|---|
slide 的 .rels |
删除指向 OLE/tags/image/vml 的 4 条关系 |
| 实际文件 | 删除 oleObject*.bin、tag*.xml、vmlDrawing*.vml、共用的 image18.emf |
[Content_Types].xml |
Default 声明保留（无对应文件后无害） |
清理后包结构完整、无孤儿引用，PowerPoint/WPP 均能正常打开。
4. 图像分析间接验证渲染
通过 Slide.Export 导出 PNG + 视觉模型分析，确认装饰形状（圆环、连接线、绿色色块）从版式正确继承显示。这是纯 XML 验证做不到的------XML 正确不等于渲染正确。
5. 诚实纠错
当用户指出「母版没改」时，ZCode 主动承认了第一次只改了文字样式、没有真正把页面提升为版式，没有掩盖方案偏差。这是 AI 协作中重要的信任基础。
三、ZCode 做得不好的地方（失）
1. 方案理解偏差（最大问题）
第一次「转为母版」被理解成「改母版字体样式」，完全没做「把页面布局提升为版式」。这是对需求的理解错误，导致返工。
根因：第一次给出的 3 个方案选项都只讨论「文本框怎么处理」，没覆盖「是否提升为版式」这个更上层的架构决策。
2. OOXML 规范细节不熟
占位符提示文字第一次写法错误：在 <a:r> 的 <a:rPr> 里加了 <a:solidFill> 和 <a:latin> 等完整属性 ------ 结果 WPP 不把它当占位符提示语。
正确写法 ：run 的 <a:rPr> 要极简（只 lang + dirty="0"），字体/颜色/字号走 <a:lstStyle> 的 <a:defRPr>。这是 OOXML 规范的细节陷阱。
3. 过度相信 COM API 的验证结果
AddSlide 新建的幻灯片占位符是空的，一度以为是 layout 写错了。后来才发现是 API 限制，不是文件问题------API 创建的占位符不带提示文字，但 layout 文件本身是对的。没及早识别 API 与 UI 行为的差异，浪费了排查时间。
4. 不可见字符处理失误
母版里的 <a:buChar char=""/> 实际含 Symbol 字体的项目符号字符（Read 工具显示为空），导致 Edit 字符串匹配失败多次。后改用「只匹配 defRPr 段、避开 buChar」绕过。
5. 早期没主动提示盲区
第一次交付时声称「母版统一完成」，但没指出「版式层有局部 lstStyle 会覆盖母版字号」这个真实缺口，让用户误以为全部统一了。
四、后续注意事项
技术层面
| # | 注意点 | 说明 |
|---|---|---|
| 1 | WPP COM AddSlide 不继承占位符提示文字 |
这是 API 已知行为。layout 文件写对就行，但必须让用户手工在 WPP 界面验证新建行为，不能只靠 API 测试。 |
| 2 | WPP COM 读占位符 Width/Left 返回 0 或 0.1pt | 连现有 slide 也读出 0，但实际渲染正常。占位符尺寸要以 XML 数值 + 渲染图为准，不能信 COM 报告。 |
| 3 | 占位符提示文字必须用标准结构 | <a:r><a:rPr lang="en-US" dirty="0"/><a:t>提示语</a:t></a:r>；样式放 <a:lstStyle> 的 <a:defRPr>。run 的 rPr 加 solidFill 会导致提示语失效。 |
| 4 | 改 layout/slide 占位符后双轨验证 | ① 现有页（继承 layout，能反映 layout 实际效果）；② 提示用户手工新建验证（API 验证不可靠）。 |
| 5 | plan mode 下 Bash 受限 | 需要解包或运行命令时，要么退出 plan mode，要么用 Agent 子代理（它有 Bash 权限）。 |
| 6 | 改 layout 涉及三处同步 | slideMaster1.xml.rels（加 rId）+ slideMaster1.xml 的 <p:sldLayoutIdLst>（加 sldLayoutId）+ [Content_Types].xml（加 Override）。漏一处就注册失败。 |
流程层面
| # | 注意点 |
|---|---|
| 7 | 遇到「转为/提升为」这类词，先确认架构层级。是 slide 层改动、layout 层改动、还是 slide→layout 提升？三者的工程量差几个数量级。 |
| 8 | 第一次方案选项要覆盖架构决策，不要只停留在「细节怎么处理」。 |
五、ZCode 的能力边界（无法做到的事）
这些是工具/环境本身的硬限制，不是努力就能克服的：
1. 无法复现 WPP 真实 UI 行为（最大盲区）
COM API 的 AddSlide 与用户在界面「新建幻灯片→选版式」的行为不一致 。ZCode 无法在脚本里点 UI 按钮，所以「用户新建时占位符提示语是否显示」这一项始终无法独立验证，必须用户手工确认。
2. 无法验证 PowerPoint（非 WPS）的行为
本机只装了 WPS Office，没有 Microsoft PowerPoint。.potx 是 OOXML 标准，理论上 PowerPoint 也能开，但渲染细节、占位符继承行为在 PPT 和 WPP 间可能有差异，ZCode 无法在本机交叉验证。
3. 无法实时视觉对比 / diff
只能「导出 PNG → 读图分析」，不能像人眼那样实时看渲染、对比改动前后。视觉验证是事后、低分辨率的。
4. 无法处理 XML 里不可见字符的精确匹配
Edit 工具按字符串匹配，遇到 Symbol 字体字符、控制字符（如项目符号 buChar）会失败。Read 工具把这些字符渲染成空，实际内容与显示不一致，需绕开匹配。
5. 无法验证最终用户体验
「模板好不好用」本质是用户主观体验。ZCode 能验证结构和渲染，但「新建时提示语是否如预期出现、操作是否顺手」必须用户实操。
6. 无法绕过文件占用
源文件被 PowerPoint 进程占用时，必须先 copy 才能解包。这是 OS 层限制。
7. WPP COM 首次启动可能弹窗卡死
首次调用 kwpp.Application 可能因 WPP 初始化/登录弹窗阻塞 2 分钟超时。需提前手动启动一次 WPP 完成初始化，或用 WithWindow:=False + DisplayAlerts=0。
六、结论与建议
ZCode 适合做的 PPT 模板工作
- ✅ OOXML XML 级的精确改造（删 OLE、改 layout 结构、注册版式）
- ✅ 批量统一母版/版式的字体、颜色、字号
- ✅ 多格式导出（potx / dpt）+ 格式真实性验证
- ✅ 依赖关系清理（删除插件残留对象）
- ✅ 结构正确性验证（rels / Content_Types 一致性）
ZCode 不适合 / 需要人工兜底的
- ❌ 最终 UI 行为验证（用户新建幻灯片时的占位符提示语、装饰是否出现）
- ❌ 跨办公软件兼容性验证（PowerPoint vs WPS）
- ❌ 主观体验判断
给使用者的建议
- 交付后务必手工验证一次：打开模板 → 新建幻灯片 → 依次选每个新版式 → 确认装饰形状出现 + 标题/正文提示语显示 + 占位符可编辑。这步 ZCode 替代不了。
- 复杂模板改造优先用 plan mode：先摸清结构、列出三处同步清单、确认架构层级，再动手。
- 建立三层验证 checklist：结构验证（XML 关系完整）+ 渲染验证（现有页导图）+ UI 验证（手工新建）。
- 方案沟通要覆盖架构层级，别只讨论细节。