MiniCode多智能体编排:3个只读子Agent并行干活,Root Agent把住所有代码
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 都拥有:
- 独立的消息数组(与 Root Agent 上下文完全隔离)
- 独立的
AbortController(可随时取消正在进行的模型请求) - 后台 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双重兜底
相关源码路径,供延伸阅读:
- 生命周期管理:src/agents/manager.ts
- 常量与状态类型:src/agents/types.ts
- 只读 worker 提示词:src/agents/worker-prompt.ts
- 4 个编排工具:src/tools/sub-agents.ts
- 只读工具白名单:src/tools/index.ts
- Root Agent 协调规则:src/prompt.ts
- 架构总览(Multi-agent MVP):ARCHITECTURE_ZH.md
当前 MVP 暂不持久化 worker、不允许嵌套 Agent、不读取自定义 agent 定义,这样能把教学重点完整聚焦在上述四个核心概念上。
小结:MiniCode 用"1 个能写的 Root Agent + 最多 3 个只读子 Agent"的极简组合,把多智能体编排讲得又轻又透——并行调研交给后台 worker,写代码的权柄始终牢牢握在 Root Agent 手里。