DS2API JSON修复工具 repair_json_tool 源码剖析：3 层修复策略全解-平芜编程栈

DS2API JSON修复工具 repair_json_tool 源码剖析：3 层修复策略全解

【免费下载链接】ds2apiDeepSeek-Compatible Middleware Interface: A technical exploration project in Go, focusing on high-concurrency protocol adaptation. It serves as a reference implementation for converting diverse web protocols into standardized formats.项目地址: https://gitcode.com/GitHub_Trending/ds/ds2api

你是否遇到过 AI 模型返回的工具调用参数无法解析的情况？DS2API 是一个将 DeepSeek 协议转换为 OpenAI / Claude / Gemini 等标准格式的中间件，其中最有代表性的"救火"模块就是 JSON 修复工具repair_json_tool及其背后的三级修复策略：非法反斜杠修复、宽松 JSON（Loose JSON）修复、路径控制字符转义。本文带你用最少代码量，读懂这套修复体系的设计思路。

为什么大模型输出需要"JSON 修复"

当模型通过工具调用（Function Calling / Tool Calls）执行任务时，参数必须以合法 JSON 传递。但真实场景中模型经常"手滑"，DS2API 在 docs/toolcall-semantics.md 中明确列出了两类典型失误：

Windows 路径反斜杠：模型输出{"path": "C:\Users\name"}，其中\U、\n会被 JSON 解析器当成非法转义，直接解析失败；
列表"幻觉"：DeepSeek 有时把数组写成连续的对象列表，例如"todos": {"a": 1}, {"b": 2}，缺少数组的[]包裹。

这些错误单独看都不致命，但一旦出现，整个工具调用就会静默失败。DS2API 的解法不是"让模型别犯错"，而是在解析层加一条逐级降级的修复流水线。

修复策略一：非法反斜杠修复

核心函数repairInvalidJSONBackslashes位于 internal/toolcall/toolcalls_json_repair.go，思路非常直观：

逐个扫描字符，遇到\就检查下一个字符；
如果是 JSON 合法转义（\"\\\/\b\f\n\r\t），原样保留；
如果是合法的\uXXXX十六进制序列，也原样保留；
其余情况——也就是"非法反斜杠"——一律加倍成\\，让它降级为普通字符。

举例：{"path": "D:\git_codes"}会被修成{"path": "D:\\git_codes"}，既合法又不改变原意。值得注意的是函数开头的快速短路：字符串里没有反斜杠就直接返回，保证正常流量的零开销。

修复策略二：宽松 JSON（Loose JSON）修复

RepairLooseJSON同样定义在 internal/toolcall/toolcalls_json_repair.go，用两条正则处理两类"偷懒写法"：

问题形态	示例	修复结果
键名未加引号	`{name: "search"}`	`{"name": "search"}`
数组缺少方括号	`"todos": {"a": 1}, {"b": 2}`	`"todos": [{"a": 1}, {"b": 2}]`

其中第二条正则是专门针对 DeepSeek "列表幻觉"定制的，甚至支持元素内部再嵌套一层{}对象（例如"input": {"q": "y"}），源码注释里写得很清楚。docs/TESTING.md 中对TestRepairLooseJSONWithNestedObjects测试用例的说明也印证了这一点。

修复策略三：路径控制字符转义

前两条策略在"解析之前"对字符串动刀，第三条则发生在"解析之后"，见 internal/toolcall/toolcalls_input_parse.go：

递归遍历解析出的参数树；
只针对键名包含path/file的字符串字段；
若其中含有控制字符（如真实换行、Tab），转义成\n、\t等 JSON 写法。

这个"外科手术式"的限定很关键——只修路径类字段，避免误伤content这类本来就合法含有转义序列的字段。对应的测试TestParseToolCallInputRepairsControlCharsInPath同时断言了 path 被修复、content 保持原样。

三级修复的调用顺序：先试后修，逐级降级

真正把这些策略串起来的是parseToolCallInput（internal/toolcall/toolcalls_input_parse.go），它遵循"能直接解析就绝不修"的原则：

直接json.Unmarshal—— 合法 JSON 走最快路径；
反斜杠修复后重试—— 针对 Windows 路径场景；
Loose JSON 修复后重试—— 针对未加引号键名、缺方括号场景；
全部失败则兜底—— 返回{"_raw": 原始字符串}，把原始文本交还给下游逻辑，绝不丢数据。

同样的"直接解析 → 反斜杠修复 → Loose 修复"三级链也复用在数组参数解析 internal/toolcall/toolcalls_array_parse.go 中，保证了对象参数与数组参数行为一致。

独立自测工具与回归测试

tests/repair_json_tool.go 是一个可以单独运行的迷你验证程序，内置了 6 组典型输入（Windows 路径、合法\n、合法\u2705、非法\u123等），逐条打印 PASS / FAIL。它和主包中的实现保持同步，方便在不动整个服务的情况下快速验证反斜杠修复逻辑。

正式的回归测试集中在 internal/toolcall/toolcalls_test.go：

TestRepairInvalidJSONBackslashes：6 组反斜杠边界用例；
TestRepairLooseJSON/TestRepairLooseJSONWithNestedObjects：10+ 组宽松 JSON 用例，含真实的 DeepSeek 8 皇后问题输出快照；
TestParseToolCallInputRepairsControlCharsInPath：路径控制字符的"修与不修"边界。

这种"真实故障快照 + 边界回归"的测试思路，让每一次上游模型输出行为变化都能被及时捕获。