OfficeCLI 开源项目仓库导读：353 个 C# 文件的三层切法

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

这个仓库最值得看的不是它支持多少种 Office 元素，而是它把 353 个 C# 文件按”谁跟谁一起改”切开：命令层只负责把一行命令翻译成一次调用，处理器层一种文档格式一套，核心层只放三种格式都得用的东西。 三条线之间的依赖方向是单向的，所以你想加一个动词、改一种元素的属性、或者调一条全局限额，各自都有唯一一个该去的目录。

先做一次消歧。OfficeCLI 是 GitHub 上 iOfficeAI/OfficeCLI 这个开源项目的专有名字，不是”用命令行操作 Office”这件事的泛称，和微软也没有任何从属、授权或官方合作关系——文中提到 Word / Excel / PowerPoint 时，指的是文件格式和对应的桌面应用，不是这个项目的归属。它的许可证是 Apache-2.0，NOTICE 文件写明 Copyright 2026 OfficeCLI，由 goworm 创建维护。仓库 README 是这样定位自己的：世界上第一个也是最好的、为 AI Agent 设计的 Office 套件——这是项目自己的说法，本文只做转述，不替它背书。

站内已经有三篇同类的仓库导读：opencode 仓库结构 拆的是终端 Agent 的会话与工具注册，hermes 仓库结构 拆的是网关型 Agent 的多前端与状态层，Pascal Editor 仓库结构 拆的是三维场景编辑器的节点模型。这一篇不碰 Agent 主循环，专看一件事：当一个工具要同时伺候三种互不相同的二进制文档格式时，代码该怎么分家。

一、先认清这个仓库的形状

克隆下来先数一遍。全仓 1201 个受版本控制的文件，主体在 src/officecli/：469 个文件，其中 353 个是 .cs。剩下的大头是三类资产——schemas/ 153 个文件（152 份 json）、examples/ 381 个文件、skills/ 下 11 个技能目录各带 1 份 SKILL.md。另有 sdk/ 的 node 与 python 两套、assets/ 37 个文件、根目录四个语言版本的 README（en/zh/ja/ko）和一份根级 SKILL.md。

这些数字都是你自己 ls、find 数得出来的，我列出来是因为比例本身说明问题：非代码资产的数量级和代码相当。原因写在 src/officecli/officecli.csproj 里——skills/**/* 和 schemas/help/**/*.json 都被声明成 EmbeddedResource，直接编进程序集。csproj 的注释解释得很直白：帮助 schema 嵌进来是为了让 SchemaHelpLoader 通过 Assembly.GetManifestResourceStream 读取，不需要在磁盘上解包，因为单文件安装器只发一个可执行文件。

单文件这件事在 csproj 的 PropertyGroup 里是三个开关：PublishSingleFile、SelfContained、PublishTrimmed 全为 true，目标框架 net10.0。自包含（SelfContained）意味着运行时一起打进去，机器上不装 .NET 也能跑；裁剪（PublishTrimmed）会砍掉没被引用到的代码以压缩体积。外部依赖只有两个 NuGet 包：DocumentFormat.OpenXml 负责 OOXML 读写，System.CommandLine 负责命令行解析。

这里需要解释一个贯穿全文的概念：OOXML。.docx / .xlsx / .pptx 这三种文件，本质是 zip 压缩包，里面装着一堆 XML 部件（part）和一堆 .rels 关系文件——关系文件记录”哪个部件引用了哪个部件”。所以这个工具做的事，说到底是”打开 zip、改里面的 XML、按原样写回去”，而它绝大部分复杂度来自”按原样”这三个字。

二、命令层：一个类摊成 18 个文件

src/officecli/Program.cs 是入口，用的是 C# 顶层语句（不写 Main 方法，文件里的语句直接就是程序主体）。它在进入命令解析器之前干了一批进程级的事：把控制台输出编码切成 UTF-8 并在退出时还原回去（注释里说明了不还原会污染用户终端的代码页）、把线程文化固定成 Invariant（避免荷兰语/德语环境下小数点变成逗号，导致 CSS 里出现 141,73pt、JSON 里出现 0,5）、调用 PipeTempDirGuard.EnsurePipePathFits() 确保命名管道路径不超过内核上限。

然后是一段”早期分发”：mcp、install、skills / skill、load_skill、config 这几个动词在根命令构建之前就被 if 拦下并直接返回，根本不进解析器。同一段里还有两个约定值得记：--output-schema-crc 会打印嵌入的 schemas/help 树的 CRC32，注释说明这是给下游自动化用来判断”属性面有没有漂移”的指纹，不是版本号、没有先后语义；--help / -h / -? 会被改写成 help 子命令，而且只检查 args[0] 和 args[1]——注释解释了为什么不全量扫描：set foo.docx /body --prop --help 里的 --help 是一个选项的值，全量改写会把它变成帮助输出。

真正的命令层是 CommandBuilder。它声明成 static partial class——分部类是 C# 的一个特性，允许把同一个类的代码分散在多个文件里，编译时再拼成一个类。这个类摊在 18 个文件里：CommandBuilder.cs 加上同目录的 CommandBuilder.Add.cs、.Batch.cs、.Check.cs、.Dump.cs、.GetQuery.cs、.Goto.cs、.Help.cs、.Import.cs、.IntegrationStubs.cs、.Mark.cs、.Plugins.cs、.Raw.cs、.Refresh.cs、.Save.cs、.Set.cs、.View.cs、.Watch.cs，共 17 个后缀文件。用 grep -r "partial class CommandBuilder" 数出来也正好 18 处。

CommandBuilder.cs 里的 BuildRootCommand() 就是那张分发表：它自己内联定义了 open、close 和隐藏的 __resident-serve__ 三个命令，其余全部是一行一个 rootCommand.Add(BuildXxxCommand(jsonOption))。所以定位任何一条命令的实现，路径是固定的两步——在这张注册表里找到 BuildXxxCommand，再去同名后缀的文件里看。

这里有一处容易找错地方的约定，值得单独点出来：根命令是在 CommandBuilder 里组装的，但真正调用 Parse 的那一行在 Program.cs 末尾，而且显式传了 ResponseFileTokenReplacer = null。注释说明了原因——以 @ 开头的 token 必须原样送到 handler，因为 set row[N] --prop @height=25 用 @ 强制走行属性那一侧（行属性和列属性存在同名遮蔽，@ 是消歧转义），默认的响应文件替换器会把它当成”找不到的响应文件”直接报错。所以查”某个参数为什么没被当成参数”这类问题时，只翻 CommandBuilder.*.cs 是翻不到的。

CommandBuilder.cs 自己收着的是两个跨入口共用件：SafeRun 统一兜底异常，ApplySetWithCorrection 做属性名的编辑距离 1 自动纠错（colot → color，且只在候选唯一、纠正后确实生效时才替换）。注释明说这是非常驻 CLI、批处理执行器、MCP 单条命令、常驻服务四个入口共用的唯一实现，理由是它们过去是手工镜像的几份拷贝，靠注释标记保持一致，最终还是会漂移。

三、处理器层：三种格式，三套处理器

分诊口是 src/officecli/Handlers/DocumentHandlerFactory.cs，只有一个公开方法 Open(string filePath, bool editable = false)。它在把文件交给具体处理器之前，串了一条相当长的检查链：

空路径直接抛 file_required（注释说这最常见于 MCP/批处理调用把 file 写进了单条命令而不是顶层）；文件不存在抛 file_not_found；0 字节抛 corrupt_file——因为 Open XML SDK 在读写模式下会默默接受空文件并造出一个空包，后续命令全部”成功退出 0”，实际文档不可用。

接着是三道拒绝服务防护，阈值集中写在 src/officecli/Core/DocumentLimits.cs：包内条目数上限 MaxZipEntries 为 100000；解压后总字节上限 MaxUncompressedBytes 为 2 GiB；整体压缩比上限 MaxCompressionRatio 为 1000 倍，且只在压缩后大小超过 64 KB 时才检查（几 KB 的高可压缩 XML 天然会超比例）。这三道只管字节，管不住内存，所以还有第四道 GuardElementExplosion：用 XmlReader 流式数元素个数，超过 MaxDomElements（默认 3000000，可用环境变量 OFFICECLI_MAX_DOM_ELEMENTS 抬高）就拒绝。注释解释了这一道为什么必要——一个塞满 <c><v>0</v></c> 的工作表可以在所有字节限额之下，把托管堆撑到好几 GiB，把常驻服务直接 OOM 掉。

再往下是两处”真实世界修复”，也是本文最想让你注意的设计点，因为它直接决定了这个工具动不动你的原文件：

• 悬空关系（.rels 里指向一个包里根本不存在的部件）。Word / PowerPoint 容忍这种文件，SDK 不容忍。工厂的处理是分模式的：editable 打开时调用 StripDanglingPackageRels(filePath) 原地改源文件（反正保存时也要重写）；只读打开时先 CreateReadOnlyRepairCopy 复制一份到临时目录（文件名形如 ocli_ro_<guid>.docx），只修副本，源文件保持字节不变，临时文件登记到进程退出时清理。
• encoding="ascii" 的 XML 声明。注释点名这是 python-pptx（底层 lxml）生成的文件的特征，SDK 会拒绝，于是 FixXmlEncoding 把它改写成 UTF-8——同样是可编辑改原文件、只读改副本。

过完这条链才轮到真正的分派，是一个朴素的 switch：.docx/.docm → WordHandler，.xlsx/.xlsm → ExcelHandler，.pptx/.pptm → PowerPointHandler，其余落到 TryOpenViaPlugin，还找不到就抛 unsupported_type。启用宏的三种扩展名复用同一个处理器，注释说明理由是 SDK 按内容类型识别文档、保存时原样回写 vbaProject 部件；但这条只对”打开”生效，dump / create / merge 仍走无宏白名单，避免任何”重建成新文件”的路径把宏弄丢——这是有意划的安全边界。

三个处理器同样用分部类摊开。数一下：grep 出 55 处 partial class PowerPointHandler、47 处 partial class WordHandler、45 处 partial class ExcelHandler。对应目录里 Handlers/Pptx/ 有 64 个 .cs、Handlers/Word/ 54 个、Handlers/Excel/ 47 个。文件名本身就是一张功能地图，比如 Word 那一摞：WordHandler.Add.Markdown.cs、WordHandler.Helpers.FindReplace.cs、WordHandler.HtmlPreview.Tables.cs、WordHandler.Set.Revision.cs、WordHandler.I18n.cs。

三个处理器实现同一个接口 IDocumentHandler（在 src/officecli/Core/IDocumentHandler.cs）。接口的文档注释里写了另一个三层，和目录上的三层是两回事，别混：语义层（ViewAsText / ViewAsAnnotated / ViewAsOutline / ViewAsStats / ViewAsIssues）、查询层（Get / Query / Set / Add / Remove / Move / CopyFrom）、原始层（Raw / RawSet / AddPart）。目录的三层切的是”代码归谁维护”，接口的三层切的是”调用方要多接近 XML”。两者正交，这也是为什么处理器层能长到 160 多个文件还不塌——每个文件同时被两个维度定了位。

四、核心层与外围资产

src/officecli/Core/ 连同八个子目录（Chart、Diagram、Formula、Markdown、Plugins、Rendering、TableStyles、Watch）一共 153 个 .cs，体量上仅次于 Handlers/ 的 171 个——两块加上 src/officecli/ 根目录的 25 个和 Help/ 的 4 个，正好凑齐 353。判断一段逻辑该不该进 Core 的标准很清楚：三种格式都要用，或者根本与格式无关。

组成部分	它负责什么	对应仓库位置	你什么时候会碰到它
入口与早期分发	编码、文化、管道路径的进程级设置；mcp/install/skills/load_skill/config 在进解析器前拦截	src/officecli/Program.cs	某个子命令的行为和其它命令不一致时
命令层	用 System.CommandLine 组根命令，一个动词一个子命令	src/officecli/CommandBuilder.cs 及同目录 17 个 CommandBuilder.*.cs	加动词、查某个参数在哪解析
打开与分诊	路径校验、压缩炸弹拦截、悬空关系与编码修复、按扩展名选处理器	src/officecli/Handlers/DocumentHandlerFactory.cs	文件打不开，报 corrupt_file / decompression_bomb
三套文档处理器	Word / Excel / PowerPoint 各自实现同一接口	Handlers/WordHandler.cs、Handlers/Word/、Handlers/Excel/、Handlers/Pptx/	某个属性不被支持，或要新增一种元素
核心层	选择器过滤、公式、图表、渲染、批处理、常驻策略、资源限额	src/officecli/Core/（含八个子目录）	改跨格式的通用行为或全局约束
常驻与 MCP	命名管道服务端与客户端、MCP 服务器与安装器	src/officecli/ResidentServer.cs、ResidentClient.cs、McpServer.cs	排查落盘时机、把工具接进 Agent
二进制之外的资产	技能包、帮助 schema、示例、双语言 SDK	skills/、schemas/help/、examples/、sdk/	想知道 Agent 拿到的能力清单从哪来

Core 里有几个文件值得单独点名，因为它们定义的是这个工具的行为边界而不是功能：

Core/AtomicPackageWriter.cs 管崩溃原子性。常驻模式把文档留在内存里、把写盘推迟到 save/close/空闲自动保存，所以那次写盘绝不能原地覆盖——注释写得很清楚：写到一半进程死掉，原字节已经没了，留下一个打不开的截断文件。它的做法是先把完整包序列化到同目录临时文件，必要的后处理也在临时文件上做完，最后一次 File.Replace 换过去，任何时刻崩溃你拿到的要么是旧文件要么是新文件。

Core/SsrfGuard.cs 管外网。ImageSource（picture=）和 FileSource（table data=、model3d=、media=）都会按调用方给的 URL 去拉字节。注释直言这个 URL 可能来自不可信输入——批处理脚本、嵌在文档里的指令、一次工具调用的参数——所以未加防护的抓取就是一个 SSRF 原语（服务端请求伪造：借工具的网络位置去探测内网或云元数据端点）。防护写在 ConnectCallback 里，在真正连接的那一刻校验实际 IP，重定向的每一跳都校验，非公网地址一律拒绝；在连接时刻校验而不是提前解析域名，也顺手关掉了 DNS 重绑定的时间窗。这一段建议和 Agent 工具的最小权限设计 对照着读。

Core/CompoundFile.cs 是自实现的复合文件读写器。复合文件（CFB / OLE 结构化存储，文件头是 D0 CF 11 E0）是比 OOXML 更老的一种容器格式，这里只用在 OLE 嵌入这一个场景。注释说明它替换掉了原先的第三方依赖，为的是把这条路径完全握在自己手里。

Core/DocumentLimits.cs 除了前面那几个限额，还定义了 MaxRecursionDepth 为 256。理由写在注释里：深度嵌套的表格或组合形状会把递归遍历器和渲染器打进 StackOverflowException，而这个异常在 .NET 里捕不住、会直接杀进程——对长期运行的常驻服务是致命的，所以每个递归遍历器都自己检查深度并改抛一个正常异常。

五、边界与代价

这套切法不是没有代价，几条要说在前面。

它改的是你磁盘上的真实文件。 前面提到，editable 打开时的悬空关系修复和编码修复都是原地重写源文件，没有自动备份。只读路径确实保证源文件字节不变（走临时副本），但你得清楚自己那条命令是哪一侧。重要文件先复制一份，这个习惯在这个工具上是必要的，不是洁癖。

常驻模式下”命令返回”不等于”文件已经变了”。 open 会 fork 一个 __resident-serve__ 子进程把文档留在内存里；TryResident 在没有常驻时还会自动起一个（空闲 60 秒退出），open 显式起的那个空闲超时是 12 分钟。落盘时机由 Core/ResidentFlushPolicy.cs 决定，命令帮助文本写明是 save / close / 空闲自动保存三选一，空闲自动保存是自适应的 2 到 10 秒，可以用环境变量 OFFICECLI_RESIDENT_FLUSH 设成 each / auto / <秒数> / off。这意味着：officecli 自己的读命令永远看得到最新状态，但任何非 officecli 的程序直接读盘，在 flush 之前看到的是旧文件。想用别的程序接手，先 save 或 close。

批处理中途失败留下什么，取决于你用了哪个开关。 batch 默认是原子的——注释说明理由是”部分应用是对程序化调用方最脏的结果：文档停在一个调用方没要求过的状态，而失败结论和磁盘上真正落下的东西不一致”。--best-effort 恢复旧的”成功的先应用”语义，--stop-on-error 在第一次失败时中止（配 --best-effort 时先前的条目会留下，默认原子模式下则两边都不留）。选错开关，回滚假设就反了。

它会自己动你的机器。 Program.cs 里有 Installer.MaybeAutoInstall(args)：如果当前不是从 ~/.local/bin/officecli 运行，它会把自己复制过去。紧接着还有 UpdateChecker.CheckInBackground()，会派一个后台进程检查并可能触发升级，除非设 OFFICECLI_SKIP_UPDATE=1。这两件事对在受管环境或 CI 里跑的人是需要知道的。

明确不管的事。 非原生扩展名不由主程序处理，只走插件旁路（协议见 plugins/plugin-protocol.md）；插件分 dump-reader 和 format-handler 两类，读这一段必须连代码一起看：TryOpenViaPlugin 方法头上的文档注释还写着 format-handler”尚未接线、解析到也只会抛一个明确错误”，但方法体里那条分支已经在构造 FormatHandlerSession 并返回 FormatHandlerProxy 了。注释比实现旧一步，以代码为准——高频迭代的仓库里这种时间差很常见，把注释当契约读迟早会踩。dump-reader 这一类的工作方式则有副作用要知道：它把外部格式转成一个同名的原生兄弟文件（<源文件名>.<目标扩展名>）放在源文件旁边，后续所有编辑都落在这个兄弟文件上，不是原始源文件，并且会在 stderr 打一行提示。

六、上手与避坑清单

• 找不到某条命令的实现，因为你在 CommandBuilder.cs 里翻。 会踩是因为这个类是分部类，18 个文件共用一个类名，符号跳转在不熟悉的编辑器里未必给全。避的方法：先在 BuildRootCommand() 的注册列表里找到 BuildXxxCommand，文件名就是 CommandBuilder.Xxx.cs，两步定位，不要全仓搜。
• 以为只读命令绝对不碰文件。 会踩是因为”修复”这件事分模式：editable 走原地改，只读走临时副本。避的方法：确认你那条命令走的是哪一侧；对不能出事的文件，先手工复制一份再操作。
• 编辑完立刻用别的程序打开，发现内容没变。 会踩是因为常驻进程把改动留在内存、把写盘推迟了。避的方法：交接给非 officecli 的程序之前显式 save（保留常驻）或 close（落盘并释放文件），或者把 OFFICECLI_RESIDENT_FLUSH 设成 each。
• 批处理跑挂了，以为前面几步已经生效。 会踩是因为默认是原子模式，前面几步一起回滚；而如果你加了 --best-effort，结论又反过来。避的方法：把这两个开关当成”回滚策略声明”来写，别当成调试选项随手加。
• 超大工作簿被拒，报”XML 元素过多”。 会踩是因为 MaxDomElements 默认 3000000，这是为了保护常驻服务不被 OOM。避的方法：确认文件确实是正常业务文件之后，用 OFFICECLI_MAX_DOM_ELEMENTS 单独抬高，而不是绕过整条打开路径。
• 在深层嵌套的沙箱目录里，常驻或监听起不来。 会踩是因为 Unix 下命名管道套接字放在 $TMPDIR，路径太长会超过内核上限。Program.cs 里 PipeTempDirGuard.EnsurePipePathFits() 就是为这个装的（注释引了 issue #263）。避的方法：缩短 TMPDIR，或者用 OFFICECLI_NO_AUTO_RESIDENT=1 关掉自动常驻，退回直连文件模式。
• 给 Agent 接线时把 --help 当参数值传进去。 会踩是因为 Program.cs 会把 args[0] 或 args[1] 位置上的 --help 改写成 help 子命令。避的方法：知道它只改写这两个位置——写在更后面的 --help 会原样传给 handler，这既是保护也是陷阱，取决于你本来想要哪个。
• 常驻活着但命令投递不进去，退出码 3。 会踩是因为 TryResident 在确认常驻存活后不会静默回退到直连文件（注释说明旧的静默回退会和常驻抢写、丢数据），投递失败就报”忙”。避的方法：把退出码 3 单独识别成”重试或先 close”，不要和命令级失败混在一个分支里处理。

最后：按什么顺序读这个仓库

如果你要给自己的 Agent 接这个工具，读四个文件就够搭起心智模型：src/officecli/Program.cs 看进程级约定和早期分发，src/officecli/CommandBuilder.cs 看命令注册表和常驻转发协议，src/officecli/Handlers/DocumentHandlerFactory.cs 看打开一份文档要过多少道关，src/officecli/Core/IDocumentHandler.cs 看三个处理器共同承诺了什么。想看它给 Agent 的提示词长什么样，再去 skills/ 下的 11 个 SKILL.md 和 schemas/help/。

搬这套结构到自己项目之前，先问三个问题：你的”格式维度”是不是真的有三条互不相同的分支（否则分部类摊开只会让人找不到代码）；你的公共层能不能像 IDocumentHandler 那样用一个接口把承诺写死（否则核心层会变成杂物间）；你的写盘路径有没有 AtomicPackageWriter 那样的原子保证（这是常驻模式敢存在的前提）。三条都成立，这套切法才是资产。

关于工具在返回结构上要给 Agent 什么，可以接着看 Agent 工具返回值怎么设计；关于让 Agent 直接改磁盘文件时该怎么约定边界，见 Agent 改动边界的约定写法。

本篇属于一个把开源Office 文档读写套件 OfficeCLI逐层拆开讲的系列，整体地图见 OfficeCLI 是什么：给 AI Agent 用的开源文档读写套件；沿着这条线往下，还可以看 开源项目 OfficeCLI 与 Pascal Editor：Agent 操作专业软件的两条路 和 开源项目 OfficeCLI：152 份 json 撑起的文档即契约设计。