/rb-setup

description: First-time setup. Configure the LLM API key, or a no-API-key local host runner (Codex / Trae / Claude / any headless CLI) that RepoBrain uses for codebase Q&A and refresh. / 首次 setup，配置 RepoBrain 代码问答与 refresh 所需的 LLM API key，或无需 API key 的本地 host runner（Codex / Trae / Claude / 任意无头 CLI）。

You are running first-time setup for the RepoBrain plugin. The user just installed the plugin and needs an LLM backend configured before the ask/refresh commands will work (`/repobrain:rb-ask` in Claude Code; `/rb-ask` in Codex CLI). There are two families of backends:

1. **API-key providers** (OpenAI-compatible) — write `OPENAI_*` keys. 2. **Local host runners (no API key)** — drive a headless CLI the user already has logged in (Codex, Trae, Claude, or any command that answers a prompt on stdin). This covers both `rb-ask` **and** `rb-refresh`: refresh runs its tool-free stages (module docs, map) through the host runner and automatically falls back to deterministic output for tool/handoff stages (conventions, git insights).

Goal: write a `.env` file at the current workspace root.

你正在执行 RepoBrain 插件的首次 setup。用户刚安装插件，需要先配置一个 LLM 后端，ask/refresh 命令才能正常工作（Claude Code 内为 `/repobrain:rb-ask`；Codex CLI 内为 `/rb-ask`）。后端分两类：

1. **API-key 提供商**（OpenAI 兼容）—— 写入 `OPENAI_*` 配置。 2. **本地 host runner（无需 API key）**—— 驱动用户本机已登录的无头 CLI（Codex、Trae、Claude，或任意能在命令行吃 prompt、吐文本的命令）。这条路同时支持 `rb-ask` **和** `rb-refresh`：refresh 的无工具阶段（module 文档、map）走 host runner，工具/handoff 阶段（conventions、git insights）会自动降级为确定性产物。

目标是在当前工作区根目录写入 `.env` 文件。

Step 1 — Detect existing config / 步骤 1 —— 检测已有配置

Read `.env` at the workspace root if it exists. If `OPENAI_API_KEY` or `RB_HOST_RUNNER` is already set, ask the user whether to overwrite the RepoBrain LLM/host-runner keys. If they say no, confirm "already configured" and stop.

如果工作区根目录已有 `.env`，先读取它。如果已经设置了 `OPENAI_API_KEY` 或 `RB_HOST_RUNNER`，询问用户是否覆盖 RepoBrain 的 LLM/host-runner 配置。若用户选择不覆盖，确认“already configured / 已配置”并停止。

Step 2 — Ask which backend (use AskUserQuestion) / 步骤 2 —— 询问后端（使用 AskUserQuestion）

First, detect which local headless CLIs are available so you only offer runners that can actually work. Run these checks (ignore ones that error):

先探测本机可用的无头 CLI，只向用户提供真正能用的 runner。运行以下检查（报错的忽略即可）：

• `command -v codex` and, if present, `codex login status`
• `command -v trae-cli` and, if present, `trae-cli login status`
• `command -v claude` (Claude Code; logged-in state is implicit)
• `command -v gemini`, `command -v ollama`

Present these options. **List the detected local CLIs first** (they need no API key), then the API-key providers:

向用户展示以下选项。**优先列出探测到的本地 CLI**（无需 API key），再列 API-key 提供商：

• **本地 CLI（无 API key）** — pick this if `codex` / `trae-cli` / `claude` / `gemini` was detected. Drives your already-logged-in CLI for both `rb-ask` and `rb-refresh`.
• **OpenAI** — gpt-4o-mini / gpt-4o
• **DeepSeek** — cheap, strong on code
• **Groq** — fast, free tier
• **阿里灵积 (DashScope)** — qwen 系列
• **NVIDIA NIM** — generous free tier
• **Ollama 本地** — no key needed, runs a local model server
• **其他 OpenAI 兼容端点** — custom URL

If the user picks **本地 CLI（无 API key）**, ask a follow-up with the concrete detected runners (e.g. Codex / Trae / Claude) so they choose exactly one.

如果用户选择 **本地 CLI（无 API key）**，再追问一次，列出具体探测到的 runner（如 Codex / Trae / Claude），让用户选定其中一个。

Step 3 — Collect URL / key / model / 步骤 3 —— 收集 URL / key / model

3a — API-key providers / API-key 提供商

Use this table to set the URL and suggest a model based on the provider:

根据用户选择的提供商，使用下表设置 URL 并建议模型：

| Provider / 提供商 | `OPENAI_BASE_URL` | Suggested `OPENAI_MODEL` / 建议模型 | |---|---|---| | OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` | | DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` | | Groq | `https://api.groq.com/openai/v1` | `llama-3.3-70b-versatile` | | 阿里灵积 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-max` | | NVIDIA NIM | `https://integrate.api.nvidia.com/v1` | `meta/llama-3.3-70b-instruct` | | Ollama 本地 | `http://localhost:11434/v1` | `llama3.2` (key can be `ollama`) | | 其他 | ask the user | ask the user |

For non-Ollama providers ask the user to paste their key. For Ollama use `OPENAI_API_KEY=ollama` (the engine requires the field to be non-empty).

非 Ollama 提供商需要让用户粘贴 API key。Ollama 使用 `OPENAI_API_KEY=ollama`（engine 要求该字段非空）。

3b — Local host runners (no API key) / 本地 host runner（无 API key）

For a local runner, first **verify the CLI is logged in** — do NOT ask for an API key and do NOT write a fake `OPENAI_API_KEY`. If the login check fails, tell the user to log in first and stop:

选了本地 runner 时，先**确认该 CLI 已登录**——不要询问 API key，也不要写假的 `OPENAI_API_KEY`。若登录检查失败，提示用户先登录并停止：

| Runner | Login check / 登录检查 | `RB_HOST_RUNNER` | Notes / 说明 | |---|---|---|---| | Codex | `codex login status` must report a ChatGPT login | `codex` | Built-in preset; model via `RB_HOST_MODEL` | | Trae | `trae-cli login status` must report logged in | `generic` | Set `RB_HOST_COMMAND` (below) | | Claude | `claude` present (login is implicit) | `generic` | Set `RB_HOST_COMMAND` (below) | | 其他 CLI | ask the user how to run it headlessly | `generic` | Set `RB_HOST_COMMAND` (below) |

For **Codex**, no command template is needed — it is a built-in preset. For every **generic** runner, write an `RB_HOST_COMMAND` template. Use these verified templates (all deliver the prompt on **stdin** and read the answer from `{output_file}`, so `RB_HOST_OUTPUT_MODE=file`):

**Codex** 无需命令模板（内置预设）。所有 **generic** runner 都需要写 `RB_HOST_COMMAND` 模板。使用下列已验证的模板（都通过 **stdin** 传入 prompt，从 `{output_file}` 读回答案，因此 `RB_HOST_OUTPUT_MODE=file`）：

| Runner | `RB_HOST_COMMAND` | |---|---| | Trae | `trae-cli exec --cd {workspace} --sandbox read-only --skip-git-repo-check --ephemeral -o {output_file}` | | Claude | `claude -p --add-dir {workspace}` (uses `RB_HOST_OUTPUT_MODE=stdout`) | | 其他 | Ask the user for a command that reads a prompt on stdin and prints the answer. Add `-o {output_file}` if the CLI supp