orchestrate

Orchestrate（开发循环驱动器）

一个编排器会话：预检、选择、端到端推进一个规格、拆除并报告；在规格已关闭且上下文余量充足的节点，可选择继续处理下一个规格。 角色固定。 你（在任何运行环境中执行此技能的 Agent）是驱动者：你负责整理、把关、合并、推送，并负责每一项跟踪器写入。 实现者始终是在你的运行环境原生子 Agent 机制中启动的全新会话，令牌数为零——由哪个运行环境驱动运行，就由哪个运行环境处理各项任务；只有在调用时明确提出请求，才会将其转交给外部运行器（见 The take）。 整理阶段的任务拆分由你自己的运行环境中的全新子 Agent 完成——一个会话编写规格，另一个按规格实现，评审始终由你负责。

此循环的语义随此技能一起提供，位于 references/dev-loop-protocol.md——原地阅读，绝不复制到项目中。 项目约定文件为 docs/agents/dev-loop.md：只记录其声明（端口、脚本、门禁证明、有意偏离）；发生冲突时以项目约定为准。跟踪器机制见 docs/agents/issue-tracker.md。 首次写入前，先阅读协议和项目约定。若没有约定文件，就停止操作，并指向 references/dev-loop-declarations.md 以创建该文件，而不是自行猜测。 跟踪器是此循环唯一的记忆：会话可能在任何时刻终止，下一次会话只能根据跟踪器状态恢复。

调用

不带参数的形式是标准方式：运行会话启动流程，并处理其选定的任务。 规格参数是人为覆盖项，只能从合法选项中选择：拒绝处理被阻塞或已认领的规格；若存在未关闭的 fix-main 工单，其优先级仍高于该参数指定的规格。 一次只处理一个规格，但不保证交付成果——会话可能修复主分支、清理一个独立工单、只进行整理，或在工单边界处中途退出。 已关闭的规格是继续执行的节点：若上下文确有余量，会话可以重新运行选择流程并继续处理下一个规格——每次会话通常处理一个规格；只有余量充足时才例外继续，且绝不启动一个会话可能来不及完成把关的规格。 每次继续执行都必须在报告中声明（见 Session end）。

会话开始

按照约定中的会话启动流程，依次执行：

1. 工作区预检——工作区存在未提交更改时，必须立即停止会话并报告发现的问题；只有能够明确识别的更改才可以暂存、提交或丢弃。 然后执行 git fetch 并变基到 origin/main，检查浏览器工具是否正常，清理由循环创建且已过期的开发服务器（这些服务器使用约定中的门禁和占用的端口）——循环之外的端口属于循环外的工作，不得触碰——并删除过期的任务工作树及其分支（遗留项都来自已结束的会话）。 服务器保持临时状态：仅在门禁需要时启动；此处不启动任何服务器。
2. 恢复清理——任何已分配的未关闭事项都视为来自已结束的会话（循环为单任务模式）。 按照约定中的恢复表处理：in-progress 票据 → 改回 ready-for-agent 并取消分配；in-progress 规格 → 清除并重新梳理（关闭其孤立的子议题，改回原状态并取消分配）；其他任何已分配的议题（总议题、史诗、跟踪议题——既非票据也非规格）→ 清除认领状态（取消分配、移除任何生命周期标签），不重新梳理。
3. 跟踪器预检——在 main 的最新提交上读取约定指定的主要健康信号（部署状态、CI 检查）；若约定声明没有远程信号，则在变基后的提交上本地运行检查命令。 任何检查未通过 → 查找或创建唯一一张未关闭的 fix-main 票据（标题注明失败的检查和 sha，正文附上证据）。 检查全部通过，但存在过期且未关闭的 fix-main → 添加备注并关闭。
4. 按优先级选择：未关闭的 fix-main 票据；否则，最早的未关闭、未阻塞、未分配的 ready-for-agent 票据；否则，第一张未关闭、未阻塞、尚未梳理的 ready-for-agent 规格；否则说明情况并停止。 needs-triage 和 needs-info 事项对循环不可见。

推进规格

• 选中规格 → 梳理规格（见下文），然后推进其新看板。
• 选中票据 → 交付票据（见下文）；若它属于某个规格，则继续推进该规格的看板。
• 在看板的前沿重复交付——最早的未关闭、未阻塞、未分配的票据——一次处理一张票据。
• **票据边界就是退出点。**每到一个边界，都要检查自己的上下文余量；如果可能无法完成门禁，就停止，不要开始新的任务。任务提交仅在本地，会随会话结束而消失。 下一会话需要的任何信息都应作为评论写在相关票据上；跟踪器是唯一的交接界面。 只需再次调用此技能即可恢复。
• 所有子议题均已关闭 → 关闭规格；已关闭的规格是持久的完成标记，可解除依赖规格的阻塞，其关闭评论就是规格报告。 然后进行继续检查：如果仍有充足的上下文余量，可以重新运行选择流程并推进下一个规格；否则，拆除环境并结束。

细化规格

切勿提前细化：只有阻塞规格已关闭，才能细化某个规格；这样，工单才是针对实际落地时的代码库编写，而非针对想象中的代码库。

1. 认领规格：先将 ready-for-agent 改为 in-progress，并指派给自己，然后再做任何其他工作。
2. 启动一个全新的子 Agent，提示它遵循仓库的 to-tickets 技能，只完成起草步骤（收集上下文，探索当前代码库，起草带有阻塞依赖边的纵向 tracer-bullet 切片），并将拆分结果报告给你——to-tickets 的测验步骤就是下面与你的交流，发布步骤则由你负责。 报告中每个工单都应包含：标题、完整正文（包括验收标准）及其阻塞依赖边。
3. 审核拆分结果。to-tickets 的测验由你来完成——像人工审核者一样判断：
   • 粒度——每个切片都能放入一个全新的上下文窗口，并且可以单独演示。
   • 依赖边——只保留真实的门槛，不要出于谨慎而把工作串行化。
   • 覆盖范围——规格中的每项要求都应落实到某个工单中。
   • 真实性——任何“已存在，无需工单”的说法，都要亲自对照代码验证后再接受。 对参考仓库或环境的任何断言（例如“X 已实现此功能，照着做”）也一样：必须在细化时根据实际仓库状态验证，绝不能照搬规格或问题正文中的说法——将过时的说法升级为工单内容，就相当于细化者为其背书，而门禁检查的是差异，不是简述中的前提。 如果这台机器无法访问某个参考资料，就必须将该说法明确标记为未经验证的假设，后续执行者依赖它之前必须先行核实——绝不能当作既定事实。 如果运行环境支持恢复同一个子 Agent，就继续让它迭代；否则，启动一个新的子 Agent，并提供此前的拆分结果及你的异议。
4. 自行发布——所有跟踪器写入都由主执行者负责，按 to-tickets 的发布步骤操作：每个切片创建一个工单，使用其问题模板，并按依赖顺序发布（先发布阻塞项，使依赖边引用真实 ID）；每个工单都应是规格的原生子问题，并在同级工单之间设置原生阻塞依赖边，且标记为 ready-for-agent。 核实发布结果：列出所有子问题，并抽查依赖边。
5. 取消认领规格：移除 in-progress，取消指派——这是“看板已上线”的原子切换。 如果规格已有子问题却仍处于 in-progress，说明看板只发布了一半，绝不能被选取。

交付工单

一个工单 → 在单个会话中闭环、原子化处理：接手 + 门禁检查 + 合入。 从工单合入的分支上的干净工作树开始；接手操作在自己的工作树中运行，因此门禁检查的差异正是接手操作产生的差异。

1. 认领：将 ready-for-agent 改为 in-progress，并在开展任何工作之前将工单分配给自己。
2. 接手：在独立工作树中启动一个全新的接手会话（参见「接手操作」）。每次尝试都是一次接手操作；每次接手操作都会提交，因此工单时间线会完整记录所有尝试。
3. 门禁检查（参见「门禁检查」）。通过 → 第 5 步；未通过 → 第 4 步。
4. 退回：在工单上评论具体缺陷——这就是审核发现问题的可审计记录——然后将发现的问题和修复预期告知同一个接手会话，并保持合同不变。回到第 3 步重新进行门禁检查。 最多进行三次接手操作；如果第三次仍未通过，则升级处理：添加 needs-human 标签，移除 in-progress，取消分配，并保留提交和评论作为记录。 驱动者不得介入代码——应升级处理，而不是接手。
5. 合入并关闭：推送前核实每次接手操作的提交消息——每条都必须包含格式正确、无闭单关键词冲突的普通 #<N> 提及；如果提及缺失、错误或冲突，则修改相应的提交消息（即使提示词中有相关规则，接手操作也经常会漏掉该提及，因此记录所依赖的提及必须由这项检查补上）——然后将接手分支合入目标分支——这需要在两个位置依次操作：如果目标分支有更新，应在接手分支的工作树中对其变基（git 会在该工作树中检出此分支），然后从主工作区快进并推送（在接手操作的工作树中进行快进合并，只会静默显示「Already up to date」并且什么也不做——HEAD 就是接手分支——只有之后推送或交付失败时才会暴露问题）。评论已交付的内容（参见「记录」）并关闭工单——关闭工单后，其依赖工单才会解除阻塞。 仅在通过时推送：未通过的接手操作绝不会推送到远程服务——在大多数配置中，推送到 main 会部署到生产环境。
6. 清理：先停止门禁检查启动的任何开发服务器或浏览器会话，再通过记录的句柄停止接手操作留下的任何后台进程（使用合同中的停止命令，或记录的 pid 所对应的进程组）——按模式匹配并终止进程会漏掉正在重试间隔中休眠的父进程，因此凡是通过模式匹配终止的进程，都必须在静默一段时间后重新检查，确认没有进程再次启动。 移除接手操作的工作树和分支前，确认没有进程仍在使用该工作树路径（lsof -a -d '^mem' +D <worktree>）——残留进程会在已删除的路径上继续运行，消耗配额并留下碎片，导致下次接手操作被归咎。 在 pnpm 项目中，排除 ^mem 很重要：node_modules 与存储目录中的文件采用硬链接，因此另一个检出目录中的构建会映射到相同的原生模块文件，而普通的 lsof +D 会将其报告为工作树路径下的文件；只有 cwd、txt 和打开的文件描述符才能标记占用者。 agent-browser close 会关闭浏览器会话，但不会停止守护进程；如果守护进程首次启动时的工作目录位于工作树中，它就会将该路径作为 cwd，因此移除工作树前必须通过 pid 停止该守护进程。 无论是合入、升级处理，还是提前停止接手操作（重新确定范围、打断），都必须执行清理；跟踪器评论才是记录，而不是残留的工作树。

接手操作

每次接手操作都是全新会话，从 token-zero 开始，在从目标分支切出的接手分支上使用自己的工作树——绝不能使用共享工作副本，以免并发会话将彼此未提交的工作一并提交，或推送彼此未经门禁检查的提交。 如果你的 harness 提供原生工作树隔离功能，则使用该功能创建工作树；否则使用普通的 git worktree add，并在接手操作开始前，按照合同中的工作树准备说明完成初始化（未跟踪的环境文件、安装依赖）。 接手操作通过你的 harness 的原生子 Agent 机制启动——只有在调用时明确提出请求，才会将其交由外部运行器处理：

• 原生子 Agent - 使用你的 harness 原生子 Agent 机制启动 take。 如果 harness 支持恢复，Bounce 会在同一 take 会话中继续执行；这样比重新启动更省成本，而且 take 的上下文会保留。如果不支持，则启动新的子 Agent，并在其提示词中逐字包含原始契约、先前 take 的报告和 Bounce 发现的问题。
• 外部运行器（仅限明确请求）- 调用中会指定此技能 runners/ 文件夹中的运行器文件；按照文件说明进行启动、恢复和 take 计量。 runners/codex.md 会将 take 作为 codex exec 会话运行。

无论采用哪种方式，Bounce 续接都计入三次 take 的预算。 如果 harness 支持，较长的 take 会在后台运行；安静运行不足 30 分钟的任务应让其继续执行。 你的上下文只保留 take 的最终报告——绝不要将 take 的转录、差异或文件转储拉入驱动会话；门禁会从 git 读取差异，而不是从报告读取。

提示词契约。 take 从零上下文开始——没有规范讨论串、驱动对话，也没有 harness 注入内容之外的内部规则。 take 的质量取决于规范的质量。 每个 take 提示词都包含：

• 目标：问题编号、标题和完整正文（逐字保留，包括验收标准），以及父级规范的引用；将规范中与此工单实现内容相关的原文内联
• 流程指引：如果项目提供了 implement 技能（.agents/skills/implement/），请遵循该技能
• 依据指引：仓库的领域术语表（CONTEXT.md）、仓库提供的任何生成式技术栈指南（优先级高于训练所得知识），以及问题涉及 UI 时的设计方向文档
• 从问题中提取的约束和非目标
• 预期证明：项目规定的确切检查命令，以及根据契约「Gate proofs」部分，此 diff 会触发的每项部署类证明——take 也会运行这些检查，因此失败成本很低
• 运行时规则：如果 take 需要运行中的应用，则通过 dev-server 脚本在自己的工作树中启动专属临时服务，并使用契约指定的端口；退出时停止服务。启动的任何其他长时间运行进程都必须可通过句柄停止——通过契约声明的生命周期脚本启动，或在独立进程组中启动并记录 PID；退出时停止，或在报告中注明。take 绝不留下没有句柄的脱离进程；破坏性 shell 命令（rm、覆盖现有路径的 mv、git clean）必须指定工作树或临时目录中的绝对路径（例如 rm -rf "$WORKTREE/.probe"，绝不能用 cd "$WORKTREE" && rm -f .probe/*）：cd 后的相对目标会相对于会话的主检出目录解析，harness 会要求确认并停止无人值守的运行
• 验证状态：如果 diff 改变了排序、筛选或布局，take 也要操作非默认状态——其他排序键、其他筛选状态、收起和展开的 chrome，以及设计方向文档指定的每种视口；报告须列出实际验证的状态。只覆盖变更针对的状态，不算证明
• 部署规则：部署侧状态（开发或预览部署上的环境变量、远程配置）由驱动程序负责；如果 take 需要更改此类状态，须在报告中说明需求并仅在本地操作。若契约明确授权 take 访问部署环境变量，则须履行两项义务：按原始值恢复（从 dotenv 文件复制的值包含外围引号时，要将引号作为字面字符保留——需去掉它们），并在报告中列出所有更改过的变量
• 审查规则：implement 技能以代码审查步骤结束，该步骤会按照其自身说明启动并行审查子 Agent——take 不得照此执行：它须在自身上下文中依次运行两项审查，无需并行。更一般地说，take 绝不启动子 Agent，也绝不阻塞等待 Agent 消息或通知——子 Agent 的回复不保证能送达 take，而且并非所有执行器都能启动它们；如果等待的结果尚未到达，则根据磁盘上的内容继续，并在报告中注明
• 提交规则：在本地提交，并以普通提及的形式引用 #<N>；该提及不能紧跟任何 GitHub 关闭关键词（fix、fixes、fixed、close、closes、closed、resolve、resolves、resolved），即使是在普通描述中也不行，因为 GitHub 会在 gate 运行前自动关闭问题；必要时请改写句子——并且绝不推送
• 输出格式：仅提供简短报告——已交付内容、证明是否通过（是/否）、修改的文件、提交 SHA、遇到的阻碍

把关

审查绝不委派，也绝不跳过。

先看差异。 运行 git status -sb，然后阅读完整差异，并从四个方面像审查贡献者 PR 一样评估：

• 规范契合度 - 是否满足每项验收标准，是否没有交付超出问题范围的内容。
• 仓库规范 - 词汇表中的用词、既有模式（函数构建器、测试接缝、固定样例）、生成代码栈指南；新增代码应与周边代码风格一致。
• 设计方向 - 将 UI 差异与仓库现行设计文档对照；发现偏离时应指出，而不是凭个人喜好重新设计。
• 简洁性 - 差异的规模是否合理：优先复用而非重新发明，不做无谓抽象，测试应在稳定的接缝上验证行为，而非实现细节。

再核实事实。 报告只是陈述；事实是你在该次执行的工作树中自行重新运行得到的结果——依赖已安装，差异已检出。 亲自运行项目的检查命令；若问题涉及运行时表面，也要端到端验证应用（如果仓库提供验证技能，则使用该技能）——使用该工作树启动自己的临时开发服务器（使用契约规定的把关端口），不要触碰非循环使用的端口。 报告若提到部署环境变量变更，也要按同样方式核实：亲自读取部署环境当前值，并与预期值对照——“已恢复并验证”只是说法；从 dotenv 文件恢复的值通常会带有多余的字面引号。

部署形态的验证。 本地检查链在结构上无法发现仅部署环境才会出现的问题；把关流程会运行生产环境所运行的内容。 契约的 把关验证 部分将差异类型对应到仓库的验证命令（架构变更、破坏性数据变更、仅生产构建时出现的错误）；差异触发的每项验证都必须运行。

参考信号。 同一部分会按表面列出仓库的审查技能和分析器（UI 指南、技术栈分析器、文案审查）；差异涉及的项目都要运行，并将其发现作为规范性和简洁性审查的参考输入，绝不能将其当作通过或失败的把关步骤。

记录

追踪器中的评论是后续会话和跨项目巡查所读取的记录。

每张工单 - 已交付的评论应包含：

• 交付内容和提交 SHA
• 使用的执行轮次；每次回退都要引用把关发现的缺陷
• 驱动会话 ID，以及每次执行轮次的会话或子 Agent ID

会话结束

无论会话如何结束，都必须执行以下事项：

• 清理 - 停止由循环启动的开发服务器和浏览器会话。
• 报告 - 每个受驱动的规范都要发布一条规范级评论：规范关闭时发布关闭评论，否则发布状态评论。 若会话未涉及任何规范，则在最后一张已交付工单上发布同样的报告。 报告应包含：已交付的工单及其执行轮次和回退情况、升级事项、提交、过程中遇到的环境或工具障碍、提交的观察事项，以及会话 ID（驱动会话和各执行轮次）——必须原样写出驱动会话 ID，不能写成“本会话”；若会话驱动了多个规范，还要注明该规范在会话中的序号（例如“本会话的第二个规范，接在 #63 之后”），以便事后按规范边界拆分记录。 然后简短写一段反思，每项一两句：本次会话中最难的判断及被否决的替代方案；最没把握之处及其依据的假设；如果范围更广，会有哪些不同做法。 最后列出循环的阻碍事项：未关闭的 needs-human 条目，以及是否仍有已就绪的规范。
• 观察事项 - 任何可采取行动的事项（工具缺陷、把关盲点、技能缺口）都应单独创建工单并标记为 needs-triage；叙述性背景写入报告的“观察事项”部分。