HRuiCcc/RuiC-oc-ferry

OC Ferry – 将 OpenCode 免费模型桥接到 WorkBuddy

它是什么

• 一款基于 Electron 构建的跨平台（macOS / Windows）托盘应用，可自动从 OpenCode 模型池中发现免费模型，测试它们能否使用 WorkBuddy 工具调用协议，并将可用的模型写入 WorkBuddy 的 models.json。它还运行一个本地 OpenAI 兼容 HTTP 端点（127.0.0.1:41980），将 WorkBuddy 请求转发到所选模型。

为什么重要

• WorkBuddy 只能使用遵循特定 JSON 封装工具调用模式的模型。OpenCode 的免费模型不直接兼容，且其可用性经常变化。OC Ferry 自动化了发现、验证、缓存和导入步骤，让用户无需手动处理 API 密钥即可获得免费模型访问。

主要特性

• 零登录、零 API 密钥 – 应用捆绑了其自己的隔离 OpenCode 运行时。
• 免费模型过滤器 – 仅考虑价格字段全为零且未弃用的模型。
• 并发探测 – 最多同时测试三个模型（每轮约 60 秒）。
• 结果缓存 – 成功的探测结果缓存 6 小时，因此重启几乎即时。
• 选择性导入 – 仅将 OC Ferry 添加的条目写入 WorkBuddy 的 models.json；用户添加的条目保持不变。
• 本地转发端口 – 一个 OpenAI 兼容端点，仅接受来自本地机器的请求（无浏览器访问）。
• 托盘 UI – 浅色/深色主题、实时状态、每个模型的详细视图，以及“全部检测 / 重新探测单个”按钮。
• 便携式构建 – macOS DMG、Windows 安装程序以及便携式 Windows zip。

工作原理（高级流程）

1. 发现 – 读取 OpenCode 模型目录，选择价格 = 0 且未弃用的条目。
2. 探测 – 发送一个小型聊天请求，包含一个随机令牌文件，并要求模型生成 JSON 封装操作。如果模型仅返回纯文本，则标记为 仅对话；如果返回正确的封装，则标记为 工具启用。
3. 缓存 – 探测结果存储在 probe-cache.json 中（TTL = 6 小时）。后续启动重用缓存，除非过期。
4. 导入 – 将发现的条目合并到 WorkBuddy 的 models.json，使用原子写入、备份和文件锁处理。
5. 转发 – WorkBuddy 向 127.0.0.1:41980 发送 OpenAI 风格请求；OC Ferry 验证请求，将其转发到所选 OpenCode 模型，并将任何 JSON 封装操作转换回 WorkBuddy。

安装与快速开始

• macOS（Apple 芯片） – 下载 .dmg，将“OC Ferry”拖入 应用程序，可选移除隔离（xattr -dr com.apple.quarantine …）。
• Windows – 运行 .exe 安装程序；它会添加一个启动项，在托盘隐藏运行应用。还提供便携式 zip。
• 首次启动自动准备隔离的 OpenCode 运行时，扫描免费模型，探测它们，并将成功的导入 WorkBuddy。
• 保持应用运行（托盘图标）– 关闭窗口隐藏它，从托盘退出会清理它添加的条目。

开发者说明

• Node ≥ 22，Electron 用于 UI，纯 JavaScript/TypeScript 代码库。
• 主要模块：main.js（状态机）、backend.js（OpenCode 会话和操作转换）、probe.js（模型测试）、server.js（本地 HTTP API），以及 desktop/ 下的 UI 代码。
• 测试：85 个自动化单元测试，可离线运行（npm test）。
• 构建命令：npm run build:mac、npm run build:win、npm run build:win:portable。
• 用于调试的环境变量（数据目录、端口、并发等）。

限制与注意事项

• 探测会消耗少量免费 OpenCode 配额；结果仅保证 此 请求成功。
• 免费模型的可用性由 OpenCode 控制，可能随时更改。
• 本地转发端口拒绝任何带有 Origin 头的请求（无浏览器使用）。
• 系统代理支持仅限于手动 HTTP/HTTPS 条目；不支持 PAC 或 SOCKS。
• Linux 支持是实验性的。

许可证

• MIT 许可证（参见 LICENSE）。

---

如果 OC Ferry 对您有帮助，作者欢迎通过微信捐赠一杯咖啡。