用 python-pptx 创建一张带标题、背景色和正文文字的幻灯片，代码大概长这样：

from pptx import Presentation
from pptx.util import Pt
from pptx.dml.color import RGBColor

prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[1])

bg = slide.background.fill
bg.solid()
bg.fore_color.rgb = RGBColor(0x1A, 0x1A, 0x2E)

title = slide.shapes.title
title.text = "Q4 Revenue Report"
run = title.text_frame.paragraphs[0].runs[0]
run.font.size  = Pt(36)
run.font.bold  = True
run.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)

slide.placeholders[1].text = "Revenue grew 25% YoY"
prs.save("report.pptx")

20 行，还没算错误处理和导包。等效的 OfficeCLI 命令：

officecli create report.pptx
officecli add report.pptx / --type slide \
  --prop title="Q4 Revenue Report" --prop background=1A1A2E
officecli add report.pptx '/slide[1]' --type shape \
  --prop text="Revenue grew 25% YoY" \
  --prop x=2cm --prop y=5cm --prop color=FFFFFF --prop size=28 --prop bold=true

3 条命令，跨语言，跨平台，无需理解 pptx 的对象模型。这就是 OfficeCLI 的核心主张：把 Office 文件操作变成和 curl 一样简单的 CLI 调用。

OfficeCLI 是什么

OfficeCLI 是一个专为 AI Agent 设计的 Office 套件，Apache 2.0 开源，发布为单个自包含二进制文件，支持 macOS、Linux 和 Windows。不需要安装 Microsoft Office，不需要 .NET 运行时，下载即用。

它统一覆盖三种格式：Word（.docx）支持段落、表格、图片、目录、批注、脚注、水印、公式；Excel（.xlsx）内置 150+ 函数自动计算、透视表、条件格式、图表；PowerPoint（.pptx）支持幻灯片、形状、动画、3D 模型、切换效果、连接符。

所有操作通过统一路径寻址访问文档元素，例如 /slide[1]/shape[2] 指向第 1 张幻灯片的第 2 个形状。每个命令都支持 --json 输出，错误也以结构化 JSON 返回，包含错误码和修复建议，方便 Agent 自动重试。

内置渲染引擎是 OfficeCLI 对比其他工具最显著的差异：view html 生成自包含 HTML，view screenshot 输出 PNG，watch 启动本地 HTTP 服务并在每次修改后自动刷新浏览器。在 Docker 容器或无显示器的 CI 服务器里，也能看到文档的实际渲染结果。

场景一：让 AI Agent 直接生成并检查文档

OfficeCLI 内置 MCP Server，一行命令注册到 Claude Code、Cursor 或 VS Code：

officecli mcp claude   # 注册到 Claude Code
officecli mcp cursor   # 注册到 Cursor
officecli mcp vscode   # 注册到 VS Code

注册之后，AI Agent 可以直接通过 MCP 协议调用 officecli 的所有操作，不需要 shell 权限，JSON 输出确定性强。更关键的是"看"的能力，Agent 生成幻灯片后，可以调用 view screenshot 拿到 PNG，通过多模态能力检查标题是否溢出、形状是否重叠、对比度是否足够，然后自动修正：

# Agent 生成后，截图确认视觉效果
officecli view deck.pptx screenshot -o /tmp/slide1.png --page 1

# 发现标题溢出，缩小字号后重新确认
officecli set deck.pptx '/slide[1]/shape[1]' --prop size=20
officecli view deck.pptx screenshot -o /tmp/slide1v2.png --page 1

这个"生成 → 渲染 → 检查 → 修正"闭环在纯 python-pptx 方案里完全缺失。Agent 写完代码之后是真的在盲飞，不打开 PowerPoint 根本不知道幻灯片长什么样。

场景二：批量生成文档，模板只设计一次

从数据库或 API 拿数据，批量生成同格式的 Word/Excel/PPT 文档，这是 OfficeCLI 最典型的工程应用。Template merge 功能是核心：用 {{key}} 占位符设计一次模板，然后批量填充 JSON 数据。

# 模板一次设计，批量生成 N 份客户报告
for file in clients/*.json; do
    id=$(jq -r .id "$file")
    officecli merge report-template.pptx "report-${id}.pptx" "$file"
done

模板只需 AI 生成一次，之后的批量渲染是确定性的，零 token 消耗。这避免了两个常见问题：重复消耗 token，以及每次生成格式微妙不一致。

多步骤操作可以用批量模式，在一次文件 open/save 中执行多个命令，大幅减少 I/O 开销：

echo '[
  {"command":"set","path":"/slide[1]/shape[1]","props":{"text":"2025 Q4"}},
  {"command":"set","path":"/slide[1]/shape[2]","props":{"text":"营收 $4.2M"}},
  {"command":"set","path":"/slide[2]/shape[1]","props":{"fill":"0d47a1"}}
]' | officecli batch report.pptx --json

从 Python 调用也很直接。封装一次，之后每个操作都能直接拿到解析好的 JSON：

import json, subprocess

def cli(*args):
    return json.loads(
        subprocess.check_output(["officecli", *args, "--json"], text=True)
    )

cli("create", "deck.pptx")
cli("add", "deck.pptx", "/", "--type", "slide", "--prop", "title=Q4 Report")
slide = cli("get", "deck.pptx", "/slide[1]")

场景三：在 CI/CD 中自动校验文档质量

在发布合同、法律文件、合规报告之前，OfficeCLI 可以作为流水线中的一道自动校验门。validate 检查 OpenXML 结构合规性，view issues 检测内容层面的问题，包括文字溢出、缺失 alt text、公式错误等。

# CI 校验脚本
officecli validate contract.docx || exit 1

issues=$(officecli view contract.docx issues --json)
errors=$(echo "$issues" | jq '[.[] | select(.severity=="error")] | length')

if [ "$errors" -gt 0 ]; then
    echo "文档存在 ${errors} 个错误，阻断发布" && exit 1
fi

结构化 JSON 输出方便接入任何 CI 系统，问题按严重程度分级，文档进入发布流程之前自动拦截。

和主流工具的对比

文档自动化领域的主流选项有三类：Python 库（python-pptx、python-docx、openpyxl）、LibreOffice headless 和 Microsoft Office COM 自动化。

python-pptx 系成熟稳定，社区资源丰富，但有几个共性问题难以绕过：语言绑定死，非 Python 技术栈无法直接用；三种格式需要三个库，API 设计不统一；没有渲染引擎，无法在不安装 Office 的环境里验证视觉结果；对 AI Agent 不友好，输出不是 JSON，错误信息不结构化。它有一个细节优势：对 slide master/layout 的继承关系处理比 OfficeCLI 更完整，可以拿到"主题继承后的实际字体颜色"这类值。

LibreOffice headless 常用于服务端文件格式转换。缺点是体积大（300MB 以上），启动慢，UNO API 学习曲线陡，容器化部署容易遇到字体和渲染环境问题，对 AI Agent 几乎没有原生集成。

Microsoft Office COM 通过 Windows COM 接口调用 Office 应用，渲染结果和手动操作完全一致，但只能在 Windows 上运行，需要 Office License，不能无头运行，速度慢，稳定性依赖 Office 进程，完全不适合 Linux 服务器或容器环境。

维度	OfficeCLI	python-pptx 系	LibreOffice	MS Office COM
无需安装 Office	是	是	是	否
三格式统一 API	是	否（3 个库）	是	是
内置渲染引擎	是	否	部分	是
语言无关	是（CLI）	否（Python only）	否（UNO）	否（COM/Win）
AI Agent / MCP 支持	是	否	否	否
容器 / CI 环境	是	是	复杂	否
JSON 结构化输出	是	否	否	否
slide master 继承	部分	完整	完整	完整

什么时候不适合用 OfficeCLI

如果核心需求是从存量文档里提取结构化数据接入 Python 数据管道（pandas、数据库写入、特征提取），python-pptx 和 openpyxl 更合适。它们直接在进程内拿到 Python 对象，无子进程开销，批量处理几千个文件也没有性能问题。

如果需要精细控制 slide master 和 theme 的继承关系，比如"这个文字框在当前 layout 下实际应用的字体是什么"，python-pptx 的对象模型对这套继承关系有完整实现，OfficeCLI 在这个层次的支持还不够深。

如果项目里已有成熟稳定的 python-pptx 代码库，覆盖了大量边缘情况，迁移到 OfficeCLI 的成本不一定值得。OfficeCLI 目前只支持 .docx、.xlsx、.pptx 三种现代格式，如果需要处理旧格式（.doc、.xls、.ppt），需要先做格式转换。

---

文档自动化的历史大致分两个阶段：手写 Python 操作 XML 对象树的时代，以及让 AI Agent 直接理解需求并自动产出文档的时代。OfficeCLI 站在两个时代的交汇处，一边对已有工程流水线友好，一边为 AI 原生工作流提供完整支撑。

文档自动化的终点，不是写出更优雅的 Python，而是根本不需要写 Python。

---

我是 Yuguo，软件设计师，正在用 AI 重构自己的开发工作流。
踩过的坑、跑通的方案、省下来的时间，都记在绿泡泡 Feed 中。 一起把 AI 真正用起来。