wehub/iofficeai--officecli
1
0
Fork 0
Code Issues Pull Requests Actions 6 Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default
Skill parity / diff (push) Waiting to run
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 10:15:30 +00:00
parent c96db981e8
commit 5aadc2dc45
1 changed files with 259 additions and 277 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+259 -277
View File
@@ -1,131 +1,134 @@
<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/iOfficeAI/OfficeCLI) · [上游 README](https://github.com/iOfficeAI/OfficeCLI/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# OfficeCLI
> **OfficeCLI is the world's first and the best Office suite designed for AI agents.**
> **OfficeCLI 是全球首个、也是最好的专为 AI 智能体设计的 Office 套件。**
**Give any AI agent full control over Word, Excel, and PowerPoint — in one line of code.**
**让任何 AI 智能体完全掌控 Word、Excel 和 PowerPoint——只需一行代码。**
Open-source. Single binary. No Office installation. No dependencies. Works everywhere.
开源免费。单一可执行文件。无需安装 Office。零依赖。全平台运行。
**OfficeCLI's built-in HTML rendering engine reproduces documents with high fidelity — and that's what gives AI eyes.** It renders `.docx` / `.xlsx` / `.pptx` to HTML or PNG, closing the *render → look → fix* loop.
**OfficeCLI 的内置 HTML 渲染引擎，高度还原文档原貌 —— 这正是让 AI 拥有"眼睛"的关键。** 它把 `.docx` / `.xlsx` / `.pptx` 渲染为 HTML 或 PNG，闭合"渲染 → 看 → 改"的循环。
[![GitHub Release](https://img.shields.io/github/v/release/iOfficeAI/OfficeCLI)](https://github.com/iOfficeAI/OfficeCLI/releases)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
**English** | [中文](README_zh.md) | [日本語](README_ja.md) | [한국어](README_ko.md)
[English](README.md) | **中文** | [日本語](README_ja.md) | [한국어](README_ko.md)
<p align="center">
<strong>🌐 Website:</strong> <a href="https://officecli.ai" target="_blank">officecli.ai</a> &nbsp;|&nbsp; <strong>💬 Community:</strong> <a href="https://discord.gg/2QAwJn7Egx" target="_blank">Discord</a>
<strong>🌐 官方网站:</strong> <a href="https://officecli.ai" target="_blank">officecli.ai</a> &nbsp;|&nbsp; <strong>💬 社区:</strong> <a href="https://discord.gg/2QAwJn7Egx" target="_blank">Discord</a>
</p>
<p align="center">
<img src="assets/ppt-process.webp" alt="OfficeCLI creating a PowerPoint presentation on AionUi" width="100%">
<img src="assets/ppt-process.webp" alt="在 AionUi 上使用 OfficeCLI 的 PPT 制作过程" width="100%">
</p>
<p align="center"><em>PPT creation process using OfficeCLI on <a href="https://github.com/iOfficeAI/AionUi">AionUi</a></em></p>
<p align="center"><em>在 <a href="https://github.com/iOfficeAI/AionUi">AionUi</a> 上使用 OfficeCLI 的 PPT 制作过程</em></p>
<p align="center"><strong>PowerPoint Presentations</strong></p>
<p align="center"><strong>PowerPoint 演示文稿</strong></p>
<table>
<tr>
<td width="33%"><img src="assets/designwhatmovesyou.gif" alt="OfficeCLI design presentation (PowerPoint)"></td>
<td width="33%"><img src="assets/horizon.gif" alt="OfficeCLI business presentation (PowerPoint)"></td>
<td width="33%"><img src="assets/efforless.gif" alt="OfficeCLI tech presentation (PowerPoint)"></td>
<td width="33%"><img src="assets/designwhatmovesyou.gif" alt="OfficeCLI 设计演示 (PowerPoint)"></td>
<td width="33%"><img src="assets/horizon.gif" alt="OfficeCLI 商务演示 (PowerPoint)"></td>
<td width="33%"><img src="assets/efforless.gif" alt="OfficeCLI 科技演示 (PowerPoint)"></td>
</tr>
<tr>
<td width="33%"><img src="assets/blackhole.gif" alt="OfficeCLI space presentation (PowerPoint)"></td>
<td width="33%"><img src="assets/first-ppt-aionui.gif" alt="OfficeCLI gaming presentation (PowerPoint)"></td>
<td width="33%"><img src="assets/shiba.gif" alt="OfficeCLI creative presentation (PowerPoint)"></td>
<td width="33%"><img src="assets/blackhole.gif" alt="OfficeCLI 太空演示 (PowerPoint)"></td>
<td width="33%"><img src="assets/first-ppt-aionui.gif" alt="OfficeCLI 游戏演示 (PowerPoint)"></td>
<td width="33%"><img src="assets/shiba.gif" alt="OfficeCLI 创意演示 (PowerPoint)"></td>
</tr>
</table>
<p align="center">—</p>
<p align="center"><strong>Word Documents</strong></p>
<p align="center"><strong>Word 文档</strong></p>
<table>
<tr>
<td width="33%"><img src="assets/showcase/word1.gif" alt="OfficeCLI academic paper (Word)"></td>
<td width="33%"><img src="assets/showcase/word2.gif" alt="OfficeCLI project proposal (Word)"></td>
<td width="33%"><img src="assets/showcase/word3.gif" alt="OfficeCLI annual report (Word)"></td>
<td width="33%"><img src="assets/showcase/word1.gif" alt="OfficeCLI 学术论文 (Word)"></td>
<td width="33%"><img src="assets/showcase/word2.gif" alt="OfficeCLI 项目建议书 (Word)"></td>
<td width="33%"><img src="assets/showcase/word3.gif" alt="OfficeCLI 年度报告 (Word)"></td>
</tr>
</table>
<p align="center">—</p>
<p align="center"><strong>Excel Spreadsheets</strong></p>
<p align="center"><strong>Excel 电子表格</strong></p>
<table>
<tr>
<td width="33%"><img src="assets/showcase/excel1.gif" alt="OfficeCLI budget tracker (Excel)"></td>
<td width="33%"><img src="assets/showcase/excel2.gif" alt="OfficeCLI gradebook (Excel)"></td>
<td width="33%"><img src="assets/showcase/excel3.gif" alt="OfficeCLI sales dashboard (Excel)"></td>
<td width="33%"><img src="assets/showcase/excel1.gif" alt="OfficeCLI 预算跟踪 (Excel)"></td>
<td width="33%"><img src="assets/showcase/excel2.gif" alt="OfficeCLI 成绩管理 (Excel)"></td>
<td width="33%"><img src="assets/showcase/excel3.gif" alt="OfficeCLI 销售仪表盘 (Excel)"></td>
</tr>
</table>
<p align="center"><em>All documents above were created entirely by AI agents using OfficeCLI — no templates, no manual editing.</em></p>
<p align="center"><em>以上所有文档均由 AI 智能体使用 OfficeCLI 全自动创建 — 无模板、无人工编辑。</em></p>
## For AI Agents — Get Started in One Line
## AI 智能体 — 一行搞定
Paste this into your AI agent's chat — it will read the skill file and install everything automatically:
把这行粘贴到你的 AI 智能体对话框 — 它会自动读取技能文件并完成安装：
```
curl -fsSL https://officecli.ai/SKILL.md
```
That's it. The skill file teaches the agent how to install the binary and use all commands.
就这一步。技能文件会教智能体如何安装二进制文件并使用所有命令。
## For Humans
## 普通用户
**Option A — GUI:** Install [**AionUi**](https://github.com/iOfficeAI/AionUi) — a desktop app that lets you create and edit Office documents through natural language, powered by OfficeCLI under the hood. Just describe what you want, and AionUi handles the rest.
**方式 A — 图形界面：** 安装 [**AionUi**](https://github.com/iOfficeAI/AionUi) — 一款桌面应用，用自然语言就能创建和编辑 Office 文档，底层由 OfficeCLI 驱动。只需描述你想要什么，AionUi 帮你搞定。
**Option B — CLI:** Download the binary for your platform from [GitHub Releases](https://github.com/iOfficeAI/OfficeCLI/releases), then run:
**方式 B — 命令行：** 从 [GitHub Releases](https://github.com/iOfficeAI/OfficeCLI/releases) 下载对应平台的二进制文件，然后运行：
```bash
officecli install
```
This copies the binary to your PATH and installs the **officecli skill** into every AI coding agent it detects — Claude Code, Cursor, Windsurf, GitHub Copilot, and more. Your agent can immediately create, read, and edit Office documents on your behalf, no extra configuration needed.
该命令会将二进制文件复制到 PATH，并自动将 **officecli 技能文件**安装到检测到的所有 AI 编程助手 — Claude Code、Cursor、Windsurf、GitHub Copilot 等。您的智能体可以立即创建、读取和编辑 Office 文档，无需额外配置。
## For Developers — See It Live in 30 Seconds
## 开发者 — 30 秒亲眼看到效果
```bash
# 1. Install (macOS / Linux) — or: brew install officecli / npm install -g @officecli/officecli
# 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. Create a blank PowerPoint
# 2. 创建一个空白 PowerPoint
officecli create deck.pptx
# 3. Start live preview — opens http://localhost:26315 in your browser
# 3. 启动实时预览 — 浏览器自动打开 http://localhost:26315
officecli watch deck.pptx
# 4. Open another terminal, add a slide — watch the browser update instantly
# 4. 打开另一个终端，添加一页幻灯片 — 浏览器即时刷新
officecli add deck.pptx / --type slide --prop title="Hello, World!"
```
That's it. Every `add`, `set`, or `remove` command you run will refresh the preview in real time. Keep experimenting — the browser is your live feedback loop.
就这么简单。你执行的每一条 `add`、`set`、`remove` 命令都会实时刷新预览。继续尝试吧 — 浏览器就是你的实时反馈窗口。
## Quick Start
## 快速开始
```bash
# Create a presentation and add content
# 创建演示文稿并添加内容
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
# View as outline
# 查看大纲
officecli view deck.pptx outline
# → Slide 1: Q4 Report
# → Shape 1 [TextBox]: Revenue grew 25%
# View as HTML — opens a rendered preview in your browser, no server needed
# 查看 HTML — 在浏览器中打开渲染预览，无需启动服务器
officecli view deck.pptx html
# Get structured JSON for any element
# 获取任意元素的结构化 JSON
officecli get deck.pptx '/slide[1]/shape[1]' --json
# Save and close — flushes the resident session to disk
officecli close deck.pptx
```
```json
@@ -141,9 +144,9 @@ officecli close deck.pptx
}
```
## Why OfficeCLI?
## 为什么选择 OfficeCLI？
What used to take 50 lines of Python and 3 separate libraries:
以前需要 50 行 Python 和 3 个独立库：
```python
from pptx import Presentation
@@ -152,58 +155,58 @@ prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[0])
title = slide.shapes.title
title.text = "Q4 Report"
# ... 45 more lines ...
# ... 还有 45 行 ...
prs.save('deck.pptx')
```
Now takes one command:
现在只需一条命令：
```bash
officecli add deck.pptx / --type slide --prop title="Q4 Report"
```
**What OfficeCLI can do:**
**OfficeCLI 能做什么：**
- **Create** documents from scratch -- blank or with content
- **Read** text, structure, styles, formulas -- in plain text or structured JSON
- **Analyze** formatting issues, style inconsistencies, and structural problems
- **Modify** any element -- text, fonts, colors, layout, formulas, charts, images
- **Reorganize** content -- add, remove, move, copy elements across documents
- **创建** 文档 -- 空白文档或带内容的文档
- **读取** 文本、结构、样式、公式 -- 纯文本或结构化 JSON
- **分析** 格式问题、样式不一致和结构缺陷
- **修改** 任意元素 -- 文本、字体、颜色、布局、公式、图表、图片
- **重组** 内容 -- 添加、删除、移动、复制跨文档元素
| Format | Read | Modify | Create |
|--------|------|--------|--------|
| 格式 | 读取 | 修改 | 创建 |
|------|------|------|------|
| Word (.docx) | ✅ | ✅ | ✅ |
| Excel (.xlsx) | ✅ | ✅ | ✅ |
| PowerPoint (.pptx) | ✅ | ✅ | ✅ |
**Word** — full [i18n & RTL support](https://github.com/iOfficeAI/OfficeCLI/wiki/i18n) (per-script font slots, per-script BCP-47 lang tags `lang.latin/ea/cs`, complex-script bold/italic/size, `direction=rtl` cascading through paragraph/run/section/table/style/header/footer/docDefaults, `rtlGutter` + `pgBorders` shorthand, locale-aware page numbering for Hindi/Arabic/Thai/CJK; `create --locale ar-SA` auto-enables RTL), [paragraphs](https://github.com/iOfficeAI/OfficeCLI/wiki/word-paragraph) (framePr, tabs shorthand, char-based indents), [runs](https://github.com/iOfficeAI/OfficeCLI/wiki/word-run) (underline.color, position half-pts), [tables](https://github.com/iOfficeAI/OfficeCLI/wiki/word-table) (virtual column ops add/remove/move/copyfrom, hMerge), [styles](https://github.com/iOfficeAI/OfficeCLI/wiki/word-style), [textbox](https://github.com/iOfficeAI/OfficeCLI/wiki/word-textbox) / [shape](https://github.com/iOfficeAI/OfficeCLI/wiki/word-shape) (textbox: rotation, `textDirection` `eaVert`/`vert270`, gradient, shadow, opacity), [headers/footers](https://github.com/iOfficeAI/OfficeCLI/wiki/word-header-footer), [images](https://github.com/iOfficeAI/OfficeCLI/wiki/word-picture) (PNG/JPG/GIF/SVG), [equations](https://github.com/iOfficeAI/OfficeCLI/wiki/word-equation) (LaTeX input), [diagrams](https://github.com/iOfficeAI/OfficeCLI/wiki/diagram) (mermaid → native editable shapes, or any mermaid type as a full-fidelity PNG), [comments](https://github.com/iOfficeAI/OfficeCLI/wiki/word-comment), [footnotes](https://github.com/iOfficeAI/OfficeCLI/wiki/word-footnote), [watermarks](https://github.com/iOfficeAI/OfficeCLI/wiki/word-watermark), [bookmarks](https://github.com/iOfficeAI/OfficeCLI/wiki/word-bookmark), [TOC](https://github.com/iOfficeAI/OfficeCLI/wiki/word-toc), [charts](https://github.com/iOfficeAI/OfficeCLI/wiki/word-chart), [hyperlinks](https://github.com/iOfficeAI/OfficeCLI/wiki/word-hyperlink), [sections](https://github.com/iOfficeAI/OfficeCLI/wiki/word-section), [form fields](https://github.com/iOfficeAI/OfficeCLI/wiki/word-formfield), [content controls (SDT)](https://github.com/iOfficeAI/OfficeCLI/wiki/word-sdt), [fields](https://github.com/iOfficeAI/OfficeCLI/wiki/word-field) (22 zero-param types + MERGEFIELD / REF / PAGEREF / SEQ / STYLEREF / DOCPROPERTY / IF), [OLE objects](https://github.com/iOfficeAI/OfficeCLI/wiki/word-ole), [revisions / tracked changes](https://github.com/iOfficeAI/OfficeCLI/wiki/word-revision) (`revision.type=ins\|del\|format\|moveFrom\|moveTo` + `revision.action=accept\|reject`, per-target `/revision[@author=Alice]` selector, tracked Find&Replace), page background color, [document properties](https://github.com/iOfficeAI/OfficeCLI/wiki/word-document)
**Word** — 完整的 [i18n 与 RTL 支持](https://github.com/iOfficeAI/OfficeCLI/wiki/i18n)（按脚本字体槽位、按脚本 BCP-47 语言标签 `lang.latin/ea/cs`、复杂脚本粗体/斜体/字号、`direction=rtl` 在段落/文本片段/节/表格/样式/页眉/页脚/docDefaults 间级联、`rtlGutter` + `pgBorders` 简写、印地语/阿拉伯语/泰语/中日韩本地化页码）、[段落](https://github.com/iOfficeAI/OfficeCLI/wiki/word-paragraph)、[文本片段](https://github.com/iOfficeAI/OfficeCLI/wiki/word-run)、[表格](https://github.com/iOfficeAI/OfficeCLI/wiki/word-table)、[样式](https://github.com/iOfficeAI/OfficeCLI/wiki/word-style)、[页眉/页脚](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)、[目录](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-document)
**Excel** — [cells](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-cell) (phonetic guide / furigana on add, Excel-UI `--shift left\|up` on remove / `shift=right\|down` on add), formulas (350+ built-in functions with auto-evaluation, spilling dynamic arrays with `_xlfn.` auto-prefix, financial / bond and statistical families, OFFSET/INDIRECT, defined-name formula bodies inlined at parse, formula-ref rewrite on row/col insert), [sheets](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-sheet) (visible/hidden/veryHidden, print margins, printTitleRows/Cols, RTL `sheetView`, cascade-aware sheet rename, empty-cell bloat filter on open), boolean `and`/`or` selectors (`row[Salary>5000 and Region=EMEA]`), [tables](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-table), [sort](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-sort) (sheet / range, multi-key, sidecar-aware), [conditional formatting](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-conditionalformatting), [charts](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-chart) (including box-whisker, [pareto](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-chart-add) with auto-sort + cumulative-%, log axis), [pivot tables](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-pivottable) (multi-field, date grouping, showDataAs, sort, grandTotals, subtotals, compact/outline/tabular layout, repeat item labels, blank rows, calculated fields, persistent `labelFilter` / `topN` filters, cache CoW + cross-pivot sharing), [slicers](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-slicer), [named ranges](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-namedrange), [data validation](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-validation), [images](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-picture) (PNG/JPG/GIF/SVG with dual-representation fallback), [sparklines](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-sparkline), [comments](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-comment) (RTL), [autofilter](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-autofilter), [shapes](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-shape), [OLE objects](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-ole), CSV/TSV import, `$Sheet:A1` cell addressing
**Excel** — [单元格](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-cell)（添加时支持音标/振假名）、公式（内置 350+ 函数自动求值，可溢出的动态数组自动加 `_xlfn.` 前缀，含财务/债券与统计函数族）、[工作表](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-sheet)（visible/hidden/veryHidden、打印边距、printTitleRows/Cols、RTL `sheetView`、级联感知的工作表重命名）、[表格](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)（含箱线图、[帕累托图](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-chart-add) 自动排序 + 累计百分比、对数轴）、[数据透视表](https://github.com/iOfficeAI/OfficeCLI/wiki/excel-pivottable)（多字段、日期分组、showDataAs、排序、总计、分类汇总、紧凑/大纲/表格布局、重复项目标签、空白行、计算字段）、[切片器](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，双重表示回退）、[迷你图](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** — [slides](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-slide) (header/footer/date/slidenum toggles, hidden), [shapes](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-shape) (pattern fill, blur effect, hyperlink tooltip + slide-jump links, **highlight color** on runs, `slideMaster`/`slideLayout` typed add/set/remove, arrow alias, effective.X + effective.X.src), [images](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-picture) (PNG/JPG/GIF/SVG, fill modes: stretch/contain/cover/tile, brightness/contrast/glow/shadow, rotation, link + tooltip), [tables](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-table) (built-in PowerPoint style catalogue, virtual `/col[C]` get + swap/copyFrom, row/col Move/CopyFrom, fill/background alias), [charts](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-chart) (pieOfPie, barOfPie, per-attr axisLine/gridline setters, series add/remove with theme palette, `anchor=x,y,w,h` shorthand), [animations](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-shape-set) (15 emphasis + 16 exit template-backed presets, multi-effect chains, motion-path presets, repeat/restart/autoReverse, chart animations + `chartBuild`), [transitions](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-morph-check) (morph + p14 + 12 p15 PowerPoint 2013+ presets), [3D models (.glb)](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-3dmodel) (combined `rotation=ax,ay,az`), [slide zoom](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-zoom), [equations](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-equation) (LaTeX input), [diagrams](https://github.com/iOfficeAI/OfficeCLI/wiki/diagram) (mermaid flowchart / sequence → native editable shapes, or any mermaid type as a full-fidelity PNG), [themes](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-theme), [connectors](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-connector) (`from`/`to` accept a full `/slide[N]/shape[@name=Foo]` path), [video/audio](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-video) (loop, autoStart), [groups](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-group) (link + tooltip; Get/Query/Add/Remove all descend into groups), [notes](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-notes) (RTL, lang), [comments](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-comment) (RTL, legacy + modern p188 threaded round-trip), SmartArt (round-trip via add-part + raw-set), [OLE objects](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-ole), [placeholders](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-placeholder) (add/set by phType)
**PowerPoint** — [幻灯片](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-slide)（页眉/页脚/日期/页码切换、隐藏）、[形状](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-shape)（图案填充、模糊效果、超链接提示 + 跳转幻灯片链接）、[图片](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-picture)（PNG/JPG/GIF/SVG，填充模式：stretch/contain/cover/tile，亮度/对比度/发光/阴影）、[表格](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-table)、[图表](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-chart)、[动画](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-slide)、[morph 过渡](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-morph-check)、[3D 模型（.glb）](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-3dmodel)、[幻灯片缩放](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)、[视频/音频](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-video)、[组合](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-group)、[备注](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-notes)（RTL、lang）、[批注](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-comment)（RTL）、[OLE 对象](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-ole)、[占位符](https://github.com/iOfficeAI/OfficeCLI/wiki/ppt-placeholder)（按 phType 添加/设置）
## Use Cases
## 使用场景
**For Developers:**
- Automate report generation from databases or APIs
- Batch-process documents (bulk find/replace, style updates)
- Build document pipelines in CI/CD environments (generate docs from test results)
- Headless Office automation in Docker/containerized environments
**开发者：**
- 从数据库或 API 自动生成报告
- 批量处理文档（批量查找/替换、样式更新）
- 在 CI/CD 环境中构建文档流水线（从测试结果生成文档）
- Docker/容器化环境中的无头 Office 自动化
**For AI Agents:**
- Generate presentations from user prompts (see examples above)
- Extract structured data from documents to JSON
- Validate and check document quality before delivery
**AI 智能体：**
- 根据用户提示生成演示文稿（见上方示例）
- 从文档提取结构化数据到 JSON
- 交付前验证和检查文档质量
**For Teams:**
- Clone document templates and populate with data
- Automated document validation in CI/CD pipelines
**团队：**
- 克隆文档模板并填充数据
- CI/CD 流水线中的自动化文档验证
## Installation
## 安装
Ships as a single self-contained binary. The .NET runtime is embedded -- nothing to install, no runtime to manage.
单一自包含可执行文件，.NET 运行时已内嵌 -- 无需安装任何依赖，无需管理运行时。
**One-line install:**
**一键安装：**
```bash
# macOS / Linux
@@ -213,23 +216,23 @@ curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh
irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
```
**Or via a package manager:**
**或通过包管理器安装：**
```bash
# Homebrew (macOS / Linux)
# Homebrew（macOS / Linux）
brew install officecli
# Scoop (Windows)
# Scoop（Windows）
scoop install officecli
# npm (all platforms — fetches the native binary for your platform)
# npm（全平台 — 安装时自动拉取对应平台的原生二进制）
npm install -g @officecli/officecli
```
**Or download manually** from [GitHub Releases](https://github.com/iOfficeAI/OfficeCLI/releases):
**或手动下载** [GitHub Releases](https://github.com/iOfficeAI/OfficeCLI/releases)：
| Platform | Binary |
|----------|--------|
| 平台 | 文件名 |
|------|--------|
| macOS Apple Silicon | `officecli-mac-arm64` |
| macOS Intel | `officecli-mac-x64` |
| Linux x64 | `officecli-linux-x64` |
@@ -237,44 +240,44 @@ npm install -g @officecli/officecli
| Windows x64 | `officecli-win-x64.exe` |
| Windows ARM64 | `officecli-win-arm64.exe` |
Verify installation: `officecli --version`
验证安装：`officecli --version`
**Or self-install from a downloaded binary (or run bare `officecli` to auto-install):**
**或从已下载的二进制文件自安装（直接运行 `officecli` 也会触发安装）：**
```bash
officecli install # explicit
officecli # bare invocation also triggers install
officecli install # 显式安装
officecli # 直接运行也会触发安装
```
Updates are checked automatically in the background. Disable with `officecli config autoUpdate false` or skip per-invocation with `OFFICECLI_SKIP_UPDATE=1`. Configuration lives under `~/.officecli/config.json`.
OfficeCLI 会在后台自动检查更新。通过 `officecli config autoUpdate false` 关闭，或通过 `OFFICECLI_SKIP_UPDATE=1` 跳过单次检查。配置文件位于 `~/.officecli/config.json`。
## Key Features
## 核心功能
### Built-in Engines & Generation Primitives
### 内置引擎与生成原语
OfficeCLI is self-contained. The capabilities below ship inside the binary — **no Office required**.
OfficeCLI 是自包含的。下列能力全部内置在二进制中——**无需 Office**。
#### Rendering engine — high-fidelity, built-in
#### 渲染引擎 —— 高保真、内置
OfficeCLI's keystone: a from-scratch, high-fidelity HTML rendering engine that lets an AI agent *see* the rendered document instead of guessing from the DOM. It covers shapes, charts (trendlines, error bars, waterfall, candlestick, sparklines), equations (OMML → LaTeX, rendered with KaTeX), 3D `.glb` models via Three.js, morph transitions, slide zoom, and shape effects. Per-page PNG screenshots are produced by piping the rendered HTML through a headless browser. Three modes:
OfficeCLI 的基石：一个从零实现、高保真的 HTML 渲染引擎，让 AI 智能体能"看见"渲染后的文档，而不是凭 DOM 瞎猜。它覆盖形状、图表（趋势线、误差线、瀑布、K 线、sparkline）、公式（OMML → LaTeX，KaTeX 渲染）、通过 Three.js 渲染的 3D `.glb` 模型、morph 过渡、幻灯片缩放、形状效果。按页 PNG 截图是把渲染出的 HTML 通过无头浏览器截出来的。三种模式：
- **`view html`** — standalone HTML file, assets inlined. Open in any browser.
- **`view screenshot`** — per-page PNG, ready for multimodal agents to read.
- **`watch`** — local HTTP server with auto-refreshing preview; every `add` / `set` / `remove` updates the browser instantly. Excel watch supports inline cell editing and drag-to-reposition charts.
- **`view html`** —— 独立 HTML 文件，资源内联。任何浏览器打开即可看。
- **`view screenshot`** —— 按页 PNG，供多模态智能体读图检查。
- **`watch`** —— 本地 HTTP 服务 + 自动刷新预览；每次 `add` / `set` / `remove` 立即更新浏览器。Excel watch 还支持单元格内联编辑、图表拖动定位。
```bash
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 view deck.pptx screenshot -o /tmp/deck.png # 多页用 --page 1-N
officecli watch deck.pptx # http://localhost:26315
```
> Without visualization, an agent generating slides is flying blind — it can read the DOM but can't tell if the title overflows or two shapes overlap. Because rendering is built into the binary, the *render → look → fix* loop works in CI, in Docker, on a server with no display — anywhere the binary runs.
> 没有可视化，生成 PPT 的智能体就是在盲跑——它能读 DOM，但分辨不出标题溢出、两个形状重叠。因为渲染引擎内置在二进制里，"渲染 → 看 → 改"循环在 CI、Docker、无显示器的服务器——只要二进制能跑的地方都能用。
#### Formula & pivot engine
#### 公式与透视引擎
350+ built-in Excel functions evaluated automatically on write — write `=SUM(A1:A2)`, `get` the cell, the value is already there. No round-trip through Office to recalc. Covers spilling dynamic arrays (`FILTER` / `SORT` / `UNIQUE` / `SEQUENCE` / `LET` / `LAMBDA` / `MAP`), `VLOOKUP` / `XLOOKUP` / `INDEX` / `MATCH`, financial & bond math (`XIRR` / `PRICE` / `YIELD` / `DURATION` / `COUPNUM`), statistical distributions, tests & regression (`NORM.DIST` / `T.TEST` / `LINEST`), and date & text functions.
350+ Excel 函数写入即自动求值——写 `=SUM(A1:A2)`，`get` 单元格，值已经在那。不需要回到 Office 重算。覆盖可溢出的动态数组（`FILTER` / `SORT` / `UNIQUE` / `SEQUENCE` / `LET` / `LAMBDA` / `MAP`，`_xlfn.` 自动加前缀）、`VLOOKUP` / `XLOOKUP` / `INDEX` / `MATCH`、财务与债券函数（`XIRR` / `PRICE` / `YIELD` / `DURATION` / `COUPNUM`）、统计分布/检验/回归（`NORM.DIST` / `T.TEST` / `LINEST`）、日期与文本函数等。
Plus native OOXML pivot tables from a source range with one command — multi-field rows/cols/filters, 10 aggregations, `showDataAs` modes, date grouping, calculated fields, top-N, layouts. Pivot cache + definition are written to OOXML, so Excel opens the file with the aggregation already populated:
外加从源数据范围一条命令生成原生 OOXML 数据透视表——多字段行/列/筛选器、10 种聚合方式、`showDataAs` 多种模式、日期分组、计算字段、Top-N、布局选项。透视表缓存和定义都写入 OOXML，Excel 打开即看到聚合后的结果：
```bash
officecli add sales.xlsx '/Sheet1' --type pivottable \
@@ -283,166 +286,168 @@ officecli add sales.xlsx '/Sheet1' --type pivottable \
--prop showDataAs=percentOfTotal
```
#### Template merge — generate once, fill many
#### 模板合并 —— 设计一次，填充 N 次
`merge` replaces `{{key}}` placeholders in any `.docx` / `.xlsx` / `.pptx` with JSON data — across paragraphs, table cells, shapes, headers, footers, and chart titles. Agent designs the layout once (expensive); production code fills it N times (cheap, deterministic, zero token cost). Avoids the failure mode where an agent regenerates each report from scratch and produces N inconsistent layouts.
`merge` 把任意 `.docx` / `.xlsx` / `.pptx` 中的 `{{key}}` 占位符替换为 JSON 数据——段落、表格单元格、形状、页眉页脚、图表标题都支持。智能体一次性设计版式（昂贵），生产代码填充 N 次（廉价、确定、零 token 成本）。避免了"每份报告都从头重生成、产出 N 份版式不一致"的失败模式。
```bash
officecli merge invoice-template.docx out-001.docx '{"client":"Acme","total":"$5,200"}'
officecli merge q4-template.pptx q4-acme.pptx data.json
```
#### Round-trip dump — learn from existing docs
#### Dump 往返 —— 从现有文档学习
`dump` serializes any `.docx`, `.pptx`, or `.xlsx` — whole document **or any subtree** (a single paragraph, table, slide, worksheet, the styles part, numbering, theme, or settings) — into a replayable batch JSON; `batch` replays it. Given a sample the user wants to imitate, an agent reads the structured spec instead of raw OOXML XML, mutates, and replays. Bridges "I have an existing template" and "generate me 100 variations."
`dump` 把任意 `.docx`、`.pptx`、`.xlsx` —— 整个文档**或任意子树**（单段、单表、单页幻灯片、单个工作表、styles、numbering、theme、settings）——序列化为可重放的 batch JSON，`batch` 重放回去。给一份用户想模仿的范本，智能体读结构化规格而不是原始 OOXML XML，修改后重放。打通"我有一份现成模板"和"给我生成 100 份变体"之间的链路。
```bash
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 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
```
### Resident Mode & Batch
### 驻留模式与批量执行
For multi-step workflows, resident mode keeps the document in memory. Batch mode applies multiple operations in a single pass.
驻留模式将文档保持在内存中，批量模式在一次打开/保存周期内执行多条命令。
```bash
# Resident mode — near-zero latency via 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
# Batch mode — multi-command execution (continues on error by default; --stop-on-error to abort)
# 批量模式 — 原子化多命令执行（默认遇到第一个错误即停止）
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
# Inline batch with --commands (no stdin needed)
# 内联 batch，无需标准输入
officecli batch deck.pptx --commands '[{"op":"set","path":"/slide[1]/shape[1]","props":{"text":"Hi"}}]'
# Abort on the first failing command (default is continue-on-error)
officecli batch deck.pptx --input updates.json --stop-on-error --json
# 使用 --force 跳过错误继续执行
officecli batch deck.pptx --input updates.json --force --json
```
> **Reading the file with another tool? Flush to disk first.**
> officecli's own reads (`get`/`query`/`view`) always see your latest edits, so within officecli you never need to save. But a live resident defers the disk write, so **before a non‑officecli program reads the file** — python‑docx/openpyxl, Microsoft Word, a renderer, delivery/upload — flush it:
> **要用其他工具读这个文件?先落盘。**
> OfficeCLI 自己的读(`get`/`query`/`view`)永远能看到最新改动,所以在 officecli 内部无需操心保存。但常驻进程会延迟写盘,因此**在非-officecli 程序读取该文件之前**——python-docx/openpyxl、Microsoft Word、渲染器、交付/上传——先落盘:
> ```bash
> officecli set report.docx /body/p[1] --prop bold=true
> officecli save report.docx # flush, keep the resident warm (or `close` to flush + release)
> python my_reader.py report.docx # now sees the edit
> officecli save report.docx # 落盘, 保留常驻进程(或 `close` = 落盘 + 释放)
> python my_reader.py report.docx # 此时才能看到改动
> ```
> A live resident also auto‑flushes shortly after going idle (adaptive 2–10s, scaled to the document's measured save cost). For a pipeline where another program reads after every command, set `OFFICECLI_RESIDENT_FLUSH=each` — every mutation is on disk before the command returns, while the resident stays warm. Full flush model (`each`/`auto`/fixed/`off`, save / close, env tuning): [wiki → open / close](https://github.com/iOfficeAI/OfficeCLI/wiki/command-open#when-the-file-on-disk-is-refreshed).
> 常驻进程闲置约 10s 后也会自动落盘一次。完整落盘模型(auto-save / auto-close / save / close、环境变量调节):[wiki → open / close](https://github.com/iOfficeAI/OfficeCLI/wiki/command-open#when-the-file-on-disk-is-refreshed)。
### Three-Layer Architecture
### 三层架构
Start simple, go deep only when needed.
从简单开始，仅在需要时深入。
| Layer | Purpose | Commands |
|-------|---------|----------|
| **L1: Read** | Semantic views of content | `view` (text, annotated, outline, stats, issues, html, svg, screenshot) |
| **L2: DOM** | Structured element operations | `get`, `query`, `set`, `add`, `remove`, `move`, `swap` |
| **L3: Raw XML** | Direct XPath access — universal fallback | `raw`, `raw-set`, `add-part`, `validate` |
| 层 | 用途 | 命令 |
|----|------|------|
| **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` |
```bash
# L1 — high-level views
# L1 — 高级视图
officecli view report.docx annotated
officecli view budget.xlsx text --cols A,B,C --max-lines 50
# L2 — element-level operations
# 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 — raw XML when L2 isn't enough
# 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 Integration
## AI 集成
### MCP Server
### MCP 服务器
Built-in [MCP](https://modelcontextprotocol.io) server — register with one command:
内置 [MCP](https://modelcontextprotocol.io) 服务器 — 一条命令注册：
```bash
officecli mcp claude # Claude Code
officecli mcp cursor # Cursor
officecli mcp vscode # VS Code / Copilot
officecli mcp lmstudio # LM Studio
officecli mcp list # Check registration status
officecli mcp list # 查看注册状态
```
Exposes all document operations as tools over JSON-RPC — no shell access needed.
通过 JSON-RPC 暴露所有文档操作 — 无需 shell 访问。
### Direct CLI Integration
### 直接 CLI 集成
Get OfficeCLI working with your AI agent in two steps:
两步将 OfficeCLI 集成到任何 AI 智能体：
1. **Install the binary** -- one command (see [Installation](#installation))
2. **Done.** OfficeCLI automatically detects your AI tools (Claude Code, GitHub Copilot, Codex) by checking known config directories and installs its skill file. Your agent can immediately create, read, and modify any Office document.
1. **安装二进制文件** -- 一条命令（见[安装](#安装)）
2. **完成。** OfficeCLI 自动检测您的 AI 工具（Claude Code、GitHub Copilot、Codex），通过检查已知配置目录并安装技能文件。您的智能体可以立即创建、读取和修改任何 Office 文档。
<details>
<summary><strong>Manual setup (optional)</strong></summary>
<summary><strong>手动配置（可选）</strong></summary>
If auto-install doesn't cover your setup, you can install the skill file manually:
如果自动安装未覆盖您的环境，可以手动安装技能文件：
**Feed SKILL.md to your agent directly:**
**直接将 SKILL.md 提供给智能体：**
```bash
curl -fsSL https://officecli.ai/SKILL.md
```
**Install as a local skill for Claude Code:**
**安装为 Claude Code 本地技能：**
```bash
curl -fsSL https://officecli.ai/SKILL.md -o ~/.claude/skills/officecli.md
```
**Other agents:** Include the contents of `SKILL.md` in your agent's system prompt or tool description.
**其他智能体：** 将 `SKILL.md` 的内容添加到智能体的系统提示词或工具描述中。
</details>
### Why your agent will thrive on OfficeCLI
### 智能体为什么在 OfficeCLI 上如鱼得水
- **Deterministic JSON output** — every command supports `--json` with consistent schemas. No regex parsing, no scraping stdout.
- **Path-based addressing** — every element has a stable path (`/slide[1]/shape[2]`). Agents navigate documents without understanding XML namespaces. (OfficeCLI syntax: 1-based indexing, element local names — not XPath.)
- **Progressive complexity (L1 → L2 → L3)** — agents start with read-only views, escalate to DOM ops, fall back to raw XML only when needed. Minimizes token usage.
- **Self-healing workflow** — `validate`, `view issues`, and the structured error codes (`not_found`, `invalid_value`, `unsupported_property`) return suggestions and valid ranges. Agents self-correct without human intervention.
- **Built-in agent-friendly rendering engine** — `view html` / `view screenshot` / `watch` emit HTML and PNG natively. No Office required. Agents can *see* their output and fix layout issues, even inside CI / Docker / headless environments.
- **Built-in formula & pivot engine** — 350+ Excel functions auto-evaluated on write (incl. spilling dynamic arrays, financial / bond and statistical families); native OOXML pivot tables from a source range with one command. Agents read computed values and shipped aggregations immediately, without round-tripping through Office.
- **Template merge** — agent designs the layout once, downstream code fills `{{key}}` placeholders N times. Avoids burning tokens regenerating every report from scratch.
- **Round-trip dump** — `dump` turns any `.docx`, `.pptx`, or `.xlsx` into replayable batch JSON. Agents learn from human-authored samples by reading a structured spec, not raw OOXML XML.
- **Built-in help** — when unsure about property names or value formats, the agent runs `officecli <format> set <element>` instead of guessing.
- **Auto-install** — OfficeCLI detects your AI tooling (Claude Code, Cursor, VS Code, …) and configures itself. No manual skill-file setup.
- **确定性 JSON 输出** —— 每条命令都支持 `--json`，schema 一致。无需正则解析、无需抓 stdout。
- **基于路径的寻址** —— 每个元素都有稳定路径（`/slide[1]/shape[2]`）。智能体无需理解 XML 命名空间即可导航文档。（OfficeCLI 自己的语法：1-based 索引、元素本地名——不是 XPath。）
- **渐进式复杂度（L1 → L2 → L3）** —— 智能体从只读视图入手，升级到 DOM 操作，仅在必要时降到 raw XML。最大限度节省 token。
- **自愈式工作流** —— `validate`、`view issues`、以及结构化错误码（`not_found`、`invalid_value`、`unsupported_property`）会返回 suggestion 和有效范围。智能体无需人工介入即可自纠错。
- **内置 agent 友好渲染引擎** —— `view html` / `view screenshot` / `watch` 原生输出 HTML 和 PNG。无需 Office。智能体能"看见"自己的产出，并在 CI / Docker / 无头环境里修复排版问题。
- **内置公式与透视引擎** —— 350+ Excel 函数写入即自动求值（含可溢出动态数组、财务/债券与统计函数族）；从源数据范围一条命令生成原生 OOXML 数据透视表。智能体立刻读到计算值和聚合结果，不需要回到 Office 重算。
- **模板合并** —— 智能体一次性设计版式，下游代码把 `{{key}}` 占位符填充 N 次。避免每份报告都烧 token 重生成。
- **Dump 往返** —— `dump` 把任意 `.docx`、`.pptx`、`.xlsx` 转成可重放的 batch JSON。智能体通过读结构化规格学习人类范本，而不是从原始 OOXML XML 反推。
- **内置帮助** —— 属性名或取值格式不确定时，智能体跑 `officecli <format> set <element>`，不靠猜。
- **自动安装** —— OfficeCLI 自动识别您的 AI 工具（Claude Code、Cursor、VS Code…）并完成配置。无需手动放 skill 文件。
### Built-in Help
### 内置帮助
Don't guess property names — drill into the help:
不确定属性名时，用分层帮助查询：
```bash
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 pptx set # 全部可设置元素与属性
officecli pptx set shape # 某一类元素的详细说明
officecli pptx set shape.fill # 单个属性格式与示例
officecli docx query # 选择器说明：属性匹配、:contains、:has() 等
```
Run `officecli --help` for the full overview.
将 `pptx` 换成 `docx` 或 `xlsx`；动词包括 `view`、`get`、`query`、`set`、`add`、`raw`。
### JSON Output Schemas
运行 `officecli --help` 查看完整概览。
All commands support `--json`. The general response shapes:
### JSON 输出格式
**Single element** (`get --json`):
所有命令均支持 `--json`。常见响应格式：
**单个元素**（`get --json`）：
```json
{"tag": "shape", "path": "/slide[1]/shape[1]", "attributes": {"name": "TextBox 1", "text": "Hello"}}
```
**List of elements** (`query --json`):
**元素列表**（`query --json`）：
```json
[
@@ -451,7 +456,7 @@ All commands support `--json`. The general response shapes:
]
```
**Errors** return a non-zero exit code with a structured error object including error code, suggestion, and valid values when available:
**错误** 返回结构化错误对象，包含错误码、建议修正和可用值：
```json
{
@@ -464,88 +469,83 @@ All commands support `--json`. The general response shapes:
}
```
Error codes: `not_found`, `invalid_value`, `unsupported_property`, `invalid_path`, `unsupported_type`, `missing_property`, `file_not_found`, `file_locked`, `invalid_selector`. Property names are auto-corrected -- misspelling a property returns a suggestion with the closest match.
错误码：`not_found`、`invalid_value`、`unsupported_property`、`invalid_path`、`unsupported_type`、`missing_property`、`file_not_found`、`file_locked`、`invalid_selector`。属性名支持自动纠错 -- 拼错属性名时会返回最接近的匹配建议。
**Error Recovery** -- Agents self-correct by inspecting available elements:
**错误恢复** -- 智能体通过检查可用元素自行修正：
```bash
# Agent tries an invalid path
# 智能体尝试无效路径
officecli get report.docx /body/p[99] --json
# Returns: {"success": false, "error": {"error": "...", "code": "not_found", "suggestion": "..."}}
# 返回: {"success": false, "error": {"error": "...", "code": "not_found", "suggestion": "..."}}
# Agent self-corrects by checking available elements
# 智能体通过查看可用元素自行修正
officecli get report.docx /body --depth 1 --json
# Returns the list of available children, agent picks the right path
# 返回可用子元素列表，智能体选择正确路径
```
**Mutation confirmations** (`set`, `add`, `remove`, `move`, `create` with `--json`):
**变更确认**（`set`、`add`、`remove`、`move`、`create` 使用 `--json`）：
```json
{"success": true, "path": "/slide[1]/shape[1]"}
```
See `officecli --help` for full details on exit codes and error formats.
运行 `officecli --help` 查看退出码和错误格式的完整说明。
## Comparison
## 对比
| | OfficeCLI | Microsoft Office | LibreOffice | python-docx / openpyxl |
|---|---|---|---|---|
| Open source & free | ✓ (Apache 2.0) | ✗ (paid license) | ✓ | ✓ |
| AI-native CLI + JSON | ✓ | ✗ | ✗ | ✗ |
| Zero install (single binary) | ✓ | ✗ | ✗ | ✗ (Python + pip) |
| Call from any language | ✓ (CLI) | ✗ (COM/Add-in) | ✗ (UNO API) | Python only |
| Path-based element access | ✓ | ✗ | ✗ | ✗ |
| Raw XML fallback | ✓ | ✗ | ✗ | Partial |
| Built-in agent-friendly rendering engine | ✓ | ✗ | ✗ | ✗ |
| Headless HTML/PNG output | ✓ | ✗ | Partial | ✗ |
| Template merge (`{{key}}`) across formats | ✓ | ✗ | ✗ | ✗ |
| Round-trip dump → batch JSON | ✓ | ✗ | ✗ | ✗ |
| Live preview (auto-refresh on edit) | ✓ | ✗ | ✗ | ✗ |
| Headless / CI | ✓ | ✗ | Partial | ✓ |
| Cross-platform | ✓ | Windows/Mac | ✓ | ✓ |
| Word + Excel + PowerPoint | ✓ | ✓ | ✓ | Separate libs |
| 开源免费 | ✓ (Apache 2.0) | ✗（付费授权） | ✓ | ✓ |
| AI 原生 CLI + JSON | ✓ | ✗ | ✗ | ✗ |
| 零安装（单一可执行文件） | ✓ | ✗ | ✗ | ✗（需 Python + pip） |
| 任意语言调用 | ✓ (CLI) | ✗ (COM/Add-in) | ✗ (UNO API) | 仅 Python |
| 基于路径的元素访问 | ✓ | ✗ | ✗ | ✗ |
| 原始 XML 兜底 | ✓ | ✗ | ✗ | 部分支持 |
| 内置 agent 友好渲染引擎 | ✓ | ✗ | ✗ | ✗ |
| 无头 HTML/PNG 输出 | ✓ | ✗ | 部分支持 | ✗ |
| 跨格式模板合并（`{{key}}`）| ✓ | ✗ | ✗ | ✗ |
| Dump → batch JSON 往返 | ✓ | ✗ | ✗ | ✗ |
| 实时预览（编辑后自动刷新） | ✓ | ✗ | ✗ | ✗ |
| 无头 / CI 环境 | ✓ | ✗ | 部分支持 | ✓ |
| 跨平台 | ✓ | Windows/Mac | ✓ | ✓ |
| Word + Excel + PowerPoint | ✓ | ✓ | ✓ | 需要多个库 |
## Command Reference
## 命令参考
| Command | Description |
|---------|-------------|
| [`create`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-create) | Create a blank .docx, .xlsx, or .pptx (type from extension) |
| [`view`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-view) | View content (modes: `outline`, `text`, `annotated`, `stats` (`--page-count`), `issues`, `html`, `svg`, `screenshot`, `pdf` (via exporter plugin), `forms` (via format-handler plugin)). docx supports `--render auto\|native\|html`. |
| [`load_skill`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-skills) | Print embedded SKILL.md content for a specialized skill (no install) |
| [`get`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-get) | Get element and children (`--depth N`, `--json`) |
| [`query`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-query) | CSS-like query with boolean `and`/`or`, row-by-column-name (`row[Salary>5000]`), `--find` flag |
| [`set`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-set) | Modify element properties; accepts selectors and Excel-native paths (parity with `get`/`query`), `--find`/`--replace` flags |
| [`add`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-add) | Add element (or clone with `--from <path>`) |
| [`remove`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-remove) | Remove an element |
| [`move`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-move) | Move element (`--to <parent>`, `--index N`, `--after <path>`, `--before <path>`) |
| [`swap`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-swap) | Swap two elements |
| [`validate`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-validate) | Validate against OpenXML schema |
| `view <file> issues` | Enumerate document issues (text overflow, missing alt text, formula errors, ...) |
| [`batch`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-batch) | Multiple operations applied in a single pass (stdin, `--input`, or `--commands`; continues on error by default, `--stop-on-error` to abort) |
| [`dump`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-dump) | Serialize a `.docx`, `.pptx`, or `.xlsx` into a replayable batch JSON (round-trip via `batch`); accepts a subtree path |
| [`refresh`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-refresh) | Recalculate TOC page numbers / `PAGE` / cross-references (`.docx`; Word backend on Windows, headless-HTML fallback) |
| [`plugins`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-plugins) | List / inspect / lint installed plugins (extend to `.doc`, `.hwpx`, `.pdf` export via dump-reader / exporter / format-handler kinds) |
| [`merge`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-merge) | Template merge — replace `{{key}}` placeholders with JSON data |
| [`watch`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-watch) | Live HTML preview in browser with auto-refresh |
| [`mcp`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-mcp) | Start MCP server for AI tool integration |
| [`raw`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-raw) | View raw XML of a document part |
| [`raw-set`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-raw) | Modify raw XML via XPath |
| `add-part` | Add a new document part (header, chart, etc.) |
| [`open`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-open) | Start resident mode (keep document in memory) |
| `close` | Save and close resident mode |
| [`install`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-install) | Install binary + skills + MCP (`all`, `claude`, `cursor`, etc.) |
| `config` | Get or set configuration |
| `<format> <command>` | [Built-in help](https://github.com/iOfficeAI/OfficeCLI/wiki/command-reference) (e.g. `officecli pptx set shape`) |
| 命令 | 说明 |
|------|------|
| [`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`、`issues`、`html`） |
| [`get`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-get) | 获取元素及子元素（`--depth N`、`--json`） |
| [`query`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-query) | CSS 风格查询（`[attr=value]`、`:contains()`、`:has()` 等） |
| [`set`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-set) | 修改元素属性 |
| [`add`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-add) | 添加元素（或通过 `--from <path>` 克隆） |
| [`remove`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-remove) | 删除元素 |
| [`move`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-move) | 移动元素（`--to <parent>`、`--index N`、`--after <path>`、`--before <path>`） |
| [`swap`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-swap) | 交换两个元素 |
| [`validate`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-validate) | OpenXML 模式校验 |
| [`batch`](https://github.com/iOfficeAI/OfficeCLI/wiki/command-batch) | 单次打开/保存周期内执行多条操作（stdin、`--input` 或 `--commands`；默认遇到第一个错误停止，`--force` 跳过错误继续） |
| [`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` | 获取或设置配置 |
| `<format> <command>` | [内置帮助](https://github.com/iOfficeAI/OfficeCLI/wiki/command-reference)（如 `officecli pptx set shape`） |
## End-to-End Workflow Example
## 端到端工作流示例
A typical self-healing agent workflow: create a presentation, populate it, verify, and fix issues -- all without human intervention.
典型的智能体自愈式工作流：创建演示文稿、填充内容、验证并修复问题 -- 全程无需人工干预。
```bash
# 1. Create
# 1. 创建
officecli create report.pptx
# 2. Add content
# 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
@@ -553,106 +553,90 @@ 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. Verify
# 3. 验证
officecli view report.pptx outline
officecli validate report.pptx
# 4. Fix any issues found
# 4. 修复发现的问题
officecli view report.pptx issues --json
# Address issues based on output, e.g.:
# 根据输出修复问题，例如：
officecli set report.pptx '/slide[1]/shape[1]' --prop font=Arial
```
### Units & Colors
### 单位与颜色
All dimension and color properties accept flexible input formats:
所有尺寸和颜色属性均接受灵活的输入格式：
| Type | Accepted formats | Examples |
|------|-----------------|----------|
| **Dimensions** | cm, in, pt, px, or raw EMU | `2cm`, `1in`, `72pt`, `96px`, `914400` |
| **Colors** | Hex, named, RGB, theme | `#FF0000`, `FF0000`, `red`, `rgb(255,0,0)`, `accent1` |
| **Font sizes** | Bare number or pt-suffixed | `14`, `14pt`, `10.5pt` |
| **Spacing** | pt, cm, in, or multiplier | `12pt`, `0.5cm`, `1.5x`, `150%` |
| 类型 | 支持的格式 | 示例 |
|------|-----------|------|
| **尺寸** | cm、in、pt、px 或原始 EMU | `2cm`、`1in`、`72pt`、`96px`、`914400` |
| **颜色** | 十六进制、命名色、RGB、主题色 | `#FF0000`、`FF0000`、`red`、`rgb(255,0,0)`、`accent1` |
| **字号** | 纯数字或带 pt 后缀 | `14`、`14pt`、`10.5pt` |
| **间距** | pt、cm、in 或倍数 | `12pt`、`0.5cm`、`1.5x`、`150%` |
## Common Patterns
## 常用模式
```bash
# Replace all Heading1 text in a Word doc
# 替换 Word 文档中所有 Heading1 文本
officecli query report.docx "paragraph[style=Heading1]" --json | ...
officecli set report.docx /body/p[1]/r[1] --prop text="New Title"
# Export all slide content as JSON
# 将所有幻灯片内容导出为 JSON
officecli get deck.pptx / --depth 2 --json
# Bulk-update Excel cells
# 批量更新 Excel 单元格
officecli batch budget.xlsx --input updates.json --json
# Import CSV data into an Excel sheet
# 导入 CSV 数据到 Excel 工作表
officecli add budget.xlsx / --type sheet --prop name="Q1 Data" --prop csv=sales.csv
# Template merge for batch reports
# 模板合并批量生成报告
officecli merge invoice-template.docx invoice-001.docx '{"client":"Acme","total":"$5,200"}'
# Check document quality before delivery
# 交付前检查文档质量
officecli validate report.docx && officecli view report.docx issues --json
```
**From Python or Node.js** — install one of the thin resident-pipe SDKs (no per-call process spawn):
```python
# 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]"))
```
```javascript
// 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]"));
```
Both SDKs auto-provision the native CLI when missing (mirror-first, Windows-capable) and announce the install rather than doing it silently.
Or wrap subprocess directly, one-shot:
**Python 调用** —— 包装一次，每次调用都返回解析好的 JSON：
```python
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 报告")
slide = cli("get", "deck.pptx", "/slide[1]")
print(slide["attributes"]["text"])
```
## Documentation
## 文档
The [Wiki](https://github.com/iOfficeAI/OfficeCLI/wiki) has detailed guides for every command, element type, and property:
[Wiki](https://github.com/iOfficeAI/OfficeCLI/wiki) 提供了每个命令、元素类型和属性的详细指南：
- **By format:** [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)
- **Workflows:** [End-to-end examples](https://github.com/iOfficeAI/OfficeCLI/wiki/workflows) -- Word reports, Excel dashboards, PowerPoint decks, batch modifications, resident mode
- **Runnable examples:** [examples/](examples/) -- copy-paste scripts (.sh/.py) for Word, Excel, and PowerPoint, with output files included
- **Troubleshooting:** [Common errors and solutions](https://github.com/iOfficeAI/OfficeCLI/wiki/troubleshooting)
- **AI agent guide:** [Decision tree for navigating the wiki](https://github.com/iOfficeAI/OfficeCLI/wiki/agent-guide)
- **按格式查看：**[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 数据表、PPT 演示、批量修改、驻留模式
- **故障排除：**[常见错误与解决方案](https://github.com/iOfficeAI/OfficeCLI/wiki/troubleshooting)
- **AI 智能体指南：**[Wiki 导航决策树](https://github.com/iOfficeAI/OfficeCLI/wiki/agent-guide)
## Build from Source
## 从源码构建
Requires [.NET 10 SDK](https://dotnet.microsoft.com/download) for compilation only. The output is a self-contained, native binary -- .NET is embedded in the binary and is not needed at runtime.
编译需要 [.NET 10 SDK](https://dotnet.microsoft.com/download)。输出为自包含的原生二进制文件 -- .NET 已内嵌，运行时无需安装。
```bash
./build.sh
```
## License
## 许可证
[Apache License 2.0](LICENSE)
Bug reports and contributions are welcome on [GitHub Issues](https://github.com/iOfficeAI/OfficeCLI/issues).
欢迎通过 [GitHub Issues](https://github.com/iOfficeAI/OfficeCLI/issues) 提交 Bug 报告和贡献代码。
---
If you find OfficeCLI useful, please [give it a star on GitHub](https://github.com/iOfficeAI/OfficeCLI) — it helps others discover the project.
如果觉得 OfficeCLI 好用，请在 [GitHub 上点个 Star](https://github.com/iOfficeAI/OfficeCLI) — 帮助更多人发现这个项目。
[OfficeCLI.AI](https://OfficeCLI.AI) | [GitHub](https://github.com/iOfficeAI/OfficeCLI)
@@ -668,7 +652,6 @@ yaml-frontmatter:
ai-agent-compatible: true
mcp-server: true
skill-file: SKILL.md
install-command-unix: curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
install-command-windows: irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
-->
@@ -686,7 +669,6 @@ keywords: office, cli, ai-agent, automation, docx, xlsx, pptx, openxml, document
ai-agent-compatible: true
mcp-server: true
skill-file: SKILL.md
skill-file-lines: 403
alternatives: python-docx, openpyxl, python-pptx, libreoffice --headless
install-command-unix: curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
install-command-windows: irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex