补丁应用器 JohnXu22786/apply-patch

dsh-patch-apply

在 DeepSeek Harness（dsh）以及任何 Node 运行时中，将结构化 unified diff（git 格式）应用到真实文件系统。

English documentation: README.md

dsh 官方只提供字符串级的 edit/write 工具，没有任何会落盘的结构化 diff 应用工具。dsh-patch-apply 填补了这一空白：它解析 unified diff，逐 hunk 应用（含模糊匹配与行号偏移修正），让整个过程要么全成功、要么全回滚，并在应用前生成反向补丁以实现字节级精确回滚（undo）。

零运行时依赖。TypeScript 源码、纯对象工具定义、使用 Node 内置测试运行器。

特性一览

- 完整的 git diff 覆盖 —— 多文件、多 hunk、±/上下文/新增/删除、/dev/null 新建与删除、rename from/to、copy from/to、old mode/new mode、index SHA、\ No newline at end of file、二进制标记（Binary files … differ、GIT binary patch）、带空格引号路径。同时支持经典的无 git 头的裸 ---/+++ 补丁。
- 自研解析器 —— 无重型依赖；解析器会把 hunk 头与实际行数严格校验，遇到格式错误立即给出精确的补丁行号。
- 精确的 hunk 定位 —— 锚点精确匹配 → 全文精确匹配（行号偏移修正）→ 模糊匹配（前导上下文容错，GNU patch 风格）。删除行永远不会被模糊丢弃，因此模糊匹配绝不会误删内容。
- 全有或全无的原子性 —— 任何写入发生之前，所有文件都在内存中完成解析与校验；一旦存在 hunk 冲突或结构性违规，什么都不写。
- 版本守卫 —— 复用与官方 dsh 文件系统完全相同的身份配方（dev:ino:size:mtimeNs:ctimeNs，见「与官方 dsh fs 的版本守卫协同」）；每次写入在发布前会重新校验身份，一旦漂移即报 STALE 并中止。
- 随处可撤销 —— 在变更前计算反向补丁，并先写入 undo 日志；undo 可以字节级还原。同样覆盖新建、删除、重命名、复制与权限变更。
- dry-run 模式 —— 静态校验可应用性；逐 hunk 报告冲突（期望/实际内容、hunk 序号、补丁行号），不改文件。
- CRLF / LF 保真 —— 文件按建模；未被触动的区域逐字节原样往返，包括混合换行与文件末尾无换行的情况。
- 二进制安全 —— 二进制标记的文件会被跳过并报告；指向二进制目标的文本补丁会被识别（NUL 字节 / 非法 UTF-8）并跳过，绝不会破坏数据。

安装

作为 dsh bundle（推荐）

本包是标准 dsh bundle：package.json 声明
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }，补丁会插入一行 Cordis
插件项，其模块导出 { name, inject, apply }，并在工具注册表（ctx.tools）
上注册四个工具。

已发布到 registry
dsh plugin --profile add dsh-patch-apply

或直接从此仓库安装
dsh plugin --profile add github:JohnXu22786/apply-patch

或使用本地检出目录
dsh plugin --profile add /path/to/apply-patch

无需其他配置——patch_apply、patch_dry_run、patch_reverse、patch_stat 立即可供模型调用。

可选插件配置（在 profile 中针对 patch-apply 行的后续补丁层，或直接写在该行的 config 中）：

- config:
id: patch-apply
defaultRoot: /abs/path/to/workspace # 相对补丁路径的基准目录（默认：process.cwd()） io: node # node | ctx-fs（见下文） fuzzContext: 3 # 模糊匹配最多可丢弃的前导上下文行数 undo: true # patch_apply 是否持久化 undo 日志 strictSha: false # 是否把 index 行 SHA-1 不匹配视为硬冲突

作为独立 CLI

npm install dsh-patch-apply # 或从本地检出目录 link
npx dsh-patch --help

作为库

npm install dsh-patch-apply

import { applyPatchText, applyUndo, parsePatch, statPatch } from 'dsh-patch-apply'

使用

1. dsh 工具

| 工具 | 用途 |
| patch_apply | 应用 unified diff，全有或全无，带 undo 日志。 |
| patch_dry_run | 校验可应用性；报告所有冲突；不写任何东西。 |
| patch_reverse | 只生成反向补丁（先校验），不应用。 |
| patch_stat | 汇总补丁（文件、hunk、+/−/上下文行数），不访问文件系统。 |

公共参数：

- patch (string，必填) —— unified diff 文本。
- cwd (string，可选) —— 相对路径的基准目录（默认：config.defaultRoot）。
- dry_run / verify_sha (boolean，可选) —— dry-run 模式 / 硬性 SHA-1 校验。

patch_apply 返回：

{
"ok": true,
"dryRun": false,
"files": [{ "path": "...", "operation": "modify", "hunks": [{ "hunkNumber": 1, "status": "offset", "atLine": 12 }] }],
"conflicts": [], // [{ file, hunkNumber, sourceLine, reason, expected[], actual[], anchorLine }]
"errors": [], // [{ code, path, message }]
"notes": [], // 信息性说明，例如 SHA-1 预检不匹配
"reversePatch": "diff --git ...",
"undoFile": "/abs/.dsh-patch-undo.json"
}

files 会列出每个已准备的文件操作及其逐 hunk 状态——成功时是已应用的结果， dry-run 时则是将要应用的结果。「全有或全无」的含义：只要 ok 为 false （conflicts/errors 任一非空），就保证什么都没写入；成功时则每个文件的每个 hunk 都已定位并提交。

2. CLI

dsh-patch [options]

Commands
apply 应用 unified diff（默认写入 undo 日志） dry-run 校验可应用性；报告冲突；绝不写入 reverse 打印反向补丁（或用 --out 写入文件） stat 汇总补丁，不访问文件系统 undo 应用 undo 日志中记录的反向补丁 help 显示帮助

Options
--root 相对补丁路径的基准目录（默认：cwd） --dry-run apply 命令等同 dry-run 行为 --no-undo 不写入 undo 日志 --undo-file apply 的 undo 日志路径（默认：/.dsh-patch-undo.json） --fuzz 模糊匹配最多可丢弃的前导上下文行数（默认：3） --strict-sha 把 index 行 SHA-1 不匹配视为硬冲突 --out 反向输出写入文件而非 stdout --json 在 stdout 输出机器可读 JSON --help 显示帮助

退出码：0 成功 · 1 补丁无法应用 · 2 用法错误。

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

3. 库

import { applyPatchText } from 'dsh-patch-apply'

const report = await applyPatchText(patchText, {
root: process.cwd(), // 相对路径的绝对基准目录 fuzzContext: 3, // 模糊容错 dryRun: false, // 是否只校验 undo: true, // 是否写入 undo 日志 undoFile: '.dsh-patch-undo.json', strictSha: false, // index SHA-1 不匹配是否视为硬冲突 })

其他导出：parsePatch、statPatch、applyUndo(journal)、
readJournal / writeJournal、blobSha、文件系统接缝 IoAdapter/NodeIoAdapter/CtxFsIoAdapter，以及各类带类型的错误类。

错误码

| 代码 | 含义 |
| PARSE | diff 格式错误；消息内包含补丁行号。 |
| CONFLICT | hunk 无法安全定位；携带 hunk 附近的 期望/实际 内容。 |
| VALIDATION | 应用前的结构性问题（覆盖已存在文件、目标缺失、路径越界）。 |
| STALE | 校验与提交之间文件身份发生变化（版本守卫被触发）。 |
| IO | 文件系统操作失败（写/chmod/unlink/…）。 |
| BINARY | 二进制目标 / 二进制标记——跳过，绝不破坏。 |
| UNSUPPORTED | 超出解析范围（如合并 diff --cc）或后端能力不足的动词。 |

工作原理

解析器（parse.ts）

一个状态机理解 git diff 的每个块以及经典的无头 ---/+++ 形式。每个 @@ 头都会在实际消费其正文行时核对行数——欠供或超供的 hunk 会立刻抛出带补丁行号的 PARSE 错误，因此被截断或损坏的补丁绝不会悄然误应用。

hunk 定位（locate.ts、engine.ts）

对每个文件，按顺序对当前内存缓冲逐 hunk 应用：

1. exact —— 旧侧块在锚点（头行号减一，并按此前 hunk 的净增量平移）处匹配；
2. offset —— 完整旧侧块在别处精确匹配；取离锚点最近者（修正行号漂移）；
3. fuzzy —— 允许丢弃最多 fuzzContext 行前导上下文来寻找螺栓。只有上下文行可被丢弃（删除行必须精确匹配），且旧、新两侧丢弃同一前缀，因此模糊匹配绝不会误删内容，也不会重复插入被模糊掉的上下文行。

若不存在安全位置，该 hunk 会作为冲突上报：包含 1 起始的 hunk 序号、补丁行号、以及期望/实际内容的短摘录——整个补丁随即被拒绝，磁盘不被触碰。

原子性与回滚（apply.ts、io.ts）

- 所有文件在内存中首先完成解析、读取与转换。任何冲突或结构性问题 ⇒ 什么都不写。
- 反向补丁与（启用时的）undo 日志会在第一次变更之前写入，因此即使提交中途崩溃，也始终存在完整的还原路径。
- 内容写入逐文件原子（临时文件 + rename），按需创建父目录；随后做权限变更；最后做删除 / 重命名源清理（先确保目标完整写好后，源才消失）。
- 若提交中途任何一次写入/chmod/unlink 失败，会把已变更的每个文件从内存中的原始内容恢复（尽力而为）并上报错误。跨多个 rename 无法用单次文件系统调用实现物理原子性；提交前的校验才是把保证变为结构性的关键。

与官方 dsh fs 的版本守卫协同

官方 @deepseek-ai/dsh-fs 后端用 stat 身份与新鲜度派生出不透明的 FsVersion： dev:ino:size:mtimeNs:ctimeNs。本包在 NodeIoAdapter.probe().identity 中复刻了完全相同的配方，因此这里产生的版本令牌与 Harness 产生的是同一含义。每次受守卫写入前会在发布时重新探测身份，一旦漂移即以 STALE 中止并回滚——与官方
writeText(…, { kind: 'replaceIfVersion' }) 的过期保护契约一致。

两点配置说明（刻意保持解耦）：

- 默认 io: node —— 通过 NodeIoAdapter 直接访问主机。CLI 与整个测试套件均在此模式下运行。
- io: ctx-fs —— 解析/stat/读取/写入经由已挂载的 Harness ctx.fs 服务（CtxFsIoAdapter），把受守卫的写入映射到后端自己的 createIfAbsent / replaceIfVersion 意图上，即版本守卫由后端自己执行。由于官方 Service Definition 没有 unlink/rename/chmod/mkdir 动词，需要这些操作的补丁会在任何变更之前以精确的 UNSUPPORTED 报错，而不是做一些出人意料的事。
需要完整覆盖删除 / 重命名 / 权限变更时，请使用 io: node。

行尾符

文件被表示为 { text, sep } 行列表，sep 是该行自身的逐字终止符（\r\n、
\n，或末尾无换行时的 ''）。补丁行仅按文本匹配，因此 CRLF 与 LF 文件都能干净应用；补丁插入的新行继承文件的主导换行；\ No newline at end of file 标记（旧、新两侧独立）会把文件末尾无换行的状态正确传递下去。

开发

npm install
npm test # 先 tsc 构建，再 node --test 运行 build/test/*.test.js
npm run build # tsc -> build/
npm run typecheck # tsc --noEmit

测试布局：parse（格式覆盖 + 畸形输入定位精度）、apply（单/多文件、CRLF、新建/删除/重命名/复制/权限、二进制、dry-run 纯净性、undo 往返）、fuzzy （偏移 / 模糊 / 拒绝路径、SHA-1）、conflict（报告精度）、rollback （全有或全无、注入 I/O 失败后的物理回滚、STALE 守卫）、cli（退出码、 JSON、reverse/undo 流程）。

许可证

MIT —— 见 LICENSE。© 2026 dsh-patch-apply contributors。