setup-opencode-ralph-rlm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Setup OpenCode Ralph RLM

设置 OpenCode Ralph RLM

Use this skill to install Ralph RLM into a target repository and make it usable from OpenCode as the

ralph-rlm/supervisor

model.

使用此技能将 Ralph RLM 安装到目标仓库，并使其能够从 OpenCode 中以

ralph-rlm/supervisor

模型使用。

Workflow

工作流

Inspect the target repository.
- Confirm the working directory is the project root.
- Identify the package manager and test command from lockfiles and
```
package.json
```
  scripts.
- Check for existing
```
opencode.json
```
  ,
```
.opencode/ralph.json
```
  , and
```
.opencode/plugins/
```
  .
- If the repo already has OpenCode or Ralph config, read references/config-files.md before editing.
Install the Ralph package if the project can accept a dev dependency.
- Prefer the package manager already used by the repo.
- Package name:
```
@doeixd/opencode-ralph-rlm
```
  .
- If the user only wants a one-time setup, use
```
npx @doeixd/opencode-ralph-rlm setup
```
  instead.
- Do not require Bun for end users; the published CLI is a Node binary.
Run setup from the project root.
bash
```
npx @doeixd/opencode-ralph-rlm setup --worktree .
```
Use
```
--dry-run
```
first when the repo already has OpenCode config. Use
```
--force
```
only when the user explicitly wants generated Ralph files overwritten. See references/cli.md for command flags and expected output.

Review generated files.

.opencode/plugins/ralph-worker.ts

should re-export

@doeixd/opencode-ralph-rlm/worker-plugin

.opencode/plugins/ralph-session-bridge.ts

should inject

x-opencode-session-id

and

directory

```
.opencode/plugins/ralph-autostart.ts
```
starts the provider automatically when OpenCode loads (so the user need not run
```
serve
```
by hand). Skipped if
```
setup --no-autostart
```
was used; disable at runtime with
```
RALPH_AUTOSTART=0
```
.
```
.opencode/ralph.json
```
should have a realistic
```
verify.command
```
.

.opencode/ralph.json

includes

plans: { dir: ".ralph-rlm/plans", active: "default" }

— the named-plan layout. Protocol files (

PLAN.md

RLM_INSTRUCTIONS.md

, …) will live under

.ralph-rlm/plans/<name>/

, not the repo root.

opencode-ralph-rlm plan-path

prints the active plan's

PLAN.md

location.

```
.opencode/ralph.json
```
may include
```
fff.enabled
```
and
```
fff.scanTimeoutMs
```
; leave the defaults unless the project cannot load optional native dependencies.
```
opencode.json
```
should preserve existing providers and include
```
provider["ralph-rlm"]
```
.

Adjust
```
verify.command
```
if auto-detection guessed poorly.
- Bun projects usually use
```
["bun", "run", "test"]
```
  or
```
["bun", "run", "verify"]
```
  .
- npm projects usually use
```
["npm", "test"]
```
  .
- Rust projects usually use
```
["cargo", "test"]
```
  .
- Python projects usually use
```
["python", "-m", "pytest"]
```
  .
Ask whether to add Ralph guidance to the project agent instructions.
- Look for
```
.opencode/ralph.json
```
```
agentMdPath
```
  , then
```
AGENT.md
```
  , then
```
AGENTS.md
```
  .
- Ask the user before creating or editing the guidance file.
- If they agree, append a short Ralph section; use references/agent-guidance.md for wording.
Run diagnostics.
bash
```
npx @doeixd/opencode-ralph-rlm doctor --worktree .
```
A provider warning is expected until the provider is running. For failures, read references/troubleshooting.md.
Set up models — discover what the user already has first; only ask if nothing usable is found.

There are two model decisions:
- Supervisor — the LLM the provider calls for orchestration (planning interview, tool routing, status). Needs reliable function/tool-calling.
- Worker — the model spawned OpenCode sessions use to write code. Workers run through OpenCode, so they already use OpenCode's providers/auth.
Discover existing credentials/models before configuring anything:
- ```
opencode auth list
```
  — which providers are authenticated.
- ```
opencode models
```
  — available model ids (e.g.
```
opencode/deepseek-v4-flash-free
```
  ,
```
anthropic/claude-*
```
  ).
Supervisor: if the user has a keyed provider authenticated in OpenCode (e.g. Google, OpenCode Zen), the provider auto-detects it — no separate key needed. So usually you do nothing here. Only set
```
RALPH_SUPERVISOR_API_KEY
```
(+
```
RALPH_SUPERVISOR_MODEL
```
/
```
RALPH_SUPERVISOR_BASE_URL
```
) or
```
.opencode/ralph-provider.json
```
```
supervisor
```
if the user wants a specific provider/model, or if no keyed provider is authenticated.
Worker: leaving it unset is fine — workers use OpenCode's configured default model. To run coding on a free model, recommend (don't force) setting
```
.opencode/ralph-provider.json
```
```
worker.providerID
```
+
```
worker.modelID
```
to a free OpenCode model such as
```
opencode
```
/
```
deepseek-v4-flash-free
```
. Confirm with the user before writing it.
If nothing usable is found (no authenticated provider, no key): direct the user to authenticate before launching, e.g.:
bash
```
opencode auth login
```
or set
```
RALPH_SUPERVISOR_API_KEY
```
. Do not start the provider expecting the supervisor to work until at least one credential path exists. See references/config-files.md.
Re-open OpenCode — the provider auto-starts; then verify the supervisor is ready.
- With the auto-start plugin installed (default), the provider launches automatically when OpenCode loads — no manual
  serve
  needed. OpenCode loads providers and plugins at startup, so quit and re-open the OpenCode TUI for the
```
ralph-rlm/supervisor
```
  model + plugins to take effect.
- Check readiness:
```
curl http://127.0.0.1:8787/api/health
```
  —
```
supervisor.ready
```
  should be
```
true
```
  (it shows the resolved
```
model
```
  ,
```
source
```
  e.g.
```
opencode-auth:google
```
  , and the provider
```
version
```
  ). If unreachable, the provider may still be starting (give it a moment) or auto-start was disabled — then start it manually:
  bash
```
npx @doeixd/opencode-ralph-rlm serve --worktree .
```
- If you just updated Ralph, restart so the new version loads. The provider is idempotent (one instance per port, reused), and
```
serve
```
  's pre-flight refuses to start a duplicate — if it reports an existing provider of a different version, stop the old one first.
- Then select the ralph-rlm/supervisor
  model.
Suggest planning before the first loop.

A loop is only as good as its
```
PLAN.md
```
. Recommend planning the goal with the supervisor (it runs an interview before
```
start_loop
```
) or via the
```
interview-and-create-plan
```
skill, rather than delegating a one-line goal cold.

检查目标仓库。
- 确认当前工作目录为项目根目录。
- 根据锁文件和
```
package.json
```
  的 scripts 识别包管理器和测试命令。
- 检查是否已存在
```
opencode.json
```
  、
```
.opencode/ralph.json
```
  和
```
.opencode/plugins/
```
  。
- 如果仓库中已有 OpenCode 或 Ralph 配置，请在编辑前阅读 references/config-files.md。
如果项目可以添加开发依赖，则安装 Ralph 软件包。
- 优先使用仓库已经在使用的包管理器。
- 软件包名称：
```
@doeixd/opencode-ralph-rlm
```
  。
- 如果用户只需要一次性设置，请改用
```
npx @doeixd/opencode-ralph-rlm setup
```
  。
- 最终用户不需要安装 Bun；已发布的 CLI 是 Node 二进制文件。
从项目根目录运行设置命令。
bash
```
npx @doeixd/opencode-ralph-rlm setup --worktree .
```
如果仓库中已有 OpenCode 配置，请先使用
```
--dry-run
```
。仅当用户明确希望覆盖生成的 Ralph 文件时，才使用
```
--force
```
。有关命令参数和预期输出，请参阅 references/cli.md。
检查生成的文件。
- ```
.opencode/plugins/ralph-worker.ts
```
  应重新导出
```
@doeixd/opencode-ralph-rlm/worker-plugin
```
  。
- ```
.opencode/plugins/ralph-session-bridge.ts
```
  应注入
```
x-opencode-session-id
```
  和
```
directory
```
  。
- ```
.opencode/plugins/ralph-autostart.ts
```
  会在 OpenCode 加载时自动启动 provider（因此用户无需手动运行
```
serve
```
  ）。如果使用了
```
setup --no-autostart
```
  ，则会跳过此项；可在运行时通过
```
RALPH_AUTOSTART=0
```
  禁用。
- ```
.opencode/ralph.json
```
  应包含合理的
```
verify.command
```
  。
- ```
.opencode/ralph.json
```
  包含
```
plans: { dir: ".ralph-rlm/plans", active: "default" }
```
  ，即命名计划布局。协议文件（
```
PLAN.md
```
  、
```
RLM_INSTRUCTIONS.md
```
  等）将位于
```
.ralph-rlm/plans/<name>/
```
  下，而不是仓库根目录。
```
opencode-ralph-rlm plan-path
```
  会打印当前计划的
```
PLAN.md
```
  位置。
- ```
.opencode/ralph.json
```
  可能包含
```
fff.enabled
```
  和
```
fff.scanTimeoutMs
```
  ；除非项目无法加载可选的原生依赖，否则应保留默认值。
- ```
opencode.json
```
  应保留现有 providers，并包含
```
provider["ralph-rlm"]
```
  。
如果自动检测对
```
verify.command
```
的猜测不准确，则进行调整。
- Bun 项目通常使用
```
["bun", "run", "test"]
```
  或
```
["bun", "run", "verify"]
```
  。
- npm 项目通常使用
```
["npm", "test"]
```
  。
- Rust 项目通常使用
```
["cargo", "test"]
```
  。
- Python 项目通常使用
```
["python", "-m", "pytest"]
```
  。
询问是否将 Ralph 指引添加到项目的 agent instructions 中。
- 依次查找
```
.opencode/ralph.json
```
  中的
```
agentMdPath
```
  、
```
AGENT.md
```
  和
```
AGENTS.md
```
  。
- 在创建或编辑指引文件前，先征得用户同意。
- 如果用户同意，则追加一小段 Ralph 内容；相关措辞请参阅 references/agent-guidance.md。
运行诊断。
bash
```
npx @doeixd/opencode-ralph-rlm doctor --worktree .
```
在 provider 启动之前出现 provider 警告属于预期现象。如有失败，请参阅 references/troubleshooting.md。
设置模型——首先发现用户已有的配置；仅在未找到任何可用配置时才询问。

这里有两个模型决策：
- Supervisor——provider 为编排工作而调用的 LLM（规划访谈、工具路由、状态管理）。需要可靠的 function/tool-calling。
- Worker——OpenCode 启动的会话用于编写代码时所使用的模型。Worker 通过 OpenCode 运行，因此已经使用 OpenCode 的 providers/auth。
配置任何内容之前，先发现现有凭据和模型：
- ```
opencode auth list
```
  ——查看已认证的 providers。
- ```
opencode models
```
  ——查看可用的模型 ID（例如
```
opencode/deepseek-v4-flash-free
```
  、
```
anthropic/claude-*
```
  ）。
Supervisor：如果用户已经在 OpenCode 中认证了带密钥的 provider（例如 Google、OpenCode Zen），provider 会自动检测到它——无需单独的 key。因此通常不需要执行任何操作。仅当用户希望指定特定的 provider/model，或者没有认证任何带密钥的 provider 时，才设置
```
RALPH_SUPERVISOR_API_KEY
```
（以及
```
RALPH_SUPERVISOR_MODEL
```
/
```
RALPH_SUPERVISOR_BASE_URL
```
），或在
```
.opencode/ralph-provider.json
```
中设置
```
supervisor
```
。
**Worker：**保持未设置也可以——Worker 会使用 OpenCode 已配置的默认模型。如果希望使用免费模型运行编码任务，建议（不要强制）将
```
.opencode/ralph-provider.json
```
中的
```
worker.providerID
```
和
```
worker.modelID
```
设置为免费的 OpenCode 模型，例如
```
opencode
```
/
```
deepseek-v4-flash-free
```
。写入前请与用户确认。
如果未找到任何可用配置（没有已认证的 provider，也没有 key）：指导用户先完成认证，然后再启动，例如：
bash
```
opencode auth login
```
或设置
```
RALPH_SUPERVISOR_API_KEY
```
。在至少存在一条可用凭据路径之前，不要启动 provider 并期望 supervisor 正常工作。请参阅 references/config-files.md。
重新打开 OpenCode——provider 会自动启动；随后验证 supervisor 已准备就绪。
- 安装自动启动插件后（默认行为），provider 会在 OpenCode 加载时自动启动——无需手动运行
  serve
  。OpenCode 会在启动时加载 providers 和 plugins，因此需要退出并重新打开 OpenCode TUI，
```
ralph-rlm/supervisor
```
  模型和 plugins 才会生效。
- 检查就绪状态：
```
curl http://127.0.0.1:8787/api/health
```
  ——
```
supervisor.ready
```
  应为
```
true
```
  （其中会显示解析后的
```
model
```
  、来源
```
source
```
  ，例如
```
opencode-auth:google
```
  ，以及 provider 的
```
version
```
  ）。如果无法访问，provider 可能仍在启动（请稍候），或者自动启动已被禁用——此时请手动启动：
  bash
```
npx @doeixd/opencode-ralph-rlm serve --worktree .
```
- **如果刚刚更新了 Ralph，**请重启以加载新版本。provider 是幂等的（每个端口对应一个实例，可重复使用），并且
```
serve
```
  的预检会拒绝启动重复实例——如果它报告存在不同版本的 provider，请先停止旧实例。
- 然后选择 ralph-rlm/supervisor
  模型。
建议在首次循环前进行规划。
- 循环的效果取决于其
```
PLAN.md
```
  的质量。建议让 supervisor 协助规划目标（它会在
```
start_loop
```
  之前进行访谈），或使用
```
interview-and-create-plan
```
  skill，而不是直接委派一个只有一句话的目标。

Notes

注意事项

The setup command is intentionally conservative: it skips existing managed files unless
```
--force
```
is passed.
```
npx @doeixd/opencode-ralph-rlm ...
```
is the portable command. The binary installed by the package is named
```
opencode-ralph-rlm
```
.
Worker search uses optional
```
@ff-labs/fff-node
```
acceleration when available. If it is unavailable,
```
rlm_grep
```
falls back automatically; set
```
RALPH_FFF_DISABLED=1
```
only when native search causes local issues.
Node can run some
```
.ts
```
files directly in recent versions, but Node refuses TypeScript files under
```
node_modules
```
; the npm package should ship compiled JavaScript for the CLI.
Do not hand-copy the legacy v0.1 plugin or tell users to call
```
ralph_spawn_worker
```
.
For supervisor LLM credentials, prefer environment variables first:
- ```
RALPH_SUPERVISOR_API_KEY
```
- ```
RALPH_SUPERVISOR_MODEL
```
Use
```
.opencode/ralph-provider.json
```
only when repo-local supervisor/worker defaults are needed.

setup 命令有意采用保守策略：除非传入
```
--force
```
，否则会跳过已有的受管理文件。
```
npx @doeixd/opencode-ralph-rlm ...
```
是可移植命令。软件包安装的二进制文件名为
```
opencode-ralph-rlm
```
。
Worker 搜索在可用时会使用可选的
```
@ff-labs/fff-node
```
加速。如果该依赖不可用，
```
rlm_grep
```
会自动回退；仅当原生搜索引发本地问题时，才设置
```
RALPH_FFF_DISABLED=1
```
。
较新版本的 Node 可以直接运行部分
```
.ts
```
文件，但 Node 拒绝运行
```
node_modules
```
下的 TypeScript 文件；npm 软件包应随 CLI 一并提供编译后的 JavaScript。
不要手动复制旧版 v0.1 插件，也不要让用户调用
```
ralph_spawn_worker
```
。
对于 supervisor LLM 凭据，优先使用环境变量：
- ```
RALPH_SUPERVISOR_API_KEY
```
- ```
RALPH_SUPERVISOR_MODEL
```
仅当仓库需要本地 supervisor/worker 默认配置时，才使用
```
.opencode/ralph-provider.json
```
。