• CLI
• AI 应用
• MCP 服务

这篇指南以仓库中的实战示例 textboxes-basic.md 为骨架，完整拆解如何用 OfficeCLI 通过officecli add/set命令在 PowerPoint 幻灯片中构建四种典型文本框场景：水平对齐、多段落与项目符号/编号列表、单段落内的富文本 run（加粗/斜体/下划线/删除线/上下标）、以及多脚本字体（Latin + East Asian）与垂直对齐/内边距排版。读完你不仅能逐条复现 4 页示例幻灯片，还能理解textbox/paragraph/run三种元素类型在 OOXML 中的对应关系，掌握list、level、valign、margin、font.latin/font.ea等关键属性的取值与底层写入行为，并学会用query/get逆向检查生成结果。

一、示例三件套与运行环境

本示例由三个文件协同构成，均位于 examples/ppt/textboxes：

• textboxes-basic.sh— Shell 脚本，逐条调用officecliCLI 命令构建整套 4 页演示文稿；
• textboxes-basic.py— 与 Shell 等价的 Python SDK 版本（officecli-sdk），通过一次doc.batch(...)批量往返生成同一份文件；
• textboxes-basic.md— 文档（即本文骨架），将每页幻灯片映射到它演示的特性；
• textboxes-basic.pptx— 生成产物：4 页幻灯片，覆盖对齐、多段落列表、样式化 run、多语言字体与布局。

重新生成演示文稿只需两步：

cd examples/ppt bash textboxes/textboxes-basic.sh # → textboxes/textboxes-basic.pptx

在运行之前，先确认officecli命令已在 PATH 中。仓库根目录提供了跨平台安装脚本：install.sh（macOS/Linux）、install.ps1（Windows PowerShell），以及面向开发者的 dev-install.sh；本地源码构建入口为 officecli.csproj（dotnet build后使用src/officecli/bin/...下的二进制）。安装完成后用officecli --version验证版本。

值得留意的是：textboxes-basic.sh 刻意没有set -e。与 Python SDK 版本的doc.batch一样，脚本对 "UNSUPPORTED props" 这类前向兼容警告（退出码 2）保持容忍，继续构建直至产出完整文档。这一点对阅读脚本输出很有用——看到警告不一定意味着失败。

二、Slide 1 — 水平对齐（align）

第一页的核心问题是：同一段长文本，在四个文本框中分别以left/center/right/justify四种对齐方式呈现，形成直观对比。

officecli create textboxes-basic.pptx officecli open textboxes-basic.pptx officecli add textboxes-basic.pptx / --type slide LOREM='Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus lacinia odio vitae vestibulum vestibulum.' # align=left (default) officecli add textboxes-basic.pptx '/slide[1]' --type textbox \ --prop x=0.5in --prop y=1.3in --prop width=12in --prop height=1.3in \ --prop fill=F1FAEE --prop text="[align=left] $LOREM" --prop size=14 \ --prop align=left # align=center officecli add textboxes-basic.pptx '/slide[1]' --type textbox \ --prop x=0.5in --prop y=2.8in --prop width=12in --prop height=1.3in \ --prop fill=F1FAEE --prop text="[align=center] $LOREM" --prop size=14 \ --prop align=center # align=right officecli add textboxes-basic.pptx '/slide[1]' --type textbox \ --prop x=0.5in --prop y=4.3in --prop width=12in --prop height=1.3in \ --prop fill=F1FAEE --prop text="[align=right] $LOREM" --prop size=14 \ --prop align=right # align=justify officecli add textboxes-basic.pptx '/slide[1]' --type textbox \ --prop x=0.5in --prop y=5.8in --prop width=12in --prop height=1.3in \ --prop fill=F1FAEE --prop text="[align=justify] $LOREM" --prop size=14 \ --prop align=justify

本页特性：--type textbox（shape的别名——在 OOXML 中二者都是文本框）、align（left、center、right、justify）、fill、text、size、x/y/width/height。

从源码看--type textbox的别名语义

在 PowerPointHandler.Add.cs 中可以看到分派逻辑：

"shape" or "textbox" when properties != null && properties.ContainsKey("formula") => AddEquation(...), ... "shape" or "textbox" => AddShape(parentPath, index, properties ?? new(), type.ToLowerInvariant()),

即textbox与shape走的是同一条AddShape路径（带formula属性时二者同样会转向AddEquation生成公式形状）。进一步在 PowerPointHandler.Add.Shape.cs 中，elementTypeHint == "textbox"被用来确定生成的是文本框风格（无几何预设、默认矩形正文）还是真正的图形形状。这也解释了 schema 中 textbox.json 的注记："Alias for shape — both route to AddShape"，且其路径映射为/slide[N]/shape[M]——也就是说，即使你写--type textbox，后续寻址依然通过/slide[N]/shape[1]进行。

属性速查（来自 textbox.json）

注意size、bold、color在 textbox 层级是"写直达、读绕行"：写入时作用于第一个 run 的字符属性，读取时请使用effective.size、effective.color、effective.bold（继承自 placeholder→layout→master→presentation 默认值，设置后即被显式值抑制）。

三、Slide 2 — 多段落 + 项目符号 / 编号列表

第二页演示"先搭段落、再整体套用列表样式"的经典模式：左侧是咖啡冲煮步骤的项目符号列表，右侧是发布检查清单的编号列表，外加一条通过level=1缩进一层级的子项。

officecli add textboxes-basic.pptx / --type slide # 项目符号列表 —— 先添加标题段落，再追加正文段落， # 最后用 set 以 list=bullet 把全部段落变成项目符号。 officecli add textboxes-basic.pptx '/slide[2]' --type textbox \ --prop x=0.5in --prop y=1.2in --prop width=6in --prop height=4in \ --prop text="Coffee preparation steps" \ --prop bold=true --prop size=18 --prop color=1D3557 officecli add textboxes-basic.pptx '/slide[2]/shape[1]' --type paragraph \ --prop text="Grind beans to medium-fine" officecli add textboxes-basic.pptx '/slide[2]/shape[1]' --type paragraph \ --prop text="Heat water to 93°C" officecli add textboxes-basic.pptx '/slide[2]/shape[1]' --type paragraph \ --prop text="Bloom 30s with 2× coffee weight" officecli add textboxes-basic.pptx '/slide[2]/shape[1]' --type paragraph \ --prop text="Pour remaining water in spirals" officecli add textboxes-basic.pptx '/slide[2]/shape[1]' --type paragraph \ --prop text="Total brew time: 3-4 minutes" # 在 shape 层级把全部段落变为项目符号 officecli set textboxes-basic.pptx '/slide[2]/shape[1]' --prop list=bullet # 编号列表 —— 同样的模式 officecli add textboxes-basic.pptx '/slide[2]' --type textbox \ --prop x=7in --prop y=1.2in --prop width=6in --prop height=4in \ --prop text="Release checklist" \ --prop bold=true --prop size=18 --prop color=1D3557 officecli add textboxes-basic.pptx '/slide[2]/shape[2]' --type paragraph \ --prop text="Run tests" officecli add textboxes-basic.pptx '/slide[2]/shape[2]' --type paragraph \ --prop text="Tag the release" officecli add textboxes-basic.pptx '/slide[2]/shape[2]' --type paragraph \ --prop text="Push to registry" officecli add textboxes-basic.pptx '/slide[2]/shape[2]' --type paragraph \ --prop text="Announce in #releases" officecli set textboxes-basic.pptx '/slide[2]/shape[2]' --prop list=numbered # 子项：level=1 将步骤嵌套一级 officecli add textboxes-basic.pptx '/slide[2]/shape[2]' --type paragraph \ --prop text="(verify checksum)" --prop level=1 officecli set textboxes-basic.pptx '/slide[2]/shape[2]' --prop list=numbered

本页特性：--type paragraph（向父 shape 追加一个段落）、list（bullet、numbered—— 通过set在 shape 层级应用）、level（缩进深度；0 = 顶层，1 = 缩进一级，以此类推）。

paragraph 的类型语义

根据 paragraph.json，--type paragraph向 shape 的 TextBody 追加一个a:p元素，路径为/slide[N]/shape[M]/p[K]，支持别名p、para。其常用属性：

• align：同上四种取值，别名alignment/halign；
• level：列表缩进级别 0–8（a:pPr/@lvl）；
• list：段落项目符号样式，命名预设bullet、dash、arrow、check、star、none，也接受字面项目符号字符；numbered/alpha/roman等映射到自动编号方案（别名bullet）；
• bold/italic/color/size/lang：段落级默认 run 属性，写入defRPr（CT_TextCharacterProperties），被段落内未显式覆盖的 run 继承；当所有 run 取值一致时，dump 会将其"折叠"到段落层。

需要理解的关键点是：list既可以像示例那样通过set在shape 层级一次应用到该 shape 的所有段落，也可以在paragraph 层级单独设置——示例先用add --type paragraph铺好段落文本，再set --prop list=...统一套样式，比逐段设置更紧凑，且能精确控制"哪几个段落变列表、哪个段落保持普通标题"。

四、Slide 3 — 样式化 Run（富文本）

第三页演示单个段落内部按 run 粒度混合样式：第一块是 "The quick brown fox…" 的经典字体样式演示，第二块用baseline=super/sub输出 E=mc² 与 H₂O 的上下标，第三块则是删除线 + 强调色的价格划线对比。

officecli add textboxes-basic.pptx / --type slide # 空文本框 —— 通过 --type run 逐 run 填充 officecli add textboxes-basic.pptx '/slide[3]' --type textbox \ --prop x=0.5in --prop y=1.5in --prop width=12in --prop height=1in \ --prop text="" --prop size=20 # 向段落 [1] 追加不同样式的 run officecli add textboxes-basic.pptx '/slide[3]/shape[1]/p[1]' --type run \ --prop text="The " officecli add textboxes-basic.pptx '/slide[3]/shape[1]/p[1]' --type run \ --prop text="quick " --prop bold=true --prop color=E63946 officecli add textboxes-basic.pptx '/slide[3]/shape[1]/p[1]' --type run \ --prop text="brown " --prop italic=true --prop color=A0522D officecli add textboxes-basic.pptx '/slide[3]/shape[1]/p[1]' --type run \ --prop text="fox jumps over the " officecli add textboxes-basic.pptx '/slide[3]/shape[1]/p[1]' --type run \ --prop text="lazy " --prop underline=single --prop color=2A9D8F officecli add textboxes-basic.pptx '/slide[3]/shape[1]/p[1]' --type run \ --prop text="dog." # 上下标 —— 通过 baseline=（也接受 baseline=super/sub） officecli add textboxes-basic.pptx '/slide[3]' --type textbox \ --prop x=0.5in --prop y=3in --prop width=12in --prop height=0.8in \ --prop text="" --prop size=24 officecli add textboxes-basic.pptx '/slide[3]/shape[2]/p[1]' --type run \ --prop text="E = mc" officecli add textboxes-basic.pptx '/slide[3]/shape[2]/p[1]' --type run \ --prop text="2" --prop baseline=super officecli add textboxes-basic.pptx '/slide[3]/shape[2]/p[1]' --type run \ --prop text=" and H" officecli add textboxes-basic.pptx '/slide[3]/shape[2]/p[1]' --type run \ --prop text="2" --prop baseline=sub officecli add textboxes-basic.pptx '/slide[3]/shape[2]/p[1]' --type run \ --prop text="O" # 同一段落内 删除线 + 字号覆盖 officecli add textboxes-basic.pptx '/slide[3]' --type textbox \ --prop x=0.5in --prop y=4.2in --prop width=12in --prop height=0.8in \ --prop text="" --prop size=20 officecli add textboxes-basic.pptx '/slide[3]/shape[3]/p[1]' --type run \ --prop text="OLD PRICE: \$99 " --prop strike=single --prop color=999999 officecli add textboxes-basic.pptx '/slide[3]/shape[3]/p[1]' --type run \ --prop text="NOW \$49!" --prop bold=true --prop color=E63946 --prop size=24

本页特性：--type run（向父p[N]段落追加 run）、bold、italic、underline（single、double 等）、strike（single、double）、color（hex）、size（pt）、baseline（super、sub 或带符号的整数百分比）。

run 的路径与扩展属性

根据 run.json，--type run在a:p内部追加a:r，路径为/slide[N]/shape[M]/p[K]/r[L]（别名r），字体属性落在a:rPr上。文档中值得注意的扩展点：

• baseline：以字体高度的百分比表示垂直偏移，接受super（等价 +30）、sub（等价 −25）、none/false/0，或带符号数字如--prop baseline=-25；readback 为带%后缀的百分比（如"30%"、"-25%"）。另有subscript=true/superscript=true两个布尔语法糖，读取时统一规范化为baseline。
• 按字符区间格式化：set <shape-or-paragraph-path> --prop range=START:END --prop bold=true可将样式只应用到指定字符区间（0 基、半开区间），支持多段区间如range=6:11,20:25；find（按文本定位）与range（按偏移定位）在同一调用中互斥。
• 更多 run 级属性：highlight（字符背景高亮，任意颜色）、kern（字距调整起始字号，1/100 pt）、spacing/charspacing（字符间距 pt，负值收紧）、cap（none/small/all，别名allCaps/smallCaps）、textOutline[.width/.color]（字形描边）、lang（BCP-47 标签，别名lang.latin，但lang.ea/lang.cs在 DrawingML 中被拒绝——PPT 只有一个主语言槽，与 Word 不同）。

命令转义提醒（源自 officecli-pptx SKILL）

示例中价格文本写作\$99正是为了应对shell 层的展开：双引号内的"$99"会被 bash 当作变量展开，$9展开为空导致文本变为99。所以包含$的文本要么整体单引号（--prop text='$15M'），要么在双引号内写\$。另外 CLI 会解释\n（段落/换行）与\t（制表符）两字符转义，若要输出字面\n需写成\\n。

五、Slide 4 — 多语言字体 + 垂直对齐 + 内边距

第四页处理多语言排版的三件套：按脚本分槽选字体（Latin 与 East Asian 分开）、高文本框内的垂直对齐、以及正文内边距。

officecli add textboxes-basic.pptx / --type slide # 混合脚本文本框：font.latin 用于拉丁字符，font.ea 用于东亚字符 officecli add textboxes-basic.pptx '/slide[4]' --type textbox \ --prop x=0.5in --prop y=1.5in --prop width=6in --prop height=2in \ --prop fill=F1FAEE --prop margin=0.2in \ --prop text="Hello, 世界! こんにちは、世界。" \ --prop size=24 --prop bold=true \ --prop font.latin="Georgia" --prop font.ea="Yu Mincho" # valign —— 高固定框内文本的垂直位置 # top (default), middle, bottom X=7 for va in top middle bottom; do officecli add textboxes-basic.pptx '/slide[4]' --type textbox \ --prop x="${X}in" --prop y=1.5in --prop width=2in --prop height=3in \ --prop fill=A8DADC --prop margin=0.15in \ --prop text="valign=$va" --prop size=16 --prop bold=true \ --prop valign="$va" --prop align=center X=$(echo "$X + 2.2" | bc -l) done officecli close textboxes-basic.pptx officecli validate textboxes-basic.pptx

本页特性：font.latin（Latin 脚本字体槽）、font.ea（East Asian 脚本字体槽）、valign（top、middle、bottom）、margin（统一内边距；另有marginLeft、marginRight、marginTop、marginBottom）、align=center。

分脚本字体槽（来自 textbox.json）

• font.latin：仅写 Latin 脚本槽（OOXMLa:latin），如--prop font.latin=Calibri；
• font.ea：仅写 East Asian 槽（a:ea），覆盖中文/日文/韩文，别名font.eastasia/font.eastasian；
• font.cs：Complex-script 槽（a:cs），覆盖阿拉伯文/希伯来文/泰文等；
• 裸font：一次性同时设置 Latin 与 East Asian（以及 cs）槽，适合拉丁为主的文本。

run 层的font写入是"写直达、读规范"：--prop font=Calibri会同时铺满 latin/ea/cs 三个槽，读取时则规范化为font.latin/font.ea/font.cs三个键，保证 get→set 往返不丢失槽位差异。这正是示例中混合脚本文本必须用font.latin=Georgia --prop font.ea="Yu Mincho"的原因——同一行内 "Hello," 走 Georgia，"世界" 走 Yu Mincho。

垂直对齐与内边距

• valign：垂直锚定（a:bodyPr/@anchor），取值top/center/middle/bottom，其中middle是center的输入别名，读取统一回读为center。在固定高度（height=3in）的高框内，它是把文字稳定压到顶部/居中/底部的唯一手段。
• margin：正文四边内缩（a:bodyPr的lIns/tIns/rIns/bIns）。单值如margin=0.2in同时作用于四边；也支持 CSS 风格四值形式margin=0.2cm,0.5cm,0.2cm,0.5cm；0/0cm是合法值且会被保留（不会坍缩为默认值）。读取时若四边一致返回单个长度，否则返回逗号分隔的四元组。单边微调则用marginLeft、marginRight、marginTop、marginBottom。

六、完整功能覆盖表

下表汇总四个演示页面与全部涉及的属性（原文档的覆盖表，附属性规范出处）：

七、检查生成结果：query / get 逆向验证

构建完成后，使用query（跨幻灯片搜索）与get（按路径读取单个元素）验证各页状态。这既是回归检查，也是熟悉元素路径层级的好机会——textbox → shape[N] → p[K] → r[L]的嵌套关系一目了然：

# 列出 slide 1 上的所有 shape officecli query textboxes-basic.pptx '/slide[1]/shape' # 读取每个文本框的对齐方式 officecli get textboxes-basic.pptx '/slide[1]/shape[2]' # 检查 slide 2 两个 shape 的列表类型 officecli get textboxes-basic.pptx '/slide[2]/shape[1]' officecli get textboxes-basic.pptx '/slide[2]/shape[2]' # 检查 slide 3 段落 [1] 的全部 run officecli query textboxes-basic.pptx '/slide[3]/shape[1]/p[1]/run' # 读取 slide 4 的 valign 与字体 officecli get textboxes-basic.pptx '/slide[4]/shape[1]' officecli get textboxes-basic.pptx '/slide[4]/shape[3]'

get默认返回元素属性（含effective.*继承解析值），query支持shape:contains("...")、shape[fill=1E2761]、shape[width>=10cm]等 CSS 风格选择器，--json输出机器可读。注意路径中的[N]一律加引号包裹（"/slide[1]"），否则 zsh/bash 会把[1]当作 glob 展开导致no matches found。

八、Python SDK 等价实现：一次 batch 完成全流程

Shell 版本逐条调用 CLI；textboxes-basic.py 则演示了面向 Agent 的高效路径：启动一个常驻进程（resident），把全部 slide/shape/paragraph/run 构建项打包进单个doc.batch(...)往返。每个 item 就是你会放进officecli batch列表的{"command","parent","type","props"}字典，且按顺序应用——后一项可以寻址前一项刚创建的 shape（例如 paragraph 立即指向同批中刚 add 的/slide[2]/shape[1]）。

import officecli # pip install officecli-sdk，或使用仓库内 sdk/python/officecli.py with officecli.create(FILE, "--force") as doc: items = [] items.append({"command": "add", "parent": "/", "type": "slide", "props": {}}) items.append({"command": "add", "parent": "/slide[1]", "type": "textbox", "props": {"text": "Horizontal Alignment", "size": "28", "bold": "true", "x": "0.5in", "y": "0.3in", "width": "12in", "height": "0.6in"}}) # ... 每个 add/set 都以同一字典形状累积 ... items.append({"command": "set", "path": "/slide[2]/shape[1]", "props": {"list": "bullet"}}) doc.batch(items)

Python SDK 的完整实现位于 sdk/python/officecli.py，对应的 Node SDK 见 sdk/node/index.js 与类型声明 sdk/node/index.d.ts；两个 SDK 都附带可独立运行的冒烟测试（sdk/python/smoke.py、sdk/node/smoke.js）。文本元素的分层结构（shape→paragraph→run）在 SDK 与 CLI 之间完全一致，因此 Shell 教程中的任何属性都能原样移植到 batch 字典中。

九、底层实现要点与常见陷阱

OOXML 映射

从源码与 schema 可以确认三个元素类型的底层对应：

• textbox/shape→p:sp（PowerPoint shape），正文在a:txBody，位置/尺寸在a:spPr，正文内边距与垂直锚定在a:bodyPr（见 PowerPointHandler.Add.Shape.cs 的类型分派与 bodyPr 处理）；
• paragraph→a:p（位于 TextBody 内），段落属性在a:pPr（@lvl、@marL/@marR、buChar/buAutoNum等），默认 run 样式在defRPr；
• run→a:r，字符属性在a:rPr（b、i、u、strike、sz、baseline、solidFill、latin/ea/cs字体槽等）。

PptxBatchEmitter（PptxBatchEmitter.Shape.cs）在导出时会把无几何预设的纯文本形状标记为"textbox"、带几何的标记为"shape"，这正是"add 时两者等价、dump/readback 时按形状类别区分"的往返设计。

高频陷阱清单

十、小结：一个可复用的文本构建工作流

把四页示例抽象为通用流程：create → open → add slide → add textbox（位置/尺寸/背景/初值）→ add paragraph（追加段落）→ add run（行内混合样式）→ set（列表/其他属性批量应用）→ close → validate → query/get 复核。再叠加三点心法：

1. 粒度分层：整段一致的样式放 shape/paragraph 级，行内混排放 run 级（或range=区间），避免无谓拆分；
2. 显式排版：OfficeCLI 没有布局引擎，x/y/width/height、valign、margin全部显式指定，这也意味着可以精确复刻任何设计稿；
3. 先 set 后验证：结构操作后用get /slide[N] --depth 1确认 shape ID，交付前用view issues检查溢出、validate检查 schema，必要时用view html做视觉审计。

如果需要在批处理场景（循环网格、多页骨架）复用这些模式，officecli-pptx SKILL 中的batchheredoc 配方（坐标数学内联进 JSON，无需bc/bash 数组）与 textboxes-basic.py 的单次doc.batch都是直接可抄的模板。更多元素（chart、connector、animation、table、zoom）的属性参考可随时通过officecli help pptx <element>查询本机安装版本的权威 schema。

• CLI
• AI 应用
• MCP 服务