前言¶
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 生態系統中的差異應用提供了可靠、原子和可撤銷的解決方案。
