Codex Subagents Simple

1) 首次安装依赖

npm --prefix .agents/skills/codex-subagents-simple install

2) 运行并行 subagents

npm --prefix .agents/skills/codex-subagents-simple run subagents -- \
  --spec /abs/path/to/subagents-spec.json \
  --workspace-root /abs/path/to/workspace

3) 控制模型与并发度

npm --prefix .agents/skills/codex-subagents-simple run subagents -- \
  --spec /abs/path/to/subagents-spec.json \
  --workspace-root /abs/path/to/workspace \
  --model gpt-5.4 \
  --reasoning-effort high \
  --max-parallel 3

4) 保留 subagent 上下文

默认会把 subagent name + spec path 对应的 threadId 写到：

.agent_cache/codex-subagents-simple/thread-registry.json

下一次运行同一个 spec 时，会自动 resumeThread(...)，让每个 subagent 继续自己的线程上下文。

如果你想强制忽略旧线程，使用：

npm --prefix .agents/skills/codex-subagents-simple run subagents -- \
  --spec /abs/path/to/subagents-spec.json \
  --workspace-root /abs/path/to/workspace \
  --fresh

5) 实时观察 subagent 工作上下文

运行时会在每个 runDir 下写：

• agents/<name>.status.json
• agents/<name>.events.jsonl
• run.json

可以实时观察最近一次 run：

npm --prefix .agents/skills/codex-subagents-simple run watch

也可以指定某个 runDir：

npm --prefix .agents/skills/codex-subagents-simple run watch -- \
  --run-dir /abs/path/to/run-dir

Spec 结构

{
  "task": "修复 reverse/java21-baseline 的一组问题",
  "acceptanceCriteria": [
    "相关模块完成修改",
    "每个 subagent 都返回改动、检查和风险"
  ],
  "sharedContextFiles": [
    "README.md",
    "reverse/java21-baseline/README.md"
  ],
  "subagents": [
    {
      "name": "entry-chain",
      "mission": "修复入口链和启动流程",
      "ownedPaths": [
        "reverse/java21-baseline/src/manual/GameMIDlet.java",
        "reverse/java21-baseline/src/manual/ba.java"
      ],
      "readFiles": [
        "reverse/java21-baseline/src/generated-all/GameMIDlet.java",
        "reverse/java21-baseline/src/generated-all/ba.java"
      ],
      "extraInstructions": [
        "优先保留现有模块边界",
        "先跑最小编译检查再结束"
      ]
    }
  ]
}

输出

• 默认输出到 .agent_cache/codex-subagents-simple/<timestamp>-<slug>/
• spec.normalized.json: 标准化后的执行 spec
• run.json: 本次 run 的元信息与整体状态
• agents/<name>.status.json: subagent 当前状态快照
• agents/<name>.events.jsonl: subagent 流式事件日志
• agents/<name>.json: 每个 subagent 的结构化结果
• summary.md: 汇总结果

质量门禁

首次运行前，建议先执行：

python3 .agents/skills/typescript-quality-gate/scripts/typescript_gate.py \
  --module .agents/skills/codex-subagents-simple \
  --install