企业官网建设流程全解析

• 人工智能
• RAG
• AI Agent
• MCP 服务
• 开发工具

RepoBrain 是一款开源的代码库知识问答引擎（ChatGPT for your codebase），它的Host-Runner 模式可以完全不用 API Key——直接驱动你本机已登录的 Codex、Trae 或 Claude Code CLI 作为推理后端，让rb-ask代码问答和rb-refresh知识库刷新都能零成本跑起来。本文讲清楚它是怎么实现的，以及如何三步配置。

为什么需要 Host-Runner：零 API Key 的代码问答

常规玩法下，rb-ask依赖一个 OpenAI 兼容的 LLM 端点（OpenAI / DeepSeek / Groq / Ollama 等），需要你粘贴 API Key 并按 token 付费。但如果你本机已经登录了某个"无头"Agent CLI——比如 ChatGPT 账号登录的 Codex、订阅制登录的 Trae、或 Claude Code——其实不需要再掏一份 API 账单。

Host-Runner 模式的核心思路是：RepoBrain 只负责"检索与组装"，把"思考"外包给你已付费登录的本地 CLI。

它的两个内置档位：

• codex— 内置预设，直接驱动你本机的codex exec登录态；
• generic— 通用驱动，通过一条RB_HOST_COMMAND命令模板驱动任意无头 CLI（Trae、Claude Code、Gemini CLI 等）。

核心实现都在 host_runner.py 这一个文件里，配合 config.py 中的环境变量定义。

最快配置方法：rb-setup 自动探测已登录 CLI

最省事的路径是交互式命令rb-setup（在 Claude Code 中为/repobrain:rb-setup，Codex CLI 中为/rb-setup）。它会先探测你本机已登录的无头 CLI，并把免 API Key 的本地 Host-Runner 作为首选推荐写入项目根目录的.env（同时自动加入.gitignore）。

探测逻辑来自 rb-setup.md 中定义的登录检查表：

配置完成后，一次刷新 + 一次提问即可：

rb-refresh --workspace . rb-ask "what does this project do?" --workspace .

手动配置详解：RB_HOST_RUNNER 与环境变量

想完全自己掌控？在项目.env里写这几行就行。完整说明见 INSTALL.md 的 "Local host-runner mode without an API key" 一节。

Codex（内置预设，无需命令模板）：

RB_HOST_RUNNER=codex # RB_HOST_MODEL 可选；留空则用 codex 登录态的默认模型 RB_HOST_TIMEOUT_SECONDS=240 RB_HOST_MAX_CONTEXT_CHARS=60000

Trae（generic 通用驱动）：

RB_HOST_RUNNER=generic RB_HOST_COMMAND=trae-cli exec --cd {workspace} --sandbox read-only --skip-git-repo-check --ephemeral -o {output_file} RB_HOST_OUTPUT_MODE=file RB_HOST_TIMEOUT_SECONDS=240

Claude Code：

RB_HOST_RUNNER=generic RB_HOST_COMMAND=claude -p --add-dir {workspace} RB_HOST_OUTPUT_MODE=stdout

常用环境变量一览（定义于 config.py）：

一个易错点：generic 模板里不要写{prompt_file}——省略它时 RepoBrain 会把 prompt 走 stdin 投递，这是最可移植的方式；只有当某个 CLI 读不了 stdin 时才用{prompt_file}。

工作原理：三步把本地 CLI 变成答案引擎

Host-Runner 的完整流程（见 host_runner.py）：

1. 组装只读提问 prompt：_build_host_prompt把"你是 RepoBrain 的本地只读问答器，可以查看文件但不得修改文件/提交/联网"的系统指令、工作区路径、你的问题，以及 RepoBrain 预检索好的项目上下文、检索证据（retrieval evidence）和图谱上下文（graph context）拼成一份完整 prompt；超过RB_HOST_MAX_CONTEXT_CHARS会自动截断并留下说明标记。

2. 只读沙箱执行：以子进程方式启动宿主 CLI。Codex 预设会拼装为codex exec --cd <workspace> --sandbox read-only --ephemeral --skip-git-repo-check --output-schema <schema> --output-last-message <out> <prompt>——注意--sandbox read-only保证宿主 CLI 只能读你的仓库，不能产生任何写副作用。generic 模式则渲染RB_HOST_COMMAND模板执行。

3. 结构化回收答案：宿主 CLI 被要求返回符合 JSON Schema 的{answer, sources, limitations}三元组。RepoBrain 优先从输出文件读取、其次解析 stdout，并容错处理 markdown 围栏和多余前后文本；错误信息里的密钥（sk-...、含 KEY/TOKEN/SECRET 的环境变量值）会被自动打码，防止泄漏到日志。

调用入口在 ask_pipeline.py：一旦检测到RB_HOST_RUNNER，rb-ask就走_ask_with_host_runner单通道，完全不经过 API provider 链。

对 rb-refresh 的影响：单轮模式下的优雅降级

同一个后端也驱动rb-refresh。由于本地 CLI 是单轮、无工具调用的，刷新流程会自动降级（设计文档见 SWARM_PROTOCOL.md 的 "Host-Runner 模式" 一节）：

• 模块文档、map 等无工具阶段：照常通过你的 CLI 生成；
• conventions（三 Agent handoff 链）：压缩为一次单轮生成的 Convention Agent；
• git insights：降级为确定性的预提取数据。

若你设置了 API 后端，则始终优先走完整的工具调用/handoff 流程。想要纯扫描（完全不消耗 LLM）？设置RB_REFRESH_SCAN_ONLY=1。

排错与调优小贴士

• 报Codex CLI is not installed or not on PATH：先安装 Codex CLI 并执行codex login，再重试。
• 报timed out after 240s：大仓库 + 慢网络时把RB_HOST_TIMEOUT_SECONDS调大（基准测试脚本里用的是 600 秒）。
• 答案被截断：调大RB_HOST_MAX_CONTEXT_CHARS，或精简.context/里的知识文件。
• generic 命令找不到：确认RB_HOST_COMMAND的第一个词在 PATH 中可执行，例如which trae-cli。
• 想验证整体状态：安装后运行rb doctor --workspace <项目>，它会报告 engine、provider、知识新鲜度，且不会暴露任何密钥。

小结

RepoBrain 的 Host-Runner 模式把"代码问答引擎"的推理成本变成了零边际成本：检索与知识组装由 RepoBrain 的rb-refresh完成，思考由你已登录的 Codex / Trae / Claude 完成，一行RB_HOST_RUNNER配置即可切换。个人本地使用完全够用（官方也说明它面向个人本地场景，而非托管产品后端），是新手体验"给仓库装上大脑"最低门槛的入口。

• 人工智能
• RAG
• AI Agent
• MCP 服务
• 开发工具