一次性 setup：它改动了什么

orbi setup 会验证本地前提和 CLI、对齐仓库标签、安装 user units，并检查配置的 checkout。 orbi setup 是新机器或新任务池仓库的一次性、配置驱动的初始化入口。它校验或重装 editable CLI 安装、验证本地前提、对齐平台标签、安装 systemd user units、检查 checkout、报告可选模型 proxy——一条命令，稳定的机器可读结果。

orbi setup

--config 仍可用于指定其他配置路径。默认的 orbi.toml 不存在时，setup 会从相邻的 .orbi.example.toml（存在时）生成，否则用 CLI 包内自带的示例（Issue #163），且不会覆盖已有文件。每台机器运行一次（每个新任务池仓库再各运行一次）。它幂等：重复运行从不创建重复的标签、units 或 timer，也从不碰业务 Issue 或业务标签。

按顺序做什么

setup 是 fail-fast：核心前提失败会在任何后续变更之前停下，stderr 给出具体原因，退出码非零。

命令 — PATH 上有 git、gh、python3、uv 和已安装的 orbi CLI（这些前提由你自己安装——setup 只检查；缺失会 fail fast 并给出可执行的安装指引，例如 required command missing: uv (not on PATH) — install uv first: curl -LsSf https://astral.sh/uv/install.sh | sh），且 systemctl --user user bus 可达（没有 user bus 的容器或 headless session 会以 bus 错误失败）。gh 必须 ≥ 2.94.0——队列扫描用到 gh api --paginate --slurp 和 blockedBy 字段，过旧的发行版包（Ubuntu 24.04 自带 2.45.0）能通过本检查，但每个 tick 都会失败；快速开始给出官方安装来源和修复命令。
CLI editable 安装（Issue #152）——官方本地部署是 editable uv tool 安装（为什么——ExecStartPre checkout 同步——定义在快速开始第 2 步）。安装作用于部署 home （deploy_home，缺省 repo_dir——Issue #330）：运行进程已经从配置的 deploy_home 导入时只校验（不调 uv，cli=verified）；否则执行精确的 force editable 重装（uv tool install --force --reinstall --editable --python <interpreter> <deploy_home>， cli=installed）。<interpreter> 遵循兼容选取规则（Issue #861）：系统 Python 满足 requires-python 下限（>= 3.14——Fedora 43 与当前 Arch 自带）时用 --python python3，否则用 --python 3.14 让 uv 自动供应或选择兼容解释器（Ubuntu 24.04 自带 Python 3.12—— 用精确路径钉死该系统解释器会因依赖解析失败而退出 1；python3、3.14 这类宽泛写法会让 uv 选取或供应满足要求的解释器）。外部单仓库模式下绝不从交付 checkout 重装 CLI——repo_dir 可能是没有任何 orbi 打包输入的外部仓库 X。安装失败 fail fast——不装 unit、不半初始化。该步骤从不碰运行中的 Runner 进程（新源码由下一个 CLI 启动加载）。
认证 — gh auth status（已登录且 token 可用）。
每个目标仓库（默认每个配置的 source_repos 条目；--repo OWNER/REPO 时恰好一个）：
- 仓库存在且 viewer 有写权限（gh repo view → viewerPermission 必须是 WRITE、MAINTAIN 或 ADMIN）。GitHub App 的 installation token（ghs_）下该字段恒为空，而其 issues:write 足以管理 labels（Issue #613）：setup 对空字段改用一次性 create+delete 标签探针（gh api）判定，并报告 permission=INSTALLATION；用户 token 保持原有的权限要求；
- 十四个平台标签（ai-ready、ai-in-progress、ai-pr-opened、 ai-fix-needed、ai-merged、ai-blocked、ai-awaiting-merge、p0、ai-epic、 ai-release、ai-content-only、ai-ops-only、ai-human-review、 ai-needs-detail）从部署 home 的 labels.toml（<deploy_home>/labels.toml，Issue #330） 声明式对齐——标签名/颜色/描述的唯一事实源：缺的创建、漂移的更新、从不删除，业务标签（bug、enhancement、…）从不被碰。外部单仓库模式下标签来自 orbi checkout，绝不来自交付 checkout X。
Systemd units — 部署 home 的模板（ <deploy_home>/systemd/[email protected]、 <deploy_home>/systemd/[email protected]；自举模式下即 orbi checkout， Issue #330）幂等安装到 user unit 目录（与 install-units 相同的安装：复制、一次性迁移 #149 之前的非模板 unit、daemon-reload、按 max_concurrency 启用 @1（值为 1）或 @1/@2（值为 2），并停掉多余 timer——从不启动、停止或重启 service），然后报告每个 timer 实例的 enabled/active 状态和下次触发时间。
Checkout + git transport — 检查配置的交付 checkout repo_dir （自举模式下是 orbi checkout，外部单仓库模式下是用户仓库 X）： origin remote 的传输方式（Issue #114、#580），由 orbi.toml 的 git_transport 选择。ssh（默认）：git 数据操作（fetch、push—— 包括 .github/workflows/*.yml）走 SSH （[email protected]:owner/repo.git），所以已有的 HTTPS origin 在这里用普通的 git remote set-url origin [email protected]:owner/repo.git 迁移（setup 是人工授权的迁移路径——Runner 本身从不改写 remote）。 https（纯 token sandbox 路线）：origin 保持 https://github.com/<repo>.git，凭据走 gh credential helper （gh auth login --with-token）——SSH origin 在这里迁移到 HTTPS URL，全程不需要 SSH 私钥。两种模式下 URL 都必须匹配第一个配置的 source repo——指向另一个仓库的 remote 从不被迁移（改写会把 checkout 指向另一个仓库），直接以 setup_failed reason=... origin remote repo mismatch ... 失败； git ls-remote <expected-url> 必须退出 0（配置的传输可达且已认证—— ssh 模式失败是 setup_failed reason=... ssh_unreachable ...，https 模式是 ... transport_unreachable ...，没有回退）。然后是只读部分：当前分支、干净 worktree（checkout 不干净会失败： timer 的 ExecStartPre fast-forward 拒绝脏 worktree，Runner 就永远无法启动）、base 新鲜度（本地 HEAD 对比刚 fetch 的 origin/<base_branch>——只报告，不失败：timer 每次启动都会把干净 checkout fast-forward）。
可选模型 proxy — 检查 local-llm-kv-cache proxy 的 health endpoint（http://127.0.0.1:18082/health），报告为可选：它的缺失或不健康只是输出里的 warning，从不阻塞核心 GitHub/Orbi setup。

setup 从不创建业务 Issue、从不领取任务、从不启动 Pi、从不修改保护分支。

外部单仓库模式（deploy_home）

外部单仓库模式（Issue #330，PR #334）下，配置把两个 checkout 分开： deploy_home 是 orbi 源码 checkout，repo_dir 是用户仓库 X。setup 按此路由——第 2 步（CLI editable 安装）、第 4 步（labels.toml）和第 5 步（unit 模板）作用于 deploy_home，第 6 步（checkout + git transport）检查 repo_dir：X 的 origin 必须是第一个配置的 source repo 所配置的 git_transport，X 的 worktree 必须干净，X 的 base 新鲜度只报告。注意外部模式下 timer 的 ExecStartPre fast-forward 作用于部署 home（orbi checkout）而不是 X——X 只在 Runner 创建任务 worktree 时被读取。 deploy_home 缺省即自举模式：一切照旧作用于 repo_dir。一个实际后果：已安装 systemd unit 从 <deploy_home>/orbi.toml 读配置（{{ORBI_REPO_DIR}} 占位符渲染的是 deploy home 路径），所以外部模式下 orbi.toml 和可选的 .orbi/env 放在 orbi checkout——用 --config <deploy_home>/orbi.toml 运行 setup。

选项

选项	含义
`--config PATH`	`orbi.toml` 配置（默认：`$ORBI_CONFIG` 或 `orbi.toml`）
`--repo OWNER/REPO`	只初始化这个配置的 source repo（默认：每个配置的 source repo）
`--installed-dir PATH`	user unit 目录（默认：标准 `~/.config/systemd/user`）
`--json`	以 JSON 而不是 `key=value` 行输出结果

输出

默认输出是稳定的 key=value 行（每个关注点一行；含空格的值加引号）， agent 和脚本可以解析：

setup=ok version=4 base_branch=main
cli=verified source=/path/to/checkout/src/orbi/__init__.py
repo=orbi-build/orbi permission=ADMIN default_branch=main labels=12/12
service=installed path=~/.config/systemd/user/[email protected] sha256=9f2c...
[email protected] enabled active=true next="Fri 2026-09-18 16:45:00 UTC"
checkout=remote=origin branch=main clean=true base_fresh=true remote_url=https://github.com/orbi-build/orbi.git protocol=https migrated=false ssh_reachable=- transport_reachable=true
model_provider=NOT CONFIGURED — edit orbi.toml (pi_providers/pi_provider/pi_model), fill /path/to/checkout/.orbi/pi-providers.json and put the key in /path/to/checkout/.orbi/env (PROVIDER_API_KEY)
model_provider_guide=See https://docs.orbi.build/getting-started#4-configure-the-model-provider
model_endpoint=optional optional_proxy=unhealthy url=http://127.0.0.1:18082/health

cli=verified 表示运行中的 CLI 已经从部署 checkout 导入 orbi （editable 安装就位）；cli=installed 表示 force editable 重装已执行。 labels=12/12 表示十二个平台标签都与 labels.toml 一致；next 是 timer 的下次触发时间（没有时为 -）。model_provider=NOT CONFIGURED 是 warning，从不改变 setup 退出码；下一行的 model_provider_guide 会告诉你在哪里配置。optional_proxy 是 healthy、unhealthy 或 unavailable，从不改变退出码。migrated=true 表示 setup 把处于相反传输的 origin 改写成了配置传输的 URL（重跑后报告 migrated=false）； ssh_reachable 是 SSH git ls-remote 探测结果（https 模式下为 -—— 不做 SSH 探测），transport_reachable 是当前生效传输的探测结果（Issue #580）。 --json 输出等价的 JSON 文档：

orbi setup --config orbi.toml --json

成功与失败示例

成功（退出码 0）：

$ orbi setup
setup=ok version=4 base_branch=main
cli=verified source=/path/to/checkout/src/orbi/__init__.py
repo=orbi-build/orbi permission=ADMIN default_branch=main labels=12/12
service=installed path=~/.config/systemd/user/[email protected] sha256=9f2c...
timer=[email protected] enabled active=true next="Fri 2026-09-18 16:45:00 UTC"
checkout=remote=origin branch=main clean=true base_fresh=true remote_url=https://github.com/orbi-build/orbi.git protocol=https migrated=false ssh_reachable=- transport_reachable=true
model_provider=NOT CONFIGURED — edit orbi.toml (pi_providers/pi_provider/pi_model), fill /path/to/checkout/.orbi/pi-providers.json and put the key in /path/to/checkout/.orbi/env (PROVIDER_API_KEY)
model_provider_guide=See https://docs.orbi.build/getting-started#4-configure-the-model-provider
model_endpoint=optional optional_proxy=unhealthy url=http://127.0.0.1:18082/health

（这里可选 proxy 没运行——注意 optional_proxy=unhealthy——但核心 setup 仍以退出码 0 成功。）失败（退出码非零，stderr 输出 setup_failed reason=...）：

setup_failed reason=required command missing: uv (not on PATH) — install uv first: curl -LsSf https://astral.sh/uv/install.sh | sh (https://docs.astral.sh/uv/getting-started/installation/)
setup_failed reason=systemctl --user user bus unavailable (is a systemd user session running?): ...
setup_failed reason=editable tool install failed for /path/to/checkout: ... (fix: uv tool install --force --reinstall --editable --python 3.14 /path/to/checkout)
setup_failed reason=repo not accessible: nobody/no-such (gh repo view failed: ...)
setup_failed reason=insufficient permission for owner/repo: viewerPermission='READ' (one of ['ADMIN', 'MAINTAIN', 'WRITE'] required to manage labels)
setup_failed reason=installation token cannot manage labels in owner/repo: ... (the GitHub App needs the Issues read/write repository permission and must be installed on owner/repo)
setup_failed reason=label alignment failed for owner/repo: ai-ready (gh label create failed: ...)
setup_failed reason=checkout is not clean: /path/to/checkout (uncommitted changes: ' M src/orbi/runner.py') — commit or stash them first: ...
setup_failed reason=checkout check failed for /path/to/checkout: ssh_unreachable: git ls-remote [email protected]:owner/repo.git failed: ... [email protected]: Permission denied (publickey). — fix SSH and retry
setup_failed reason=checkout check failed for /path/to/checkout: transport_unreachable: git ls-remote https://github.com/owner/repo.git failed: ... stderr=fatal: Authentication failed — 检查 gh 凭据（`gh auth status`）后重试

缺失的前提命令（例如 uv）、仓库错误、无法创建的缺失标签（权限）、脏 checkout、传输不可达（没有回退）或缺 systemd user bus 都会带具体原因停下——不会半初始化而没有明确信号。

幂等性

在已初始化的机器上重跑 setup，对外部状态是 no-op：已一致的标签不重写， unit 模板从仓库重新复制（漂移修复），配置的 timer 保持其 enabled 或 disabled 状态，不创建或修改任何 Issue 或业务数据。报告的 hash 和状态跨运行稳定。传输迁移是一次性的：第一次运行后 origin remote 已匹配配置的 git_transport，重跑只重新验证（migrated=false）。

从这里开始

核心概念

模型 Provider

配置与运行

参与贡献

参考

发布

一次性 setup：它改动了什么

按顺序做什么

外部单仓库模式（deploy_home）

选项

输出

成功与失败示例

幂等性

​按顺序做什么

​外部单仓库模式（deploy_home）

​选项

​输出

​成功与失败示例

​幂等性

按顺序做什么

外部单仓库模式（deploy_home）

选项

输出

成功与失败示例

幂等性