Github分享:OfficeCLI一行命令操作Office

现在让 AI 生成一份 PPT，并不难。难的是下一步：标题溢出了，它能不能看见；第三页数据错了，它能不能精确改掉；改完以后，它能不能证明文件仍然可用。

OfficeCLI 补上的正是这段「最后一公里」。Word、Excel、PowerPoint 被统一成一套可读取、可定位、可修改、可渲染、可校验的命令，聊天界面只负责下达任务。

我的判断很直接：想让 AI 稳定处理 Office 文件，关键在于执行结果可检查、错误可恢复、操作可复现。只会生成，离可靠交付还差一截。

1 工具定位

OfficeCLI 支持 .docx、.xlsx、.pptx 的创建、读取与修改，不要求机器上安装 Microsoft Office。官方仓库采用 Apache License 2.0，提供 Windows、macOS 和 Linux 版本。

它最适合三类任务：让智能体生成并迭代文档；从现有 Office 文件提取结构化数据；在 CI、容器或服务器中批量生产和检查文档。

理解这套工具，可以把它拆成三层：

Skills 更像一份写给智能体看的操作手册，不会直接修改 Office 文件。具体操作仍由 OfficeCLI 二进制程序执行。

上图来自 OfficeCLI 官方仓库。左侧是智能体的执行过程，右侧是生成中的文档与预览。每一步文件操作都能被看到和追踪，这才是图里的重点。

2 安装与验证

OfficeCLI 是单一可执行文件。官方给了多种安装入口，我更建议优先使用自己熟悉的包管理器；团队环境则应固定版本并保留安装记录。

2.1 Windows

PowerShell：

# 方式一：Scoop scoop install officecli  # 方式二：官方安装脚本 irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex

2.2 macOS 与 Linux

Bash：

# Homebrew brew install officecli  # 或使用官方安装脚本 curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash

2.3 全平台 npm

终端：

npm install -g @officecli/officecli

也可以前往 GitHub Releases 手动下载对应架构的二进制文件。Windows 区分 x64 与 ARM64；macOS 区分 Apple Silicon 与 Intel；Linux 同样提供 x64 与 ARM64。

无论用哪种方式，安装后都先跑两条命令：

终端：

officecli --version officecli install

第一条确认 PATH 是否生效；第二条会执行自安装，并尝试把技能文件安装到检测到的 AI 编程助手。

这里有一个安全细节：curl | bash 与 irm | iex 会直接执行远程脚本。个人测试很省事，但在企业电脑、生产机或受控网络中，应该先下载并检查脚本，或者改用包管理器与 Releases 手动安装。

3 接入 Skills 与 MCP

最省事的路径，是在 AI 智能体的对话框中提供官方技能文件地址：

终端或智能体对话框：

curl -fsSL https://officecli.ai/SKILL.md

官方说明中，officecli install 还会检测 Claude Code、Cursor、Windsurf、GitHub Copilot 等工具，并尝试自动安装技能文件。自动检测没覆盖到你的环境时，再把 SKILL.md 放入对应工具的 Skills 目录即可。

如果你的 AI 工具支持 MCP（Model Context Protocol，模型上下文协议），还可以直接注册内置服务器：

终端：

officecli mcp claude officecli mcp cursor officecli mcp vscode officecli mcp lmstudio officecli mcp list

CLI 与 MCP 不需要二选一。CLI 适合脚本、CI 和透明的命令记录；MCP 适合不方便开放 Shell 的智能体环境。Skills 则告诉模型该在什么时候调用哪个能力。

4 跑通第一份 PPT

下面这组命令足够把核心工作流跑一遍。建议开两个终端：一个负责实时预览，另一个负责修改文件。

终端 A：

# 创建空白演示文稿 officecli create deck.pptx  # 启动预览，浏览器会打开 http://localhost:26315 officecli watch deck.pptx

终端 B：

# 添加第一页，并设置标题和背景色 officecli add deck.pptx / --type slide \   --prop title="Q4 Report" --prop background=1A1A2E  # 在第一页添加文本框 officecli add deck.pptx '/slide[1]' --type shape \   --prop text="Revenue grew 25%" \   --prop x=2cm --prop y=5cm \   --prop font=Arial --prop size=24 --prop color=FFFFFF

/slide[1] 是稳定路径，表示第一张幻灯片。OfficeCLI 使用从 1 开始的索引，这套路径语法不是 XPath。对智能体而言，稳定路径比“找到页面上差不多位于左上角的文字”可靠得多。

接着检查大纲和元素：

终端：

officecli view deck.pptx outline officecli get deck.pptx '/slide[1]/shape[1]' --json

view outline 给人看，get --json 更适合程序和智能体读取。后者会返回元素路径、名称、文本、位置等结构化字段，避免再用正则从终端文本里猜结果。

图源：OfficeCLI 官方仓库。官方展示里包含多种 PPT 风格，但复杂版式仍建议通过 watch 或截图做人工终审，尤其要看文字溢出、遮挡、对齐和字体替换。

5 Word 与 Excel 实操

PowerPoint 跑通后，Word 和 Excel 的思路没有变化：先建立文件，再通过路径找到元素，最后读取或修改属性。

5.1 Word

终端：

officecli create report.docx officecli add report.docx /body --type paragraph \   --prop text="Executive Summary" --prop style=Heading1 officecli add report.docx /body --type paragraph \   --prop text="Revenue increased by 25%."  # 查看带格式标注的文本 officecli view report.docx annotated  # 精确修改第一个段落中的第一个文本片段 officecli set report.docx '/body/p[1]/r[1]' --prop bold=true

当你不知道目标元素在哪里时，不要猜路径。先用浅层读取查看子元素：

终端：

officecli get report.docx /body --depth 2 --json officecli query report.docx "run:contains(Revenue)" --json

get 适合从已知父节点向下看，query 适合按文本或属性筛选。拿到真实路径后再执行 set，会比让模型直接修改 OOXML 稳定很多。

图源：OfficeCLI 官方仓库。Word 场景除了段落和样式，还覆盖表格、页眉页脚、图片、批注、脚注、目录等对象；具体属性应以当前版本内置帮助为准。

5.2 Excel

终端：

officecli create data.xlsx officecli set data.xlsx /Sheet1/A1 --prop value="Name" --prop bold=true officecli set data.xlsx /Sheet1/B1 --prop value="Revenue" --prop bold=true officecli set data.xlsx /Sheet1/A2 --prop value="Alice" officecli set data.xlsx /Sheet1/B2 --prop value=4200 officecli set data.xlsx /Sheet1/B3 --prop formula="SUM(B2:B2)"  # 读取单元格结构化结果 officecli get data.xlsx '/Sheet1/B3' --json  # 只看指定列，限制输出行数 officecli view data.xlsx text --cols A,B --max-lines 20

官方 README 标注，Excel 内置公式引擎覆盖 350 多个函数，并支持数据透视表、条件格式、图表、数据验证等能力。函数数量很亮眼，但更实用的是：公式写入后可以被 OfficeCLI 继续读取，智能体不必先打开 Excel 等待重算。

图源：OfficeCLI 官方仓库。真实项目中，建议先用少量数据验证列名、格式与公式，再把同一套命令放大到批量任务。

6 看见结果再交付

Office 文档自动化最容易被忽略的一步，是视觉检查。文件能打开，不等于版式正确；XML 合法，也不代表标题没有压住图表。

OfficeCLI 提供三种常用入口：

终端：

# 生成独立 HTML 预览 officecli view deck.pptx html -o deck.html  # 生成 PNG 截图；多页可用 --page 1-N officecli view deck.pptx screenshot -o deck.png  # 启动本地服务并自动刷新 officecli watch deck.pptx

再把结构检查补上：

终端：

officecli validate deck.pptx officecli view deck.pptx issues --json

validate 负责 OpenXML 结构校验，view issues 用来查格式问题与潜在缺陷。遇到无效路径或属性时，JSON 错误对象会给出错误码、建议和可用范围，智能体可以据此重新读取父节点，再选择正确路径。

这套闭环比“一次生成完就交付”多了几条命令，却大幅降低了错误文件流到用户手里的概率。

7 批量任务与模板

当文档数量从 1 份变成 100 份，不应该让模型从头生成 100 次。OfficeCLI 给了三条更确定的路径。

7.1 模板合并

先在模板里放入 {{client}}、{{total}} 之类的占位符，再用 JSON 数据替换：

终端：

officecli merge invoice-template.docx out-001.docx \   --data '{"client":"Acme","total":"$5,200"}'  officecli merge q4-template.pptx q4-acme.pptx --data data.json

模板设计一次，数据填充多次，版式更一致，也不会反复消耗模型上下文。

7.2 Dump 与 batch

dump 可以把现有文档或某个子树序列化为可重放的 batch JSON；修改 JSON 后，再用 batch 重放到新文件。

终端：

officecli dump existing.docx -o blueprint.json officecli dump existing.xlsx /Sheet1 -o sheet.json officecli batch new.docx --input blueprint.json

批量模式默认具有原子性：一条失败，整批回滚。如果业务允许保留已成功的部分，再显式使用 --best-effort。这类选择不要交给模型猜，应写进脚本或流水线配置。

7.3 驻留模式

连续修改同一文件时，可以把文档留在内存中，减少反复打开与保存的开销：

终端：

officecli open report.docx officecli set report.docx '/body/p[1]/r[1]' --prop bold=true officecli set report.docx '/body/p[2]/r[1]' --prop color=FF0000 officecli save report.docx officecli close report.docx

OfficeCLI 自己的 get、query、view 能看到内存中的最新状态；但 Python、Microsoft Word 或其他程序准备读取这个文件之前，应先执行 save 或 close，确保改动已经落盘。

8 六个常见坑

一是路径从 1 开始。/slide[1] 是第一页，/body/p[1] 是第一个段落。把它当成编程语言里常见的 0 起始索引，会立刻找错对象。

二是 OfficeCLI 路径不是 XPath。 常规操作使用 /slide[1]/shape[2] 这套路径；只有进入 raw-set 等底层能力时才会接触 XPath。

三是不要凭记忆猜属性。 版本迭代后，可用属性和取值可能变化。直接查询内置帮助：

终端：

officecli help pptx set shape officecli help docx query officecli --help

四是不同 Shell 的引号规则不同。 README 中的反斜杠续行适合 Bash；PowerShell 里可以把命令写成一行，或改用反引号续行。包含空格、方括号和 JSON 时，优先给路径与数据加引号。

五是驻留模式要主动落盘。 外部程序马上读取文件时，先 save；任务已经结束则 close。否则你看到的可能仍是旧文件。

六是渲染检查不能省。 AI 能读结构，不等于它天然知道页面是否好看。复杂图表、长标题、特殊字体、动画和跨平台打开效果，都应该在交付前看一遍 HTML、截图或真实 Office 预览。

9 适用边界

OfficeCLI 很适合自动报告、批量替换、模板填充、结构化抽取、CI 中的文档检查，以及无桌面环境的 Office 文件生产。

如果你的流程高度依赖 VBA 宏、专有插件、人工拖拽微调或组织内部的特殊 Office 环境，不要一开始就全量迁移。先选一份真实模板和一组真实数据，验证打开效果、公式、字体和打印版式，再决定自动化范围。

建议的上手顺序也很简单：先用 L1 的 view 读懂文件；需要精确修改时进入 L2 的 get/query/set/add；只有常规元素模型覆盖不了时，才下沉到 L3 的 raw 与 raw-set。

OfficeCLI 不会替你省掉所有人工判断。它做得更务实：让智能体处理 Office 的过程可观察、可复现、可校验。先拿一份不重要的测试文档跑通「读取—定位—修改—渲染—校验」，比直接把生产文件交给 AI 更稳。

END