AI导哈

子代理委托工具

一个本地MCP服务器，用于管理和协调Codex CLI的子代理运行，支持并行化和专业化任务处理，并生成持久的调试工件。

  • by leonardsellem
  • TypeScript
  • 本地部署
  • 69 星标
  • 更新于
在 GitHub 查看 leonardsellem/codex-specialized-subagents

使用说明

codex专业子代理

Codex CLI（MCP服务器）的工件首个子代理委托。

此仓库提供了一个本地（stdio）MCP服务器，它公开了：

  • delegate_autopilot --决定是否委派，如果是，则编排一个或多个 codex exec 子代理运行
  • delegate_run --通过以下方式运行单个专业子代理 codex exec
  • delegate_resume --通过以下方式恢复之前的子代理线程 codex exec resume

每个工具调用都会在下写入一个运行目录 ${CODEX_HOME:-$HOME/.codex}/delegator/runs/<run_id>/ 包含提示、选定技能、事件流和结构化结果（工件优先调试）。

何时使用

  • 您希望多步骤/跨领域工作具有并行性和专业性。
  • 您需要持久的工件（日志+输出）来调试和查看发生的事情。

需求

  • Node.js >=20 （参见 package.json#engines)
  • npm
  • mise （推荐）：从以下位置安装固定运行时 mise.toml
  • codex PATH上的CLI并经过身份验证（真实委派运行所需）

可选：

  • Python 3（仅适用于以下辅助脚本 .agent/)

安装并快速启动（从源代码）

从repo根目录（安装deps+构建 dist/):

# Recommended: install the pinned runtime (see mise.toml)
mise install

# Drift check (lockfiles + pins)
./toolchain-check.sh

# Install deps from lockfile
npm ci

# Build
npm run build

配置Codex（推荐，防止超时）

委托运行可能需要几分钟。在Codex配置中将此服务器的MCP工具超时设置为1200秒（20分钟）($HOME/.codex/config.toml):

mkdir -p "$HOME/.codex"
cat >> "$HOME/.codex/config.toml" <<'EOF'

[mcp_servers.codex-specialized-subagents]
tool_timeout_sec = 1200
EOF

如果你已经有了 [mcp_servers.codex-specialized-subagents] 部分，编辑现有 tool_timeout_sec 而不是附加副本。

常见问题： tool_timeout_sec 是 不 如果你把它放在下面 mcp_servers.codex-specialized-subagents.env.*，Codex将出现“预期字符串”错误（环境值必须是字符串）。

如果您看到关于“重复密钥”的TOML解析错误 [mcp_servers.codex-specialized-subagents]，您已经声明了该表两次——只保留一个标头并放入 tool_timeout_sec = 1200 里面。

在Codex注册（推荐默认值）

从仓库根目录（包括每个作业的推理工作覆盖 delegate_autopilot):

codex mcp add codex-specialized-subagents \
  --env CODEX_AUTOPILOT_REASONING_EFFORT_LOW=low \
  --env CODEX_AUTOPILOT_REASONING_EFFORT_MEDIUM=medium \
  --env CODEX_AUTOPILOT_REASONING_EFFORT_HIGH=high \
  -- node "$(pwd)/dist/cli.js"

验证：

codex mcp get codex-specialized-subagents

删除：

codex mcp remove codex-specialized-subagents

用法

交互式自动驾驶仪（推荐）

在Codex交互模式下， delegate_autopilot 可以将请求拆分为作业（扫描/实施/验证）并运行专业子代理。

要使委派在交互模式下感觉自动，请安装附带的 delegation-autopilot 全球技能：

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/delegation-autopilot"
cp .codex/skills/delegation-autopilot/SKILL.md \
  "${CODEX_HOME:-$HOME/.codex}/skills/delegation-autopilot/SKILL.md"

然后尝试以下提示：

  • “重构MCP服务器并更新测试+README。”
  • “审核回购文档并提出改进建议。”

可选： delegate_autopilot 为每个作业分配一个 thinking_level (low | medium | high).您可以设置 CODEX_AUTOPILOT_REASONING_EFFORT_LOW|MEDIUM|HIGH 在MCP服务器进程上覆盖Codex model_reasoning_effort 每份工作（见 docs/usage.md).（传统/高级： CODEX_AUTOPILOT_MODEL_LOW|MEDIUM|HIGH 覆盖模型名称。)

手动工具调用

如果您更喜欢显式使用工具，请告诉Codex调用以下工具之一：

  • delegate_autopilot （多代理编排）
  • delegate_run （单个子代理运行）
  • delegate_resume （继续前面的子代理线程）

可选（高级）：用于 delegate_run / delegate_resume，你可以通过 reasoning_effort （地图到 codex exec -c model_reasoning_effort="...")或生的 config_overrides （地图到 codex exec -c <override>).如果要手动运行的默认值，请设置 CODEX_DELEGATE_REASONING_EFFORT 在MCP服务器进程上（仅适用于以下情况 reasoning_effort 省略并且 config_overrides 尚未设置 model_reasoning_effort).

技能

子代理运行可以从以下位置加载Codex技能：

  • 回购本地 .codex/skills （被委托人的最近祖先 cwd)
  • 全球 ${CODEX_HOME:-$HOME/.codex}/skills

注意：此回购 delegation-autopilot 技能已标记 delegator_exclude: true （仅限父级）以防止委托递归。

工件（运行目录）

每个工具调用都会在下写入一个运行目录 ${CODEX_HOME:-$HOME/.codex}/delegator/runs/<run_id>/.

文档

开始 docs/README.md （索引），则：

  • docs/usage.md --如何有效地使用工具
  • docs/troubleshooting.md --常见故障模式（超时、丢失 codex等等）
  • docs/development.md --本地开发和测试矩阵
  • docs/reference/tools.md --全工具模式（输入/输出）
  • docs/reference/run-directories.md --运行目录布局和工件含义

发展

npm test
npm run lint
npm run dev

集成测试（需要Codex CLI+身份验证）：

RUN_CODEX_INTEGRATION_TESTS=1 npm test

贡献： CONTRIBUTING.md.

安全

  • 不要泄露秘密(.env 被忽视；使用 .env.example 作为模板）。
  • 运行目录可以包含敏感的提示/输出；对待 ${CODEX_HOME:-$HOME/.codex}/delegator/runs 敏感。

报告： SECURITY.md.

许可证

麻省理工学院

相关 MCP