OfficeCLI v1.0.152：让 Agent 改 Office 文件前先管好写权限

OfficeCLI 用一个自包含命令行程序处理 DOCX、XLSX 和 PPTX。它能返回 JSON、按路径修改元素、执行原子批量操作、渲染 HTML/PNG，并通过技能或 MCP 接给 Agent。

版本、依赖与安装选择

当前版 v1.0.152 发布于 2026-09-22，修复 `>` 子组合器的查询错误。官方发布二进制不需要 Office 或 .NET；只有源码构建才需要 .NET 10 SDK。

安装建议：从官方 Release 下载固定版本并核对来源。不要直接把 README 中的远程脚本通过管道交给 shell。`officecli install` 不只复制程序，还会修改 PATH 并给检测到的 Agent 安装技能。

最小工作流

officecli create demo.pptx
officecli add demo.pptx / --type slide --prop title="Test"
officecli view demo.pptx outline
officecli validate demo.pptx
officecli view demo.pptx issues --json

这条路径先创建、再读取结构、校验并查看问题。真实交付还要在 Microsoft Office、LibreOffice 或目标查看器中检查版式，尤其是字体、图表、外部链接、宏和复杂对象。

三层操作与结果语义

L1 是文本、结构、问题和渲染视图；L2 用路径与选择器增删改元素；L3 用 XPath 直接操作 raw XML。JSON 结果里要读取 `success` 和 `warnings`，不能只看退出码 2，因为它既可能表示操作成功但有警告，也可能表示所有属性都被拒绝。

resident、MCP 与预览端口

resident 把文档留在内存；其他程序读取前要 `save` 或 `close`。
batch 默认原子执行，`--best-effort` 会保留部分成功项，含义完全不同。
MCP 暴露全部文档操作，不应给不可信 Agent 或过宽目录。
`watch` 示例在 `localhost:26315` 提供实时预览，文档可能含敏感内容，不要转发到公网。

与 Microsoft Open XML SDK 对比

Open XML SDK 是微软维护的 .NET 底层框架，官方明确说它不直接提供高级抽象或生产力工具，使用者需要熟悉格式标准。OfficeCLI 已经封装 CLI、选择器、JSON、渲染和 Agent/MCP 流程。写定制 .NET 逻辑、精确控制包结构可选 SDK；多语言脚本或 Agent 快速操作文档可评估 OfficeCLI。

验证边界：本轮只核对官方 README、v1.0.152 Release、构建要求和 Open XML SDK README。未下载或运行二进制，未执行安装脚本，未修改 PATH/Agent 配置，未创建 Office 文件，也未启动 preview、resident 或 MCP。

这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。

先判断这个项目是否适合你

适合谁用

适合在 CI 或 Agent 工作流中批量生成报告、更新表格、制作演示文稿、执行模板合并、做 Open XML 校验和渲染检查。对复杂版式、宏、外部链接、OLE 或交付前视觉一致性，仍应使用真实 Office/目标查看器做最终验收。

采用建议

OfficeCLI 的强项是给 Agent 一套一致、可解析的三格式文档接口。采用时应固定 Release、从小样本开始，把安装副作用、MCP 写权限、resident 刷盘和预览端口写进运行规范，并保留目标 Office 应用的最终视觉验收。

原教程未展开的系统信息

核心功能

Agent 可解析结果
命令可返回 JSON、明确 success/error/warnings，并用 0/1/2 退出码区分成功、失败和带警告结果。
原子批量与常驻模式
batch 默认任一失败就回滚；resident 模式把文档留在内存，通过 save/close 或自动策略刷盘，Python/Node SDK 可复用管道。
渲染、预览和 MCP
内置 HTML/PNG 渲染与 `watch` 本地预览，MCP 可把全部文档操作暴露成 JSON-RPC 工具。

架构与数据流

核心是 C#/.NET 10 构建的自包含二进制。文档操作从语义视图、结构化 DOM 到 raw XML 分三层；常驻进程通过命名管道减少重复打开文件，MCP 与薄 SDK 复用命令协议。写操作可能暂存在 resident 内存，外部程序读取前要 `save` 或 `close`。`watch` 会在 `localhost:26315` 打开本地 HTTP 预览；`officecli install` 还会复制二进制并向检测到的 Agent 安装技能。

常见问题

OfficeCLI v1.0.152 运行时需要 Microsoft Office 或 .NET 吗？

官方发布二进制是自包含文件，不需要 Microsoft Office，也不要求另装 .NET；只有从源码编译才需要 .NET 10 SDK。

执行 officecli install 会改哪些地方？

它会把二进制复制到 PATH，并向检测到的 AI 编码工具安装技能；运行前应先备份相关配置并确认需要覆盖哪些 Agent。

officecli watch 的 26315 端口能公开访问吗？

README 示例使用 `localhost:26315`。不要主动把它绑定到公网或通过隧道暴露；预览可能包含敏感文档内容，用完后应关闭。

OfficeCLI 的 resident 模式为什么改完文件后别的程序看不到？

resident 会把修改暂存在内存并延迟刷盘。交给 Word、上传器或其他库前要执行 `officecli save` 或 `officecli close`，也可设置每次修改都刷盘。

官方来源：仓库、v1.0.152、Open XML SDK。