补丁式文件编辑drscrewdriver/dsh-patch-edit-plus

dsh-patch-edit-plus

面向 DeepSeek Harness（DSH） 的补丁风格文件编辑插件：只提供 1 个模型可见工具 apply_patch，接受 git/unified diff（默认开启）与 Codex apply_patch 语法（可选开启），全量验证后原子应用，对 DSH 既有功能零负面影响。

DSH 版本适配矩阵

| DSH 版本 | 状态 | 说明 |
|---|---|---|
| 0.1.2-rc.1 | ✅ 支持 | 工具编写契约（defineTool DSL、presentation 视图）在 0.1.2–0.1.5 间逐字节未变，单一代码路径服务两个版本。 |
| 0.1.3-alpha.x | ✅ 支持 | 同上。 |
| 0.1.5-rc.2 | ✅ 静态核验 | npm run typecheck:0.1.5 用真实 0.1.5-rc.2 peer 包对 src/ 做类型核验；不调用 readByteRange，不含 0.1.5-only PTC 字符串。 |

settings 注册走双 API 回退：0.1.2+ 的 settings.installSection 优先，旧版回退 settings.register。

工具路由指引（为什么该用谁）

工具 description 内置了明确的路由规则：

- 单个已读文件里的单点小改 → 优先原生 edit（patch 反而多花 token）。
- 大文件里的小改动 → apply_patch（无需回显整个文件）。
- 跨文件批量改动 → apply_patch（一次调用、原子验证）。
- 新建大内容文件 / 删除 / 重命名 → apply_patch。

安装

dsh plugin --profile web add
dsh web --dump-config   # 确认插件行出现
重启 DSH

使用示例

unified diff（默认）

--- a/src/app.ts
+++ b/src/app.ts
@@ -10,4 +10,4 @@ export function main() {
init()
-  start(oldPort)
+  start(newPort)
await shutdown()
}

Codex apply_patch 语法（需开启）

*** Begin Patch
*** Update File: src/app.ts
@@
init()
-  start(oldPort)
+  start(newPort)
*** Add File: docs/notes.md
+# Notes
*** Delete File: tmp/junk.txt
*** End Patch

在配置中设 allowCodexPatch: true 开启。关闭状态下收到 Codex 补丁时，工具返回可操作提示（如何开启、或改用 unified diff），而不是泛化的解析错误 —— Codex 语法是 GPT 系模型的强先验，沉默失败会让模型陷入重试循环。

四类操作

| 操作 | unified diff | Codex | 执行路径 |
|---|---|---|---|
| Add | new file mode + /dev/null | *** Add File: | ctx.fs.writeText（官方 intent 舞蹈） |
| Update（多 hunk） | @@ hunk | @@ hunk | ctx.fs.writeText |
| Delete | deleted file mode + /dev/null | *** Delete File: | ctx.shell（沙箱感知，路径走 env） |
| Move / rename | rename from/to | *** Move to: | ctx.shell |

保证

- 全量先验证后写入：整个补丁先对当前文件内容做验证（上下文定位、工作区围栏、symlink 策略、路径去重），任一失败即零写入中止。
- read-before-write 门禁生效：每次写入完整复刻官方 write 工具的 intent 舞蹈 —— fs/write-intent waterfall → 带 intent 的 writeText → fs/observed 事件。DSH 的 provider 从不分发 fs/* 事件，裸调 writeText 会静默绕过门禁。
- 精准失败诊断：hunk 定位失败时，错误包含文件 + hunk 序号、搜索起始行号、期望行预览（空白字符可视化）、文件实际片段和针对性提示。
- 换行保真：CRLF 文件按原风格写回；无尾换行状态保持，除非补丁本身改动了文件尾。
- 纯增量：只注册 1 个工具、绝不调用 tools.restrict()、不覆盖原生工具、不注册全局服务、卸载即完全恢复。与其他 apply_patch 提供方（bainianlaoyao/dsh-codex-mode、shuind/dsh-codex-harness 等）的重名冲突通过改名避让解决（apply_patch_1、…_2…），不会导致 DSH 启动失败。

配置项

| 选项 | 默认值 | 说明 |
|---|---|---|
| toolName | apply_patch | 模型可见工具名。 |
| conflictPolicy | rename | 重名时 rename / skip / fail。 |
| renameSuffix | _1 | 改名避让使用的后缀。 |
| allowUnifiedDiff | true | 接受 git/unified diff。 |
| allowCodexPatch | false | 接受 Codex apply_patch 语法。 |
| deleteBackend | shell | shell 或 none（Delete/Move 返回结构化错误）。 |
| shellDialect | auto | auto（win32 上 pwsh）/ posix / pwsh。 |
| deleteCommand / moveCommand | 内置 | 自定义命令模板。路径仍然只经 env 传入（DSH_PATCH_TARGET / DSH_PATCH_SOURCE），请勿把路径插值进命令串。 |
| dryRunByDefault | false | 默认按 dry run 处理，除非调用显式传 dryRun: false。 |
| followSymlinks | false | 允许补丁路径穿越符号链接。 |
| maxFiles | 50 | 单补丁最大文件段数。 |
| maxPatchBytes | 524288 | 补丁文本字节上限。 |
| maxDiffBytes | 16384 | 结果元数据中单文件 diff 上限（超出置空并标记 truncated）。 |

限制（明确披露）

- Delete/Move 走 ctx.shell：沙箱强度取决于装载的 shell 执行器（bash-sandbox 有围栏；bash-local 没有）—— 与原生 bash 工具的风险姿态一致。每次请求都携带 sandboxPolicy 并回传沙箱事实，"策略拒绝"与"命令失败"可区分。
- Add 不创建父目录：与原生 write 工具一致（ctx.fs 无 mkdir）；错误信息会指出缺失的目录。
- 不做模糊/偏移匹配：定位容错为精确 → trimEnd → trim 三级，刻意保守（模糊匹配对删除类操作不安全，已列入路线图）。
- 二进制补丁被拒绝并给出明确错误。

开发

npm install
npm run typecheck        # 针对 0.1.2-rc.1 peer 包（devDependencies）
npm run typecheck:0.1.5  # 针对 0.1.5-rc.2 peer 包（双版本静态核验）
npm test                 # vitest，84 个用例
npm run lint
npm run build            # lib/
npm run verify:source    # 静态安全断言（intent 舞蹈、无 node:fs 等）
npm run smoke            # stub 宿主加载冒烟

实机验证（dsh plugin --profile web add → 重启 → 会话调用）由部署者手动执行。

License

MIT