Orchestrate 插件 Planner 操作手册任务图设计、CLI 驱动循环与 Andon 停止线的完整实践【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/pluginsOrchestrate 是 Cursor 插件仓库中用于把大目标拆分为并行云端 Agent 树的调度插件其中 planner.md 是 root 与 subplanner 两类规划节点的操作手册规定了从发布任务图plan.json、驱动工作区循环run到失败恢复与 Andon 全局暂停的全部行为准则。读完本文你将掌握 planner 的前置依赖与 Slack 权限配置、plan.json/state.json的职责边界、CLI 各子命令与退出码语义、comment重试队列以及 Andon 停止线的 raise/clear 机制并能对照仓库源码理解每条规则背后的实现依据。一、角色定位planner 与 dispatcher 的分工Orchestrate 技能定义了两种角色各自对应一份参考文档互不混读Dispatcher在本地 IDE 会话中收到用户/orchestrate goal时只负责一次性启动云端 root planner 并返回其 URL随后停止。其行为规范见 dispatcher.md。Plannerroot 或 subplanner以 You are the root planner for: 或 You are a subplanner for: 开头提示词被唤醒时读取planner.md。Root 向用户汇报subplanner 向父 planner 汇报两者的工作方式完全一致——这正是planner.md开篇声明的核心原则。角色路由在 SKILL.md 中有明确说明且该技能声明disable-model-invocation: true只在用户显式调用时加载。二、前置条件bun、cursor-sdk 与 Slack 权限planner.md要求 planner 在行动前完成三项加载加载 cursor-sdk 技能认证、spawn 与错误分类CursorAgentError与RunResult.status error的区别都在 cursor-sdk 技能中定义planner 不应重复实现这些逻辑。bun 运行时所有脚本期望 PATH 上有bun。首次使用需在技能的scripts/目录执行bun install安装依赖。schema 再生成plan 或 state 结构变化后在scripts/目录执行bun run generate-schemas由 schemas.ts 重新生成schemas/*.json。Slack 可见性使用SLACK_BOT_TOKEN所需 scope 如下原文档完整清单Scope用途chat:write发送与编辑消息chat:write.customize设置 bot 消息的自定义用户名和图标chat:write.public未加入前先向公共频道发消息files:write上传 handoff 工件files:read配合files:write走上传 v2 流程reactions:read监听 kickoff 消息上的 Andon:rotating_light:表情channels:history通过conversations.replies读线程回复若 run 线程在私有频道则改用groups:history可选 scopeusers:read.email——对 dispatcher 的 git email 做尽力而为的 first-name 查找缺省时需显式传--dispatcher-name。文档特别强调一个健壮性设计在 scope 补齐之前Slack 调用会以missing_scope错误进入attention.log但运行不会中断因为 git 与磁盘才是权威数据源。这一点与下文single source of truth一节呼应。三、Single source of truthgit 与磁盘是载体planner.md用 Git and disk are the substrate 概括了四个文件各自的职责工件承载内容plan.json任务图、Slack 配置、repo URL、模型选择state.json任务状态、agent/run id、分支名、Slack 消息时间戳handoffs/*.mdworker 与 verifier 的输出attention.log操作者可见的失败与决策记录Slack 只是人类可见性通道不是任务状态。脚本会发一条 kickoff 消息、在该线程内镜像任务状态并读取 kickoff 消息上的:rotating_light:表情作为 Andon 信号。kickoff 之后Slack 写入全部限制在 run 线程内——Slack 适配器要求这类写入必须带threadTs。边界划分同样清晰Orchestrate 拥有 Slack 状态镜像、Andon 与 comment 重试队列agent 仍可自己直接调用 Linear、GitHub、Slack、Notion 等 MCP 做临时外部工作但这些系统不是orchestrate 的目的地。从 schema 层面可以印证这一设计plan.schema.json 把slackChannel、slackKickoffRef描述为由 kickoff 或脚本写入planner 不编写的字段而 state.schema.json 中每个任务行的slackTs、slackRendered最后渲染的 Slack 状态元组用于无操作更新守卫都是脚本回写字段与 planner 编写的name、type、branch、startingRef、dependsOn、status等必填字段分离。四、Phase 1发布任务图plan.json4.1 写入位置与完整示例plan.json写入workspace默认工作区为.orchestrate/rootSlug/。原文档给出的标准示例如下{ $schema: path-to-orchestrate/schemas/plan.schema.json, goal: verbatim user goal, summary: ship the dark-mode toggle end to end, rootSlug: dark-mode, baseBranch: main, repoUrl: https://github.com/example-org/example-repo, tasks: [ { name: frontend-toggle, type: worker, scopedGoal: Add a Settings UI toggle that flips useDarkMode in localStorage., pathsAllowed: [packages/ui/src/settings/**], acceptance: [Toggle renders in Settings Appearance] } ] }字段语义要点goalvssummarysummary给 Slack 线程里的人类看goal是 agent 的完整上下文。未设summary时 kickoff 回退为截断的goal。Slack 通道继承首次run --root时脚本使用plan.slackChannel发 kickoff 并写回plan.slackKickoffRef。Root plan 的slackChannel来自kickoff --slack-channel、run --root --slack-channel或SLACK_CHANNEL_IDsubplanner 继承这两个字段使整棵任务树镜像到同一个线程。对照 plan.schema.json顶层必填字段为goal、rootSlug、baseBranch、repoUrlrootSlug与任务name均受^[a-z0-9-]$约束kebab-case ASCII用于分支名。tasks[]是worker/subplanner/verifier三类的anyOf判别联合verifier必须提供verifies指向被校验任务名而worker与subplanner显式禁止verifies字段。4.2 规划规则planning rules文档给出十条规划规则是 planner 判断分解粒度的核心逐条说明Merge 也是任务发布一个 worker其scopedGoal说明合并哪些分支、冲突处理意图与验证方式。默认用 worker除非你能说出 subplanner 会做的具体分解。一个 worker 可以承担很多worker 和 verifier 都是拥有数小时运行时的完整云端 agent——多文件切片、多步骤重构、完整的复现/修复/测试循环都适合放进单次 spawn。每次 spawn 都消耗云端 agent 运行时、Slack 噪音与你的协调开销。默认更少、更宽的 worker只有在切片真正独立或有真实争用风险时才拆细。默认配 verifier使用type: verifier和verifies: 目标任务名。verify是具体检查配方worker 把它当目标行为读verifier 从目标任务继承它。openPR: true仅用于你希望独立作为 draft PR 交付的独立 worker 任务。定量声明加measurements[]脚本会在 handoff 后于 worker 分支重新执行每条命令并记录漂移。保持 fan-in 小某任务需要大量上游 handoff 时先发布一个聚合 worker。最小化路径重叠兄弟任务所有权重要时列出禁止路径。任务规格放plan.tasks[]共享工件放 git并按路径引用。Slack 备注走commentCLI的重试队列只有必须送达的消息用--criticality required非 Slack 目的地由 agent 直接调用相应 MCP。measurements[]的 schema 细节值得展开每项必填name须与 worker 的## Measurements报告块行前缀逐字匹配如LOC(packages/ui/src/Settings.tsx)与command在 worker 分支全新 checkout 中以bash -c执行parser支持wc-l默认统计非空行数与regexJS 正则作用于 stdout捕获组 1 为取值两种toleranceFraction为 0–1 的数值漂移容忍度默认 0.1010%字符串值要求精确匹配。这正是worker 自报数据 vs 实际工件漂移检测的实现契约。五、Phase 2驱动工作区run 循环所有操作者动作都经过 cli.tsbun path-to-orchestrate/scripts/cli.ts subcommand workspace [...]CLI 的入口实现见 cli/index.ts它用 commander 注册了五组子命令任务操作组cli/task.ts提供run、kickoff、spawn、kill检查组cli/inspect.ts提供tree、list、status。run的循环语义spawn 所有依赖已满足的 pending 任务等待 handoff写入 handoff重复直到无法再推进退出码0表示干净完成退出码100表示计划中的 checkpoint 重启——原样重跑同一条命令其余非零码表示应阅读state.json与attention.log。退出码 100 在源码中是具名常量core/loop.ts 定义PLANNED_CHECKPOINT_EXIT_CODE 100当运行时达到上限且仍有非终态任务时循环先调用syncStateToGit(planned checkpoint restart)提交状态再退出并打印重跑提示——这与文档计划性 checkpoint 重启会在退出 100 前提交 state 与 handoffs的说明完全一致。不要 detachrun。脚本是 state、handoffs、Slack 镜像、重试队列排空与 Andon 轮询的心跳。退出后调用tree若仍有pending或running任务就再跑一轮循环。state.json是事实源用tree、list、status检查。从 state.schema.json 可以确认状态机取值status枚举为pending/running/handed-off/error/cancelled/pruned注释说明pruned指任务被移出plan.jsonresultStatus记录云端 run 的RunResult.statusattempts记录逻辑 spawn 次数与 planner 侧的maxAttempts上限对应。六、comment CLISlack 备注与重试队列commentCLI 仅面向 Slack实现见 cli/comments.ts且永远不会发布 kickoff。两种定位方式--task name校验任务上下文并解析 run 线程--thread-ts ts显式给定线程时间戳。原文档示例bun cli.ts comment worker-one is blocked on auth --task worker-one --workspace .orchestrate/root bun cli.ts comment no-repro on the upstream report; need a Linear ticket filed before retrying --thread-ts 1714500000.000100 --criticality required --workspace .orchestrate/root操作边界规则使用--task以及非操作者文件上传时--workspace必填处于 run 之外的操作者需把~/.orchestrate/operator-mode文件置为0600才能启用操作者模式worker 被假定无法写操作者的 OS home 目录必需级required消息走comment-retry-queue.json并按既有退避表重试外部追踪器Linear、GitHub、on-call 呼叫由 agent 直接调用对应 MCPorchestrate 不代理这些系统。七、失败恢复脚本管机制planner 管语义planner.md的分工原则是Script handles mechanical liveness. Planner handles meaning.具体恢复手段场景处理方与行为瞬时 spawn 失败在spawnTask内部自动重试循环重启通过recoverRunning重新附着到运行中的任务RunResult.status error或 handoff 被阻塞planner 决策重生、拆分、升级或放弃上游失败下游任务保持pending修复上游后重跑或kill掉已放弃的下游工作Subplanner 重生首次尝试后从自己的分支克隆已提交的子状态与 handoffs 得以保留自动 spawn 上限maxAttempts封顶仅当再次尝试是有意为之时才在任务定义中上调计划性 checkpoint 重启退出100前提交 state 与 handoffs重跑同一条命令八、Andon跨树暂停的新 spawn 熔断Andon 会暂停整棵树的新 spawn。Root 轮询 Slack kickoff 消息上的:rotating_light:表情子节点则通过 git 读取缓存的 root 状态plan.andonStateRef与plan.andonStatePath无需自己调用 Slack。bun path-to-orchestrate/scripts/cli.ts andon raise --reason why --workspace workspace bun path-to-orchestrate/scripts/cli.ts andon clear --workspace workspace [--note what changed]源码实现cli/andon.ts与文档逐条对应raise必填--reason它在 run 线程内发布 ANDON RAISED by sender: reason并给 kickoff 消息添加rotating_light反应clear会先断言操作者模式源码注释明确workers must not clear an active Andon然后发布✅ ANDON CLEARED并移除反应源码注释解释了为何子节点用表情而非消息体reactions.get便宜且不携带文本reason 作为独立线程消息供人类阅读前缀 ANDON RAISED则让attention.log的历史扫描能 grep 回原因。状态写入路径root 把截断后的 reason 写入state.andon.reason对应 state.schema.json 中andon对象的raisedAt/raisedBy/reason/cleared/clearNote/lastCheckedAt字段。Andon 状态是操作者输入、上限 500 字符、与state.json其余内容处于同一信任圈。触发纪律只有当继续 spawn 会给整棵树产出垃圾时才 raise Andon——上游输出坏、验收标准坏了、不可恢复的认证/基础设施问题。单个任务自己的小故障属于它自己的 handoff不属于 Andon。九、定位 agent 与远程观测用bun cli.ts tree workspace和bun cli.ts list workspace查看血缘、状态与 agent ID不要依赖云端 agent 的显示标题。syncStateToGit默认为开schema 中default: true远程观察者可直接从 git 读state.json与 handoffs若这些工件应保持本地将其置为false。forensics 组命令cli/forensics.ts用于在任意本地仓库副本上回溯bun cli.ts crawl local-repo-path root-branch root-slug bun cli.ts kill-tree local-repo-path root-branch root-slug [-y] [--agent-id id]两条命令都遍历.orchestrate/rootSlug/state.json每个 subplanner 行会递归进入orch/rootSlug/subplanner-name——这就是任务树分支命名的落地形态。十、小结planner.md的本质是把长循环 agent 会漂移这一问题收敛为一条可执行纪律planner 只写plan.json与决策脚本拥有run心跳与state.jsongit 与磁盘是权威载体Slack 是可降级的可见性层。围绕这条主线文档覆盖了规划粒度判断少而宽的 worker、默认 verifier、小 fan-in、失败恢复的双层分工机械存活归脚本、语义判断归 planner、Andon 全局熔断的严格触发条件以及 comment 重试队列的送达保障。配合 plan.schema.json 与 state.schema.json 的字段契约、cli/index.ts 的子命令注册和 core/loop.ts 中的 checkpoint 退出逻辑操作者可以完整复现一次/orchestrate运行并做出有据可依的运维决策。【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考