前言¶
DeepSeek Harness (DSH) 采用插件化架构。在文件编辑场景中，针对单行修改，原生 edit 工具更为高效；但在需要处理大文件、跨文件批量变更或新增/删除文件时，逐行编辑不仅效率低下，还难以保证操作的原子性。dsh-patch-edit-plus 插件通过封装统一的 apply_patch 工具，为模型提供了处理 Git unified diff 和 Codex apply_patch 语法的能力，确保所有变更“全有或全无”地执行。
插件介绍¶
该插件为 DSH 提供了一个单一的模型接口——apply_patch 工具。
- 核心能力：支持 git/unified diff（默认启用）和 Codex
apply_patch语法（可选）。 - 执行模式：采用原子性应用，任何步骤失败都会导致整个补丁回滚，零字节写入。
- 兼容性：支持 DSH 0.2.0-rc.1 及以上版本。
- 设计原则：插件注册后完全由 DSH 调度，自身不干预核心流程，卸载时自动清理资源。
安装与配置¶
使用官方安装命令添加插件，随后验证配置并重启 DSH。
dsh plugin --profile web add <path-to-dsh-patch-edit-plus>
dsh web --dump-config # 验证插件行是否出现
# 重启 DSH
在 DSH 设置面板中，可以调整以下关键配置项：
| 配置项 | 默认值 | 说明 |
|---|---|---|
allowCodexPatch |
false |
是否接受 Codex apply_patch 语法 |
conflictPolicy |
rename |
工具名冲突时的处理策略 (rename / skip / fail) |
deleteBackend |
shell |
删除/移动操作的后端实现 (shell / none) |
shellDialect |
auto |
Shell 脚本方言 (auto / posix / pwsh) |
maxFiles |
50 |
单个补丁允许的最大文件数 |
maxPatchBytes |
524288 |
补丁文本的最大字节数 |
典型用法¶
模型根据场景选择使用 Unified Diff 或 Codex 语法。
1. Unified Diff 语法（默认）¶
适用于标准的 Git 补丁格式。
--- a/src/app.ts
+++ b/src/app.ts
@@ -10,4 +10,4 @@ export function main() {
init()
- start(oldPort)
+ start(newPort)
await shutdown()
}
2. Codex apply_patch 语法（可选）¶
通过设置 allowCodexPatch: true 启用。此语法允许在一个补丁块中混合执行多种操作。
*** Begin Patch
*** Update File: src/app.ts
@@
init()
- start(oldPort)
+ start(newPort)
*** Add File: docs/notes.md
*** Delete File: tmp/junk.txt
*** End Patch
适用场景与注意¶
适用场景¶
- 大文件内的微小修改：无需回显整个文件内容。
- 跨多个文件的批量变更：一次调用完成多个文件的修改。
- 新增文件 / 删除 / 重命名：这些操作由
apply_patch统一处理。
关键限制¶
- 沙箱依赖：删除和移动操作通过
ctx.shell执行，沙箱强度取决于加载的 shell 执行器（例如bash-sandboxfences；bash-local不受此限制）。 - 权限策略：每次写入和删除操作都会检查会话级策略 (
ctx.sandboxPolicy.resolve({ session }))，确保在workspace-write模式下的安全性。 - 目录创建：添加文件时不会自动创建父目录，需确保目录已存在。
- 精确匹配：不支持模糊匹配或偏移量匹配，hunk 位置必须精确。
- 二进制文件：拒绝二进制补丁。
- 换行符保真：CRLF 文件会被写回为 CRLF。
结语¶
dsh-patch-edit-plus 插件通过统一的 apply_patch 接口，解决了 DSH 中批量文件编辑的原子性问题，同时保持了与原生工具的兼容性。通过合理的配置，可以平衡安全性与开发效率。
