前言¶
在 DeepSeek Harness (DSH) 的開發與調試中，通過行號或原始文本定位文件行是常見操作，但文本格式變動或行號偏移容易導致定位失效。dsh-hash-edit 旨在通過爲文件每行生成穩定的哈希錨點，解決文件編輯中的定位與回滾問題，確保編輯操作基於內容而非位置。
插件定位¶
這是一個爲 DeepSeek Harness (DSH) 提供哈希錨定讀寫、替換和撤銷能力的客戶端插件。它通過攔截寫入、遮蔽內置工具，實現對文件行的高精度操作。插件採用 MIT 許可證，由開發者 ddv12138 維護。
核心功能¶
該插件主要實現以下行爲：
- 哈希錨點機制：利用 xxHash32 算法爲每行生成穩定的 3 字符 base-62 錨點。錨點通過互質位圖探測解決衝突，構造性保證唯一性。
- 接管編輯：插件裝載後，遮蔽內置的
edit工具，並攔截write操作，自動追加錨點塊以保持文件新鮮度。 - 拒絕規則：插件拒絕過期的錨點、歧義的錨點以及無效引用，絕不進行模糊匹配。
- 持久化撤銷：支持
undo_last_replace，撤銷記錄跨重啓持久化，並支持字節級還原。
安裝與啓用¶
這是一個 DSH bundle（插件包），用戶需將其安裝進特定的 profile。
# 從 GitHub 安裝
dsh plugin --profile demo add github:ddv12138/dsh-hash-edit
# 從本地安裝
dsh plugin --profile demo add ./dsh-hash-edit
# 從 npm 安裝
dsh plugin --profile demo add @ddv12138/dsh-hash-edit
把該 bundle 的 patch 裝載進 profile 後，會插入插件行，從而接管編輯行爲。由於是按 profile 安裝，它能在任意 preset / profile 下工作。
使用說明¶
使用該插件時需遵守以下紀律：
- 單次編輯：一個文件每條消息只允許一次編輯。
- 純淨哈希：操作時只拷貝純淨的 3 位哈希，不包含行號或上下文。
工具調用¶
插件提供以下工具：
- read (hashline)：將行轉換爲
HASH│content格式，支持分頁，並記錄已展示區間。 - replace：使用
remove_from/remove_to（純淨 3 位哈希）指定刪除區間，後接replacement_text進行替換。一次調用僅支持一處修改。 - undo_last_replace：撤銷最近一次替換，內容還原精確到字節。
拒絕代碼¶
操作時若遇到文件狀態不符或參數錯誤，會返回以下拒絕代碼：
[E_STALE_ANCHOR]：錨點在當前文件中不存在。[E_AMBIGUOUS_ANCHOR]：錨點匹配到多行。[E_RANGE_STALE]：文件已變更或該區間從未被展示。[E_BAD_REF]：引用不是純淨的 3 位哈希。[E_UNDO_STALE]：上次替換後文件被改動。[E_FILE_TOO_LARGE]：文件超過 238,328 行或 100 MB。
技術細節與限制¶
- 算法：錨定算法爲
xxHash32(canon, seed 0) >>> 14 % 238328，生成的錨點爲 base-62 字符集。 - 存儲：撤銷記錄與快照存儲在項目工作區的
.dsh-hash-edit/store.json中（已 gitignore）。 - 文件限制：插件僅支持行數 ≤ 238,328 且大小 ≤ 100 MB 的文件。
結語¶
dsh-hash-edit 提供了一種基於內容哈希的健壯文件編輯方案，適合需要精確控制文件行變更且需頻繁撤銷的場景。更多細節可參考 GitHub 倉庫 或 社區目錄。
