别让 Agent 直接改 .pptx：Slaide 用纯文本、主题与校验把演示文稿纳入版本控制
让编码 Agent 生成演示文稿，最常见的失败并不是“内容写得不够漂亮”，而是产物不可审查。.pptx 本质是一组体积不小的 XML 与媒体文件：人类可以在 PowerPoint 里拖拽修正，模型却难以稳定地理解版式约束；进入 Git 后，评审者也很难从二进制差异判断一段话、一个图表或一次布局修改究竟改变了什么。
Slaide 提供了另一种边界更清晰的做法。它把演示文稿表示为 .slaide 纯文本文件：正文使用 Markdown，小型 YAML 主题承载视觉规则。CLI 将同一份源文件渲染为可导航的 Web 演示、PDF 和可编辑的 PowerPoint；项目的语言、渲染器、导入导出、MCP server 和 Agent skill 都在 Apache-2.0 许可的仓库中。它并非把所有功能都称作开源：需要登录后解锁的桌面可视化编辑器引擎，以及云端代写/改写演示文稿的 Agent，属于产品的另一层能力。这个区分对团队采购与本地构建尤其重要。
先把“内容变更”和“设计变更”拆开
传统演示工具把文字、颜色、间距、动画和对象坐标混在一个图形化文件里。Slaide 的思路是让幻灯片文本只表达结构，把风格交给可复用主题。
一份最小文件可以包含封面和内容页：
---
master: ./theme.slaide.yaml
title: 发布复盘
---
layout: cover
---
:: title ::
[把演示稿放回 Git]{.grad}
:: subtitle ::
内容与视觉分层
---
layout: title-content
---
## 本周结论
- 先校验，再导出
- 主题决定视觉，不手工摆像素
??? 这里是演讲者备注，不会显示给观众。
--- 切分页面；:: name :: 将 Markdown 送入主题定义的插槽；??? 表示 speaker note。换句话说，Agent 的责任是提出可评审的标题、论点、列表和备注，而不是猜测每个文本框的坐标。设计系统维护者则通过主题集中控制字体、颜色与布局。两种变更在 Git diff 中自然分离：内容 PR 不应顺带制造一批无关的视觉微调，主题升级也可单独审查。
这并不意味着纯文本天然优于可视化编辑。需要自由排版、逐页艺术指导或现场快速拖拽时，GUI 仍更直接；但对于周报、架构评审、发布复盘和由 Agent 持续更新的项目说明，确定的文本源更适合自动化管线。
用 CLI 建立“生成前可检查”的交付流程
Slaide 的 npm 包名是 @aivorynet/slaide。安装后可以先创建文件、校验语法，再启动本地预览；需要导出 PDF、PPTX 或图片时，官方说明要求额外安装 Chromium：
npm install -g @aivorynet/slaide npx playwright install chromium slaide new release-review.slaide slaide validate release-review.slaide slaide dev release-review.slaide slaide build release-review.slaide --out out slaide export release-review.slaide --pdf out/release-review.pdf slaide export release-review.slaide --pptx out/release-review.pptx
validate 应当放在 Agent 提交内容与渲染之间，而不是等导出失败才人工打开文件排查。dev 默认提供本地实时预览；build 生成可独立分发的 out/index.html。在 CI 中，最小策略可以是：仅允许 Agent 修改 .slaide 和数据素材，执行 slaide validate，随后构建 Web 成品并把输出作为 PR artifact。这样评审既能看文本 diff，也能打开渲染结果检查溢出、层级与逻辑。
Agent 接入时，别绕过文件与验证步骤
Slaide 还提供 slaide install 与 slaide mcp：前者安装 Agent skill，后者启动 MCP server。文档明确区分 slaide install 和 slaide app——前者面向 Agent skill，后者打开并按需获取桌面查看器，不应把两者混作一个“安装命令”。
一个稳妥的工作流是让 Agent 只在分支中修改源文件，然后由自动化执行校验和导出：
- 将公司主题与示例
.slaide一并纳入仓库，作为可复用的受控输入； - 提示 Agent 只新增或修改指定文稿，要求其保留页面分隔、主题槽位和备注语法；
- 在合并前运行
slaide validate，并在预览或 artifact 中检查输出； - 只有确认内容与渲染都正确后，才导出 PDF 或 PPTX 给外部受众。
PPTX 导入也有它的边界。slaide import deck.pptx 可将 PowerPoint 或 Keynote 导入为 .slaide，但导入结果应被看作迁移起点，而不是对复杂原稿的无损证明：带有大量自定义动画、特殊图形或精细手工布局的旧文件，仍需要人通过预览逐页验收。
让主题成为团队接口，而不是又一份说明文档
当多个 Agent 或多人同时写演示稿时，真正容易漂移的是视觉约定。有人把风险写成红色大标题，有人把同一类结论放进脚注；当这些选择没有落在主题与布局的名字上，后续每轮生成都会重新发明规则。Slaide 的 master 字段指向主题文件，页面再以 layout 和命名槽位表达意图，恰好可以把“什么是封面、结论页、双栏页”变成仓库中可复审的接口。
建议不要一开始制作万能主题，而是先为一种业务文稿固定三到五个布局。例如封面只接受 title 与 subtitle，结论页只接受标题和项目符号，架构页统一预留图表或代码槽位。Agent 的提示词也应该引用这些已存在的布局名称，禁止它临时杜撰 slot 名称。这样，校验失败通常意味着结构不符合主题契约，而不是留给设计同事在最后一分钟肉眼发现。
还可以把主题升级当作普通工程变更处理：先用一组示例文稿构建 HTML、PDF，比较渲染结果；再合并主题 PR。不要在生成一份重要客户演示稿时同时升级主题、替换字体、让 Agent 改写文本。将内容、主题和导出环境拆成独立变量，排错成本会低得多。
导出链路里最容易遗漏的两件事
第一，PDF、PPTX 和图像导出依赖 Playwright 的 Chromium。CI 容器如果只安装 npm 包而未安装浏览器，文稿本身即使通过 validate，导出步骤仍可能失败。因此应将 npx playwright install chromium 写进构建镜像或 CI 初始化阶段，并用一个很小的样例文稿做健康检查。
第二，构建成功不等于沟通成功。语法校验能发现格式问题，却无法替你判断一页是否塞入过多论点、图示是否与结论一致，或说话人备注是否泄露给了错误受众。实际评审可采用两道门：自动门检查 validate 与导出是否成功；人工门打开 HTML/PDF，重点看长标题换行、列表密度、关键数字和每张图的来源。对 Agent 生成内容，还应把外部事实、数字和引用链接留在源文件或相邻的研究笔记中，避免把未经验证的叙述直接固化成演示结论。
与既有 PowerPoint 流程如何共存
一个务实的迁移方式不是要求所有人改用新格式，而是从“机器生成、需持续更新”的文稿开始。比如发布说明可以由代码变更和 issue 数据生成初稿，架构评审可以从 ADR 与仓库模块信息生成提纲；这些内容天然适合文本 diff 和自动构建。对外品牌发布、营销视觉或高自由度培训材料，则仍可在 GUI 中完成最终设计。
Slaide 的 PowerPoint 导出使两条路径不必互斥：工程团队可以把 .slaide 作为源文件和审计记录，外部协作者则接收可编辑 PPTX。需要回收历史文件时，再从导入命令开始逐步迁移。关键不是宣称格式转换没有损耗，而是明确哪一份文件是可复现的事实来源、哪一份是面向交付的编辑副本。
可复现并不等于放弃可编辑交付
Slaide 的价值不在于替代所有幻灯片软件，而在于为“AI 参与写稿”的场景增加一个稳定接口：文本源可审查、主题可复用、渲染可重跑，最终仍可导出可编辑的 PowerPoint。对于已经把代码、文档和架构决策纳入版本控制的团队，这比直接让 Agent 操作二进制办公文件更接近可维护的软件交付。
落地时先挑一种高频、版式较稳定的文稿试运行，例如迭代复盘或技术设计评审。若主题规范与校验步骤能消除大部分返工，再逐步把更多模板迁入；若团队真正依赖的是自由设计与即时协作，则应保留现有 GUI 工作流，而不是为了“AI 化”强行转换。
相关链接