前言¶
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 中批量文件編輯的原子性問題，同時保持了與原生工具的兼容性。通過合理的配置，可以平衡安全性與開發效率。
