afk-fleet

afk-fleet

一个无人值守的任务群，可自行实现拆分后的 GitHub 问题待办事项，并在单次会话中连续运行数天，且可随时压缩上下文而不丢失任何信息。两个角色各自持有上下文：

角色	定义	生命周期
launcher	你在其中调用 /afk-fleet 的交互式会话。它只进行一次引导，之后循环执行：运行一个周期（afk cycle）→ 回答它返回的判断 → 休眠 → 重复。	长期运行。一个周期会留下少量精简的 JSON 对象；自动压缩会限制上下文大小，且不会丢掉运行所需的信息。
worker	一个即发即弃的自主编码 Agent（Claude Code 或 qoderclicn，即此次运行的运行时），每个问题对应一个：orca 会创建其工作树和分支，然后使用此次运行的worker 启动命令启动它，使其与 launcher 使用相同的运行时。它的结果只通过 GitHub 传递（其 PR 和问题评论）；它直接发送给 launcher 的唯一内容是没有正文的 wake。	独立于 launcher——launcher 永远不会读取它。

tick 不是第三个角色，也不持有任何上下文：它是在 afk cycle 中以代码运行的、针对 GitHub 的一次协调检查。launcher 发起调用，并获取周期的 state、休眠时间和进度行——以及代码无法做出的少量判断。

此技能只会消费待办事项。 它不会将 PRD/史诗拆分成问题——这是上游工作，而且史诗明确不会被派发。请假设问题已存在，大小适合 worker，已添加标签，并按依赖关系排序。

为何它能无限运行（从设计上即可安全压缩）

单次会话可让任务群连续运行数天。其上下文受常规自动压缩的限制，而且这样做是安全的，因为launcher 必须记住的信息不会只存在于其上下文中 （ADR-0028）：

• 协调检查是代码，而不是文字。 afk cycle 会根据 GitHub 重建状态，并执行所有下一步可通过查表确定的状态转换；只有代码无法决定的内容——少量判断——才会交给你，每项判断都会附上执行任一选项的命令（ADR-0017）。压缩不会丢失规则，因为检查中的规则无需你记住。
• 一个周期只留下少量信息。 一次调用，一个精简的 JSON 对象。它读取的问题列表、PR 检查结果和 ref 扫描信息会在 afk 进程内消失（ADR-0008）；落地操作的长时间门禁运行由 worker 执行（ADR-0027）。
• 任何压缩后，你只需要三个值：仓库、配置和上一次的 state。 state 包含实例 ID 和 worker 启动命令，因此下次 afk cycle 仍会运行同一个任务群实例，无论其他内容是否已被遗忘。绝不要手动重建 state。如果 state 完全丢失，则无法恢复：请停止并说明情况——它持有的声明可以通过 --takeover 接管。
• 如果某个周期的可观察状态没有变化，就完全不执行检查——afk cycle 中的门禁（纯代码）会证明无需操作，刷新租约并返回休眠时间；每六个周期强制执行一次完整检查，以弥补状态哈希无法检测到的变化（ADR-0007）。
• 所有持久状态都存储在 GitHub 中，因此每个 tick 都可以重建完全一致的工作集： refs/afk/claim/<n> ref = 声明（由任务群实例持有） · PR（Closes #n）= 结果 · afk:verdict 标记评论 = worker 未创建 PR 的机器可读原因（already-satisfied / blocked / giving-up / needs-decision）· afk-attempt/<n> 标签 = 重试次数 · refs/afk/heartbeat/<id> ref = 所有者存活状态。tick 之间不记忆任何内容。（面向用户的状态看板评论是将此状态投影到问题页面上的派生视图，每个 tick 都会重新生成——它本身绝不是事实来源，tick 也绝不会读取它。）

模式

• /afk-fleet — 启动器（默认）：引导，然后循环，一轮接一轮。主入口。 调用它即为启动——不预览，只确认一项：所有 PR 将合并到的基础分支（ADR-0023、ADR-0042）。--base-branch <name> 和 --worker-command "<cmd>" 可提前回答引导阶段可能提出的两个问题。
• /afk-fleet --plan — 试运行：在 Act 阶段前短路的一个 tick。它会完整重建（frontier + in-flight + stale classification），打印派发计划，然后退出——不会授予权限、派发或回收任何内容：这是启动前查看计划的方式。它与 --tick 使用相同的重建代码路径，因此计划不会偏离实时 tick 的实际执行结果（ADR-0002）。如果未提供 --base-branch，它的引导探测不会提出任何问题：打印 base.recorded，说明启动时会合并到哪个分支（或者说明尚无启动确定基础分支）。
• /afk-fleet --tick — 一个周期，冷启动，然后输出进度行并退出：执行引导，然后在没有 state 的情况下运行 afk cycle——这是第一个周期，一定会执行 tick；随后回答其判断，不休眠。它的行为与循环中的一个周期完全一致，包括合并各轮更改；退出时不会释放任何内容：它不是排空操作。
• /afk-fleet --takeover — 启动器引导变体，适用于 fleet 因配额而硬停止、且你不打算等待其租约失效的情况：执行完整引导，然后从已失效对等方的认领内容，而非仅从 frontier，播种初始工作集。此后就是普通的常驻 fleet。参见接管模式。

启动器（默认模式）

引导（一次）

调用此技能即为启动（ADR-0023）：调用本身即表示同意在本次运行中推送 worker 分支，并在无人值守的情况下将通过检查的 PR 自动合并到 base_branch。引导不显示预览，也不会征求同意——从步骤 3 直接进入循环。只有在运行无法进行时才会停止（例如配置错误，或合并目标会拒绝所有合并），且只会询问代码无法推断的两项内容，并且仅在你未提供时询问：所有内容要合并到哪个分支（步骤 2——每次启动都要确认，绝不假定：ADR-0042）以及 worker 启动命令（步骤 3）。

1. 加载配置 — afk config --file <target repo>/docs/agents/afk-fleet.md 会解析并验证文件 是否符合唯一的架构（未知键或结构错误 → 报错：停止并报告，不要猜测），并返回规范配置 JSON：包含所有键，并填入默认值（ADR-0009）。启动器持有此 JSON，并将其传给每次 afk 调用——下游不再重新解析 YAML 或重新应用默认值。文件不存在时 → 提议根据模板创建（references/config-template.md），然后停止；绝不使用猜测的设置运行。
2. 建立此 Fleet 实例 — 生成一个简短且唯一的实例 ID（标识此次启动器运行，传给第一个周期，此后一直保存在周期 state 中）。它必须符合 [a-z0-9][a-z0-9-]{0,39} — 小写字母、数字和 -，例如 fl-7fbd5e；afk 会拒绝任何其他 --instance。然后运行 afk probe --repo <repo> --config '<config>' [--base-branch <name>]，它会回答四个兼容性问题并返回本次运行的配置——从此开始使用其中的 config，替代第 1 步的配置：
   • 认领命名空间 — 返回的 config 带有实际可用的 claim_namespace，因此之后每次调用通过 --config 继承它，无需额外传入参数。如果报告 "blocked": true（组织规则集禁止使用 refs/afk/*；detail 是服务端的拒绝原因），则该命名空间会回退到 refs/heads：警告认领引用此时是普通分支，可能触发 on: push CI。请参阅协作式多 Fleet。此处出现 {"error": …} 表示无法向远程推送（身份验证、网络问题）——请修复问题；这不是命名空间问题。
   • 基准分支（ADR-0042）— 每个 Worker 都从该分支切出、以其为目标创建 PR，并最终合并到该分支。它不在任何配置文件中，也没有默认值：每次启动都由人工确认。 如果调用此技能时传入了 --base-branch <name>，就将其传给 probe——这便是确认；无需提问。否则，不带该参数运行 probe：它会返回 base.status == "ask"、base.recorded（此仓库上次启动时确认的分支，或 null）以及 base.default_branch，不会给出其他答案。询问人工：“本次运行所做的所有更改都会合并到 <recorded>——确认吗？”如果有 recorded，先提供它，然后提供 default_branch，再提供他们指定的其他分支。如果没有已记录分支，则不推荐任何分支：任何人都不应想当然地合并到 main。然后使用 --base-branch <answer> 再次运行 probe；此时 base.status == "settled"，其 config 中包含该分支。出现 {"error": …} 表示答案被拒绝——远程上没有该分支（Fleet 不会创建分支），或者当某个认领或仍在运行的 Fleet 实例依赖已记录分支时，指定了不同分支：报告并停止。绝不要在 probe 未传入 --base-branch 的配置上运行周期。
   • 分支保护（仅当 gate.ci: local 时）— protection.verdict == "error" 表示 base_branch 要求状态检查，因此无论本地关卡结果多么理想，gh pr merge 都会被拒绝：在此停止——移除该分支要求的检查，或切换到 gate.ci: required。（gh pr merge --admin 不可选：它也会绕过人工审核。）除非设置了 gate.adversarial_verify_prompt，否则当目标分支会拒绝直接推送（要求 PR 审核、限制推送、分支已锁定）时，也会返回 "error"——合并批次通过推送落地；同样在此停止。"warn" 结果（读取结果不确定——没有管理员权限）会报告，但流程继续。
   • 关卡记录（仅当 gate.ci: local 时）— gate_records.verdict == "warn" 表示远程拒绝 refs/afk/gate/*，因此无法记录关卡运行结果，每次落地都要自行运行关卡（ADR-0030）：说明此情况并继续——这会耗费时间，但不会影响正确性。
3. 确定 Worker 启动命令 — afk worker-command。该工具首先检测运行时（ADR-0014）：环境中有 QODERCN_CLI=1 → qoderclicn（始终使用原版——不使用自定义提供商或封装器——返回其默认值且不会提问）；否则 → claude，并采用现有的提供商一致性流程。Worker 会在不继承本会话任何环境变量的全新登录 Shell 中启动，因此，如果 Claude 启动器使用自定义提供商运行（ckimi、csk、direnv、封装脚本），Worker 否则会被派发到原版 Anthropic，并在之后几天都停留在那里（ADR-0010）。对于 Claude 运行时，该工具会报告：
   • "status": "stock" — 未设置 ANTHROPIC_BASE_URL；使用其 command，且无需提问。
   • "status": "ask" — 使用了自定义提供商，代码无法将其映射回命令。如果调用此技能时传入了 --worker-command "<cmd>"，那就是答案——无需提问。否则，显示 base_url 和找到的 candidates（登录 Shell 中可启动 Claude 的别名；wraps_env: true 表示别名会携带提供商配置），并询问*“Worker 应该使用哪个命令启动？”*——启动时唯一可以提出的问题。无论哪种情况，都要验证答案： afk worker-command --check "<the answer>"。unresolved → 说明未能解析的内容，并重新询问（无法解析的命令会完全无法启动 Worker：此认领不会生成 PR，而是进入重试流程并升级处理，原因只是拼写错误）。confirmed 且 "yolo": false → 警告此命令不包含无人值守标记，因此 Worker 会停在权限提示处——Fleet 无法区分这种情况和已完成的 Worker。"yolo": null 仅表示无法从解析结果中确认这一点。 将得到的 command 原样保留，并传给第一个周期。它是不透明的——绝不解析它，绝不自行拼装，也绝不向其追加标志（向一个会展开为子 shell 的别名追加内容，甚至不是有效语法）。这样，所有凭据都会留在这个人类已经信任的包装器内：整个集群不会复制任何环境变量，不会写入任何文件，也不会将任何密钥放到命令行上。

实例 ID 和 worker 启动命令是本次运行由启动器持有的两个事实：在启动时确定一次，传给第一个 afk cycle，之后始终保存在周期 state 中，不写入文件，并在启动器停止时消失。

接管模式（--takeover）

当集群遭遇硬停止时使用——例如，提供方配额耗尽或进程被杀死——而你正好在现场。租约会将其认领项交给对等实例，但只有在 CLAIM_LEASE_TTL_SECONDS（4500）之后才会这样做，因为心跳是机器能看到的、区分“已死亡”和“仍存活但运行缓慢”的唯一依据。 此刻在场的人类才是知道当前情况的权威；垂死的集群帮不上忙，因为硬停止后完全不会运行任何代码（不会排空，也不会释放）——ADR-0011。

按上文完整执行 Bootstrap——配置、一个新的实例 ID、基础分支、worker 启动命令——使其成为一个真正的集群实例。基础分支仍会被读回并确认，而且不能与已死亡集群的基础分支不同：其认领项以该分支为基础。只有初始工作集不同：

1. 列出 GitHub 仍记得的内容。 已死亡的启动器忘记了自己的 ID；认领标记（instance=<id> host=<host>）和心跳引用却没有忘：

   <skill>/scripts/afk.py takeover --list --repo <repo> --instance <my instance id> --config '<config json>'
   

   向人类显示每个实例的 ID、主机、认领数和心跳时间，并询问要接管哪一个。每行都会标记状态，便于发现错误选择：fresh: true（看起来仍存活）、claim_count: 0（已正常排空——没有可接管的内容）、is_me: true（本次运行）。
2. 强制接管所选实例：

   <skill>/scripts/afk.py takeover --from <dead id> --instance <my instance id> --repo <repo> --config '<config json>'
   

   使用与过期认领回收相同的原子 --force-with-lease 推送，只是跳过过期检查——因此，实际上并未死亡的集群仍会赢得竞争，结果会在 lost 下报告这一情况。 若返回 "action": "confirm"（目标的心跳仍然新鲜），请将警告原样转达，取得明确肯定后再使用 --yes 重新运行；若返回 "error"/"none"，则显示该结果，并按普通启动器运行继续。
3. 随后它就是一个普通的常驻集群。 不作改动地进入 Loop：第一次 tick 会将已接管的认领项视为 mine，并通过续作逐个恢复——如果已死亡的集群在这台机器上运行，则使用第 1 级恢复，因为其工作树仍在这里——并且将工作扩展至前沿，直到达到 concurrency（接管可能导致它持有更多认领项：此时在数量降回限制以下之前，不会再接收新的认领项），直到你停止它。

接管不是重试（它不会读取或递增 afk-attempt/<n>），也不会缩短租约——无人值守安全网的范围完全不变；这只是跨越该等待期、由人类把关的快速通道。由于续作会让每次接管都从更靠后的进度开始，反复接管同一个认领项最终会收敛，而不会陷入循环。

循环

不断重复，直到你停止。每个周期都由你在本会话中自行运行：tick 是调用内部的代码，运行只需几秒。循环的全部记忆是一个不透明的值——上一个周期返回的 state。原样传回；绝不读取其中内容，也绝不对它做算术运算（ADR-0017）。循环所需的所有计数器——上次 tick 结束时集群的指纹、跳过次数、空闲次数、正在运行的任务——都保存在其中，并由代码维护；实例 ID 和工作器启动命令也从第一个周期起保存在其中。

1. 运行一个周期——在前台运行 afk cycle（只需几秒），并原样传入仓库、配置和上次的 state。第一个周期还没有 state：改为传入 --instance 和 --worker-command。
2. 处理它的判断结果，如果有的话：逐项决定，然后运行它给出的命令（见判断结果）。处理完判断结果后，立即执行第 1 步，并使用本周期返回的 state。
3. 否则，显示 progress——周期输出的一行说明——然后休眠 sleep_seconds（ScheduleWakeup）。如果没有判断结果且 sleep_seconds 为 0，就不需要休眠：tick 运行期间有 PR 创建，下一周期会处理它的合并——立即执行第 1 步，中间不要调用 ScheduleWakeup（等待时间不能少于一分钟）。这个数值已经包含了节奏规则——你无需自行应用任何规则，也无法配置：上次 tick 有所操作或有任务正在运行时，采用 BUSY_INTERVAL_SECONDS（90），以便及时合并已完成的 PR——远短于认领租期，因此已持有的认领不会过期；连续 IDLE_TICKS_BEFORE_SLEEP（3）个周期均为空闲（tick 没有做任何事，或跳过，且没有任务正在运行，也没有剩余待处理事项）后，采用 IDLE_INTERVAL_SECONDS（1500）。 唤醒会提前结束休眠。 如果此终端收到一行 afk-wake #<n>，表示工作器的结果已在 GitHub 上（ADR-0020）：立即执行第 1 步，不要等到休眠结束；新的周期结束时安排的休眠会取代当前休眠。这行消息仅表示如此——它只是提示，不代表事实：绝不要仅凭这行消息合并、派发或得出任何结论；周期仍会照常读取 GitHub，而且很可能会 skip。如果在周期运行期间收到唤醒消息，不需要立即处理；等周期返回后，立即启动下一个周期，而不是休眠，并为其添加 --wake：运行中的 tick 可能已经在你看不到的情况下处理了唤醒所指的变更，而 --wake 会让下一个周期无论指纹如何都运行 tick。
4. 收到用户的停止指令时停止：再运行一个周期，即收尾周期——

   <skill>/scripts/afk.py cycle --drain --repo <repo> --config '<config json>' --state '<state json>'
   

   ——释放此集群中所有尚无 PR 的认领，并保留已有未关闭 PR 的认领（见协作式多集群）。显示其 progress，然后不再运行任何周期。正在运行的工作器会自行完成；其 PR 会由同伴（或之后的一次运行）继承并在租期到期后合并；升级处理的问题会继续保留标签，供人工处理。

启动器不会自行执行任何状态转换：除引导子命令外，它运行的都是 afk cycle 或判断结果给出的命令。它绝不读取工作器，不会在自身上下文中计算待处理事项，也无需读取工具的源码（afk.py、afk_decide.py）或 worker-prompt.md——流程由代码实现，因此上下文可以安全地压缩（ADR-0028）。

工具（scripts/afk.py）——确定性的执行力量

该技能运行的每个确定性步骤都是 afk.py 的一个子命令，每个子命令都会打印一个 JSON 对象： 不会再从说明文字中重新推导 git/gh/orca 咒语（ADR-0004）。Act 阶段也一样：启动工作进程、让 PR 进入合并流程、失败、升级处理、搁置和关闭认领，各自都是一次调用，执行完整的有序流程（ADR-0017）——而 afk cycle 则是一次调用，按顺序运行完整的一轮，并在需要的地方返回判断结果。因此，启动器不会自行运行任何原始的 git、gh pr merge、gh issue edit 或 orca worktree/terminal create 命令——实际上不会运行任何 orca 命令：甚至工作进程是否繁忙，也是通过代码读取的（ADR-0021）。完整的接口表——包括每个子命令及其参数和返回格式——见 references/tools.md；当你需要了解调用位置尚未展示的签名时，请查阅该文档。

统一的调用约定。 每个子命令都必须提供本次运行的 --config '<config json>'（两个在配置存在前运行的引导命令——afk config 和 afk worker-command——除外），所有涉及 GitHub 的子命令都必须提供 --repo <repo>。每次调用都传入这两项——配置中包含认领命名空间、租约、标签和门控模式。不带 --config 的调用会被拒绝（退出码 3）；它绝不会使用默认值运行。下方内联示例为便于阅读，省略了这两项（afk release <n> --instance <id>）。

工具是一个可执行词。 <skill>/scripts/afk.py 是可执行文件——直接通过其路径调用，前面不要加解释器。如果要缩短调用，只将路径存入变量，或定义一个 shell 函数（afk() { <skill>/scripts/afk.py "$@"; }）；不要把多词命令（AFK="python3 …"）存入变量——zsh 不会对其进行词拆分，因此批处理中的每个 $AFK … 都会以退出码 127 失败，而与其串联的后续命令仍会运行。

退出码 3 绝不是一种结果。 无法完成任务的子命令会打印 {"error": …} 并以退出码 3 退出。这属于运行故障（身份验证、网络、推送被拒、无法读取远程端、无法删除认领、命令行错误）——应将错误展示给人工；不要把它理解成“无事可做”。如果失败的是 afk cycle 本身，就保留现有的 state，并在上次指定的等待时间结束后开启下一轮；每轮都重复出现的错误，需要停止处理。反过来也成立：退出码为 0 的结果始终是真实答案——mine 为空表示你没有持有任何认领，"released": true 表示认领已删除。在 afk cycle 内部失败的状态转换也属于同样的故障，会记录在该轮的 errors 中，同时继续执行本轮的其余步骤。

一个周期（--tick）——一次调用，tick 在其中执行

一个周期就是一次调用。Tick——即协调过程：从 GitHub 重新构建，然后执行每个下一步是查表的转换——都在其中以代码形式运行（ADR-0017）：不消耗令牌、不会被遗忘，而且无论由谁调用，行为都相同。

<skill>/scripts/afk.py cycle --repo <repo> --config '<config json>' \
     [--state '<state json>'] [--instance <id> --worker-command '<worker_command>']

原样传入上次的 state。如果没有 state——例如启动器的第一个周期，或冷启动的 /afk-fleet --tick——则改为传入 --instance 和 --worker-command（后者必须原样传入：它是不透明的，参见 ADR-0010）；此后它们会保存在 state 中。若传入的 state 不包含它们，周期调用将被拒绝。它会返回 {action, reason, state, sleep_seconds, progress, judgments}：

• "action": "skip"——没有可观察到的变化（ADR-0007），因此未运行协调过程。如果集群持有声明，租约已在此次调用中续期（heartbeat），所以跳过周期绝不会导致租约过期。你无需采取任何操作。
• "action": "tick"（first / changed / forced / unsettled / gate_off）——协调过程已运行，所有能够确定的事项均已处理完毕。它绝不会等待自己启动的工作线程。
• progress——周期的一行说明：清除了什么、授予了什么、派发了什么、回收了什么、升级处理了什么、搁置了什么、重试了什么、提醒了什么，以及集群当前的状态。
• judgments——代码无法决定、因此返回而非代为决定的事项。见下文。
• errors（仅在存在错误时）——[{step, issue, error}]：协调过程中的某个转换失败了。该操作未能解决问题——声明仍由你持有——下一周期会根据摘要再次执行 tick。请将这些错误与进度说明一并展示；绝不要将其理解为“无事可做”，也不要手动重跑该步骤。

--drain 会将其设为本次运行的最后一个周期（"action": "drain"，sleep_seconds 为 null）：不运行协调过程，只执行停止。

此流程的作用

按以下顺序，每一步都是你可以自行输入的同一条 afk 转换 （references/tools.md）：

1. 重建工作集（afk rebuild）：前沿、我的每项声明及其 status、合并队列、仍有效和已过期的同伴声明，以及空闲槽位。
2. 询问正在等待的工作者（afk no-pr）：每项没有 PR 的声明，或因其 PR 放弃了一轮而正在修复的声明；以及每项正在着陆、但其工作者在本次检查时尚未停止的声明。工作者的状态以其报告给 orca 的运行时状态为准，而不是其屏幕上的状态（ADR-0021）。
3. 着陆轮次（afk turn）——每个周期最多一次：交给合并队列头部的声明；或者在两个或更多声明可以一起着陆时，交给它们的合并批次。参见 着陆。
4. 处理已停止的工作者留下的问题（仅限原因有记录的情况）：空闲且没有结果的工作者会收到一次提醒（afk nudge，ADR-0018）；处于着陆轮次，或因其 PR 放弃了一轮而正在修复的工作者若仍无响应，则重启一次（afk turn --restart），若之后仍无响应，则在保留其 PR 的情况下升级处理（afk escalate，ADR-0035、ADR-0045）；giving-up 判定、经证伪的 already-satisfied 判定，以及超过提醒期限仍无响应且没有 PR 的情况，均判定为失败（afk fail）；若积压事项会解决其阻塞因素，则搁置 blocked 判定（afk park，ADR-0022）；若不会解决，则升级处理——needs-decision 判定也立即升级处理（afk escalate，ADR-0041）。
5. 释放所有存续期超过其问题的声明（即工作者已着陆的 PR），以及合并批次推进了其着陆进度、但在关闭问题前被截断的声明；删除所有已失效同伴的虚假锁。
6. 启动工作者（afk dispatch）：首先，通过继续处理处理已持有的声明——孤立声明（始终继续处理，绝不释放回池），以及所有阻塞因素均已解除的声明。然后，仅在空闲槽位中（并发）：按编号从小到大回收并继续处理过期的同伴声明，接着处理前沿；其余继续等待。
7. 发送心跳（先发送每项声明的推送心跳），然后更新上述步骤均未触及的所有声明的状态面板。

仍在编写代码的工作者、正在运行检查的 PR、等待轮次的已完成 PR，以及仍有效同伴的声明：全部保持原样。

判定

每项都是 {issue, kind, question, context, if_yes, if_no}——一个问题，以及针对任一答案的一个 afk 转换，可直接运行：其中已包含仓库、配置、实例 ID 和工作器启动命令。

kind	问题	if_yes	if_no
empty_diff	工作器声明 already-satisfied，随后停止，分支上什么都没有。与基准分支的差异真的为空吗？查看 context.worktree。	afk close	afk fail
no_checks	即将合并的 PR 完全没有检查——渐进式门禁。该问题的验收标准是否已满足？	afk turn --allow-no-checks	afk fail
adversarial_verify	已设置 gate.adversarial_verify_prompt：context.head 能否通过对抗式验证？如果 PR 也没有检查，就只会问这一个问题——验证将是它唯一的门禁。	afk turn --verified <head>	afk fail
reason	不是是非题：转换已确定——这是一次失败，或一次原因尚未记录的升级（检查失败，或判定未提供原因）。从 context.where 重新读取原因，并替换 --reason 后面的文本。	afk fail --reason …——或者，对于升级，使用 afk escalate --reason …	相同命令

• 先做出判断，再运行交给你的命令——按原样运行，只更改 --reason 的文本。 然后立即再次运行 afk cycle，并传入本次返回的 state（判定尚未完成时， sleep_seconds 为 0）。每个答案都是一次转换，因此下一轮周期不会再次询问； 未回答的判定会再次询问。
• bulky: true（adversarial_verify，以及存在于 CI 日志中的 reason）——将其委派给 临时子 Agent（[Agent] 工具），让它返回一行：判定结果或原因。正在审查的差异或 CI 日志绝不会进入你的上下文（ADR-0001）。在此技能中，Agent 工具仅用于这一事项——一次 tick 绝不会用到它。
• 重复执行，直到某轮周期不再返回判定；该轮周期的 sleep_seconds 就是你要等待的时间。

--plan 不会运行上述任何内容：它会打印 afk rebuild --instance <id>——包括前沿、声明及每项将如何处理——仅此而已。与实际执行相同的 rebuild，但没有任何副作用。

协作式多舰队

多个舰队实例——甚至运行在多台机器上、共用一个 GitHub 账户——可以同时处理同一个仓库：所有权存储在隐藏的 refs/afk/* 命名空间下的原子 git 引用中， 存活状态则通过每个实例的租约记录（ADR-0003）。 操作规则（工作前先认领、每次终止转换时释放、仅回收过期认领）见 防护规则；机制及每个 git 子命令实际运行的原始命令见 references/cooperative-multi-fleet.md——需要了解认领、 心跳或回收在底层如何运作时，请阅读该文档。文档还定义了跳过认领引用删除所导致的 幽灵锁故障。

通过续接恢复（已死亡的认领会续接，而非重新开始）

工作进程死亡后，其认领——我的孤立认领、从已死亡的同伴那里回收的过期认领，或通过接管继承的认领——都会从其持久化进度中恢复；只要进度存在，就绝不会从基础状态重新分派。afk dispatch --issue <n> 会自动完成此操作：它会选择对应级别（1 复用工作树／2 在分支顶端重建／3 从基础状态开始——此流程绝不会拆除任何内容），并发送匹配的续接或全新提示词。无人值守的运行始终会续接：此轮次不会询问任何人恢复的状态是否适合继续构建，也绝不会将孤立认领释放回待处理队列。对此有疑虑的人可以查看——references/recovery.md：afk recovery --issue <n> 会显示将要续接的内容——并在分派时手动使用 --start fresh 丢弃它。认领会始终保留；afk-attempt/<n> 计数器既不会读取，也不会递增（续接回答的是“工作进程是否死亡？”，重试阶梯回答的是“工作是否失败？”）。这不是重试流程——红色门禁／对抗性反驳／giving-up 判定会按设计从全新状态开始（参见失败处理——有界重试并升级处理，绝不静默丢弃）。

完成门禁

只有所有已配置的门禁都通过后，PR 才能合并。适用的机器门禁由 gate.ci 决定（ADR-0012）：required（默认值）会等待 PR 的 GitHub 检查；local 则将 gate.local_command 设为门禁，由负责合并的工作进程在即将合并的提交上运行，且绝不读取检查结果。afk land 会应用所配置的门禁（合并——工作进程在轮到自己时合并自己的 PR）；其背后的不变量——本地门禁的两次运行规则、合并流程跳过自身运行的唯一情况（已在远程记录了对即将合并的树运行的绿色结果；ADR-0030)、临时 CI 子读取，以及设置了 gate.adversarial_verify_prompt 时的对抗性验证流程——详见 references/completion-gate.md。运行对抗性验证或将仓库切换为 gate.ci: local 之前，请先阅读该文档。afk gate 和 afk land 是工作进程的子命令：你永远不会运行它们。

合并——工作进程在轮到自己时合并自己的 PR

只有负责该 PR 的工作进程才能合并它。 已完成的 PR 由编写它的工作进程在自己的工作树中使用 afk land 合并：与 base_branch 同步（通过合并，绝不变基——ADR-0012）→ 推送 → 在该精确提交上运行机器门禁 → 将 gh pr merge 固定到通过门禁的提交。合并操作固定到 PR 的头部提交，而非目标分支；门禁运行耗时较长：运行前，合并流程会再次读取自己的轮次和目标分支顶端，只有轮次仍是开始时的轮次，且通过门禁的提交仍包含该顶端时才会合并（否则为 target_moved——它会在同步并对新顶端运行门禁后再次合并）。

同步冲突或合并时门禁未通过，都由该工作进程在当前上下文中就地修复，不需要往返启动器（ADR-0027）。整个工作进程集群提供的是合并轮次：在 PR 轮到自己之前，afk land 不会合并任何内容；轮次一次只分配一个，因此不会有 PR 合并到一个即将变动的顶端上。一个轮次涵盖合并中有界的部分——同步、门禁、合并：如果 PR 的合并过程因冲突或门禁未通过而停止，就会放弃其轮次，并且只放弃一次；之后在轮次之外修复（ADR-0045）。 系统授予轮次——每个周期最多一次，授予合并队列最前面的 PR：在这支队伍已就绪的 PR 中，先选已持有轮次的 PR，然后选曾放弃轮次且已再次就绪的 PR，最后选 PR 编号较小的。授予时会在 PR 上添加一条标记评论以记录轮次，告知工作器——只提交一行，指向一份落地简报——并更新状态看板。如果工作器的终端已不存在（工作器已完成并关闭、机器重启，或认领来自另一台机器），则通过继续执行启动新的工作器，使用同一工作树、同一分支；或者在 PR 当前提交上重新创建的工作树中启动——简报中只要求落地该 PR。启动器不会代为合并。如果在告知工作器之前必须处理的问题尚未解决，就不会授予轮次：仍在运行的检查需等待一个周期；检查失败、PR 完全没有检查，以及仍需进行对抗性验证的 PR，都会作为裁定处理。

其他所有已完成的 PR 都必须等待——不进行同步，不告知任何事，不会因等待而被催促或判失败，也不消耗尝试次数，状态看板会显示等待状态。只有在该 PR 已落地（其认领已释放）、已升级处理（其认领已释放，且已释放的认领不持有轮次），或在周期裁定中被判定失败（afk fail 会关闭其 PR）后的下一个周期，才会授予下一轮次。

PR 持有轮次期间，所有工作都由其工作器完成，并在 PR 上说明上一次 afk land 停止的位置：

• conflict 或 gate_red 是 worker 自己的问题，由它原地修复；而且第一次修复时不在轮次内：landing 会在轮次标记上记录 PR 已让出轮次（given_up），认领状态为 fixing，下一个周期则将轮次授予合并队列中的下一个 PR，或一个合并批次。worker 不会收到任何新指示：它修复问题、提交更改，然后再次运行 afk land；不在轮次内时，这仍会同步并运行 gate 检查，但不会合并任何内容；此时检查通过意味着 awaiting_turn——worker 唤醒 launcher 后停止，PR 再次就绪，并且会在所有从未获得轮次的 PR 之前获授下一个轮次。PR 只会让出轮次一次：下一轮次中，conflict 或 gate_red 会在持有轮次时修复，因此，其他 PR 通过的 landing 不会让它一直等下去。无论是在轮次内还是轮次外修复，pass 都会像处理没有 PR 的 worker 一样监控该 worker：它静默时提醒一次；终端消失时，则通过 continuation 接手 landing。收到提醒后静默超过宽限期，就会在该轮次上重启（afk turn --restart），而不是判定失败：PR 已被认定就绪，未发生的只是 landing——因此会关闭空闲会话，并通过 continuation 在同一个 worktree 中启动一个 worker，只告知它去完成 landing；PR、分支、worktree 和尝试次数均保持不变，重启记录在轮次标记上（ADR-0035）。每轮一次：重启后的 worker 若在收到自己的提醒后再次静默，就会被升级处理——执行 afk escalate，PR 保持打开，分支和 worktree 保留，不消耗尝试次数，将原因和 worker 最后一个屏幕的内容记录到 issue 上，并释放认领，从而腾出轮次。这一流程——告知 → 宽限期 → 提醒 → 宽限期 → 重启 → 宽限期 → 提醒 → 宽限期 → 升级处理——限定了一个轮次，也同样适用于让出轮次后的修复；流程中的任何一步都不会丢弃内容。
• afk land 会在同一次运行中等待同步所推送的 head 上必须运行的检查：检查通过就合并，检查不通过则标记为 gate_red。这不涉及任何周期。
• awaiting_ci、needs_verify 或 no_checks 表示下一步由 fleet 处理——landing 的等待超时（--checks-timeout）时，检查仍在运行；或者同步移动了已作出判断的 head：pass 会再次运行 afk turn，等待新 head 上的检查、请求对新 head 进行 verify，然后告知 worker 再次执行 landing。该 PR 仍持有轮次。

每条路径都遵守的不变量：最终落到目标分支上的内容，必须是经过 gate 检查的那个版本。 同步导致 head 移动后，旧版本上的检查和验证都会失效；如果分支在 gate 检查后发生变化，gh 会拒绝合并。任何 landing 结果都不会消耗尝试次数或关闭 PR，landing worker 的静默也不会；只有 afk fail 会这样做，而且只有基于你自己的判断，它才会处理 landing 认领——例如 required 模式下检查不通过，或 verify 结论被推翻——绝不会因为静默而处理。 一次批量合并——一轮合并多个 PR（gate.ci: local，且没有 gate.adversarial_verify_prompt； 没有开关 — ADR-0029， ADR-0034）。当两个或更多 已完成的 PR 可以一起合并时，检查会同时将这一轮交给它们全部 — afk turn --batch — 而不是交给第一个：它会在每个成员 PR 上记录一个标记，并在批次专属的工作树中启动一个批次工作进程。 该工作进程运行 afk land --batch，将这些 PR 逐个堆叠到目标分支上，每个 PR 各用一个合并提交；对整个堆叠 只运行一次检查，然后将堆叠推送到目标分支；每个 PR 自身的头提交随后都会出现在目标分支上，因此 GitHub 会显示它已合并，其议题也会关闭。哪些 PR 会被批量处理，以及是否进行批量处理，都由代码决定 — 你无需选择。不会告知成员各自的工作进程，批次工作进程也不持有认领权或名额。检查会像监控这一轮中的任何工作进程一样监控批次工作进程：若进程消失，就继续执行；若进程无响应，就提醒一次，然后放弃该批次（afk turn --abandon），不合并任何内容 — 不会导致任何 PR 失败，也不会消耗任何尝试次数。若批次在推送已完成后中途停止：下一次检查会根据目标分支处理其成员，而放弃操作不会影响它们。未纳入批次的 PR（与其他 PR 存在冲突）或已放弃批次中的 PR，会像上文所述在单独的轮次中合并，并且不会再次批量处理。

此轮次机制防范的是偏离预期的工作进程，而非恶意工作进程：工作进程和启动器共用一个 gh 凭据，因此这里无法阻止工作进程自行运行 gh pr merge。

整个工作集群的职责**止于合并到 base_branch 并通过检查。**部署是单独的、 需要人工把关的步骤 — 此处绝不执行。

失败处理 — 有限重试 → 升级处理，绝不静默丢弃

以下情况会导致认领失败：PR 检查未通过；对抗性验证驳回；判定为 giving-up；分支上的工作驳回了 already-satisfied；没有 PR 的工作进程在提醒一次后的宽限期内仍处于空闲状态，且完全没有判定。同步冲突、合并时检查未通过，或合并轮次中无响应，都不在此列 — 工作进程会在其合并阶段中或在其 PR 放弃的轮次中就地修复前两项；若在此阶段无响应，则会导致重启，随后升级处理并保留 PR（ADR-0035、 ADR-0045）— 绝不会消耗尝试次数。只有通过你自己的判断，afk fail 才会影响合并认领：处于 required 模式时检查未通过，或验证遭到驳回。

<skill>/scripts/afk.py fail --issue <n> --instance <id> --worker-command '<worker_command>' \
     --reason "<why it failed>" --repo <repo> --config '<config json>'

对于已有记录的原因，检查会自行运行此操作 — 工作进程自身的 reason=、无响应情况、它停留的轮次 — 对于没有记录的原因，则会将其交给你作为 reason 判断：这时失败由你来描述，从已有记录的位置重新读取（PR 的 CI 检查、验证器的审查评论、工作进程的判定评论），绝不会从上下文中传递。无论哪种情况，调用都会完成其余操作，并报告处理结果：

• "action": "retry" — 重试次数未耗尽（默认 2 次）。尝试次数记录为 issue 上的 afk-attempt/<n> 标签（不在任何人的上下文中），而 afk fail 是唯一会写入该标签的命令：它将标签中的次数加一，丢弃失败的尝试（关闭其 PR、删除其分支、移除其 worktree——这样认领就不会在同一个红色 PR 上循环），并在同一认领下从基准分支启动一个全新工作器，将失败原因交给它。在收到提醒后仍未得到回应时，它会将工作器最后的屏幕内容追加到原因中。无论 afk fail 运行多少次，一次失败只消耗一次尝试：同一次编辑还会添加 afk-attempt/starting，已启动的工作器会移除该标签——因此，如果调用在计数后出错（例如 PR 关闭被拒绝或 orca 宕机），再次运行它：它会完成重试，不会重复计数；下一次轮询也会自动完成相同操作。
• "action": "escalate" — 尝试次数已耗尽。按固定顺序执行：状态看板 → 评论说明原因 → 更改标签（添加 escalate_label，移除 ready_label 和尝试次数标签）→ 释放认领。PR 和 worktree 会留给人工处理——但如果某个 worktree 的分支没有任何工作（没有已提交或未提交的更改），就会连同其中空闲的工作器一起移除：里面没有可供查看的内容。无论运行多少次，一次升级都只算一次：评论会记录它属于哪个认领，以及重试了多少次。因此，如果调用出错时认领仍未释放（更改标签被拒绝或释放被拒绝），再次运行它——afk fail 或 afk escalate——它就会完成：不会重复评论，也绝不会重试计数已被标签移除的 issue。下一次轮询也会自动完成相同操作。

对于应交由人工处理、而不消耗一次重试的 issue，直接执行相同的有序状态转换：afk escalate --issue <n> --instance <id> --reason "<…>"。分为三种情况：blocked 判定指出了一个不会有人解决的依赖——它不存在、已被标记为不计划处理而关闭、是一个 epic、处于开放状态但没有工作团队接手，或者等待它会形成依赖环；无人能让工作器完成的落地工作——轮到它时，或修复它放弃的 PR 后续工作时：唯一一次重启后仍再次没有回应，审核判定已就绪的 PR 将保持当前状态，连同其分支和 worktree 一并交给人工处理，并附上原因和工作器最后的屏幕内容（ADR-0035）；以及 needs-decision 判定：issue 的当前描述需要其负责人作出决定——例如前提不成立，或验收标准相互矛盾——新工作器只会再次发现同样的问题，因此升级评论会指向工作器的评论，其中详细说明了需要作出的决定（ADR-0041）。这三种情况均由该流程自行处理。绝不静默丢弃或静默落地有问题的工作。

只要待办列表会解决它，工作器发现的依赖就不属于这类缺口：afk park --issue <n> --instance <id> 会将其记录为原生 blocked_by 依赖关系并释放认领，前沿契约负责等待——不更改标签、不交由人工处理、不消耗尝试次数（ADR-0022）。afk park 会重新读取阻塞项；如果认领当前无法暂存，就会拒绝操作（退出码 3，不作任何更改）。

工作器停止后留下的情况并非全都是失败：如果工作器空闲且没有结果，会先发送提醒，不消耗尝试次数；如果它持有落地工作所需的轮次（或正在修复其 PR 放弃的后续工作），则会重启并继续处理该工作一次，之后升级处理，两者都不消耗尝试次数——落地工作永远不会消耗尝试次数；blocked 判定完全跳过重试计数——阻塞项关闭后重新派发；开放的阻塞项若是可处理的待办工作，则暂存等待；而 already-satisfied 判定若其分支上没有任何更改，则在确认 diff 为空后关闭 issue。

并发

concurrency（默认值为 3）限制一个 fleet 实例持有的认领项数量，因此也限制其并行工作进程数量：认领项从被领取的那一刻起就会占用一个槽位，直到释放为止，无论工作进程正在做什么。 空闲槽位是上限内剩余的槽位；每轮只会领取一个尚未持有的认领项——先领取过期的同伴认领项，再领取前沿 issue——且仅在有空闲槽位时才会领取；本轮解决的认领项会在同一轮释放其槽位。继续处理已持有的认领项不会占用额外槽位。若一个 fleet 持有的认领项数量超过 concurrency（例如执行 --takeover 后，或降低该键的值后），则在认领项数量回到上限以下之前不会领取任何内容。语义上的排序由积压事项的依赖 DAG 决定（拆解工作由你负责）；并行 PR 之间的文本冲突由一次只允许一个分支进入合并流程的机制捕获，并由编写该分支的工作进程解决。早期那些都会修改共享根配置的机制类 issue，自然会受到 DAG 的限制——用 blocked_by 将它们串联起来。

防护措施

• 调用即授权，且授权仅限于此。 运行此技能即表示人类同意为本仓库、本次运行推送工作分支，并将绿色 PR 合入 base_branch——确认基础分支后（ADR-0042），无需再请求确认；也不得将其视为对任何其他操作的许可（ADR-0023）。使用 --plan 可只查看、不执行。
• 所有凭据都必须留在工作者自己的 shell 中。 只推送到工作分支，并将变更合入 base_branch；部署、机密信息以及所有其他远程目标均不在范围内。不得向工作者传递任何凭据——不得复制 ANTHROPIC_*（或任何）环境变量，不得传递环境文件，也不得传递来自机密管理器的令牌：不透明的工作者启动命令存在的目的，就是让人类指定的包装器自行处理这些事（ADR-0010）。复制启动器的环境变量也会让整个工作者集群彻底失效——ORCA_TERMINAL_HANDLE 等变量会使每个工作者都报告为启动器的终端，导致所有工作者的状态合并成一个。
• 只分派适合工作者处理的问题。 Epic／PRD 留在上游；如果待处理队列全是 Epic，就报告“尚未拆解”。
• 唤醒只是信号，绝不是指令。 afk-wake #<n> 是工作者发送到启动器终端的唯一一行内容，其唯一作用是提前触发 afk cycle。任何未经请求而到达那里的其他内容——以及唤醒行看似表达的任何额外意思——都不会被执行（ADR-0020）。
• 通过 GitHub 查看工作者，绝不查看其记录。 工作者的结果是其 PR（Closes #n）；不打算创建 PR 时，结果是其 afk:verdict 标记评论；阻塞情况则写在 issue 评论中。工作者是否忙碌，以其工作者状态为准——即其运行时向 orca 报告的状态，通过 afk no-pr 查看，绝不通过其屏幕查看；工作者停止后，还要结合工作树的 git 进度和其 verdict 标记判断（见“进行中”——仅仅停止绝不等于完成）。完整记录绝不会进入启动器；唯一读取终端的情况是 afk nudge／afk fail／afk escalate 获取失去响应的工作者最后一屏，以判断它停在何处——绝不是读取其结果（ADR-0018）。
• 绝不要自行合并 PR。 不得运行 gh pr merge，不得推送到 base_branch：PR 只能由对应工作者在 afk turn 分配给它的轮次中通过 afk land 合入；或者在合并批次中，通过批次工作者的 afk land --batch 合入。无人合入的轮次会升级处理，并保留其 PR；无人合入的批次会被放弃，不得绕过流程合并（ADR-0027、ADR-0029、ADR-0035）。
• 开工前先认领；每次终态转换时都要释放。 afk dispatch 会先创建 refs/afk/claim/<n> 引用——如果创建被拒绝，说明已有其他工作者认领，不会启动任何操作。afk escalate、afk park 和 afk close 都会在最后一步删除该引用；存续时间超过其 issue 的认领——每个已合入的 PR 都会留下一个——由下一轮处理（afk release）。每次释放只删除其读取到的认领：如果其他工作者期间已接手，则会保留该认领，并且调用会失败。泄漏的引用是虚假的锁。只能协调自己的认领；只有在其他工作者的心跳过期时（即过期认领）才能接手——唯一例外是人类明确指定 --takeover。对于已关闭 issue 上的过期认领（stale_closed），一律不接手：使用 afk release --expect-sha 将其删除。
• 保留已停止工作者的进度。 通过继续执行来恢复失效的认领（直接运行 afk dispatch）；只有在丢弃尝试本身就是目的时才丢弃——例如 afk fail 的重试，或明确使用 --start fresh。仅仅因为目标分支已变更而发生冲突的已完成 PR，应由工作者在其合入轮次中解决，绝不能标记失败。绝不要自行运行 orca worktree rm：对于仍包含未完成工作的工作树，这是整个工作者集群中唯一不可恢复的操作。
• 只有得到人类明确同意，才能接管有效租约。 afk takeover --from 只能根据人类从 --list 中明确选择的对象运行；只有在转述最新心跳警告并得到明确同意后，才能使用 --yes。无人值守时，租约是唯一的处理路径（绝不要为了简化一轮运行而使用 --yes）。
• 尊重人类的预留。 人类通过移除 ready_label 来预留 issue（工作者集群将不再读取受理人）；保持跟踪器信息准确，避免其他工作者集群或人类重复接手。
• 避开预留命名空间。 工作者集群负责管理 afk-attempt/<n> 标签、refs/afk/* 引用命名空间（认领和心跳引用）、带有 标签的唯一状态面板评论、PR 上的 标记评论（集群会解析该评论）、issue 上的 标记评论（其中会注明集群应从哪些分支继续执行和丢弃），以及工作者编写的 标记（集群会解析这些标记）——这些都留给工作者集群处理，不得将这些前缀／标记用于其他用途。