OfficeCLI

OfficeCLI

OfficeCLI 是全球首款且最优秀的 Office 套件，专为 AI agent（智能体）设计。

只需一行代码，即可让任何 AI agent 完全控制 Word、Excel 和 PowerPoint。

开源。单二进制文件。无需安装 Office。无依赖项。随处可用。

OfficeCLI 内置的 HTML 渲染引擎能以高保真度还原文档——这也赋予了 AI 眼睛。 它可以将 .docx / .xlsx / .pptx 渲染为 HTML 或 PNG，从而闭环 渲染 → 观察 → 修正 的流程。

English | 中文 | 日本語 | 한국어

🌐 网站: officecli.ai  |  💬 社区: Discord

在 AionUi 上使用 OfficeCLI 创建 PPT 的过程

PowerPoint 演示文稿

—

Word 文档

—

Excel 电子表格

以上所有文档均由 AI agent 使用 OfficeCLI 完全创建——无模板，无手动编辑。

面向 AI Agent——一行代码即可开始

将其粘贴到你的 AI agent 的聊天中——它将读取技能文件并自动完成所有安装：

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

就这样。该技能文件教会 agent 如何安装二进制文件并使用所有命令。

面向人类用户

方式 A — GUI: 安装 AionUi——一款桌面应用，可让你通过自然语言创建和编辑 Office 文档，底层由 OfficeCLI 驱动。只需描述你想要的内容，AionUi 就会处理其余部分。

方式 B — CLI: 从 GitHub Releases 下载适用于你平台的二进制文件，然后运行：

officecli install

这会将二进制文件复制到你的 PATH，并将 officecli skill 安装到它能检测到的每个 AI 编码 agent 中——Claude Code、Cursor、Windsurf、GitHub Copilot 等。你的 agent 可以立即代表你创建、读取和编辑 Office 文档，无需额外配置。

面向开发者——30 秒内现场体验

# 1. 安装 (macOS / Linux) — 或：brew install officecli / npm install -g @officecli/officecli
curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
# Windows (PowerShell): irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex

# 2. 创建一个空白 PowerPoint
officecli create deck.pptx

# 3. 启动实时预览 — 在浏览器中打开 http://localhost:26315
officecli watch deck.pptx

# 4. 打开另一个终端，添加一张幻灯片 — 观察浏览器即时更新
officecli add deck.pptx / --type slide --prop title="Hello, World!"

就这样。你运行的每个 add、set 或 remove 命令都会实时刷新预览。继续尝试——浏览器就是你实时的反馈循环。

快速入门

# 创建演示文稿并添加内容
officecli create deck.pptx
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

# 以大纲形式查看
officecli view deck.pptx outline
# → Slide 1: Q4 Report
# →   Shape 1 [TextBox]: Revenue grew 25%

# 以 HTML 形式查看 — 在浏览器中打开渲染预览，无需服务器
officecli view deck.pptx html

# 获取任何元素的 JSON 结构
officecli get deck.pptx '/slide[1]/shape[1]' --json

# 保存并关闭 — 将驻留会话刷新到磁盘
officecli close deck.pptx

{
  "tag": "shape",
  "path": "/slide[1]/shape[1]",
  "attributes": {
    "name": "TextBox 1",
    "text": "Revenue grew 25%",
    "x": "720000",
    "y": "1800000"
  }
}

为什么选择 OfficeCLI？

过去需要 50 行 Python 和 3 个独立库才能完成的工作：

from pptx import Presentation
from pptx.util import Inches, Pt
prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[0])
title = slide.shapes.title
title.text = "Q4 Report"
# ... 45 more lines ...
prs.save('deck.pptx')

现在只需一条命令：

officecli add deck.pptx / --type slide --prop title="Q4 Report"

OfficeCLI 可以做什么：

• 创建文档——从头开始（空白或带内容）
• 读取文本、结构、样式、公式——以纯文本或结构化 JSON 形式
• 分析格式问题、样式不一致以及结构问题
• 修改任何元素——文本、字体、颜色、布局、公式、图表、图像
• 重新组织内容——跨文档添加、删除、移动、复制元素

格式	读取	修改	创建
Word (.docx)	✅	✅	✅
Excel (.xlsx)	✅	✅	✅
PowerPoint (.pptx)	✅	✅	✅

Word — 完整的 i18n 和 RTL 支持（按脚本的字体槽、按脚本的 BCP-47 语言标签 lang.latin/ea/cs、复杂脚本的粗体/斜体/字号、通过段落/run/节/表格/样式/页眉/页脚/docDefaults 层叠的 direction=rtl、rtlGutter + pgBorders 简写、区域感知的页码编号（印地语/阿拉伯语/泰语/中日韩）；create --locale ar-SA 自动启用 RTL）、段落（framePr、制表符简写、基于字符的缩进）、run（underline.color、position 半磅）、表格（虚拟列操作 add/remove/move/copyfrom、hMerge）、样式、文本框 / 形状（文本框：旋转、textDirection eaVert/vert270、渐变、阴影、透明度）、页眉/页脚、图片（PNG/JPG/GIF/SVG）、公式（LaTeX 输入）、图表（mermaid → 原生可编辑形状，或任何 mermaid 类型作为全保真 PNG）、批注、脚注、水印、书签、目录、图表、超链接、节、表单字段、内容控件 (SDT)、域（22 种零参数类型 + MERGEFIELD / REF / PAGEREF / SEQ / STYLEREF / DOCPROPERTY / IF）、OLE 对象、修订/跟踪更改（revision.type=ins|del|format|moveFrom|moveTo + revision.action=accept|reject、按目标的 /revision[@author=Alice] 选择器、跟踪的查找和替换）、页面背景颜色、文档属性

Excel — 单元格（添加时支持拼音指南/振假名、Excel UI 风格的 --shift left|up（删除时） / shift=right|down（添加时））、公式（350+ 内置函数，自动求值、自动扩展动态数组并带 _xlfn. 自动前缀、金融/债券和统计函数族、OFFSET/INDIRECT、在解析时内联定义名称公式体、插入行/列时重写公式引用）、工作表（visible/hidden/veryHidden、打印边距、printTitleRows/Cols、RTL sheetView、层叠感知的工作表重命名、打开时过滤空白单元格膨胀）、布尔 and/or 选择器（row[Salary>5000 and Region=EMEA]）、表格、排序（工作表/范围、多键、侧边栏感知）、条件格式、图表（包括箱线图、帕累托图（带自动排序和累积百分比）、对数坐标轴）、数据透视表（多字段、日期分组、showDataAs、排序、总计、小计、紧凑/大纲/表格布局、重复项目标签、空行、计算字段、持久化 labelFilter / topN 过滤器、缓存 CoW + 跨透视表共享）、切片器、命名区域、数据验证、图片（PNG/JPG/GIF/SVG，带双表示回退）、迷你图、批注（RTL）、自动筛选、形状、OLE 对象、CSV/TSV 导入、$Sheet:A1 单元格寻址

PowerPoint — 幻灯片（页眉/页脚/日期/幻灯片编号开关、隐藏）、形状（图案填充、模糊效果、超链接工具提示 + 幻灯片内跳转链接、run 的高亮颜色、slideMaster/slideLayout 类型的 add/set/remove、箭头别名、effective.X + effective.X.src）、图片（PNG/JPG/GIF/SVG、填充模式：stretch/contain/cover/tile、亮度/对比度/发光/阴影、旋转、链接 + 工具提示）、表格（内置 PowerPoint 样式目录、虚拟 /col[C] 的 get + swap/copyFrom、行/列的 Move/CopyFrom、填充/背景别名）、图表（复合饼图、复合条饼图、按属性的轴线/网格线设置器、使用主题调色板的系列添加/删除、anchor=x,y,w,h 简写）、动画（15 种强调 + 16 种退出模板支持的预设、多效果链、运动路径预设、重复/重新开始/自动反转、图表动画 + chartBuild）、切换效果（变形 + p14 + 12 p15 PowerPoint 2013+ 预设）、3D 模型 (.glb)（组合 rotation=ax,ay,az）、幻灯片缩放、公式（LaTeX 输入）、图表（mermaid 流程图/序列图 → 原生可编辑形状，或任何 mermaid 类型作为全保真 PNG）、主题、连接线（from/to 接受完整的 /slide[N]/shape[@name=Foo] 路径）、视频/音频（循环、自动开始）、组合（链接 + 工具提示；Get/Query/Add/Remove 都会深入组合）、备注（RTL、语言）、批注（RTL、旧版 + 现代 p188 线程化往返）、SmartArt（通过 add-part + raw-set 往返）、OLE 对象、占位符（按 phType 添加/设置）

使用场景

面向开发者：

• 自动化从数据库或 API 生成报告
• 批量处理文档（批量查找替换、样式更新）
• 在 CI/CD 环境中构建文档流水线（从测试结果生成文档）
• 在 Docker/容器化环境中进行无头 Office 自动化

面向 AI Agent：

• 根据用户提示生成演示文稿（参见上面的示例）
• 从文档中提取结构化数据到 JSON
• 在交付前验证和检查文档质量

面向团队：

• 克隆文档模板并填充数据
• 在 CI/CD 流水线中自动验证文档

安装

作为单个独立的二进制文件发布。.NET 运行时已嵌入——无需安装任何东西，也无需管理运行时。

一键安装：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex

或通过包管理器：

# Homebrew (macOS / Linux)
brew install officecli

# npm（所有平台——为你的平台获取原生二进制文件）
npm install -g @officecli/officecli

或手动下载 从 GitHub Releases 获取：

平台	二进制文件
macOS Apple Silicon	officecli-mac-arm64
macOS Intel	officecli-mac-x64
Linux x64	officecli-linux-x64
Linux ARM64	officecli-linux-arm64
Windows x64	officecli-win-x64.exe
Windows ARM64	officecli-win-arm64.exe

验证安装：officecli --version

或从下载的二进制文件自行安装（或直接运行 officecli 以自动安装）：

officecli install    # 显式安装
officecli            # 裸调用也会触发安装

更新会在后台自动检查。使用 officecli config autoUpdate false 禁用，或按调用跳过更新：OFFICECLI_SKIP_UPDATE=1。配置位于 ~/.officecli/config.json。

关键特性

内置引擎与生成基元

OfficeCLI 是自包含的。以下能力内置于二进制文件中——无需 Office。

渲染引擎——高保真、内置

OfficeCLI 的基石：一个从头开始编写的高保真 HTML 渲染引擎，让 AI agent 能够 看到 渲染后的文档，而不是从 DOM 猜测。它涵盖形状、图表（趋势线、误差线、瀑布图、烛台图、迷你图）、公式（OMML → MathJax 兼容）、通过 Three.js 渲染的 3D .glb 模型、变形切换效果、幻灯片缩放和形状效果。每页 PNG 屏幕截图通过将渲染后的 HTML 通过无头浏览器生成。三种模式：

• view html —— 独立 HTML 文件，资源内联。在任何浏览器中打开。
• view screenshot —— 每页 PNG，供多模态 agent 读取。
• watch —— 本地 HTTP 服务器，带自动刷新预览；每次 add / set / remove 都会立即更新浏览器。Excel 的 watch 模式支持内联单元格编辑和通过拖拽重新定位图表。

officecli view deck.pptx html -o /tmp/deck.html
officecli view deck.pptx screenshot -o /tmp/deck.png # 添加 --page 1-N 以渲染更多幻灯片
officecli watch deck.pptx                            # http://localhost:26315

没有可视化，生成幻灯片的 agent 就是在盲目飞行——它可以读取 DOM，但无法判断标题是否溢出或两个形状是否重叠。由于渲染内置于二进制文件中，渲染 → 观察 → 修正 循环可以在 CI、Docker、没有显示器的服务器上运行——任何二进制文件能运行的地方都可以。

公式与数据透视引擎

350+ 内置 Excel 函数在写入时自动求值——写入 =SUM(A1:A2)，get 该单元格时值已经存在。无需通过 Office 来回计算。涵盖自动扩展动态数组（FILTER / SORT / UNIQUE / SEQUENCE / LET / LAMBDA / MAP）、VLOOKUP / XLOOKUP / INDEX / MATCH、金融与债券计算（XIRR / PRICE / YIELD / DURATION / COUPNUM）、统计分布、检验与回归（NORM.DIST / T.TEST / LINEST）以及日期与文本函数。

此外，只需一条命令即可从源范围创建原生 OOXML 数据透视表——多字段行/列/筛选、10 种聚合方式、showDataAs 模式、日期分组、计算字段、Top-N、布局。数据透视缓存和定义被写入 OOXML，因此 Excel 打开文件时将直接显示聚合结果：

officecli add sales.xlsx '/Sheet1' --type pivottable \
  --prop source='Data!A1:E10000' --prop rows='Region,Category' \
  --prop cols=Quarter --prop values='Revenue:sum,Units:avg' \
  --prop showDataAs=percentOfTotal

模板合并——一次生成，多次填充

merge 将任何 .docx / .xlsx / .pptx 中的 {{key}} 占位符替换为 JSON 数据——涵盖段落、表格单元格、形状、页眉、页脚和图表标题。Agent 设计一次布局（开销大）；生产代码填充 N 次（廉价、确定性、零 token 消耗）。避免了 agent 从头开始重新生成每个报告而产生 N 种不一致布局的失败模式。

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

往返转储——从现有文档中学习

dump 将任何 .docx、.pptx 或 .xlsx——整个文档或任何子树（单个段落、表格、幻灯片、工作表、样式部分、编号、主题或设置）——序列化为可重放的批量 JSON；batch 则重放它。给定用户希望模仿的样本，agent 读取结构化规范而不是原始的 OOXML XML，进行修改并重放。桥接了“我有一个现有模板”和“为我生成 100 个变体”之间的差距。

officecli dump existing.docx -o blueprint.json                  # 整个文档
officecli dump existing.docx /body/tbl[1] -o table.json         # 任何子树
officecli dump existing.xlsx /Sheet1 -o sheet.json              # 单个工作表
officecli batch new.docx --input blueprint.json

驻留模式与批处理

对于多步骤工作流，驻留模式将文档保留在内存中。批处理模式在单次传递中应用多个操作。

# 驻留模式——通过命名管道实现近乎零延迟
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 close report.docx

# 批处理模式——多命令执行（默认在出错时继续；使用 --stop-on-error 中止）
echo '[{"command":"set","path":"/slide[1]/shape[1]","props":{"text":"Hello"}},
      {"command":"set","path":"/slide[1]/shape[2]","props":{"fill":"FF0000"}}]' \
  | officecli batch deck.pptx --json

# 内联批处理，使用 --commands（无需 stdin）
officecli batch deck.pptx --commands '[{"op":"set","path":"/slide[1]/shape[1]","props":{"text":"Hi"}}]'

# 在第一个失败命令时中止（默认是继续执行）
officecli batch deck.pptx --input updates.json --stop-on-error --json

使用其他工具读取文件？请先刷新到磁盘。 officecli 自己的读取命令（get/query/view）始终能看到你的最新编辑，因此在使用 officecli 时你不需要保存。但是，活动的驻留模式会推迟磁盘写入，因此在非 officecli 程序读取文件之前——python‑docx/openpyxl、Microsoft Word、渲染器、交付/上传——请先刷新它：

officecli set report.docx /body/p[1] --prop bold=true
officecli save report.docx           # 刷新，保持驻留模式活跃（或使用 `close` 来刷新并释放）
python my_reader.py report.docx      # 现在可以看到编辑

活动的驻留模式还会在空闲后不久自动刷新（自适应 2-10 秒，根据文档测量的保存成本缩放）。对于另一个程序会在每条命令后读取的流水线，设置 OFFICECLI_RESIDENT_FLUSH=each——每次修改在命令返回前就已写入磁盘，同时驻留模式保持活跃。完整的刷新模型（each/auto/固定时间/off、save / close、环境变量调优）：wiki → open / close。

三层架构

从简单开始，仅在需要时深入。

层	目的	命令
L1: 读取	内容的语义视图	view（text、annotated、outline、stats、issues、html、svg、screenshot）
L2: DOM	结构化元素操作	get、query、set、add、remove、move、swap
L3: 原始 XML	直接 XPath 访问——通用回退	raw、raw-set、add-part、validate

# L1 — 高层视图
officecli view report.docx annotated
officecli view budget.xlsx text --cols A,B,C --max-lines 50

# L2 — 元素级操作
officecli query report.docx "run:contains(TODO)"
officecli add budget.xlsx / --type sheet --prop name="Q2 Report"
officecli move report.docx /body/p[5] --to /body --index 1

# L3 — 当 L2 不够时使用原始 XML
officecli raw deck.pptx '/slide[1]'
officecli raw-set report.docx document \
  --xpath "//w:p[1]" --action append \
  --xml '<w:r><w:t>Injected text</w:t></w:r>'

AI 集成

MCP 服务器

内置 MCP 服务器——一行命令注册：

officecli mcp claude       # Claude Code
officecli mcp cursor       # Cursor
officecli mcp vscode       # VS Code / Copilot
officecli mcp lmstudio     # LM Studio
officecli mcp list         # 检查注册状态

通过 JSON-RPC 将所有文档操作作为工具暴露——无需 shell 访问。

直接 CLI 集成

分两步让 OfficeCLI 与你的 AI agent 配合工作：

1. 安装二进制文件——一条命令（参见安装）
2. 完成。 OfficeCLI 会自动检测你的 AI 工具（Claude Code、GitHub Copilot、Codex），通过检查已知的配置目录来安装其技能文件。你的 agent 可以立即创建、读取和修改任何 Office 文档。

手动设置（可选）

如果自动安装不适用于你的设置，你可以手动安装技能文件：

直接将 SKILL.md 提供给 agent：

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

作为本地技能安装到 Claude Code：

curl -fsSL https://officecli.ai/SKILL.md -o ~/.claude/skills/officecli.md

其他 agent： 将 SKILL.md 的内容包含在你的 agent 的系统提示或工具描述中。

为什么你的 agent 会在 OfficeCLI 上蓬勃发展

• 确定性的 JSON 输出 —— 每条命令都支持 --json，且模式一致。无需正则解析，无需抓取 stdout。
• 基于路径的寻址 —— 每个元素都有稳定的路径（/slide[1]/shape[2]）。Agent 无需理解 XML 命名空间即可导航文档。（OfficeCLI 语法：基于 1 的索引，元素本地名称——不是 XPath。）
• 渐进式复杂度（L1 → L2 → L3） —— Agent 从只读视图开始，逐步升级到 DOM 操作，仅在必要时回退到原始 XML。最小化 token 消耗。
• 自愈工作流 —— validate、view issues 和结构化的错误代码（not_found、invalid_value、unsupported_property）会返回建议和有效范围。Agent 无需人工干预即可自我修正。
• **内置的 agent 友好渲染引擎