开源项目 OfficeCLI 的两套 SDK：什么时候别直接调命令

本文基于 OfficeCLI 仓库 commit 459b1a4（2026-08-04）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/iOfficeAI/OfficeCLI 最新代码与文档为准。

这里说的 OfficeCLI 是 GitHub 上那个开源仓库 iOfficeAI/OfficeCLI。它这两套 SDK 不是给你换一套 API，而是替你省掉「每条命令启动一次进程」。它们对外只有 send 和 batch 两个动词，你要写的命令对象跟命令行 batch 里的那一项完全一样。所以判断该不该上 SDK，只有一条线：你是不是要对同一个文件连续下很多条指令。

名词消歧还得再说透一层，这件事在这个项目上特别容易出岔子。OfficeCLI 是那个开源仓库的专有名字，既不是”用命令行操作 Office”这个泛称，也和微软没有任何从属、授权或官方合作关系——后面提到 Word、Excel、PowerPoint 时，指的都是 .docx / .xlsx / .pptx 这三种文件格式和对应的桌面应用，不是这个项目的归属。仓库根目录的 LICENSE 是 Apache-2.0，NOTICE 里写着 Copyright 2026 OfficeCLI，由 goworm 创建维护。仓库 README 把自己定位成”为 AI agent 设计的 Office 套件”，还用了 first and best 这样的措辞——那是项目自己的说法，本文不替它背书，只描述代码里能查到的机制。

一、这两套 SDK 到底”薄”到什么程度

sdk/python/README.md 开头就把话说死了：它是一个 thin 客户端，只做一件事——把一条 officecli 命令通过命名管道转发给正在运行的常驻进程，再把响应递回来。

“薄”体现在词汇量上。sdk/python/officecli.py 的模块 docstring 里那句写得很直白：没有第二套词汇要学，一条命令就是你会放进 officecli batch 列表里的那个字典。也就是说，你不会看到 doc.set_cell()、doc.add_paragraph() 这类按元素类型铺开的几十个方法，只有一个统一动词：

with officecli.create("report.xlsx", "--force") as doc:
    doc.send({"command": "set", "path": "/Sheet1/A1",
              "props": {"text": "Region", "bold": "true"}})

这个取向有清晰的代价交换。好处是命令行侧新增的命令和字段，SDK 不用改一行就能用——send() 的实现里，除了 command（或 op）和 props，其余键一律原样转发为命令参数，客户端不维护任何字段白名单。坏处是你的编辑器给不了任何提示，字段名写错要等运行时才知道，后面第五节会展开。

两套 SDK 都把接口切成两个面，Python 的 docstring 里管它叫 two surfaces：

• bootstrap（低频）：create() / open() 会真的启动一次 CLI 进程。一个还没被打开、甚至还不存在的文件，本来就没有常驻进程可以对话。
• hot path（高频）：send() / batch() 是纯粹的管道往返，不再有任何进程启动。

理解这两个面的分工，基本就理解了这两套 SDK 存在的全部理由。

二、常驻进程加命名管道：SDK 真正替你做的那部分

先解释两个词。常驻进程（resident）是 officecli 把文档解析进内存后留在后台不退出的那个进程，后续命令直接操作它内存里的文档树，省掉反复解析的开销。命名管道是同一台机器上进程之间的一条通信通道，不走网络端口，用一个名字来寻址。

SDK 的核心难点就在于：怎么算出该连哪条管道。officecli.py 顶部的 docstring 把协议列得很完整，两套 SDK 用的是同一套推导：

pipe name : officecli-<SHA256(fullpath)[:16] uppercase>
unix path : $TMPDIR/CoreFxPipe_<name>  (+ "-ping");  $TMPDIR else /tmp
win path  : \\.\pipe\<name>            (+ "-ping")
framing   : one request line + one response line, UTF-8, '\n' terminated
request   : PascalCase {"Command","Args","Props","Json"}
response  : {"ExitCode","Stdout","Stderr"}

也就是：把文件的绝对路径做 SHA256，取前 16 位十六进制转大写，前缀 officecli-；macOS 和 Windows 上路径先整体转大写（Linux 大小写敏感，不转）。一次连接只发一条命令，请求和响应各占一行。除了主管道，每个文档还有一条同名加 -ping 后缀的旁路管道——它在主管道被占满时也能应答，SDK 靠它区分”常驻进程死了”和”常驻进程活着但正忙”。

这个区分决定了失败时的行为，两套 SDK 完全一致：

• 常驻进程已经没了（崩溃、空闲超时退出、管道文件是残留的）：透明重启一次并重试，调用方看不到错误。
• 常驻进程活着但主管道不响应：直接抛 OfficeCliError。注释里写明了原因——绝不绕过活着的常驻进程去直接写文件，第二个写入者会在它后续保存时把数据覆盖掉。

超时和重试的数值不是拍脑袋的，SDK 是照抄 CLI 的策略：连接超时 30 秒、最多重试 3 次、退避 50 * (n + 1) 毫秒。这三个值在 src/officecli/CommandBuilder.cs 里能找到对应常量（ResidentBusyConnectTimeoutMs = 30000、ResidentBusyMaxRetries = 3）。还有一个容易被忽略的细节：重试只重连、不重发。连接阶段发生在命令真正执行之前，所以重连是安全的；而一旦请求已经写出去、对端却空着连接关掉了，SDK 宁可抛错也不重发，因为那条命令可能已经生效，重发会把一个非幂等操作做两遍——所谓非幂等，就是同一条指令执行两次的结果不等于执行一次，比如”在末尾追加一段”。这一点值得你抄进自己的工具层——重试与幂等怎么配 里讨论的正是同一类问题。

空闲超时也做了区分：create() 顺带起的常驻进程默认只活 60 秒（CommandBuilder.cs 里 TryStartResidentProcess(filePath, idleSeconds: 60, ...)），而 open() 会通过 ping 管道发一条 __set-idle-timeout__ 把它抬到 12 分钟（DefaultOpenIdleSeconds = 12 * 60）。SDK 的 open() 复刻了这个动作，免得你用 create() 起了会话、编辑到一半被 60 秒掐掉。这个值也能用环境变量 OFFICECLI_RESIDENT_IDLE_SECONDS 覆盖。

三、Node 和 Python 各包了什么，差在哪

先看两套 SDK 的物理构成，路径都在仓库 sdk/ 目录下：

组成部分	它负责什么	仓库位置	你什么时候会碰到它
Python 单文件模块	管道地址推导、传输层、Document 会话、二进制解析与自动安装	sdk/python/officecli.py	任何 Python 侧调用
Python 打包声明	分发名 officecli-sdk、零三方依赖、requires-python >=3.8	sdk/python/pyproject.toml	装包时名字对不上
Node 实现	同一套协议的 async 版本	sdk/node/index.js	任何 Node 侧调用
Node 类型声明	BatchItem / Result / OpenOptions / BatchOptions	sdk/node/index.d.ts	在 TypeScript 里想要补全
Node 包声明	依赖 @officecli/officecli、engines: node >= 18	sdk/node/package.json	追问二进制从哪来
两个可跑的例子	建表头、写公式、读回、in-session validate 全流程	sdk/python/demo.py、sdk/node/demo.js	第一次上手照抄
两个冒烟脚本	在没装 CLI 的机器上验证自动安装加管道往返	sdk/python/smoke.py、sdk/node/smoke.js	想在 CI 里验证整条链路

功能面几乎是对称的，两边都提供 create / open / install / Document / OfficeCliError，Document 上都有 send / batch / alive / close。真正的差异集中在这几处，都会实打实影响你的代码：

二进制从哪来。 Node 侧 package.json 把 @officecli/officecli 列为依赖，README 说这个包捆绑了会自动更新的原生二进制，装 SDK 就等于把 CLI 一起装了；index.js 的 resolveBinary() 里也把这个捆绑二进制排在 PATH 查找之前。Python 侧不一样，pip install officecli-sdk 只装那个单文件模块，二进制要么已经在 PATH 上，要么由 SDK 在首次使用时跑官方安装脚本装上。

同步还是异步。 Python 版是同步的，Document.__init__ 里直接调了 _start()，构造对象就完成了 bootstrap。Node 版全异步，构造函数只算管道地址、不做任何网络动作，_start() 由 create() / open() 去 await——所以在 Node 里 new Document(...) 然后直接 send 是不对的。

会话语法糖。 Python 用 with，__exit__ 里调 close()；Node 在 18 及以上可以 try/finally 手动收尾，在 24 及以上能用 await using（Document 实现了 Symbol.asyncDispose）。

Windows 上的进程启动。 index.js 里有一段 Python 版没有的处理：自 CVE-2024-27980 之后 Node 拒绝不经 shell 直接启动 .cmd / .bat，于是 spawnCli() 自己走 cmd.exe，并且对每个 token 单独加引号（quoteForCmd），注释里解释了为什么是无条件加引号而不是”看起来危险才加”——被双引号包住的 token 不会被 cmd 重新切分。

并发保护的实现方式。 两边都防”多个调用方同时发现常驻进程死了、各自启动一个”这种情况，Python 用 threading.Lock，Node 用一个记在实例上的 in-flight promise。

还有一处不一致值得你知道：sdk/node/README.md 和 index.d.ts 都把 install() 标成 unix only，但 index.js 里的 install() 实现有完整的 Windows 分支（用 PowerShell 跑 install.ps1）。以实现为准。

四、什么时候用 SDK，什么时候直接调命令

判断线其实就是那两个面的分界：

一次性的、一条命令能收工的事，直接调命令。 SDK 的 create() / open() 本身就要启动一次 CLI 进程，你为了下一条命令而引入一个依赖、写一段生命周期管理，收益是负的。

对同一个文件连续下几十上百条指令，用 SDK。 这是它唯一真正的价值：bootstrap 一次，后面每条都是纯管道往返。sdk/python/demo.py 是个标准形状——把表头、五行数据、每行的 =B{i}*C{i} 公式、合计行的 =SUM(...) 全部拼成一个 items 列表，doc.batch(items) 一次打过去。

常驻进程是别人起的，用 borrow 模式。 Python README 里写得很清楚：不用 with、也不调 close()，你就只是借用一个别的程序拥有的常驻会话。反过来，只要你写了 with 或 finally 里的 close()，退出时那个常驻进程就被停掉了。

你的调用方是 agent 而不是你的程序，先考虑 MCP。 仓库里带了内置的 MCP server（src/officecli/McpServer.cs，注册命令是 officecli mcp claude 这一类），把文档操作暴露成工具。SDK 面向的是”你自己写的那段代码”，不是面向模型的工具协议。这两条路的取舍标准，可以参考 MCP 与 function calling 怎么选。

顺带说清本篇和站内几篇相近文章的分工：这里只拆 OfficeCLI 这一个仓库里的两套 SDK 具体包了什么，不做跨项目的抽象层选型——想在”用厂商 SDK 还是上多智能体框架”这个层面做决策，看 Agent SDK 还是多智能体框架；想看另一个开源项目怎么把 server 和 SDK 拆开、让多个前端共享同一会话，看 opencode 的 server 与 SDK 共享模型；想在 HTTP API、命令行、SDK 这几种接入方式之间横向比较成本和耦合度，看 几种 API 接入方式的对比。

五、边界与代价：它明确不管的事

它不校验任何东西。 转发层不维护字段表，props 里的键写错了、path 选择器写错了，SDK 一律照发。Node 的 index.d.ts 虽然给了 BatchItem 接口，但里面有 [key: string]: unknown 索引签名，等于放行任意键——类型系统在这里帮不上忙。

业务失败不是异常。 两边 README 都强调：只有传输和进程层面的失败才抛 OfficeCliError（.code 带着退出码），业务结果（比如 validate 没过、路径不存在）活在返回结果的 success 字段里，跟 CLI 的退出码一个语义。你必须自己判 result.success，不能靠 try/catch 兜住。

管道名推导是硬耦合。 Python README 专门有一节 Versioning 说这件事：客户端按 officecli 的方式从文档路径推导管道地址，这是唯一一处耦合内部实现的地方，所以客户端版本要和你装的 officecli 保持兼容。

它只在本机。 命名管道没有跨机能力，也没有任何网络传输层。想远程调用，得自己在上面套一层服务。

改的是原文件，不是副本。 这一点必须说清楚：officecli.create() / open() 操作的就是你磁盘上那个真实的 .docx / .xlsx / .pptx。而落盘时机是延迟的——常驻进程把改动留在内存，只在 save、close 或空闲自动保存时才真正写回磁盘。仓库 README 里写明自动保存是”进入空闲后自适应 2–10 秒，按文档实测的保存成本缩放”，并且明确提醒：在让 officecli 之外的程序（python-docx、openpyxl、Word、渲染器、上传流程）读这个文件之前，要先 flush。想让每条命令返回前都落盘，可以设 OFFICECLI_RESIDENT_FLUSH=each；officecli 自己的 get / query / view 则始终读得到最新改动。

批量中途失败会发生什么。 命令行侧的 batch 现在默认是原子的：任一项失败就整批回滚，--best-effort 才保留已成功的项。常驻侧的 ResidentServer.ExecuteBatch 实现方式是先做一次刷盘屏障（让磁盘状态等于批前状态），失败时丢弃内存里被污染的文档树、重新加载磁盘文件。两套 SDK 的 batch() 都不发 bestEffort，所以只要批里含有会改动文档的项，走的就是这条原子路径。

自动安装会拉取外部资源。 CLI 找不到时，SDK 会在 stderr 打一行提示然后执行官方安装脚本：unix 是 (curl -fsSL https://d.officecli.ai/install.sh || curl -fsSL <GitHub raw 兜底>) | bash，Windows 是用 powershell -NoProfile -ExecutionPolicy Bypass 拉取并执行 install.ps1。它不会静默进行，但这确实是一次”从网上取脚本并执行”的暴露面。传 auto_install=False（Python）或 autoInstall: false（Node）可以关掉。

六、上手与避坑清单

装包名和导入名不一致。 为什么会踩：pip install officecli-sdk，但代码里是 import officecli。pyproject.toml 的注释解释了原因——PyPI 拒绝了裸名 officecli，因为和一个不相关的项目太像。怎么避：记住这对名字，就像 pillow 对 PIL。

别 from officecli import open。 为什么会踩：这个模块自己定义了一个叫 open 的函数（模块内部特意把内建的存成了 _builtin_open），你要是把它直接导进自己的命名空间，本文件里所有读文件的 open() 都会被换掉。怎么避：一律 import officecli 后用 officecli.open(...)。

Node 里别自己 new Document()。 为什么会踩：Python 的构造函数里就做了 bootstrap，看惯 Python 例子的人会以为 Node 也一样，结果构造出来的 handle 从没连过常驻进程。怎么避：只用 await oc.create(...) / await oc.open(...) 拿 handle。

别把整行 CLI 塞进 command 字段。 为什么会踩：batch 的帮助文本（在 src/officecli/CommandBuilder.Batch.cs 里的 BatchHelpDescription，这是个 C# 分部类——同一个类拆到多个文件的写法）直接点名这是最常见的错误：写成 {"command":"add /slide[1] --type shape --prop ..."} 会报 Unknown command。怎么避：command 只放裸动词，参数是它的兄弟字段（parent / path / type / props / to / after / before）。

batch() 的 force 默认是 true，它不只是”继续执行”。 为什么会踩：两套 SDK 的 batch() 默认都往参数里塞 force=true，看名字容易当成无害的兼容开关；但在 ResidentServer.ExecuteBatch 里，Word 文档保护检查的条件是 if (!force && _handler is WordHandler)——也就是说 SDK 默认就把这道闸门跳过了。怎么避：处理带保护设置的 Word 文档时，显式传 force=False / force: false，让保护检查生效。

交给别的程序读之前先 save 或 close。 为什么会踩：你在 SDK 里 send 完看着返回成功，转手用 openpyxl 去读，读到的是几秒前的旧内容——改动还在常驻进程内存里。怎么避：交接前显式发一条 {"command": "save"}（保住常驻进程继续用）或 close()（刷盘并释放），或者整条流水线设 OFFICECLI_RESIDENT_FLUSH=each。

别在 CI 里放任自动安装。 为什么会踩：构建机上没有 CLI，第一次 create() 就会去网上拉安装脚本执行，成功与否取决于当天的网络，失败信息还埋在 stderr 里。怎么避：在镜像里预装好二进制并显式指定 binary="/path/to/officecli"，同时把 auto_install / autoInstall 关掉，让缺失变成一个清晰的报错而不是一次隐式下载。

收尾：按这个顺序读代码

如果你决定试一下，读文件的顺序建议是：sdk/python/README.md 建立整体印象 → sdk/python/officecli.py 顶部那段 docstring（协议、管道命名、两个面，一屏看完）→ sdk/python/demo.py 抄一个能跑的形状。用 Node 的话，把中间那步换成 sdk/node/index.d.ts，接口面比 README 更准。想弄明白 SDK 之外发生了什么，再去看 src/officecli/ResidentServer.cs 的 ExecuteBatch 和 src/officecli/CommandBuilder.Batch.cs 的批处理帮助文本——原子回滚和保护闸门的真相都在那里。

动手前的三个自检：你这段代码到底要对同一个文件发几条命令（一条就别上 SDK）；这个文件之后会不会被 officecli 之外的程序读（会就得管落盘时机）；这个常驻进程是你起的还是你借的（借的就别 close）。这三个问题答清楚了，剩下的都是拼命令对象的体力活。

本篇属于一个把开源Office 文档读写套件 OfficeCLI逐层拆开讲的系列，整体地图见 OfficeCLI 是什么：给 AI Agent 用的开源文档读写套件；沿着这条线往下，还可以看 开源项目 OfficeCLI 的 11 个技能包：里面写了什么，和命令行工具怎么分工 和 开源项目 OfficeCLI 排障：用它自带的体检命令定位文档问题。