夜雨聆风当你让 AI Agent 生成一份季度汇报 PPT，它能输出一整页 Markdown 大纲——标题层级清晰，内容要点齐全，但无法生成 .pptx 文件。你只能手动打开 PowerPoint，逐条复制到幻灯片中。
这并非某个 Agent 的能力不足，而是当前主流 AI Agent 的共性局限：无法直接操作办公文档。Word、Excel、PPT——这些办公场景中高频使用的文件格式，Agent 无法直接读写。
GitHub 上 star 数近 1.9 万的 OfficeCLI，正是为了解决这个能力缺口。
传统方案的局限
想在代码里操作 Office 文档，传统的路有两条。
路一：Python 库。 python-docx 管 Word，openpyxl 管 Excel，python-pptx 管 PPT——三个库各自独立，跨格式协作需自行整合。以 python-pptx 为例，生成一页带标题和项目列表的幻灯片需要 10-15 行代码。更关键的是，这些库的 API 面向人类开发者设计，Agent 调用需额外编写 Python 代码并执行，多了一层转换。
路二：LibreOffice headless。 命令行启动 LibreOffice，可以通过 UNO API 做格式转换和文档操作。问题也明显：安装包 300-400 MB、启动慢、没有结构化 JSON 输出、UNO API 本身学习成本高，Agent 调用不友好。
三者对比如下：
本质上，前两种方案的核心问题是：它们的核心 API 不是为程序化自动调用而设计的。
OfficeCLI 是什么
OfficeCLI 是 iOfficeAI 开源的办公文档命令行工具，基于 C# 开发，Apache 2.0 许可。一句话概括：专为 AI Agent 设计的办公文档 CLI。
几个核心特点：
brew install officecli 即可完成安装这三层具体是：
view 命令，获取文档的语义视图（text/outline/issues 等）和渲染输出（html/screenshot）get/query/set/add/remove/move/swap，按路径或选择器操作文档元素，大部分日常操作在这一层raw/raw-set/add-part/validate，直接 XPath 访问底层 XML，L2 不够用时才降级到这层原则很简单：永远从 L1 开始理解文档，L2 做修改，只有 L2 不够用时才降级到 L3。
30 秒跑通
从安装到生成第一个 PPT，完整流程：
watch 命令启动一个本地 HTTP 服务，浏览器里实时渲染。Agent 每做一步修改，浏览器里立刻看到效果。后文渲染引擎部分将详述此机制。
和 AI Agent 的连接方式
OfficeCLI 提供了几种接入方式，适配不同 Agent 框架。
方式一：CLI 直接调用
最通用的方式。任何能执行 shell 命令的 Agent 都能用：
所有命令支持 --json 输出，Agent 解析起来很方便。如果操作步骤多，可以开启常驻内存模式（Resident Mode），文件保持在内存中，省掉每次启动和文件读写的开销，延迟很低。还有 Batch Mode，多命令原子执行——任一步失败，全部回滚。
方式二：MCP 服务器
这是和 Claude Code、Cursor、VS Code Copilot 这类 Agent 最直接的集成方式。一条命令注册：
注册之后，MCP 把所有文档操作暴露为 JSON-RPC 工具，Agent 无需 shell 访问就能直接操作文档。MCP 工具只有一个 command 字符串参数，直接透传 CLI 命令语法。
方式三：SKILL.md 自动安装
项目根目录提供了一份详尽的 SKILL.md，包含完整的使用策略、命令参考、常见陷阱，还按场景分了专项技能：学术论文、融资 Deck、Morph 动画、财务模型、数据仪表盘。
运行 officecli install，它会自动检测你本地的 AI 工具，把 SKILL.md 安装到对应配置目录。Agent 读完这份文件就知道怎么操作 Office 文档了。
也可以手动拉取：
三个真实场景
场景一：Agent 生成季度汇报 PPT
最常见的需求。Agent 从数据源拿到季度数据，生成完整的 PPT：
关键在 issues 诊断步骤——Agent 不只生成文档，还能自行验证布局是否合理，发现问题后自动修正。Agent 能「看见」自己的输出，这是传统方案难以实现的。
场景二：批量填充 Excel 报表
每月给 50 个部门生成报表，数据结构一样，只是数值不同。逐一手动生成不可行。
先用模板合并（Merge）功能：在 Excel 里做好模板，需要替换的地方写 {{key}} 占位符，然后一条命令填充：
更省 token 的做法：让 Agent 一次性设计好版式（这一步成本高），后续填充只做 merge（确定性操作，成本很低）。
如果你已经有一个做好的样本 Excel，想批量生成同类文档，可以用 dump 把样本序列化成可回放的 JSON，再用 batch 重放生成变体：
场景三：读取 Word 文档提取结构化数据
另一种典型需求：有一批 Word 格式的合同或报告，需要把关键信息抽出来做统计。
query 和 get 输出的 JSON 可以直接传递给 Agent 做后续分析，无需人工逐页翻阅。
内置渲染引擎和公式引擎
这两个能力是 OfficeCLI 相比 Python 库最大的不同，也是 Agent 能闭环检查的前提。
渲染引擎：让 Agent「看见」自己的输出
python-docx 生成的 .docx 文件，无法预知其在 Word 中的实际排版效果，直到手动打开才发现布局偏差。OfficeCLI 内置了渲染引擎，Agent 可以在命令行里直接查看：
这闭合了一个关键回路：Agent 生成文档 → 渲染查看 → 发现问题 → 修改 → 再渲染。没有渲染引擎，Agent 无法验证修改结果的正确性。
更实用的是 watch 里的交互：浏览器里可以直接点击选中元素，Agent 通过 get 文件名 selected 读取用户选中的内容，实现人机协作——用户选中目标元素，Agent 定位并修改。
公式引擎：350+ 函数自动求值
openpyxl 读到 =VLOOKUP(...) 这种单元格，返回的就是公式字符串本身，不做求值。OfficeCLI 内置了 350+ 个 Excel 函数的求值引擎，包括：
这就意味着，Agent 修改了 Excel 里的某个数值，依赖这个数值的所有公式会自动重新计算——效果等同于在 Excel 中修改单元格后触发的联动更新。
配合数据透视表（PivotTable）功能，Agent 甚至能直接操作透视表的字段、分组、排序，不需要打开 Excel。
渲染引擎让 Agent 看到输出对不对，公式引擎让计算结果靠得住，两个合在一起，Agent 才能真正做到生成→检查→修正的闭环。
现在的边界
OfficeCLI 还在快速迭代，目前几乎每天发布一个新版本。当前版本有些事还做不了，或者做得不够好。
不做的事：
正在修的问题（从 GitHub Issue 整理）：
watch 暂不支持元素选中定位；透视表的标签筛选和 Top-N 只能在添加时指定，之后改不了实操上需要注意几个问题：
[N] 的路径必须加引号，否则 shell 会当 glob 展开shape[1] 通常是标题占位符，内容形状从 shape[2] 开始$ 和 \n 要注意转义日常场景——生成 PPT、填报表、读文档——已经够用。对于非典型需求，建议查阅 Issue 列表，通常已有相关讨论。
写在最后
OfficeCLI 补的是 AI Agent 一个直接的缺口：让 Agent 能直接读写 Word、Excel、PPT，无需人工中转。
