前言¶

在 DSH 插件体系中，Agent 经常需要比较两份内容：配置片段、接口响应、表格或文档修订。dsh-tool-diff 是 omdsh-dev 维护的一个 DSH Diff 文本差异工具插件，用于把这类比较收敛为一个只读、纯函数、零依赖的 diff 工具。

下面介绍它的定位、安装方式、典型用法和使用边界。

这是什么¶

dsh-tool-diff 提供文本 / JSON / CSV / Markdown 结构化比较，并生成 unified diff。

它注册 diff 工具，row id 为 tool-diff，许可为 MIT。

核心功能¶

diff 工具支持以下 action：

• text：文本比较。
• json：JSON 结构化比较。
• csv：CSV 结构化比较。
• markdown：Markdown 结构化比较。
• patch：生成 unified diff，并在内存中校验，绝不落盘。

所有 action 都会输出 JSON 文本字符串信封，并带有通用摘要：

{
  "equal": true,
  "truncated": false,
  "beforeBytes": 128,
  "afterBytes": 132,
  "changes": []
}

其中字段含义如下：

• equal：两侧内容是否相等。
• truncated：输出是否被截断。
• beforeBytes：before 侧字节数。
• afterBytes：after 侧字节数。
• changes：变更列表。

安装与启用¶

先安装到目标 profile，再验证插件是否已注册。

已核实的 headless profile 安装命令为：

dsh plugin --profile headless add github:omdsh-dev/dsh-tool-diff

注意：

• web 与 headless 是不同 profile。
• web 安装不会自动覆盖 headless。
• dsh run 默认使用 headless profile。
• 如果目标 profile 是 web，需要单独为 web profile 安装。

在 web profile 安装后，可以用下面命令确认工具 row 已出现：

dsh --profile web --dump-config | grep tool-diff

运行验证：

dsh run "使用 diff 工具对比两段文本"

典型用法¶

调用 diff 工具时，需要填写以下字段：

1、action：选择比较类型，支持 text、json、csv、markdown、patch。

2、before：原内容。

3、after：新内容。

可选字段：

• format：支持 unified、structured、both。
• unified 默认用于 text / patch。
• structured 默认用于 json / csv / markdown。
• key：CSV 场景可用 key 指定主键列名或 1-based 索引；缺省按位置比较。

下面是一个最小调用要求：

使用 diff 工具对比两段文本

适用场景与注意¶

适合以下场景：

• 需要比较两份文本、JSON、CSV 或 Markdown 内容。
• 需要生成 unified diff。
• 需要只读、纯函数、零依赖的差异比较工具。
• 不希望 patch 文件落盘，只希望在内存中生成并校验。

使用边界：

• 只读：不读文件、不写文件、不联网、不调用 git。
• patch 只在内存中生成并校验补丁，绝不落盘。
• 输入单侧限制为 256 KiB。
• 输出限制为 64 KiB。
• timeoutMs 为 2000。
• 工具参数会记入会话日志，不要传入敏感数据。
• 插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。

参考¶

GitHub 仓库：

https://github.com/omdsh-dev/dsh-tool-diff