在 DeepSeek Harness（DSH）環境中開發智能體時，處理文件編輯常面臨機械可靠性問題：同一文件經過多輪對話修改，行號可能漂移；文本在不同系統間傳輸可能改變換行符（CRLF/LF）。模型如果依賴絕對行號或靜態文本進行替換，極易出現匹配失敗。
前言¶
這是什麼¶
DeepSeek Harness 哈希錨點文件編輯插件（magian1127/deepseek-harness-hashline）提供 hashline_read 和 hashline_edit 兩個工具。它使用 LINE:HASH 格式作爲錨點，將編輯操作綁定到模型最近讀取過的具體行內容。這解決了多輪修改、原子批量修改以及換行符差異導致的編輯失敗問題。
核心功能¶
該插件主要包含以下能力：
LINE:HASH讀取：以LINE\|HASH 內容格式讀取文件。默認使用 4 位十六進制 SHA-256 前綴，結果同時報告 EOL（換行符）和 BOM（字節順序標記）。- 三種錨定編輯：支持
set_line（設置單行）、replace_lines（替換行段）、insert_after（在行後插入）三種操作。hashline_edit的參數edits爲扁平對象數組。 - 方言回收：自動識別並回收常見的畸形傳參，如忘傳
op（自動推斷爲set_line或replace_lines）、字段提升到根級等。 - 原子批量編輯：在一次調用中校驗所有錨點，拒絕重疊修改，然後原子寫入。
- 版本 CAS 保護：利用 DSH 文件版本機制，防止校驗後到寫入前的併發覆蓋。
- 文本保真：保留 UTF-8 BOM、LF/CRLF 及混合換行符，不破壞文件末尾狀態。
- 失效恢復：哈希匹配失敗時自動重定位到附近行，或報錯回顯真實錨點。
- 原生結果卡片：讀取複用 DSH 原生
ReadBlock，編輯顯示原生風格 diff 卡，刪除/新增行以灰色 gutter 標記。 - 可逆嚴格替換：開啓“替換內置讀寫”後，Agent 使用嚴格錨定的
read/edit，智能體操作更安全。 - 提示詞中文化：可配置將工具說明、錯誤消息等文案改爲中文。
安裝與啓用¶
DSH 的 bundle 按 profile 隔離，Web GUI、Open Design 和 Headless 模式需分別安裝。
- Web GUI 模式
node bin/dsh-hashline.mjs install --profile web --link $PWD
- Open Design 模式
dsh plugin --profile open-design add "link:$PWD"
- Headless 模式
dsh plugin --profile headless add "link:$PWD"
注意：--link 參數必須指向本插件源碼目錄。安裝後可使用 node bin/dsh-hashline.mjs status --profile web 等命令確認狀態。
典型用法¶
讀取文件時，使用 LINE|HASH 格式：
LINE\|HASH 3a2f1b 這是被錨定的內容
進行編輯時調用 hashline_edit，參數 edits 爲扁平對象數組：
- 基礎編輯：指定
op（可選）、anchor（錨點文本）和new_text（新文本）。
{
"edits": [
{
"op": "set_line",
"anchor": "LINE|HASH 3a2f1b",
"new_text": "新的內容"
}
]
}
- 方言簡化：若不傳
op，系統自動按形狀推斷：- 帶
anchor+new_text->set_line - 帶
start_anchor+end_anchor+new_text->replace_lines
- 帶
若傳入 old_string 或 replace 等非錨定字段，操作會被拒絕並提示改用內置 edit。
適用場景與注意¶
- 適用場景：需要高可靠性文件編輯的場景，特別是多輪對話維護同一文件，或需要確保文本格式（如保留 BOM）不被破壞時。
- 注意：
- 測試階段：當前仍處於測試（experimental）階段，接口、配置項和行爲可能隨時變更，請勿用於正式項目。
- 權限要求：Web GUI 配置卡片要求 DSH 包含
settings.register(..., { exposeToClients: true })。 - 數據安全：插件不上傳數據、不維護獨立數據文件。
總結¶
該插件通過哈希錨定機制，解決了 DSH 環境下文件編輯的機械可靠性問題，提供了原子性、保真度和自動容錯能力。目前處於測試期，適合在隔離環境驗證其穩定性與行爲。
