办公命令行

OfficeCLI 是全球首个也是最好的专为 AI 代理（Agent）设计的 Office 套件。

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

开源。单一二进制文件。无需安装 Office。无依赖。随处运行。

内置代理友好的渲染引擎 — 代理可以看到它们创建的内容，无需 Office 即可渲染 .docx / .xlsx / .pptx 为 HTML 或 PNG，在任何运行该二进制文件的地方闭环完成 渲染 → 查看 → 修复 的过程。

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

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

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

PowerPoint 演示文稿

—

Word 文档

—

Excel 电子表格

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

面向 AI 代理 — 一行代码上手

将以下内容粘贴到你的 AI 代理聊天中 — 它会读取技能文件并自动安装所有内容：

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

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

面向人类用户

选项 A — GUI： 安装 AionUi — 一个桌面应用，让你通过自然语言创建和编辑 Office 文档，底层由 OfficeCLI 驱动。只需描述你想要什么，AionUi 会处理其余部分。

选项 B — CLI： 从 GitHub Releases 下载对应平台的二进制文件，然后运行：

officecli install

这会将二进制文件复制到你的 PATH 中，并将 officecli 技能 安装到它能检测到的每个 AI 编码代理中 — Claude Code、Cursor、Windsurf、GitHub Copilot 等。你的代理可以立刻代表你创建、读取和编辑 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. 打开另一个终端，添加一张幻灯片 — 浏览器会即时更新
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 报告" --prop background=1A1A2E
officecli add deck.pptx '/slide[1]' --type shape \
  --prop text="收入增长 25%" --prop x=2cm --prop y=5cm \
  --prop font=Arial --prop size=24 --prop color=FFFFFF

# 查看大纲
officecli view deck.pptx outline
# → 幻灯片 1：Q4 报告
# →   形状 1 [文本框]：收入增长 25%

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

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

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

{
  "tag": "shape",
  "path": "/slide[1]/shape[1]",
  "attributes": {
    "name": "TextBox 1",
    "text": "收入增长 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 报告"
# ... 额外 45 行 ...
prs.save('deck.pptx')

现在只需一条命令：

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

OfficeCLI 能做什么：

• 创建文档 — 空白文档或包含内容的文档
• 读取文本、结构、样式、公式 — 以纯文本或结构化 JSON 形式输出
• 分析格式问题、样式不一致以及结构问题
• 修改任何元素 — 文本、字体、颜色、布局、公式、图表、图片
• 重组内容 — 添加、删除、移动、复制元素

Word — 完整的国际化与 RTL 支持（按文字系统的字体槽、按文字系统的 BCP-47 语言标签 lang.latin/ea/cs、复杂文字粗体/斜体/字号、direction=rtl 贯穿段落/运行/节/表格/样式/页眉页脚/docDefaults、rtlGutter + pgBorders 简写、针对印地语/阿拉伯语/泰语/CJK 的本地化页码；create --locale ar-SA 自动启用 RTL）、段落（framePr、制表符简写、基于字符的缩进）、运行（下划线颜色、位置半磅）、表格（虚拟列操作 add/remove/move/copyfrom、hMerge）、样式、文本框/形状（旋转、垂直文字 eaVert/vert270、渐变、阴影、透明度）、页眉/页脚、图片（PNG/JPG/GIF/SVG）、公式、批注、脚注、水印、书签、目录、图表、超链接、节、表单域、内容控件 (SDT)、域（22 种无参数类型 + MERGEFIELD / REF / PAGEREF / SEQ / STYLEREF / DOCPROPERTY / IF）、OLE 对象、修订/跟踪更改（revision.type=ins\|del\|format\|moveFrom\|moveTo + revision.action=accept\|reject、按目标 /revision[@author=Alice] 选择器、跟踪的查找替换）、页面背景颜色、文档属性

Excel — 单元格（添加时支持拼音/振假名、Excel UI --shift left\|up 删除时 / shift=right\|down 添加时）、公式（150+ 内置函数并可自动计算、动态数组函数自动加 _xlfn. 前缀、OFFSET/INDIRECT、定义名称公式体在解析时内联、插入行/列时自动重写公式引用）、工作表（可见/隐藏/深度隐藏、打印边距、printTitleRows/Cols、RTL sheetView、级联感知的工作表重命名、打开时过滤空单元格膨胀）、布尔 and/or 选择器（row[Salary>5000 and Region=EMEA]）、表格、排序（工作表/区域、多键、侧边栏感知）、条件格式、图表（包括盒须图、帕累托图 可自动排序 + 累积百分比、对数轴）、数据透视表（多字段、日期分组、showDataAs、排序、汇总总计、分类汇总、紧凑/大纲/表格布局、重复项目标签、空行、计算字段、持久的 labelFilter / topN / fillDownLabels、写时复制缓存 + 跨透视表共享）、切片器、命名区域、数据验证、图片（PNG/JPG/GIF/SVG 带双表示降级）、迷你图、批注（RTL）、自动筛选、形状、OLE 对象、CSV/TSV 导入、$Sheet:A1 单元格地址

PowerPoint — 幻灯片（页眉/页脚/日期/幻灯片编号开关、隐藏）、形状（图案填充、模糊效果、超链接工具提示 + 幻灯片跳转链接、文本运行上的高亮颜色、slideMaster/slideLayout 类型化添加/设置/删除、箭头别名、effective.X + effective.X.src）、图片（PNG/JPG/GIF/SVG、填充模式：拉伸/包含/覆盖/平铺、亮度/对比度/发光/阴影、旋转、链接 + 工具提示）、表格（内置 PowerPoint 样式目录、虚拟 /col[C] 获取 + 交换/copyFrom、行/列的 Move/CopyFrom、填充/背景别名）、图表（复合饼图、复合条饼图、按属性设置轴线/网格线、使用主题调色板添加/删除序列、anchor=x,y,w,h 简写）、动画（15 种强调 + 16 种退出模板预设、多效果链、路径动画预设、重复/重启/自动翻转、图表动画 + chartBuild）、切换（变形 + p14 + 12 种 PowerPoint 2013+ 的 p15 预设）、3D 模型 (.glb)（组合 rotation=ax,ay,az）、幻灯片缩放、公式、主题、连接符（使用 @name= 选择器指定起点/终点）、视频/音频（循环、自动开始）、组合（链接 + 工具提示；获取/查询/添加/删除均可深入组合内部）、备注（RTL、语言）、批注（RTL、旧版 + 现代 p188 线程化往返）、SmartArt（通过添加部件 + 原始设置实现往返）、OLE 对象、占位符（按 phType 添加/设置）

用例

针对开发者：

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

针对 AI 代理：

• 根据用户提示生成演示文稿（参见上面的示例）
• 从文档中提取结构化数据到 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：

验证安装：officecli --version

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

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

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

主要功能

内置引擎与生成原语

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

渲染引擎

二进制文件自带一个从头构建的、对代理友好的渲染引擎，覆盖形状、图表（趋势线、误差线、瀑布图、蜡烛图、迷你图）、公式（OMML → MathJax 兼容）、通过 Three.js 渲染的 3D .glb 模型、变形过渡、幻灯片缩放和形状效果。每页 PNG 截图通过将渲染后的 HTML 经无头浏览器管道输出生成。三种模式：

• view html — 独立的 HTML 文件，资源内联。可在任意浏览器中打开。
• view screenshot — 每页 PNG，可供多模态代理读取。
• watch — 本地 HTTP 服务器，提供自动刷新预览；每次执行 add / set / remove 都会立即更新浏览器。Excel 的 watch 模式支持内联单元格编辑以及拖拽重绘图表。

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

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

公式与数据透视表引擎

150+ 内置 Excel 函数在写入时自动计算——写入 =SUM(A1:A2)，get 该单元格，值已经存在。无需通过 Office 进行循环重计算。覆盖动态数组函数（FILTER / UNIQUE / SORT / SEQUENCE 自动添加 _xlfn. 前缀）、VLOOKUP / INDEX / MATCH、日期与文本函数，以及 140+ 更多函数。

此外，只需一条命令即可从源区域原生创建 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 数据——覆盖段落、表格单元格、形状、页眉、页脚和图表标题。代理设计一次布局（成本高）；生产代码填充 N 次（成本低、确定性、零 token 成本）。避免了代理为每份报告从头生成并产生 N 种不一致布局的失败模式。

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

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

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

officecli dump existing.docx -o blueprint.json                  # 整个文档
officecli dump existing.docx /body/tbl[1] -o table.json         # 任意子树
officecli batch new.docx --input blueprint.json

驻留模式与批量模式

对于多步骤工作流，驻留模式将文档保存在内存中。批量模式在一次打开/保存周期内执行多个操作。

# 驻留模式——通过命名管道实现接近零延迟
officecli open report.docx
officecli set report.docx /body/p[1]/r[1] --prop bold=true
officecli set report.docx /body/p[2]/r[1] --prop color=FF0000
officecli close report.docx

# 批量模式——原子化多命令执行（默认在第一个错误处停止）
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"}}]'

# 使用 --force 忽略错误继续执行
officecli batch deck.pptx --input updates.json --force --json

三层架构

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

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

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

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

AI 集成

MCP 服务器

内置的 MCP 服务器 — 一条命令即可注册：

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

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

直接 CLI 集成

两步即可让 OfficeCLI 与你的 AI 代理协同工作：

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

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

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

为何你的代理会在 OfficeCLI 上大放异彩

• 确定性的 JSON 输出 — 每条命令都支持 --json 并带有一致的 schema。无需正则解析，无需抓取 stdout。
• 基于路径的寻址 — 每个元素都有稳定的路径（/slide[1]/shape[2]）。代理无需理解 XML 命名空间即可操作文档。（OfficeCLI 语法：基于 1 的索引，元素本地名称 — 而非 XPath。）
• 渐进式复杂度（L1 → L2 → L3） — 代理从只读视图开始，逐步升级到 DOM 操作，仅在必要时回退到原始 XML。最大限度地减少 token 使用。
• 自修复工作流 — validate、view issues 以及结构化的错误代码（not_found、invalid_value、unsupported_property）会返回建议和有效范围。代理无需人工干预即可自我纠正。
• 内置的友好渲染引擎 — view html / view screenshot / watch 原生输出 HTML 和 PNG。无需 Office 即可运行。代理可以看到它们的输出并修复布局问题，即使在 CI / Docker / 无头环境中也是如此。
• 内置公式和数据透视表引擎 — 写入时自动评估 150+ 个 Excel 函数；一条命令即可从源范围创建原生 OOXML 数据透视表。代理无需经过 Office 即可立即读取计算值和已处理的聚合。
• 模板合并 — 代理设计一次布局，下游代码 N 次填充 {{key}} 占位符。避免每次重新生成报告时浪费 token。
• 往返导出 — dump 将任意 .docx 或 .pptx 转换为可重放的批量 JSON。代理通过读取结构化的规范（而非原始 OOXML XML）来学习人工编写的样本。
• 内置帮助 — 当不确定属性名称或值格式时，代理运行 officecli <format> set <element> 而不是猜测。
• 自动安装 — OfficeCLI 检测你的 AI 工具（Claude Code, Cursor, VS Code, …）并自行配置。无需手动设置技能文件。

内置帮助

不要猜测属性名称 — 深入帮助：

officecli pptx set              # 所有可设置的元素和属性
officecli pptx set shape        # 一种元素类型的详细信息
officecli pptx set shape.fill   # 一个属性：格式和示例
officecli docx query            # 选择器参考：属性、:contains、:has() 等

运行 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。属性名称会自动纠正 — 拼写错误的属性会返回建议，包含最接近的匹配。

错误恢复 — 代理通过检查可用元素进行自我纠正：

# 代理尝试无效路径
officecli get report.docx /body/p[99] --json
# 返回：{"success": false, "error": {"error": "...", "code": "not_found", "suggestion": "..."}}

# 代理通过检查可用元素自我纠正
officecli get report.docx /body --depth 1 --json
# 返回可用子元素的列表，代理选择正确的路径

变更确认（set、add、remove、move、create 加 --json）：

{"success": true, "path": "/slide[1]/shape[1]"}

有关退出码和错误格式的详细信息，请参阅 officecli --help。

对比

命令参考

端到端工作流示例

典型的自愈智能体工作流：创建演示文稿、填充内容、验证并修复问题——全程无需人工干预。

# 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

单位与颜色

所有尺寸和颜色属性均支持灵活输入格式：

常见模式

# 替换 Word 文档中所有 Heading1 文本
officecli query report.docx "paragraph[style=Heading1]" --json | ...
officecli set report.docx /body/p[1]/r[1] --prop text="New Title"

# 将所有幻灯片内容导出为 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 使用 — 安装精简版 officecli-sdk（驻留管道封装，无需每次调用生成进程）或直接封装 subprocess：

# 选项 A：基于驻留管道的精简 SDK
from officecli import Doc
with Doc("deck.pptx") as d:
    d.add("/", type="slide", title="Q4 Report")
    print(d.get("/slide[1]"))

# 选项 B：subprocess 封装（一次性，非驻留）
import json, subprocess
def cli(*args):
    return json.loads(subprocess.check_output(["officecli", *args, "--json"], text=True))
cli("create", "deck.pptx")

当 officecli 不在 PATH 中时，SDK 会回退到默认安装目录。

文档

Wiki 提供了每个命令、元素类型和属性的详细指南：

• 按格式： Word | Excel | PowerPoint
• 工作流： 端到端示例 —— Word 报表、Excel 仪表板、PowerPoint 演示文稿、批量修改、驻留模式
• 可运行示例： examples/ —— 可直接复制粘贴的脚本（.sh/.py），适用于 Word、Excel、PowerPoint，包含输出文件
• 故障排查： 常见错误与解决方案
• AI 智能体指南： Wiki 导航决策树

从源码构建

仅编译时需要 .NET 10 SDK。输出为自包含的原生二进制文件 —— .NET 已嵌入其中，运行时无需安装。

./build.sh

许可证

Apache License 2.0

欢迎在 GitHub Issues 上提交错误报告和贡献。

如果您觉得 OfficeCLI 有用，请在 GitHub 上为其点星 —— 这有助于其他人发现该项目。

OfficeCLI.AI | GitHub