@fro.bot/harness

中文文档
1.19.5-harness.bf7f7dfe发布于 2026/11/07MITES Module零依赖构建来源已验证近 30 天下载 1983

Published patched-OpenCode binary with orw-embedded LLM-merge integration — the default OpenCode for Fro Bot

原始使用文档
文档目录10 节
  1. Commands
  2. harness
  3. opencode
  4. Install
  5. Install caveats
  6. How the binary is found
  7. Upgrading
  8. Signals and exit codes
  9. Development checkouts
  10. License

@fro.bot/harness

The patched OpenCode build that Fro Bot runs. Installing this package puts two commands on your PATH:

  • harness — the patched OpenCode plus a few harness-own subcommands.
  • opencode — the patched OpenCode and nothing else.

Commands

harness

CommandDoes
harness infoPrint provenance: base version, integration refs, build SHA
harness patchesList the integration refs carried on top of upstream
harness doctorCheck that the resolved binary is present, runnable, and the right build
harness integrateRun the integration pipeline (maintainers)
harness --helpPrint usage
harness --versionPrint the harness provenance version

Everything else passes through to the patched binary: harness run ... behaves like opencode run ....

opencode

A pure passthrough. It has no reserved subcommands: every argument, including --version, info, doctor, and upgrade, goes to the patched binary unchanged. Tools that look opencode up by name (editors, scripts, the OpenCode SDK) get the patched build.

Install

npm i -g @fro.bot/harness
bun add -g @fro.bot/harness
mise use -g npm:@fro.bot/harness

The native binary ships in a per-platform package that the installer pulls in as an optional dependency:

PackagePlatform
@fro.bot/harness-linux-x64Linux x64
@fro.bot/harness-linux-arm64Linux arm64
@fro.bot/harness-darwin-x64macOS x64
@fro.bot/harness-darwin-arm64macOS arm64

Windows is not supported. Install does not fail when the platform package is missing; the commands then exit with a message until a binary is provided (see below).

Install caveats

Both commands share the name opencode with the stock opencode-ai package, so the two compete for the same bin. OpenCode 2's @opencode/cli (which also declares opencode2) declares an opencode bin too and collides the same way. The legacy opencode-ai and @opencode-ai/sdk packages stay on the 1.x line.

  • npm: if opencode-ai is installed globally, installing the harness fails with EEXIST because that package already owns the opencode bin. npm i -g --force @fro.bot/harness overwrites the bin. Uninstalling the harness afterwards removes it and leaves no opencode on your system; reinstall opencode-ai if you want the stock command back.
  • bun: a global install silently overwrites the existing opencode bin.
  • mise: which opencode runs depends on PATH order between the tools mise manages. Check with which opencode.

How the binary is found

In order:

  1. OPENCODE_PATH — an explicit path to the native binary (an absolute path is recommended), not a script or a dispatcher such as a mise shim. A bare or relative value resolves against the current directory and is never looked up on PATH.
  2. The platform package — @fro.bot/harness-<os>-<arch>, resolved from the installed harness.
  3. HARNESS_ALLOW_PATH_FALLBACK=1 — searches PATH for a native opencode. For development only.

Resolution never runs the binary to check it. Candidates are rejected rather than executed when they are:

  • not a native binary (a script or dispatcher cannot be proven to be the patched build);
  • not executable;
  • one of the harness's own entry points, which would recurse forever. This check compares real paths and inodes, so symlinks and hardlinks to the shim are caught. A copy of the shim is a different file and is not recognized as one.

harness doctor is the exception: it runs the binary with --version and compares it with the expected build. It also prints the binary the opencode command will run (opencode command:) and exits non-zero if that resolution fails, even when the probe passed.

Upgrading

opencode upgrade is unsupported for a harness install, and OpenCode never updates it in place. Update the package with the tool you installed it with:

npm i -g @fro.bot/harness@latest
bun add -g @fro.bot/harness@latest
mise upgrade

Do not run opencode upgrade --method <pm>: that installs stock opencode-ai from the package manager, not the harness. opencode upgrade --major --method <pm> is worse: it removes the global opencode-ai package and installs OpenCode 2 (@opencode/cli), also not the harness.

Since 1.19, OpenCode never installs updates automatically; the autoupdate setting only controls the update notice. The interactive TUI checks for a newer release shortly after startup and every 10 minutes, and may show an update notice or an "OpenCode 2" notice. Set autoupdate: false or OPENCODE_DISABLE_AUTOUPDATE to turn the check off. opencode serve never runs the check. The check reads the newest opencode-ai release from the npm registry for every install method (Homebrew Core is the exception: its formula is OpenCode 2, so the check reports no update). Only a newer 1.x release counts as an update, and the installed version's build metadata is ignored when comparing, so <base>+harness.<sha> is not older than <base>.

The install method is detected by asking each package manager whether opencode-ai is installed globally (a binary under .opencode/bin or .local/bin counts as a curl install). A harness install matches none of these, so its method is unknown, and applying an update from /update, opencode upgrade, or opencode upgrade --major fails: the TUI reports "Installation method not found", and the CLI reports an unknown installation method (opencode upgrade first asks "Install anyways?", defaulting to No).

If stock opencode-ai is also installed under a detected package manager, the method is detected as that manager, and an applied update targets that stock install instead.

Signals and exit codes

The shim runs the binary as a direct child with inherited stdio and stays in your terminal's foreground group, so terminal input, Ctrl-C, and window resizing behave as they do for stock OpenCode.

  • Signals: SIGINT, SIGTERM, SIGHUP, SIGQUIT, SIGUSR1, and SIGUSR2 are forwarded to the child. A signal sent to the whole foreground group, such as Ctrl-C or a terminal hangup, may therefore reach the child twice.
  • Cases that cannot be forwarded: SIGKILL sent to the shim, or an uncaught error inside it, can leave the server running.
  • Hangup protection does not carry through the shim: Node resets inherited signal ignores at startup, so nohup opencode serve and trap '' HUP do not protect a server that runs through the shim. To keep a server alive across a hangup, invoke the native binary directly, not through the shim: nohup "$OPENCODE_PATH" serve with OPENCODE_PATH set to the native binary, or the platform package's bin/opencode. (Setting OPENCODE_PATH alone still launches it through the shim.)

Exit codes:

CodeMeaning
child's codePassed through unchanged
signal deathSIGINT, SIGTERM, SIGHUP, SIGQUIT are re-raised on the shim; any other signal exits 128+n
127Binary not found, rejected by resolution, or a self-reference
126Binary exists but is not executable
1Any other spawn failure, or an unexpected error in the shim

Development checkouts

In a checkout of this repository, bun install links node_modules/.bin/opencode to the workspace shim, so opencode inside bun run scripts resolves to it. The workspace has no platform package, so set OPENCODE_PATH to a native harness binary first:

OPENCODE_PATH=/path/to/native/opencode bun run <script>

License

MIT. Embeds cortexkit/orw's integration method and redistributes a modified OpenCode build; see LICENSE.

版本与发布记录

@fro.bot/harness 共发布 29 个版本,首次发布于 2026/06/05;过去 12 个月发布了 29 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.19.5-harness.bf7f7dfelatest2026/11/078 天前
1.19.4-harness.5bde26352026/10/2719 天前
1.19.0-harness.caa472722026/10/121 个月前
1.18.34-harness.6546eb642026/10/061 个月前
1.18.30-harness.7c4794292026/09/102 个月前
1.18.30-harness.770cf62d2026/09/102 个月前

关于 @fro.bot/harness 的常见问题

@fro.bot/harness 是什么?

Published patched-OpenCode binary with orw-embedded LLM-merge integration — the default OpenCode for Fro Bot

如何安装 @fro.bot/harness?

在项目目录运行 npm install @fro.bot/harness,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 harness、opencode,可以用 npx harness 直接运行。

@fro.bot/harness 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/fro.bot__harness 是否存在。

@fro.bot/harness 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@fro.bot/harness 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@fro.bot/harness 可以商用吗?

@fro.bot/harness 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@fro.bot/harness 的下载量有多少?

根据 npm 官方下载统计,@fro.bot/harness 在 2026/10/16 – 2026/11/14 这 30 天内被下载 1,983 次,日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@fro.bot/harness 还在维护吗?

最新版本 1.19.5-harness.bf7f7dfe 发布于 2026/11/07(8 天前);至今共发布 29 个版本,其中过去 12 个月发布了 29 个;首次发布于 2026/06/05。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。