dsh-text-diff

dsh-text-diff

两文本 / 两文件 / 多文件批量的行级 diff 插件（dsh / DeepSeek Harness）。基于 LCS（最长公共子序列）动态规划，输出 unified diff 格式变更块，支持空白归一、移动检测与概览统计。零依赖，与 dsh-diff-writer 组成找差-修复闭环。

安装

npm install dsh-text-diff

cordis.patch.yml 已随包声明，dsh 宿主加载后自动注册 diff_text / diff_files。

工具

diff_text — 行级 diff

参数	类型	说明
a_text / a_file	string	文本或文件路径（A 侧，二选一）
b_text / b_file	string	文本或文件路径（B 侧，二选一）
context	number	每个变更块的上下文行数（默认 3，0 只显示变更行，上限 50）
ignore_whitespace	boolean	可选，忽略行首尾空白差异（尾空格/前导缩进变化不算变更，默认 false）
move_detection	boolean	可选，移动检测：同一内容块被移走记为移动而非删除+新增（默认 true）
stat	boolean	可选，概览模式：只输出统计与相似度，不输出 diff 内容（默认 false）

diff_text { a_file: "a.js", b_file: "b.js" }
diff_text { a_text: "old code...", b_text: "new code..." }

输出格式：

diff: +1 -2（8 行未变，1 个变更块，上下文 1 行）

@@ -3,3 +3,2 @@
 keep2
-old-a
-old-b
+new-a
 keep3

一致性时返回 两份内容完全一致（N 行）。；A/B 侧为空时另一侧全部记为 add/del。

移动块（v0.2）：内容完全相同的删块与增块两两配对后以 ~ 标注，不计入 +/-，并注明来源行与目标行：

diff: +0 -0，其中 2 行为移动（~ 标注，1 个块）（4 行未变，1 个变更块，上下文 3 行）
~2  （移至第 5 行）
~3

diff_files — 多文件批量对比（v0.2 新增）

参数	类型	说明
a_files	string[]	文件 A 路径列表（必填，与 b_files 等长、按序配对）
b_files	string[]	文件 B 路径列表（必填，与 a_files 等长、按序配对）
context / ignore_whitespace / move_detection / stat	同上	与 diff_text 同口径

diff_files { a_files: ["src/a.js", "src/b.js"], b_files: ["new/a.js", "new/b.js"], stat: true }

输出为「总览 + 逐文件对结果」：

多文件对比: 2 对文件，1 对有差异 / 1 对一致；合计 +2 -1
[1/2] src/a.js ↔ new/a.js：一致（12 行）
[2/2] src/b.js ↔ new/b.js
diff: +2 -1（...

约束

• 输入文本上限 1MB，单行上限 3000 行（LCS 矩阵内存约 9MB）
• 超长输出截断到 8000 字符并提示
• CRLF/LF 已归一，跨平台比较无需预处理
• diff_files 单次上限 20 对文件，每文件同受 1MB / 3000 行限制
• 移动检测是启发式：以“内容完全相同的删块/增块两两配对”为准，被改过内容的移动块会退化为删除+新增；可用 move_detection: false 关闭

与其他插件配合

• 找差-修复闭环：diff_text 定位差异 → dsh-line-ops extract_lines 查看上下文 → dsh-diff-writer apply_patch 精确修复
• A/B 均为大文件时复杂 diff 建议改用 git 本地 git diff（可通过 dsh-git-helper 触发）

测试

npm test

RoadMap

v0.2（已落地于 0.2.0）

• 文件级别 diff（多文件批量对比）
• --stat 概览模式（仅统计不显示内容）
• 忽略空白差异（尾空格 / 前导缩进变化不算变更）
• 移动检测（同一块被移走记为 move 而非 del+add）

v0.3（展望）

• 词级 / 字符级 diff：行内高亮，适合散文与只改半行的配置项
• 相似度阈值：行内容轻微改动不再整行判为 del+add
• 三路 diff（base / ours / theirs）：合并冲突预览
• 结构化 JSON 输出（hunk / 行号 / 变更类型），便于 CI 与其他插件消费

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-text-diff
• npm：https://www.npmjs.com/package/dsh-text-diff

典型场景

1. 修改前后对比

用户：这两段文本差在哪

diff_text 基于 LCS 输出统一 diff（keep/del/add），按上下文拆 hunk。

2. 确认改动范围

用户：我只想改一行，看看实际改了几行

先 diff 再决定是否落盘，避免误改。

3. 与 git 差异互相印证

用户：git diff 和实际内容对得上吗

把两段文本交给 diff_text，与 dsh-git-helper 的 git_diff 交叉验证。

4. 配置漂移检查

用户：两个环境的配置文件差多少

对两份配置做文本级 diff；结构化比对可改用 dsh-json-yaml-toolkit 的 diff_data。

安全边界

• 只读：仅比较传入文本，不读写文件。
• 空文本语义明确：空字符串视为"已提供的空文本"（非"未提供"），因此"空 vs 非空"会正确报告为全部新增/删除，而不会被误判为一致。
• 规模保护：LCS 为 O(n×m) 算法，超长文本会受上限保护以避免长时间占用（大文件建议先按行切片）。
• 不做语义比较：只做文本级差异，不理解配置语义。

其他插件集成说明

协作插件	集成方式
dsh-diff-writer	本插件负责"看差异"，diff-writer 负责"改文件"，两者配套使用
dsh-git-helper	git_diff 看工作区差异，diff_text 看任意两段文本差异
dsh-line-ops	大文本先按行切片再 diff，控制计算量
dsh-json-yaml-toolkit	结构化数据用 diff_data（按路径），纯文本用本插件
dsh-hash-checksum	二进制或大文件场景用摘要比对更高效

版本说明

• 0.1.0：初始版本——diff_text 基于 LCS 的统一 diff（hunk 拆分、上下文控制）。
• 0.2.0：按 v0.2 RoadMap 迭代——新增 diff_files 多文件批量对比、stat 概览模式（含相似度）、ignore_whitespace 忽略首尾空白、移动检测（~ 标注，可关闭）。

FAQ

Q：空字符串和"没传"有什么区别？ 空串是合法输入（表示空文本），未提供才会报错。因此"空 vs 有内容"会正确显示为全部新增/删除。

Q：大文件 diff 很慢？ LCS 复杂度与两段长度乘积相关。建议先用 dsh-line-ops 切片，或对大文件改用哈希比对。

Q：输出是标准 unified diff 吗？ 是按 hunk 组织的 keep/del/add 序列，便于直接阅读；与 git diff 格式接近但非逐字节兼容。

Q：CRLF 会误判为差异吗？ 比较前会做换行归一处理，避免因换行符差异产生整篇红绿。