dsh-tool-call-guard

中文 | English

在 tool call 的 arguments 到达 wire 之前，把其中 JSON 不合法的调用中性化——避免一次模型的畸形输出毁掉整个 session。

dsh plugin add dsh-tool-call-guard

为什么需要它

部分模型偶尔会生成 arguments 不是合法 JSON 的 tool call——最常见的是内部引号未转义：

{"queries": [""The Idiots" 预告片 youtube 官方"]}

严格的 OpenAI 兼容服务端（vLLM 等）对此是双重标准：

• 流式生成路径——宽松。畸形调用流出来、被 harness 持久化进追加式 session 日志，当轮看起来一切正常。
• 历史回放路径——严格。下一个请求回放这条毒化 tool call，服务端校验后拒绝整个请求：

400 {"message": "Assistant tool call function.arguments must be valid JSON.",
     "type": "BadRequestError"}

从此该 session 每次请求都会失败，除非手工修复日志。同类问题在各生态都存在（openai-agents-python #2061、vLLM #41122）。

它做什么

消毒跑在 adapter 的消息序列化层（各 adapter 把 harness 消息转成 wire 格式的地方），对每个请求应用两条规则：

⚠️ 为什么不在 llm/stream waterfall 上做？ 我们最初就挂在那里，实测行不通：harness 在派发前对整个请求（含 messages）deepFreeze，且 cordis waterfall 的 next() 丢弃传给它的参数——dispatch 闭包永远拿到原始 argv；严格模式 ES module 对冻结对象赋值会 throw。这个 waterfall 实际是只读的，文档没有写明（我们用运行时探针验证的）。因此插件在 waterfall 上只做探测器（发现非法 arguments 时打 warn），真正中性化在 adapter 序列化层完成。对每个 arguments 过不了 JSON.parse 的 assistant tool-call 块：

1. 调用变成一条诚实的文本记录（仅 wire 层）——模型能看到自己当时发出的原文，可以重新发起正确的调用：

   [A tool call to 'web_search' was removed from history because its arguments
   were malformed JSON. Original arguments as emitted: {"queries": [""The Idiots" …]}]

2. 配对的工具结果改写为普通用户消息——结果内容保留，且会话保持协议平衡（不留悬挂 tool_calls，也不留孤儿 role:"tool"——这两者在严格服务端各自都是 400）：

   [Tool Result: web_search] 10 results about The Idiots

孤儿结果转用户消息的写法沿用上游 serializer 讨论（deepseek-harness #4668）。

特性

• 干净历史零开销——每个 tool-call 块一次 JSON.parse；无问题时不碰任何对象。
• 尊重追加式日志——从不改写持久化 session 日志，中性化只在每次请求的 wire 层动态生效。
• Provider 无关——挂在 llm/stream，覆盖所有适配器。
• 失败放行——guard 自身出错时原样透传请求。
• 零配置——装上重启即生效。

安装

dsh plugin --profile web add dsh-tool-call-guard
# 或 desktop：
dsh plugin --profile desktop add dsh-tool-call-guard

或从 GitHub 安装：dsh plugin add github:alchemistwu/dsh-tool-call-guard。

包内声明了 dsh.bundle patch，安装即自动注册。重启 dsh web / DSH Desktop 后开新 session 生效。

生产实测

首发场景：vLLM 0.27（--enable-auto-tool-choice）部署的 zai-org/GLM-5.3-Flash，一次 web_search 调用里电影名引号未转义——流式正常、被持久化、之后该 session 每轮 400。装上本插件后 session 复活：毒条目在每次请求中被改写为诚实记录，模型在上下文里能看到自己当时的错误。

测试

npm test

九个用例覆盖真实生产毒数据、好坏调用混合、协议平衡不变量（wire 上不出现非法 tool_calls、不出现孤儿 role:"tool"）、退化输入、每请求状态重置。

许可

MIT