Agent 架构避坑指南：三层上下文裁剪模式与实践

整个过程中，LLM 拥有完全的自主权——选哪个工具、传什么参数、循环几次，全由模型自己决定。

我为什么先选了它

原因很简单：ReAct 是最灵活的模式，几乎所有 Agent 教程的第一课都在教它。而且 LangGraph 直接提供了 createReactAgent 这个开箱即用的工具。我只需要定义好 Tool，把用户消息丢进去，Agent 就能"自动"工作了。

遇到的问题

第一个：不可预测性。

用户说"帮我看看这个任务的进度"，我期望 Agent 调用 query_task 查一下然后回答。但 ReAct 模式下，模型有时候会：先查任务详情，再查项目详情，再查团队成员负载，最后给出一个"综合分析"——用户只是想看个进度，不需要这么复杂的分析链路。更麻烦的是，同样的输入，不同时间可能走出不同的路径。

第二个：成本不可控。

ReAct 的循环次数由模型自己决定。一个简单的任务查询，模型可能"谨慎地"循环 4-5 轮（思考→调用→观察→再思考…），每一轮都在消耗 token。而其中很多轮次的"思考"是不必要的。

第三个：安全风险。

ReAct 模式下模型可以自由选择任何 Tool。我没有一个可靠的机制来确保"删除任务"这种高风险操作在执行前必须经过用户确认。只靠 prompt 里写"删除前请确认"是不够的——Anthropic 自己的工程建议里就明确说过：不能只靠 prompt 来防护高风险操作。

思考

ReAct 的问题本质是：它把所有的决策权都交给了 LLM，但 LLM 并不是所有环节的最优决策者。 对于"查询任务进度"这种有明确固定流程的操作，我不需要 LLM 来"思考"应该怎么做——直接走固定流程就好。

这让我开始思考一个原则：确定性 workflow 优先，只有在真正需要开放式决策时才引入 LLM 推理。这条原则贯穿了后续所有的架构选择。

第二站：Plan-Execute 模式——"先规划再执行"

Plan-Execute 是什么

这个模式把 ReAct 的"边想边做"拆成了两个明确阶段：

Planner（规划）→ 生成步骤列表 → Executor（执行）→ 逐步执行 → 结果不对？→ Replanner（重新规划） 

Planner 用一个强模型（比如 GPT-4 级别）来分析任务、生成完整的执行计划；Executor 用一个轻量模型或固定代码逐步执行计划；如果中间结果偏离预期，Replanner 会调整计划。

比 ReAct 好在哪

Plan-Execute 解决了 ReAct 的一部分不可预测性问题。因为计划是预先生成的，我至少可以在执行前看到 Agent 打算做什么，甚至可以让用户确认计划后再执行。这比 ReAct 的"黑盒循环"可控多了。

新的问题

过度规划。

用户说"帮我创建一个任务：修复登录页面的样式"。这是一个再明确不过的指令——直接调用 create_task 就行了。但 Plan-Execute 模式下，Planner 仍然会被触发，花几秒钟"规划"一个只有一步的计划。这个规划过程消耗了一次强模型调用的成本和延迟，却没有产生任何价值。

所有请求走同一条路。

不管是"创建一个任务"（简单 CRUD）还是"帮我分析这个项目所有延期任务的原因"（需要深度推理），都要经过 Planner → Executor → Replanner 这条路径。简单操作被迫走了复杂链路，复杂操作的 Planner 又不够专业（它是通用的，不是针对特定业务场景优化的）。

Replanner 的引入增加了系统复杂度。

Replanner 需要判断"当前结果是否偏离预期"，这本身就是一个模糊的判断。什么叫"偏离"？偏离多少要重新规划？重新规划几次就该放弃？这些都需要额外的设计和测试，而很多场景根本用不到 Replanner。

思考

Plan-Execute 的问题在于：它假设所有请求都需要"规划"这个步骤，但现实中大量请求是可以直接执行的。 我需要一个机制来区分"需要规划的复杂请求"和"可以直接执行的简单请求"。

第三站：Router 分发模式——"先分流再处理"

Router 是什么

Router（路由器）的思路是：在 Planner 之前加一个轻量的分发层，先判断用户的请求属于哪个类别，然后根据类别走不同的处理路径。

用户输入 → Router（意图分类） ├─ 简单 CRUD → 直接执行（不经过 Planner） ├─ 数据查询 → SQL 查询 + 结果解释 ├─ 任务拆解 → Planner → Executor → Replanner └─ 周报生成 → 固定 Pipeline（取数→聚合→润色） 

这解决了 Plan-Execute 的"所有请求走同一条路"问题——简单操作走快速路径，复杂操作才启用完整的规划链路。

我的两层路由设计

进一步优化后，我把路由拆成了两层：

第一层：Fast-path Router（零 LLM 调用）。 前端的快捷按钮、卡片操作等结构化入口，直接映射到对应的能力模块，完全不需要 LLM 来判断意图。比如用户点了"生成周报"按钮——意图已经明确了，不需要模型来"理解"。

第二层：LLM Fallback Router（仅处理自由文本）。 只有用户在输入框里用自然语言提问时，才需要 LLM 来判断意图。而且这个 LLM 调用使用最轻量的模型，只做分类，不做推理。

这个两层设计的效果是：在我的场景中，预估超过 60% 的请求可以走 Fast-path，零 LLM 调用就完成路由。剩下 40% 的自由文本请求走轻量 LLM 路由，成本也远低于直接启动一个 ReAct 循环。

到这里为止，还有什么问题？

Router 分发解决了"不同请求走不同路径"的问题，但引入了一个新的问题：不同路径上的节点需要的上下文信息是不同的，但它们拿到的上下文是一样的。

具体来说，前端会传一个完整的页面上下文给后端，包含当前页面、选中的对象、筛选条件、可见的列表数据、分页信息等。这个上下文对象会被注入到 LangGraph 的 State 里，然后所有节点——Router、Executor、Tool、LLM prompt——都能读到全部内容。

刚开始我觉得这没什么问题：节点用得上的字段就用，用不上的就忽略呗。

但这个"忽略"的假设，很快就出事了。

第四站：三层上下文裁剪——"从源头控制信息流动"

触发我重新思考的三件事

事件一：Token 账单异常。

我在测试环境跑了一批模拟请求后发现，Router 节点消耗的 token 数远超预期。排查后发现，前端传过来的 visibleEntityIds（当前列表可见的条目 ID 列表）有时候多达 40-50 个 ID。这些 ID 被完整地塞进了 Router 的 prompt 里——但 Router 的工作仅仅是判断"用户想做什么类别的事"，它根本不需要知道列表里有哪些具体条目。

每次请求白白多消耗几百 token，单次不多，但乘以日均请求量，一个月下来是一笔实际的成本。

事件二：Tool 里出现了不该有的 if-else。

我在 code review 时发现一段代码：某个 Tool 在执行查询时，根据 origin（请求来源）字段返回不同详细程度的结果——如果请求来自侧边栏就返回简要信息，来自 AI 工作台就返回详细信息。

这段代码"能跑"，但它意味着 Tool 和 UI 入口产生了耦合。如果以后新增一个入口（比如从甘特图发起的分析），这个 Tool 就要再加一个 if 分支。而 origin 本来是路由层的信息，Tool 不应该关心请求从哪来，它只应该关心"操作什么数据"。

这段代码之所以能写出来，是因为 Tool 能读到 origin 字段——信息可达就会被使用，这是工程中的必然规律。

事件三：安全隐患。

我在考虑 prompt injection 防护时意识到，如果 LLM 的 system prompt 里直接拼入了完整的页面上下文 JSON，攻击者可以利用这些结构化信息构造更精准的注入指令。而 LLM 其实只需要一句自然语言描述就能理解当前场景——它不需要看到原始的数据结构。

设计思路

这三件事的共同根源是：所有节点都能看到全部上下文，但没有任何机制约束"谁该看什么"。

我重新审视了整个 Agent 系统中的角色分工，发现有且只有三类上下文消费者：

1. 路由层（Router）。 它的任务是判断用户意图——"用户想做什么类别的事"。它需要知道用户在哪个页面、从哪个入口发起、选中了什么对象。它不需要知道列表有多长、筛选条件的细节、分页在第几页。

2. 执行层（Tool / Executor）。 它的任务是具体执行操作——查数据库、创建任务、修改状态。它需要知道操作的目标对象、筛选条件、分页信息。它不需要知道请求从哪个入口来——Tool 的行为不应该因为来源不同而改变。

3. 模型层（LLM system prompt）。 它的任务是理解场景并生成自然语言回答。它需要一个对当前页面的自然语言描述。它不需要原始的 JSON 结构、ID 列表、分页参数。

三类消费者，三种信息需求。那答案就很自然了：在信息进入 Agent 系统之前，按消费者裁剪成三份，每份只包含该消费者需要的字段。

这就是 Context Assembler——上下文装配器。它是后端的一个函数，在请求进入 Agent 图之前执行，把前端传来的完整页面上下文拆成三个视图：

前端传入：完整的页面上下文 │ Context Assembler（后端，执行一次） │ ┌───────┼───────────────┐ ▼ ▼ ▼ 路由上下文 执行上下文 模型上下文摘要 (RouterCtx) (ExecCtx) (ModelSummary) │ │ │ ▼ ▼ ▼ Router Tool/Executor LLM System Prompt 

三份视图存入 Agent 的状态中，各节点只读取自己对应的那份。

三、三层裁剪的设计细节

字段如何分配

字段分配的判断标准不是"这个字段对这一层有没有用"，而是**"给了这个字段之后，这一层会不会做出不该做的事"**。

下面逐个分析关键字段的归属：

origin（请求来源）

这是整个裁剪方案中最重要的隔离字段。

origin 表示请求从哪个 UI 入口发起：侧边栏、快捷按钮、任务行操作、AI 工作台等。

• 路由层：需要。 Fast-path Router 的核心依据就是 origin——"用户从快捷按钮点了生成周报"，origin 直接告诉 Router 该映射到哪个能力模块，无需 LLM 介入。
• 执行层：禁止给。 一旦 Tool 能读到 origin，开发者就会写出"首页来的返回简要版、工作台来的返回详细版"这种逻辑。Tool 的行为应该只取决于"操作什么数据"，不取决于"从哪来的"。如果产品确实需要不同入口返回不同详细度，这应该是路由层选择不同能力模块来实现，而不是同一个 Tool 内部 if-else。
• 模型层：不需要。 LLM 不需要知道"这个请求来自侧边栏"，这对生成回答没有帮助。

visibleEntityIds（当前列表可见条目）

这是最容易造成 token 浪费的字段。

一个任务列表页可能同时展示 20-50 条任务的 ID。如果全量传入 Agent，每个 ID 大约 10-15 个字符，50 个 ID 就是 500-750 个字符，折合约 200 token。

• 路由层：禁止给。 Router 判断意图不需要知道列表内容。如果 Router 能看到这些 ID，可能有人会在路由逻辑里写"列表为空时推荐创建任务"——这不是路由层的职责。
• 执行层：有条件给。 只有当列表很短（20 条以内）且用户明确针对可见项操作（比如"把这些全部标记完成"）时才传入。大多数场景下，Tool 应该根据筛选条件去数据库查询，而不是依赖前端传来的 ID 快照。
• 模型层：禁止给。 一串 ID 对 LLM 生成自然语言回答没有任何帮助，纯粹是 token 噪音。

filters（筛选条件）

这个字段需要差异化处理。

完整的筛选条件可能包含：状态、负责人、优先级、日期范围、自定义字段等，结构比较复杂。

• 路由层：只给关键部分。 Router 需要知道"用户在看进行中的任务"来辅助意图判断，但不需要知道"日期范围是 3 月 1 日到 3 月 22 日"。所以只抽取影响意图判断的关键字段（status、assignee、priority），形成一个精简的 keyFilters。
• 执行层：给完整的。 Tool 查数据库需要完整的筛选条件。
• 模型层：给自然语言摘要。 不传 {"status":"in_progress","priority":"P1"}，而是传"筛选：进行中、P1 优先级"。

分配总结

模型层为什么必须是自然语言摘要

关于模型层拿到的应该是原始 JSON 还是自然语言摘要，我做了一个明确的选择：只给自然语言摘要。

Token 效率差距明显。 同样的信息，JSON 格式大约 80 token，自然语言摘要大约 35 token。每次请求省一半，积少成多。

降低 Prompt Injection 风险。 结构化的 JSON 给了攻击者明确的格式线索。如果某个业务数据字段（比如任务标题）被注入了恶意内容，在 JSON 结构中它更容易被模型误解为系统指令。自然语言摘要打断了这种结构化格式，注入内容变成了一段不通顺的描述文字，模型更容易识别其异常。

LLM 的真实需求。 system prompt 里注入上下文的目的是让模型"了解当前场景"，不是让模型"拿数据做计算"。真正需要用 ID 查数据库的是 Tool，不是 LLM。模型只需要知道"用户在项目详情页看着甘特图"就够了，projectId: "p123" 这种原始数据对它没有意义。

摘要的生成方式是纯模板拼接，不需要调 LLM。根据页面类型和存在的字段，用固定模板拼出一句话。比如：

'用户当前在项目详情页，项目 p123，Tab 进行中，甘特视图，选中了任务 t456，筛选：P1 优先级。'

控制在 200 token 以内，简洁明了。

四、状态不可变性：如何保证裁剪后不被污染

做了裁剪只是第一步。三份上下文存入 Agent 状态后，还有一个问题：怎么保证后续节点不会篡改它们？

LangGraph 的状态更新机制是基于 reducer 的——每个状态字段都有一个 reducer 函数，决定"当节点返回新值时如何合并"。

我对三个上下文字段使用了"首次写入后冻结"的 reducer 策略：

• 第一次写入时（入口节点执行 Context Assembler 的结果），正常存入
• 之后任何节点如果尝试返回这些字段的新值，reducer 直接丢弃，保留原值

这意味着即使某个节点的代码里不小心 return 了一个修改过的上下文对象，框架层面就会拒绝这次更新。架构约束下沉到了框架机制，而不是浮在代码规范上。 规范可以被忽略，框架机制不会。

再叠加 CI 层面的 grep 检查——比如路由模块的代码里不该出现执行上下文相关的关键词——三道防线（框架拒绝 → CI 报错 → Code Review）就构成了完整的保护。

五、对比总结：四种模式的演进逻辑

回顾整个演进路径，每一次架构切换都不是"为了用新技术"，而是上一个方案的某个缺陷在实际开发中暴露后的应对：

四次演进的底层逻辑是同一条线索：逐步收回 LLM 的权限，把确定性还给确定性的模块，把信息控制权从"消费者自律"转移到"供给侧管控"。

ReAct 是把所有决策权交给 LLM；Plan-Execute 是把执行权收回来但规划权还在 LLM；Router 是把路由决策权也尽量收回来（Fast-path 零 LLM）；三层裁剪是把信息访问权也收回来（每个节点只看到该看的）。

每一步都在缩小 LLM 的"自由活动空间"——不是因为 LLM 不够强，而是因为在生产系统中，可控性比灵活性更重要。

六、防止架构退化

一个架构方案的价值不在于它设计出来的那天有多漂亮，而在于三个月后、十个人协作时它还能不能保持住。

我在设计三层裁剪方案时，同步设计了一份"防滑坡检查表"。它列举了最可能发生的四种退化模式：

这份表的价值在于：它把"未来可能出的问题"变成了现在就可以检查的清单。 Code Review 时对照这张表过一遍，就能拦住大部分退化。

我认为，能预见系统会怎么腐化，比设计系统本身更能体现架构能力。任何架构在白板上画出来都是干净的，难的是在真实协作中保持住这个干净。

七、思考

整个演进过程给我最大的感受是：Agent 系统的核心挑战不在于"让 LLM 更强"，而在于"给 LLM 恰当的边界"。

初期我花了大量时间在 prompt 调优上——怎么让模型更准确地选择 Tool、更好地理解用户意图。但后来发现，很多问题的根源不是模型不够聪明，而是我给了它太多不该看的信息、太多不该有的权限。

三层上下文裁剪模式的本质就是一个在 LLM 系统中落地的"最小权限原则"：

每个环节只应该看到刚好够它完成工作的信息，多一个字段都是负债。