Poteto Mode Orchestrate 剧本解析用单一协调者聊天驱动多日、多 PR、上百子代理的程序级编排【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins导读Orchestrate是 pstack 插件 Poteto Mode 中面向「程序Program」级别的编排剧本回答一个核心问题当一个项目需要多日持续作战、几十个堆叠 PR、数十乃至上百个子代理而人类每天只检查两次时如何用一个常驻的协调者聊天把整条流水线跑完并安全收尾。读完本文你将掌握协调者/子协调者/工作代理的角色划分、基于纯文本文件的 Store 布局、bun scripts/orch/orch.ts简称orch的完整命令用法、Brief 模板与缩放规则、七个执行步骤、队列排空纪律、Stack 安全与验证台账以及故障恢复与升级策略。本文以 orchestrate.md 为骨架结合 orch.ts、store.ts 与 orch.test.ts 的源码实现逐层展开。何时路由到 Orchestrate程序与单任务的边界剧本开篇就划清了边界You own the program, never the code.当一个完整项目被交给一个常驻协调者聊天时——多日周期、大量堆叠 PR、数十到数百个子代理、人类每天只检查两次而非每五分钟一次——就应路由到这里。三种形态的区分是Autonomous run一个任务被驱动到某个判定谓词predicate即为完成参见 autonomous-run.md。figure-it-out一次野心勃勃的运行需要定制工作流时使用。Orchestrate当工作超越任何单个代理的寿命时路由到这里。一个代理能在本次会话预算内完成的工作不叫程序不应走 Orchestrate。在 SKILL.md 中这个边界被进一步强化figure-it-out 设计一次定制运行orchestrate 运行整个程序standing project-scale program多日、多个堆叠 PR、一个协调者下的代理群一律路由 Orchestrate见 SKILL.md。剧本同时强调仪式感必须随程序规模伸缩在廉价且近乎同构的单元上要按各节的指示把仪式折叠掉而不是机械套用全套流程。三条铁律完成是队列事件不是中断Completions are queue events, not interrupts。每一次 spawn 和每一次 resume 都必须逐字携带常驻指令standing orders verbatim。Brief 就是产品。含糊的 brief 会安静地失败因为工作代理无法向你提问。这三条规则贯穿全文是后面所有纪律的推导起点。角色与布局协调者、子协调者、工作代理/验证代理协调者Coordinator即本聊天协调者是本地Local的负责框定程序Frame、撰写 brief、排空收件箱drain the inbox、拥有对人类的汇报、做判断决策。它从不编写或编辑代码。冲突合并、restack、代码变更永远是任务只有机械落地一个已验证单元对工作代理提交做 fast-forward 或干净的 cherry-pick然后 push属于簿记协调者可以在本地 git 成本低的仓库里自己做。关键纪律整个循环端到端都是 agentic 的——代理只能通过 Task 工具被 spawn、resume 和排空状态读写只在 drain 点通过scripts/orch/orch.ts进行一条命令进、一行输出出CLI 从不 spawn、等待或唤醒任何东西。子协调者Sub-coordinator子协调者总是本地、持久durable、每个 track 一个仅当程序超出单个协调者一次 drain 能管理的规模时才引入。协调者自己就能 drain 的 track 不需要中间层。原因有二每嵌套一层都要重新支付一次完整的定位前导orientation preamble阻塞式子协调者会在父级空闲时隐藏它的子代理。子协调者职责拥有其 track 的单元与看板、撰写其工作代理的 brief、spawn 自己的工作代理与验证代理嵌套深度到 3 层嵌套 spawn 拥有完整 Task schema包括environment、在 wave 边界汇总聚合。它从不转发原始的子报告在途子代理数量上限约为十个作为滚动窗口绝不使用阻塞式批次——因为阻塞式批次每个批次都要付出最慢子代理的代价。工作代理 / 验证代理Worker / Verifier默认environment: cloud除非任务确实需要本机cursor-team-kit的control-ui或control-cli运行时验证、读取agent-transcripts/下的本地转录、模拟器与本地 IDE 状态、仅存在于本机的认证。云端代理读不到本地 store所以它们的 brief 要么内联所需内容要么指向仓库路径。偏好更少但更宽的工作代理。每个 worktree 或分支只有一个写入者对应 principle-separate-before-serializing-shared-state 原则。一个单元的验证代理必须与工作代理使用不同的模型族以保证独立性。深度与 track 划分深度保持在三层协调者、track、工作代理。track 分解按项目定制build、landing、verification 是常见切法但不是必须的形状。剧本明确记录硬编码的 swarm 树曾尝试过因过于僵化而被搁置。Store 布局纯文本文件即事实在系统提示中的当前代理 store 路径下创建orchestrate/project-slug/。每个文件恰好一个写入者拥有者发布事实读者在读取时聚合。簿记统一用bun scripts/orch/orch.ts下文写作orch但其规范化的纯 TSV/JSON 文件不依赖 CLI 也可直接阅读。文件作用维护规则preferences.md常驻指令登记册编号行每行一条约束模型策略、栈形状与数量、验证门槛、禁止路径、升级策略。每次 spawn 和每次 resume 逐字粘贴。指令会跨 resume 衰减每丢一条都要耗掉人类一轮。当你发现自己重复某条指令时先追加该行再行动对应 principle-encode-lessons-in-structureoverview.md持久 PR 与 issue 数据库只追加绝不按事件整篇重写units.tsv单元表一行一个单元id、track、state、branch、PR、head SHA、brief 路径。原地更新行frontier.json计算出的合并前沿按 Stack safety 节维护ledger.tsv验证台账按 Verification 节维护inbox/完成指针存放完成通知gates.md停放人类门禁问题、选项、无答复时的默认值decisions.tsv决策轨迹通过 show-me-your-work 技能维护status.md状态页每次 drain 时从units.tsv和ledger.tsv派生绝不手工维护从表重新生成而不是把事件叙述进去源码印证纯文本 store 的实现细节store.ts 用约 1600 行 TypeScript 实现了这套纯文本 store几个值得注意的实现事实TSV 头严格校验units.tsv头为id\ttrack\tstate\tbranch\tpr\tsha\tbrief7 列ledger.tsv头为pr\tsha\tverdict\tevidence\tverifier\tts6 列读写都做宽度与头校验store.ts格式损坏会直接报错而非静默吞掉。原子写入所有写入都走临时文件 rename避免半写状态store.ts。CSV 公式注入防护cleanCell会把以 - 开头的单元格前缀防止把表格公式当数据处理store.ts。PID 文件锁.orch.lock记录持有者 pid写入前必须拿到锁--force可夺锁持有者 pid 已死process.kill(pid, 0)返回 ESRCH则自动替换对应剧本死会话的 store 锁会在下次写入时自动清除、orch 会替换持有者 pid 已消失的锁store.ts。幂等初始化orch init只writeIfMissing重复初始化不会破坏已有数据——测试 orch.test.ts 验证了两次 init 后文件内容一致。测试中还覆盖了锁的两种行为写入者在锁被他人持有时被阻塞并报store lock held by pid N只有--force才能夺锁以及脏锁pid 已死自动替换orch.test.ts。Brief唯一的产品你对代理的提示是你唯一的产品一份草率的 brief 会在整棵树上放大成次品。每次 spawn 都携带完整 brief一个你填不出来的字段就是一个你还没界定清楚的单元。完整模板GOAL 一句话说明产出能让没有聊天权限的陌生人直接执行 SCOPE 本单元可写的路径不可写的路径其独占的 worktree 或分支 CONTEXT 指向文件和 PR 的指针当本单元依赖上游报告时完整粘贴上游报告 因为工作代理看不到兄弟代理 ACCEPTANCE 可检查的标准一行一条 VERIFY 精确命令或 control 技能路径外加已知陷阱 TIMEBOX 运行时长的大致上限到期返回部分发现并停止而不是继续跑 FORBIDDEN 不 gt、不 rebase、不 force-push、不修 scope 之外的东西再加单元级禁令 REPORT 状态、分支、head SHA、PR、判定、实际跑了什么、偏差、建议的后续 STANDING preferences.md 逐字粘贴按单元缩放 brief一行命令的单元模板折叠成一段但仍须点名 goal、scope、verify 命令和报告形状。一个两行编辑外包 4KB 脚手架的 brief其书写与遵守成本比编辑本身还高。本地 spawn可以直接按 store 路径引用常驻指令文件逐字粘贴是给云端 spawn 和每次 resume 的。子协调者 brief 与依赖中继子协调者 brief 额外包含其 track 边界与单元清单、spawn 预算云端默认 本地例外清单、drain 协议、rollup 格式每个子代理名字、状态、PR、head SHA、判定、一行说明外加 track 状态与 frontier 增量。依赖是上下文中继不只是排序。未声明的上游上下文会让工作代理靠猜。缺失字段是拒绝 spawn 的条件。每个 wave 每子协调者抽查一个工作代理 brief且抽查与该 wave 并发进行绝不作为其前置门禁。失败的 brief 会停掉该 track 并修正子协调者的指令而不只是修正该工作代理——因为 brief 质量在运行后期会衰减。绝不 resume-chain 一个 brief用整合后的 scope 重新 spawn。七个执行步骤1. Frame框定把完成谓词写成可数的形式例如全部 126 个单元已合并每个都在台账中记为unit-test-verified或更优。量化范围单元数、大致工作量、预期栈数量、墙上时钟预算。如果单个代理能在该预算内完成在此停下改走 Autonomous run。Collapsing 的含义是直接在本会话内干活需要时用普通工作代理、验证内联、边做边落地不启用下述 store、登记册或 pilot 机制。对照预算安排落地节奏大约到 70% 预算时停止 spawn落地所有已验证的东西。按项目命名 track。有争议的分解或单向门先在 arena 技能pstack/skills/arena/SKILL.md中过一遍再开始 pilot。framing 只呈现一次可逆的准备不等待。2. Install the runtime安装运行时运行orch init。通过 show-me-your-work 技能pstack/skills/show-me-your-work/SKILL.md打开决策轨迹在任何 spawn 之前写好常驻指令并用orch frontier set --repo repo-dir从既有 PR 播种frontier.json。3. Pilot试点把一个单元推过完整路径brief、工作代理、验证、栈条目、台账行、合并。Pilot 的存在目的是在代价是一个代理而非五十个代理时证伪 brief 模板、验证配方和单元规模。从 pilot 证据修正契约后再开始任何扇出。Pilot 规模随单元缩放对近乎同构的廉价单元第一个单元本身就是 pilot作为普通单元运行、verify 命令内联落地即开始扇出。专用 pilot 管线独立验证代理、审计门禁只用于昂贵或新颖的单元形态克隆单元没必要——串行 pilot 没有可证伪的东西。4. Scale扩容按在途上限 spawn 一个滚动窗口的工作代理子代理完成即补位。阻塞式批次要付出每个批次最慢子代理的代价。只有超过 Roles 节的一次-drain 阈值才 spawn track 子协调者。每次 drain 后重算就绪工作。把上游报告中继进下游 brief。兄弟间通信只向上。抽样 brief 审计与它所抽样的 wave 并行运行失败时停的是下一次补位而不是当前这一波。5. Drain排空在每个 drain 点执行下文队列与 drain 纪律。6. Land落地落地是连续的绝不是收尾阶段。集成从第一个已验证单元开始与剩余 wave 并行推进。重型仓库上 stacker 从 wave 一开始就是常驻角色单元一验证就集成本地 git 便宜的仓库协调者按 Roles 节自己落地已验证单元。保持前沿绿色先于上层栈工作。Stack safety 主导。frontier.json只在合并或报告了新 head SHA 时才推进。7. Close收尾排空最终收件箱把每个 spawn 过的代理调和成终止行done、abandoned、zombie-reconciled在真实工件上确认谓词确认每个已落地 PR 的当前 head SHA 都有判定按 show-me-your-work 审计轨迹含跨模型评审把反复出现的修正编码进preferences.md或 brief 模板。保留 store 原样——它就是事后复盘材料。队列与 Drain 纪律收到完成通知时运行orch inbox push agent unit status [--report PATH]然后回到你正在做的事。绝不内联深度评审需要评审的完成会变成验证单元。绝不在 drain 中评审 diff。四个时点批量 drain关键小节结束、track rollup、前沿 watcher 唤醒通过 loop 技能布防配长心跳兜底、人类报告之前。每批以orch inbox drain开始。drain 期间到达的通知等下一批。优先完成的关键小节撰写 brief、栈操作、冲突决策、写门禁、更新台账或前沿。每次 drain 把每个指针分类为landed、needs-verify、failed、zombie、noise通过orch unit add、orch unit set、orch ledger record写入结果行运行orch status然后在一条消息里 spawn 下一波。在 track rollup 时对每个 spawn 过的子代理对账已到、已重 spawn、或其 scope 被显式吸收。默默重做缺失子代理的工作会同时掩盖浪费的开支和该结果本要填补的覆盖缺口。一次 drain 回合以orch status的三行输出结束按状态统计的计数、什么变了、有哪些门禁开着。细节在status.md中。源码印证orch CLI 的完整命令面orch.ts 用 commander 实现了全部簿记命令。全局选项--store dir或环境变量ORCH_STORE、--json输出完整行、--force夺锁。完整命令树命令用途关键参数orch init初始化 store—orch unit add id新增单元--track track必填、--brief path新单元状态为pendingorch unit set id更新单元--state state必填、--branch、--pr、--shaorch unit get/list/counts查询单元list 支持--state、--track过滤orch ledger record pr sha verdict记录验证判定--evidence path必填、--verifier nameorch ledger check pr sha查询判定未记录输出NOT-VERIFIED退出码 2orch ledger summary判定统计—orch inbox push agent unit status推入完成指针--report pathorch inbox drain/peek/count排空/窥视/计数drain 支持--peek只读不排空orch gate park/list/resolve管理门禁park 需--question、--options、--defaultresolve 需--answerorch frontier set/show计算/展示前沿set 需--repo dir或ORCH_REPO可选--prs n,...钉定 PR 顺序orch status渲染status.md并打印摘要—orch standing show/add line管理常驻指令自动编号追加退出码约定测试 orch.test.ts 验证成功为 0用户/用法错误为 1not-found 为 2且--json下仍向 stdout 输出结构化 JSON如{pr:184530,sha:abc123,verdict:NOT-VERIFIED}。orch status的三行摘要来自statusLinesorch.tscounts:单元数与状态分布、台账判定分布、changed:与上次渲染的差异如units done 0-3; ledger unit-test-verified 1-4、gates open:门禁数量与 ID。status.md内含!-- orch-summary ... --注释用于差异检测store.ts。Stack 安全前沿是计算对象绝不是叙述。每次合并和栈突变后都要从gt重新计算frontier.json——因为 GitHub base ref 会在 restack 中途漂移而 gt 的追踪才是权威有序 PR 列表、分支名、head SHA、代数generation number、最低未合并 PR。在 gt 认识该栈的地方解析它通常是 stacker 的 clone。gt 元数据从未见过提交的 checkout 会报告无 PR命令直接报错而不是猜。每个栈恰好一个 stacker 可运行gt在其栈内串行。持有者记录在常驻指令中。Restack 在云端运行——此规模下本地 restack 会把笔记本拖垮。工作代理绝不 rebase、绝不运行gt。Babysitter 按 babysit.md 行事每个栈一个scope 限定在一个不可变前沿代内它们把冲突报告给 stacker而不是自己 restack。PR 关闭与重定向只经 stacker。关闭一个基 PR 会让其上方整条链成为孤儿。合并与栈手术是和其它单元一样带 brief 的单元。一个 retro watcher跟踪已合并 PR 的 revert、合并后 CI 破裂和孤儿后续。源码印证前沿计算orch frontier set --repo的实现先gt log short --stack --reverse拿到有序分支再对每个分支gt info解析 PR 号与状态MERGED/CLOSED/OPEN其中OPEN匹配一长串 Graphite 状态词如Needs approvals、Merge conflicts、Ready to merge等再用git rev-parse取每个分支 SHA代数 1lowestUnmerged取第一个OPEN的 PRstore.ts。可选的--prs n,...钉定会校验实际顺序与预期完全一致漂移时报frontier pin mismatch: missing from gt ...; extra in gt ...; order differs ...store.ts。测试用 fakegt脚本验证了 merged/closed/open 三种状态、钉定校验与不可解析输出的显式报错orch.test.ts。验证体系台账是唯一答案验证规模随单元缩放VERIFY 是单个廉价命令时工作代理运行并报告输出协调者抽查凭证即可。专用验证代理模型族与工作代理不同只用于验证昂贵、依赖判断或高爆炸半径的单元。一个只会重跑一条命令的验证代理是仪式不是验证。台账命令orch ledger record写行orch ledger check查当前 PR 与 head SHA。ledger.tsv每行一个判定键为PR 号 head SHA五档判定判定含义live-ui-verified真实 UI 验证通过unit-test-verified单元测试验证通过type-check-only仅类型检查verifier-blocked验证器被阻塞不是通过verifier-failed验证失败关键规则CI 绿是判定的输入不是判定本身。行为类工作必须好于type-check-only。verifier-blocked不是通过环境恢复后重新 spawn。verifier-failed产生一个修复单元而不是重新验证。工作代理可自报但验证代理在同一键上覆盖之。新 head SHA 使旧行失效restack 后必须重新验证。台账回答这个是否被验证过不靠记忆也不靠转录。一个单元在落地那一刻输出被外部化之前都不算完成绝不批量拖到运行结束工作代理 push 分支、验证代理写台账行、凭证落进 store。只存在于某台 VM 上、而那台 VM 死了的工作等于从未做过。源码印证台账的键与覆盖语义ledger.record按pr sha查找现有行找到则原地替换覆盖否则追加ts自动写入 ISO 时间戳store.ts。parseVerdict在 CLI 层把非法判定直接拒绝orch.ts。测试验证了先record unit-test-verified再record live-ui-verified后 summary 只剩后者即同一键被覆盖非法判定looks-good直接抛错orch.test.ts。存活性与失败处理绝不 resume 一个代理去看看它。Resume 会重启空闲代理。用只读方式探测台账、units.tsv、gh、已 push 的分支、Cursor 仪表盘里云端代理的状态。转录的 mtime 不是存活证据。静默死亡得到收件箱里一条合成的复盘行单元、失败模式、最后证据、选项。证据一到就重规划。绝不等待完全静止。按模式重试失败模式处理命中上限或 OOM缩小 scope 重新 spawn网络断连原样重试工具错误换不同模型重试未知重试一次两次重试后放弃该单元并绕行重规划。迟归数小时的僵尸在接受任何东西之前先对照当前前沿与台账调和。通过全新单元抢救独有发现绝不盲合并。当继续 spawn 会产生树级垃圾上游输出差、验收坏了、基础设施死了时在常驻指令顶部写一行停止线让在途工作完成修好原因再清除该行。用约束子代理的同样方式约束你自己的基础设施重试。连续几次工具中止后停止重试把终止交接写入持久状态做了什么、存在哪里、恢复用的确切命令结束运行。Cursor 重启之后本地代理已死云端工作没死。重读常驻指令与units.tsv重算前沿按 PR 与分支而非代理 ID 重新挂接云端工作从存储的 brief 加当前状态为每个 track 重 spawn 一个子协调者drain继续。死会话的 store 锁在下一次写入时自行清除orch会替换持有者 pid 已消失的锁源码见上文 PID 锁实现与测试 orch.test.ts。升级策略什么该打扰人类到达人类批量汇入状态页而不是逐条不可逆动作对共享分支 force-push、部署、删除、关闭别人的 PR、没有实验能定案的产品或偏好判断、与观察到的现实相矛盾的常驻指令、重规划后仍然存活的程序级死胡同。先把它作为gates.md条目停放再绕行其继续工作。绝不打扰人类前沿微调、restack 机制、重试、CI flake 分诊、评审线程分诊、格式修复、brief 已禁止的 scope拒绝并继续、以及我该继续吗。拿不准就行动并记录。运行中发现的问题只修阻挡前沿的部分其余一律停进 follow-ups——在这个扇出规模下一次小的 scope 泄漏会倍增成没人要的 PR。Reply 契约从表里取数不靠叙述在检查点与收尾时回复谓词及对照units.tsv与ledger.tsv的计数、各 track 及其落地内容、前沿PR 列表加 SHA、判定摘要、放弃了什么及原因、等待人类的门禁唯一允许的请求、store 路径、轨迹路径。数字来自表不是叙述。包含 PR 链接。这条契约与 drain 纪律呼应一次 drain 回合的三行摘要、收尾时的完整报告全部以表为事实源保证协调者聊天在长周期运行中始终能向人类给出可核验、可续接的状态快照。小结Orchestrate 剧本把程序级多代理并行从口号变成了可执行的纪律角色分层协调者/子协调者/工作代理、纯文本 store每文件一写入者、brief 模板与缩放、七步执行、队列 drain、Stack 安全、验证台账、失败恢复与升级边界。其背后的 orch.ts 与 store.ts 以约 1600 行实现和完整测试orch.test.ts把这些纪律落成了可运行、可审计、可恢复的工具——让人类每天检查两次的长周期程序有一个不依赖任何单次会话寿命的持久骨架。【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Poteto Mode Orchestrate 剧本解析：用单一协调者聊天驱动多日、多 PR、上百子代理的程序级编排
Poteto Mode Orchestrate 剧本解析用单一协调者聊天驱动多日、多 PR、上百子代理的程序级编排【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins导读Orchestrate是 pstack 插件 Poteto Mode 中面向「程序Program」级别的编排剧本回答一个核心问题当一个项目需要多日持续作战、几十个堆叠 PR、数十乃至上百个子代理而人类每天只检查两次时如何用一个常驻的协调者聊天把整条流水线跑完并安全收尾。读完本文你将掌握协调者/子协调者/工作代理的角色划分、基于纯文本文件的 Store 布局、bun scripts/orch/orch.ts简称orch的完整命令用法、Brief 模板与缩放规则、七个执行步骤、队列排空纪律、Stack 安全与验证台账以及故障恢复与升级策略。本文以 orchestrate.md 为骨架结合 orch.ts、store.ts 与 orch.test.ts 的源码实现逐层展开。何时路由到 Orchestrate程序与单任务的边界剧本开篇就划清了边界You own the program, never the code.当一个完整项目被交给一个常驻协调者聊天时——多日周期、大量堆叠 PR、数十到数百个子代理、人类每天只检查两次而非每五分钟一次——就应路由到这里。三种形态的区分是Autonomous run一个任务被驱动到某个判定谓词predicate即为完成参见 autonomous-run.md。figure-it-out一次野心勃勃的运行需要定制工作流时使用。Orchestrate当工作超越任何单个代理的寿命时路由到这里。一个代理能在本次会话预算内完成的工作不叫程序不应走 Orchestrate。在 SKILL.md 中这个边界被进一步强化figure-it-out 设计一次定制运行orchestrate 运行整个程序standing project-scale program多日、多个堆叠 PR、一个协调者下的代理群一律路由 Orchestrate见 SKILL.md。剧本同时强调仪式感必须随程序规模伸缩在廉价且近乎同构的单元上要按各节的指示把仪式折叠掉而不是机械套用全套流程。三条铁律完成是队列事件不是中断Completions are queue events, not interrupts。每一次 spawn 和每一次 resume 都必须逐字携带常驻指令standing orders verbatim。Brief 就是产品。含糊的 brief 会安静地失败因为工作代理无法向你提问。这三条规则贯穿全文是后面所有纪律的推导起点。角色与布局协调者、子协调者、工作代理/验证代理协调者Coordinator即本聊天协调者是本地Local的负责框定程序Frame、撰写 brief、排空收件箱drain the inbox、拥有对人类的汇报、做判断决策。它从不编写或编辑代码。冲突合并、restack、代码变更永远是任务只有机械落地一个已验证单元对工作代理提交做 fast-forward 或干净的 cherry-pick然后 push属于簿记协调者可以在本地 git 成本低的仓库里自己做。关键纪律整个循环端到端都是 agentic 的——代理只能通过 Task 工具被 spawn、resume 和排空状态读写只在 drain 点通过scripts/orch/orch.ts进行一条命令进、一行输出出CLI 从不 spawn、等待或唤醒任何东西。子协调者Sub-coordinator子协调者总是本地、持久durable、每个 track 一个仅当程序超出单个协调者一次 drain 能管理的规模时才引入。协调者自己就能 drain 的 track 不需要中间层。原因有二每嵌套一层都要重新支付一次完整的定位前导orientation preamble阻塞式子协调者会在父级空闲时隐藏它的子代理。子协调者职责拥有其 track 的单元与看板、撰写其工作代理的 brief、spawn 自己的工作代理与验证代理嵌套深度到 3 层嵌套 spawn 拥有完整 Task schema包括environment、在 wave 边界汇总聚合。它从不转发原始的子报告在途子代理数量上限约为十个作为滚动窗口绝不使用阻塞式批次——因为阻塞式批次每个批次都要付出最慢子代理的代价。工作代理 / 验证代理Worker / Verifier默认environment: cloud除非任务确实需要本机cursor-team-kit的control-ui或control-cli运行时验证、读取agent-transcripts/下的本地转录、模拟器与本地 IDE 状态、仅存在于本机的认证。云端代理读不到本地 store所以它们的 brief 要么内联所需内容要么指向仓库路径。偏好更少但更宽的工作代理。每个 worktree 或分支只有一个写入者对应 principle-separate-before-serializing-shared-state 原则。一个单元的验证代理必须与工作代理使用不同的模型族以保证独立性。深度与 track 划分深度保持在三层协调者、track、工作代理。track 分解按项目定制build、landing、verification 是常见切法但不是必须的形状。剧本明确记录硬编码的 swarm 树曾尝试过因过于僵化而被搁置。Store 布局纯文本文件即事实在系统提示中的当前代理 store 路径下创建orchestrate/project-slug/。每个文件恰好一个写入者拥有者发布事实读者在读取时聚合。簿记统一用bun scripts/orch/orch.ts下文写作orch但其规范化的纯 TSV/JSON 文件不依赖 CLI 也可直接阅读。文件作用维护规则preferences.md常驻指令登记册编号行每行一条约束模型策略、栈形状与数量、验证门槛、禁止路径、升级策略。每次 spawn 和每次 resume 逐字粘贴。指令会跨 resume 衰减每丢一条都要耗掉人类一轮。当你发现自己重复某条指令时先追加该行再行动对应 principle-encode-lessons-in-structureoverview.md持久 PR 与 issue 数据库只追加绝不按事件整篇重写units.tsv单元表一行一个单元id、track、state、branch、PR、head SHA、brief 路径。原地更新行frontier.json计算出的合并前沿按 Stack safety 节维护ledger.tsv验证台账按 Verification 节维护inbox/完成指针存放完成通知gates.md停放人类门禁问题、选项、无答复时的默认值decisions.tsv决策轨迹通过 show-me-your-work 技能维护status.md状态页每次 drain 时从units.tsv和ledger.tsv派生绝不手工维护从表重新生成而不是把事件叙述进去源码印证纯文本 store 的实现细节store.ts 用约 1600 行 TypeScript 实现了这套纯文本 store几个值得注意的实现事实TSV 头严格校验units.tsv头为id\ttrack\tstate\tbranch\tpr\tsha\tbrief7 列ledger.tsv头为pr\tsha\tverdict\tevidence\tverifier\tts6 列读写都做宽度与头校验store.ts格式损坏会直接报错而非静默吞掉。原子写入所有写入都走临时文件 rename避免半写状态store.ts。CSV 公式注入防护cleanCell会把以 - 开头的单元格前缀防止把表格公式当数据处理store.ts。PID 文件锁.orch.lock记录持有者 pid写入前必须拿到锁--force可夺锁持有者 pid 已死process.kill(pid, 0)返回 ESRCH则自动替换对应剧本死会话的 store 锁会在下次写入时自动清除、orch 会替换持有者 pid 已消失的锁store.ts。幂等初始化orch init只writeIfMissing重复初始化不会破坏已有数据——测试 orch.test.ts 验证了两次 init 后文件内容一致。测试中还覆盖了锁的两种行为写入者在锁被他人持有时被阻塞并报store lock held by pid N只有--force才能夺锁以及脏锁pid 已死自动替换orch.test.ts。Brief唯一的产品你对代理的提示是你唯一的产品一份草率的 brief 会在整棵树上放大成次品。每次 spawn 都携带完整 brief一个你填不出来的字段就是一个你还没界定清楚的单元。完整模板GOAL 一句话说明产出能让没有聊天权限的陌生人直接执行 SCOPE 本单元可写的路径不可写的路径其独占的 worktree 或分支 CONTEXT 指向文件和 PR 的指针当本单元依赖上游报告时完整粘贴上游报告 因为工作代理看不到兄弟代理 ACCEPTANCE 可检查的标准一行一条 VERIFY 精确命令或 control 技能路径外加已知陷阱 TIMEBOX 运行时长的大致上限到期返回部分发现并停止而不是继续跑 FORBIDDEN 不 gt、不 rebase、不 force-push、不修 scope 之外的东西再加单元级禁令 REPORT 状态、分支、head SHA、PR、判定、实际跑了什么、偏差、建议的后续 STANDING preferences.md 逐字粘贴按单元缩放 brief一行命令的单元模板折叠成一段但仍须点名 goal、scope、verify 命令和报告形状。一个两行编辑外包 4KB 脚手架的 brief其书写与遵守成本比编辑本身还高。本地 spawn可以直接按 store 路径引用常驻指令文件逐字粘贴是给云端 spawn 和每次 resume 的。子协调者 brief 与依赖中继子协调者 brief 额外包含其 track 边界与单元清单、spawn 预算云端默认 本地例外清单、drain 协议、rollup 格式每个子代理名字、状态、PR、head SHA、判定、一行说明外加 track 状态与 frontier 增量。依赖是上下文中继不只是排序。未声明的上游上下文会让工作代理靠猜。缺失字段是拒绝 spawn 的条件。每个 wave 每子协调者抽查一个工作代理 brief且抽查与该 wave 并发进行绝不作为其前置门禁。失败的 brief 会停掉该 track 并修正子协调者的指令而不只是修正该工作代理——因为 brief 质量在运行后期会衰减。绝不 resume-chain 一个 brief用整合后的 scope 重新 spawn。七个执行步骤1. Frame框定把完成谓词写成可数的形式例如全部 126 个单元已合并每个都在台账中记为unit-test-verified或更优。量化范围单元数、大致工作量、预期栈数量、墙上时钟预算。如果单个代理能在该预算内完成在此停下改走 Autonomous run。Collapsing 的含义是直接在本会话内干活需要时用普通工作代理、验证内联、边做边落地不启用下述 store、登记册或 pilot 机制。对照预算安排落地节奏大约到 70% 预算时停止 spawn落地所有已验证的东西。按项目命名 track。有争议的分解或单向门先在 arena 技能pstack/skills/arena/SKILL.md中过一遍再开始 pilot。framing 只呈现一次可逆的准备不等待。2. Install the runtime安装运行时运行orch init。通过 show-me-your-work 技能pstack/skills/show-me-your-work/SKILL.md打开决策轨迹在任何 spawn 之前写好常驻指令并用orch frontier set --repo repo-dir从既有 PR 播种frontier.json。3. Pilot试点把一个单元推过完整路径brief、工作代理、验证、栈条目、台账行、合并。Pilot 的存在目的是在代价是一个代理而非五十个代理时证伪 brief 模板、验证配方和单元规模。从 pilot 证据修正契约后再开始任何扇出。Pilot 规模随单元缩放对近乎同构的廉价单元第一个单元本身就是 pilot作为普通单元运行、verify 命令内联落地即开始扇出。专用 pilot 管线独立验证代理、审计门禁只用于昂贵或新颖的单元形态克隆单元没必要——串行 pilot 没有可证伪的东西。4. Scale扩容按在途上限 spawn 一个滚动窗口的工作代理子代理完成即补位。阻塞式批次要付出每个批次最慢子代理的代价。只有超过 Roles 节的一次-drain 阈值才 spawn track 子协调者。每次 drain 后重算就绪工作。把上游报告中继进下游 brief。兄弟间通信只向上。抽样 brief 审计与它所抽样的 wave 并行运行失败时停的是下一次补位而不是当前这一波。5. Drain排空在每个 drain 点执行下文队列与 drain 纪律。6. Land落地落地是连续的绝不是收尾阶段。集成从第一个已验证单元开始与剩余 wave 并行推进。重型仓库上 stacker 从 wave 一开始就是常驻角色单元一验证就集成本地 git 便宜的仓库协调者按 Roles 节自己落地已验证单元。保持前沿绿色先于上层栈工作。Stack safety 主导。frontier.json只在合并或报告了新 head SHA 时才推进。7. Close收尾排空最终收件箱把每个 spawn 过的代理调和成终止行done、abandoned、zombie-reconciled在真实工件上确认谓词确认每个已落地 PR 的当前 head SHA 都有判定按 show-me-your-work 审计轨迹含跨模型评审把反复出现的修正编码进preferences.md或 brief 模板。保留 store 原样——它就是事后复盘材料。队列与 Drain 纪律收到完成通知时运行orch inbox push agent unit status [--report PATH]然后回到你正在做的事。绝不内联深度评审需要评审的完成会变成验证单元。绝不在 drain 中评审 diff。四个时点批量 drain关键小节结束、track rollup、前沿 watcher 唤醒通过 loop 技能布防配长心跳兜底、人类报告之前。每批以orch inbox drain开始。drain 期间到达的通知等下一批。优先完成的关键小节撰写 brief、栈操作、冲突决策、写门禁、更新台账或前沿。每次 drain 把每个指针分类为landed、needs-verify、failed、zombie、noise通过orch unit add、orch unit set、orch ledger record写入结果行运行orch status然后在一条消息里 spawn 下一波。在 track rollup 时对每个 spawn 过的子代理对账已到、已重 spawn、或其 scope 被显式吸收。默默重做缺失子代理的工作会同时掩盖浪费的开支和该结果本要填补的覆盖缺口。一次 drain 回合以orch status的三行输出结束按状态统计的计数、什么变了、有哪些门禁开着。细节在status.md中。源码印证orch CLI 的完整命令面orch.ts 用 commander 实现了全部簿记命令。全局选项--store dir或环境变量ORCH_STORE、--json输出完整行、--force夺锁。完整命令树命令用途关键参数orch init初始化 store—orch unit add id新增单元--track track必填、--brief path新单元状态为pendingorch unit set id更新单元--state state必填、--branch、--pr、--shaorch unit get/list/counts查询单元list 支持--state、--track过滤orch ledger record pr sha verdict记录验证判定--evidence path必填、--verifier nameorch ledger check pr sha查询判定未记录输出NOT-VERIFIED退出码 2orch ledger summary判定统计—orch inbox push agent unit status推入完成指针--report pathorch inbox drain/peek/count排空/窥视/计数drain 支持--peek只读不排空orch gate park/list/resolve管理门禁park 需--question、--options、--defaultresolve 需--answerorch frontier set/show计算/展示前沿set 需--repo dir或ORCH_REPO可选--prs n,...钉定 PR 顺序orch status渲染status.md并打印摘要—orch standing show/add line管理常驻指令自动编号追加退出码约定测试 orch.test.ts 验证成功为 0用户/用法错误为 1not-found 为 2且--json下仍向 stdout 输出结构化 JSON如{pr:184530,sha:abc123,verdict:NOT-VERIFIED}。orch status的三行摘要来自statusLinesorch.tscounts:单元数与状态分布、台账判定分布、changed:与上次渲染的差异如units done 0-3; ledger unit-test-verified 1-4、gates open:门禁数量与 ID。status.md内含!-- orch-summary ... --注释用于差异检测store.ts。Stack 安全前沿是计算对象绝不是叙述。每次合并和栈突变后都要从gt重新计算frontier.json——因为 GitHub base ref 会在 restack 中途漂移而 gt 的追踪才是权威有序 PR 列表、分支名、head SHA、代数generation number、最低未合并 PR。在 gt 认识该栈的地方解析它通常是 stacker 的 clone。gt 元数据从未见过提交的 checkout 会报告无 PR命令直接报错而不是猜。每个栈恰好一个 stacker 可运行gt在其栈内串行。持有者记录在常驻指令中。Restack 在云端运行——此规模下本地 restack 会把笔记本拖垮。工作代理绝不 rebase、绝不运行gt。Babysitter 按 babysit.md 行事每个栈一个scope 限定在一个不可变前沿代内它们把冲突报告给 stacker而不是自己 restack。PR 关闭与重定向只经 stacker。关闭一个基 PR 会让其上方整条链成为孤儿。合并与栈手术是和其它单元一样带 brief 的单元。一个 retro watcher跟踪已合并 PR 的 revert、合并后 CI 破裂和孤儿后续。源码印证前沿计算orch frontier set --repo的实现先gt log short --stack --reverse拿到有序分支再对每个分支gt info解析 PR 号与状态MERGED/CLOSED/OPEN其中OPEN匹配一长串 Graphite 状态词如Needs approvals、Merge conflicts、Ready to merge等再用git rev-parse取每个分支 SHA代数 1lowestUnmerged取第一个OPEN的 PRstore.ts。可选的--prs n,...钉定会校验实际顺序与预期完全一致漂移时报frontier pin mismatch: missing from gt ...; extra in gt ...; order differs ...store.ts。测试用 fakegt脚本验证了 merged/closed/open 三种状态、钉定校验与不可解析输出的显式报错orch.test.ts。验证体系台账是唯一答案验证规模随单元缩放VERIFY 是单个廉价命令时工作代理运行并报告输出协调者抽查凭证即可。专用验证代理模型族与工作代理不同只用于验证昂贵、依赖判断或高爆炸半径的单元。一个只会重跑一条命令的验证代理是仪式不是验证。台账命令orch ledger record写行orch ledger check查当前 PR 与 head SHA。ledger.tsv每行一个判定键为PR 号 head SHA五档判定判定含义live-ui-verified真实 UI 验证通过unit-test-verified单元测试验证通过type-check-only仅类型检查verifier-blocked验证器被阻塞不是通过verifier-failed验证失败关键规则CI 绿是判定的输入不是判定本身。行为类工作必须好于type-check-only。verifier-blocked不是通过环境恢复后重新 spawn。verifier-failed产生一个修复单元而不是重新验证。工作代理可自报但验证代理在同一键上覆盖之。新 head SHA 使旧行失效restack 后必须重新验证。台账回答这个是否被验证过不靠记忆也不靠转录。一个单元在落地那一刻输出被外部化之前都不算完成绝不批量拖到运行结束工作代理 push 分支、验证代理写台账行、凭证落进 store。只存在于某台 VM 上、而那台 VM 死了的工作等于从未做过。源码印证台账的键与覆盖语义ledger.record按pr sha查找现有行找到则原地替换覆盖否则追加ts自动写入 ISO 时间戳store.ts。parseVerdict在 CLI 层把非法判定直接拒绝orch.ts。测试验证了先record unit-test-verified再record live-ui-verified后 summary 只剩后者即同一键被覆盖非法判定looks-good直接抛错orch.test.ts。存活性与失败处理绝不 resume 一个代理去看看它。Resume 会重启空闲代理。用只读方式探测台账、units.tsv、gh、已 push 的分支、Cursor 仪表盘里云端代理的状态。转录的 mtime 不是存活证据。静默死亡得到收件箱里一条合成的复盘行单元、失败模式、最后证据、选项。证据一到就重规划。绝不等待完全静止。按模式重试失败模式处理命中上限或 OOM缩小 scope 重新 spawn网络断连原样重试工具错误换不同模型重试未知重试一次两次重试后放弃该单元并绕行重规划。迟归数小时的僵尸在接受任何东西之前先对照当前前沿与台账调和。通过全新单元抢救独有发现绝不盲合并。当继续 spawn 会产生树级垃圾上游输出差、验收坏了、基础设施死了时在常驻指令顶部写一行停止线让在途工作完成修好原因再清除该行。用约束子代理的同样方式约束你自己的基础设施重试。连续几次工具中止后停止重试把终止交接写入持久状态做了什么、存在哪里、恢复用的确切命令结束运行。Cursor 重启之后本地代理已死云端工作没死。重读常驻指令与units.tsv重算前沿按 PR 与分支而非代理 ID 重新挂接云端工作从存储的 brief 加当前状态为每个 track 重 spawn 一个子协调者drain继续。死会话的 store 锁在下一次写入时自行清除orch会替换持有者 pid 已消失的锁源码见上文 PID 锁实现与测试 orch.test.ts。升级策略什么该打扰人类到达人类批量汇入状态页而不是逐条不可逆动作对共享分支 force-push、部署、删除、关闭别人的 PR、没有实验能定案的产品或偏好判断、与观察到的现实相矛盾的常驻指令、重规划后仍然存活的程序级死胡同。先把它作为gates.md条目停放再绕行其继续工作。绝不打扰人类前沿微调、restack 机制、重试、CI flake 分诊、评审线程分诊、格式修复、brief 已禁止的 scope拒绝并继续、以及我该继续吗。拿不准就行动并记录。运行中发现的问题只修阻挡前沿的部分其余一律停进 follow-ups——在这个扇出规模下一次小的 scope 泄漏会倍增成没人要的 PR。Reply 契约从表里取数不靠叙述在检查点与收尾时回复谓词及对照units.tsv与ledger.tsv的计数、各 track 及其落地内容、前沿PR 列表加 SHA、判定摘要、放弃了什么及原因、等待人类的门禁唯一允许的请求、store 路径、轨迹路径。数字来自表不是叙述。包含 PR 链接。这条契约与 drain 纪律呼应一次 drain 回合的三行摘要、收尾时的完整报告全部以表为事实源保证协调者聊天在长周期运行中始终能向人类给出可核验、可续接的状态快照。小结Orchestrate 剧本把程序级多代理并行从口号变成了可执行的纪律角色分层协调者/子协调者/工作代理、纯文本 store每文件一写入者、brief 模板与缩放、七步执行、队列 drain、Stack 安全、验证台账、失败恢复与升级边界。其背后的 orch.ts 与 store.ts 以约 1600 行实现和完整测试orch.test.ts把这些纪律落成了可运行、可审计、可恢复的工具——让人类每天检查两次的长周期程序有一个不依赖任何单次会话寿命的持久骨架。【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考