orchestrator-skill

Codex 司令模式工作流：主 agent 只做规划、派发、审查和汇报，读文件、搜代码、改代码、跑测试等消耗 token 的操作交给 subagent。

支持 Windows、macOS、Linux，可通过 npm 一键安装，也可手动复制到任意设备。

让 Codex 更省、更快、更有秩序。 orchestrator-skill 是一个面向 Codex 的 Agent 编排 Skill：主 Agent 负责判断与调度，subagent 负责高负载读取、搜索、编辑和验证，用指挥官驱动多 agent 协作的方式显著节省模型 Token 和 API 开销，同时保住任务质量与吞吐。它面向 AI 编程、Codex Agents、大上下文代码任务、long-context 项目分析，以及所有希望降低 coding agent 成本、提升自动化效率的开发者。

Quickstart

1. 安装：

npm install -g orchestrator-skill

2. 选择并生成 worker：

orchestrator-skill init-agent

3. 校验：

orchestrator-skill check

4. 在 Codex prompt 中带上触发词：

司令模式

功能

• 主 agent 当指挥，subagent 干活
• 触发词：司令模式 或 orchestrator
• 可自定义 subagent 模型
• 从用户自己的 config.toml 自动生成 worker 配置
• 不会覆盖用户已有的 agent 配置
• 支持并行派发独立任务、顺序派发依赖任务

安装

推荐使用 npm（稳定，走 npm 官方 registry 全球 CDN）。需要 Node.js 18+ 和 npm。

npm install -g orchestrator-skill

安装完成后校验：

orchestrator-skill check

不使用 npm 的安装

不使用 npm 时，最稳的方式是直接从 npm 官方 registry 下载 tarball，不依赖 GitHub。需要 curl、tar 和 Node.js 18+：

curl -fsSL https://registry.npmjs.org/orchestrator-skill/-/orchestrator-skill-1.3.6.tgz -o /tmp/orchestrator-skill.tgz \
  && rm -rf /tmp/orchestrator-skill-pkg \
  && mkdir -p /tmp/orchestrator-skill-pkg \
  && tar -xzf /tmp/orchestrator-skill.tgz -C /tmp/orchestrator-skill-pkg \
  && node /tmp/orchestrator-skill-pkg/package/install.js install

这条命令从 npm 官方 CDN 拉取 tarball，自动安装 skill、全局规则，并在安装完成后提示运行 orchestrator-skill init-agent。由于它不经过 npm 全局安装，orchestrator-skill 命令不会自动进入 PATH；你需要手动调用：

node /tmp/orchestrator-skill-pkg/package/install.js check

或在能将 Node 脚本加入 PATH 的环境中，把 install.js 链接为可执行命令后使用。

另一种可选方式（稳定性依赖 GitHub raw 域名，不如 npm registry 稳定）：

curl -fsSL https://raw.githubusercontent.com/SU0510/orchestrator-skill/main/install.sh | bash

该脚本会自行从 npm 官方 registry 拉取最新 tarball 安装，并额外把 orchestrator-skill CLI 放入 ~/.local/bin 并加入 PATH。两者下载源都是 npm registry，区别只是入口脚本的位置。

初始化 worker

首次安装后，需要指定一个模型作为 worker。

交互式选择：

orchestrator-skill init-agent

直接指定模型：

orchestrator-skill init-agent mycombo
orchestrator-skill init-agent glm-5.2

init-agent 会：

1. 读取你的 ~/.codex/config.toml
2. 列出所有可用模型
3. 生成对应的 ~/.codex/agents/<name>.toml
4. 写入 ~/.codex/orchestrator.json
5. 把该 agent 设为默认 worker

切换 worker

# 交互式：列出已有的 agent.toml 供选择
orchestrator-skill set-agent

# 或直接指定名字
orchestrator-skill set-agent deepseek-pro

orchestrator-skill check

不带参数运行 set-agent 会列出 ~/.codex/agents/ 下已有的 *.toml 供选择；它只写入配置，不创建文件。如果没有任何已有 agent，会询问是否用 init-agent 从你的 config.toml 新建。

配置

~/.codex/orchestrator.json

{
  "default_agent": "deepseek-flash"
}

skill 激活时，主 agent 会读取这个文件，并把 default_agent 作为 spawn_agent 的 agent_type。

~/.codex/agents/<name>.toml

worker 配置示例：

name = "my-agent"
description = "Codex worker using my model."
developer_instructions = """
You are a Codex subagent.
"""
model = "my-model"
model_provider = "my-provider"
model_context_window = 1000000

model_reasoning_effort 是可选字段。为避免某些 provider 不支持指定的思考强度而报错，init-agent 生成时不再强制写入该字段，让 provider 使用自己的默认值。建议使用 orchestrator-skill init-agent 生成，不要手动复制占位模板。

使用

在 Codex prompt 中加入触发词：

用司令模式帮我重构这个项目的登录模块

或：

use orchestrator to refactor the login module

激活后，主 agent 会：

1. 首次激活时完整读取一次 SKILL.md，确保所有规则生效
2. 只读取一次 ~/.codex/orchestrator.json，确认默认 worker
3. 检查 ~/.codex/agents/<默认 worker>.toml 是否存在
4. 直接派出 subagent，后续不再重复展开说明
5. 独立任务并行，依赖任务顺序执行
6. 审查结果、合并并汇报

如果主 agent 对规则不确定，允许重新读取 SKILL.md 对应章节，避免错误调用。

完整命令

| 命令 | 作用 | | --- | --- | | orchestrator-skill install | 安装/更新 skill 和规则 | | orchestrator-skill check | 校验安装状态 | | orchestrator-skill init-agent [model] | 从 config.toml 选择并生成 worker | | orchestrator-skill set-agent [name] | 交互式切换默认 worker（也支持直接指定名字） |

工作流说明

主 agent 负责

• 任务拆分
• 任务派发
• 结果合并
• 关键决策
• diff 审查
• 最终验收
• 用户沟通

subagent 负责

• 大文件 / 多文件读取
• 代码搜索
• 批量替换
• 文件编辑
• 测试 / 构建 / 长命令执行
• 文档和长文本提取

委派规则

• 独立任务并行派发
• 依赖任务顺序派发
• 每个任务必须自包含：目标、文件范围、允许写入文件、交付格式、禁止事项
• subagent 禁止再派生 subagent
• 小到一两行的琐碎读写可由主 agent 自己完成

常见问题

我的模型不在内置列表里

没有固定列表。init-agent 会读取你的 config.toml，你的模型只要在其中就可以生成 worker。

已有 agent.toml 会不会被覆盖

不会。安装和切换只会在文件缺失时提示你生成，不会覆盖已有配置。

只装了 npm 包，没有手动复制 skill

npm 的 postinstall 会自动把 skill 写入 ~/.codex/skills/orchestrator。

提示 agent.toml is missing

运行：

orchestrator-skill init-agent

触发词不生效

新安装的 skill 可能需要在新的 Codex 会话中才会被加载。

目录结构

orchestrator/
├── SKILL.md
├── README.md
├── orchestrator.rules
├── install.sh
├── check.sh
├── install.ps1
├── check.ps1
├── agents/
│   └── agent.toml.example
└── pkg/
    ├── package.json
    ├── install.js
    ├── README.md
    └── skill/

License

MIT