finish-it

完成它

运行一次交付：从规范来源开始，推进到一个拉取请求；经过至少一轮后，或交付过程中的首次评审在没有待处理事项的情况下通过后，最新发布的评审应反映其当前头部提交。每个步骤都在全新的上下文子 Agent 中运行；代码托管平台是唯一的共享记忆，因此不会在磁盘上持久保存任何内容，重新对该拉取请求调用此技能时，会从代码托管平台所记录的进度继续交付。

以下三个术语贯穿整个技能：

• 规范来源：该拉取请求所实现的问题、任务单或书面规范。
• 轮次：对拉取请求反馈进行一次 resolve-review 处理；没有待处理事项时则跳过，之后由 review-code-publish 重新评审。
• 交付：整个运行过程，可从流程链中的任意步骤开始。

边界

调用此技能即授权底层技能代表其执行所有写入操作：根据文字规范创建问题、打开拉取请求、发布评审、回复、解决讨论串，以及发布处理摘要。它绝不会合并拉取请求、关闭问题，也不会更改标签或指派对象。

交付过程无人值守。底层技能原本会向用户提出的问题，会在拉取请求创建后发布到该拉取请求中；停止时会说明步骤及原因。

如果未安装 implement-publish、review-code-publish、resolve-review 或 review-code，则应在进行任何写入操作前停止，并显示 missing-dependency: <name>。先检查这四项。review-bot 是可选项；若未安装，则记录为回退到已认证用户并暂停门控，不应因此以缺少依赖为由停止。

流程

1. 确定输入

如果存在 docs/agents/issue-tracker.md，请阅读。记录：

• N，请求的轮次总数：调用文本中的整数（rounds: 5、"with 2 rounds"），否则为 3。允许为 0。
• 基础分支：调用方指定的分支，否则为仓库的默认分支。
• 作者身份：本次会话用于编写代码、拉取请求、回复和署名摘要的代码托管平台登录名（gh api user --jq .login）。
• 审阅者身份：在此处根据 docs/agents/issue-tracker.md 一次性确定，该文件声明 Reviewing app 和 Client id，或可选的字面值 Review-token command。如果有字面值命令，则原样使用，不要查询 review-bot；使用 GH_TOKEN=$(sh -c '<review-token command>') gh api graphql -f query='{viewer{login}}' --jq .data.viewer.login 读取登录名；对应用令牌拒绝使用 gh api user。命令缺失、执行失败或其令牌无法通过身份验证，均不构成错误。对于未提供字面值命令的应用，如果已安装，则调用 review-bot 的 Resolve 入口，并提供客户端 ID 和交付目标仓库的 <owner>/<repo>：即拥有基础分支的仓库；存在拉取请求后，则为该拉取请求的基础仓库，绝不能使用检出代码的远程仓库。保留其返回的登录名和命令，不做任何改动。如果该技能不存在、返回任何 unavailable 结果，或字面值命令执行失败，则使用作者身份，并在报告和数据包中记录原因，同时禁用门控。身份解析不会中止交付。若未声明应用或命令，则使用作者身份。发布时令牌被拒绝，则停止该次写入。
• 门控授权：仅当审阅者身份是与拉取请求作者不同的审阅应用时，才视为已授权；这使审阅可以提交 APPROVE 或 REQUEST_CHANGES。使用作者身份回退时，因自我审阅规则，审阅将以 COMMENT 发布，因此门控授权应为禁用。在此处记录此决定；子代理不得自行推断。
• 嵌套审阅者层级：如果调用提供 reviewer tier: <name>，则使用其中的名称，否则未设置。层级未设置时，由各底层技能的分派流程自行选择层级。指定名称的层级将覆盖该选择，并且每个步骤都将其传递给审阅者分派流程。每次分派都必须明确说明所选层级。

调用方未明确的基础分支或规格来源应在此处确定，绝不能交由没有用户可询问的子代理决定。如果无法确定，则在任何写入操作之前停止。

2. 定位交付内容

阅读 Forge，并根据入口表选择第一步。单独一个数字优先表示拉取请求，其次表示议题，具体规则见议题跟踪器文档。

观察到的状态	第一步
纯文本规格说明	创建议题，然后执行议题对应行
议题没有正在关闭它的开放拉取请求	实现
议题已由一个开放拉取请求关闭	执行该拉取请求对应行
当前分支有提交，但没有拉取请求，也没有议题	实现，让 implement-publish 根据分支和提交推断规格说明
拉取请求在任何提交版本上都没有评审	评审，然后进行多轮处理
拉取请求的最新评审在当前提交版本上不是 Approved	进行多轮处理
拉取请求的提交版本在最新评审后发生变动，或有一条晚于最新评审的处理摘要	评审；这会结束尚未计数的轮次，然后进行多轮处理

阅读拉取请求时的注意事项：

• “最新”按 Forge 时间戳判断；若评论经过编辑，则按其最后编辑时间判断。评审和处理摘要均涵盖任何身份发布的内容。人工评审也属于评审。
• 没有关联议题的拉取请求依据其自身文本进行评审；review-code 会处理这种情况。
• 使用 gh pr list --state open --search "<number>" 查找议题的开放拉取请求，并通过正文中的关闭引用确认。

根据纯文本规格说明创建议题：使用 gh issue create，撰写单行标题，并将纯文本原样放在 ## Spec 标题下作为正文；不要添加标签或受理人。读取议题内容；其编号就是后续每一步的规格说明来源。

统计已完成的轮次。 D 是带有 `` 尾标或以 **Addressed** at 开头的一般拉取请求评论数量，不限发布者身份。剩余轮次 = max(1, N − D)。记录 D 和剩余轮次数。

3. 交接信息包

每个子 Agent 都会收到相同的信息包，不会收到之前步骤的任何内容：仓库路径、基础分支、头部分支、拉取请求 URL、议题 URL 或规范来源、轮次编号和剩余轮数、作者身份、评审者身份以及步骤 1 的处理结果（包括任何回退原因）、适用时返回的或原样提供的评审令牌命令、步骤 1 的门控授权，以及指定的嵌套评审者层级或其未设置状态。评审子 Agent 看不到处理者的报告；处理子 Agent 看不到以文本形式呈现的评审。两者都会读取 forge。

将每个步骤作为一个通用子 Agent 分派到全新上下文中，不继承本对话的任何内容；使用 fork_turns="none" 或宿主环境的等效方式。之所以使用通用类型，是因为每个底层技能都会自行分派评审者或验证者；不具备 Agent 工具的类型不适用。说明此次分派选用的层级，并通过等待路由、前台分派或受支持的联接来运行，使工具调用在本会话仍处于活动状态时返回已完成的报告；确认消息或 Agent ID 不算返回。子 Agent 返回后，才为该步骤读取 forge 中的产物。简要指示它按名称调用指定技能并附上信息包；若指定了嵌套评审者层级，则传递该层级，若未设置，则让底层技能自行选择；每次分派或继续前，先选择等待路由，并等待它分派的每个子 Agent 都通过该路由返回——如果报告显示其评审者或验证者仍在运行，则该步骤尚未完成；最后返回报告。

子 Agent 的报告只是一项声明。每个步骤完成后，都要先读取 forge 中该步骤的产物，再继续。以下情况均表示步骤失败：缺少产物；报告显示该步骤自身的子 Agent 仍在等待（early-handback: <step>）；底层技能给出的停止结果不符合该步骤的产物规则；或无法解析规范来源或基础分支。失败步骤会结束本次交付，并需报告步骤名称和失败原因，以及受影响的阶段、可用时的待处理 Agent ID 和缺失的产物：不得重试任何步骤，也不得跳过任何步骤。编排器自身的 forge 写入仅尝试一次；结果不明确时，先读取目标，再最多重试一次，然后报告失败，不得再次写入。

4. 实施

指示子 Agent 使用信息包中的规范来源、基础分支和当前分支调用 implement-publish。

产物：恰好一个处于打开状态且头部分支为该分支的拉取请求。将其 URL 和头部 SHA 记录到信息包中。implement-publish 仅会在本地评审批准最终提交后发布，因此，如果遇到无法满足的门控条件（例如只有人才能回答的问题），就不会创建拉取请求，该步骤也会失败。

5. 评审

指示子 Agent 使用规范来源，对该拉取请求调用 review-code-publish。

产物：由评审者身份提交、且所评审头部为拉取请求当前头部的评审。比较登录名时，两边都忽略末尾的 [bot]：GitHub REST 记录会带有 GraphQL author.login 中省略的后缀，因此未规范化的比较永远无法匹配应用自己的评审。review-code-publish 的 duplicate-review 停止结果会指出已存在的此类评审，因此该评审步骤视为成功；从 forge 读取该评审。记录状态、未决问题和有争议的发现。

6. 轮次

如果本次交付执行了步骤 5，且在当前头提交上，审查结果为 Approved，并且下方的空账目检查通过，则不运行任何轮次并进行报告：对没有任何待处理事项的未变更头提交重新审查，只会重复已有结果。否则，按顺序重复执行剩余轮次：

1. 空账目检查。 在当前头提交上，最新审查结果为 Approved，没有列出未解决问题或有争议的发现，并且没有尚未解决的审查讨论串，也没有未获拉取请求作者回复的反馈。全部满足时，跳过解决步骤，直接进入审查；该轮仍计入轮次。
2. 准备检出环境。 获取更新，确认工作树干净，并在拉取请求当前的头提交上检出其头分支。工作树不干净时必须停止，不得清理。
3. 解决。 告知子 Agent 在该拉取请求上调用 resolve-review。产物：本轮发布的处理摘要，或更新的现有同一头提交摘要；其最后编辑时间晚于本轮所处理的审查，包含与已推送头提交相等、且也等于本地头提交的 addressed head=。记录本轮是否添加了提交。
4. 审查，按步骤 5 的方式，在新头提交上进行。
5. 计入本轮，然后在当前头提交的审查结果为 Approved 且空账目检查通过时提前停止。从本次交付的第二轮开始，如果本轮没有进展，也提前停止：没有添加提交，且审查中唯一尚未解决的事项是有争议的发现或等待他人处理的问题。轮次一旦开始，每次交付的第一轮都必须执行，包括进入时已获 Approved 的拉取请求。

7. 报告

最后提供拉取请求 URL 和头 SHA、最终审查状态、本次交付运行的轮次数以及进入时发现的 D、有争议的发现、未解决问题，以及任何停止的步骤及其原因。每个文件位置都必须使用所报告头提交上 forge 的不可变链接。