工作流

• 修复 — 当 X，应该 Y，实际 Z。示例： #1074 — 当 gh auth status 退出码为 1 且当前账号有效时，Runner 应该解析出该 账号；实际却因退出码让交付失败。
• 变更 — 当 X，用户应该能够 Y；今天不能，因为 Z。示例： #1048 — 用户从 发布镜像启动 runner 时，应该得到一个配好模型 provider 的 runner；当时还没有任何代码读取 ORBI_PI_* 变量。

​

完整链路

ai-ready                任务被派发（orbi add，或人工加标签）
  -> ai-in-progress     Runner 领取：加标签，从冻结的 origin/<base> SHA
                        创建 worktree，启动 Pi session（prompt 携带
                        Issue body 加受信任评论时间线 {{ISSUE_COMMENTS}}，
                        Issue #745：只收 OWNER/MAINTAINER/MEMBER/
                        COLLABORATOR 评论，按 issue_comments_limit 截断
                        并显式标明省略条数）
  -> ai-pr-opened       PR 验收通过（base 新鲜度、run marker、Fixes #N）；
                        该 tick 随即结束并释放槽位（Issue #788）——
                        交付等待它的评审 tick
  -> review             一个 tick 一步：可恢复扫描把 opened-PR 交付分类
                        为 RESUME_REVIEW；PR head 的 CI 仍 pending 时记
                        一行 journal（`delivery_ci_pending`）并跳过该候选
                        （Issue #1473）——tick 继续走 in-flight 与
                        fresh-claim 扫描，而不是就此结束（有界延迟，不丢
                        交付）。否则独立
                        Pi session——唯一的阻塞阶段，槽位只被占用一段
                        Pi 运行时长——审查精确的 base/head SHA，并在
                        会话内修复 findings（代码、完整测试、分层
                        覆盖率门禁（Issue #234）、只 push task
                        branch），然后输出 REVIEW_VERDICT。其 prompt
                        除关联 Issue 的受信任评论时间线外，还携带**当前
                        PR** 上受信任的人类反馈：正式 review 状态以及
                        行内评论的文件/行号锚点。交付身份自己的 review
                        会被排除；PR 反馈只是输入，不是交付状态，也不会
                        往 PR 写 label。合并后的 Issue/PR 时间线共用同一个
                        issue_comments_limit 上限；读取 PR 反馈失败会记录日志
                        并退回仅使用 Issue 评论。
  -> ai-fix-needed      会话内未能修复 finding，PR 落后最新 base / 有
                        merge conflict，或已有 run/PR 的**可恢复失败**
                        （Issue #50：Pi 执行失败、验证失败、未推送本地
                        commit）：失败 comment 写入 Issue
                        和 PR，带完整现场（run_id、PR、branch、worktree、
                        session、phase、last activity、具体错误）；下一
                        个 tick 在同一 run_id、branch、worktree、PR 上
                        启动下一个审查会话
  -> merge              clean verdict（其 head 字段等于 PR head，
                        Issue #591）+ merge 门禁（head 包含最新 base、
                        CI 已有结论、PR mergeable、远端 head 未变——
                        每项只读一次：CI pending 或 mergeable UNKNOWN
                        把合并顺延到下一 tick，Issue #788）
  -> ai-merged          Orbi 自动合并模式：成功终态；合并同时清除
                        `ai-ready`，合并后的 Issue 只剩 `ai-merged`
                        （Issue #1526；不回溯已合并的 Issue）；
                        PR body 的 Fixes #N 原生关闭 Issue
  -> ai-awaiting-merge  已知策略阻塞：Issue 评论写明维护者要做的一件事；
                        完成后 Orbi 在后续 tick 恢复并合并 PR

​

运行中的交付修正

• 一个任务 = 一个 run = 一个 feature branch = 一个 worktree = 一个 PR。 review/fix 循环期间 PR 编号永远不变；只有它的 head 可以前进。
• 只有两个 opened-PR 状态会被自动拾取：ai-pr-opened（等待 review） 和 ai-fix-needed（等待下一个审查会话）。ai-ready 作为新工作被 领取；ai-blocked 从不自动恢复。携带回填的 ai-in-progress 标签的 交付仍会被拾取（Issue #178：review 中被杀的 Runner 会留下该标签—— 正向的 opened-PR 限定已保证 implement 阶段的 Issue 不会匹配该扫描）。
• review/fix 循环有界（5 轮）。已完成轮数存在受信任现场里 （review_round 字段，Issue #788）：每条轮次评论携带更新后的现场 块，下一 tick 从中读出推进后的计数（人工在 block 之后把 Issue 改回 ai-fix-needed 的恢复仍会重置预算，Issue #483）。超轮仍有 findings 时 Issue 标记 ai-blocked（超轮是人工决策）；可恢复失败（Issue #50） 保持 ai-fix-needed。无论哪种，PR、branch 和 worktree 原样保留。 评审会话自己也守卫预算（Issue #878）：开工前其 prompt 会读本交付 （同一 run_id）的轮次评论，当同一失败原因已连续出现在两轮及以上 时，直接发点名重复的 findings verdict，不再重复同一修复路径—— 同一堵墙最多撞两轮。
• tick 内零等待（Issue #788）：旧进程内等待循环（wait_for_delivery、 对 CI/mergeability 的轮询、release_ci_wait_seconds / mergeable_wait_seconds）已移除。所有等待都走 waiting 原语——写状态、 返回、释放槽位，下一 tick 重读（delivery_ci_pending、 merge_gate_ci_pending、merge_gate_mergeable_unknown）。可恢复 扫描直接跳过 CI 仍 pending 的候选（Issue #1473），pending 的 PR 因此不再占掉一整个 tick。崩溃恢复 路径就是主路径。
• base 前进由 task branch 上对最新 origin/<base> 的普通 git merge 吸收（冲突手工解决），然后重跑完整测试。不 force push、不自动解决 冲突、不 push 保护分支。
• 吸收契约（Issue #877，Runner 机器校验）：一轮评审开始时 head 已落后 origin/<base> 或 PR 有冲突时，该轮结束必须满足二者之一——分支包含 origin/<base>（git merge-base --is-ancestor 为真），或 verdict 为 findings 且写明「本轮尝试吸收但放弃」及具体原因。head 仍不含 base 的 pass 会在轮次评论里被 Runner 点名为违反吸收契约（ review_absorb_abandoned）；既有 5 轮有界语义不变。
• Git transport（Issue #114、#580）：git 数据操作走配置的传输方式 （git_transport：默认 ssh——git over SSH——，或 https 走 gh credential helper），GitHub API 操作留在 gh token 上——完整的双通道边界与启动前检查见运维； 凭据见安全。

​

Reviewing with a different model（用不同的模型评审）

# 实现运行在一个模型上，独立评审运行在另一个模型上。
pi_provider = "z-ai"
pi_model = "glm-5.3-flash"

review_pi_provider = "groq"
review_pi_model = "groq/compound"

​

合并账本：external_commits 与 commits

Orbi merged PR: <url>
- review: pass, no findings (2 review rounds)
- merged into: main

<details><summary>Run details</summary>

- merge_commit=…
- review_rounds=N
- commits=M
- external_commits=K
- run_id=…

</details>

• commits —— 合并时 PR 分支相对 base 的全部 commit 数（比例的分母）。
• external_commits —— 不在引擎自己推送历史里的 commit 数（开 PR 时的 head 加上 Runner 自己推的每一轮 review/fix head；绝不检查 git 作者 身份）。0 = merged as-is：合并前没有人改过交付分支的一行。计数在 合并后通过 merge commit 的父链读取（M^1 为 base 端、M^2 为 PR head），减去引擎记录的推送线：最后一个引擎推送 head；外部接管 （Issue #608）时再排除接管的贡献者 head（推送线的起点），贡献者的 commit 保持为外部。
• external_commits=unknown —— 推送历史无法证实（重建的 worktree 丢了 run-state 记录；某轮 fix 推送在记录之前回合已结束且历史不完整；或 记录的 head/base 不是合并 head 的祖先）。squash 或 rebase 合并 （Issue #1480）没有 M^2，两项指标同样为 unknown。数不出来的历史 绝不写成 0。

​

交付标签

​

人工验收门禁（ai-human-review）

• 栏一 · 本次 run 已验证的（证据，不是待办）：PR head 的 CI 检查 状态（Issue #1613：引擎不再解析本地测试日志）、覆盖层（仓库测试套件）、 改动文件数。
• 栏二 · 机器验不了的最小集合，按每个交付的改动路径与可用证据生成 （不是硬编码的”人类专属”模板）：业务意图（测试只证明实现与测试一致， 不证明测试与意图一致）、UI 视觉与文案、外部环境验证，以及 head 的检查 未通过或 diff 不可读时的证据缺失条目。

​

薄 ticket 闸门

​

票派发：content、dev、ops

• 信任边界是（凭据，票面）——不是命令白名单。 会话原样获得 runner 的全部环境（gh 凭据、CLOUDFLARE_API_TOKEN、AWS keys 等，外加 deploy home 的 .orbi/env 文件）；凭据给多宽是用户的决定，runner 不做二次裁剪。
• 票面即授权。 会话只执行票面写明的 ops 动作（合并哪个 PR、部署 哪个环境）；票面之外的动作回帖说明并停。人工审批门（environment approval、Release 批准）不由会话代行——这是提示词约定，不是执法代码。
• 交付 = 证据（Issue #526 的事实文化）：每一步把真实命令与真实 输出 / API 返回原文贴到票上；未执行的步骤如实标注未执行。纯 ops 运行 （无 commit）以 Runner 关闭 Issue 并摘除 ai-in-progress 收尾—— 无 PR。附带代码 commit 则照常走 PR 路径（审查 + 合并）。

​

Run marker 与 run_id

• 该 attempt 的每条 journal 行（前缀 [e07383c2]）；
• Issue/PR 评论：可见字段 run_id=e07383c2 + 隐藏机器可读 marker <!-- orbi:run=e07383c2 -->；
• 里程碑与场景评论还携带隐藏的 runner marker <!-- runner=1a2b3c4d -->： 写出评论的部署指纹——执行 checkout 的 HEAD；非 editable 安装为包版本； 探测失败为 unknown（live progress 评论与 PR 评论不带它）；
• Orbi opened PR 场景评论携带隐藏的带版本 run 现场 <!-- orbi:scene:v1 {json} -->（src/orbi/scene.py）：这是 resume 扫描解析的机器可读恢复记录——现场损坏与现场缺失是两个不同的失败 分支（Issue #786）；
• 稳定的按 Issue 命名的 feature branch（orbi/<owner>-<repo>-issue-<N>）；
• worktree 名（.worktrees/orbi-<owner>-<repo>-issue-<n>-e07383c2），以及 Pi session 目录和 run 产物；
• PR body——稳定 marker <!-- orbi:run=e07383c2 --> 是 PR 契约 的一部分；Runner 拒绝没有它的 PR。

journalctl --user -u [email protected] -u [email protected] | grep e07383c2
gh search issues "e07383c2" --repo OWNER/PILOT-REPO

​

失败记录：orbi:failure:v1

<!-- orbi:failure:v1 {"schema":1,"outcome":"blocked","reason_code":"github_transient","action_code":"requeue","retry_safe":true} -->

​

PR body 契约：Fixes #N

​

Epic、Release task 与 P0 优先级

• Epic：协调 Issue，把一组相关任务归在一起（例如 v0.1 release checklist）。它带 ai-epic 标签。Epic 本身不是可直接执行的任务： 实际工作拆成独立的 ai-ready Issue，每个一个 runtime outcome、一个 PR、一次 review、一次 merge。Runner 从不领取 Epic（Issue #93）： 普通领取扫描跳过它并记录结构化日志 epic_not_claimed issue=N repo=...（不领取、不改标签、不建 worktree、 不启动 run、不占 slot），重启恢复扫描也排除它。Epic 的子票声明唯一 来源是 GitHub 原生 sub-issues 关系：所有子 Issue 必须 CLOSED（或其 PR 已 merged），且没有 open 的原生 blockedBy。正文中的引用（包括 Children/Child Issues 段落）不构成声明。没有 sub-issues 或子票、依赖 状态畸形时 fail-closed；Runner 每个 tick 重试并留下幂等审计评论。随后 同一个 tick reconcile open Milestone：title 精确匹配的已发布 Release （draft 不算）且当前没有 open Issue 才关闭，其余情况保持 open。最后 同一个 tick 还会扫一遍 open PR（Issue #746）：head 为稳定交付命名 （orbi/<repo>-issue-<N>）且源票已被人工关闭的 PR，会在 PR 上收到 一条幂等的报告评论——所有 resumable 扫描都只查 state=open 的票，没有 这个扫描该 PR 会永久悬空。合并/关闭由人决定：Runner 绝不自动合， 也绝不越过人的关闭决定去自动关。
• Release task：带 ai-release 标签的 ai-ready Issue（Issue #98）。它不是开发任务。三个普通扫描会记录 release_not_claimed 并跳过它；只有 release fallback 扫描使用 allow_release=True。在领取前， _pick_from_scan 会执行 Milestone 完整性门禁：只要所属 Milestone 还有 其他 open Issue（open_issues > 1），Runner 就记录 release_milestone_incomplete，让 release 保持 ai-ready，并在之后的 tick 重试。这是可恢复的等待，永远不会变成 ai-blocked。Milestone 查询 无法评估时也会跳过领取，并记录 release_milestone_check_failed。该领取层 发生在 process_issue 和所有 release 状态机等待之前，因此排在 open ticket 后面的 release 没有 wait_started，累积的 release_waited_seconds 为零。 领取后，process_issue 才会把它路由到确定性的 release 状态机而不是 run_pi——没有 Pi 会话、没有 PR。状态机幂等且可恢复（重启后恢复同一 run id/worktree），按顺序执行这些步骤：
  1. 严格解析 Issue 正文的 ## Release 声明：version、 base_branch、scope（#N 列表）或 scope_from_milestone， 以及可选的 version_file（默认 pyproject.toml，也可为 package.json 或 none）。声明不携带任何测试契约 （Issue #569）：测试验收就是 release commit 的 GitHub Actions CI 结果（#268 CI-wait 门）。字段缺失、重复或未知 都 fail fast。
  2. 冻结 base——release commit 就是 origin/<base_branch>（在 base-sync 锁下 fetch）。在任何门禁等待之前，校验声明（或默认） 的 version_file 确实存在于该冻结树的根目录（Issue #740）： 不匹配在认领瞬间 fail fast，错误信息列出根目录实际存在的受支持 文件和 none 选项，不会在烧完门禁和范围核验后才以 FileNotFoundError 失败。
  3. 执行发布前门禁。只有上述领取层允许领取后，门禁层的 release_waiting_deliveries 才可能等待带有 ai-in-progress、 ai-pr-opened 或 ai-fix-needed 的 open Issue（release Issue 本身 除外）。release 有 Milestone 时，只有同一 Milestone 内的 Issue 会阻塞 门禁（Issue #671）；没有 Milestone 时仍按全仓扫描。只有 ai-ready 的 Issue 不会阻塞该门禁。这个有界等待使用 RELEASE_DELIVERIES_WAIT_SECONDS；超时就是 delivery wait timeout， release 进入 ai-blocked。随后要求 release commit 的 CI 全绿 （no check runs passes 带明确证据； pending check 是中间态——门禁等待最终结论，每次轮询一条 release_waiting_ci journal 行和一次进度评论更新，上限 release_ci_wait_seconds（默认 1800 秒）；等待超时以独立原因 失败，绝不报成 CI 失败）。open PR 刻意不是门禁（Issue #608， 维护者裁决）：open PR 是队列状态，不是发布前提——是否存在 open PR、多少个、谁提的，与发版无关；滞留 PR 由交付循环自身的 接管/对账机制处理。因真实 gh 失败而查不了的门禁算失败门禁。
  4. 逐项验证 scope：gh pr view 必须报告 MERGED，否则 gh issue view 必须报告 CLOSED 且 stateReason 为 COMPLETED——NOT_PLANNED 关闭（重复/不做）的票在 Scope 证据里 标注为排除、绝不进入 Changelog，Changelog 的 PR 链接只在 PR 位于 带 tag 的 commit 区间内时才写入（Issue #1492）。Changelog 本身源自带 tag 的 commit 区间（prev_tag..release_commit），绝不源自 Milestone Issue 列表：Milestone scope 只决定能否发版，不决定 notes 内容。 对于 Milestone-derived scope， open_milestone_evidence 不等待：仍 open 的 Milestone Issue 会被 排除，并记录为 NOT released (still open in milestone <name>): <item>。 禁止解析复选框——每个 scope 项都对照 live API 检查。
  5. 测试验收就是 release commit 的 CI-wait 门：版本 bump 之后，门禁会对 该 commit 重跑（步骤 3 的 release_ci_wait_seconds 等待），CI 红或 等待超时走既有可恢复失败路径（ai-blocked）。没有本地测试执行 （Issue #569）——release 流程即 bump → push → CI-wait → tag。 如果 CI 红或等待超时，既有失败路径会阻止发布；版本 bump 可以保留在 main，这是可接受的终态。bump 是幂等的，修复 CI 后重试 release 会安全地再次准备所请求的版本。
  6. 打 tag：远端 tag 不存在时，在 release commit 上创建 annotated tag 并普通 push（绝不 --force）。已存在时必须精确指向 release commit——不匹配 fail fast。已存在的 tag 绝不移动、覆盖或 force-push。
  7. 发布 GitHub Release（幂等），notes 带完整验证证据：version、 tag、release commit、逐项 scope 证据、门禁证据、测试证据和 run marker。文档站 Release 页不由状态机写入（Issue #1483）：仓库 自己的 .github/workflows/release-docs.yml（Issue #1482）在 Release 发布时用其 body 生成 docs/release-<version>.mdx 与 docs/zh/release-<version>.mdx，把新版本插到 docs/docs.json 的 Releases/发布 导航分组首位（中英文两处，最新在前），并 转移 (latest) 标题标记。自 Issue #1096 起两个分组各嵌套一个 折叠的 Earlier releases（历史版本）子分组——自动同步把新版本 插到可见页首位，并将超过最新三个版本的可见条目移入该子分组， 让可见分组始终保持最新三个版本。幂等：已有页面内容一致时不重复 生成、不覆盖，无改动时不提交；已有页面内容不一致则 fail fast—— workflow 运行失败，绝不静默跳过。
  8. 给 release Issue 打上 ai-merged 并关闭它（交付终态转换）；merged 事件同时清除 ai-ready 与 ai-in-progress，发布后的 Issue 只剩 ai-merged（Issue #1526）。
  9. 关闭 title 与发布 version 精确一致的 Milestone（Issue #214）， 然后写成功评论（release URL、tag、commit、证据、Milestone 证据）。只按 title 精确匹配（不猜测、不模糊匹配、绝不关别的 Milestone）：0 个 open Issue 时关闭；已关闭 是幂等成功（不重开）；Milestone 缺失或仍有 open Issue 则 fail fast，带上 version、Milestone 编号/链接和 open issue 列表（绝不 静默跳过）。release 票自己永不算未完成工作（Issue #808）：它正被 本次发版关闭，issue 索引落后关票几秒（Issue #754）造成的 「只剩 release 票自己」的陈旧读既不阻止也不拖延关闭；其余任何 open Issue 仍然拒绝关闭。 任何失败：单独进入 ai-blocked（release 是人工决策 点——不自动重试），失败评论带 run marker 和具体原因，异常向上传 播让 tick fail fast。
  ai-release 标签是类型标记，不是交付状态：它不属于交付状态机、 不是 ready 扫描的排除条件，Runner 从不增删它——只有人在派发时 （与 ai-ready 一起）添加。
• P0 优先级：普通 p0 GitHub 标签标记紧急 Issue（生产故障）。它 不是交付状态——只决定 ready 领取顺序，从不改变 Issue 粒度、任何 交付状态或终态语义，Runner 也从不增删它。ready 领取顺序固定： ai-ready+p0 → ai-ready+bug → 普通 ai-ready（三次 gh issue list 扫描，共享完全相同的排除条件和 blockedBy 语义）。 P0 遵守所有现有排除规则和单 slot 约束：被阻塞的 P0 被跳过（回退到 bug/普通扫描），在途的 P0 由重启扫描接回。P0 运行失败单独进入 ai-blocked（领取标签被移除；ai-ready 残留被所有 ready 扫描排除）， 所以没有任何 tick 重新领取——没有无限重试。没有优先级数字或加权队列。

​

仓库级交付策略（.github/orbi.toml）

# .github/orbi.toml
base_branch = "beta"
active_milestone = "v0.5.0"
context_files = ["AGENTS.md"]

​

等待 Milestone 决策时的唯一回复