officecli-pptx

OfficeCLI PPTX 技能

安装

如果缺少 officecli：

• macOS / Linux：curl -fsSL https://d.officecli.ai/install.sh | bash
• Windows (PowerShell)：irm https://d.officecli.ai/install.ps1 | iex

使用 officecli --version 验证（如果 PATH 尚未更新，请打开新的终端）。如果安装失败，请从 https://github.com/iOfficeAI/OfficeCLI/releases 下载二进制文件。

⚠️ 先查阅帮助的规则

此技能介绍优秀幻灯片的样子，而非每个命令标志。当属性名称、枚举值或别名不确定时，先查阅帮助，再做判断。

officecli help pptx                         # List all pptx elements
officecli help pptx <element>               # Full element schema (e.g. shape, chart, animation, connector, zoom, group)
officecli help pptx <verb> <element>        # Verb-scoped (e.g. add shape, set slide)
officecli help pptx <element> --json        # Machine-readable schema

帮助反映已安装的 CLI 版本。技能说明与帮助不一致时，以帮助为准。以下情况应立即运行帮助：出现 UNSUPPORTED props: 警告、动画预设未知、connector.shape= 的枚举值有变，属性与别名不确定（lineWidth 与 line.width、color 与 font.color）。

Shell 与执行规范

Shell 引号（zsh / bash）。 始终为元素路径加引号（"/slide[1]/..."）——zsh 会将未加引号的 [1] 视为 glob，导致 no matches found。转义分为三层，请分别处理（CLI 会为你处理第二层）：

1. Shell。 值中的 $ 仍由 shell 处理——请用单引号括住整个值：--prop text='$15M'。双引号括起的 "$15M" 会被展开为 M。CLI 不会替你对 \$ 取消转义。
2. CLI（text=）。 两字符转义序列 \n 和 \t 会被解析，且在 pptx / docx / xlsx 中行为一致——\n 表示换行 / 段落换行，\t 表示制表符。要在文本中输出字面量反斜杠-n，需将其加倍（\\n）；这种情况很少是你想要的。
3. JSON（批处理 heredoc）。 以下示例通过 cat <<EOF | officecli batch 传递内容，且不加引号，因此 $SLIDE / $FILE 会在正文中展开。同一个未加引号的 heredoc 也会展开值中的字面量 $："$1.42" 会静默变成 .42，"$2.4B" 会变成 .4B（$1 / $2 是空的 shell 参数）。货币符号需转义为 \$——"text":"\$1.42"——这样仍可展开 $SLIDE。JSON 中的 \n / \t 无论哪种方式都能正常工作。完全加引号的 <<'EOF' 会保护所有 $，但 $SLIDE 也不会展开，因此仅在正文不含 shell 变量时使用。写入金额后，使用 view text 确认 $ 仍然存在。

如有疑问，写入后使用 view text，逐字符比较。

增量执行。 每次执行一条命令 → 检查退出代码 → 再继续。如果 50 条命令的脚本在第 3 条命令处失败，后续错误会悄然连锁发生。执行任何结构性操作（新建幻灯片、图表、动画、连接符）后，先运行 get 再继续添加内容。

输出要求

以下是每份演示文稿都必须满足的交付标准。任意一项不达标 = 未完成，无论内容质量如何。

所有幻灯片

每张幻灯片只讲一个观点。 如果需要加第二个标题来解释幻灯片的内容，就拆分成多张。内容密集、试图涵盖“关于 X 的所有内容”的幻灯片，会在 3 秒内让观众失去注意力。用章节分隔页将表达单一观点的相关幻灯片归类，而不是做成一张巨型幻灯片。

明确的字体层级——不要依赖主题默认设置。 不同母版的主题默认设置可能不一致。为每个文本形状明确设置字号。

元素	最小值	常用范围	形状最小高度
幻灯片标题	≥ 36pt，加粗	36–44pt	≥ 2cm
章节标题 / 副标题	≥ 20pt	20–24pt	≥ 1.2cm
正文	≥ 18pt	18–22pt	≥ 1cm
图注 / 坐标轴标签	≥ 10pt，弱化显示	10–12pt	≥ 0.6cm

经验法则：形状最小高度 ≈ 字号（pt）× 0.05cm。在 0.8cm 高的文本框里放 18pt 的副标签会溢出——view annotated 会检测到这种情况。

标题字号必须至少是正文字号的 2 倍（36pt 标题搭配 20pt 正文很合适；28pt 搭配 20pt 则显得拘谨）。正文可以低于 18pt 的情况只有 4 种：图表坐标轴标签、图例、页脚 / 页码，以及不超过 5 个词的 KPI 副标签（例如“活跃用户”）。描述性句子必须 ≥ 18pt。正文左对齐；只有标题和醒目的大数字居中。如果“卡片放不下”，就删掉卡片，不要缩小字号。

最多两种字体，使用一套配色。 一种标题字体 + 一种正文字体（例如 Georgia + Calibri）——只有用于醒目的大数字或封面标题时，才可以使用第三种展示字体，且标题字体与正文字体的搭配必须保持不变。一种主品牌色（占比 60–70%）+ 一种辅助色 + 一种强调色。正文内容中绝不要混用 4 种或更多颜色。《设计原则》中的配色方案和字体搭配只是起点，不是可选菜单： 如果用户提供了品牌颜色 / 字体或现有模板，应优先与之保持一致；否则，所列方案是经过校准的基础组合——只要最终效果不比它们差，且满足最低对比度要求，就可以自由融合或另辟蹊径。

每张幻灯片都要有非文本视觉元素，且能传达信息。 可以是形状、图表、图标或传递含义的渐变色带，而不是装饰。只有项目符号的幻灯片和 Word 文档没什么区别。例外：纯引用幻灯片、代码块，以及单页总结表格。

少即是多——每个元素都要有存在的理由。 上述视觉原则是为了避免项目符号墙，并非让页面变得杂乱。不要用无法传递信息的装饰性统计数据、图标或填充章节来凑内容（“数据垃圾”）。如果幻灯片显得空洞，就通过布局和留白来调整，而不是编造内容——宁可缩小范围，也不要堆砌；如果确实需要大幅增加内容，应明确指出，而不是擅自添加。

每张内容幻灯片都要有演讲者备注。 --type notes --prop text="..."。演讲者需要讲稿；观众不该只是照着幻灯片逐字阅读。

文案要像真人写的，而不是 AI 写的。 标题应围绕内容展开，而不是追求 punchline。不要写“这不是 X，而是 Y”，不要刻意制造张力，不要装出洞见（“神奇时刻”），也不要用一个词营造戏剧效果（“势头。”）。删掉夸张的形容词（无缝、稳健、颠覆性）——让数字自己说明问题。

保留现有模板。 如果文件已有主题和母版，应与之保持一致。现有规范优先于本指南。

视觉交付底线（适用于每一份演示文稿）

在宣布完成之前，每张幻灯片的渲染结果（见 QA）都必须满足以下要求：

• 渲染内容中不得出现占位符。 {{name}}、$fy$24、<TODO>、lorem、xxxx，以及图表标题中的空 ()/[] 都不得出现。
• 不得有内容溢出边缘或形状中的文字被裁切。 view issues 会同时标记这两类问题（shape_off_slide + 文本适配提示）。要修复裁切：扩大文本框或缩短内容，绝不能裁剪内容来强行适配。
• 封面应包含引导信息。 标题 + 副标题 + 演讲者/客户 + 日期 + 品牌色带或核心要点横幅——只有标题的封面看起来像个空壳。留出充足空白依然是正确做法；内容丰富 ≠ 拥挤。
• 对比度。 view issues 会自动标记常见问题：深色文本不透明地放在形状自身的深色填充上（low_contrast）。它无法识别其他情况：图标/图表系列填充色、主题/继承颜色，或文字叠放在独立的背景形状上。因此，对于亮度 < 30% 的填充色（1E2761、36454F、深森林绿/莓果色/樱桃红），仍须确认每段正文、卡片正文、图表系列和图标的颜色都是 FFFFFF 或亮度 > 80%——中灰色（6B7B8D，亮度约 44%）在笔记本屏幕上看得见，投影时却会消失。深色填充检查完成后，通过 view html 抽查。

如果任何一项不合格，请立即停止并修复，然后再宣布完成。

设计原则

演示文稿不是文档。观众只有 3 秒钟来理解每张幻灯片。添加任何内容之前，先问自己：“如果观众只看最大的元素，再扫一眼就离开，他们能明白重点吗？”如果他们必须阅读要点列表，说明最大的元素设计错了。

网格、边距与负空间

标准宽屏尺寸为 33.87 × 19.05cm。在内部将其视为 12 列网格：

• 四周边距 ≥ 1.27cm（0.5"）。
• 模块间距 ≥ 0.76cm（0.3"），用于卡片/列/行之间——选定一个值（0.76 或 1.27cm）并全篇统一；间距不一会显得不完整。
• 每张幻灯片至少留出 20% 的负空间。 填满每个像素会显得不专业。
• 进行构图，而不是像网页那样居中。 留白具有结构作用：幻灯片上部内容较多、下三分之一留白，是正确的构图，而非空洞缺陷。有意的不对称（内容靠左，右侧留出呼吸空间）比所有内容都居中更显设计感——不要仅仅因为那里有空隙就把它填上。
• 对于卡片网格：usable = 33.87 − 2·margin − (N−1)·gap，然后 col_width = usable / N。不要手动挑选 x 坐标。

字体搭配

根据文档风格搭配字体，而不是追求新奇。“适用场景”是提示，并非硬性规定；只要合适，表格外的搭配也可以——这里的 8 种只是示例，并非全部选项。

标题	正文	适用场景
Georgia	Calibri	正式商务、金融、高管报告
Arial Black	Arial	大胆营销、产品发布
Calibri	Calibri Light	简洁企业风、极简设计
Cambria	Calibri	传统专业风格、法律、学术
Trebuchet MS	Calibri	亲和科技风、初创公司、SaaS
Impact	Arial	醒目标题、活动演示文稿、主题演讲
Palatino	Garamond	优雅编辑风格、奢侈品、非营利组织
Consolas	Calibri	开发者工具、技术/工程

在每个形状上显式设置两种字体（标题使用 --prop font=Georgia，正文使用 --prop font=Calibri），不要依赖主题继承。

色彩与对比度

各列：主色（主导色——占整体视觉权重的 60–70%，第一眼看到的颜色）、辅助色（辅助色调）、强调色（少量使用，用于重点强调）、文本色（用于浅色填充上的正文）、弱化色（用于说明文字 / 坐标轴标签 / 页脚）。

主题	主色	辅助色	强调色	文本色	弱化色
珊瑚活力	F96167	F9E795	2F3C7E	333333	8B7E6A
午夜商务	1E2761	CADCFC	FFFFFF	333333	8899BB
森林苔藓	2C5F2D	97BC62	F5F5F5	2D2D2D	6B8E6B
炭灰极简	36454F	F2F2F2	212121	333333	7A8A94
暖陶土	B85042	E7E8D1	A7BEAE	3D2B2B	8C7B75
莓果奶油	6D2E46	A26769	ECE2D0	3D2233	8C6B7A
海洋渐变	065A82	1C7293	21295C	2B3A4E	6B8FAA
青绿信任	028090	00A896	02C39A	2D3B3B	5E8C8C
鼠尾草宁静	84B59F	69A297	50808E	2D3D35	7A9488
樱桃醒目	990011	FCF6F5	2F3C7E	333333	8B6B6B

根据主题选择，而不要默认使用某个主题——金融内容适合午夜商务，产品发布适合珊瑚活力，安全 / LOTO 适合樱桃醒目。如果最接近的命名主题不太合适，可以混搭（例如，森林主题主色 + 金色 D4A843 强调色）。浅色填充上使用文本色，说明文字 / 坐标轴 / 页脚使用弱化色，深色填充上的正文使用 FFFFFF 或辅助色。

在深色背景上，文本和图表系列必须符合上文的硬性对比度下限。

图表选择决策表

错误的图表类型会让你无法通过 3 秒测试：

数据形态	使用	避免
类别比较（A 与 B 与 C）	column（竖向）/ bar（≥ 6 个类别，横向）	饼图（扇区容易混在一起），折线图（没有时间轴）
时间序列，1–3 个系列	line	面积图（遮挡），条形图（会让人以为数据离散）
整体中的部分，2–5 个扇区	pie / doughnut	含 8 个以上扇区的饼图（难以阅读）
相关性 / 分布	scatter	折线图（会让人以为数据有序）
多个类别 × 多项指标，数据密集	堆叠 column 或热力图	每项指标单独做一张图——应合并呈现
KPI 快照（单个大数字）	大号文本形状（60–72pt + ≤ 5 个词的副标签），而非图表	仪表盘图表、很小的条形图

经验法则：如果系列数 > 3 且类别数 > 8，就拆成两张图或改用表格。

动画

动画用多用少，应由品牌和内容决定——正式的金融演示文稿通常几乎不使用动画，产品发布则可以更具表现力。动画是工具，而不是装饰。以下三条底线可以避免动画损害演示文稿（它们都不限制动画的使用量）：

• 有明确目的——每个动画都应用于揭示内容或突出重点（逐步显示项目符号、逐步构建图表），绝不只是装饰。如果无助于理解，就删掉。
• 优雅降级——pptx 动画在不同查看器（Keynote / Slides / 网页 / 移动端）中的渲染并不一致，也可能完全无法播放，因此每张幻灯片都必须在作为静态画面时也能正确传达信息。绝不能把关键信息藏在动画效果之后。
• 现场验证——动画只在运行时生效；view html 和截图无法显示动画，因此交付前要在实际的演示文稿查看器中确认效果。

风格建议（并非禁令）：fade / appear / 单次 zoom-entrance，搭配利落的时长（约数百毫秒），适合大多数演示文稿；bounce / swivel / spin / fly-from-edge / 密集的多对象编排通常显得不专业——只有在品牌风格刻意追求活泼时才使用。

布局模式与数据展示

在不同幻灯片中变换布局模式——重复相同的模式会让每张幻灯片看起来都一样。以下是常见的构建模块，并非全部模式——每张幻灯片选一种；如果内容需要，也可以在表格之外设计布局：

模式	适用场景	关键尺寸
双栏（左侧文字，右侧视觉内容）	概念 + 佐证；功能 + 截图	每栏约 14-15cm；间距 1cm
图标行（填充圆形中的图标 + 粗体标题 + 描述）	功能列表、优势、团队角色	图标圆形直径 1.5-2cm；最多 3-4 行
2×2 或 2×3 网格（卡片式平铺）	象限分析、SWOT、选项比较	间距 ≥ 0.76cm；卡片高度一致
半幅出血图（左侧或右侧半幅铺满，内容叠加在另一侧）	主视觉场景、案例研究开篇	图片宽 16-17cm；内容栏宽 ≥ 14cm
大型数据指标（60-72pt 数字 + 下方不超过 5 个词的副标签）	单个 KPI、里程碑、市场规模	使用形状，而非图表；副标签 14-16pt，颜色柔和

数据展示速查规则：

• 比较 2-3 个选项时，使用对比栏（之前/之后、A 与 B）优于表格。
• 时间线和流程图：使用带连接线的编号步骤形状，而非项目符号列表。

图片处理（仅适用于使用照片 / 截图 / Logo 的幻灯片）

先查看图片（打开文件），再根据实际内容选择处理方式——不要只凭文件名盲目放置。

• 全幅出血照片 → 调整尺寸以覆盖区域（裁切边缘），不加边框。
• 截图 / 示意图 / Logo → 调整尺寸以适应（绝不裁切内容）。透明图片或适应区域的图片应放在对比明显的底色上——在后方添加彩色矩形，不要让图片直接浮在白底上。
• 照片上的文字 → 绝不直接叠在图片上。将文字放在卡片中，或在图片与文字之间加一层保护遮罩（约 50–60% 不透明度的深色矩形，或从文字一侧渐隐的渐变）。
• 绝不拉伸（扭曲宽高比）；不要在繁杂的截图上叠加文字。
• 优先使用用户提供的图片 / 品牌素材；除非用户要求，否则不要使用 Emoji 或自行绘制的艺术图案。

视觉元素的统一运用

选择一个独特元素（圆角图片框、填充圆形中的章节编号、单侧边框色带、斜向装饰条），并将其贯穿每张幻灯片——在整套幻灯片中保持一致；只设计一张幻灯片，其余都保持朴素，会让人觉得项目半途而废。只有在不会与主要元素争抢注意力时，才可使用次要元素。先在构建计划中声明：## Motif: numbered circles in brand color。

应避免的 AI 视觉痕迹

• 不要在幻灯片标题下方使用装饰性下划线。 标题下的色带 / 横线是最常见的 AI 幻灯片痕迹——改用留白或背景色变化。
• 不要使用带彩色左侧边框色带的圆角卡片。 这是另一种典型的 AI 幻灯片痕迹——改用纯色填充、顶部强调色带或留白分隔。
• 除非品牌本身使用 Emoji，否则不要将 Emoji 用作图标。 请使用形状或真实图标素材。

文案层面的痕迹请参阅“Copy reads human”。

常见工作流

1. 打开/保存生命周期。 开始时运行 officecli open <file>，结束时运行 officecli save <file>，将编辑内容写入磁盘。save 只负责写入——它会让常驻进程保持就绪，便于后续编辑；只有在想立即释放常驻进程时（一次性交接），才使用 officecli close <file>。这两种操作始终安全——不会报错或丢失工作。重复处理形状网格时使用 batch。仅在跨出 officecli 的边界时刷新： officecli 自身的读取总能看到你的编辑；只有在非 officecli 程序要读取文件（python-pptx、PowerPoint、渲染器、交付）之前，才运行 save/close。
2. 了解现状。 新建演示文稿：officecli create "$FILE"。编辑现有文件：先运行 officecli view "$FILE" outline。切勿盲目编辑。
3. 先确定标题顺序（先规划，暂不构建）。 创建任何幻灯片或形状之前，先写出完整且有序的幻灯片标题列表。如果有人只读标题就无法理解论述脉络，现在就调整结构——在列表中修改比做完 14 张幻灯片后再改便宜得多。选择一种标题语法——全部使用主题名词短语，或全部使用行动陈述，绝不要混用——并始终保持一致（参见“文案读起来自然”）。
4. 按展示顺序构建。 按观众看到的顺序添加幻灯片：封面 → 议程 → 第 1 节分隔页 → 第 1 节内容 → 第 2 节分隔页 → … → 结尾页。添加幻灯片时可以使用 --index，但按顺序追加能让构建脚本更易读，也能避免索引计算错误。最终交付前，确认幻灯片数量和叙事脉络与构建计划一致。 第 3 道关卡的顺序检查可以发现封面排在 14 张中的第 11 张、而非第 1 张等问题。
5. 逐张增量构建。 创建幻灯片和背景，然后添加标题，再添加辅助形状/图表/连接符。自定义设计始终使用 layout=blank。每次结构性操作后，运行 get /slide[N] --depth 1 确认形状 ID。
6. 按规范设置格式。 按照要求表格执行；格式是交付内容的一部分，而非润色。
7. 保存并验证。 officecli save 会将文件刷新到磁盘（或使用 officecli close，刷新文件并结束会话）。交付前，务必在目标演示文稿查看器中打开文件——图表颜色、动画、字体和缩放都是 view html 无法渲染的运行时特性。完整验证见下文 QA。
8. QA——假设总有问题。 持续修复并验证，直到一轮检查未发现任何新问题。

快速开始

最精简的可用演示文稿：封面 + 一张内容页 + 备注。$FILE 代表你的文件名。

FILE="deck.pptx"
officecli create "$FILE"
officecli open "$FILE"

# Cover — dark fill, centered title
officecli add "$FILE" / --type slide --prop layout=blank --prop background=1E2761
officecli add "$FILE" /slide[1] --type shape --prop text="FY26 Strategic Review" \
  --prop x=2cm --prop y=7cm --prop width=29.87cm --prop height=3cm \
  --prop font=Georgia --prop size=44 --prop bold=true --prop color=FFFFFF --prop align=center

# Content — white fill, title + body + notes
officecli add "$FILE" / --type slide --prop layout=blank --prop background=FFFFFF
officecli add "$FILE" /slide[2] --type shape --prop text="Revenue grew 18% YoY" \
  --prop x=1.5cm --prop y=1.2cm --prop width=30cm --prop height=2cm \
  --prop font=Georgia --prop size=36 --prop bold=true --prop color=1E2761
officecli add "$FILE" /slide[2] --type shape --prop text="Enterprise renewals + new EMEA region drove the beat; NRR held at 118%." \
  --prop x=1.5cm --prop y=4cm --prop width=30cm --prop height=3cm \
  --prop font=Calibri --prop size=20 --prop color=333333
officecli add "$FILE" /slide[2] --type notes --prop text="Lead with the 18% beat, preview EMEA."

officecli save "$FILE"
officecli validate "$FILE"

每个构建都遵循以下流程：打开 → 幻灯片+背景 → 标题 → 正文 → 备注 → 保存 → 验证。

阅读与分析

先全面了解，再深入细节。先运行 outline，确定要查看的位置后，再使用 view text / get / query。

officecli view "$FILE" outline          # slide count + titles
officecli view "$FILE" annotated        # complete per-slide breakdown with fonts, sizes, tables, charts
officecli view "$FILE" text --start 1 --end 5   # text dump (includes table cell text)
officecli view "$FILE" issues           # empty slides, overflow hints
officecli view "$FILE" stats            # counts + totals (incl. pictures missing alt)

检查单个元素。 类 XPath 路径，从 1 开始计数。始终加引号。优先使用 @name= / @id= 选择器，而非位置选择器 [N]（重新排序后依然稳定）。[last()] 可用。添加 --json 可输出机器可读内容。

officecli get "$FILE" "/slide[1]" --depth 1              # shape list with IDs and names
officecli get "$FILE" "/slide[1]/shape[@name=Title]"
officecli get "$FILE" "/slide[1]/table[1]" --depth 3     # table rows / cells

跨整份演示文稿查询。 类 CSS 选择器；运算符包括 =、!=、~=、>=、<=、[attr]、:contains()、:no-alt。help pptx query 会列出可查询的元素类型。

officecli query "$FILE" 'shape:contains("Revenue")'
officecli query "$FILE" 'picture:no-alt'                 # accessibility gap
officecli query "$FILE" 'shape[fill=1E2761]'             # color match
officecli query "$FILE" 'shape[width>=10cm]'             # numeric

query --json 输出架构。 结果封装在 .data.results[] 中——使用 jq -r '.data.results[0].format.id'，而非 .[0].id。形状名称为 .name；填充为 .format.fill；文字颜色为 .format.textColor。

视觉预览（LEAD）。

officecli view "$FILE" html                # prints an HTML preview path; Read it for per-slide visual audit (best structural ground truth)
officecli view "$FILE" svg --start 3 --end 3   # single slide SVG (charts + gradients do NOT render in SVG)

解读输出——一种预期情况，并非缺陷：

• layout=blank 没有标题占位符。 标题是普通的 shape 元素，因此 view outline 报告 (untitled) 属于预期情况，并非缺陷。只有在需要兼容屏幕阅读器大纲时，才使用 layout=title + placeholder[title]。

创建与编辑

动词：add / set / remove / move / swap / batch / raw-set。一份演示文稿的九成内容是幻灯片、形状、文本、少量图表、图片和连接符。

幻灯片与背景

幻灯片路径为 /slide[N]。自定义设计始终传入 layout=blank。背景可以是纯色、渐变或图片。

officecli add "$FILE" / --type slide --prop layout=blank --prop background=1E2761                 # solid
officecli add "$FILE" / --type slide --prop layout=blank --prop "background=1E2761-CADCFC-180"   # gradient (start-end-angle)
officecli add "$FILE" / --type slide --prop layout=blank --prop background=image:/path/to/hero.jpg  # image background (LEAD)

形状

shape 保存文本、填充、边框、位置和可选的动画／链接。

officecli add "$FILE" /slide[2] --type shape --prop name=Title --prop text="Key Insight" \
  --prop x=2cm --prop y=2cm --prop width=20cm --prop height=3cm \
  --prop font=Georgia --prop size=36 --prop bold=true --prop color=1E2761 --prop fill=none

位置需要显式指定——没有布局引擎，网格计算由你负责。--prop preset= 用于选择几何形状（rect、roundRect、ellipse、triangle、arrow、star5 等）；不支持自定义 M...Z 路径，请选择预设。创建形状时为其命名（--prop name=HeroTitle），之后通过 "/slide[N]/shape[@name=HeroTitle]" 定位——形状名称在调整 z 顺序以及移除后重新添加时仍会保留，而位置索引 /shape[3]（甚至 @id=）会改变。进行任何结构更改后，都要重新执行 get --depth 1，再使用位置索引。

形状内的文本（段落、文本片段、样式）

一个形状包含多个段落（paragraph[K]）和文本片段（run[K]）。对于单行文本，只需在形状上设置 --prop text=；文本中的 \n 会产生段落换行，\t 会插入制表符（参见 Shell 与执行规范；要表示字面值，请使用双重 \\n）。add --type paragraph 接受与形状相同的样式属性（text、align、bold、italic、size、color、font）。若要在同一行内使用混合样式，可追加带样式的文本片段：

officecli add "$FILE" "/slide[2]/shape[@name=Card1]/paragraph[1]" --type run \
  --prop text=" (inline detail)" --prop size=14 --prop italic=true --prop color=8899BB

图表

根据设计原则中的图表选择表格来选择图表类型。完整属性列表（chartType 枚举、seriesN.*、data=／categories=、坐标轴选项）：help pptx add chart。典型的多系列图表及品牌色示例：

officecli add "$FILE" /slide[3] --type chart --prop chartType=column \
  --prop series1.name=Revenue --prop series1.values="42,45,48" --prop series1.color=1E2761 \
  --prop series2.name=Growth  --prop series2.values="2,7,7"    --prop series2.color=CADCFC \
  --prop categories="Q1,Q2,Q3" \
  --prop x=2cm --prop y=4cm --prop width=20cm --prop height=10cm

注意事项：（1）包含 ()、[]、TBD 的图表标题会按原样显示。（2）某些查看器会将图表颜色规范化为主题默认色——请在目标查看器中确认。创建图表后也可以添加系列（add --type series）。

图片

officecli add "$FILE" /slide[4] --type picture --prop src=hero.jpg \
  --prop x=1cm --prop y=1cm --prop width=32cm --prop height=18cm \
  --prop alt="Product hero, gradient lit from right"

使用 officecli query "$FILE" 'picture:no-alt' 确认结果为空——交付前必须为空。

连接符（LEAD——优先用于流程图／决策树）

在两个形状之间或自由坐标之间绘制连线。完整属性／枚举参考（shape、headEnd／tailEnd 的取值、from／to 引用形式）：help pptx add connector。

officecli add "$FILE" /slide[5] --type connector \
  --prop "from=/slide[5]/shape[@name=BoxA]" --prop "to=/slide[5]/shape[@name=BoxB]" \
  --prop shape=elbow --prop color=333333 --prop tailEnd=triangle

每个流程连接符都需要箭头。 若没有箭头，bentConnector3 会渲染为无方向的线。preset=rightArrow 叠加方式仅适用于水平流程；带有分叉边的菱形／决策树需要设置 tailEnd=。

动画（LEAD）

遵循上述动画底线（目的明确、降级时效果良好、现场验证）。预设名称和时长语法：help pptx animation。

officecli set "$FILE" "/slide[2]/shape[@name=HeroCard]" --prop animation=fade-entrance-400
officecli set "$FILE" "/slide[2]/shape[@name=HeroCard]" --prop animation=none    # clear all

超链接、工具提示、跳转幻灯片

使用 --prop link=slide[N] 跳转到当前演示文稿中的幻灯片（从 1 开始；目标幻灯片必须存在）；使用 link=nextslide／firstslide／lastslide／previousslide／endshow 进行命名导航；使用 link=https://... 设置 URL；使用 --prop tooltip="..." 设置悬停文本。

表格、占位符、组、缩放——简要说明

• 表格——--type table --prop rows=N --prop cols=M。行级 set 支持 height 和 c1/c2/c3（用于预填单元格文本）。标题行样式在表格级别设置（firstRow=true／headerFill=），而非行属性。单元格格式由单元格段落／文本片段控制。设置表格级字体前，请先填充行（行操作会重置字体级联）。
• 占位符——"/slide[N]/placeholder[title]"／placeholder[body]。仅当幻灯片使用包含占位符的版式时可用（layout=blank 除外）。
• 组（LEAD）——通过 "/slide[N]/group[@name=G]/shape[1]" 定位子项。与位置索引相比，在重新排序后更稳定。
• 缩放幻灯片（LEAD）——--type zoom --prop target=N（每个目标对应一个链接；别名为 slide）。对于多目标导航中心，请分别生成 N 个缩放形状。缩放是运行时功能——view html 显示的是静态几何形状；缩放交互仅在实时演示查看器中运行。
• 幻灯片批注——锚定在 /slide[N]/comment[M] 上的审阅者注释。完整生命周期操作（add / set / get / query / remove）。属性：text、author、initials（自动生成）、date（ISO 8601，默认为 UtcNow）、x／y（长度锚点）。

  officecli add "$FILE" "/slide[2]" --type comment --prop author="Alice" --prop text="Tighten this bullet" --prop x=20cm --prop y=3cm
  officecli query "$FILE" 'comment' --json | jq '.data.results | length'   # count all review comments
  officecli remove "$FILE" "/slide[2]/comment[1]"                           # resolve after addressing
  

幻灯片级方案

一些无法从基础操作中直接看出的模式。每个方案都会先说明视觉效果，然后提供可运行的代码块。$FILE = 你的文件名。使用 /slide[last()] 定位刚添加的幻灯片。这些方案展示了结构和坐标计算——请替换为你为该主题选择的调色板／字体；海军蓝 1E2761 + Georgia 只是示例主题，并非需要照搬的固定风格。

Z 轴顺序。 后添加的形状会显示在上层。请先添加背景装饰，最后添加标题。事后调整：--prop zorder=back/front（会重新编号同级元素——继续堆叠前请重新运行 get --depth 1）。

(a) 封面（及章节分隔页）

视觉效果。 深海军蓝填充，居中的 44pt 标题，18pt 冰蓝色元信息行。

officecli add "$FILE" / --type slide --prop layout=blank --prop background=1E2761
officecli add "$FILE" "/slide[last()]" --type shape --prop text="Strategic Growth Review" \
  --prop x=2cm --prop y=7cm --prop width=29.87cm --prop height=3cm \
  --prop font=Georgia --prop size=44 --prop bold=true --prop color=FFFFFF --prop align=center
officecli add "$FILE" "/slide[last()]" --type shape --prop text="Prepared for Acme Leadership — FY26 Outlook" \
  --prop x=2cm --prop y=11cm --prop width=29.87cm --prop height=1.2cm \
  --prop font=Calibri --prop size=18 --prop color=CADCFC --prop align=center

章节分隔页 = 相同的封面，另加一个巨大的半透明数字（size=120、opacity=0.15），并最先添加，使其位于章节标题后方。

(b) 数据页（图表 + 评论区块）

视觉效果。 左侧三分之二：使用品牌系列色的柱状图。右侧三分之一：「关键洞察」卡片，包含 20pt 标题 + 18pt 正文——让观众先读结论，再解读柱状图。

officecli add "$FILE" / --type slide --prop layout=blank --prop background=FFFFFF
officecli add "$FILE" "/slide[last()]" --type shape --prop text="FY26 Revenue Beat Plan by 18%" \
  --prop x=1.5cm --prop y=1cm --prop width=30cm --prop height=1.8cm \
  --prop font=Georgia --prop size=36 --prop bold=true --prop color=1E2761

# Chart — left 2/3 (single-quote the title because of `$`)
officecli add "$FILE" "/slide[last()]" --type chart --prop chartType=column \
  --prop series1.name=Actual --prop series1.values="42,45,48,55" --prop series1.color=1E2761 \
  --prop series2.name=Plan --prop series2.values="40,42,45,48" --prop series2.color=CADCFC \
  --prop categories="Q1,Q2,Q3,Q4" --prop x=1.5cm --prop y=3.5cm --prop width=20cm --prop height=14cm --prop title='FY26 Revenue ($M)'

# Commentary card — right 1/3: background + heading + body
officecli add "$FILE" "/slide[last()]" --type shape --prop preset=roundRect --prop fill=F5F7FA --prop line=none \
  --prop x=22.5cm --prop y=3.5cm --prop width=9.8cm --prop height=14cm
officecli add "$FILE" "/slide[last()]" --type shape --prop text="Key Insight" \
  --prop x=23cm --prop y=4cm --prop width=9cm --prop height=1.2cm \
  --prop font=Georgia --prop size=20 --prop bold=true --prop color=1E2761
officecli add "$FILE" "/slide[last()]" --type shape --prop text="EMEA launch + NRR at 118% drove 12pp of the 18pp beat." \
  --prop x=23cm --prop y=5.5cm --prop width=9cm --prop height=11cm \
  --prop font=Calibri --prop size=18 --prop color=333333

(c) 流程图／流程示意图（方框 + 连接线）

视觉效果。 四个圆角方框横向排列在 y=8cm 处，每个尺寸为 6×3cm，交替使用海军蓝／冰蓝色，并用带三角箭头的肘形连接线连接。

网格计算（4 个方框，幻灯片宽度 33.87cm，边距 1.5cm）：gap = (33.87 − 3 − 24) / 3 = 2.29cm。x 坐标：1.5, 9.79, 18.08, 26.37。

每个方框通过 valign=middle 携带自己的标签（无需单独的叠加形状）。使用 batch heredoc 实现可移植的坐标计算——无需 bc 或 bash 数组。

cat <<EOF | officecli batch "$FILE"
[
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Step1","preset":"roundRect","fill":"1E2761","line":"none","x":"1.5cm","y":"8cm","width":"6cm","height":"3cm","text":"Step 1","font":"Georgia","size":"20","bold":"true","color":"FFFFFF","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Step2","preset":"roundRect","fill":"CADCFC","line":"none","x":"9.79cm","y":"8cm","width":"6cm","height":"3cm","text":"Step 2","font":"Georgia","size":"20","bold":"true","color":"1E2761","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Step3","preset":"roundRect","fill":"1E2761","line":"none","x":"18.08cm","y":"8cm","width":"6cm","height":"3cm","text":"Step 3","font":"Georgia","size":"20","bold":"true","color":"FFFFFF","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Step4","preset":"roundRect","fill":"CADCFC","line":"none","x":"26.37cm","y":"8cm","width":"6cm","height":"3cm","text":"Step 4","font":"Georgia","size":"20","bold":"true","color":"1E2761","align":"center","valign":"middle"}}
]
EOF

# Connector pattern — reuse for any box-to-box graph.
for pair in "Step1 Step2" "Step2 Step3" "Step3 Step4"; do
  A=${pair% *}; B=${pair#* }
  officecli add "$FILE" "/slide[$SLIDE]" --type connector \
    --prop "from=/slide[$SLIDE]/shape[@name=$A]" \
    --prop "to=/slide[$SLIDE]/shape[@name=$B]" \
    --prop shape=elbow --prop color=333333 --prop tailEnd=triangle
done

shape=elbow 是标准写法（也接受 bentConnector2／bentConnector3）。

(d) 多页幻灯片演示文稿骨架

无代码块——这是关于节奏的安排。以下序列是一种可行节奏的示例（深色分隔页与白色内容页交替），并非必需的页面顺序——先根据内容设计实际叙事脉络（参见「先确定标题序列」），再借鉴合适的分隔页／内容页节奏：

• 10 页回顾演示文稿： 封面 · 议程 · 3 个 KPI · 分隔页 01 · 图表 · 图表 · 分隔页 02 · 流程图 · 时间线 · 结束页
• 20 页路演演示文稿： 相同节奏 × 2，分为问题 · 解决方案 · 市场 · 产品 · 业绩 · 商业模式 · 团队 · 财务 · 融资诉求
• 每个分隔页都必须位于相应章节内容之前（门槛 3：顺序检查）
• 封面／分隔页 = (a)；图表页 = (b)；流程页 = (c)；KPI 页 = (e)；决策页 = (f)

(e) KPI 数据标注——巨型数字卡片网格

视觉效果。 一行排列三个或四个巨型数字；每张卡片包含单位副标签、小型百分比变化标签，以及一行摘要。这是高管演示文稿中最常见的元素。

尺寸规则。 60pt Georgia 粗体在宽 9.78cm 的卡片中可容纳约 5 个字符（$84.2、118%、24.5）。对于较长的值（$84.2M），请拆分：将 $84.2 作为大数字，USD millions 作为副标签——不要为了显示单位后缀而缩小字体，否则只会导致换行。

网格计算（3 张卡片，边距 1.5cm，间距 0.76cm）：col_width = (33.87 − 3 − 1.52) / 3 = 9.78cm。x 坐标：1.5, 12.04, 22.58。仅在一张「关注」卡片上使用强调色，让风险一目了然。

# Two cards: navy standard + terracotta watch. Each = bg + big number + sublabel + chip.
cat <<EOF | officecli batch "$FILE"
[
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"preset":"roundRect","fill":"1E2761","line":"none","x":"1.5cm","y":"4cm","width":"9.78cm","height":"7cm"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"84.2","x":"1.5cm","y":"4.8cm","width":"9.78cm","height":"2.8cm","font":"Georgia","size":"60","bold":"true","color":"FFFFFF","align":"center"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"USD millions · ARR","x":"1.5cm","y":"8cm","width":"9.78cm","height":"0.8cm","font":"Calibri","size":"14","color":"CADCFC","align":"center"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"+24% YoY","x":"1.5cm","y":"9cm","width":"9.78cm","height":"0.8cm","font":"Calibri","size":"14","bold":"true","color":"CADCFC","align":"center"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"preset":"roundRect","fill":"B85042","line":"none","x":"22.58cm","y":"4cm","width":"9.78cm","height":"7cm"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"\$1.42","x":"22.58cm","y":"4.8cm","width":"9.78cm","height":"2.8cm","font":"Georgia","size":"60","bold":"true","color":"FFFFFF","align":"center"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"CAC payback (yrs)","x":"22.58cm","y":"8cm","width":"9.78cm","height":"0.8cm","font":"Calibri","size":"14","color":"FFFFFF","align":"center"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"+8% — watch","x":"22.58cm","y":"9cm","width":"9.78cm","height":"0.8cm","font":"Calibri","size":"14","bold":"true","color":"FFFFFF","align":"center"}}
]
EOF

(f) 决策树——是／否分支

视觉效果。 顶部居中的菱形；「是」／「否」子方框分别向左右分开；两条分支最终汇合至同一个终点方框。布局：菱形位于 x=13.94, y=2cm，尺寸为 6×3cm；「是」位于 3cm, 7.5cm；「否」位于 22.87cm, 7.5cm；终点位于 13.94cm, 13cm。惯例：红色 = 停止／升级处理，蓝色 = 标准流程，绿色 = 安全终点。每条连接线都必须有箭头——否则读者容易误判方向。

cat <<EOF | officecli batch "$FILE"
[
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Decide","preset":"diamond","fill":"1E2761","line":"none","x":"13.94cm","y":"2cm","width":"6cm","height":"3cm","text":"Hazardous energy present?","font":"Calibri","size":"14","bold":"true","color":"FFFFFF","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"YesBox","preset":"roundRect","fill":"B85042","line":"none","x":"3cm","y":"7.5cm","width":"8cm","height":"3cm","text":"Lockout + Tagout + Verify","font":"Calibri","size":"16","bold":"true","color":"FFFFFF","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"NoBox","preset":"roundRect","fill":"CADCFC","line":"none","x":"22.87cm","y":"7.5cm","width":"8cm","height":"3cm","text":"Proceed with standard PPE","font":"Calibri","size":"16","bold":"true","color":"1E2761","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Done","preset":"roundRect","fill":"2C5F2D","line":"none","x":"13.94cm","y":"13cm","width":"6cm","height":"2.5cm","text":"Begin service","font":"Calibri","size":"16","bold":"true","color":"FFFFFF","align":"center","valign":"middle"}}
]
EOF

然后使用 (c) 中的连接线循环模式添加 4 条连接线（Decide→YesBox、Decide→NoBox、YesBox→Done、NoBox→Done）。

QA（必需）

假设一定存在问题。 首次渲染几乎从来都不正确。如果你发现了零个问题，那就是看得还不够仔细。

交付检查门（任何一项失败 = 拒绝，不要交付）

检查门 1–2b 属于文本／架构级检查（无法查看渲染后的幻灯片）；检查门 3 是唯一的视觉检查。只有所有检查门都通过，且检查门 3 的循环已收敛，才算完成。

每项检查都是运行命令并判断其输出——所有操作系统（macOS / Linux / Windows）上的 officecli 命令完全相同，因此无需编写 shell 脚本；是否通过由你判断。

• 检查门 1 — 架构。 officecli validate "<file>"。任何架构错误 → 拒绝并修复。
• 检查门 2 — 溢出／格式／结构。 officecli view "<file>" issues。如果列出任何问题（带有 [O1]、[C1]、[S1] 等标签的行）→ 拒绝，修复后重新运行，直到没有问题。
• 检查门 2b — 遗留占位符。 officecli view "<file>" text，然后扫描输出，查找 xxxx、lorem / ipsum、<TODO>、placeholder、"this slide layout" 或空的 () / []。任何匹配项 → 拒绝。

Gate 3 — 视觉审查（MANDATORY）

选择一种路径：

截图（默认） — 适用于具备视觉能力的 Agent。依次为每张幻灯片截图 — officecli view "<file>" screenshot --page 1 -o slide1.png，然后是 --page 2、…… — 直到页索引超出整套幻灯片的范围（每张截图对应一张幻灯片）。如果第 1 页报错，请使用下面的备用方案。

对照清单逐一严格审查每张 PNG — “假定存在问题；如果什么都没发现，说明你看得还不够仔细。” 每个问题报告一行 slide N: <issue>，没有问题则报告 PASS。无论运行方式如何，此步骤都是必需的。如果你的运行环境可以启动子 Agent，请将审查委派给一个全新、独立的 Agent — 制作幻灯片的 Agent 会倾向于认为“看起来没问题”，另一个审查者会更加严格 — 将截图和此清单交给它，并采用同样的严格审查方式。没有子 Agent？请自己进行完全相同的审查。

备用方案 — HTML 文本（不具备视觉能力，或截图失败）：将 view "$FILE" html 作为文本读取。DOM 无法证明深色背景上的深色元素／细微重叠／箭头／间距和页边距指标／列对齐 — 请将这些标记为“未进行视觉验证”，而不是 PASS。

可选 --grid N — 仅在用户要求检查布局节奏，或 view outline 显示布局分布异常时使用：officecli view "<file>" screenshot --grid 3 -o grid.png。

逐页检查清单（假定存在问题）：

• 重叠 — 形状／图表／大型装饰数字（01/02/03，100pt+）相互碰撞
• 文本溢出 — 超出幻灯片或形状边界而被裁切（KPI 卡片、窄文本框）
• 文本框过窄 — 内容虽然勉强放得下，但被拆成许多很短的行（每行 1–2 个词）；3cm KPI 卡片中的长副标签、过窄列中的正文行
• 深色背景上的深色元素 — 填充亮度 < 30%，且文字／图标亮度 < 80%（包括深色图标在深色背景上且没有对比色圆形底的情况）
• 图片处理 — 照片拉伸／变形、文字直接置于杂乱图片上（无卡片／遮罩）、截图或徽标被裁切、透明图片浮在白色背景上
• 缺少箭头 — 流程图连接线只是普通线条
• 装饰线／标题不匹配 — 适用于单行标题的强调条，但标题换成了两行（反之亦然）
• 页脚／引文碰撞 — 来源行、页码或脚注与上方内容相接
• 页边距／间距过紧 — 元素距离幻灯片边缘约 0.5" 以内，或两张卡片间距约 0.3" 以内
• 间距不均 — 一侧大片空白，另一侧拥挤（节奏失衡）
• 列／重复元素未对齐 — KPI 卡片／图标基线不齐或宽度不一致
• 顺序合理性 — 顺序是否符合叙事（封面 → 议程 → 章节分隔页置于章节之前 → 结束页）

有问题则以 slide N: <issue> 拒绝，否则报告“Gate 3 PASS”（使用 HTML 文本备用方案时，需加上“ 未进行视觉验证”）。

修复与验证（必需，最多 3 轮）。 修复 → 重新运行 Gate 3 → 重复，直到没有新问题；一次修复往往会暴露另一个问题。若 3 轮后仍未收敛，请停止 — 这可能是反复调整、模板层面的问题，或 Agent 误读所致。报告 slide N: <issue> — attempted: <fixes> — likely root: <template|design-conflict|ambiguous>，交由用户决定。

然后刷新（此环节也是检查的一部分）。 Gate 3 收敛后，最后运行 officecli save "<file>" — 这可确保交付前已将修改写入磁盘（如需在一次性移交中同时释放常驻进程，请改用 officecli close "<file>"）。这是必需的最后一步，不可省略。始终安全：不会报错或丢失工作。

常见陷阱

快速检查备忘单——初次尝试时容易出错的地方。设计和 shell 陷阱。

陷阱	正确做法
在 zsh/bash 中未加引号的 [N]	始终给路径加引号："/slide[1]"。zsh 会将未加引号的 [1] 作为 glob 模式处理，导致 no matches found——这是初次使用时最常遇到的问题
--name "foo"	所有属性都通过 --prop 指定：--prop name="foo"
/shape[myname]（方括号中直接写名称）	使用 @name= 选择器：/shape[@name=myname] 或 /shape[@id=10007]
路径索引从 1 开始，而 --index 从 0 开始	/slide[1] = 第一张幻灯片；--index 0 = 第一个位置
--prop text= 中的 $	使用单引号：--prop text='$15M'。双引号括起的 "$15M" 会被 shell 展开为 M
--prop text= 中的 \n / \t	由 CLI 解释：\n = 段落换行，\t = 制表符。要表示字面量，请使用双反斜杠 \\n