_{托盘常驻 · 无需登录注册、无需 API Key · 隔离运行时 · 并发检测 · 判定缓存 · 一键导入 · 本机 OpenAI 兼容转发口}

---

⚠️ 这是上游的非官方 Windows fork

原作者：HRuiCcc · 上游仓库：HRuiCcc/RuiC-oc-ferry

本仓库以 MIT License 发布（Copyright (c) 2026 HRuiCcc，LICENSE 原样保留）， 与原作者无隶属关系。相对上游 v0.3.0 的改动见 NOTICE.md： ① 最小化到托盘 ② 退出时清理 opencode-cli.exe 残留 ③ Windows 绿色版部署脚本。

如果你只是想要原版，请去上游仓库。 上游只发布了 macOS 构建产物； 本 fork 补的是 Windows 这一块——Windows 专章见 docs/Windows-说明.md （OpenCode 运行时存放规则、构建命令、缓存重试时长）。

---

WorkBuddy 支持在它的 models.json 里填自定义模型。OpenCode 的免费模型池是现成的免费额度，但它不是一个能直接填进去的 OpenAI 端点：目录里带 free 的模型不一定免费，能聊天不等于能按 WorkBuddy 的方式产生工具调用，而且免费池随时上下线。

OC Ferry 就是中间这一层：在数据目录里放一份隔离的 OpenCode，按价格筛出免费模型，逐个探测它们能不能按 WorkBuddy 的工具协议干活，把通过的写进你的 models.json，再起一个只监听本机的转发口供 WorkBuddy 调用。

界面

浅色与深色两套主题，四档状态一眼可读；检测是并发的，多个模型同时跑。

深色主题	并发检测：多路同时跑，底部实时显示还剩几个
行内展开详情，可「只重测这一个」	判定来自缓存时如实标注

工作流程

flowchart LR
  A["托盘 / 控制面板"] -->|读取模型目录| B["隔离 OpenCode<br/>运行时"]
  B --> C{"逐个检测<br/>能否按协议产生动作"}
  C -->|产生正确动作| D["判定缓存<br/>成功 6 小时"]
  C -->|只回文本| E["可用 · 仅对话<br/>工具关闭"]
  C -->|超时 / 限流| F["记录原因<br/>10 分钟后自动重试"]
  C -->|已下线 / 无权限| G["记录原因<br/>1 小时后重试"]
  D --> H["写入 WorkBuddy<br/>models.json"]
  E --> H
  H --> I["WorkBuddy"]
  I -->|"OpenAI 兼容请求"| J["本机转发口<br/>127.0.0.1:41980"]
  J --> K["适配器：JSON 信封协议<br/>审批围栏 · 动作转交"]
  K --> B
  A -->|退出| L["摘掉自己导入的条目<br/>保留你手写的"]

Loading

五条核心链路

1. 发现：只看价格字段（输入/输出/缓存读写全为 0）才算免费，名字里带 free 不算数；已声明 deprecated 的直接排除。
2. 体检：给 5 个工具、自由选择，让它读一个带随机 token 的文件。只回文本不算失败——按「可用 · 仅对话」发布并关掉工具；动作不符重试一次；超时与格式失败不重试。
3. 提速：检测 3 路并发（一轮约 60 秒）；判定按模型缓存，成功保留 6 小时、当时的负载只保留 10 分钟——重启基本是秒开，不会每次都全量重测。
4. 导入：只增删自己标记过的条目，你手写的一条都不动；写前备份、加锁、原子替换，内容没变就不写；退出时把自己的条目摘干净。
5. 转发：模型只能回一个 JSON 信封表达动作，执行权始终在 WorkBuddy 手里——任何本机动作一律被拒绝或转交成外部工具调用，模型永远不会自己动手。

用法

先安装 WorkBuddy。不需要另外装 Node.js（打包后的应用用 Electron 自带的 Node 跑后台服务）。

• macOS：解压 zip，把 OC Ferry.app 拖进「应用程序」，双击打开。未做 Apple 公证，首次打开可能要右键 →「打开」。
• Windows：到 Releases 下载 OC-Ferry-Deployer.exe， 双击、选个安装目录，它会自动把主程序和 OpenCode 运行时都装好（约 1 分钟，目标机无需预装 Python / Node）， 完事在桌面留一个「OC Ferry」快捷方式。 想用绿色版就直接下 OC-Ferry-0.3.0-win-x64.zip —— 必须完整解压，然后双击 启动 OC Ferry.bat （不要只复制 exe 出来，运行时和数据目录都在压缩包里）。

首次启动会自动准备 OpenCode、扫描免费模型并逐个检测，检测完自动导入一次。之后重新检测或读取不会自动改 WorkBuddy，需要点「导入 WorkBuddy」。

几个日常操作：

• 关窗口 ≠ 退出：关掉窗口它继续在托盘跑；从托盘退出时会把自己导入的条目摘掉（保留你手写的），所以这些模型可用期间请让它常驻。
• 想重新验证：点「检测全部」强制重测一轮；只想重测某一个，在它的详情里点「只重测这一个」。
• 主题：工具栏右上角可在系统 / 浅色 / 深色之间切换，选择会记住。

一键部署器（Windows）

tools/deployer/ 下是一个独立的 Windows 部署器：选一个目录、点一下按钮， 主程序与 OpenCode 运行时全部装好。

• 单文件 exe：约 13.5 MB，目标机不需要预装 Python / Node，双击即用
• 无控制台窗口：以 WINDOWS_GUI 子系统编译（PE Subsystem=2），系统不会分配控制台
• 界面完全自绘：pywebview + WebView2 无边框窗口，暗色科技风，无任何系统控件
• 单实例保护：重复双击只会激活已有窗口，不会并发跑两次部署
• 子进程无黑框：所有 subprocess 统一带 CREATE_NO_WINDOW

五步部署流程（全部已实现）：

步骤	做什么	校验
1	检测运行环境（系统版本、WebView2 运行时）	—
2	校验部署位置（写入权限、磁盘空间）	—
3	展开 OC Ferry 主程序（从 Release 下载 151 MB 载荷）	SHA-256 + 安全解压（拒绝越界路径）
4	获取 OpenCode 运行时（解析 npm 官方元数据）	SHA-512 比对官方 integrity
5	创建启动入口（桌面快捷方式 + 启动脚本）	—

两个值得说的细节：

• 失败可回滚：覆盖安装时先把旧目录移开，解压失败自动还原到原安装。
• 下载有备用线路：github.com 不可达时自动改用 GitHub API 资产端点重试。

系统要求：Windows 10 1809+ / Windows 11。Windows 7 / 8 / 8.1 不受支持 （主程序基于 Electron，其 Chromium 与 WebView2 均已放弃 Win7）。

详见 tools/deployer/README.md。

开发

npm ci
npm test              # 85 项自动测试，不访问网络
npm run desktop       # 起 Electron（窗口 + 托盘 + 后台服务）
npm start             # 只起后台服务（无界面），用于调试
npm run build:mac     # 打 macOS zip（ad-hoc 签名 + 深度严格校验）
npm run build:win     # 打 Windows 安装包（NSIS，桌面图标 + 开机自启）
npm run build:win:portable   # 打 Windows 便携版（不写注册表、不自启）

数据目录

系统	应用数据	WorkBuddy 配置
macOS	~/Library/Application Support/OC Ferry	~/.workbuddy/models.json
Windows	%APPDATA%\OC Ferry	%USERPROFILE%\.workbuddy\models.json
Linux（实验性）	$XDG_CONFIG_HOME/OC Ferry	~/.workbuddy/models.json

数据目录里：api-key（本机转发口的密钥）、status.json、settings.json、probe-cache.json（判定缓存）、runtime/（托管运行时）、opencode/（隔离 OpenCode 自己的目录）。

环境变量（调试用）：FERRY_DATA_DIR、FERRY_PORT（默认 41980）、FERRY_MODELS_FILE、FERRY_NO_SYNC=1（完全不写 WorkBuddy）、FERRY_OPENCODE_PATH、FERRY_PROBE_CONCURRENCY（并发度，默认 3，上限 6）、FERRY_PROBE_TTL_MINUTES（成功判定有效期，默认 360 分钟）、WORKBUDDY_CONFIG_DIR / WORKBUDDY_DATA_FOLDER_NAME。

本机接口

所有路由都要 Authorization: Bearer <数据目录>/api-key，带 Origin 头的请求一律 403（这个端口不给浏览器用）。

GET  /health                 # 完整状态
GET  /v1/models              # 已判定可用的模型（id 为 "OC · 名字"）
POST /v1/chat/completions    # 转发，支持 stream；并发上限 4
POST /admin/refresh | /admin/probe | /admin/import | /admin/selection
POST /admin/system-proxy | /admin/find-config

代码结构

src/
  main.js            编排：状态机 / 检测队列 / 刷新 / 导入 / 退出清理
  backend.js         OpenCode 会话、审批围栏、事件流、动作转交与翻译
  runtime.js         运行时发现·下载·校验·隔离启动
  protocol.js        请求校验 / 信封编解码 / usage 换算 / SSE
  probe.js           检测请求与判定规则
  probe-cache.js     判定缓存：跨重启复用，按能力指纹与过期时间失效
  repair.js          翻译兜底：系统提示、材料打包、诊断重发
  handoff.js         本机动作 → 外部工具的映射与 schema 复核
  config-finder.js   Windows 配置查找（只读）
  sync.js            models.json 的合并 / 加锁 / 备份 / 原子写
  server.js          本机 HTTP 面（鉴权、来源围栏、转发）
  platform.js  system-proxy.js  atomic.js  json.js
  service-instance.js  model-status.js  reasoning.js  workbuddy-config.js
desktop/
  main.cjs           Electron：窗口、托盘、受限 IPC、服务生命周期
  preload.cjs        只暴露状态订阅与固定动作
  index.html  style.css  renderer.js   控制面板
  activity.cjs       托盘与面板共用的阶段文案
test/                85 项自动测试
docs/
  设计说明.md         架构、协议、机制与边界（模块地图 / 信封协议 / 审批围栏 / 缓存策略）
  screenshots/       界面截图

诚实交代

• 启动后会自动发送简短的检测请求，会使用少量免费额度；检测通过只代表"这一次能按协议产生动作"，不代表完整工作流都验证过。
• 界面上的耗时是完整请求用时，不是首字延迟；剩余额度上游不提供，查不到。
• 不可用的模型只在窗口里保留记录，不会提供给 WorkBuddy。
• 免费模型与额度由上游决定，随时可能变化。
• 系统代理只支持手动 HTTP/HTTPS 配置，不支持 PAC/SOCKS。

License

MIT — Copyright (c) 2026 HRuiCcc（上游原作者）

本仓库是 HRuiCcc/RuiC-oc-ferry 的非官方 fork， 按 MIT 条款保留原始版权声明与许可全文。改动清单见 NOTICE.md。

---

原作者的赞赏码已从本 fork 移除 —— 如果这个工具帮到了你，请到上游仓库支持 HRuiCcc。