Ruby vs. Java vs. TypeScript：构建 Cowork DOCX 插件的实战复盘

背景

近期，开发团队尝试使用三种不同的编程语言——Ruby、Java 和 TypeScript——分别构建了一个用于 Claude Cowork 的 DOCX 插件原型。DOCX 文件本质上是一个包含多个 XML 文件及其他资源的 ZIP 压缩包，因此开发核心难点在于对 ZIP 文件和 XML 数据的处理。

在为期一个月的开发周期内，团队经历了从 Ruby 原型到 Java 桌面应用，再到 TypeScript 兼容 MCPB（Model Context Protocol Binary）方案的三次重构。尽管 Java 在运行时稳定性和类型系统上表现最佳，但最终团队选择了 TypeScript，主要出于对未来 MCPB 支持的考量，这有望消除嵌入式运行时依赖，并将二进制体积缩减 99%。

此外，作者还对比了 Claude 与 Codex 在插件机制上的差异，指出 Codex 目前在该领域落后于 Claude Desktop。

核心内容

1. Ruby：快速原型与类型缺失的痛点

最初，由于团队成员熟悉 Ruby 且希望构建服务端应用，作者选择了 Ruby 进行原型开发。尽管 Ruby 语法优美，但在实际工程实践中遇到了显著挑战：

• 缺乏静态类型：这是最大的痛点。作者曾考虑集成 Sorbet 或 RBS，但因集成复杂度高且文档晦涩而放弃。缺乏类型提示导致调试困难，例如常见的 nil 错误往往出现在代码的随机位置，难以定位。
• 测试干扰：使用 assert_raises 有时会掩盖编译错误，导致开发者必须注释掉测试代码才能看到真实的堆栈跟踪。
• 库版本陷阱：使用 ruby_llm-mcp 时，文档中的 tool.input_schema 在最新版本中已重命名为 tool.params_schema，由于缺乏类型提示，排查这一问题耗费了大量时间。
• 底层库缺陷：
  • rubyzip：存在一个难以复现的隐蔽 Bug，会导致生成的 DOCX 文件损坏。由于涉及客户机密文件，作者无法将具体案例分享给库作者，导致问题无法解决。
  • nokogiri：基于 libxml2，存在非阻塞性 Bug，无法正确格式化 XML。这被视为 libxml2 层面的问题，而非 nokogiri 本身的缺陷。

2. Java：运行时稳定性与成熟度的胜利

为了构建支持本地执行二进制文件的 Claude 插件，团队转向 Java。

• 原生支持优异：Java 标准运行时对 ZIP 和 XML 处理提供了开箱即用的支持，无需引入第三方库，且未遇到任何兼容性问题。
• 开发效率高：借助 AI 辅助，将数千行 Ruby 代码移植到 Java 仅耗时 3 天。
• 静态类型优势：严格的类型系统显著降低了编码难度和错误率。
• 二进制体积：最终生成的单文件二进制包约为 88MB，这是因为 JDK 被嵌入其中。
• 跨平台信心：Java 在 Windows 和 Mac 上的运行时成熟度给开发者带来了更高的信心。

3. TypeScript：面向未来的 MCPB 兼容性

随后，团队发现 Claude Desktop 支持 MCPB（提供 Node 运行时环境）。这意味着应用只需包含业务代码，无需嵌入运行时，体积可降至约 1MB。

• 库的选择：
  • ZIP 处理：使用 fflate，表现符合预期。
  • XML 处理：使用 xmldom，因为它提供 DOM API。虽然不支持 XML 美化打印（Pretty-print），但这被解释为 XML 主要用于传输/序列化，且缺乏美化标准，因此属于设计取舍而非 Bug。
• 移植效率：从 Java 移植到 TypeScript 仅耗时 1.5 天，AI 辅助效果显著。
• 构建工具选择：由于 Claude 插件仅支持单文件二进制执行，而 Node.js 原生不支持此功能，团队最终采用了 Bun 进行构建。Bun 能生成单文件二进制，且在 Mac 和 Windows 上表现良好。
• 遗留问题：Bun 的一个主要缺口是难以将 Source Map 上传至 PostHog。PostHog 要求同时提供最小化的 JS 文件和 .js.map 文件，但 Bun 仅生成二进制和 .js.map 文件，导致调试链路受阻。
• 最终体积：Mac 上约 70MB，Windows 上约 120MB（主要因 Bun 嵌入运行时所致，若支持 MCPB 可大幅缩减）。

4. 插件机制对比：Claude vs. Codex

作者在尝试为 Codex 开发插件时发现其机制落后于 Claude Desktop：

• Claude：支持环境变量 CLAUDE_PLUGIN_ROOT，允许开发者将单文件二进制作为 stdio MCP 服务器执行。
• Codex：缺乏等效的环境变量支持。虽然插件结构包含二进制文件夹，但文档未说明如何执行其中的二进制文件。作者尝试了多种路径均告失败。

关键要点

• 语言选择权衡：
  • Java 是处理 ZIP 和 XML 的“赢家”，因其标准库成熟、类型系统严格且运行时稳定。
  • TypeScript 最终胜出，主要因为潜在的未来 MCPB 支持能力，这能消除嵌入式运行时，极大减小二进制体积。
• Ruby 的工程局限：虽然适合快速原型，但缺乏静态类型、第三方库（如 rubyzip）的隐蔽 Bug 以及文档滞后问题，使其不适合生产级复杂插件开发。
• Bun 的实用性与短板：Bun 成功解决了 Node.js 无法生成单文件二进制的问题，但在 Source Map 调试集成（特别是与 PostHog 配合）方面存在明显短板。
• AI 辅助开发效能：AI 在代码移植中表现优异，Ruby 到 Java 移植耗时 3 天，Java 到 TypeScript 移植仅耗时 1.5 天。
• Codex 插件生态滞后：目前 Codex 的插件机制不如 Claude Desktop 完善，缺乏对二进制执行和环境变量的明确支持。

意义与影响

1. AI 代理插件开发的标准化趋势：随着 Claude 和 Codex 等 AI 平台对插件和 MCP（Model Context Protocol）支持的演进，开发者需要深入理解不同运行时环境（如 MCPB）对应用架构的影响。选择 TypeScript 而非 Java，反映了开发者对“轻量化”和“标准化运行时”的偏好。
2. 工具链的成熟度验证：此次实践验证了 Bun 在生成单文件二进制方面的能力，同时也暴露了其在调试工具链集成上的不足。这对未来基于 Bun 构建 AI 插件的开发者具有参考价值。
3. Java 在 AI 后端/桌面端的回归：尽管 JavaScript/TypeScript 生态活跃，但 Java 在处理复杂文件结构（如 DOCX）和提供稳定桌面应用方面的优势依然不可替代。其严格的类型系统和成熟的库生态，在大型项目中仍具竞争力。
4. 对开发者的建议：
   • 若追求快速验证且项目简单，Ruby 可用，但需警惕库的稳定性。
   • 若需要构建稳定、跨平台的桌面端 AI 插件，Java 是稳健之选。
   • 若目标是最大化兼容未来的 MCP 标准并减小体积，TypeScript + Bun 是当前的最佳实践，但需预留时间解决调试工具链的集成问题。
   • 密切关注 Codex 插件机制的更新，目前其生态尚不成熟，开发需谨慎。

注：该插件目前处于早期阶段，作者欢迎通过 [email protected] 联系以获取帮助或更新通知。