# MAX_PARALLEL_SUB_AGENTS 限制一轮里最多同时跑几个 sub_agent。每一个都会
# 起自己的一整套 provider 连接和多轮对话，扇出多大都不设上限，就是在
# 拿本地资源和 provider 的并发限额去赌。这个数字没有理论最优解，纯粹是
# 部署环境的取舍——本书的玩具 harness 是单机跑，4 只是"够看出并发效果，
# 又不至于把本机或 provider 打满"的一个保守选择。
MAX_PARALLEL_SUB_AGENTS = 4


# can_fan_out 判断这一轮工具调用能不能并发跑。判据故意收得很紧：调用数
# 大于一个，且全部是 sub_agent——不是"只读工具都能并发"这种更通用的
# 规则。原因是这本书至今没有给任何工具标注过"只读"，bash/write_file/
# edit_file 都会改共享状态（cwd、trash、registry 的 has_read 记账），
# 混在一起并发执行没人能担保顺序和结果；sub_agent 不一样——它起的是
# 一整个独立的子 agent，自己的 history、自己的 child_reg，跟父 agent
# 的注册表没有任何写共享。这份安全保证只覆盖 history/registry 这层
# 状态——子 agent 内部如果自己调用了需要人工确认的 bash 命令，confirm()
# 读的是同一个共享 stdin，多个线程同时问会互相冲撞，见这一章"常见问题"
# 里的实测记录，这份判据没有、也不打算解决这个问题。
def can_fan_out(calls):
    if len(calls) < 2:
        return False
    return all(tc["function"]["name"] == "sub_agent" for tc in calls)

再加实际分发这一批调用的函数。Python 没有 goroutine，但这里的每一次 sub_agent 调用本质上是“发 HTTP 请求、等回包“，等待期间会释放 GIL， 多个线程真的能并发地在等待网络——用 threading 而不是 asyncio，是 因为 send() built 在阻塞的 urllib 之上，不用把整个工具层重写成 协程也能拿到同样的效果：

# dispatch_tool_calls 跑完一轮里的全部工具调用，按原始顺序整理成待追加
# 的 tool 消息。can_fan_out 为真时用一个容量 MAX_PARALLEL_SUB_AGENTS 的
# threading.Semaphore 当限流阀：每个线程先占一个坑位再执行，执行完释放，
# 坑位不够的调用在 sem.acquire() 这一行排队——跟 Go 版"channel 当信号量"
# 是同一个道理，只是换成了标准库的 Semaphore。结果按下标写回一个和
# calls 等长的列表，保证 tool 消息和原始 tool_calls 一一对应。不能并发
# 的这一轮（只有一个调用，或混了 bash/write 这类工具）走原来那条串行
# 路径，行为跟练习 19 完全一样。
def dispatch_tool_calls(reg, round_no, calls):
    results = [None] * len(calls)
    if can_fan_out(calls):
        sem = threading.Semaphore(MAX_PARALLEL_SUB_AGENTS)
        log_lock = threading.Lock()
        threads = []
        for i, tc in enumerate(calls):
            sem.acquire()  # 占坑位；坑位不够就阻塞在这一行排队

            def worker(i=i, tc=tc):
                try:
                    with log_lock:
                        print(f"[round {round_no}] {tc['function']['name']}({tc['function']['arguments']})",
                              file=sys.stderr)
                    results[i] = reg.execute(tc["function"]["name"], tc["function"]["arguments"])
                finally:
                    sem.release()  # 让出坑位给下一个排队的调用

            t = threading.Thread(target=worker)
            threads.append(t)
            t.start()
        for t in threads:
            t.join()
    else:
        for i, tc in enumerate(calls):
            print(f"[round {round_no}] {tc['function']['name']}({tc['function']['arguments']})", file=sys.stderr)
            results[i] = reg.execute(tc["function"]["name"], tc["function"]["arguments"])
    return [{"role": "tool", "tool_call_id": tc["id"], "content": results[i]} for i, tc in enumerate(calls)]

main() 里原来那段“一个个 execute、一个个 append“的循环，换成两行：

    tool_calls = msg.get("tool_calls") or []
    if can_fan_out(tool_calls):
        print(f"[round {round_no} 并发扇出：{len(tool_calls)} 个 sub_agent，"
              f"上限 {MAX_PARALLEL_SUB_AGENTS} 个坑位]", file=sys.stderr)
    sess.history.extend(dispatch_tool_calls(reg, round_no, tool_calls))

别忘了在文件头加一行 import threading。

// MAX_PARALLEL_SUB_AGENTS 限制一轮里最多同时跑几个 sub_agent。每一个都会
// 起自己的一整套 provider 连接和多轮对话，扇出多大都不设上限，就是在
// 拿本地资源和 provider 的并发限额去赌。这个数字没有理论最优解，纯粹是
// 部署环境的取舍——本书的玩具 harness 是单机跑，4 只是"够看出并发效果，
// 又不至于把本机或 provider 打满"的一个保守选择。
const MAX_PARALLEL_SUB_AGENTS = 4;

// canFanOut 判断这一轮工具调用能不能并发跑。判据故意收得很紧：调用数
// 大于一个，且全部是 sub_agent——不是"只读工具都能并发"这种更通用的
// 规则。原因是这本书至今没有给任何工具标注过"只读"，bash/write_file/
// edit_file 都会改共享状态（cwd、trash、registry 的 hasRead 记账），
// 混在一起并发执行没人能担保顺序和结果；sub_agent 不一样——它起的是
// 一整个独立的子 agent，自己的 history、自己的 childReg，跟父 agent
// 的注册表没有任何写共享。这份安全保证只覆盖 history/registry 这层
// 状态——子 agent 内部如果自己调用了需要人工确认的 bash 命令，confirm()
// 读的是同一个共享 stdin，见这一章"常见问题"里的实测记录，这份判据
// 没有、也不打算解决这个问题。
function canFanOut(calls) {
  if (calls.length < 2) return false;
  return calls.every((tc) => tc.function.name === "sub_agent");
}

再加实际分发这一批调用的函数。JavaScript 没有 goroutine，也没有真正的 多核并行——但 Node 的事件循环本身就是“单线程 + 非阻塞 I/O“：每个 sub_agent 调用大部分时间都花在 await fetch() 等网络响应上，这段 等待期间事件循环可以去处理别的任务，效果上等价于 Go 的 goroutine + channel 限流，只是并发单位从“系统线程“换成了“还没 resolve 的 Promise“：

// Semaphore 是一个最小的异步信号量：容量之内 acquire() 立刻 resolve，
// 容量耗尽时排进队列，release() 时唤醒队首等待者。
class Semaphore {
  constructor(n) {
    this.available = n;
    this.queue = [];
  }
  acquire() {
    return new Promise((resolve) => {
      if (this.available > 0) {
        this.available--;
        resolve();
      } else {
        this.queue.push(resolve); // 坑位不够，排队等 release() 唤醒
      }
    });
  }
  release() {
    const next = this.queue.shift();
    if (next) next(); // 直接把坑位转交给排队的下一个，不经过 available 计数
    else this.available++;
  }
}

// dispatchToolCalls 跑完一轮里的全部工具调用，按原始顺序整理成待追加
// 的 tool 消息。canFanOut 为真时用一个容量 MAX_PARALLEL_SUB_AGENTS 的
// Semaphore 当限流阀：每次派发前先 await acquire()——坑位不够就在这里
// 排队，跟 Go 版"sem <- struct{}{} 这一行阻塞"是同一个位置。结果按下标
// 写回一个和 calls 等长的数组，保证 tool 消息和原始 tool_calls 一一
// 对应。不能并发的这一轮（只有一个调用，或混了 bash/write 这类工具）
// 走原来那条串行路径，行为跟练习 19 完全一样。
async function dispatchToolCalls(reg, round, calls) {
  const results = new Array(calls.length);
  if (canFanOut(calls)) {
    const sem = new Semaphore(MAX_PARALLEL_SUB_AGENTS);
    const tasks = [];
    for (let i = 0; i < calls.length; i++) {
      const tc = calls[i];
      await sem.acquire(); // 占坑位；坑位不够就在这里排队
      tasks.push(
        (async () => {
          try {
            console.error(`[round ${round}] ${tc.function.name}(${tc.function.arguments})`);
            results[i] = await reg.execute(tc.function.name, tc.function.arguments);
          } finally {
            sem.release(); // 让出坑位给下一个排队的调用
          }
        })()
      );
    }
    await Promise.all(tasks);
  } else {
    for (let i = 0; i < calls.length; i++) {
      const tc = calls[i];
      console.error(`[round ${round}] ${tc.function.name}(${tc.function.arguments})`);
      results[i] = await reg.execute(tc.function.name, tc.function.arguments);
    }
  }
  return calls.map((tc, i) => ({ role: "tool", tool_call_id: tc.id, content: results[i] }));
}

顶层脚本里原来那段“一个个 execute、一个个 push“的循环，换成三行：

const toolCalls = msg.tool_calls ?? [];
if (canFanOut(toolCalls)) {
  console.error(`[round ${round} 并发扇出：${toolCalls.length} 个 sub_agent，` +
    `上限 ${MAX_PARALLEL_SUB_AGENTS} 个坑位]`);
}
sess.history.push(...(await dispatchToolCalls(reg, round, toolCalls)));

运行不用编译，跳到下一步给任务就行。

运行不用编译，跳到下一步给任务就行。

python3 main.py "我这里有三个互相独立的项目目录：projA、projB、projC，各自有一份 README.md。请分别为每一个目录派一个独立的 sub agent 去检查它的 README.md 里有没有提到 'deprecated'（废弃）相关的说明，如果有就摘要是哪个接口废弃了。这三个检查任务彼此没有依赖，请一次性同时发起这三个 sub_agent 调用，不要等上一个做完再发起下一个。"

# 同一份代码但没有并发分发的练习 19，作对照（cd 到 ex19 目录）
time python3 ../../ex19/python/main.py "……同一段任务原文……"
time python3 main.py "……同一段任务原文……"

node main.mjs "我这里有三个互相独立的项目目录：projA、projB、projC，各自有一份 README.md。请分别为每一个目录派一个独立的 sub agent 去检查它的 README.md 里有没有提到 'deprecated'（废弃）相关的说明，如果有就摘要是哪个接口废弃了。这三个检查任务彼此没有依赖，请一次性同时发起这三个 sub_agent 调用，不要等上一个做完再发起下一个。"

# 同一份代码但没有并发分发的练习 19，作对照
time node ../../ex19/node/main.mjs "……同一段任务原文……"
time node main.mjs "……同一段任务原文……"

python3 main.py "我这里有三个互相独立的项目目录：projA、projB、projC，各自有一份 README.md。请分别为每一个目录派一个独立的 sub agent，要求每个 sub agent 都必须用 bash 的 grep 命令（例如 grep -i deprecated projX/README.md）去检查有没有提到 'deprecated'，不要用 read_file。这三个任务彼此没有依赖，请一次性同时发起这三个 sub_agent 调用。"

node main.mjs "我这里有三个互相独立的项目目录：projA、projB、projC，各自有一份 README.md。请分别为每一个目录派一个独立的 sub agent，要求每个 sub agent 都必须用 bash 的 grep 命令（例如 grep -i deprecated projX/README.md）去检查有没有提到 'deprecated'，不要用 read_file。这三个任务彼此没有依赖，请一次性同时发起这三个 sub_agent 调用。"