KeyError 的五级放大故障链：模型输出截断如何伪装成"参数缺失"

WeClaw 技术博客 · 第 107 篇 - 模块九第 7 篇 · tool_call 解析加固 · 防御纵深四层 · 审计假象

📚 专栏信息

《从零到一构建跨平台 AI 助手：WeClaw 实战指南》专栏 · 模块九【稳定性实战：故障链解剖与自愈工程】（共 8 篇）

本文是模块九第 7 篇，Agent 侧两篇的开篇。桌面侧五篇的整套方法论—— 误导性报错、逐层取证、防线分层、真实节奏验证——在 LLM Agent 世界原样复演了一遍。

上一篇：《WeClaw_106 测试的测试》｜下一篇：《WeClaw_108 别猜你的模型预算》

👨‍💻 作者与项目

作者简介：翁勇刚 WENG YONGGANG 新概念龙虾-WeClaw 开发团队负责人，一群专注于跨平台 AI 应用的实践者理念："再复杂的技术，也能用代码讲清楚"

💻 项目地址：https://github.com/wyg5208/weclaw
🌐 官网地址：https://weclaw.link
📝 作者 CSDN：https://blog.csdn.net/yweng18

📝 摘要

本文结构概览：从"两个跑了好几个月的 AI 定时任务突然全挂、报错却是八竿子打不着的 KeyError: 'path'"开场，用三选一（模型/代码/配置）排除法定案根因；逐层解剖五级放大链；给出解析/校验/观测/审计四层防线的真实实现，并重点讲两个反直觉取舍——"刻意不做截断自动修复"与"审计日志里的成功可能是张冠李戴"。

背景： WeClaw 的「每日新闻早报」（07:04）与「每日论文精读」（09:15）两个 AI 定时任务连续失败，UI 显示 file.write → KeyError: 'path'，tool_call 参数为空字典 {}。

核心问题：当报错与真实故障隔了五级放大链时，如何定位？修最后一层为什么等于没修？

解决方案：配置实测校准 + 解析层统一告警 + 执行层必填参数校验 + 观测层截断显式化 + 审计层会话配对与 TTL 清理的五位一体。

关键成果：

根因定案置信度高（整文件新建时间戳铁证）
8 处静默吞异常收敛为 1 个带 WARNING 的统一解析入口
新增 13 用例全过、全量回归 450 通过、31 个失败逐一甄别为存量
"日志显示成功但任务失败"的审计假象机理定位并修复

适合读者：LLM 应用开发者、做过 function calling / tool call 工程化的人、对"可观测性分层"感兴趣的后端工程师

阅读时长：约 13 分钟

关键词：tool_call、finish_reason=length、JSON截断、静默异常、防御纵深、审计配对、定时任务

一、案发现场：一个与真相无关的报错

1.1 用户报告

"「每日新闻早报」和「每日论文精读」今天连续失败，界面上报 file.write → KeyError: 'path'，参数是空的 {}。这两个任务跑了几个月一直好好的，今天突然这样，必然是有什么变了。帮我定案： (a) deepseek-flash 免费档模型的新问题？(b) 系统代码被修订？(c) 配置参数被修订？"

先品一下这个报错的荒谬度：file.write 缺 path 参数？ 是模型自己"决定"要写文件的，它怎么会连自己的目标路径都不给？ 直觉答案有二：模型发神经，或者我们的解析层把参数弄丢了。而真相是第二个的一半——参数不是"弄丢"的，是被截断后无人报警。

1.2 三选一定案：先看铁证

排除法逐走：

(b) 代码被修订？ git log 检查：近三次提交与 tool-call 解析链路无关；本链路里"8 处静默吞异常"与 file.py 裸下标都是存在了很久的存量缺陷—— 它们一直没发作，只说明以前的输入没踩到扳机，不说明它们无罪。❌ 排除为主因。

(a) 模型有新问题？ 时间线部分相关，但模型侧行为可用配置完全解释（见下）。△ 部分成立。

(c) 配置被修订？ 铁证到手：

# ~/.weclaw/custom_models.toml
CreationTime : 2026/09/11 21:37:49
LastWriteTime: 2026/09/11 21:37:49     # ← 两值相等 = 整文件新建！

前一晚 21:37，一张免费档自定义模型卡 custom-deepseek-flash 被创建， max_tokens = 8192（建卡保守默认），取代了此前执行这两个任务的内置模型 deepseek-v4-flash（max_tokens=131072）。输出预算一夜之间缩水 16 倍。

时间线严丝合缝：09-12 07:03:50 免费模型首跑 news 任务即现首例 KeyError； paper 会话日志 10:32:29-10:33:02 记录"动态调整 max_tokens 8192→4096"，与 KeyError 同秒。

取证小抄：CreationTime == LastWriteTime 是"整文件新建"的经典指纹；排查配置突变时先 Get-ChildItem | Select CreationTime, LastWriteTime，比 grep 内容自证清白快一个数量级。

二、五级放大链：错误如何改头换面

定案只是开始，真正精彩的是这条故障的传播路径——每一级都在给错误加冕，直到它以完全不同的面目出现在用户面前：

[L1 任务层]  单次 file_write 参数含 13-20KB HTML（中文 token 密度高）
      │
[L2 预算层]  registry.py 动态压缩公式：
      │      effective = max(min(8192, 128000 − 122000 − 6400), 4096) = 4096
      │      → 输出预算被压到保底下限
      ▼
[L3 模型层]  输出写到一半没额度了 → finish_reason = "length"
      │      → tool_call 的 arguments 是一个残缺 JSON
      ▼
[L4 解析层]  agent.py 8 处：except json.JSONDecodeError: arguments = {}
      │      → 无任何日志，残缺参数"消失"成空字典
      ▼
[L5 执行层]  file.py:407  params["path"] 裸下标
      │
      ▼  💥
用户所见：  KeyError: 'path'      ← 与"输出截断"四个字毫无关系

真实代码各就各位。L2 的压缩公式（src/models/registry.py）：

input_tokens_est = input_chars // 2
safety_margin = int(context_window * 0.05)      # 5% 余量
max_allowed_output = context_window - input_tokens_est - safety_margin
effective_max_tokens = max(min(configured_max_tokens, max_allowed_output), 4096)
#                    保底 4096 ◀── paper 任务输入≈12.2万 tokens 时，全靠它吊命

L4 的旧代码（本次被统一替换的 8 处之一）：

# ❌ 修复前：静默三连
try:
    arguments = json.loads(func.arguments)
except json.JSONDecodeError:
    arguments = {}          # 残缺 JSON 蒸发
    # 没有日志。什么都没有。

这条链回答了一个经典问题："为什么日志明明报了 A 错，修的却是 B 层？" 因为报错永远出现在最后一环，而真相住在第一环。五级链的每一环都单看无辜：参数大是任务需要、压缩是防超限的本职、截断是 API 的合法行为、吞异常"反正有兜底"、裸下标"参数本该必填"—— 平庸的防御凑在一起，就生产了无法定位的事故。

三、还有一个烟雾弹：审计日志里的"假成功"

排查期间出现过一次更迷惑的现象：任务明明失败了，工具审计日志却躺着一条成功记录：

07:04:45 | file.write | {} | success | "枫桥夜泊 8388 字符"

空参数 {} 怎么 success 还写出了 8388 字符的诗？！

答案在审计的配对算法里。ToolCallEvent/ToolResultEvent 没有 tool_call_id 字段，audit.py 只能以 tool_name_action_name_ 前缀做全局 FIFO 配对：news 任务失败后留下的孤儿 pending，在 17 分钟后被一个 poetry 会话里同名工具的真实成功结果错配消费—— 两个会话的碎片拼成一条"时空穿越"的假记录。

这印证了模块九反复出现的主题：观测系统自身的 Bug，会把排查者引向比原 Bug 更远的歧途。（与第 52 篇 Tool 配对完整性同源，那篇在消息层，这篇在审计层。）

四、解决方案：四层防线 + 指令层兜底

4.1 第 1 层 · 解析层：失败必须开口（`src/core/agent.py` +98/−48）

8 处散落的 try/except 收敛为一个静态方法，全部调用点统一走它：

@staticmethod
def _load_tool_arguments(func_name, raw_arguments, tc_id=""):
    """解析 tool_call 参数；解析失败不再静默回退空字典。"""
    if isinstance(raw_arguments, dict):
        return raw_arguments
    raw_text = raw_arguments if isinstance(raw_arguments, str) \
        else str(raw_arguments or "")
    try:
        args = json.loads(raw_text) if raw_text.strip() else {}
    except json.JSONDecodeError as e:
        head = raw_text[:120].replace("\n", "\\n")
        tail = raw_text[-80:].replace("\n", "\\n") if len(raw_text) > 200 else ""
        logger.warning(
            "tool_call 参数 JSON 解析失败(疑似输出截断): func=%s id=%s "
            "原始长度=%d err=%s head=%r%s",
            func_name, tc_id, len(raw_text), e, head,
            f" tail={tail!r}" if tail else "")
        args = {}
    return args if isinstance(args, dict) else {}

首 120 + 尾 80 字符片段进日志——下次再出事，一眼分辨"截断"还是"模型真给了空参"。

⚠️ 本篇最重要的反直觉决定：刻意不做截断自动修复。 常见的"聪明"方案是补全引号括号把残缺 JSON 抢救回来。我们评估后明确否决：

无法区分"恰好截在收尾括号处"（补全无损）与"截在 content 字符串中间" （补全 = 写出一个看起来合法、实际残缺的文件）。 静默写出残缺文件，比一次明确报错危险得多——报错会被看见，残缺的新闻 HTML 会直接发布出去。

4.2 第 2 层 · 校验层：死配置第一次真正上岗（`src/tools/base.py` +35）

file.py 早在注册时就声明过 required_params=["path", "content"]—— 但执行链从来没有人读过它（只进了给 LLM 看的 schema）。 safe_execute 这次成为全部工具调用的统一入口后，必填校验第一次生效：

if action_def and action_def.required_params:
    missing = [k for k in action_def.required_params
               if params.get(k) is None or params.get(k) == ""]
    if missing:
        hint = ("收到空参数——通常是模型输出 JSON 被截断导致解析失败，"
                "请减小单次输出体积或分段写入（先写骨架，再用 append 模式分批追加）。"
                if not params else "")
        result = ToolResult(status=ToolResultStatus.ERROR,
                            error=f"缺少必填参数: {', '.join(missing)}。{hint}")
        return result          # 结构化错误直达模型，且带下一步指引

注意 hint 的读者是模型：错误消息是模型下一步行为的 prompt。告诉它"疑似截断，请分段写"，重试成功率远高于只说"缺参数"。

4.3 第 3 层 · 观测层：把截断从隐性事实变成显式事件（`registry.py` +63/−10）

if effective_max_tokens <= 4096:
    logger.warning("动态调整 max_tokens: %d → %d ... —— 输出预算触及保底危险区，"
                   "建议压缩上下文或改用大窗口模型", ...)
...
if _fr == "length":
    logger.warning("模型 %s 输出被截断（finish_reason=length, max_tokens=%d）"
                   "—— tool_call 参数或正文可能不完整，建议压缩上下文或分段输出", ...)

chat 与 chat_stream 双路径同标准覆盖。这两条 WARNING 就是五级链 L2、L3 的"指纹采集器"——下次同类事故，日志回溯三步到根因，而不是五层迷宫。

4.4 第 4 层 · 审计层：会话隔离 + TTL 清理（`audit.py` +67/−6）

self._pending_ttl_seconds: float = 1800.0   # 30 分钟

def _purge_expired_pending(self) -> None:
    """清理超过 TTL 仍未收到结果的孤儿 pending。..."""
    ...
    if age > self._pending_ttl_seconds:
        expired_keys.append(k)
    for k in expired_keys:
        orphan = self._pending.pop(k)
        orphan.status = "unknown"
        orphan.error = "TOOL_RESULT 缺失（调用方熔断/异常中断），pending 超时清理"
        ...   # 落库 + WARNING，保持调用计数真实

配对逻辑同步升级：session_id 非空时优先同会话匹配，否则回退全局 FIFO（兼容旧事件）。假成功从此失去生存空间：要么同会话配真对，要么 30 分钟后以 unknown 现身。

4.5 指令层兜底：给任务立"写入纪律"

代码管住了"出事后怎么办"，指令层再管"少出事"——两个任务的 task_instruction 追加 340 字符纪律（脚本幂等落库，934→1274 / 1700→2040）：

第 1 次 file_write 只写 HTML 骨架（≤3000 字符）；此后每次带 append=true 分批追加 ≤3000 字符；最后一次追加收尾标签；写完 file_read 抽查首尾各 20 行。

单次数 KB 的参数变成多次 ≤3KB——从源头退出截断危险区。 file.py 的 write 原生支持 append 模式，零代码变更。

五、验证：13 个新用例 + 一次"存量失败甄别"示范

tests/tools/test_tool_params_hardening.py 13/13 通过，覆盖：

组	用例要点
_load_tool_arguments ×5	合法 JSON / dict 透传 / 截断 JSON 触发 caplog WARNING 断言 / 空串 / 非 dict 顶层
safe_execute ×4	空参返回结构化 ERROR 含分段指引且无 KeyError / 缺 content / 合法执行放行 / read 缺 path
审计 ×4	同会话配对隔离孤儿 / 无 pending 时新建 / TTL 超时清理落 unknown / 未超时不误清

全量回归 450 通过、31 失败——每一个失败都做了归因留档： 27 个 quant（BacktestEngine.run 早已改 async 而测试仍同步调用）、 1 个 scoring 业务断言、3 个 parallel_group mock 缺参，并用 git diff 验证相关行不在本轮变更内。 "我的测试挂了 31 个"与"我的测试挂了 31 个且每个都知道为什么"，是两种完全不同的工程状态。

六、总结与展望

6.1 核心要点回顾

五级放大链：大参数→压缩→截断→静默吞→裸下标，报错与真相零重合—— 修 L5 只是装纱窗，必须层层设防；
三取一铁证法：文件时间戳指纹（CreationTime==LastWriteTime）定案配置突变；
反直觉取舍：不修复截断（宁报错不写残file）；错误消息是给模型的 prompt；
观测系统也是被测系统：审计 FIFO 错配的假成功比缺日志更有害；
声明过的契约要被执行：required_params 存在了半年，这周才第一次上岗。

1 个核心公式：

故障可见性 = 每级放大都有一个"不许静默"的哨兵

6.2 下一步学习方向

📖 下一篇：《WeClaw_108 别猜你的模型预算》——max_tokens=8192 到底是不是真的 8192？两把探针量出精确答案
中期路线图：ToolCallEvent/ToolResultEvent 增加 tool_call_id，配对从"会话+FIFO"升级为精确 ID

下期预告：《别猜你的模型预算》

五档 max_tokens 递增探针 + 三档上下文探针
一次超限请求 = 服务端亲口告诉你精确上限（1,048,576）
实测 0.2046 tokens/字符：官方换算表也有偏差

敬请期待！

附录 A：本篇涉及的代码清单

文件路径	变更	作用
`src/core/agent.py`	+98/−48	`_load_tool_arguments` 统一 8 处解析 + WARNING
`src/tools/base.py`	+35	safe_execute 必填参数校验 + 分段写入指引
`src/models/registry.py`	+63/−10	4096 危险区 WARNING + finish_reason=length 双路径检测
`src/permissions/audit.py`	+67/−6	会话优先配对 + 孤儿 pending TTL 清理
`tests/tools/test_tool_params_hardening.py`	新增	13 用例防线固化

附录 B：参考资料

上一篇：《WeClaw_106 测试的测试》
WeClaw_52《Tool 配对完整性：ReAct Agent 最隐蔽的 Bug》（消息层姊妹篇）
WeClaw_63《确定性约束引擎》（"声明即执行"哲学同源篇）
OpenAI Completion API finish_reason 语义：https://platform.openai.com/docs/api-reference/chat/object
迭代记录：docs/开发记录/v11.17.0_2026-09-13_定时任务大参数截断链四层治本与模型预算实测校准.md

原文链接：https://blog.csdn.net/yweng18

KeyError 的五级放大故障链：模型输出截断如何伪装成"参数缺失"

KeyError 的五级放大故障链：模型输出截断如何伪装成"参数缺失"

📚 专栏信息

👨‍💻 作者与项目

📝 摘要

一、案发现场：一个与真相无关的报错

1.1 用户报告

1.2 三选一定案：先看铁证

二、五级放大链：错误如何改头换面

三、还有一个烟雾弹：审计日志里的"假成功"

四、解决方案：四层防线 + 指令层兜底

4.1 第 1 层 · 解析层：失败必须开口（src/core/agent.py +98/−48）

4.2 第 2 层 · 校验层：死配置第一次真正上岗（src/tools/base.py +35）

4.3 第 3 层 · 观测层：把截断从隐性事实变成显式事件（registry.py +63/−10）

4.4 第 4 层 · 审计层：会话隔离 + TTL 清理（audit.py +67/−6）

4.5 指令层兜底：给任务立"写入纪律"

五、验证：13 个新用例 + 一次"存量失败甄别"示范

六、总结与展望

6.1 核心要点回顾

6.2 下一步学习方向

附录 A：本篇涉及的代码清单

附录 B：参考资料

4.1 第 1 层 · 解析层：失败必须开口（`src/core/agent.py` +98/−48）

4.2 第 2 层 · 校验层：死配置第一次真正上岗（`src/tools/base.py` +35）

4.3 第 3 层 · 观测层：把截断从隐性事实变成显式事件（`registry.py` +63/−10）

4.4 第 4 层 · 审计层：会话隔离 + TTL 清理（`audit.py` +67/−6）