前言¶
DeepSeek Harness (DSH) 提供了字符串级别的 edit 和 write 工具，但缺乏将结构化统一差异（unified diff）写入磁盘的工具。apply-patch 插件填补了这一空白：它解析统一差异，应用每个补丁块，保证原子性（全部或全无），并记录反向补丁以实现精确的撤销。
核心功能¶
插件支持完整的 git diff 覆盖，包括多文件、多块、重命名、复制、权限变更、二进制文件标签以及带有空格的引用路径。
它使用自实现的解析器，该解析器不依赖重型库，并严格验证补丁块头部的实际行数，对格式错误的输入报错。
在定位补丁块时，它支持精确匹配、行偏移修正和模糊匹配（GNU-patch 风格），并保证删除操作绝不会在模糊匹配中被错误应用。
操作采用原子性：在写入任何内容之前，每个文件都在内存中解析和验证。任何补丁冲突或结构违规都会导致零写入。
它包含版本控制，使用与官方 DSH 文件系统相同的标识符配方（dev:ino:size:mtimeNs:ctimeNs），并在发布时重新检查标识符，在发生漂移时中止。
它在修改之前计算反向补丁，并在写入前写入撤销日志。undo 恢复字节完全相同的状态。这适用于创建、删除、重命名、复制和模式变更。
它支持干运行模式，静态验证适用性并报告冲突，而无需接触磁盘。
它维护 CRLF/LF 保真度，按行建模文件及其终止符，确保未触及的区域按字节往返传输。
它提供二进制安全，跳过标记为二进制的文件，检测针对二进制目标的文本补丁（NUL 字节 / 无效 UTF-8）并跳过它们，而不会损坏文件。
安装与启用¶
插件通过以下命令安装：
dsh plugin --profile <name> add github:JohnXu22786/apply-patch
安装后，四个工具立即在 Harness 工具注册表中可用。
典型用法¶
插件提供三种主要使用方式：DSH 工具、CLI 和库。
DSH 工具¶
在 DSH 配置或提示词中使用以下工具：
* patch_apply：应用统一差异，带有原子性和撤销日志记录。
* patch_dry_run：验证适用性，报告冲突，不写入磁盘。
* patch_reverse：生成反向补丁（验证后）而不应用。
* patch_stat：总结补丁（文件、块、+/-/上下文计数）而不接触文件系统。
CLI¶
作为独立命令行工具使用：
dsh-patch apply changes.patch --root /workspace
dsh-patch dry-run changes.patch
dsh-patch reverse changes.patch > revert.patch
dsh-patch undo .dsh-patch-undo.json
库¶
在代码中导入以进行编程使用：
import { applyPatchText, applyUndo, parsePatch, statPatch } from 'dsh-patch-apply'
适用场景与注意¶
该插件零运行时依赖，使用 TypeScript 源码和 Node.js 内置测试运行器。
文件按行建模，带有各自的终止符；未触及的区域按字节往返传输。
二进制安全：标记为二进制的文件被跳过；针对二进制目标的文本补丁被检测并跳过。
请注意，该插件在当前 DSH 进程的权限下运行。安装前应检查源代码和许可证。
结尾¶
apply-patch 为 DSH 生态系统中的差异应用提供了可靠、原子和可撤销的解决方案。
