前言¶

在 DeepSeek Harness（DSH）裏，智能體經常要分頁讀文件、再按行改代碼。若讀和寫之間文件被其他進程或並行工具改過，普通「按行號替換」容易覆蓋新內容或產生衝突。DSH 內置的 read/edit 並不自帶「讀時快照 + 寫前再驗」這一套機制。@lightjunction/dsh-hashline（倉庫 LIghtJUNction/dsh-hashline）爲 DSH 增加 hashline_read 與 hashline_edit，讀取時返回整文件 SHA-256 revision 和每行的 LINE:HASH 錨點，編輯時同時校驗 revision 與錨點，不一致則拒絕寫入。維護者爲 LIghtJUNction，社區目錄分類爲工作流；行爲思路來自 coctostan/pi-hashline-readmap（MIT），本倉庫爲獨立 DSH 實現，首版不替換 DSH 內置 read/edit。

這是什麼¶

一句話：Stale-safe hash-anchored line editing for DSH——在 DSH 工具鏈裏做「過期安全」的行級編輯。

插件向 Cordis 註冊兩個工具名：hashline_read、hashline_edit。讀結果裏帶完整文件 revision、帶哈希前綴的行文本、分頁字段；寫操作必須帶上讀時得到的 revision 和起止行的 LINE:HASH 錨點。任意文件變化（包括編輯範圍之外）都需要重新讀取後再編輯。

核心功能¶

下面只列 README 與 package 中已說明的能力。

hashline_read¶

• 參數示例：path、offset（從 1 開始）、limit（每頁最多 1000 行）。
• 返回：revision（整文件 SHA-256）、lines（形如 12:0123456789abcdef|原文）、totalLines、nextOffset（爲 0 表示沒有下一頁）。

hashline_edit¶

• 必須提供讀返回的 revision 以及錨定的 start（和可選的 end）。
• operation 支持 replace；省略 end 表示只替換一行。insert_after 在 start 行後插入，不接受 end。
• text 爲行內容；末尾換行不會多出一空行；replace 且 text 爲空時刪除範圍。
• 寫入保留原文件 LF/CRLF、末尾換行習慣和普通權限位；使用同目錄臨時文件並原子 rename，提交前再次檢查哈希、inode 和路徑。

與上游 pi 實現的差異（v0.1）¶

• 行哈希爲 SHA-256 的 16 位十六進制，並要求整文件 revision；與上游 xxhash 三位錨點不兼容。
• 不含 readmap、AST 搜索、模糊錨點重定位、copy/move lines、語法檢查或 TUI diff；README 明確不應把這些未實現能力算作已遷移。

邊界與拒絕條件¶

• 默認通過當前 agent 的 workingDirectory 定位工作區；無 agent 的宿主需在插件 overlay 配置 root（絕對路徑倉庫根）。
• 只處理宿主機本地文件系統，不使用 DSH remote world 或 sandbox 文件接口。
• 拒絕：工作區外路徑、路徑分量中的符號鏈接、.git 元數據、目錄、多重硬鏈接、非 UTF-8/NUL、混合換行、超過 1 MiB 的文件。
• 不創建文件、不提供跨文件事務；不保留 inode、ACL、擴展屬性或特殊權限位。

安裝與啓用¶

面向 Node.js 24+、DeepSeek Harness 0.2.1-rc.2。當前交付爲源碼與本地構建，README 未表示已發佈 npm。插件以當前 dsh 進程權限訪問本地磁盤，安裝前請自行審閱源碼與 MIT 許可證。

在已安裝 monorepo 依賴的目錄執行：

npm run check --workspace @lightjunction/dsh-hashline
cd plugins/dsh-hashline
npm pack
dsh plugin --profile web add "$PWD/lightjunction-dsh-hashline-0.1.0.tgz" --ignore-scripts

npm pack 會觸發構建；不要把未構建的源碼直接當編譯入口安裝。重啓目標 profile 後，在工具列表確認 hashline_read 和 hashline_edit。TUI 使用者將命令中的 web 換成實際 profile 名。

本地驗證（不含遠程模型或 remote world）：

npm run check --workspace @lightjunction/dsh-hashline

典型用法¶

先做分頁讀取。下面 JSON 爲 hashline_read 參數示例：

{"path":"src/example.ts","offset":1,"limit":100}

從返回結果中取出實際的 revision 和行錨點（如 12:0123456789abcdef），再調用 hashline_edit：

{"path":"src/example.ts","revision":"<read 返回的 revision>","operation":"replace","start":"<起始 LINE:HASH>","end":"<結束 LINE:HASH>","text":"替換後的代碼"}

單行替換可省略 end；範圍外或 revision 過期時編輯會被拒絕，應重新 hashline_read 後再寫。

適用場景與注意¶

適合誰： 需要在 DSH agent 循環裏穩定做「讀—改—再讀」、且希望避免靜默覆蓋併發修改的開發者；分類上歸入工作流類插件，與目錄頁 skillhub.cn 條目 一致。

務必注意：

• 插件不是路徑隔離沙箱，以 dsh 進程權限讀寫工作區內的普通文件。
• README 說明無法通過 Node 可移植 API 排除所有「外部進程同時替換父目錄」的競態。
• 社區插件目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；安裝來源以 GitHub 倉庫與上述 pack 流程爲準。

結尾¶

dsh-hashline 把「整文件 revision + 行哈希錨點」接到 DSH 工具面，讓行級編輯在文件已變 stale 時失敗而不是誤寫。需要細節、Issue 或上游說明時，見 GitHub README 與目錄頁 https://www.skillhub.cn/plugins/LIghtJUNction/dsh-hashline。