让 AI Agent 处理 Office 文件，难点通常不是“能否写出一段文字”，而是能否保留既有模板、正确更新公式和图表、看见排版结果，并在交付前确认文件已经真正保存。OfficeCLI 是一个面向 Agent 的本地命令行工具，支持 .docx、.xlsx 和 .pptx 的读取、创建、编辑与渲染，不需要安装 Microsoft Office。
它适合放在本地自动化、CI 文档生成或受控 Agent 工作流中。它不应直接获得共享盘、客户原件或财务主文件的无限写权限；先从副本和模板开始，经过预览与人工审核后再交付。
OfficeCLI 适合哪些任务
OfficeCLI 提供结构化命令来操作 Word、Excel 和 PowerPoint。常见用途包括：
- 从现有文档读取文字、样式、表格、公式或幻灯片结构；
- 用 JSON 或命令生成报告、演示文稿和工作簿；
- 批量查找替换、统一样式或按模板填充数据；
- 从数据库或 API 生成固定格式的周报、报价单和项目汇总；
- 把 Office 文件渲染为 HTML 或 PNG，让 AI 和人工检查版式；
- 在 CI 或容器环境中生成文档，而不依赖桌面版 Office。
对一次性的个人文档，桌面编辑器可能更快；对重复生成、批处理或需要 Agent 参与的场景，命令行和结构化输出更容易审查、复现和测试。
安装前先确定文件边界
在任何安装和自动化前，先设定这三条边界：
- 输入目录：只允许 Agent 读取任务需要的模板或副本，不直接读取整个共享盘。
- 输出目录：把生成结果写入独立的
out/或临时目录，避免覆盖原始文件。 - 交付动作：上传、邮件发送、覆盖共享文件和修改财务数据都应由人工确认。
Office 文档可能包含批注、修订记录、隐藏工作表、外部链接、宏或敏感元数据。自动化前应先确认来源可信，并使用副本测试。不要把“能读取文件”误认为“可以安全公开文件中的所有内容”。
怎样安装并确认版本
OfficeCLI 提供各平台的单二进制文件，也支持包管理器安装。Windows 用户可以优先使用已配置的软件包渠道，例如：
|
|
也可从项目 Releases 下载对应平台的二进制文件。安装后先确认版本：
|
|
如果使用下载脚本或全局 npm 安装，应先核对仓库、版本和企业软件策略；不要把未知来源的远程脚本直接放进高权限终端。对团队环境，建议固定经过测试的版本，而不是让每台机器自动追踪最新版。
第一次创建和预览 PowerPoint
最小工作流是“创建 → 写入 → 预览 → 保存”。例如创建一份演示文稿并添加标题页：
|
|
outline 适合快速核对幻灯片和文本结构，html 会生成可在浏览器中查看的渲染结果。不要只根据命令成功就认为文件可交付：标题溢出、形状重叠、字体替换和图表比例问题，往往要在渲染结果中才看得出来。
需要连续调整时，可以启动实时预览：
|
|
官方示例中预览服务默认会在本机 http://localhost:26315 打开。只在本机受控环境使用该端口，不要未经验证就把预览服务暴露到公网。
让 AI Agent 按“读、改、看、验”工作
直接要求 Agent “生成一份 PPT”容易得到不可控的整文件重写。更稳定的提示方式是把动作拆开：
- 先读取目标文件的结构或导出 JSON，不修改任何内容。
- 让 Agent 列出计划修改的页面、单元格或段落路径。
- 一次只改一个逻辑单元，例如一页幻灯片或一个工作表区域。
- 渲染 HTML 或截图，并检查内容、溢出、对齐和数据正确性。
- 保存到输出目录，最后由人工审核并决定是否替换原件。
可直接使用的任务约束示例：
读取
templates/monthly-report.pptx，不要修改原文件。根据data/summary.json生成out/monthly-report-review.pptx；只替换标题、三个 KPI 和图表数据。完成后导出 HTML 预览，列出所有修改路径、未填充字段和需要人工确认的内容。
这比“根据数据更新月报”更容易审查，也能防止 Agent 改动无关母版、备注或隐藏内容。
Word、Excel 和 PowerPoint 的差异
| 文件类型 | Agent 常做的事 | 交付前重点检查 |
|---|---|---|
Word .docx |
替换段落、表格、页眉页脚、样式和目录 | 页码、分页、引用、修订记录、字体与表格断行 |
Excel .xlsx |
写入单元格、公式、数据验证、图表和透视表 | 公式结果、引用范围、隐藏表、筛选条件、图表数据源 |
PowerPoint .pptx |
新建幻灯片、形状、图片、图表、备注和主题 | 标题溢出、元素重叠、配色、比例、放映效果 |
Excel 尤其需要谨慎：公式可以正确写入，不代表业务口径正确。应把指标定义、日期范围、币种、单位和舍入规则写在任务输入中，并让 Agent 输出计算来源和异常值，而不是只给最终数字。
用模板合并代替重复生成
重复型报告不应每次都让 Agent 从空白开始设计。OfficeCLI 的 merge 可用 JSON 数据替换 .docx、.xlsx 或 .pptx 中的 {{key}} 占位符：
|
|
适合的做法是：第一次人工确定模板和字段，后续由程序或 Agent 只准备经过校验的数据并执行合并。这样比每次重新排版更稳定，也能把“内容生成”和“版式控制”分开。
当字段缺失时，应让流程停止并报告缺失项，而不是用猜测值、空字符串或上一次客户的数据继续生成。对报价单、合同、发票、绩效表和面向外部的报告尤其如此。
多步骤编辑要注意保存时机
OfficeCLI 支持 resident mode，让文档在内存中保持打开状态以加快多步骤操作：
|
|
在 resident mode 中，工具自身的读取命令能看到最新内存状态；但其他程序、同步客户端或上传流程未必能看到。交给 Word、Excel、渲染器、Python 脚本或网盘之前，先执行 officecli save 或 officecli close，确保修改已写入磁盘。
批量操作还要明确失败策略。若每条命令都允许继续执行，可能生成“部分更新”的文件；对关键文档更适合使用 --stop-on-error 并把失败任务留给人工处理。
生成后怎样做质量检查
建议把质量检查分为三层：
- 结构检查：确认页数、工作表、段落、占位符、表格行数和输出路径。
- 数据检查：抽查公式、汇总金额、日期、图表范围和源数据版本。
- 视觉检查：查看 HTML 或 PNG，检查文字截断、页边距、重叠、颜色与模板一致性。
对批量生成文件，可随机抽样人工复核，并保留输入数据版本、模板版本、OfficeCLI 版本、命令日志和生成时间。这样出现错误时能定位是数据、模板、命令还是模型指令的问题。
常见问题
文件生成了但样式不对
先执行 officecli view <文件> html 或截图预览，不要只检查文件是否能打开。确认 Agent 是否改错了对象路径、是否覆盖了主题或母版，以及输入数据是否超过原模板的文字容量。将大段文本限制、图片尺寸和图表数量写进任务约束。
Excel 数据正确但图表或公式不对
核对图表引用范围、工作表名称、绝对/相对引用和日期格式。对包含宏、外部数据连接、复杂插件或企业模板的工作簿，先在副本上验证兼容性；自动化工具不应绕过组织对宏和外部链接的安全策略。
Agent 覆盖了原始文件
立即停止后续写入，从版本控制、备份或原始模板恢复。之后将输入路径设为只读副本，输出路径固定到独立目录，并要求 Agent 在每次写入前报告目标文件。不要依赖“请不要覆盖”这句提示词来保护文件。
总结
OfficeCLI 让 AI Agent 可以在本地、无 Office 安装的环境中处理 Word、Excel 和 PowerPoint，但可靠性来自流程而非单条命令：限定输入输出目录、从模板和副本开始、按读改看验循环操作、保存后再交给外部程序，并对数据和版式进行人工复核。把它当作可审查的文档自动化组件，而不是自动发布器，才能同时获得效率与可控性。