tool-call-repair

Tool Call Repair — 工具调用输入修复管线

概述

当 LLM 输出工具调用参数时，频繁出现四种可穷举的结构性错误。不是模型能力问题，是合约设计问题。此 skill 提供一套 validate-then-repair 管线，在 Zod/JSON Schema 校验失败时自动修复可恢复的输入噪声，并记录修复率遥测数据。

核心理念

严格的 Schema 是一种有代价的选择——它过滤了噪声，也过滤了任何没有背下这个特定 JSON 合约的模型产生的可恢复噪声。

validate-then-repair > preprocess-then-validate：让校验器先报错，Schema 本身就是"哪里会坏"的先验，修复预算只花在校验器实际不同意的精确路径上。

---

工作流决策树

LLM 输出 tool call 参数
        │
        ▼
  按原样解析 (parse as-is)
        │
   ┌────┴────┐
   ▼         ▼
 成功       失败
   │         │
   ▼         ▼
直接执行   遍历 Zod issue list
           │
           ├─ 形状问题 ──→ 四项修复（按顺序尝试）
           ├─ 链接泄漏 ──→ Markdown 链接解包
           └─ 关系问题 ──→ 扩展语义 + 默认值
                │
                ▼
           再次解析
           ┌───┴───┐
           ▼       ▼
         成功     失败
           │       │
           ▼       ▼
    记录 repaired  记录 invalid
    执行工具       返回模型可读的重试消息

---

1. 四项通用形状修复

这是覆盖 ~90% 开源模型工具调用失败的模式集合。四项修复共享一个结构：输入 JSON、Zod 报出的 issue 路径、尝试修复 → 返回修复后 JSON 或 null。

修复 1: 剥离 null 值

模型常对可选字段发送 null 而非省略。

# 修复前: {"limit": null, "query": "hello"}
# 修复后: {"query": "hello"}

修复 2: 解析字符串化的 JSON 数组

模型把数组序列化为 JSON 字符串。

# 修复前: {"filePath": "[\"a\",\"b\"]"}
# 修复后: {"filePath": ["a", "b"]}

修复 3: 解包多余的外层对象包装

单参数被包在 {} 里。

# 修复前: {"args": {"query": "hello"}}，但 schema 期望 args 是 string
# 修复后: {"args": "hello"}

修复 4: 裸值包装为单元素数组

# 修复前: {"paths": "foo"}
# 修复后: {"paths": ["foo"]}

⚠️ 执行顺序（关键）

修复 2 必须在修复 4 之前运行。否则：

输入: {"paths": "[\"a\",\"b\"]"}
先执行修复4 → {"paths": ["[\"a\",\"b\"]"]}  ← 错误！
先执行修复2 → {"paths": ["a", "b"]}          ← 正确

使用方式

调用 scripts/repair.py：

python scripts/repair.py \
  --input '{"filePath":"[\"a\",\"b\"]"}' \
  --schema-path schema.json \
  --tool-name writeFile

输出 JSON：

{
  "repaired": true,
  "output": {"filePath": ["a", "b"]},
  "repairs_applied": ["json_array_parse"],
  "telemetry": "tool_input_repaired:writeFile"
}