Skip to main content
Orbi 将密钥保留在本地，把保护分支操作限制给 Runner，并要求先通过审查的 PR 才能合并。 Orbi 在你的机器上运行一个带 GitHub token 的自主 coding agent。 安全模型刻意简单：交付契约里的硬边界、本地密钥、没有远端状态存储。

​
交付边界

  • GitHub Issue 和 label 是唯一的状态存储；Orbi 没有数据库、消息队列或 Web UI。
  • Python Runner 不是 daemon：systemd 用户 timer 每五分钟启动一个 tick，每个 tick 最多处理一个 Issue，或恢复一个已打开的 PR，然后退出。
  • Orbi 没有任务 DAG、多 agent 并行、风险模型、策略引擎或 fallback path。命令错误会快速失败，并把现场记录在 journal 和 Issue 评论中。
  • 没有业务任务超时：模型缓慢不代表失败。命令错误、环境不可用或无法解决的审查会快速失败。
  • Orbi 不会发现仓库，不会自行合并或 push 保护分支，也不会在没有可用模型端点时运行。

​
AI 从不 merge 或 push 保护分支

  • 实现者 Pi 在提交的交付处停止：不 fetch base、不 push、不创建 PR——Runner 推送 task branch（普通 push，从不 force）并开一个 PR （Issue #186）。Pi 不 merge、不 push main/master、不 force push、从不自动解决冲突。
  • Runner 是唯一 merge actor，且只通过已审查的 PR merge：clean REVIEW_VERDICT——通过向后扫描读取，容忍评审者的自然语言包装 （Issue #774），绝不采纳非判定行的 REVIEW_VERDICT 提及，两个互相 冲突的 verdict 判为失败，并绑定被审查的 head SHA（Issue #591：经 Issue 正文、diff 或评论注入的 verdict 行永远覆盖不了评审者的真实 结论，指向其他 head 的 verdict 永远不会合并）——merge 门禁（PR head 包含最新远端 base、PR mergeable、远端 head 仍是被审查的 head）、gh pr merge --match-head-commit 保证只有被审查的 head 落地。
  • 默认分支上的 GitHub branch protection 是最终边界：把保护分支的 权限限定在运行 Runner 的账号（或谁都不给——由 Runner 的 token 执行 merge）。
  • 交付状态是推导出来的，从不信任公开文本：恢复现场只从 trusted maintainer（OWNER/MAINTAINER/MEMBER/COLLABORATOR）发布的评论读取； branch/worktree 路径由配置的 repo、Issue 编号和 run id 推导——公开 评论永远无法把 Runner 指向任意本地路径。机器可读的记录是隐藏的 orbi:scene:v1 带版本块（由 src/orbi/scene.py 渲染和解析）， 旁边的可读文本仅供人看。

​
GitHub token（API）与 SSH（git 数据）——两条通道

  • GitHub API 操作（Issue、PR、label、comment、merge）用 gh 认证（gh auth status 必须成功）。使用细粒度 personal access token，限定在 Orbi 实际工作的仓库，最小权限：contents （read/write）、pull requests（read/write）、issues（read/write）、 metadata（read）。避免组织级或经典宽 scope token。
  • Git 数据操作（fetch、push——包括 .github/workflows/*.yml）用 机器的 SSH key 走 [email protected]:owner/repo.git（Issue #114）； 或在 git_transport = "https"（Issue #580）下用 gh credential helper 走 https://github.com/<repo>.git（纯 token sandbox 路线）。 workflow 推送从不依赖 OAuth App 的 workflow scope——那是阻塞 Issue #106 的 HTTPS/OAuth 传输。启动前检查验证配置的传输，损坏时 fail fast（没有回退）。
  • 两条通道从不混用：SSH 从不做 API 认证，GitHub API 也从不走 SSH。 默认 ssh 传输模式下 gh token 不是 git 数据凭据（凭据是机器的 SSH key）；https 传输模式下（Issue #580）token 按显式配置、经 gh credential helper 充当 git 数据凭据。 token 存在 Runner 机器上 gh 的本地凭据存储；SSH key 在用户的 SSH agent/config 里。两者都不写入仓库、配置文件、journal 或 GitHub 评论。
  • 日志按构造脱敏：带密钥的命令日志固定为 <redacted>，工具摘要截断 并屏蔽。完整 prompt、Issue body 和 token 永远不进 journal 或进度 评论。
  • 按正常周期轮换 token；泄露的 token 被限制在它可见的仓库内。

​
本地状态文件

Orbi 保留从不出机的本地状态：
  • 配置（orbi.toml）：本地、gitignored。仓库只提交打包进 CLI 的 example（src/orbi/example_config.toml）。
  • Run 产物：plan、test log、session JSONL 和 review 证据在任务 worktree（.worktrees/...，gitignored）。
  • Slots：<repo_dir>/.orbi/slots/slot-N 锁文件（通过 checkout 的 .orbi/ 目录约定 gitignore）。
  • KV cache 文件（仅当你运行可选的 local-llm-kv-cache proxy）：磁盘上的 prefix 和 session KV 状态（例如 ~/.llama-slot-cache/*.bin）包含从你的 prompt 派生的序列化模型状态——当作敏感本地数据处理，留在同一台 机器，不再需要缓存的 session 时删除。
如果你在共享机器上运行 Orbi，给 Runner 用户独立的 home 目录，让 配置、worktree 和 KV 文件只属于该用户。

​
仓库级配置：信任模型

仓库可以在 .github/orbi.toml 放交付策略文件（见 工作流）。claim 时从默认分支 tip 读取。允许它的 信任论证与 CI workflow 已经适用的论证相同：
  • 无合并权的贡献者无法把文件落到默认分支，不在范围内。
  • 有合并权的维护者本就控制默认分支上的 CI workflow——任意代码 执行加仓库 secrets。策略键的边际风险因此 ≈ 0。
  • 与 Dependabot/Renovate 不同，Orbi 能合并自己经评审的产出。即使 prompt injection 穿透评审，白名单策略键的最坏结果也只是可见、可 逆的策略变更——run 评论始终记录 repo_config: <sha>，并在变更时 附有效键值 diff。
红线是凭据外送。决定 ORBI_GITHUB_TOKEN 与模型 API key 发往何 处的键——pi_provider、pi_model、pi_thinking、pi_providers、 pi_extensions、model_wait_probe_url endpoint 以及一切 endpoint/key 字段——永久 host-only。一个部署宿主服务多个池 （zcode-website / zcode-e2e / 生产），一个仓库配置失守不能把宿主全部 凭据引向别处或在池之间横移。同理 source_repos/repo_dir/deploy_home/workspace_root（跨池横移）与 prompt/prompt_review/skills（系统上下文的持久化注入通道）都是 host-only。仓库文件出现任何 host-only 键都会让 claim fail-fast， Issue 进入 ai-blocked 并列出违规键。不认识的键则改为记一行警告后忽略 （Issue #1329），host-only 集合不受影响。 以下交付策略键可被仓库写入：base_branch、active_milestone、 auto_next_milestone、context_files、dispatch_label、 steering_enabled、steering_poll_seconds、steering_max_rounds、 release_confirmation 和 clarify_thin_tickets。Steering 值只影响该仓库； 省略的键回退到宿主配置。策略变更是默认分支 变更，因此用 GitHub 原生评审机制保护该文件——把 .github/orbi.toml 加入 CODEOWNERS，改它必须 owner 过目。