+
- 🌐 Website: officecli.ai | 💬 Community: Discord + 🌐 官方网站: officecli.ai | 💬 社区: Discord
-
+
PPT creation process using OfficeCLI on AionUi
+在 AionUi 上使用 OfficeCLI 的 PPT 制作过程
-PowerPoint Presentations
+PowerPoint 演示文稿
 |
- |
- |
+ |
+ |
+ |
 |
- |
- |
+ |
+ |
+ |
—
-Word Documents
+Word 文档
 |
- |
- |
+ |
+ |
+ |
—
-Excel Spreadsheets
+Excel 电子表格
 |
- |
- |
+ |
+ |
+ |
All documents above were created entirely by AI agents using OfficeCLI — no templates, no manual editing.
+以上所有文档均由 AI 智能体使用 OfficeCLI 全自动创建 — 无模板、无人工编辑。
-## 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 '