场景:三个 Agent 同时改一个仓库,跑到一半有人失忆、有人重复劳动、有人把别人的改动覆盖掉。
结论:多 Agent 协作的瓶颈不在模型,在上下文——把探索塞进子 Agent 隔离、把状态写到外部文件、把记忆当代码版本化,三件事做好就不打架。
承诺:本文给出上下文预算参数表、一份可落地的协作骨架、三个必踩的坑,照着做能让长任务不飘。
📌 全文 6 节 · 主线:先认清上下文是有限资源,再搭隔离与记忆机制,最后用版本化兜底。
🎯 一、问题现场
一个多 Agent 改代码的任务:主 Agent 负责规划,一个子 Agent 读代码库定位问题,一个子 Agent 写测试,一个子 Agent 改文档。跑到第 20 分钟开始出问题——主 Agent 忘了最初的目标,写测试的子 Agent 重复实现了别人做过的功能,文档 Agent 把代码 Agent 刚改的接口写成了旧版。
这类问题难查在于每个 Agent 单独看都「在正常干活」,错误发生在交接处。根因是上下文窗口是有限资源:随着对话变长,模型对其中信息的使用能力会下降(称为 context rot),再多的 token 不等于更好的结果。三个 Agent 如果把读到的所有东西都往主上下文里堆,主线程很快就淹没在噪音里。
🔢 二、关键参数
| 参数 | 典型值/范围 | 影响什么 | 出处 |
|---|---|---|---|
| 上下文窗口 | 有限资源,随填充质量下降 | 长任务准确性 | [官方] 上下文工程共识 |
| 压缩触发时机 | 接近窗口上限时做 compaction | 保留决策、丢弃探索噪音 | [官方] 长任务实践 |
| 中间摘要频率 | 每 3 步写一次结构化摘要 | 避免临时抱佛脚压缩 | [推算] 工程经验 |
| 子 Agent 返回物 | 只回结论摘要,不回全量 | 保持主线程上下文干净 | [官方] 子 Agent 隔离原则 |
| 共享记忆载体 | 外部文件(如 SUMMARY.md) | 跨会话/跨重置存活 | [官方] 结构化笔记法 |
| 记忆版本化 | 每次改动 git 提交一次 diff | 可追溯、可回滚 | [官方] 上下文即代码 |
| 项目记忆文件 | CLAUDE.md / AGENTS.md | 自动加载的规范与命令 | [官方] 开放标准 |
| 检索 vs 硬塞 | 给轻量引用,按需拉取 | 上下文预算效率 | [官方] just-in-time 检索 |
怎么读这张表:这是一套「省上下文」的组合拳。子 Agent 隔离和结构化笔记是主力,压缩和 JIT 检索是辅助。最关键的是「记忆版本化」那一行——模型输出不确定,但共享记忆的每次变更是确定的,谁能改、改了什么都可查,这是长会话可靠性的真正地基。
💻 三、最小可运行实现
下面是一份多 Agent 协作的项目骨架(以通用 Agent 框架的调用序列示意,非特定产品 API,未实机验证):
<!-- AGENTS.md:每个 Agent 自动加载,把不重复的规范写在这里 -->
## 项目
嵌入式固件仓库,C + CMake。
## 命令
- 构建:cmake --build build
- 测试:ctest --test-dir build # 每次改动后必跑
## 约定
- 不要改 /generated 下的构建产物
- 数据库改动需迁移脚本,禁止手改 schema
## 记忆
- 进度写 progress.md,每次关键步骤后更新
- submodule 改动先在 SUMMARY.md 记一句再动手
# 主 Agent 的任务调度伪代码(示意)
for 子任务 in [定位问题, 写测试, 更新文档]:
result = spawn_subagent(
task=子任务,
instructions="只返回结论摘要,不要返回你读过的全部文件内容",
context=精简引用 # 给文件路径,不给全量内容
)
# 每个关键步骤后写结构化摘要到外部文件
append(progress.md, f"[{子任务}] 完成:{result.summary}")
commit(progress.md) # 记忆当代码版本化,一次改动一次提交
# 上下文接近上限时:compaction——保留决策/待办/未解问题,丢弃探索噪音
放在哪:AGENTS.md 放仓库根目录自动加载;progress.md、SUMMARY.md 作为共享记忆进版本库。怎么触发:每个子 Agent 只拿精简引用,返回摘要;主 Agent 每步写进度并提交。预期输出:主上下文始终只保留高信号信息,任何时刻新开一个 Agent 读 progress.md 就能接上进度,跑偏时 git 回滚到上一版记忆即可。
⚠️ 四、三个必踩的坑
坑 1:共享记忆不版本化,改动被覆盖无从追溯。 现象:两个 Agent 同时改 SUMMARY.md,后写的覆盖先写的,任务跑偏却查不出谁改的。原因:模型输出不确定,多人写同一文件必有冲突 [官方]。规避动作:把记忆文件纳入 git,每次改动提交一次 diff,跑偏时直接回滚到上一版,而不是从头重跑整条链路。
坑 2:子 Agent 把全量内容倒回主上下文。 现象:主 Agent 上下文迅速膨胀,几轮后开始「失忆」、重复劳动。原因:子 Agent 阅读文件后如果把全部内容返回,主线程被噪音淹没(context rot)[官方]。规避动作:明确要求子 Agent 只回紧凑摘要;探索、读文件、追引用这类脏活在子 Agent 自己的上下文里烧掉,主线程只做协调。
坑 3:等上下文快爆了才压缩。 现象:临近上限时一次性 compaction,丢掉了关键决策或遗留 bug,接不上进度。原因:临时压缩难以判断什么该留 [推算]。规避动作:每 3 步主动写一次中间摘要,把已完成的事压成几句话、原始细节归档;把缓存命中率、上下文膨胀速度当生产指标监控。
📋 五、上手核对清单
- 在仓库根目录建 AGENTS.md(或 CLAUDE.md),写清命令与约定
- 建立外部进度文件 progress.md / SUMMARY.md,并纳入版本库
- 每个子任务明确要求「只返回结论摘要」
- 主 Agent 给子 Agent 文件路径等轻量引用,而非全量内容
- 每完成一个关键步骤写一次结构化摘要并提交
- 配置压缩机制,保留决策/待办/未解问题的优先级
- 用 just-in-time 检索替代一次性全量加载
💡 六、结论与边界
结论:多 Agent 不打架的关键是把上下文当稀缺预算管理——探索隔离到子 Agent、状态落到外部文件、记忆进版本库,三者缺一不可。以上原则来自公开的上下文工程实践与多 Agent 协作经验,压缩阈值、每 3 步摘要等为工程推算值;具体频率需按任务长度和框架调整,本文为方法论拆解,未绑定特定产品实测。
245



被折叠的 条评论
为什么被折叠?



