Agent 治理:用 Hook 堵住 LLM 的偷懒、越权与失忆


本文是 DECO(一个跑在生产上的数仓 Agent 引擎)实践系列之一,聚焦护栏层:怎么用 Agent 框架的 Hook 切面,把 LLM 处理长文本时的"偷懒"(截断、略写、残缺)、对生产环境的"越权"(未确认发布、回刷)以及上下文传递中的"失忆"(改了表不查风险、产出了物不知汇报),在代码层确定性兜底——prompt 管不住的,框架来堵。

DECO 作为腾讯一站式数据工程 Agent 智能协作平台,以业务数仓知识库为基础,致力于解决从需求到数据交付全过程,主要聚焦于数据问询、开发、同步、分析、运维五大环节。希望帮助更多同学更轻松地获取数据、理解数据、应用数据,助力数据平权。

引子:从两个真实案例说起

案例一:用户让 Agent 改一张核心表的 ETL——1200 多行的长 SQL。Agent 读完原文、开始输出,写到一半"偷懒"了,中间跳过一大段逻辑写了句省略,然后若无其事地继续往下写。这份带省略号的脚本一旦提交上线,下游几十张表当天的数据就会算错。

案例二:Agent 还在"方案设计"阶段、用户都没点头,就径直调了发布工具,把一张还在讨论的表结构推上了生产。

这两个案例看似不相干,根因却是同一个——不是模型能力不够,而是它"图省事"或"自作主张"。具体有三种表现:

  1. LLM 偷懒:处理长脚本(动辄上千行的 SQL / Python ETL)时,模型会截断、占位略写(输出 -- 其他字段...)、跳步骤、把长 SQL "复印"式重写到 token 耗尽,最后剩一堆残缺、不可执行的脚本。
  2. 越权操作:发布、回刷、冻结/解冻、终止实例这些写生产或不可逆的动作,模型无法区分操作的可逆性——它把发布和查询视为同一类"完成任务的步骤",可能不打招呼就直接调了。
  3. 上下文失忆:模型改完表不去分析下游风险、Python 产出图表不知告诉用户——「需要查的就不查」。模型被训练成用最短路径完成任务——额外一次 tool call 意味着多一步推理,模型倾向于跳过"看起来不必要"的检查步骤。(此处风险分析为事后下游影响评估,非改表前拦截——事前拦截由 HITL Guard 负责。)

"在 prompt 里多写几句 ⚠️ 禁止"根本管不住。 这不是 prompt engineering(通过提示词约束模型行为)能解决的问题——长 SQL 是物理上超出 token 预算,危险操作是模型无法区分"查询"和"发布"的可逆性差异,被动探测是模型追求最短完成路径的自然倾向。唯一的解法是在 Agent 框架层,让偷懒和越权的路径代码级强制走不通,让失忆的已知盲区确定性补齐。

本文拆解这套机制——Hook 链(Agent 框架的 Callback 切面)+ 挂在它上面的读写两侧 offload(长内容落盘、上下文仅留引用句柄)+ HITL 门禁 + 上下文联动闭环。


一、背景:数仓 Agent 的任务开发流程

DECO 的数仓开发 Agent 帮用户把数据需求落成 US 平台上可运行的任务。先约定几个关键名词:


二、Hook 链:在关键切面挂载护栏逻辑

拦截这三类问题的切入口,是 Agent 框架普遍提供的Hook(或称 Callback)机制:框架在 Agent 运行的每个关键节点(围绕"模型调用"和"工具调用",各有执行前 / 后)暴露出切面。我们把拦截逻辑挂载到这些切面上——到点框架自动回调,同一切面可挂多个、按序执行。一次会话沿这条流水线跑下来:

本文主要用到下面几个切面:

切面
触发时机
本文用它做什么
Before Tool(beforeTool)
工具真正执行前,可改入参、可直接拦截
长脚本回写前从文件加载全文、危险操作确认(HITL 门禁)
After Tool(afterTool)
工具执行后、结果回给 LLM 前,可改返回值
长脚本拉取后把内容替换成引用句柄
Before / After Model
每次请求 LLM 前 / 后
响应用户取消等
Before / After Agent
单个 Agent 运行前 / 后
对话持久化等

设计原则:基础设施和推理逻辑解耦——Hook 切面上的逻辑独立运作,模型的 ReAct 循环不用感知;新增 / 删除一个 Hook,主流程一行代码都不用改。

本文逐层拆解三个最重要的应用:长文本完整性护栏(§三,揪"偷懒")、危险操作确认 HITL(§四,封"越权")、上下文联动闭环(§五,补"失忆")。


三、长文本完整性护栏:让长脚本进出 LLM 都不出错

3.1 长 SQL 在哪里被截断、略写

数仓任务开发会遇到两类长脚本,它们的偷懒形式不同:

  • 修改场景:从 US 平台拉来的存量长 SQL,要在原脚本上局部改写后回写。风险集中在"拉取—改写"环节。
  • 新建场景:LLM 新生成的目标态长 SQL,通过 US 平台"保存/更新任务"工具的 scriptContent 入参提交。风险集中在"写回"环节。

无论哪种场景,长脚本都要经过拉取(US 平台 → LLM)和写回(LLM → US 平台)两段,每段都有各自高频的偷懒形式:

阶段
偷懒形式
现象
后果
拉取
流式 token 自截断
把长 SQL 塞进上下文后,输出端重写时 token 预算耗尽
文件截断成残缺 SQL,回写即生产事故
拉取
view
(沙箱文件查看)后 create_file(创建文件)重写
读长 SQL → 用"创建文件"工具把整段再吐一遍(而非只改局部)
等于复印一遍,输出 token 翻倍,此路径下自截断概率接近 100%
拉取
占位 / 略写
输出含 (SQL略)、-- 其他字段...
落盘脚本不可执行
写回
scriptContent
 入参自截断
拼回写工具入参时长 SQL 在 JSON 串里被截断
提交残缺脚本,US 平台无校验

一句话定位:长产物的偷懒是结构性问题。解法是——把 LLM 必须接触的长内容降到最少、每次接触的窗口压到最小、所有写入路径都做成"小步增量改 + 强制校验"。

根治方案:让长 SQL 从 LLM 上下文里"消失",全文走文件通道——这就是读写两侧 offload 要解决的问题。

3.2 框架层方案:读写两侧 offload + 引用句柄

做法:整体思路是——LLM 永远不直接接触脚本全文。 两端都用 Hook 拦截 + 沙箱文件做"中转站":长内容全文留在沙箱,LLM 上下文里只有一句引用句柄,US 平台 ↔ 沙箱 ↔ LLM 三方各管一段,LLM 只用 str_replace 小步改写,最终通过文件路径入参把工作副本喂给回写工具。

下文为可读性将盘路径统称 /sandbox/,实际代码中只读快照在 /mnt/chat-offload/,可编辑工作副本在 /mnt/user-data/。

拉取侧:Offload Hook(afterTool)

Hook 拦截到含 scriptContent 的响应后,将全文写入沙箱只读快照,响应中替换为引用句柄。句柄明确告诉 LLM "要改先 copy_file(把只读快照复制为可编辑工作副本),再 str_replace":


案例 · 同一个"拉取长 SQL"动作,治理前后 LLM 看到的东西(脱敏示意):

# 治理前:约 3.8 万字符长 SQL 原样进上下文,复印重写到一半 token 耗尽
INSERT OVERWRITE TABLE dws_order_detail ...
SELECT ... FROM dwd_a UNION ALL
SELECT ... FROM dwd_b
-- 其他字段...                       ← 占位略写
(输出在此截断,下游 SQL 不完整)

# 治理后:上下文里只剩一句引用句柄,长 SQL 全文留在沙箱只读快照

关键设计点:

  • 响应形态适配:单条 Map 和数组都要支持;数组下每条 item 独立判定,任一落盘失败仅该条降级,避免"一条出错让整批 SQL 全进上下文"。
  • 失败降级:落盘失败 → 该条返回原 scriptContent,让 LLM 至少拿到内容(承担自截断风险),不阻断主流程。

写回侧:Onload Hook(beforeTool)

同模式延展:表侧 Offload

上面详细拆解的是任务脚本的长文本护栏链路。同一套 Hook 链上,表侧也挂了完全对称的 Hook(面向宽表 200–500 列场景),心智模型与任务侧完全一致——读侧降级(落盘失败透传)、写侧阻断(文件不存在抛异常)。

工具协议:scriptContent 与 scriptFilePath 互补参数

回写工具同时声明两个参数,scriptFilePath 是纯框架契约:

scriptContent  : 脚本内容。⚠️推荐改走scriptFilePath让框架Hook自动加载,
                 避免长SQL拼入参时自截断;仅沙箱不可用时才直接传。
scriptFilePath :脚本的沙箱路径(强烈推荐)。框架OnloadHook会从沙箱读全文覆盖
                 scriptContent,并在转发给本工具前剥离该字段;下游实现侧不消费它。

好处:下游无感知(协议不用改)、框架可独立演化(阈值/白名单/剥离规则升级都不影响下游)、防御性日志兜底(下游对 scriptFilePath 留 log.warn——到达本工具时它本应已被剥离,还在就是 Hook 失效信号)。

效果:修改任务时,模型不用再"吐"那几千行 SQL——它只输出脚本路径,全文由框架在后台对齐。「长文本走文件路径,修改任务的工具调用输出 token 直接降约 90%」的落地机制;长 SQL 从此彻底从对话历史和 token 消耗里"隐身"。

3.3 多重防线全景(对应数仓四阶段)

这套护栏不是单点,而是贯穿 Skills 编排篇那条流水线的多重防线:

每一阶段的防线,正好对应 Skills 编排篇里那条数仓开发流水线(设计→拆解→执行→验证四阶段)的各个阶段——Hook 在框架层做物理兜底。

图中隐含了两条关键分支,未直接绘出以保持主线清晰:

  • Onload 阻断(红线):「⑤ → Onload Hook 加载工作副本」环节,若 scriptFilePath 不在白名单路径、身份缺失、文件不存在或内容为空 → 抛异常阻断工具调用,不进入 C1 后续。
  • Offload 降级(橙线):「① Offload Hook 落只读快照」环节,若 COS 落盘失败 → 该条原 scriptContent 透传给 LLM(承担自截断风险),不阻塞主流程。

3.4长文本护栏效果小结

把前面散落的数字汇成一张表(均为脱敏汇总):

维度 / 指标
治理前
治理后
offload 策略
SQL 原样进出上下文
全量落盘
,所有 scriptContent 自动换引用句柄
修改任务工具调用输出 token
每轮重传整段 SQL
**直降约 90%**(上下文仅留引用句柄)
SQL 复印自截断
"view → 重写"路径下概率近 100%
物理消除(只走 str_replace 小步改)
读侧失败(Offload,afterTool)
—
降级
透传,可重试,不污染生产
写侧失败(Onload,beforeTool)
—
阻断
工具调用,杜绝发布残缺脚本

3.5 行业对比:哪些是现成的,哪些必须自研

和 HITL 不同——HITL 是单点拦截决策,各框架几乎都有一行配置或一个中间件搞定。长文本护栏是一个流水线问题(拉取 → offload → 编辑 → onload → 写回),没有哪个框架直接给一个开箱即用的完整闭环。但"offload + 引用句柄"这个模式本身,行业已有多种层级的实现:

注:DECO 使用 Java ADK,其 Hook API 与 Python ADK 同构但接口名略有差异;以下对比以 Python ADK 为例说明设计思路差异,具体接口以 Java ADK 文档为准。

工程
读侧策略
写侧策略
自动化程度
ADKArtifactServicesave_artifact
 / load_artifact API + LoadArtifactsTool,官方有 context_offloading_with_artifact 示例(save→摘要→hook 注入→仅当前轮次可见)
❌ 需工具内手动调 load_artifact 再拼入参
⚠️ 每个工具手动调用 API,非 Hook 层自动拦截
LangGraph
 DeepAgents
内置 "Large Tool Result Offloading" 中间件:工具结果 >20k token 自动落盘,消息中只留引用指针;另有 SummarizationMiddleware 在 85% 容量时自动摘要压缩历史
❌ 只做读侧
✅ 全自动,中间件层透明
Anthropic Claude CodeRead
 默认 2000 行、offset/limit 分页
Edit
 强制 str_replace,Pre-read requirement
❌ 无 offload,内容全留上下文

两个关键结论:

  1. ADK 和 LangGraph 都有内置的 offload 能力——如果 DECO 只需要"读长 SQL 时把全文换成引用句柄",用它俩的原生机制改造即可,不是从零发明。但这两者的 offload 都只做到读侧(工具结果 offload),没有写侧 onload——因为大部分 Agent 场景不需要把长产物再原样发回外部 API。

  2. DECO 的数仓场景不同——有"写长 SQL"的保存工具,长产物要原样回写 US 平台。这意味着必须两端对称 offload,并且写回时需要额外加固:

加固项
为什么框架原生覆盖不了
写侧 onload
(beforeTool 加载全文覆盖入参)
ADK / LangGrap…
— 以上为试看内容(约 40%),开通会员后阅读全文 —