monotykamary/dsh-tool-repair

🩹 dsh-tool-repair

面向 DeepSeek Harness 的 schema 引导式工具调用修复

_先验证。只修复明确无歧义的部分。在任何内容执行之前再次验证。_

checks
npm
DeepSeek Harness
license

dsh-tool-repair 是一个原生 Cordis 插件和 DSH bundle，用于处理那些几乎构成有效工具调用的 provider 输出。它包装了 provider 中立的 llm/stream waterfall，根据该请求中发送的精确 schema 检查最终确定的工具调用块，并且仅当 DSH 的权威 JSON Schema 验证器接受结果时才提交修复。

该插件是一个外部配套组件，而非 Harness monorepo 中的某个包。官方 DSH 应用固定其测试所用的版本，并将该 bundle 分层纳入其发布的 Web 和 Headless profile，而本仓库则保持自己的发布和维护周期。

为什么在这个时间点修复？

flowchart LR
Model[Model / gateway] --> Stream[DSH llm/stream]
Stream --> Check{Exact request schema}
Check -->|valid| Same[Byte-for-byte passthrough]
Check -->|recoverable| Repair[Deterministic repair]
Repair --> Recheck{Revalidate}
Recheck -->|valid| Log[assistant/message + tool/call]
Recheck -->|invalid| Reject[Fail closed]
Log --> Runtime[DSH ToolRuntime]
Runtime --> Policy[Policy + tool body]

如果在 ToolRuntime 启动之后才修复，就会让持久化的 assistant 消息与已执行的内容不一致。如果在 provider 完成之前修复，就会根据不完整的 JSON 进行猜测。最终确定的 block-end 是第一个同时具备完整调用、请求的 schema 快照，以及在 agent 循环记录消息之前替换 provider 重放元数据的时间的时点。

它修复什么

| 输入问题 | 行为 |
| --- | --- |
| 有效参数 | 原样逐字节返回，不做更改。 |
| 平衡但格式错误的 JSON | 通过 jsonrepair 修复，然后进行 schema 验证。 |
| 位于键或值边界的 GLM  /  包装 | 仅对已配置的 provider/model 路由剥离，且仅在结果通过验证时进行。 |
| 完整的 GLM 键/值参数对 | 当每个键/值标签都完整，且剩余的信封命名了同一工具时，进行解码。 |
| 作为 null 发送的可选属性 | 当该属性非必需且其 schema 拒绝 null 时，将其移除。 |
| 作为 JSON 字符串发送的数组/对象 | 当属性 schema 接受解析后的集合时，进行解析。 |
| 已知的备用字段名 | 仅通过显式的逐工具别名映射重命名，且仅重命名为实时 schema 中的属性。 |

它拒绝猜测的内容

- 缺失的必需操作值绝不会被凭空捏造。
- 未知字段绝不会为了强制通过验证而被丢弃。
- 字段名绝不会进行模糊匹配。
- 被截断的字符串、对象、数组、程序、命令和文件内容绝不会被自动闭合。
- 值中间的语法标记不会被切除。对于已配置的路由，残留标记会交给单调的 ToolRuntime 守卫，并在工具主体执行前被拒绝。
- 键冲突会拒绝候选对象，而不是选择其中一个胜出者。
- 作为普通助手散文泄露的完整工具语法不会被转换为工具调用。此包修复的是最终确定的工具调用参数，而非自由文本。

这些规则对于会修改状态的工具尤为重要：schema 有效性无法证明自动补全的文件主体或命令包含模型的完整意图。

安装

要求：Node.js ^22.19.0 || >=24、此检出使用 pnpm 11、DeepSeek Harness ^0.1.0-rc.7 以及 Cordis ^4.0.1。

该包已包含在经测试的 DSH 发行版中。对于其他配置文件或检出：

Registry install into one profile
pnpm dlx @monotykamary/dsh@0.1.0 plugin --profile web add dsh-tool-repair

Local development checkout
pnpm install
pnpm run install:local

本地安装器会构建该包，记录它替换的任何依赖，通过 DSH 插件命令链接此检出，并验证一行处于活动状态的 dsh-tool-repair。它绝不会启动或重启 DSH。安装后重新加载所选配置文件。

其他配置文件、主目录和卸载

pnpm run install:local -- --profile headless
DSH_HOME=/path/to/home pnpm run install:local -- --profile web
pnpm run install:local -- --skip-build
pnpm run uninstall:local -- --profile web

卸载器仅移除经证实属于此检出的本地链接，并恢复之前确切的依赖规范。

配置

该 bundle 插入一行，id 为 dsh-tool-repair。后续的配置文件补丁可以替换其配置：

- id: dsh-tool-repair
config:
grammarLeakModels:
- glm
repairJsonSyntax: true
dropOptionalNulls: true
parseStringifiedCollections: true
aliases:
read:
path: [file_path, filePath]
debug: false

| 键 | Bundle 值 | 含义 |
| --- | --- | --- |
| grammarLeakModels | [glm] | 不区分大小写的子字符串，与 provider/model 匹配；只有匹配的路由才会接受语法令牌处理。 |
| repairJsonSyntax | true | 仅当输入通过平衡容器检查后，才允许使用 jsonrepair。 |
| dropOptionalNulls | true | 将不符合 schema 的 null 可选属性视为已省略。 |
| parseStringifiedCollections | true | 仅在属性要求数组或对象的位置解析内嵌 JSON。 |
| aliases | {} | 显式的 tool → canonical field → aliases[] 映射。不存在隐式别名。 |
| debug | false | 记录工具标识、状态、规则名称和有界诊断信息；参数永远不会被记录。 |

空的 grammarLeakModels 列表会禁用标记特定的变更，同时保持 schema 引导的 JSON 和集合修复处于启用状态。未知配置键会导致插件加载失败。

修复生命周期

1. 从不可变的 GenerateOptions 请求中快照工具 schema。
2. 让已配置的适配器通过调用 next() 生成其流。
3. 严格解析每个最终确定的工具调用。无效输入可以使用完整的 GLM 对解码或平衡 JSON 语法修复。
4. 对于已配置的语法泄漏路由，规范化精确的键/值边界包装器，并拒绝残留标记或冲突。
5. 应用显式别名和 schema 导向的可选 null 或集合规范化。
6. 根据请求 schema 重新验证。只有在验证成功后，才会发出更改后的调用。
7. 在任何调用发生更改后丢弃响应重放信封，因为提供商私有元数据描述的是原始内容。
8. ToolRuntime 会根据实时定义再次验证修复后的参数，并保留所有常规策略、审批、超时、沙箱、日志和结果行为。

工具定义可能在响应流式传输期间发生变化。根据请求快照进行验证可确定模型被要求生成的内容；ToolRuntime 随后根据当前定义进行的验证对于执行仍然具有权威性。

模型体验

模型可见行为

该插件不添加任何提示词部分，也不更改任何工具 schema。有效调用和普通助手文本保持不变。恢复的调用会像提供商发出了规范 JSON 一样继续进行。有歧义的已配置语法泄漏会返回一个正常的被拒绝工具结果，说明必须重新生成完整调用。

Token 影响

没有稳态提示词成本。成功的修复可以避免一次完整的错误并重试的模型往返；无法修复的调用只会增加 DSH 已返回的普通有界工具错误。

KV 缓存影响

无。请求前缀、工具 schema 和系统提示词均未改动。修复仅影响新生成的助手后缀。

编程 API

import { repairToolCall } from 'dsh-tool-repair'

const outcome = repairToolCall({
name: 'read',
arguments: '{"path":"README.md"}',
schema: request.tools?.find(tool => tool.name === 'read'),ts
grammarLeak: true,
config,
})

if (outcome.status === 'repaired') {
console.log(outcome.arguments)
}

该包还导出了 repairToolCallStream 和 BlockedCallStore，用于经过测试的嵌入。这些 API 接受 DSH 的公共消息、schema 和流类型；它们不会构建另一个注册表或执行管线。

开发与发布
bash
pnpm install --frozen-lockfile
pnpm run check

检查确切的 npm 载荷；prepack 会再次运行完整检查
pnpm pack --dry-run

在仓库和 npm 元数据就绪后发布
pnpm publish --access public

pnpm run check 会对源码进行类型检查，生成声明文件和 ESM 运行时打包产物，运行完整测试，并验证构建后的导出、打包产物元数据、必需文件，以及不存在 Pi 宿主依赖或源码检出路径。

已知限制与推迟的工作

- 该插件只能修复 DSH 适配器所暴露的数据。如果上游库在发出最终块之前就抛出异常，则必须在该适配器或提供方解析器中修复。
- 有意不实现文本到工具的语法恢复；添加该功能需要在混合的散文和工具信封之间保留块顺序、调用 ID、结束原因和重放语义。
- 路由匹配使用显式的不区分大小写子字符串，而非正则表达式，这样无效模式就不会破坏插件加载，也不会把宽泛的表达式变成意外的变更。
- 包含字面语法 token 且符合 schema 的字符串，在没有路由知识的情况下，与提供方泄漏无法区分。请将 grammarLeakModels 配置得尽量狭窄，尤其是当 agent 编辑关于这些 token 的文档时。

与其他项目的关系

- pi-tool-repair 为 Pi 确立了先验证后修复的策略，并提供了此处改编使用的提供方损坏语料库。
- dsh-fabric 负责 Fabric 可选的推断 run_code 标签。表面性的标签缺失在那里解决；本包处理提供方序列化损坏，而不伪造缺失的工作输入。
- dsh-fovea 确立了单包外部 DSH 打包、包验证器以及所有权安全的本地安装器约定。
- DeepSeek Harness 负责请求 schema、会话日志、ToolRuntime 验证、策略和执行。

许可证与致谢

MIT © Tom Nguyen。参见 LICENSE 和 THIRD_PARTY_NOTICES.md。