iOfficeAI/OfficeCLI
GitHub: iOfficeAI/OfficeCLI
OfficeCLI 是一款让 AI agent 通过命令行直接创建、读取和编辑 Word、Excel、PowerPoint 文档的开源工具，无需安装 Office 即可运行。
Stars: 16988 | Forks: 1130
# OfficeCLI
**一行代码，即可让任何 AI agent 全面掌控 Word、Excel 和 PowerPoint。**
开源。单一二进制文件。无需安装 Office。无依赖。随处运行。
**OfficeCLI 内置的 HTML 渲染引擎能够高保真地还原文档——这正是赋予 AI “双眼”的关键。** 它可以将 `.docx` / `.xlsx` / `.pptx` 渲染为 HTML 或 PNG，从而闭合 *渲染 → 查看 → 修复* 循环。
[](https://github.com/iOfficeAI/OfficeCLI/releases)
[](LICENSE)
**English** | [中文](README_zh.md) | [日本語](README_ja.md) | [한국어](README_ko.md)
Injected text set ` 来获取帮助，而不是靠猜。
- **自动安装**——OfficeCLI 会自动检测您的 AI 工具（如 Claude Code、Cursor、VS Code 等）并完成自身配置。无需手动设置 skill 文件。
### 内置帮助
无需猜测属性名称——直接查阅帮助文档：
```
officecli pptx set # All settable elements and properties
officecli pptx set shape # Detail for one element type
officecli pptx set shape.fill # One property: format and examples
officecli docx query # Selector reference: attributes, :contains, :has(), etc.
```
运行 `officecli --help` 查看完整概述。
### JSON 输出 Schema
所有命令均支持 `--json`。常规的响应结构如下：
**单个元素** (`get --json`):
```
{"tag": "shape", "path": "/slide[1]/shape[1]", "attributes": {"name": "TextBox 1", "text": "Hello"}}
```
**元素列表** (`query --json`):
```
[
{"tag": "paragraph", "path": "/body/p[1]", "attributes": {"style": "Heading1", "text": "Title"}},
{"tag": "paragraph", "path": "/body/p[5]", "attributes": {"style": "Heading1", "text": "Summary"}}
]
```
**错误** 将返回非零退出代码及结构化的错误对象，其中包含错误代码、建议以及可用时的有效值：
```
{
"success": false,
"error": {
"error": "Slide 50 not found (total: 8)",
"code": "not_found",
"suggestion": "Valid Slide index range: 1-8"
}
}
```
错误代码包括：`not_found`、`invalid_value`、`unsupported_property`、`invalid_path`、`unsupported_type`、`missing_property`、`file_not_found`、`file_locked`、`invalid_selector`。属性名称会自动纠错——拼错属性会返回最接近匹配项的建议。
**错误恢复** —— Agent 通过检查可用元素进行自我纠错：
```
# Agent 尝试了一个无效路径
officecli get report.docx /body/p[99] --json
# 返回：{"success": false, "error": {"error": "...", "code": "not_found", "suggestion": "..."}}
# Agent 通过检查可用元素进行自我纠正
officecli get report.docx /body --depth 1 --json
# 返回可用子元素的列表，Agent 选择正确的路径
```
**变更确认** (`set`, `add`, `remove`, `move`, `create` 带有 `--json` 时):
```
{"success": true, "path": "/slide[1]/shape[1]"}
```
有关退出代码和错误格式的完整详细信息，请参阅 `officecli --help`。
## 对比
| | OfficeCLI | Microsoft Office | LibreOffice | python-docx / openpyxl |
|---|---|---|---|---|
| 开源且免费 | ✓ (Apache 2.0) | ✗ (付费许可) | ✓ | ✓ |
| 原生支持 AI 的 CLI + JSON | ✓ | ✗ | ✗ | ✗ |
| 零安装（单一二进制文件） | ✓ | ✗ | ✗ | ✗ (Python + pip) |
| 可从任何语言调用 | ✓ (CLI) | ✗ (COM/Add-in) | ✗ (UNO API) | 仅限 Python |
| 基于路径的元素访问 | ✓ | ✗ | ✗ | ✗ |
| 回退至原始 XML | ✓ | ✗ | ✗ | 部分支持 |
| 内置对 Agent 友好的渲染引擎 | ✓ | ✗ | ✗ | ✗ |
| 无头 HTML/PNG 输出 | ✓ | ✗ | 部分支持 | ✗ |
| 跨格式的模板合并 (`{{key}}`) | ✓ | ✗ | ✗ | ✗ |
| 往返转储 → 批处理 JSON | ✓ | ✗ | ✗ | ✗ |
| 实时预览（编辑时自动刷新） | ✓ | ✗ | ✗ | ✗ |
| 无头模式 / CI | ✓ | ✗ | 部分支持 | ✓ |
| 跨平台支持 | ✓ | Windows/Mac | ✓ | ✓ |
| Word + Excel + PowerPoint | ✓ | ✓ | ✓ | 独立的库 |
## 命令参考
| 命令 | 描述 |
|---------|-------------|
| [`create`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-create) | 创建空白的 .docx、.xlsx 或 .pptx（根据扩展名判断类型） |
| [`view`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-view) | 查看内容（模式包括：`outline`、`text`、`annotated`、`stats` (`--page-count`)、`issues`、`html`、`svg`、`screenshot`、`pdf`（通过导出器插件）、`forms`（通过格式处理程序插件））。docx 支持 `--render auto\|native\|html`。 |
| [`load_skill`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-skills) | 打印特定技能的内嵌 SKILL.md 内容（无需安装） |
| [`get`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-get) | 获取元素及其子元素（支持 `--depth N`, `--json`） |
| [`query`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-query) | 支持类 CSS 查询、布尔运算 `and`/`or`、行及列名定位 (`row[Salary>5000]`) 以及 `--find` 标志 |
| [`set`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-set) | 修改元素属性；接受选择器和 Excel 原生路径（与 `get`/`query` 对齐），支持 `--find`/`--replace` 标志 |
| [`add`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-add) | 添加元素（或使用 `--from ` 克隆元素） |
| [`remove`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-remove) | 移除元素 |
| [`move`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-move) | 移动元素（`--to `、`--index N`、`--after `、`--before `） |
| [`swap`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-swap) | 交换两个元素 |
| [`validate`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-validate) | 依据 OpenXML schema 进行验证 |
| `view issues` | 枚举文档中的问题（文本溢出、缺少替换文本、公式错误等） |
| [`batch`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-batch) | 在单次执行中应用操作（支持 stdin、`--input` 或 `--commands`；默认在出错时继续执行，可使用 `--stop-on-error` 终止） |
| [`dump`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-dump) | 将 `.docx`、`.pptx` 或 `.xlsx` 序列化为可重放的批处理 JSON（可通过 `batch` 进行往返操作）；接受子树路径 |
| [`refresh`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-refresh) | 重新计算 TOC 页码 / `PAGE` / 交叉引用（`.docx`；在 Windows 上使用 Word 后端，在无头环境下回退到 HTML） |
| [`plugins`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-plugins) | 列出 / 检查 / lint 已安装的插件（通过 dump-reader / exporter / format-handler 类型扩展支持 `.doc`、`.hwpx`、`.pdf` 导出） |
| [`merge`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-merge) | 模板合并——使用 JSON 数据替换 `{{key}}` 占位符 |
| [`watch`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-watch) | 在浏览器中实时预览 HTML，支持自动刷新 |
| [`mcp`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-mcp) | 启动 MCP 服务器以集成 AI 工具 |
| [`raw`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-raw) | 查看文档部件的原始 XML |
| [`raw-set`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-raw) | 通过 XPath 修改原始 XML |
| `add-part` | 添加新的文档部件（如页眉、图表等） |
| [`open`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-open) | 启动常驻模式（将文档保留在内存中） |
| `close` | 保存并关闭常驻模式 |
| [`install`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-install) | 安装二进制文件 + 技能 + MCP (`all`、`claude`、`cursor` 等) |
| `config` | 获取或设置配置 |
| ` ` | [内置帮助](https://github.com/iOfficeAI/OfficeCLI/wiki/command-reference) (例如 `officecli pptx set shape`) |
## 端到端工作流示例
一个典型的自我修复 agent 工作流：创建演示文稿、填充内容、进行验证并修复问题——全部无需人工干预。
```
# 1. 创建
officecli create report.pptx
# 2. 添加内容
officecli add report.pptx / --type slide --prop title="Q4 Results"
officecli add report.pptx '/slide[1]' --type shape \
--prop text="Revenue: $4.2M" --prop x=2cm --prop y=5cm --prop size=28
officecli add report.pptx / --type slide --prop title="Details"
officecli add report.pptx '/slide[2]' --type shape \
--prop text="Growth driven by new markets" --prop x=2cm --prop y=5cm
# 3. 验证
officecli view report.pptx outline
officecli validate report.pptx
# 4. 修复发现的任何问题
officecli view report.pptx issues --json
# 根据输出解决问题，例如：
officecli set report.pptx '/slide[1]/shape[1]' --prop font=Arial
```
### 单位与颜色
所有尺寸和颜色属性均接受灵活的输入格式：
| 类型 | 可接受的格式 | 示例 |
|------|-----------------|----------|
| **尺寸** | cm、in、pt、px 或原始 EMU | `2cm`, `1in`, `72pt`, `96px`, `914400` |
| **颜色** | Hex、命名颜色、RGB、主题色 | `#FF0000`, `FF0000`, `red`, `rgb(255,0,0)`, `accent1` |
| **字体大小** | 纯数字或带 pt 后缀 | `14`, `14pt`, `10.5pt` |
| **间距** | pt、cm、in 或倍数 | `12pt`, `0.5cm`, `1.5x`, `150%` |
## 常用模式
```
# 替换 Word 文档中的所有 Heading1 文本
officecli query report.docx "paragraph[style=Heading1]" --json | ...
officecli set report.docx /body/p[1]/r[1] --prop text="New Title"
# 将所有 slide 内容导出为 JSON
officecli get deck.pptx / --depth 2 --json
# 批量更新 Excel 单元格
officecli batch budget.xlsx --input updates.json --json
# 将 CSV 数据导入 Excel 工作表
officecli add budget.xlsx / --type sheet --prop name="Q1 Data" --prop csv=sales.csv
# 用于批量报告的模板合并
officecli merge invoice-template.docx invoice-001.docx '{"client":"Acme","total":"$5,200"}'
# 在交付前检查文档质量
officecli validate report.docx && officecli view report.docx issues --json
```
**在 Python 或 Node.js 中使用** —— 安装轻量级的常驻管道 SDK 之一（避免每次调用时重新生成进程）：
```
# Python — `pip install officecli-sdk`
from officecli import Doc
with Doc("deck.pptx") as d:
d.add("/", type="slide", title="Q4 Report")
print(d.get("/slide[1]"))
```
```
// Node.js — `npm install @officecli/sdk`
import { Doc } from "@officecli/sdk";
await using d = await Doc.open("deck.pptx");
await d.add("/", { type: "slide", title: "Q4 Report" });
console.log(await d.get("/slide[1]"));
```
这两个 SDK 在缺少原生 CLI 时都会自动进行配置（支持镜像优先，兼容 Windows），并且会发出安装通知而不是在后台默默执行。
或者直接封装子进程进行一次性调用：
```
import json, subprocess
def cli(*args):
return json.loads(subprocess.check_output(["officecli", *args, "--json"], text=True))
cli("create", "deck.pptx")
```
## 文档
[Wiki](https://github.com/iOfficeAI/OfficeCLI/wiki) 中包含了针对每个命令、元素类型和属性的详细指南：
- **按格式分类：** [Word](https://github.com/iOfficeAI/OfficeCLI/wiki/word-reference) | [Excel](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-reference) | [PowerPoint](https://github.com/iOfficeAI/OfficeCLI/wiki/powerpoint-reference)
- **工作流：** [端到端示例](https://github.com/iOfficeAI/OfficeCLI/wiki/workflows) —— Word 报告、Excel 仪表板、PowerPoint 演示文稿、批量修改、常驻模式
- **可运行示例：** [examples/](examples/) —— 包含可复制粘贴的脚本（.sh/.py），适用于 Word、Excel 和 PowerPoint，并附带输出文件
- **疑难解答：** [常见错误及解决方案](https://github.com/iOfficeAI/OfficeCLI/wiki/troubleshooting)
- **AI agent 指南：** [浏览 Wiki 的决策树](https://github.com/iOfficeAI/OfficeCLI/wiki/agent-guide)
## 从源码构建
仅需 [.NET 10 SDK](https://dotnet.microsoft.com/download) 即可进行编译。输出结果为一个自包含的原生二进制文件——.NET 已内嵌于二进制文件中，运行时无需额外安装。
```
./build.sh
```
## 许可证
[Apache License 2.0](LICENSE)
欢迎在 [GitHub Issues](https://github.com/iOfficeAI/OfficeCLI/issues) 中提交 Bug 报告和做出贡献。
如果 OfficeCLI 对您有帮助，请[在 GitHub 上给它点个 Star](https://github.com/iOfficeAI/OfficeCLI)——这有助于让更多人发现这个项目。
[OfficeCLI.AI](https://OfficeCLI.AI) | [GitHub](https://github.com/iOfficeAI/OfficeCLI)
🌐 Website: officecli.ai | 💬 Community: Discord
使用 OfficeCLI 在 AionUi 上创建 PPT 的过程
PowerPoint 演示文稿
 |
 |
 |
 |
 |
 |
—
Word 文档
 |
 |
 |
—
Excel 电子表格
 |
 |
 |
以上所有文档均由 AI agent 使用 OfficeCLI 完全创建——无需模板，无需人工编辑。
## AI agent 专属——一行代码入门 将此内容粘贴到您的 AI agent 聊天框中——它会读取 skill 文件并自动安装所需的一切： ``` curl -fsSL https://officecli.ai/SKILL.md ``` 就是这样。该 skill 文件会指导 agent 如何安装二进制文件并使用所有命令。 ## 面向开发者 **选项 A — GUI：** 安装 [**AionUi**](https://github.com/iOfficeAI/AionUi)——这是一款桌面应用，可让您通过自然语言创建和编辑 Office 文档，底层由 OfficeCLI 提供支持。只需描述您的需求，剩下的交给 AionUi 处理。 **选项 B — CLI：** 从 [GitHub Releases](https://github.com/iOfficeAI/OfficeCLI/releases) 下载适用于您平台的二进制文件，然后运行： ``` officecli install ``` 这会将二进制文件复制到您的 PATH 中，并将 **officecli skill** 安装到它检测到的每一个 AI 编程 agent 中——包括 Claude Code、Cursor、Windsurf、GitHub Copilot 等。您的 agent 可以立即代表您创建、读取和编辑 Office 文档，无需额外配置。 ## 面向开发者——30 秒看真实时效果 ``` # 1. 安装 (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 # 2. 创建一个空白的 PowerPoint officecli create deck.pptx # 3. 启动实时预览 — 在浏览器中打开 http://localhost:26315 officecli watch deck.pptx # 4. 打开另一个终端，添加一张 slide — 观察浏览器即时更新 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 # 保存并关闭 — 将驻留的 session 刷新到磁盘 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 行 ... 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 支持](https://github.com/iOfficeAI/OfficeCLI/wiki/i18n)（按字符集设置字体槽位、按字符集使用 BCP-47 语言标签 `lang.latin/ea/cs`、复杂脚本的加粗/斜体/字号设置、`direction=rtl` 可在段落/文本块( run)/节/表格/样式/页眉/页脚/docDefaults 间级联生效、支持 `rtlGutter` + `pgBorders` 简写、支持印地语/阿拉伯语/泰语/CJK 的本地化页码；`create --locale ar-SA` 会自动启用 RTL）、[段落](https://github.com/iOfficeAI/OfficeCLI/wiki/word-paragraph)（framePr、制表符简写、基于字符的缩进）、[文本块( run )](https://github.com/iOfficeAI/OfficeCLI/wiki/word-run)（underline.color、position half-pts）、[表格](https://github.com/iOfficeAI/OfficeCLI/wiki/word-table)（虚拟列操作 add/remove/move/copyfrom、hMerge）、[样式](https://github.com/iOfficeAI/OfficeCLI/wiki/word-style)、[文本框 / 形状](https://github.com/iOfficeAI/OfficeCLI/wiki/word-textbox)（旋转、verticalText `eaVert`/`vert270`、渐变、阴影、不透明度）、[页眉/页脚](https://github.com/iOfficeAI/OfficeCLI/wiki/word-header-footer)、[图像](https://github.com/iOfficeAI/OfficeCLI/wiki/word-picture)（PNG/JPG/GIF/SVG）、[公式](https://github.com/iOfficeAI/OfficeCLI/wiki/word-equation)、[评论](https://github.com/iOfficeAI/OfficeCLI/wiki/word-comment)、[脚注](https://github.com/iOfficeAI/OfficeCLI/wiki/word-footnote)、[水印](https://github.com/iOfficeAI/OfficeCLI/wiki/word-watermark)、[书签](https://github.com/iOfficeAI/OfficeCLI/wiki/word-bookmark)、[目录( TOC )](https://github.com/iOfficeAI/OfficeCLI/wiki/word-toc)、[图表](https://github.com/iOfficeAI/OfficeCLI/wiki/word-chart)、[超链接](https://github.com/iOfficeAI/OfficeCLI/wiki/word-hyperlink)、[节](https://github.com/iOfficeAI/OfficeCLI/wiki/word-section)、[表单域](https://github.com/iOfficeAI/OfficeCLI/wiki/word-formfield)、[内容控件 (SDT)](https://github.com/iOfficeAI/OfficeCLI/wiki/word-sdt)、[域](https://github.com/iOfficeAI/OfficeCLI/wiki/word-field)（22 种零参数类型 + MERGEFIELD / REF / PAGEREF / SEQ / STYLEREF / DOCPROPERTY / IF）、[OLE 对象](https://github.com/iOfficeAI/OfficeCLI/wiki/word-ole)、[修订 / 跟踪更改](https://github.com/iOfficeAI/OfficeCLI/wiki/word-revision)（`revision.type=ins\|del\|format\|moveFrom\|moveTo` + `revision.action=accept\|reject`、支持基于目标的 `/revision[@author=Alice]` 选择器、支持跟踪查找和替换）、页面背景色、[文档属性](https://github.com/iOfficeAI/OfficeCLI/wiki/word-document) **Excel** — [单元格](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-cell)（添加时支持拼音指南 / 注音( furigana )，移除时支持类似 Excel UI 的 `--shift left\|up` / 添加时支持 `shift=right\|down`）、公式（包含 350+ 个内置函数并支持自动求值，支持溢出动态数组并自动添加 `_xlfn.` 前缀，涵盖财务/债券和统计函数族，支持 OFFSET/INDIRECT，解析时内联定义名称的公式体，在插入行/列时重写公式引用）、[工作表](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-sheet)（visible/hidden/veryHidden、打印边距、printTitleRows/Cols、RTL `sheetView`、级联感知的工作表重命名、打开时过滤空单元格冗余）、布尔 `and`/`or` 选择器（`row[Salary>5000 and Region=EMEA]`）、[表格](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-table)、[排序](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-sort)（工作表/范围、多条件、感知辅助数据）、[条件格式](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-conditionalformatting)、[图表](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-chart)（包括箱线图、支持自动排序 + 累计百分比的[排列图( pareto )](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-chart-add)、对数坐标轴）、[数据透视表](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-pivottable)（多字段、日期分组、showDataAs、排序、总计/小计、紧凑/大纲/表格布局、重复项目标签、空行、计算字段、持久化的 `labelFilter` / `topN` / `fillDownLabels`、缓存写时复制( CoW ) + 跨透视表共享）、[切片器( Slicers )](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-slicer)、[命名范围](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-namedrange)、[数据验证](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-validation)、[图像](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-picture)（支持双表示回退的 PNG/JPG/GIF/SVG）、[迷你图( Sparklines )](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-sparkline)、[评论](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-comment)（支持 RTL）、[自动筛选](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-autofilter)、[形状](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-shape)、[OLE 对象](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-ole)、CSV/TSV 导入、`$Sheet:A1` 单元格寻址 **PowerPoint** — [幻灯片](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-slide)（页眉/页脚/日期/幻灯片页码开关、隐藏状态）、[形状](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-shape)（图案填充、模糊效果、超链接提示 + 幻灯片跳转链接、支持文本块上的 **高亮颜色**、`slideMaster`/`slideLayout` 类型的 add/set/remove、箭头别名、effective.X + effective.X.src）、[图像](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-picture)（PNG/JPG/GIF/SVG、填充模式：拉伸/包含/覆盖/平铺、亮度/对比度/发光/阴影、旋转、链接 + 提示）、[表格](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-table)（内置 PowerPoint 样式目录、虚拟 `/col[C]` 的 get + swap/copyFrom、行/列的 Move/CopyFrom、填充/背景别名）、[图表](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-chart)（pieOfPie、barOfPie、基于属性的 axisLine/gridline 设置器、使用主题调色板的系列添加/移除、`anchor=x,y,w,h` 简写）、[动画](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-shape-set)（15 种强调 + 16 种退出模板预设、多效果链、动作路径预设、重复/重启/自动反转、图表动画 + `chartBuild`）、[切换效果](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-morph-check)（morph + p14 + 12 种 p15 PowerPoint 2013+ 预设）、[3D 模型 (.glb)](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-3dmodel)（组合的 `rotation=ax,ay,az`）、[幻灯片缩放](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-zoom)、[公式](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-equation)、[主题](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-theme)、[连接符](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-connector)（使用 `@name=` 选择器确定 from/to）、[视频/音频](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-video)（循环、自动开始）、[组合](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-group)（链接 + 提示；Get/Query/Add/Remove 均会深入到组合内部）、[备注](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-notes)（RTL、语言）、[评论](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-comment)（RTL、遗留格式 + 现代化的 p188 线程往返处理）、SmartArt（通过 add-part + raw-set 进行往返处理）、[OLE 对象](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-ole)、[占位符](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-placeholder)（按 phType 进行 add/set） ## 应用场景 **面向开发者：** - 自动化从数据库或 API 生成报告 - 批量处理文档（批量查找/替换、更新样式） - 在 CI/CD 环境中构建文档流水线（根据测试结果生成文档） - 在 Docker / 容器化环境中进行无头( Headless ) 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 ``` **或手动下载** [GitHub Releases](https://github.com/iOfficeAI/OfficeCLI/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 # explicit officecli # bare invocation also triggers install ``` 更新会在后台自动检查。使用 `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 # add --page 1-N for more slides officecli watch deck.pptx # http://localhost:26315 ``` #### 公式与数据透视表引擎 包含 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 负责一次性设计好布局（成本较高）；生产代码只需负责多次填充数据（成本低、结果确定、无需消耗 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 )——从现有文档中学习 `dump` 可将任何 `.docx`、`.pptx` 或 `.xlsx`——整篇文档 **或任意子树**（单个段落、表格、幻灯片、工作表、样式部件、编号、主题或设置）——序列化为可重放的批处理 JSON；使用 `batch` 即可进行重放。给定一个用户想要模仿的样本，agent 可以读取结构化的规格说明而不是原始的 OOXML XML，然后进行修改并重放。这在“我有一份现成模板”和“给我生成 100 个变体”之间架起了桥梁。 ``` officecli dump existing.docx -o blueprint.json # whole document officecli dump existing.docx /body/tbl[1] -o table.json # any subtree officecli dump existing.xlsx /Sheet1 -o sheet.json # a single worksheet officecli batch new.docx --input blueprint.json ``` ### 常驻模式与批处理 对于多步骤的工作流，常驻模式( Resident Mode )会将文档保留在内存中。批处理模式则可以在单次执行中应用多项操作。 ``` # 驻留模式 — 通过 named pipes 实现近乎零延迟 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 ``` ### 三层架构 从简单开始，只在需要时才深入探索。 | 层级 | 目的 | 命令 | |-------|---------|----------| | **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 '