setup-opencode-ralph-rlm

设置 OpenCode Ralph RLM

使用此技能将 Ralph RLM 安装到目标代码库，并使其能在 OpenCode 中作为 ralph-rlm/supervisor 模型使用。

工作流

1. 检查目标代码库。

   • 确认当前工作目录是项目根目录。
   • 根据锁文件和 package.json 脚本识别包管理器和测试命令。
   • 检查是否已有 opencode.json、.opencode/ralph.json 和 .opencode/plugins/。
   • 如果代码库已有 OpenCode 或 Ralph 配置，请在编辑前阅读 references/config-files.md。

2. 如果项目可以接受开发依赖，则安装 Ralph 包。

   • 优先使用代码库已有的包管理器。
   • 包名：@doeixd/opencode-ralph-rlm。
   • 如果用户只想进行一次性设置，则使用 npx @doeixd/opencode-ralph-rlm setup。
   • 不要要求最终用户安装 Bun；发布的 CLI 是 Node 二进制文件。

3. 在项目根目录运行设置命令。

   npx @doeixd/opencode-ralph-rlm setup --worktree .
   

   如果代码库已有 OpenCode 配置，先使用 --dry-run。只有用户明确要求覆盖生成的 Ralph 文件时，才使用 --force。 命令标志和预期输出请参阅 references/cli.md。

4. 检查生成的文件。

   • .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 加载时自动启动提供程序（因此用户无需手动运行 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 应保留现有提供程序，并包含 provider["ralph-rlm"]。

5. 如果自动检测结果不理想，请调整 verify.command。

   • Bun 项目通常使用 ["bun", "run", "test"] 或 ["bun", "run", "verify"]。
   • npm 项目通常使用 ["npm", "test"]。
   • Rust 项目通常使用 ["cargo", "test"]。
   • Python 项目通常使用 ["python", "-m", "pytest"]。

6. 询问是否要将 Ralph 使用指南添加到项目 Agent 指令中。

   • 依次查找 .opencode/ralph.json 中的 agentMdPath、AGENT.md，然后是 AGENTS.md。
   • 创建或编辑指南文件前，请先询问用户。
   • 如果用户同意，则追加一段简短的 Ralph 说明；措辞请参阅 references/agent-guidance.md。

7. 运行诊断。

   npx @doeixd/opencode-ralph-rlm doctor --worktree .
   

   提供程序运行前出现警告是正常的。 如果遇到故障，请阅读 references/troubleshooting.md。

8. 设置模型 — 先检查用户已有的模型；仅在找不到可用模型时才询问。

   需要决定两种模型：

   • Supervisor — 提供程序用于编排的大模型（规划访谈、工具路由、状态）。需要具备可靠的函数／工具调用能力。
   • Worker — OpenCode 会话用于编写代码的模型。Worker 通过 OpenCode 运行，因此已使用 OpenCode 的提供程序／身份验证。

   配置前先检查现有凭据／模型：

   • opencode auth list — 查看已完成身份验证的提供程序。
   • opencode models — 查看可用模型 ID（例如 opencode/deepseek-v4-flash-free、anthropic/claude-*）。 Supervisor：如果用户在 OpenCode 中通过密钥认证了某个提供商（例如 Google、OpenCode Zen），提供商会自动检测到它——无需单独的密钥。因此，通常无需在此进行任何操作。只有当用户想指定特定的提供商／模型，或尚未通过密钥认证任何提供商时，才设置 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。写入前请先征得用户同意。

   如果没有找到可用选项（没有已认证的提供商，也没有密钥）：引导用户先完成认证再启动，例如：

   opencode auth login
   

   或设置 RALPH_SUPERVISOR_API_KEY。至少存在一种凭据配置方式之前，不要启动提供商并期待 Supervisor 能正常工作。参阅 references/config-files.md。

9. 重新打开 OpenCode——提供商会自动启动；随后确认 Supervisor 已就绪。

   • 安装了自动启动插件（默认情况）时，OpenCode 加载时会自动启动提供商——无需手动运行 serve。OpenCode 会在启动时加载提供商和插件，因此请退出并重新打开 OpenCode TUI，让 ralph-rlm/supervisor 模型和插件生效。
   • 检查就绪状态：curl http://127.0.0.1:8787/api/health——supervisor.ready 应为 true（其中会显示解析出的 model、source，例如 opencode-auth:google，以及提供商的 version）。如果无法连接，提供商可能仍在启动（稍等片刻），或者自动启动已被禁用——此时请手动启动：

     npx @doeixd/opencode-ralph-rlm serve --worktree .
     

   • **如果刚刚更新了 Ralph，**请重启以加载新版本。该提供商具有幂等性（每个端口运行一个实例，并可重复使用），且 serve 的启动前检查会拒绝启动重复实例——如果它报告已有不同版本的提供商，请先停止旧实例。
   • 然后选择 ralph-rlm/supervisor 模型。

10. 建议在首次循环前先进行规划。

• 循环的效果取决于其 PLAN.md。建议先与 Supervisor 一起规划目标（它会在 start_loop 前进行访谈），或使用 interview-and-create-plan 技能，而不是直接丢给它一句话目标。

备注

• 设置命令有意采用保守策略：除非传入 --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。