在用大模型（LLM）处理复杂工程任务时，很多人都会撞上一堵"叹息之墙"------上下文长度溢出与注意力涣散。
想象一个极其高频的场景：你让 AI 帮你扫描一个包含数十个 Java 文件的代码库，排查空指针（NPE）风险。如果是传统的"单体 Agent"模式，它会先 ls 查看文件，然后逐个 cat 读取并分析。几十个文件看下来，中间所有的源码内容、思考过程全堆积在同一个对话上下文里。结果往往是：Token 瞬间爆掉，或者模型"失忆"，忘了最开始的任务目标。
这就好比让项目经理亲自去工地搬砖------能干，但每次弯腰捡砖头都占用了他的核心注意力带宽。更致命的是，搬完这块砖才能搬下一块，中间产出极低。
真正的解法，是走向 Multi-Agent（多智能体）协作：让主 Agent 作为一个调度者，把脏活累活"委托"给在独立沙盒中运行的子 Agent。今天，我们就来深度拆解这套架构的核心设计，以及在落地过程中我们踩过的那些血泪坑。
一、 核心架构：把 Agent 抽象为"纯函数"
Multi-Agent 的核心思路是将任务委托并隔离。
当主 Agent 收到扫描目录的指令时，它调用 AgentTool.execute() 触发一个子 Agent。子 Agent 在一个全新的、干净的上下文沙盒中开启自己的 ReAct（Think-Act-Observe）循环，独立完成读取和分析。任务结束后，子 Agent 仅返回一段包含最终结论的 String，随后被 GC（垃圾回收）销毁。
支撑这套流程的，是四个核心设计决策：
| 设计理念 | 核心原理解析 |
|---|---|
| 零上下文继承 | 子 Agent 绝不继承主 Agent 的历史对话，它只接收一份干练的任务描述，保持极高的"信噪比"。 |
| ReAct 自循环 | 子 Agent 内部维护独立的思考与执行闭环，无需主 Agent 逐帧微操。 |
| 显式结束标记 | 强制要求子 Agent 在任务末尾输出 [TASK_COMPLETE]，让模型自己声明完工，摒弃不可靠的猜测机制。 |
| 结果坍缩 | 子 Agent 的全生命周期被封装为一个返回 String 的方法，中间数万 Token 的废话随栈帧灰飞烟灭，绝不污染主干。 |
二、 极简核心代码拆解
2.1 AgentTool 入口与深度控制
让 Agent 调用 Agent，最怕的就是无限递归（子生孙，孙生子）。我们通过 ThreadLocal 配合 try-finally 实现了严密的深度控制。
Java
public class AgentTool extends BaseTool {
private static final int MAX_AGENT_DEPTH = 1;
// 使用 ThreadLocal 确保并发安全
private static final ThreadLocal<Integer> depthCounter = ThreadLocal.withInitial(() -> 0);
@Override
public ToolResult execute(String input) {
int depth = depthCounter.get();
if (depth >= MAX_AGENT_DEPTH) {
return ToolResult.error("你已经是子 Agent，请自己完成任务，禁止无限外包！");
}
depthCounter.set(depth + 1);
try {
return forkAndRun(input); // 核心：Fork 子进程运行
} finally {
depthCounter.set(depth); // 🔑 铁律：无论是否异常，深度标记必须还原
}
}
}这就像工地安全帽的 RFID 门禁------进门 +1，出门 -1，即使遇到异常（走消防通道）也必须刷卡退出，确保状态不被污染。
2.2 物理级隔离：子 Agent 看到的"楚门的世界"
如果子 Agent 的任务只是"分析代码"，那它就不该拥有修改代码的能力。我们不仅要口头警告它，更要在底层菜单上"阉割"它。
Java
// 在 ContextManager 构建系统提示词时：
if (isSubAgentContext()) {
// 子 Agent 看到的菜单：只能看，不能动
context.append("- 读取文件：⏺ Read(文件路径)\n");
context.append("- 列出目录：⏺ List(目录路径)\n");
} else {
// 主 Agent 的完整权限
context.append("- 读取文件：⏺ Read(文件名)\n");
context.append("- 创建文件：⏺ Write(文件名)\n");
context.append("- 执行命令：⏺ Bash(命令)\n");
context.append("- 委托子Agent：⏺ Agent(任务描述)\n");
}能力最小化原则（Principle of Least Privilege）： 这不是"有权限但被禁止用"，而是 UI 层面压根不显示。就像餐厅洗碗工登录系统，连"退单"按钮都看不到。
2.3 强制逼问：榨干最终总结
AI 模型在多轮交互中天然是"近视"的。如果它查了 10 个文件，在最后一步触发 [TASK_COMPLETE] 时，它往往只会汇报第 10 个文件的结果。
解法：追加一轮"述职汇报"。
Java
private String executeMultiRound(AgentLoop subLoop, String task, Terminal t) {
for (int i = 0; i < 15; i++) {
subLoop.processInput(nextPrompt); // 执行一轮 Think→Act→Observe
String result = extractFinalResult(subLoop.getHistory());
// 无论是检测到结束标记，还是常规迭代结束，统一进入 requestFinalSummary
if (result.contains("[TASK_COMPLETE]") || !lastRoundTriggeredTool(subLoop.getHistory())) {
return requestFinalSummary(subLoop);
}
nextPrompt = "请继续执行任务。";
}
return requestFinalSummary(subLoop);
}
private String requestFinalSummary(AgentLoop subLoop) {
// 强制逼问，榨干前置上下文
subLoop.processInput("请输出完整总结，涵盖每一步的关键发现。末尾加上 [TASK_COMPLETE]。");
return extractFinalResult(subLoop.getHistory()).replace("[TASK_COMPLETE]", "").trim();
}三、 深度排雷：那些年我们踩过的 4 个巨坑
坑 1：子 Agent 的"回声"（全局单例的幽灵）
现象： 子 Agent 的分析报告在终端打出了两次（一次流式亮青色，一次带缩进的工具结果）。
根因： 系统中的 AI Service 是全局单例（类似单一广播电台频道）。子 Agent 一出生就把全局 MessageHandler 抢了，导致内部的思考全漏到了前台。
修复（乐观覆盖策略）： 将 handler 的注册从构造函数移到 processInput() 中。主 Agent 每次发起调用时，自动夺回对讲机频道。未来若需真正的多线程并行，则必须重构为通过上下文参数传递。
坑 2：口头禁令防不住"手贱"
现象： 在 System Prompt 里写了"不要使用 Write 工具"，子 Agent 依然越权修改源码。
根因： 提示词防线太弱。
修复： 如 2.2 节所述，直接从源头动态移除工具清单。看不见，才是绝对的安全。
坑 3：安全与体验的平衡（只读操作自动放行）
为了防止子 Agent 搞破坏，所有工具调用理论上都该弹窗让用户确认。但如果它扫 50 个文件弹窗 50 次，用户会疯掉。
修复： 建立基于指令的自动放行白名单机制。
Java
private boolean isReadOnlyOperation(ToolCall toolCall) {
if ("file_manager".equals(toolCall.getToolName())) {
Object cmd = toolCall.getParameters().get("command");
return "read".equals(cmd) || "list".equals(cmd); // 只读指令绝对安全
}
return false; // bash 执行永远不进白名单
}执行时，命中白名单的 Read/List 直接静默通过；一旦触发 Write/Bash，立即挂起并弹出包含详细变更 Diff 的确认框。
坑 4：跨平台的连环绞肉机（Windows + Bash + JSON）
现象： 在 Windows 上通过 Bash 工具执行复杂命令时，路径和转义符彻底损坏。
根因： 路径（如 D:\Project）中的 \ 被传入 Bash 时被吃掉；工具参数序列化成 JSON 时又经历了一次转义。两层转义叠加 Windows 特色，直接让参数面目全非。
修复： 1. 重写 Bash 探测逻辑，涵盖 Git Bash、MSYS2 等所有可能路径。
- 针对命令执行工具（CommandExecutor），跳过 JSON 序列化，直接透传原始字符串参数，避开无意义的双重转义陷阱。
四、 架构总结：选择与妥协
构建 Multi-Agent 系统，本质上是一门"权衡的艺术"。以下是我们当前架构的决策清单：
| 维度 | 当前选择 | 架构折衷（Trade-off） |
|---|---|---|
| 隔离粒度 | 独立 AgentLoop 实例（线程/对象级隔离） | 内存开销小、启动极快；但安全性弱于真进程（Docker）隔离。 |
| 通信机制 | 纯文本 String 传入传出 | 协议简单、普适性强；但下游结构化解析依赖模型的输出稳定性。 |
| 并发模型 | 串行阻塞（主 Agent 等待子 Agent） | 逻辑可控、调试容易；但暂时牺牲了多子任务并发扇出的性能。 |
| 安全体系 | 提示词菜单隔离 + 敏感操作二次确认 | 防御纵深足够；但频繁的确认弹窗可能引发用户的"确认疲劳"。 |
| 终态收口 | 显式标记 + 强制 Final Summary 轮次 | 完美解决汇报遗漏问题；但强制多耗费了一次 API 交互的时间和 Token。 |
把 Agent 封装成一个普通的 Tool，利用 Fork → Sandbox → Collapse 的纯函数生命周期模型，这是对抗复杂性最优雅的手段。记住：Multi-Agent 的难点从来不在于堆砌酷炫的技术名词，而在于每一层防御都严丝合缝------少一层，用户的代码就可能被失控的 AI 撕成碎片。