OfficeCLI 插件开发完整指南：从装好第一个格式扩展到打开 .hwpx

OfficeCLI 插件开发完整指南从装好第一个格式扩展到打开 .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让 AI 代理打开一个 .doc 合同它只会报错——OfficeCLI 核心只认 docx、xlsx、pptx 三种格式。OfficeCLI 是专为 AI 代理打造的办公套件能通过 OfficeCLI 插件把 .doc、.hwpx、.pdf 这类格式纳入同一套命令行工作流核心代码一行不用改。本文讲清机制、安装方式和三类插件的实现路径。 一张表看懂三类 OfficeCLI 插件转换、导出、接管插件是独立的外部进程sidecar主程序按需拉起。协议 v1 定义了三类职责边界清晰角色典型场景生命周期文件归属通信方式转换型dump-reader把 .doc 迁移成 .docx短命跑完即退插件只读源文件主程序写出结果无 IPC向 stdout 流式吐 JSONL 命令后退出导出型exporter导出 .pdf短命跑完即退插件只读源文件、写目标文件无 IPC普通命令行调用接管型format-handler.hwpx 完整读写编辑长驻覆盖整个会话插件全程持有文件读写stdin/stdout 请求-响应三个要点先记住转换型产出的是原生格式target只能是 docx/xlsx/pptx后续编辑都发生在生成的兄弟文件上源文件不动。导出型是单向渲染不参与任何编辑。接管型的词汇表由插件自定义manifest 里声明可加类型、可设属性、路径语法会话开始时再快照一次主机以快照为准。另有两个预留类型engine、transformerv1 禁止声明留给未来的子系统后端与原生格式互转。 插件装在哪四级发现机制与一行安装命令主程序按(kind, ext)找插件时按固定顺序搜索先命中先生效环境变量$OFFICECLI_PLUGIN_KIND_EXT如OFFICECLI_PLUGIN_DUMP_READER_DOC值为可执行文件绝对路径用户插件目录~/.officecli/plugins/kind/ext/plugin(.exe)主程序同级的捆绑目录主程序目录/plugins/kind/ext/plugin(.exe)PATH 查找名字为officecli-kind-ext或officecli-ext。约定kind用 kebab-casedump-reader、format-handlerext不带点Windows 自动补.exe符号链接会被跟随。发现结果按进程缓存下次调用自动拾取新插件。安装协议本身不强制渠道手动解压、发布包捆绑、包管理器都行。推荐用内置安装器officecli plugins install name它从插件注册表拉取清单并校验 SHA-256支持配置私有镜像企业内网场景。装完用officecli plugins list看发现结果officecli plugins info看完整 manifestofficecli plugins lint做持久化校验。完整规则见 plugins/plugin-protocol.md 第 3、8 节。 写一个插件从浅到深的三个项目先说语言协议是 stdin/stdout 上的 JSONL任何能读写标准流的语言都行——.NET、Go、Python、Rust 均可.NET 侧还有OfficeCli.Contracts包提供类型安全的封装。所有插件的第一职责相同响应--info向 stdout 打印一个 JSON manifest 并以 0 退出。入门级 | Exporter只读、一次性、最省事以导出 PDF 为例渲染库体积大、有许可证约束所以拆出去。用户执行officecli view report.docx pdf --out out.pdf主程序把 view 模式映射成目标扩展名解析出插件后按export source --out target [--options json]拉起它。你的插件只需做三件事用自带库读源文件严禁写回源文件主程序基于这条约定跳过快照需要可写副本就自己建临时文件写出目标成功则退出 0。诊断信息走 stderr。渲染耗时较长时定期向 stderr 打一行{heartbeat:true}避免触发看门狗。进阶级 | Dump-Reader用 JSONL 命令流把 .doc 迁移成 .docx打开 .doc 时主程序先看旁边有没有比源文件更新的同名 .docx有就直接打开没有才以dump source启动插件。插件解析源文件向 stdout 逐行输出 add/set/batch 命令每行单独 flush然后退出 0。主程序建一个空白骨架、逐行重放再把成品移到源文件旁边。两条硬约束输出必须是 JSONL顶层 JSON 数组会被拒收corrupt_batch必须流式输出——每行 flush 既是主机看门狗的活动信号也限制了主程序处理大文件时的内存占用。缓存靠 mtime源文件一改就自动失效删掉兄弟文件可强制重转。manifest 长这样来自协议文档的officecli-doc示例{ name: officecli-doc, version: 1.0.0, protocol: 1, kinds: [dump-reader], extensions: [.doc], target: docx, runtime: dotnet, idle_timeout_seconds: { default: 60, verbs: { dump: 30 } }, supports: [paragraphs, runs, tables, images, lists] }高级 | Format-Handler长驻进程全程接管 .hwpx这是最重的一类主程序以open file拉起插件后双方在整个会话期间保持通信。先做 open 握手之后严格一问一答地处理 add/set/get/query/save/close。最关键的通信片段如下{protocol:1,msg_type:open,path:report.hwpx,editable:true} {protocol:1,msg_type:ok,result:{capabilities:{commands:[get,set,save],features:[extract-binary]},vocabulary:{addable_types:[paragraph,table],settable_props:{},path_segments:[/page[N]]}}} {protocol:1,msg_type:command,command:add,args:{parent_path:/page[1],type:paragraph},props:{text:Hello}}实现要点stdout 只走协议帧调试输出全去 stderr 或--log-file污染 stdout 会被判protocol_mismatch、会话进入 brokensave必须真正刷盘后才能回 ok这是主程序崩溃恢复的前提plugins lint会在重开文件后验证持久化broken 会话不会自动重启由调用方重开。 协议要点速查manifest、JSONL、超时与退出码项要点manifest 必填字段namekebab-case、versionSemVer、protocol1不匹配拒收退出 5、kinds、extensions带点、idle_timeout_seconds、runtimedump-reader 另需targetformat-handler 另需vocabulary可选description、license、tier等JSONL 通信每行一个 JSON 对象、\n结尾、UTF-8 无 BOM、键名 snake_caseformat-handler 用 stdin 收请求、stdout 回响应、stderr 放诊断与心跳空闲超时看门狗盯无活动stdout 字节、RPC 响应、stderr 心跳都算活动不限总时长manifest 里不允许写 0用户侧可用OFFICECLI_PLUGIN_IDLE_TIMEOUT_SECONDS覆盖0 表示彻底关闭看门狗崩溃与恢复非零退出会给出明确错误内存中的半成品状态被丢弃不落损坏文件空闲超时杀整个进程树并报plugin_idle_timeoutbroken 会话快速失败不自动重启退出代码0 成功2 输入损坏3 该构建不支持此功能4 许可证过期5 协议不匹配6 空闲超时仅主机设置64–78 保留sysexits.h其余按internal_error上报错误码同理可查corrupt_batch、protocol_mismatch、plugin_idle_timeout、license_expired等都在协议文档 6.6 节列了语义主机把未知码一律归为internal_error。❓ 常见问题语言、崩溃、授权与调试Q插件可以随便选语言吗可以。协议只约束标准流和 JSON 形态。C#、Go、Python、Rust 都行.NET 插件可选用OfficeCli.Contracts包获得类型安全的消息体。Q插件崩了或卡死了会怎样崩溃时主程序直接报清晰错误丢弃内存中的部分状态不会写出损坏文件。卡死时看门狗在 manifest 声明的空闲窗口内收不到任何活动就杀掉进程树并报告超时长任务靠 stderr 心跳保活。Q闭源或商业插件被允许吗允许。插件是独立可执行文件许可证与主仓库Apache-2.0解耦许可证校验失败按约定退出 4license_expired。Q调试插件从哪下手先officecli plugins list确认插件被发现、路径对再加--log-file把诊断落盘、--quiet压低噪音怀疑是看门狗误杀时用OFFICECLI_PLUGIN_IDLE_TIMEOUT_SECONDS临时放宽该变量只在宿主环境生效不会传入插件进程。Q为什么不做总时长上限大型 .doc 的 dump 合理耗时就是几分钟总时长上限会误杀慢但正确的转换空闲超时只抓真正的挂起没有误报。 收尾谁该给 OfficeCLI 做格式扩展对个人用户偶尔碰到 .doc 遗留文件或区域性的 .hwpx装一个成熟插件即可本文不必全读。对企业私有注册表加 IT 分发可以把内部文档流水线做成自研插件和核心版本彻底解耦。值得留意的延伸方向协议预留的engine与transformer类型意味着日后 docx→pptx 这类原生互转、以及 PDF 渲染后端都能用同一套发现与通信机制接进来。主程序侧的实现集中在 src/officecli/Core/Plugins/想读源码可以直接从这里入手。【免费下载链接】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），仅供参考