# ---- subagent 层：隔离出一个全新的对话去跑子任务 ----

# CHILD_MAX_ROUNDS 是子 agent 自己的循环预算，比父 agent 的 MAX_ROUNDS 更
# 紧——子任务应该足够聚焦，不该是另一场需要十轮才能收尾的长对话；
# 真撞上限，run_child_loop 把这当一次不完整的结果处理，不是错误。
CHILD_MAX_ROUNDS = 6


# run_child_loop 是子 agent 自己的一个迷你 agent loop：发请求、有
# tool_calls 就分发、没有就返回。故意不跟 main() 里那个大循环共用——
# 子 agent 不需要会话存盘（纯内存，这次调用完就没了）、不需要压缩
# （任务足够聚焦，轮数上限本身就比触发压缩的量级小得多）、也不需要
# resume。蒸馏自 octo 的说法：子 agent 的保活范围纯 in-memory，生命
# 周期只有一次调用，不写盘、不进 session、不跨进程。
def run_child_loop(base, api_key, model, reg, history):
    total_tokens = 0
    for _ in range(CHILD_MAX_ROUNDS):
        r = send(base, api_key, model, history, reg.definitions())
        u = r.get("usage") or {}
        total_tokens += u.get("prompt_tokens", 0) + u.get("completion_tokens", 0)
        choice = r["choices"][0]
        msg = choice["message"]
        history.append(msg)
        if choice.get("finish_reason") != "tool_calls":
            return msg.get("content") or "", total_tokens, True
        for tc in msg.get("tool_calls") or []:
            result = reg.execute(tc["function"]["name"], tc["function"]["arguments"])
            history.append({"role": "tool", "tool_call_id": tc["id"], "content": result})
    # 跑满轮数没个结论，不是异常——蒸馏自 octo 的 max-turns 处理：把最后
    # 一条内容当部分结果带回去，标记不完整，让父 agent 自己判断怎么办。
    last = history[-1]
    return last.get("content") or "", total_tokens, False

父 agent 唯一能看到的分身入口是一个新工具，防递归靠的是一个结构性 事实：它拿到的工具列表里根本没有 sub_agent 这个名字：

# SubAgentTool 是父 agent 唯一能看到的分身入口。tools 是子 agent 能用
# 的工具集——调用方负责传一份"父的工具集去掉 SubAgentTool 自己"的列表，
# 这就是防递归：子 agent 的注册表里根本没有 sub_agent 这个名字，不是
# 靠它自己克制。
class SubAgentTool:
    def __init__(self, base, api_key, model, tools, skills):
        self.base = base
        self.api_key = api_key
        self.model = model
        self.tools = tools
        self.skills = skills

    def definition(self):
        return {
            "name": "sub_agent",
            "description": (
                "派生一个隔离的子 agent 去完成一个独立子任务。子 agent 看不到这次对话到"
                "目前为止的任何内容——prompt 必须自包含，把它需要知道的一切都写进去。你只会拿到"
                "子 agent 最后的结论，它中途调用了哪些工具、读了哪些文件，都不会进入你的上下文。"
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "description": {"type": "string", "description": "这个子任务的一句话标签，仅用于日志"},
                    "prompt": {"type": "string", "description": "子任务的完整描述，自包含——子 agent 看不到别的上下文"},
                },
                "required": ["description", "prompt"],
            },
        }

    def execute(self, args):
        try:
            in_ = json.loads(args) or {}
        except json.JSONDecodeError as e:
            return "错误: 参数不是合法 JSON: " + str(e)
        description = in_.get("description", "")
        prompt = in_.get("prompt", "")
        if not prompt.strip():
            return "错误: prompt 不能为空——子 agent 看不到别的上下文，全靠这一份"
        child_reg = Registry(*self.tools)
        child_history = [
            {"role": "system", "content": compose_system_prompt(self.skills)},
            {"role": "user", "content": prompt},
        ]
        try:
            reply, tokens, complete = run_child_loop(self.base, self.api_key, self.model, child_reg, child_history)
        except Exception as e:
            return "错误: 子 agent 执行失败: " + str(e)
        tag = "" if complete else "[未完成：达到轮数上限，以下是部分结果]\n\n"
        print(f"[子 agent {description!r} 结束：内部消耗约 {tokens} tokens，"
              f"父对话只收到下面这条回复，约 {estimate_text(reply)} tokens]", file=sys.stderr)
        return tag + reply

接进 main()——SubAgentTool 拿到的工具列表，是加它自己之前的那份 快照：

    # SubAgentTool 拿到的是此刻的 tools——不含它自己，因为这一行还
    # 没把它加进去。子 agent 的注册表由这份列表构造，天生没有 sub_agent
    # 这个名字，递归在结构上就不成立，不是靠模型自觉不去调用它。
    sub_agent = SubAgentTool(base, api_key, model, list(tools), skills)
    tools.append(sub_agent)
    reg = Registry(*tools)

// ---- subagent 层：隔离出一个全新的对话去跑子任务 ----

// CHILD_MAX_ROUNDS 是子 agent 自己的循环预算，比父 agent 的 maxRounds 更
// 紧——子任务应该足够聚焦，不该是另一场需要十轮才能收尾的长对话；
// 真撞上限，runChildLoop 把这当一次不完整的结果处理，不是错误。
const CHILD_MAX_ROUNDS = 6;

// runChildLoop 是子 agent 自己的一个迷你 agent loop：发请求、有
// tool_calls 就分发、没有就返回。故意不跟顶层那个大循环共用——
// 子 agent 不需要会话存盘（纯内存，这次调用完就没了）、不需要压缩
// （任务足够聚焦，轮数上限本身就比触发压缩的量级小得多）、也不需要
// resume。蒸馏自 octo 的说法：子 agent 的保活范围纯 in-memory，生命
// 周期只有一次调用，不写盘、不进 session、不跨进程。
async function runChildLoop(base, apiKey, model, reg, history) {
  let totalTokens = 0;
  for (let round = 1; round <= CHILD_MAX_ROUNDS; round++) {
    const r = await send(base, apiKey, model, history, reg.definitions());
    totalTokens += (r.usage?.prompt_tokens ?? 0) + (r.usage?.completion_tokens ?? 0);
    const choice = r.choices[0];
    const msg = choice.message;
    history.push(msg);
    if (choice.finish_reason !== "tool_calls") {
      return [msg.content ?? "", totalTokens, true];
    }
    for (const tc of msg.tool_calls ?? []) {
      const result = await reg.execute(tc.function.name, tc.function.arguments);
      history.push({ role: "tool", tool_call_id: tc.id, content: result });
    }
  }
  // 跑满轮数没个结论，不是异常——蒸馏自 octo 的 max-turns 处理：把最后
  // 一条内容当部分结果带回去，标记不完整，让父 agent 自己判断怎么办。
  const last = history[history.length - 1];
  return [last.content ?? "", totalTokens, false];
}

父 agent 唯一能看到的分身入口是一个新工具，防递归靠的是一个结构性 事实：它拿到的工具列表里根本没有 sub_agent 这个名字：

// SubAgentTool 是父 agent 唯一能看到的分身入口。tools 是子 agent 能用
// 的工具集——调用方负责传一份"父的工具集去掉 SubAgentTool 自己"的列表，
// 这就是防递归：子 agent 的注册表里根本没有 sub_agent 这个名字，不是
// 靠它自己克制。
class SubAgentTool {
  constructor(base, apiKey, model, tools, skills) {
    this.base = base;
    this.apiKey = apiKey;
    this.model = model;
    this.tools = tools;
    this.skills = skills;
  }

  definition() {
    return {
      name: "sub_agent",
      description:
        "派生一个隔离的子 agent 去完成一个独立子任务。子 agent 看不到这次对话到" +
        "目前为止的任何内容——prompt 必须自包含，把它需要知道的一切都写进去。你只会拿到" +
        "子 agent 最后的结论，它中途调用了哪些工具、读了哪些文件，都不会进入你的上下文。",
      parameters: {
        type: "object",
        properties: {
          description: { type: "string", description: "这个子任务的一句话标签，仅用于日志" },
          prompt: { type: "string", description: "子任务的完整描述，自包含——子 agent 看不到别的上下文" },
        },
        required: ["description", "prompt"],
      },
    };
  }

  async execute(args) {
    let inArgs;
    try {
      inArgs = JSON.parse(args) ?? {};
    } catch (err) {
      return "错误: 参数不是合法 JSON: " + err.message;
    }
    const description = inArgs.description ?? "";
    const prompt = inArgs.prompt ?? "";
    if (!prompt.trim()) {
      return "错误: prompt 不能为空——子 agent 看不到别的上下文，全靠这一份";
    }
    const childReg = new Registry(...this.tools);
    const childHistory = [
      { role: "system", content: composeSystemPrompt(this.skills) },
      { role: "user", content: prompt },
    ];
    let reply, tokens, complete;
    try {
      [reply, tokens, complete] = await runChildLoop(this.base, this.apiKey, this.model, childReg, childHistory);
    } catch (err) {
      return "错误: 子 agent 执行失败: " + (err.message ?? err);
    }
    const tag = complete ? "" : "[未完成：达到轮数上限，以下是部分结果]\n\n";
    console.error(`[子 agent "${description}" 结束：内部消耗约 ${tokens} tokens，` +
      `父对话只收到下面这条回复，约 ${estimateText(reply)} tokens]`);
    return tag + reply;
  }
}

接进顶层脚本——SubAgentTool 拿到的工具列表，是加它自己之前的那份 快照。JavaScript 这一章还多一处改动：sub_agent 的 execute 要发 网络请求，是异步的，注册表原来那层同步的查表分发也要跟着改成 async，调用点补一个 await：

// SubAgentTool 拿到的是此刻的 toolList——不含它自己，因为这一行还
// 没把它加进去。子 agent 的注册表由这份数组构造，天生没有 sub_agent
// 这个名字，递归在结构上就不成立，不是靠模型自觉不去调用它。
const subAgent = new SubAgentTool(base, apiKey, model, [...toolList], skills);
toolList.push(subAgent);
const reg = new Registry(...toolList);

  // sub_agent 的 execute 是异步的（内部要发网络请求），所以这层查表分发
  // 也跟着是 async——其余工具的 execute 都是同步返回一个字符串，await
  // 一个非 Promise 值本来就是安全的，不用为它们单独分叉一条同步路径。
  async execute(name, args) {
    const t = this.tools.get(name);
    if (!t) return "错误: 未知工具 " + name;
    // ……原有的 read-before-write / bash 权限检查不变……
    const result = await t.execute(args);
    // ……原有的记账逻辑不变……
    return result;
  }

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

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

python3 main.py "我们在整理旧笔记，规则是：只挑出提到 'signing' 这个词的笔记，把它的内容摘要成一句话给我；不提这个词的笔记不用管，也不用告诉我它们讲了什么。派一个 sub agent 去 notes/ 目录下看看三份笔记，按这个规则处理。"

node main.mjs "我们在整理旧笔记，规则是：只挑出提到 'signing' 这个词的笔记，把它的内容摘要成一句话给我；不提这个词的笔记不用管，也不用告诉我它们讲了什么。派一个 sub agent 去 notes/ 目录下看看三份笔记，按这个规则处理。"

python3 main.py "我们这个项目的写作风格要求是：全文所有比喻只能用一次，不能对同一个概念重复使用同一个比喻。记住这条规则，后面我会让你检查文档是否符合。"

# 全新会话，不带 -c，这次任务里没有一个字提到"比喻"或那条规则
python3 main.py "麻烦你派一个 sub agent 去检查一下 draft.md 是否符合我们项目的写作风格要求，告诉我具体哪句话违反了。"

node main.mjs "我们这个项目的写作风格要求是：全文所有比喻只能用一次，不能对同一个概念重复使用同一个比喻。记住这条规则，后面我会让你检查文档是否符合。"

# 全新会话，不带 -c，这次任务里没有一个字提到"比喻"或那条规则
node main.mjs "麻烦你派一个 sub agent 去检查一下 draft.md 是否符合我们项目的写作风格要求，告诉我具体哪句话违反了。"