工具调用修复 bojansandhaus/tool-repair-skill-for-hermes-and-opencode

Hermes 和 OpenCode 的工具修复技能

针对 LLM 工具调用的框架层修复方案。它能捕获开放模型常犯的 JSON 格式错误，在工具执行器看到之前就确定性地修好。内置四套智能体框架的适配器：

| 适配器 | 语言 | 修复策略 |
| Hermes（两次调用） | Python | 派发前改写参数，再把修复说明追加到结果里。基于本库自带的 34 项 Python 测试套件和 21 项 TypeScript 对等测试套件构建并测试。 |
| OpenCode（插件） | TypeScript | 用 tool.execute.before 钩子，直接改写参数 |
| Claude Code（钩子） | Bash + jq | PreToolUse 拦截，让模型重试；PostToolUse 做遥测。无法改写参数：PreToolUse 只能放行或拦截，所以这个适配器靠反馈纠正，不能就地修改。 |
| DeepSeek Harness（钩子桥接） | Bash + jq | 用 PreToolUse 命令钩子，注册到框架桥接插件上。同样无法改写参数：这个接缝只允许拒绝，不允许重写。 |

这套方案源自一个让 DeepSeek V4 Pro 在工具调用上超过 Opus 4.7 的做法（见 CommandCode 关于工具调用修复的文章、他们的深度解析，以及这段视频讲解）。

问题所在

开放模型（DeepSeek、GLM、Qwen、Kimi）在工具调用里反复犯同样的小 JSON 错误。每错一次就触发一次校验失败。模型用同样的错误格式重试。会话在 50 多次无用的重试循环里逐渐崩坏。模型始终学不会，因为错误信息根本看不懂。

这些错误不是随机的。它们是有限的一小组模式，来自模型的训练分布从工具边界渗了出来。

框架 vs 模型

大多数人把这当成模型问题：「DeepSeek 工具调用不行，等下一版吧。」这是错的。这是框架问题。框架夹在模型和工具执行器之间，它决定怎么处理模型的输出：拒绝并浪费 token 重试，还是悄悄修好继续走。一个能确定性修复的框架，用大约 200 行代码就能把工具调用很差的模型变成能用的模型。

模型没变。只是框架在恰好需要宽容的地方变得更宽容了。

它应用的修复规则

| 模式 | 模型发来的内容 | 应该是什么 |
| 空值省略 | {"cmd": "ls", "timeout": null} | {"cmd": "ls"} |
| 保留 null | {"name": null}，其中 name 为 required | 原样保留，交给校验器报错 |
| 字符串化的数组 | {"files": "[\"a\",\"b\"]"} | {"files": ["a", "b"]} |
| 空对象 | {"files": {}} | {"files": []} |
| 裸字符串 | {"files": "main.ts"} | {"files": ["main.ts"]} |
| Markdown 自动链接 | {"filePath": "/x/f.md"} | {"filePath": "/x/f.md"} |

工作原理

flowchart TD
subgraph Harness["HARNESS BOUNDARY"]
direction TB
P["Parse JSON"] --> V{"Schema Valid?"}
V -->|"Yes"| D["Execute Tool"]
V -->|"No"| W["Walk Issue List by Path"]
W --> R["Apply Repairsin Priority Order"]
R --> RV{"Re-validate"}
RV -->|"Pass"| D
RV -->|"Fail"| E["Return Readable Errorwith Guidance"]
end

M["Model Output(raw tool call JSON)"] --> P
D --> N["Tool Result+ Repair Note"]
E --> N
N --> B["Back to Model"]

HARNESS BOUNDARY 框里的全部内容都属于你的智能体框架。模型给出原始 JSON，再接收结果。所有修复逻辑、校验和修正说明都在 harness 层处理。

核心设计原则： 只有确定无疑该修时才动手，合法数据才能保住。可能碰到任意内容的规则，都刻意收得很窄。字符串只有在能解析成数组时才按数组解析；自动链接只有在链接文字等于 URL 自身的路径部分时才拆掉；数组形态的修复只在 schema 声明该字段是数组时才触发；null 只在 schema 既不要求该字段、也不接受 null 时才丢弃。所以 writeFile 的内容即使恰好长得像 JSON，真正的 click 链接，以及 [1, 2] and [3, 4] 这类带方括号的普通文本，都会原样通过，测试套件对每一种情况都有断言。

组件

tool_repair.py（核心库）

独立的 Python 模块，除标准库外没有任何依赖。主要入口：

from agent.tool_repair import repair_function_args

repaired_args, repair_notes = repair_function_args(
function_name="readFile",
function_args={"path": "/tmp/test.txt", "limit": None},
tool_schema=None, # optional JSON schema for type-aware repairs
)
repaired_args = {"path": "/tmp/test.txt"}
repair_notes = ["[repair: null values removed for optional fields]"]

任何智能体框架都能导入使用，不限于 Hermes。

Hermes Agent 集成（两处调用）

这个库已经构建并测试完毕：34 个 Python 测试、21 个 TypeScript 对等测试，CI 会跑这两套加上模块自测。要把它接进 Hermes harness，只需在 harness 层、模型输出与工具执行器之间加两处调用：
1. agent/agent_runtime_helpers.py。sanitize_tool_call_arguments() 是 harness 函数，在派发前遍历工具调用。等 json.loads() 成功之后，对解析出的 dict 调用 repair_function_args()。如果触发了修复，就把修好的 JSON 写回该调用的 arguments。

2. agent/tool_dispatch_helpers.py。make_tool_result_message() 是 harness 函数，在工具结果返回给模型之前构建它。在这里调用 deduplicate_repair_notes()，把修复说明追加到结果内容里。

模型会连同成功的结果一起读到修复说明，并在下一轮做出调整。修复是 harness 做的，模型只是看到了修了什么，并从中受益。

Hermes 插件清单

references/plugin.yaml 声明了钩子面（transform_llm_output），plugin-architecture.md 勾勒了接线方式。今天的 pre_tool_call 钩子能拦截调用，但改不了参数，所以上面这套两次调用的集成就是你要写的代码；plugin-architecture.md 描述的是另一种钩子面，有了它就能把这件事变成一个配置开关。

适配其他框架

本仓库在 adapters/ 目录下为另外两个智能体框架提供了适配器。每个适配器都用 harness 专属的接线方式，包装同一个核心库 tool_repair.py。

| 适配器 | 位置 | 关键机制 |
| Hermes | SKILL.md | sanitize_tool_call_arguments 派发前处理 + 修复说明。 |
| OpenCode | adapters/opencode/ | tool.execute.before TS 插件，直接改写参数 |
| Claude Code | adapters/claude-code/ | PreToolUse 拦截 + PostToolUse 遥测（bash + jq） |
| DeepSeek Harness | adapters/deepseek-harness/ | 通过 harness 桥接插件实现的 PreToolUse 命令钩子（bash + jq） |
| 共享检测器 | adapters/shared/detect.sh | 三个 shell 钩子都 source 这一份 bash + jq 选择逻辑 |

OpenCode 的集成最干净，因为它的 tool.execute.before 钩子支持改写参数。Claude Code 和 DeepSeek Harness 限制最多：两者都只能拦截调用，不能改写，所以检测到模式时会白白浪费一轮。DeepSeek Harness 适配器读取的是 harness 自己的载荷键（tool_name、tool_input），所以它单独成了一个脚本，但它的检测器并不是第二份拷贝：adapters/shared/detect.sh 被三个 shell 钩子共同 source，所以改动一处选择逻辑，不会像 v1.0.1 和 v1.0.5 那样落在一个适配器里、漏掉其他几个。

各适配器的安装说明见其 README。

安全保障

- 字符串值的内容不受影响。 字符串化数组规则只对能解析成 JSON 数组的字符串生效，自动链接规则只在链接文本等于 URL 自身的路径部分时生效。像 [1, 2] and [3, 4] 这样的普通文本，以及 click 这样的真实链接，都会原样通过，测试套件对此有断言。
- 非 JSON 工具数据不受影响。 修复层只检查工具调用参数（描述工具该做什么的 JSON dict），不碰工具结果、二进制内容、图片或多模态数据。
- 感知 schema 的数组修复。 数组专属修复（空对象转数组、裸字符串包裹）只在工具 JSON schema 确认该字段期望数组类型时才触发。没有 schema 时，只运行安全的通用修复（去除 null、解析字符串化数组、拆掉自动链接）。
- 无法解析的方括号字符串永远不会被包成数组元素。 [not json] 要么是普通文本，要么是损坏的数组序列化，把它变成 ["[not json]"] 只会产出一个看似合法、实则全是垃圾的调用。这种情况留给校验器去报告。格式错误或布尔值的 JSON Schema 会被跳过，而不是抛错。
- 调用方的 dict 不会被改动。 repair_function_args 会深拷贝输入，所以文档里写的回写模式（if fixed != parsed）确实会触发，而无需修复的工具调用不会产生回写。
- 修复说明会去重。 如果某条修复说明在上一轮已经追加过，就不会再叠加一次。

依赖

核心库（tool_repair.py）除 Python 标准库外不需要任何东西。

| 适配器 | 依赖 |
| Hermes | Hermes Agent（任意较新版本），库本身只用标准库 |
| OpenCode | TypeScript、OpenCode CLI |
| Claude Code | bash、jq |
| DeepSeek Harness | @deepseek-ai/dsh、bash、jq |

核心库不需要 pip 包、不需要 npm 模块、不需要外部服务。

如何安装

核心库（任意框架）

cp references/tool_repair.py /your/project/tool_repair.py

from tool_repair import repair_function_args
fixed, notes = repair_function_args("my_tool", {"some_field": None})

Hermes Agent

复制库文件，然后按「组件」一节所述加入两处调用：

cp references/tool_repair.py /path/to/hermes/agent/tool_repair.py

或者直接提示你的智能体：

克隆 https://github.com/bojansandhaus/tool-repair-skill-for-hermes-and-opencode.git，把 references/tool_repair.py 复制到 Hermes 智能体目录，然后在 sanitize_tool_call_arguments 里、json.loads() 成功之后调用 repair_function_args，并在 make_tool_result_message 里调用 deduplicate_repair_notes。Hermes 没有对应的配置项，需要改这两处代码。

OpenCode

把 TypeScript 适配器复制到你的 OpenCode 插件目录：

cp -r adapters/opencode/* ~/.config/opencode/plugins/

或者直接提示你的智能体：

克隆 https://github.com/bojansandhaus/tool-repair-skill-for-hermes-and-opencode.git，把 adapters/opencode/ 里的 TypeScript 插件复制到 ~/.config/opencode/plugins/。

Claude Code

复制钩子脚本和共享检测器，然后在 claude.json 里配置：

mkdir -p .claude/hooks
cp -r adapters/claude-code adapters/shared .claude/hooks/bash
chmod +x .claude/hooks/claude-code/.sh

钩子从 adapters/shared/detect.sh 读取检测器，这份副本与 DeepSeek Harness 适配器和遥测钩子共用，所以目录结构必须跟着一起带上。如果你把它们装到别处，就设置 TOOL_REPAIR_SHARED_DIR。

或者直接提示你的智能体：

克隆 https://github.com/bojansandhaus/tool-repair-skill-for-hermes-and-opencode.git，把 adapters/claude-code/ 里的钩子脚本复制到 .claude/hooks/，把 adapters/shared/ 复制到它们旁边，给它们加上可执行权限，再把 pre_tool_use 和 post_tool_use 两条钩子条目加到 claude.json。
json
{
"hooks": {
"pre_tool_use": {
"matcher": "",
"command": "bash .claude/hooks/pre_tool_use.sh"
},
"post_tool_use": {
"matcher": "",
"command": "bash .claude/hooks/post_tool_use.sh"
}
}
}

DeepSeek Harness

复制钩子，以及它读取的共享检测器，然后用 harness 自带的某个桥接插件（@deepseek-ai/dsh-hooks-claude-code 或 @deepseek-ai/dsh-hooks-codex）注册它： bash
mkdir -p ~/.dsh/tool-repair
cp -r adapters/deepseek-harness adapters/shared ~/.dsh/tool-repair/
chmod +x ~/.dsh/tool-repair/deepseek-harness/pre_tool_use.sh

写入 ~/.dsh/tool-repair/hooks.json： json {
"hooks": {
"PreToolUse": [
{
"matcher": "",
"hooks": [
{ "type": "command", "command": "bash ~/.dsh/tool-repair/deepseek-harness/pre_tool_use.sh" }
]
}
]
}
}

再把桥接加到 ~/.dsh/cordis.patch.yml： yaml
- id: hooks-claude-code
name: '@deepseek-ai/dsh-hooks-claude-code'
config:
configPath: ~/.dsh/tool-repair/hooks.json

或者直接提示你的智能体：

克隆 https://github.com/bojansandhaus/tool-repair-skill-for-hermes-and-opencode，把 adapters/deepseek-harness/ 和 adapters/shared/ 复制到 ~/.dsh/tool-repair/，保持目录结构不变，给 ~/.dsh/tool-repair/deepseek-harness/pre_tool_use.sh 加上可执行权限，写一个 hooks.json 把它注册为 PreToolUse 命令钩子，并在 ~/.dsh/cordis.patch.yml 里加一条指向它的 @deepseek-ai/dsh-hooks-claude-code 条目。

注意你在跑哪个桥接。Claude Code 桥接会转发整个参数对象，所以每个字段都会被检查。Codex 桥接转发的是 tool_input: {command: commandOf(exec.arguments)}——只有一个字符串——所以那里只能检测 command 形态的缺陷，钩子每次都会在 stderr 上说明这一点。Codex 桥接变体、验证步骤和限制，见 adapters/deepseek-harness/README.md。

克隆仓库 bash
git clone https://github.com/bojansandhaus/tool-repair-skill-for-hermes-and-opencode.git
cd tool-repair-skill-for-hermes-and-opencode

用法

在任何 Python 项目里 python import json from tool_repair import repair_function_args

def dispatch_tool(name, args_json):
args = json.loads(args_json)
if isinstance(args, dict):
fixed_args, notes = repair_function_args(name, args)
if notes:
print(f"Repaired {name}: {notes}")
args_json = json.dumps(fixed_args)
proceed with the tool call

在 Hermes Agent 中

两处调用，分别在 sanitize_tool_call_arguments 和 make_tool_result_message 里，如「组件」一节所示。这里没有配置项，属于 harness 代码。

路线图

- [x] 核心修复库（5 条修复规则）
- [x] Hermes 集成（两处调用：派发前 repair_function_args，拿到结果后 deduplicate_repair_notes）
- [x] OpenCode 适配器（TypeScript 插件）
- [x] Claude Code 适配器（bash + jq 钩子）
- [x] DeepSeek Harness 适配器（bash + jq 钩子，经由桥接插件）
- [x] 感知 schema 的修复（数组字段，以及 required/nullable 的空值安全）
- [ ] 按模型统计修复遥测（仪表盘标签页）
- [ ] 按模型定制的修复配置档（DeepSeek、GLM、Kimi 的怪癖）

许可证

MIT。可自由使用、修改和分发。这是对 CommandCode 团队发现的模式做的直接实现。原始洞见归功于他们。