HRuiCcc/RuiC-oc-ferry

把 OpenCode 的免费模型摆渡给 WorkBuddy —— 隔离运行时、并发检测、判定缓存、一键导入、本机 OpenAI 兼容转发口

OC Ferry – Bridge OpenCode free models to WorkBuddy

What it is

A cross‑platform (macOS / Windows) tray application built with Electron that automatically discovers free models from the OpenCode model pool, tests whether they can speak the WorkBuddy tool‑calling protocol, and writes the usable ones into WorkBuddy’s models.json. It also runs a local OpenAI‑compatible HTTP endpoint (127.0.0.1:41980) that forwards WorkBuddy requests to the selected models.

Why it matters

WorkBuddy can only consume models that follow a specific JSON‑envelope tool‑calling schema. OpenCode’s free models are not directly compatible and their availability changes frequently. OC Ferry automates the discovery, validation, caching and import steps, letting users get free model access without manual API‑key handling.

Key features

Zero‑login, zero‑API‑key – the app bundles its own isolated OpenCode runtime.
Free‑model filter – only models whose price fields are all zero and are not deprecated are considered.
Concurrent probing – up to three models are tested in parallel (≈60 s per round).
Result caching – successful probes are cached for 6 h, so restarts are near‑instant.
Selective import – only entries added by OC Ferry are written to WorkBuddy’s models.json; user‑added entries stay untouched.
Local forwarding port – an OpenAI‑compatible endpoint that only accepts requests from the local machine (no browser access).
Tray UI – light/dark themes, real‑time status, per‑model detail view, and a “detect all / re‑probe single” button.
Portable builds – macOS DMG, Windows installer, and a portable Windows zip.

How it works (high‑level flow)

Discovery – reads the OpenCode model directory, selects entries with price = 0 and not deprecated.
Probe – sends a small chat request that includes a random token file and asks the model to produce a JSON‑envelope action. If the model returns only plain text, it is marked dialog‑only; if it returns a correct envelope, it is marked tool‑enabled.
Cache – probe results are stored in probe‑cache.json (TTL = 6 h). Subsequent launches reuse the cache unless it expires.
Import – merges the discovered entries into WorkBuddy’s models.json with atomic write, backup and file‑lock handling.
Forwarding – WorkBuddy sends OpenAI‑style requests to 127.0.0.1:41980; OC Ferry validates the request, forwards it to the selected OpenCode model, and translates any JSON‑envelope action back to WorkBuddy.

Installation & quick start

macOS (Apple silicon) – download the .dmg, drag “OC Ferry” into Applications, optionally remove quarantine (xattr -dr com.apple.quarantine …).
Windows – run the .exe installer; it adds a start‑up entry that runs the app hidden in the tray. A portable zip is also provided.
First launch automatically prepares an isolated OpenCode runtime, scans free models, probes them, and imports the successful ones into WorkBuddy.
Keep the app running (tray icon) – closing the window hides it, exiting from the tray cleans up the entries it added.

Developer notes

Node ≥ 22, Electron for UI, pure JavaScript/TypeScript codebase.
Main modules: main.js (state machine), backend.js (OpenCode session & action translation), probe.js (model testing), server.js (local HTTP API), plus UI code under desktop/.
Tests: 85 automated unit tests that run offline (npm test).
Build commands: npm run build:mac, npm run build:win, npm run build:win:portable.
Environment variables for debugging (data dir, port, concurrency, etc.).

Limitations & caveats

Probing consumes a tiny amount of free OpenCode quota; results only guarantee that this request succeeded.
Free model availability is controlled by OpenCode and may change without notice.
The local forwarding port rejects any request with an Origin header (no browser use).
System proxy support is limited to manual HTTP/HTTPS entries; PAC or SOCKS are not supported.
Linux support is experimental.

License

If OC Ferry helps you, the author welcomes a coffee donation via WeChat.