本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

dsh-tool-diff

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add github:omdsh-dev/dsh-toolkit#path:packages/dsh-tool-diff

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

常见问题

安装后注册了什么？

在 profile layer stack 插入 row id 为 tool-diff 的工具（工具名 diff），并附带一个 diff-invariant companion 插件用于声明 invariant 所有权（runtime 不做事）。dsh --dump-config | grep tool-diff 应能看到这一行。

为什么不直接调 bash diff？

系统 diff 每次起一个 bash 子进程（Windows 上尤其昂贵），且完全不懂结构：JSON 只能给整段文本 diff，看不到 $.user.name 这种路径级变更；CSV 不知道列对应关系。本插件是纯函数、零依赖，一次函数调用毫秒返回结构化 JSON。

patch action 会不会写文件？

不会。patch action 只在内存中按行级坐标把 hunks 应用到 before 并与 after 逐行比对，输出 valid/targetMatchesAfter/errors 等字段。没有 git apply、没有 fs 写入，完全只读。

输入内容大就报错，怎么办？

单侧输入硬顶 256 KiB（UTF-8 字节），超限直接抛 diff: before input exceeds 256KiB；最终 JSON 输出硬顶 64 KiB，超出会用 maxChanges 与字节二分截断并在信封里置 truncated:true。行数 ≤ 50K、JSON 嵌套 ≤ 64 层、CSV ≤ 50K 行 / 512 列。

CSV 含中文/逗号/换行的字段能比对吗？

可以。CSV 解析按 RFC 4180：引号包裹、"" 转义、CRLF/BOM、引号内换行都已处理。分隔符可改为 tab；不传 key 时按行号位置比较，传入列名后按主键匹配（行顺序无关）。

web profile 和 headless profile 区别？

DSH 把交互式 UI（web）和一次性命令跑（headless）拆成两个独立 profile，插件需要各自安装一次；dsh run 默认走 headless，所以想让 LLM 在 CLI 调用 diff 工具也得在 headless profile 装一次。

JSON 里的重复 key 会丢吗？

不会。解析时遇到重复 key 照常解析，但解析后会在结果里以 duplicateKeys.before / duplicateKeys.after 分别报告并把 equal 标 false，不静默吞错。

如何验证安装与运行？

验证安装：dsh --profile web --dump-config | grep tool-diff 应有输出。验证调用：dsh run "用 diff 工具对比两段文本"，LLM 会触发 diff(before, after, action='text')。

— 源: plugin_wiki.faq_json

兼容性

• DSH: >=0.1.0-rc.8
• Node: ^22.19.0 || >=24.0.0

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则