OfficeCLI 插件实战：3 步扩展 .doc 与 .hwpx 支持（附避坑清单）

OfficeCLI 插件实战3 步扩展 .doc 与 .hwpx 支持附避坑清单【免费下载链接】OfficeCLIOfficeCLI is the first and best Office suite purpose-built for AI agents to read, edit, and automate Word, Excel, and PowerPoint files. Free, open-source, single binary, no Office installation required.项目地址: https://gitcode.com/GitHub_Trending/of/OfficeCLI客户发来的合同还是 2003 年版的.docAI 代理读不了韩国同事的文档是.hwpx连工具都不知道它是什么。OfficeCLI 的插件系统就是解决这类问题的主程序保持轻量用独立的小程序去啃生僻格式不动核心代码也不必为每个罕见格式捆绑大依赖。 5 分钟跑通第一个插件流程一共四步拿仓库、装插件、验证、使用。git clone https://gitcode.com/gh_mirrors/of/OfficeCLI officecli plugins install officecli-doc officecli plugins list officecli view report.doc第一行是仓库地址第二行装一个处理.doc的插件。不想走安装器把可执行文件放到~/.officecli/plugins/dump-reader/doc/plugin同样有效。plugins list会以表格列出名称、版本、类型、扩展名看到条目说明已被发现。最后一条命令直接读.doc文件后台由插件完成格式转换你只操作原生格式。不确定哪种插件干什么用先查这张表插件类型能力适用场景通信方式dump-reader外来格式转为原生 docx/xlsx/pptx.doc、.rtf、.odt一次性迁移stdout 输出 JSONL干完即退出exporter原生格式转导出目标格式.docx导出为.pdf、.epub直接命令行调用无对话format-handler外来格式完整读写编辑.hwpx、.hwp长期处理stdin/stdout JSONL 长连接一条转换命令背后的完整链路把插件想成一位临时翻译官主程序不懂.doc请翻译来一句一句转述自己照转述落笔写进 docx。以最常见的 dump-reader 链路为例你执行officecli view report.doc主程序先查旁边有没有比原件更新的report.docx有就直接打开跳过后面步骤。没有就按发现顺序找插件环境变量$OFFICECLI_PLUGIN_DUMP_READER_DOC、用户目录~/.officecli/plugins/dump-reader/doc/plugin、主程序旁的捆绑插件目录、PATH 下的officecli-doc首个命中生效。主程序以plugin dump 源文件启动插件插件解析文件向 stdout 逐行输出add/set命令每行单独 flush。主程序建好空白 docx 骨架逐行重放这些命令把成品存成与原件同目录的report.docx。下次再打开report.doc时直接命中兄弟文件转换只做一次原件若有改动mtime 对比会自动让缓存失效。另外两条链路思路相同形态不同exporter 走officecli view file pdf --out path插件只读源文件、写出目标文件format-handler 走plugin open file主程序先发open握手帧插件回以能力清单和词汇表快照之后每个请求与应答经 stdin/stdout 逐帧往返直到close结束会话。 实战从零写一个最小 dump-reader插件要做的事只有两件用--info自我介绍用dump流式输出命令。下面是约 25 行的 C# 最小版本using System.Text.Json; if (args[0] --info) { Console.WriteLine(JsonSerializer.Serialize(new { name officecli-doc-min, version 0.0.1, protocol 1, kinds new[] { dump-reader }, extensions new[] { .doc }, target docx, runtime dotnet, idle_timeout_seconds new { default 30 } })); return 0; } // args: dump source-file string sourcePath args[1]; var stdout Console.Out; stdout.WriteLine(JsonSerializer.Serialize(new { command add, parent /body, type paragraph, props new { text Hello from .doc } })); stdout.Flush(); return 0;编译成单文件可执行放进~/.officecli/plugins/dump-reader/doc/pluginofficecli plugins list就能看见它officecli-doc-min 0.0.1 dump-reader .doc /home/you/.officecli/plugins/dump-reader/doc/plugin再运行officecli view hello.doc插件向 stdout 输出的那行 JSONL 是{command:add,parent:/body,type:paragraph,props:{text:Hello from .doc}}。主程序把它重放进新建的hello.docx第二次打开时直接复用这份缓存。⚠️ 避坑记录1. 报错 corrupt_batch现象转换刚启动就失败。原因把全部命令写成了一个 JSON 数组[{...},{...}]挤在一行。解法协议要求每行一个 JSON 对象并逐行 flush流式输出顺带给看门狗提供活动信号。2. 看门狗杀掉进程退出码 6现象大文件处理总在 30 秒左右被终止。原因idle_timeout_seconds内没有任何输出被判挂死。解法长任务定期向 stderr 发{heartbeat:true}或让输出自然流式化本机调试可设OFFICECLI_PLUGIN_IDLE_TIMEOUT_SECONDS0关闭看门狗manifest 里不允许写 0。3..doc仍提示不支持现象插件装好了却不生效。原因可执行文件不在四条发现路径中的任何一条。解法用officecli plugins list确认是否被发现或直接用环境变量$OFFICECLI_PLUGIN_DUMP_READER_DOC指向可执行文件绝对路径它的优先级最高。4. 会话突然 broken现象format-handler 会话进入 broken 状态后续请求全部快速失败。原因stdout 里混进了非协议内容比如调试打印。解法stdout 只发协议帧诊断信息走 stderr 或--log-file。5. 查退出码再查代码0 成功、2 源文件损坏、3 当前构建不支持该特性、4 许可证校验失败、5 协议版本不一致manifest 的protocol字段必须是 1。多数莫名失败在这一步就能定位。下一步去哪插件作者可以用任何带 stdin/stdout 的语言C#、Go、Rust、Python 都行使用者只需把可执行文件放对位置。想深入读 plugins/plugin-protocol.md 里的完整协议定义主程序侧的调用逻辑在 src/officecli/Core/Plugins/各格式字段规范在 schemas/ 目录。你的团队里有没有一个至今没人敢碰的文档格式它值得成为你的第一个插件吗【免费下载链接】OfficeCLIOfficeCLI is the first and best Office suite purpose-built for AI agents to read, edit, and automate Word, Excel, and PowerPoint files. Free, open-source, single binary, no Office installation required.项目地址: https://gitcode.com/GitHub_Trending/of/OfficeCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考