orchestrator

Orchestrator

使用 Orchestrator，让当前 Agent 协调其他 Agent。此技能是接口；orchestrator CLI 是底层确定性控制平面。

开始

1. 阅读本文件旁边的 PREFERENCES.md。仅应用 User Preferences 下的非注释内容。No preferences set. 表示自行判断。
2. 优先遵循当前用户请求中的明确指示，再考虑已存储的偏好。
3. 使用 orchestrator --help 检查 CLI。如果未安装且 npm 可用，请使用 npm install -g @backnotprop/orchestrator-cli 安装。
4. 运行 orchestrator help --json --compact，查看当前命令约定。
5. 如果不确定运行时是否可用，请运行 orchestrator doctor --json --compact。仅从 runtimeSummary.availableIds 中选择。
6. 选择确切的模型值之前，先运行 orchestrator models <runtime> --json --compact。

不要因为示例中出现某个运行时或模型，就假定它一定存在。

偏好

偏好是供调用方 Agent 使用的路由策略，可能说明：

• 某类任务应使用哪个运行时或模型；
• 应使用哪些回退选项，以及顺序如何；
• 何时拆分任务并行处理，何时交由单个 Agent 处理；
• 提供商用量耗尽时应采取什么措施。

按以下优先级处理：

1. 当前请求中的明确指示；
2. PREFERENCES.md；
3. 实时运行时和提供商信息；
4. 自行判断。

如果偏好名称与已配置的运行时和模型值之间的对应关系明确，请进行映射。如果映射会造成重大影响且不明确，请向用户询问一次。偏好不代表获准执行无关工作，也不能凌驾于任务安全要求之上。

如果偏好取决于用量，请运行 orchestrator limits --json --compact。无法获取的限额数据应视为未知，而非已耗尽。仅当首选项不可用、已耗尽或明确失败时，才遵循已配置的回退选项。如果策略要求在所有选项耗尽时暂停，则不要启动任何任务，并通知用户。

选择模型

用户未指定模型时，省略 --model。已安装的运行时会选择当前默认模型。

传入确切的模型值之前，先运行：

orchestrator models <runtime> --json --compact

• 将用户请求和偏好标签与 models[].id 或 models[].displayName 匹配，并将匹配到的 id 传给 --model。
• 根据返回的 defaultModel、alias 或 router 解析“latest”或“best”。不要按版本名称排序，也不要凭记忆猜测。
• 将 partial 视为有用但不完整的发现结果。例如，Claude Code 会提供当前系列的别名，而不是确切目录。
• 如果无法进行发现，除非请求要求选择确切模型，否则省略 --model。
• 除非当前请求或偏好定义了回退选项，否则不要悄悄替换不可用的确切模型。
• 如果描述或能力信息很重要，请运行返回的 fullModels.args。

模型值保持提供商原生形式，传递时不得更改。

委派一项任务

使用命名任务，并保留其返回的 ID：

orchestrator launch codex --name "inspect store" --json --compact --brief "Inspect the task store."
orchestrator read <task-id|prefix> --wait --json --compact

精确的本地命令使用 shell。审查、实现、研究、探索或分析任务使用 AI 运行时。

并行分派

为相互独立的工作启动单独的任务。如果有多个任务需要同时启动，请使用清单：

{
  "schemaVersion": 1,
  "tasks": [
    {
      "runtime": "claude-code",
      "name": "review tests",
      "task": "Find the highest-risk missing tests."
    },
    {
      "runtime": "grok",
      "name": "inspect api",
      "task": "Inspect the API boundary for bugs."
    }
  ]
}

orchestrator launch -f agents.json --json --compact --brief
orchestrator ps --json --compact --active --brief
orchestrator read <task-id> <task-id> --wait --json --compact

不要将多个任务 ID 合并到一个带引号的字符串中。

让 Orchestrator 协调

如果用户希望 Orchestrator 自行规划并管理委派，请使用父 Agent：

orchestrator run --background --name "repo work" --json --compact "Delegate independent work, wait for every child, then synthesize the result."

如果 compact doctor 返回 parent.canRun: true，请将请求附加到 parent.run.argsPrefix 或 parent.run.backgroundArgsPrefix。

操作工作

orchestrator ps --json --compact --active --brief
orchestrator ps -A --json --compact --active --brief
orchestrator watch <task-id> --agent-only --json
orchestrator read <task-id>... --wait --json --compact
orchestrator logs <task-id> --follow
orchestrator events <task-id> --agent-only --json --compact
orchestrator resume <task-id> --json --compact "Continue from the prior result."
orchestrator interrupt <task-id> --json --compact --reason "no longer needed"

• 优先使用 JSON 中返回的可移植 commands.*.args 和 stop.args。
• 将返回的参数数组视为 argv 数组。
• 如果下一步需要等待结果，请使用 read --wait，而不是反复轮询。
• 使用 watch 查看规范化的实时事件，使用 logs 查看原始提供方输出。
• 仅在任务已完成、已存储提供方元数据且运行时支持恢复时才恢复任务。
• 停止已过时、重复或不再需要的工作。
• 交接工作时，报告任务 ID、运行时、模型和状态。

运行时说明

内置启动目标包括 claude-code、codex、 codex-app-server、copilot、grok、pi 和 shell。配置可以 禁用内置目标，或添加自定义运行时 ID。

一次性 Codex 工作请使用 codex。如果 Codex 工作需要多次发送消息、原生 目标、引导或持久化的提供方线程，请优先使用 codex-app-server --session：

orchestrator launch codex-app-server --session --name "deep worker" --json --compact --brief
orchestrator send <task-id> --wait --json --compact "Inspect the current bottlenecks."
orchestrator goal start <task-id> --wait --json --compact "Improve the system."

除非用户需要硬性上限，否则不要设置目标令牌预算。

清理范围

优先使用精确的任务 ID。仅在有意为之时才清理整个工作区：

orchestrator interrupt --active --json --compact --reason "cleanup"

仅在用户明确要求时才清理所有工作区：

orchestrator interrupt -A --active --yes --json --compact --reason "cleanup"