配置参考
Orbi 从部署 home 读取orbi.toml；设置 ORBI_CONFIG 可选择其他文件。相对路径相对该文件解析。启动 tick 前运行 orbi check 校验配置。
仓库与路径
| Key | Type | Default | Allowed values | Meaning |
|---|---|---|---|---|
source_repos | 字符串列表 | 必填 | 非空 owner/repo | 每个 tick 扫描的一个 owner/repo 任务池。多个条目会因当前执行层只有一个 checkout 而 fail fast；多仓库 workspace 尚未提供（Issue #133） |
repo_dir | 路径 | . | 任意路径 | 交付 checkout：Runner 交付 Issue 的仓库。任务 worktree 从它冻结的 origin/<base_branch> SHA 创建，PR 对它打开，slot 锁在 <repo_dir>/.orbi/slots/。自举模式下它就是 orbi checkout 自身；外部单仓库模式（Issue #330）下是外部用户仓库 X |
deploy_home | 路径 | repo_dir | 任意路径，必须存在 | orbi 源码 checkout（Issue #330）：editable CLI 安装来源（自更新）、systemd/ unit 模板、labels.toml、prompt 默认（prompts/prompt.md、prompts/prompt_review.md 未设置时）。缺省 = repo_dir（自举模式，行为不变）。repo_dir 是外部仓库 X 时把它设为 orbi checkout。必须是非空字符串；目录不存在会启动 fail fast |
workspace_root | 路径 | .. | 任意路径 | 包含任务 worktree 和 agent 可修改仓库的目录 |
base_branch | 字符串 | main | 任意非空字符串 | 交付 base 分支；每个任务 worktree 都从冻结的 origin/<base_branch> SHA 创建 |
git_transport | 字符串 | ssh | ssh | https | 交付 checkout 的传输方式（Issue #580）。ssh（默认）：git 数据操作走 [email protected]:owner/repo.git，用机器的 SSH key；setup 会把 HTTPS origin 迁移过去。https：origin 保持 https://github.com/<repo>.git，git ls-remote/fetch/push 的凭据走 gh credential helper（gh auth login --with-token）——无 SSH 私钥的纯 token sandbox 路线。其他值直接让配置加载失败 |
engine_source_track | 字符串 | main | main、branch:<name>、release、tag:<name> 或 sha:<40-hex> | engine source 更新通道（Issue #535，host/deploy-only——仓库的 .github/orbi.toml 永远不允许携带）：每次 service 启动时 deploy home checkout 跟随的源。缺省/main：fast-forward origin/main（#535 之前 dogfood 的行为）——开发主线，每次提交都变。branch:<name>：fast-forward origin/<name>。release（别名 stable）：最新正式 semver tag（排除 pre-release），detached——跟随最新已发布版本，只在发版时变化。tag:<name>/sha:<40-hex>：精确锁定，detached——不改值就永不移动，版本变更永远是一次有意操作（要求可复现的部署用它锁定）；回滚就是把值改回去。checkout 脏、tag/SHA 缺失或任何不可验证状态都会以结构化行让启动失败（见运维） |
allow_stale_runner | 布尔值 | false | true | false | Runner 执行代码新鲜度门禁的离线逃生口（Issue #525）：领取任何 Issue 之前，Runner 必须证明自己执行的代码与配置的 engine source 通道一致——即 engine_source_track（Issue #535），缺省 origin/main，绝不是交付 base_branch（editable 安装看 import 所在 checkout 的 HEAD；非 editable 看安装版本与最新 release tag——全部是本地 git 读操作）。落后或无法证明时输出结构化 runner_source_stale 行（事实 + 修复命令）并 fail fast。true 把同一行降级为告警放行，供离线/受限网络机器继续运行——绝不跳过检查。非法值立即失败 |
调度
| Key | Type | Default | Allowed values | Meaning |
|---|---|---|---|---|
max_concurrency | 整数 | 1 | 1–5 | 本机并发 Orbi 任务数和启用的 Runner timer 数（1..5，即 MAX_RUNNER_INSTANCES 声明上限——Issue #827；实际能稳定跑几条取决于 CPU/内存峰值，调高前先实测） |
unit_name | 字符串或空 | 未设置 | 字母、数字、-、_ | 可选的部署专用 systemd unit 前缀。 |
active_milestone | 字符串或空 | 未设置 | 任意非空字符串 | 新领取扫描的领取范围（Issue #139）：当前活跃的 GitHub Milestone 标题（如 v0.2.0）。设置后 p0/bug/普通三个 ready 扫描只领取该 Milestone 的 Issue（milestone:"<title>" 限定词直接进 gh 搜索查询——其他 Milestone 或无 Milestone 的 Issue 永远进不了队列）；ai-ready 仍是执行开关，领取顺序（p0 → bug → 普通）不变，P0 不跨 Milestone，恢复态（已开 PR、在途重启）不受 Milestone 限制。唯一例外是外部接管扫描（Issue #842 决策 D1）：第五条、排最后的 ready 扫描不带 Milestone 限定，带正文标记 <!-- orbi:external-pr:N --> 的外部 triage 票始终可被认领——外部贡献不属于任何版本的范围，绝不能阻塞发版门禁。未设置 = 所有 ai-ready Issue 都可领取（#139 之前的行为）。用 orbi milestone set <title> 推进（见运维；Runner 下一 tick 发布 ORBI_ACTIVE_MILESTONE variable） |
auto_next_milestone | 布尔值 | true | true | false | 当前 Milestone 关闭且队列为空时是否自动推进。false 保持 active_milestone 不变，记录待确认告警并创建一个不带 ai-ready 或 p0、不会被领取的确认 Issue；人工推进后旧通知会自动关闭。非法值立即失败 |
worktree_retain_hours | 数字 | 72 | 有限正数 | tick 开头任务 worktree 回收的保留窗口（Issue #760，仅宿主/部署侧——仓库的 .github/orbi.toml 不可携带）：已关闭超过该小时数的任务 worktree 会被自动移除（OPEN 的票和有活跃 run 的现场绝不触碰）。机制与 worktree_reclaimed journal 行：运维。必须是有限正数小时，否则启动 fail fast |
模型 provider
| Key | Type | Default | Allowed values | Meaning |
|---|---|---|---|---|
pi_providers | 路径或空 | 未设置 | provider JSON 文件路径 | 指向 Pi models.json 形状 JSON 文件的路径，为每个 run 向 Pi 目录添加或覆盖 provider（Issue #157）。未设置 = Pi 原样使用自己的 agent 目录（第 4 步） |
pi_provider | 字符串或空 | 未设置 | 任意非空字符串 | 每个 run 选用的 provider id（Issue #119）——以 --provider 传给 Pi；设置 pi_providers 文件时必须已在其中定义 |
pi_model | 字符串或空 | 未设置 | 任意非空字符串 | 选中 provider 内的 model id——以 --model 传给 Pi；必须存在于该 provider 的 models 列表 |
pi_thinking | 字符串或空 | 未设置 | off | minimal | low | medium | high | xhigh | max | 以 --thinking 传给 Pi 的思考级别（off、minimal、low、medium、high、xhigh、max） |
pi_extensions | 表列表 | [] | 锁定的 npm:/git 来源或已有本地路径 | 可重复的 extension 表：source 必须是锁定版本的 npm:/git 来源或配置文件相对的现有本地路径；enabled 默认开启，env 只注入当前 Pi 子进程。每次运行都传入 --no-extensions，不会发现全局 Pi extension。 |
review_pi_provider | 字符串或空 | 未设置 | 任意非空字符串 | 评审会话的 provider 覆盖；未设置时回落到 pi_provider |
review_pi_model | 字符串或空 | 未设置 | 任意非空字符串 | 评审会话的模型覆盖；未设置时回落到 pi_model |
review_pi_thinking | 字符串或空 | 未设置 | 同 pi_thinking | 评审会话的思考级别覆盖；未设置时回落到 pi_thinking |
model_wait_probe_url | URL 或空 | 未设置 | 非空 http:// 或 https:// URL | 模型吞请求探针（Issue #233）：模型的 /slots 端点（如 http://127.0.0.1:18082/slots，agent 面向的端口——local-llm-kv-cache 代理从 llama.cpp 透传该端点）。Pi 冻结在 model_wait 时 Runner 探测它，所有 slot 持续 model_wait_probe_seconds 宽限空闲时快速杀掉 Pi 会话。字段语义（吞请求现场、旁路边界）：运维 的 model_wait_swallowed journal 行。未设置 = 探针禁用（#233 之前的行为）。必须是非空 http:///https:// URL，否则启动 fail fast |
model_wait_probe_seconds | 数字 | 60 | 有限正数 | 吞请求探针的持续空闲宽限（Issue #233）：model_wait 期间“所有 slot 空闲”状态需持续多少秒才判定请求被吞并杀掉 Pi。必须是有限正数，否则启动 fail fast |
model_wait_dead_seconds | 数字 | 1800 | 有限正数 | 模型请求挂死阈值（Issue #228）：model_wait 静默多少秒后 Runner 杀掉 Pi 会话并 fail fast。字段语义（完整事件之间的静默、慢生成边界）：运维 的 model_wait_dead journal 行。必须是有限正数，否则启动 fail fast |
review_pi_* 配置让独立评审运行在与实现不同的模型上——见 Reviewing with a different model。
Prompt 与上下文
| Key | Type | Default | Allowed values | Meaning |
|---|---|---|---|---|
prompt | 路径 | prompts/prompt.md | 任意路径 | 实现者 prompt 模板（{{SOURCE_REPO}} 等占位符由 Runner 渲染） |
prompt_review | 路径 | prompts/prompt_review.md | 任意路径 | PR 后独立审查 session 的 review prompt 模板 |
skills | 路径列表 | [] | 绝对、~ 或相对配置文件路径 | 可选 Pi skill 路径（绝对、~，或相对配置文件） |
context_files | 路径列表 | [] | 路径 | 可选 Markdown 上下文文件，以路径形式注入 prompt |
attribution_footer | 布尔值 | true | true | false | 在 Orbi 创建的 PR 正文和 Release notes 末尾追加一行回链；设为 false 可关闭，必须是布尔值 |
交付行为
| Key | Type | Default | Allowed values | Meaning |
|---|---|---|---|---|
dispatch_label | 字符串或空 | 未设置 → ai-ready | 任意非空字符串 | 仓库策略使用的 ready 标签，见仓库配置。 |
human_review_gate | 布尔值 | false | true | false | 人工验收门禁（Issue #763，仅宿主/部署侧——仓库的 .github/orbi.toml 不可携带）：true 时每个交付在 PR 打开时向 Issue 发一条验收清单（栏一：本次 run 已验证的证据——真实测试结果与覆盖层；栏二：按改动路径生成的机器验不了的最小集合——业务意图、UI 视觉与文案、外部环境、证据缺失）。栏二非空时评审轮次在任何 Pi session 之前短路：票回 ai-ready（opened-PR 标签保留作 resume 锚）、槽位释放，此后每个 tick 只花一次 label 读——等待绝不消耗评审轮次预算。人用只有人能打的 ai-human-review 标签确认清单，下一 tick 照常评审/合并（--match-head-commit 零改动）。栏二为空是目标状态：清单明写无需人工介入，交付不要求标签直接通过。默认关闭：关闭时交付/评审/merge/release 与之前逐字节一致。必须是布尔值，否则配置加载立即失败 |
issue_comments_limit | 整数 | 20 | 正整数 | 受信任评论注入上限（Issue #745，仅宿主/部署侧——仓库的 .github/orbi.toml 不可携带）：{{ISSUE_COMMENTS}} 占位符注入多少条受信任评论（OWNER/MAINTAINER/MEMBER/COLLABORATOR 或 runner 自己的 App——与恢复现场同一套 authorAssociation 信任判据），按时间正序、保留最新。超出上限时丢弃更早的，并在注入内容里标明省略条数——绝不静默截断。模板不含该占位符时不发起任何评论读取（#745 之前的行为）。必须是正整数，否则启动 fail fast |
release_ci_wait_seconds | 数字 | 1800 | 有限正数 | release 门禁 CI 上限（Issue #268）：release 状态机在 tick 内等待 release commit 上 pending（queued/in_progress）检查的最长时间，超时以独立原因失败——它只是 release 机的纯上限保护，绝不是交付等待机制（Issue #788 已移除交付路径的 CI 等待：pending 检查把交付顺延到下一 tick）。等待期间以 release_waiting_ci journal 行和进度评论更新可见；最终结论说了算。必须是有限正数，否则启动 fail fast |
release_deliveries_wait_seconds | 数字 | 1800 | 有限正数 | release 等待未完成交付的上限。 |
Steering
Steering 让 Runner 轮询 Issue 中的受信任修正，并带着修正重启正在进行的交付。steering_max_rounds 限制重启次数，避免交付被无限重定向。轮询失败属于纯旁路：会记录日志，但绝不会让交付失败。
详见 Operations 中的 delivery_steered、steering_limit_reached、steering_poll_failed 行。
| Key | Type | Default | Allowed values | Meaning |
|---|---|---|---|---|
steering_enabled | 布尔值 | true | true | false | 启用受信任的 Issue 修正轮询。 |
steering_poll_seconds | 数字 | 60.0 | 有限正数 | Steering 轮询间隔。 |
steering_max_rounds | 整数 | 3 | 非负整数 | 每个交付最多重启的 Steering 次数。 |
Health
| Key | Type | Default | Allowed values | Meaning |
|---|---|---|---|---|
health_alert_repo | 字符串或空 | 未设置 | 任意非空 owner/repo | 接收 Runner crash-loop/stale-pickup 健康 Issue；未设置时从 deploy-home origin 推导。 |