MiniCode多智能体编排:3个只读子Agent并行干活,Root Agent把住所有代码

原创2026-10-14 09:01:302,150 阅读
文章标签:人工智能AI Agent代码智能体工具调用MCP ClientsCLI开发工具AI 技能

MiniCode多智能体编排:3个只读子Agent并行干活,Root Agent把住所有代码

MiniCode 是一个轻量级终端编码助手,内置一套可直接观察的多智能体(multi-agent)编排机制:Root Agent 作为唯一写代码的角色,最多同时派 3 个只读子 Agent 并行调研。本文带你读懂它的分工、并行上限与安全边界,适合想入门 AI 编程 Agent 的同学。

一句话看懂 MiniCode 的多智能体设计

把整个流程想象成一次"分头侦查":

  • Root Agent(主脑):接收你的需求,拆解任务,负责所有真正的代码修改与命令执行。
  • 只读子 Agent(侦查员):并行处理互相独立的调研任务,只读文件、检索信息,产出报告,绝不改代码。

这种"独立上下文 + 受限工具集 + 后台 Promise + 生命周期控制"的组合,是理解 MiniCode 多智能体架构的四个核心概念,完整描述见 ARCHITECTURE_ZH.md 的 Multi-agent MVP 一节。

💡 关键约束:同时最多 3 个 running 子 Agent,超过就会报错拦截。

3 个子 Agent 如何并行干活

MiniCode 在 src/agents/types.ts 里用两个常量钉死了边界:

export const MAX_SUB_AGENTS = 3
export const MAX_SUB_AGENT_STEPS = 20
  • MAX_SUB_AGENTS = 3:并发上限,保证资源可控。
  • MAX_SUB_AGENT_STEPS = 20:每个子 Agent 最多执行 20 个工具/模型步骤,防止无限空转。

当 Root Agent 调用 spawn_agent 时,SubAgentManager 会先检查 runningCount 是否已到达上限,一旦超过立即抛出错误并终止:

`At most ${this.maxConcurrent} sub-agents may run at the same time`

每个被拉起的子 Agent 都拥有:

  1. 独立的消息数组(与 Root Agent 上下文完全隔离)
  2. 独立的 AbortController(可随时取消正在进行的模型请求)
  3. 后台 Promise(不阻塞主回合,主 TUI 仍保持单前台交互节奏)

这套生命周期管理集中在 src/agents/manager.ts 的 SubAgentManager 类中,spawn / wait / close / closeAll 四个方法覆盖了创建、等待、关闭的完整闭环。

Root Agent 如何把住所有代码

这是整套设计里最妙的一笔——只读保障是"硬编码"的,而非靠提示词自觉。

第一道锁:工具白名单

在 src/tools/index.ts 中,子 Agent 能拿到的工具被显式限制为 6 个只读工具:

export const SUB_AGENT_TOOL_NAMES = [
  'list_files',
  'grep_files',
  'read_file',
  'load_skill',
  'web_fetch',
  'web_search',
]

注意:没有 write_file、edit_file、patch_file、run_command。子 Agent 物理上就拿不到写文件与执行命令的能力。

第二道锁:系统提示词兜底

buildSubAgentPrompt 生成的系统提示词进一步在语义层面强化角色:

  • "You are a read-only sub-agent helping the root coding agent."
  • "You cannot modify files, run commands, ask the user questions, or create other agents."
  • "Do not claim to have changed code. The root agent is the only agent allowed to make edits."

同时,Root Agent 自身的系统提示词在 src/prompt.ts 里被明确告知:"You are the root agent and the only agent allowed to edit files or run commands that change the project." 双端约定,边界清晰。

Root Agent 手里的 4 个编排工具

Root Agent 通过 src/tools/sub-agents.ts 暴露的 4 个工具来调度子 Agent,形成一个完整控制回路:

工具 作用 典型场景
spawn_agent 拉起一个只读子 Agent 处理独立调研任务 分头查找不同模块
list_agents 列出所有子 Agent 及当前状态 巡检进度
wait_agent 等待指定子 Agent 结束并回收报告 汇总结果
close_agent 关闭某个运行中的子 Agent 发现它空转/不再需要

wait_agent 默认等待 30 秒,超时则返回最新状态而不关闭 Agent,最大可设到 120 秒。close_agent 会取消正在进行的模型请求,并阻止子 Agent 进入下一步骤,避免继续消耗模型调用。

一个典型的并行编排时序

spawn_agent(任务A)  → agent_1 running
spawn_agent(任务B)  → agent_2 running
spawn_agent(任务C)  → agent_3 running
wait_agent([1,2,3]) → 收集三份报告
close_agent(剩余)    → 收尾,确保无遗留 worker

在终端里看到子 Agent 在跑

子 Agent 运行时,MiniCode 的 TUI 底栏会显示醒目的状态提示(实现位于 src/tty-app.ts 的 renderSubAgentFooter):

● SUB-AGENTS 2/3 RUNNING

一眼就能知道当前有几个 worker 在后台干活、距离 3 个并发上限还剩多少余量,无需打断主回合。

这套设计值得学什么

MiniCode 故意把多智能体实现成一个"可读的最小闭环",非常适合用来学习:

  • 🧭 上下文隔离:每个 worker 独立消息数组,互不污染
  • 🔒 工具隔离:白名单硬编码只读能力,不依赖提示词自觉
  • ⏱️ 生命周期控制:AbortController 可随时取消进行中的模型请求
  • 📊 并发与步数上限:MAX_SUB_AGENTS = 3、MAX_SUB_AGENT_STEPS = 20 双重兜底

相关源码路径,供延伸阅读:

当前 MVP 暂不持久化 worker、不允许嵌套 Agent、不读取自定义 agent 定义,这样能把教学重点完整聚焦在上述四个核心概念上。

小结:MiniCode 用"1 个能写的 Root Agent + 最多 3 个只读子 Agent"的极简组合,把多智能体编排讲得又轻又透——并行调研交给后台 worker,写代码的权柄始终牢牢握在 Root Agent 手里。

登录后查看全文
MiniCode