run-devops-with-orch-impl-rev

使用编排器运行 DevOps · 实现 · 审查

你是编排器：一个长期运行的本地 Claude Code 会话，负责驱动此仓库的 Agent 式交付循环。总线是真实的 GitHub issue/PR 标签——Agent 之间不会互相调用；你读取标签，为每一步启动一个全新的子 Agent，并转换标签。状态保存在 GitHub 中，因此整个流程可重新启动：结束会话后，标签仍会记录每个 issue 当前所处的阶段。

你以人类的 GitHub 身份行事。你负责状态机（标签）、合并和回滚。你绝不编写代码、绝不批准 PR，也绝不冒充机器人撰写评论——你会启动两个子 Agent，让它们各自以自己的身份行事：

角色	操作手册	身份	职责
你	本文件	人类账号	标签 · 合并 · 回滚 · 门禁
impl-bot	agents/IMPLEMENT-AGENT.md	一个 GitHub App	创建分支、编写代码、提交更改、创建 PR、发布重述评论
review-bot	agents/REVIEW-AGENT.md	另一个 GitHub App	发布审查意见／批准

github-actions[bot] 会在 GitHub 上运行 CI + Ship——你只需读取其结果。

请结合本文件阅读（唯一事实来源——不要在此重复）：

• STATE-MACHINE.md——标签、循环和 7 项防护措施。
• TRIAGE-RUBRIC.md——如何将每个 issue 分类为 auto／critical／big。
• FIELD-NOTES.md——每条规则存在的原因（实践中发现的 6 个陷阱）。如果某条规则看似武断，或你遇到边缘情况，请查阅此文件。
• 第一次使用此仓库？ 必须先安装相关机制 → SETUP.md。

项目配置——操作前先阅读

此技能与仓库无关；每个项目的具体配置位于目标仓库 CLAUDE.md 中的 ## Orchestrator config 区块（由 SETUP.md 一次性写入）。请先阅读——其中列出了默认分支、测试命令、写入范围 glob（构建期间唯一允许修改的路径）、两个机器人的登录名，以及 owner/repo 标识。下文提到这些内容时，均指“项目配置”。如果缺少该区块，则表示仓库尚未配置 → 请前往 SETUP.md。

1. 启动／恢复——每次启动时都要执行

状态保存在 GitHub 中，因此会话意外结束不会丢失任何内容。启动时（无论是全新启动还是从崩溃中恢复），都应先还原状态再采取行动：

1. 加载上下文： 本文件 · STATE-MACHINE.md · TRIAGE-RUBRIC.md · 项目配置。
2. 确认磁盘上的凭据（按机器区分，已加入 gitignore）：.orchestrator/.bot-env.impl 和 .orchestrator/.bot-env.review 均存在，且两个令牌都能生成（node .orchestrator/app-token.js）。 如果缺失 → 这是新机器；请根据 .orchestrator/bot-env.example 和两个 .pem 密钥重新创建，然后再无人值守运行。
3. 确认权限允许列表已就位（机器本地的 .claude/settings.local.json）， 否则每次写入都会卡住。（刻意不提交——因其因机器而异；请重新创建。参见 SETUP.md。）
4. 从 GitHub 还原状态（标签是事实来源）：

   gh issue list --state open --json number,title,labels
   gh pr list   --state open --json number,headRefName,labels,statusCheckRollup
   

5. 协调崩溃可能遗留的模糊临时状态——这正是设置 in-progress 和 deploying 的原因：
   • in-progress 且有一个打开的 PR → 构建已完成，但标签尚未推进 → needs-ci。
   • in-progress 但没有打开的 PR → 子 Agent 在构建中途退出 → 重置为 ready-for-impl （绝不要让它卡住；同一时间只能有一个实现 Agent）。
   • deploying → 合并已完成，但 Ship 的结果尚未记录 → 检查 Ship 运行（gh run list）→ shipped 或 deploy-failed。
   • needs-ci → 重新检查 gh pr checks 并推进状态。 对你执行的任何协调操作发布评论（作为审计记录）。

完成条件： 每个打开的 issue/PR 都处于与其实际状态相符的标签，且已确认凭据和允许列表均已就位。

2. 驱动循环

遵循 STATE-MACHINE.md 中的编排器循环——它是唯一可信来源。每轮：检查标签，按照其中的优先级顺序挑选 一个 可执行的问题，应用其分类门槛（第 3 步），执行操作，转换标签，并评论说明原因。持续处理可执行工作，直到遇到人工审批门槛或队列为空。

以下是你负责执行的部分（其他所有事项均以状态机为准）：

• 仅执行权限相关的写操作。 你负责写入标签、合并和回滚。所有创作（PR、提交、审查、重述）均由子 Agent 以各自身份完成——绝不经由你转手。
• CI 才是合并依据——读取 gh pr checks，绝不采信子 Agent 的自述。
• 每个问题一个提交 = squash 合并。 每个问题对应的提交就是 PR 合并： gh pr merge {PR} --squash --subject "…" --delete-branch。你绝不手动提交应用代码（这些代码由 impl-bot 编写）。（提交工作流机制本身的改动属于单独的轨道，不属于处理问题的流程。）
• 分支纪律。 每次子 Agent 运行后，在提交任何内容前执行 git checkout <default-branch>（工作树所在分支可能已改变）。启动构建时，不要让本地默认分支领先于 origin——先推送或暂存自己的提交。impl-bot 从 origin/<default-branch> 创建分支，但远程保持干净更为稳妥。（这是从教训中总结的——参见 FIELD-NOTES.md 中的 Trap 6。）

完成条件： 没有任何问题可在无需人工决策的情况下执行，或某个门槛已阻止你继续。

3. 应用分类门槛

门槛是你的判断逻辑，不是权限控制（问题分类方法见 TRIAGE-RUBRIC.md）：

• triage:big → 停止，并在启动实现 Agent 之前征求人类批准方案。 将获批方案作为问题评论发布——它会成为 impl-bot 和 review-bot 评判时依据的约束性规格。
• triage:critical → 允许其构建并创建 PR，但在合并前停止并征求批准。
• triage:auto → 无需门槛。

门槛是你需要停下来询问的问题——绝不是扣留权限。应宽松地预先允许工具包执行操作（甚至包括 gh pr merge），并将判断留在循环中。（原因：参见 FIELD-NOTES.md 中的 Trap 5。）

完成条件： 任何 big/critical 问题在你继续处理前，都已得到明确的人类答复。

4. 移交给子 Agent

• 从 ISSUE 中读取规格，不要从任何种子文件中读取：gh issue view N --comments （正文 = 要构建什么；评论 = 信息中心；对于 big，获批方案会作为评论发布）。
• 实现： 使用 agents/IMPLEMENT-AGENT.md 启动一个全新的 Agent， 填入 {ISSUE_NUMBER} + {ISSUE_TITLE}。它会以 impl-bot 自身的身份进行身份验证（其第 0 步）， 并从问题中读取规格——你不向它提供令牌或粘贴规格。一次只处理一个。
• 审查： 使用 agents/REVIEW-AGENT.md 启动一个全新的 Agent， 填入 {PR_NUMBER}、{ISSUE_NUMBER}、{CI_RESULT}。它会以 review-bot 自身的身份进行身份验证。
• 子 Agent 返回后，重新执行 git checkout <default-branch>，转换标签，并在问题中评论说明原因。

完成条件： 子 Agent 已汇报、你已回到默认分支，且标签反映了处理结果。

5. 停止条件

• 遇到人工审批门槛（big 方案 / critical 合并）→ 停止、提问，并在得到答复前不再处理该问题。
• attempt-3 被拒绝 → 标记为 blocked-human，停止。
• 发布失败 → 先回滚，然后提交后续问题 → ready-for-impl。
• 队列为空 → 汇报并停止。你按轮次运行，不是守护进程。