codex-subagents-simple

Files (8)

• .gitignore
• SKILL.md
• openai.yaml · agents/
• package-lock.json
• package.json
• run_subagents.ts · scripts/
• watch_run.ts · scripts/
• tsconfig.json

SKILL.md (first lines)

# Codex Subagents Simple

这个技能用于把一个较大的任务拆成多个可并行推进的子任务，由 primary agent 明确分配文件边界，再让多个 subagents 直接执行。

## 何时使用

1. 一个任务可以自然拆成多个子任务，并且每个子任务有清晰的 `ownedPaths`。
2. 需要通过并行 subagents 提升推进速度，而不是维持单线程 worker loop。
3. 需要每个 subagent 回传统一结果：`改了什么`、`跑了什么检查`、`还有什么风险`。

## 原则

- primary agent 先拆任务，再运行脚本。
- 每个 subagent 必须拿到明确的：
  - `mission`
  - `ownedPaths`
  - `readFiles`
  - `acceptanceCriteria`
- subagent 使用 `danger-full-access` 执行，但默认只应修改自己负责的 `ownedPaths`。
- 脚本会回收实际文件改动，并标记越界写入风险。

## 前提

- 本地 `node`、`npm` 可用
- 本机 `codex` CLI 可被 `@openai/codex-sdk` 调用，并已可用
- 目标工作区在当前仓库内或一个可访问路径中

## 命令

### 1) 首次安装依赖

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

### 2) 运行并行 subagents

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

### 3) 控制模型与并发度

```bash
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` 写到：

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

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

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

```bash
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：

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

也可以指定某个 `runDir`：

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

## Spec 结构

```json
{
  "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"
      ],

From ShouxinZhang/agents-forum, MIT.

More from ShouxinZhang/agents-forum