Agent Team 的上下文工程设计：如何组织和共享上下文

这是一个系列文章中的第二篇，讨论 Pragma 在构建多 Agent 系统过程中遇到的六个核心问题。它不从 Prompt 技巧出发，而是从一个长期运行的 Agent 系统需要具备的工程能力出发：执行环境如何替换，上下文如何组织，多个专家如何协作，经验如何积累，复杂任务如何组合，以及整套工作方式如何成为可以版本化和分享的资产。开源地址：https://github.com/pqpo/pragma ，欢迎下载体验、 star、fork 和提交 PR, 支持 Windows，Mac 客户端，可以直接下载体验。

首先，我们先回答一个问题：为什么要组建多 Agent 系统？多 Agent 并不是免费的。恰恰相反，一个系统中的 Agent 越多，通常意味着更高的 Token 消耗和更复杂的上下文管理成本。

以最简单的 SubAgent 模式为例：主 Agent 将一个任务委托给子 Agent，通常可以理解为一次特殊的 Tool Call。主 Agent 需要先将任务描述和必要的上下文传递给子 Agent；子 Agent 独立完成推理后，再将结果返回给主 Agent。这里存在一个很容易被忽略的成本：同一份信息可能会跨 Agent 边界被重复计入上下文。

例如，子 Agent 生成一份结果时，这部分内容首先产生了一次 Output Token；当结果返回给主 Agent 后，它又会成为主 Agent 后续推理上下文的一部分，再产生 Input Token。Agent 层级越深、协作次数越多，这种上下文在不同 Agent 之间的复制和传递就越频繁。

而 Token 只是最直观的成本。更大的问题来自上下文隔离：主 Agent 已经搜索、阅读并理解过的代码、文档和资料，子 Agent 默认并不知道。如果没有一套有效的上下文共享机制，子 Agent 很可能需要重新搜索、重新阅读、重新建立理解。

所以，从纯粹的上下文效率来看，多 Agent 天生比单 Agent 更昂贵。

那么问题就来了：既然多 Agent 会带来额外的 Token 消耗、上下文复制和重复检索，我们为什么还要组建 Agent Team？

当上下文污染降低性能时，任务可以并行运行时，以及专业化能改善工具选择或任务聚焦，这时候就可以考虑使用 SubAgent。
当任务复杂、执行路径不确定，需要多个专业角色自主分工、并行协作、动态调整时使用。可以组建 Agent Team。
当任务流程相对确定，可以预先定义步骤、条件和依赖，需要稳定、可控、可重复执行时使用。可以组建 Workflow。

所以原则就是单智能体优先，当损耗大于收益的时候，以上下文为中心原则分解多 Agent 系统。

回到正题，如何组织和共享多 Agent 之间的上下文？如何减少上下文传递？如何高效的利用已知上下文？正是本文需要讨论的内容，阅读完全文后希望能给你一个清晰的答案。

在很多 Agent 项目中，上下文工程最终会变成一个越来越长的 Prompt 拼接函数：系统指令、用户偏好、项目文档、历史消息、检索结果和临时状态全部塞进同一个字符串，然后期待模型自己找出重点。

随着上下文来源增多，系统会逐渐失去三个基本答案：内容从哪里来，为什么在这次运行中被加载，以及当前 Agent 是否有权读取或修改它。所以我们需要设计一个模块化、可插拔、易管理的统一上下文系统。

上下文基础设施：ContextSystem

ContextSystem 希望把 Context 从“Prompt 的一部分”提升为一个独立的运行子系统。统一管理上下文从哪里来、如何发现、什么时候加载，以及谁能够访问。

后续会基于这套系统，实现任意的知识库对接，记忆系统对接，还有后文提到的 Agent Team 上下文协作系统对接。

上下文适配器：ContextStore

我们把不同的上下文来源统一抽象为 ContextStore：

listContext
readContext
searchContext
addContext
editContext
deleteContext

关键不在这几个 CRUD API，而在于它不限制底层实现。文件系统、JSON、项目知识库、Memory、Mission Board，甚至数据库和远程知识服务，都可以通过同一套协议接入，可以类比为一个虚拟文件系统。不同 Store 再挂载到不同 namespace：

project/*         项目知识
memory/*          长期记忆
mission-board/*   Mission 共享上下文
team/*            Team 级上下文

于是 Agent 面对的始终是一套统一的 Context，而不需要知道背后究竟是文件、数据库还是 Memory 系统。

Context 本身也不只是正文，还包含 trigger、priority、trustLevel、sensitivity 等元信息，用来描述它什么时候应该加载、重要程度以及可信和安全边界。

渐进式加载上下文

ContextSystem 另一个核心设计是 Progressive Disclosure：不是把所有知识一次性塞进 Prompt，而是逐步暴露。

一个知识库即使包含大量文档，Agent 启动时也不需要全部读取。整体过程变成：

再结合优先级和 Context Budget，预算不足时优先保留重要信息；大型文档则可以分段读取。本质上，ContextSystem 管理的不只是“有哪些知识”，更重要的是：在什么时机，把什么知识放进模型的 Context Window 。

上下文窗口管理：Context Budget

渐进式加载解决的是“哪些 Context 应该进入模型”，但还有另一个问题：即使都是应该加载的内容，也不能无限占用 Context Window。因此在 Context Assembly 阶段又增加了一层 Context Budget。

它不是直接按照模型的最大 Token 数把窗口塞满，而是限制系统主动注入的上下文。目前主要分成两部分：

System Prompt Budget ： Agent 指令 + Context Index
Preload Budget： always_on / preloadPaths 正文

预算不足时，Context 会按照：critical → high → normal → low 的优先级进行装配，高优先级内容优先保留。priority 既可以由文档自己声明，也可以由 Expert 的 Root Rule 根据路径进一步提升。

对于必须预加载的大文档，ContextSystem 也不会因为文件过大就把整份内容塞进去，而是在剩余 Budget 内读取一部分，并保留 nextStartOffset。Agent 后续真正需要时，可以继续按段读取。

所以 Context Budget 的目标并不是“尽可能利用模型窗口”，而是控制主动注入的信息量，把有限的 Context Window 留给真正有价值的内容和后续推理，ContextSnapshot 还会记录实际使用了多少预算、哪些 Context 被省略或截断，因此一次 Context Assembly 是可以被观测和解释的。

上下文权限与治理

ContextSystem 不只统一 Context 的读取方式，也提供了一层通用的权限边界。权限并不是简单的 canRead / canWrite，而是由多个层次共同决定：

ContextStore Binding：挂载哪些上下文
Namespace ：可以访问哪个空间
Runtime Context：当前以什么身份访问
Store Capability ：允许执行哪些操作
Mutation Policy：哪些修改需要审批

其中真正的权限最终落实在 Runtime 和 ContextStore，而不是依赖 Prompt 约束模型。例如一个 ContextStore 可以只开放 list / search / read，直接在系统层拒绝修改；数据库或企业知识库也可以根据 Runtime Context，在自己的数据层继续执行租户和身份鉴权。

写操作同样可以受到治理。不同 Store 可以配置不同的 Mutation Policy，例如普通内容允许直接更新，但把一份 Context 提升为 always_on——意味着它以后会自动进入 Agent 上下文——则可以要求显式审批。

因此 ContextSystem 提供的是一套通用能力：决定谁能看到什么、能做什么，以及哪些上下文变化需要被控制，而不是把权限规则写进 Prompt。

ContextSystem 最核心的价值，不是再造一个知识库，而是为不同类型的 Context 提供统一抽象，以后新增一种上下文来源，不需要重新设计一套 Prompt 拼接逻辑，只需要把它接入 ContextStore。

下文要介绍的 Mission Board 就是一个典型例子：它本质上也是一个 Mission Scoped ContextStore，用统一的 Context 协议承载多个 Agent 之间共享的计划、进度、决策和任务产物。

上下文协作模型：Mission Board

上一章介绍的 ContextSystem 是通用上下文基础设施，它统一解决 Context 的存储、寻址、加载、权限和版本控制问题。而 Mission Board 是建立在 ContextSystem 之上的一种具体 ContextStore，专门服务于一次 Mission 内多个 Agent 的协作。ContextSystem 解决的是“上下文如何统一管理”，Mission Board 进一步解决的是：一个 Agent Team 在执行同一个 Mission 时，团队共同的工作状态应该保存在哪里？

如果没有这样一层共享上下文，最简单的协作方式就是让协调者承担所有信息流转：Expert A 完成任务，把结果返回协调者；协调者整理后，再传递给 Expert B。

但随着任务复杂度增加，Team 的 Plan、进度、关键决策、任务产物和 Handoff 都会散落在不同 Agent 的 Conversation 中。协调者逐渐变成信息中转站，新 Expert 接手任务时，也需要不断复制和重组之前的上下文。Mission Board 因此可以理解为一块属于当前 Mission 的持久化团队共享工作区。

它保存的不是所有 Agent 的完整对话，而是团队继续完成这个 Mission 真正需要的工作状态。例如：

plan.md：当前团队计划
todos.md：团队任务
progress.md：当前进度
decisions.md：关键决策
handoffs/.md： Expert 之间的交接信息

这些并不是 Mission Board 特有的数据结构，本质上仍然都是 Context。Plan、Progress、Decision、Handoff 只是团队对这些 Context 的使用约定，因此它们天然继承了 ContextSystem 的搜索、按需读取、权限控制、版本冲突和持久化能力。

这也是 Mission Board 设计中很重要的一点：它不是在 ContextSystem 之外重新设计一套 Agent 协作协议，而是把“团队协作状态”也纳入统一的 Context 模型。

共享上下文结果：Handoff 机制

Expert A 完成工作后，并不需要把自己的完整 Session 交给 Expert B，只需要把后续真正需要的信息整理成 Handoff：

这样 Expert 之间传递的是任务上下文，而不是彼此越来越长的对话历史。

Mission Board 又是持久化的，因此 Expert 不需要同时在线。即使 Session 结束、Runtime 重启，甚至换一个 Harness，后续 Agent 仍然可以重新读取之前留下的 Plan、Progress 和 Handoff。

除了 Agent 主动编写 Handoff，还有一层非常重要的兜底机制。如果一次 Expert 调用返回的内容很大，系统不会把完整结果继续复制到上层 Agent 的 Context 中，而是自动将原始输出写入 Mission Board 的：system/outputs/...

调用链中只保留： Summary + Context Reference，后续 Agent 真正需要细节时，再通过 ContextSystem 按需读取完整内容。这不只是节省 Token。更重要的是，原始结果被作为一手资料保存了下来。

Agent 的 Conversation 后续可能经历 Context Compression，详细分析可能最终只剩下一段摘要；但 Mission Board 中保存的原始产物并不会因此变成摘要。后面的 Agent 如果发现细节不足，仍然可以沿着 Context Reference 重新读取原文。

因此 Mission Board 实际形成了两种 Handoff：

主动 Handoff：Agent 主动整理给其他 Expert 的协作上下文
自动沉淀：Runtime 自动保存过大的 Expert 原始输出

前者强调信息提炼，后者强调原始信息不丢失。

共享状态与私有状态

Mission Board 正是 ContextSystem 的权限模型在 Agent Team 协作中的一个具体应用。

它通过两个 Namespace 把团队状态划分为共享和私有空间：

mission-board : Mission 内所有 Expert 共享
mission-board-private: 当前 Runtime Context 私有

团队的 Plan、Progress、Decision 和 Handoff 属于共同工作状态，适合放入 Shared Board；Expert 自己拆解出的 TodoList、草稿和中间判断，则更适合保存在 Private Board。

Private Board 会根据 Runtime 的 contextId 隔离数据。不同 Runtime Context 即使访问相同的 todos.md，看到的也是各自独立的内容；没有可信 contextId 时则无法访问 Private Board。

真正需要其他成员知道的信息，再从 Private Board 提炼到 Progress、Decision 或 Handoff，因此这里的核心不是简单区分“公共文件和私人文件”，而是建立两层协作上下文：Private Board 保存个人工作状态，Shared Board 保存团队已经形成的共识。

多 Agent 同时写冲突

既然 Mission Board 是共享区域，就一定会遇到并发写入。比如 Expert A 和 Expert B 同时读取了 progress.md，然后分别进行修改。如果只是普通文件覆盖，后写入的人就可能把前一个人的结果静默覆盖掉。使用 revision / etag 做乐观并发控制：

所以共享并不等于“所有 Agent 随便改同一份文件”。Mission Board 会把真正的并发冲突暴露出来，而不是让最后一次写入静默覆盖之前的内容。

同时在协作设计上，也应该尽量减少热点文件：Team 级 Plan 和 Progress 保持精炼，个人 Todo 放到 Private Board，Handoff 和大型产物按 Topic 独立保存。

写在最后

ContextSystem 解决的是 Agent 系统中统一的上下文抽象，ContextStore 负责接入不同的上下文来源，而 Mission Board 则是其中一种面向协作场景的 ContextStore。Mission Board 真正解决的，不是“Agent 之间如何发消息”，而是：一个长期运行的 Mission，它的共享工作状态应该存在什么地方。

Agent 可以结束，Session 可以被压缩，Harness 也可以切换，但 Mission 的 Plan、Progress、Decision、Handoff 以及关键任务产物仍然能够持续保留下来，并在需要时重新读取。

这也是 Context Engineering 在 Agent Team 中真正重要的地方：上下文不应该只是一次推理前临时拼出来的 Prompt，而应该成为可以持续积累、共享、检索和重新使用的系统资源。

当这种能力建立起来之后，Agent Team 的协作方式也会发生变化：从不断在不同 Agent 之间复制 Prompt，逐渐变成更接近真实团队的工作模式——每个成员维护自己的工作上下文，通过共享白板同步计划、进度、决策和交接，重要的一手资料被持久保存，需要时再按需读取。

最终，真正被长期保留下来的，不应该是某一次 Agent 的完整对话，而应该是这个团队完成任务过程中形成的有效上下文。

‍

>> 转载请注明来源：Agent Team 的上下文工程设计：如何组织和共享上下文

赏

免费分享，随意打赏