SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场orchestrate

orchestrate

智能体与模型

查看项目

更新于 10-16 04:14

技能介绍

Orchestrate 是一个元智能体监督器（Agent Fleet Supervisor），用于管理一组运行在 tmux 窗口中的 Claude Code 智能体。其核心模型是：一个 tmux 会话、N 个窗口，每个窗口是一个在独立 worktree 中工作的智能体。用户可以用自然语言表达意图，由 Claude 将其映射到相应脚本。

【用途】 Orchestrate 用于并行调度和监控多个 Claude Code 智能体，让它们各自在独立的 git worktree 中执行任务（如实现功能、提交 PR、处理 PR 评论等），同时由监督者统一协调、检查状态、处理阻塞和验证完成情况。

【主要能力】 脚本能力包括：

  • find-spare.sh [REPO_ROOT]：列出空闲 worktree，每行输出 PATH BRANCH。
  • spawn-agent.sh SESSION PATH SPARE NEW_BRANCH OBJECTIVE [PR_NUMBER] [STEPS...]：创建窗口、检出分支、启动 claude、发送任务，标准输出仅返回 SESSION:WIN。
  • recycle-agent.sh WINDOW PATH SPARE_BRANCH：关闭窗口并恢复空闲分支。
  • run-loop.sh：机械式看护，负责空闲重启、对话框批准、在 ORCHESTRATOR:DONE 后回收、监督者健康检查、全部完成通知。
  • verify-complete.sh WINDOW：验证 PR 是否完成，检查检查点、未解决线程数、CI 状态、是否有新的 CHANGES_REQUESTED。
  • notify.sh MESSAGE：通过 Discord webhook、macOS 通知中心和标准输出发送通知。
  • capacity.sh [REPO_ROOT]：打印可用和正在使用的 worktree。
  • status.sh：打印舰队状态和实时窗格命令。
  • poll-cycle.sh：执行一次监控周期，分类窗格、跟踪检查点、返回 JSON 动作数组。
  • classify-pane.sh WINDOW：分类单个窗格状态。

【监督模型】 编排 Claude（当前会话本身即监督者）负责读取窗格输出、检查 CI、进行针对性干预。run-loop.sh 运行在单独的 tmux 窗口中，每 30 秒执行一次，仅做机械操作：空闲重启、对话框批准、在 ORCHESTRATOR:DONE 后回收。监督者不应另开一个 Claude 窗口，因为会丢失上下文、难以观察并加剧上下文压缩问题。

【检查点协议】 智能体在完成每个必需步骤时输出 CHECKPOINT:<step-name>。必需步骤作为参数传给 spawn-agent.sh（例如 pr-address pr-test）。run-loop.sh 只有在窗格输出中找到所有必需检查点后才会回收窗口。如果 verify-complete.sh 失败，智能体会被自动重新简报。

【worktree 生命周期】 spare/N 分支 → spawn-agent.sh（--session-id UUID）→ 窗口 + feat/branch + claude 运行 → CHECKPOINT:<step> → ORCHESTRATOR:DONE → verify-complete.sh 验证 → 状态置为 done、通知、窗口保持打开 → 用户或编排者显式请求回收 → recycle-agent.sh → 恢复为 spare/N。窗口从不自动关闭，worktree 保持在任务分支上，会话保持存活，直到显式回收。

【会话恢复】 可通过 claude --resume SESSION_ID --permission-mode bypassPermissions 恢复指定会话，或通过 cd /path/to/worktree && claude --continue --permission-mode bypassPermissions 恢复该目录最近会话。--continue 会恢复完整对话历史，包括所有工具调用、文件编辑和上下文。

【状态文件】 状态文件位于 ~/.claude/orchestrator-state.json，从不提交到 git，使用 jq + 原子写入（.tmp → mv）维护。包含 active、tmux_session、idle_threshold_seconds、loop_window、repo、discord_webhook、last_poll_at 以及 agents 数组。每个 agent 记录包含 window、worktree、worktree_path、spare_branch、branch、objective、pr_number、session_id、steps、checkpoints、state、last_output_hash、last_seen_at、spawned_at、idle_since、revision_count、last_rebriefed_at。智能体状态包括 running、idle、stuck、waiting_approval、complete、done、escalated。done 表示已验证完成，但窗口仍打开、会话仍存活、worktree 仍在任务分支上，尚未回收。

【串行 /pr-test 规则】 /pr-test 和 /pr-test --fix 会运行本地 Docker 和集成测试，使用共享端口、共享数据库和共享构建缓存。同时运行两个 /pr-test 会导致端口冲突和数据库损坏。规则是同一时间只运行一个 /pr-test，由编排者串行化。智能体可以并行执行 pr-review 和 pr-address，但当 PR 需要本地测试时，应加入队列，由编排者自己顺序运行 /pr-test，并通过 tmux send-keys 将结果反馈给相关智能体。

【意图到动作映射】 用户说“status”“what's running”“show agents”时运行 status.sh + capacity.sh；说“how many free”“capacity”“available worktrees”时运行 capacity.sh；说“start N agents on X, Y, Z”或“run these tasks”时进入生成智能体流程；说“add task”“add one more agent for”时添加智能体；说“stop”“shut down”“pause the fleet”时停止；说“poll”“check now”“run a cycle”时运行 poll-cycle.sh；说“recycle window X”“free up autogpt3”时直接运行 recycle-agent.sh。意图不明确时先显示容量并询问任务。

【生成智能体流程】

  1. 解析 tmux 会话，使用已有会话，绝不在 Claude 内创建 tmux 会话（会成为 Claude 进程子进程并在会话结束时死亡）。若无会话，提示用户先在终端运行 tmux new-session -d -s autogpt1，再重新调用 /orchestrate。
  2. 显示可用容量。
  3. 从用户收集任务：objective、branch name、pr_number、steps。仅在用户提及时询问 idle_threshold_seconds（默认 300）。不要让用户指定 worktree，从 find-spare.sh 自动分配。
  4. 每个任务生成一个智能体，spawn-agent.sh 会自动写入初始 agent 记录，不要重复追加。
  5. 启动机械看护 run-loop.sh。
  6. 在当前对话中直接开始监督，立即开始第一次轮询循环，每 2-3 分钟一次，不要另开监督 Claude 窗口。

【监督者职责】 监督者每 2-3 分钟在本对话中运行轮询循环。轮询机制：以 run_in_background: true 加 sleep 开始每次轮询，后台任务通知后读取窗格输出并采取行动，立即安排下一次后台轮询，直到所有智能体完成或升级。每次轮询检查状态文件、捕获每个 running/stuck/idle 智能体的窗格输出，并根据所见采取行动：工具运行中则不动；空闲提示则发送针对性提醒；错误循环则发送精确修复；等待输入则回答解锁；CI 红色则告知失败详情；GitHub 滥用速率限制则提醒等待；上下文压缩则发送恢复指令；看到 ORCHESTRATOR:DONE 则查询未解决线程数并验证。轮询所有窗口应基于状态文件而非记忆。

【RUNNING 计数说明】 run-loop.sh 的 RUNNING 计数包含 waiting_approval 状态的智能体，因此仅等待批准的舰队仍会显示 RUNNING > 0，并不代表智能体在积极工作。应直接检查状态文件确认。

【状态文件陈旧恢复】 状态文件可能因窗口关闭、会话过期或编排者跨对话重启而与现实脱节。迹象包括 loop_window 指向不存在的窗口、agent 状态为 running 但 tmux 窗口已关闭或显示 shell 提示、last_seen_at 数小时前但状态仍为 running。恢复步骤包括验证实际 tmux 窗口等。

【适用场景】 适合需要并行运行多个 Claude Code 智能体、各自在独立 worktree 中处理任务（如实现功能、提交 PR、处理 PR 评论、运行测试）并需要统一监督、验证和通知的开发工作流。

【限制】 /pr-test 必须串行执行，不能并行；不应在 Claude 内创建 tmux 会话；不应另开监督 Claude 窗口；窗口不会自动关闭，需显式回收；状态文件可能陈旧，需要恢复。