OfficeCLI

项目概述

OfficeCLI 是一款面向 AI 智能体的 Office 套件命令行工具，使用单文件二进制分发，内置 .NET 运行时，无需安装 Office 或额外依赖即可跨平台运行。它同时支持 .docx、.xlsx、.pptx 三种格式的读取、修改与创建，并提供从浏览器侧实时预览、模板合并、批量回放等一系列高级能力。

工具内置 HTML 渲染引擎，可将文档渲染为 HTML 或 PNG，使 AI 智能体能够"看见"文档布局，从而在"渲染→观察→修正"这一闭环中自主迭代排版。该引擎覆盖形状、图表（含趋势线、误差线、瀑布图、K 线图、迷你图）、公式（OMML → LaTeX，使用 KaTeX 渲染）、3D .glb 模型（通过 Three.js）、变形切换页、幻灯片缩放以及形状特效。

安装方式

提供四种安装途径：官方安装脚本（macOS/Linux 与 Windows）、包管理器（Homebrew、Scoop、npm）、从 GitHub Releases 手动下载对应平台二进制，以及手动调用 officecli install 将二进制复制到 PATH 并向已识别的 AI 编程工具（Claude Code、Cursor、Windsurf、GitHub Copilot 等）注入 skill 文件。

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

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

# 也可通过 Homebrew / Scoop / npm 安装

更新默认在后台自动检查，可通过 officecli config autoUpdate false 关闭，或设置环境变量 OFFICECLI_SKIP_UPDATE=1 在单次调用中跳过。配置文件位于 ~/.officecli/config.json。

快速上手

# 创建空白演示文稿
officecli create deck.pptx

# 启动实时预览（默认打开 http://localhost:26315）
officecli watch deck.pptx

# 在另一终端中添加幻灯片，浏览器即时刷新
officecli add deck.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
officecli add deck.pptx '/slide[1]' --type shape \
  --prop text="Revenue grew 25%" --prop x=2cm --prop y=5cm \
  --prop font=Arial --prop size=24 --prop color=FFFFFF

读取与查看命令支持多种视图模式：

officecli view deck.pptx outline       # 以大纲形式查看
officecli view deck.pptx html          # 在浏览器中渲染
officecli view deck.pptx screenshot    # 导出每页 PNG
officecli get deck.pptx '/slide[1]/shape[1]' --json   # 获取结构化 JSON

核心能力

公式与数据透视引擎

内置 350 多种 Excel 函数，写入时自动求值，无需通过 Office 重算。支持 FILTER、SORT、UNIQUE、SEQUENCE、LET、LAMBDA、MAP 等动态数组函数，VLOOKUP、XLOOKUP、INDEX、MATCH，金融与债券计算（XIRR、PRICE、YIELD、DURATION、COUPNUM），以及统计分布、检验与回归等。通过一条命令即可基于源数据范围生成原生 OOXML 数据透视表，支持多字段行列筛选、十种聚合方式、showDataAs 模式、日期分组、计算字段、Top-N 筛选等。

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 数据，覆盖段落、表格单元格、形状、页眉页脚与图表标题，便于"设计一次、批量填充"。dump 与 batch 命令可将整篇文档或任意子树（段落、表格、幻灯片、工作表、样式部件等）导出为可回放的批处理 JSON，借助结构化规格学习现有样式的布局。

officecli merge invoice-template.docx out-001.docx --data '{"client":"Acme","total":"$5,200"}'
officecli dump existing.docx -o blueprint.json
officecli batch new.docx --input blueprint.json

架构与命令分层

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

每个元素都拥有稳定的路径标识（如 /slide[1]/shape[2]），使用 1 起始索引与元素本地名称，无需理解 XML 命名空间。

# L2 元素级操作
officecli query report.docx "run:contains(TODO)"
officecli move report.docx /body/p[5] --to /body --index 1

# L3 原始 XML 回退
officecli raw-set report.docx document \
  --xpath "//w:p[1]" --action append \
  --xml '<w:r><w:t>Injected text</w:t></w:r>'

常驻模式与批处理

常驻模式将文档驻留内存，通过命名管道提供接近零延迟的操作；批处理支持原子回滚（任一命令失败即全部撤销）、--best-effort（保留成功项）与 --stop-on-error（遇错即停）。

officecli open report.docx
officecli set report.docx /body/p[1]/r[1] --prop bold=true
officecli save report.docx              # 刷盘但保留常驻
officecli close report.docx             # 刷盘并释放

officecli batch deck.pptx --commands '[{"op":"set","path":"/slide[1]/shape[1]","props":{"text":"Hi"}}]'

若在 officecli 之外的程序（如 python-docx、Microsoft Word）读取文件前，应使用 save 或 close 显式刷盘。常驻进程亦会在闲置 2–10 秒后自动刷盘；可通过 OFFICECLI_RESIDENT_FLUSH=each 让每次写入立即落盘。

AI 集成

内置 MCP 服务器，可通过一条命令注册到 Claude Code、Cursor、VS Code/Copilot、LM Studio 等工具，所有操作以 JSON-RPC 工具形式暴露，无需 shell 权限。同时支持直接 CLI 集成：安装二进制后，工具会自动检测 AI 编程工具的配置目录并写入 skill 文件。

officecli mcp claude
officecli mcp list

所有命令支持 --json，返回统一的结构化响应。单元素、元素列表、变更确认与错误对象均遵循一致模式，错误信息附带错误码（not_found、invalid_value、unsupported_property 等）、建议以及合法值域，便于智能体自纠。

{
  "success": false,
  "error": {
    "error": "Slide 50 not found (total: 8)",
    "code": "not_found",
    "suggestion": "Valid Slide index range: 1-8"
  }
}

属性名称具备自动纠错能力；遇到不确定的参数时，可使用 officecli <format> set <element> 内置帮助命令查询所有可设置的元素与属性。