前言¶
在 DeepSeek Harness（DSH）裏跑智能體時，模型會通過 edit、write、apply_patch 等工具改工作區文件。宿主默認能展示工具調用，但若缺少逐次修改的 diff、輪級彙總和可撤銷能力，開發者很難像在用 GitHub Copilot 那樣「改一處看一處、整輪審一遍、不滿意就撤」。
社區裏已有 change-review、diff-approval、file-changes 等插件，各自覆蓋追蹤、審批或輪末展示的一部分。dsh-copilot-diff 由 huieric 維護，定位爲 Copilot 風格的內聯 diff + 右側 Changes 審閱，並帶 Keep／Undo、輪前 Restore Checkpoint 與命令行改寫保護。它不調用模型，只做變更觀察與 UI。
下面介紹插件定位、能力、安裝與日常用法；事實以 GitHub 倉庫 README 爲準（當前 npm 包版本 0.8.3，MIT 許可證）。
這是什麼¶
dsh-copilot-diff 是一個 DSH Web 客戶端插件（platform: web）。服務端爲純 ESM，客戶端爲手寫 module-loader bundle，零依賴、零構建。
它解決三類問題：
- 每次文件修改都有可讀的 diff：跟在真實工具調用行後面就地展開，或進右側 Changes 做整文件審閱。
- 輪級視角：一輪結束有
+A −R統計、文件卡或緊湊 chip，並可 保留、撤銷 整輪或單條記錄。 - 工作區一致性：默認攔截
sed -i、重定向等靜默改寫，引導模型走文件工具，保證 diff 能掛在對應調用上；輪開始前可 恢復檢查點 把磁盤迴到該輪之前（在快照覆蓋範圍內）。
文件工具的逐調用 diff 仍由宿主保留；本插件另做按輪工作區快照，識別腳本、sed、Python replace 等命令行造成的磁盤變化，並提供持久化檢查點。超出快照範圍或未覆蓋的文件不會假裝能恢復。
核心功能¶
修改追蹤¶
插件觀察以下工具（一次調用一條獨立記錄；一次改多文件時按文件各記一條）：
- 常規：
edit/write/apply_patch - 編輯器風格：
replace_string_in_file、multi_replace_string_in_file、edit_file、multi_edit、create_file、write_to_file
對「只換字符串、結果裏沒有前後全文」的調用：調用前快照目標文件，調用後再讀一遍，用兩份文本算 diff。拿不到快照時（例如導入的歷史會話）退化爲用參數裏的 oldString / newString 畫片段。
就地 diff 與 Changes 面板¶
| 位置 | 行爲 |
|---|---|
| 聊天內工具行 | diff 長在對應編輯調用處，默認收起；點行首 > 就地展開；右側 +A −R 可點開右側審閱並定位到該次修改 |
| 右側 Changes | 0.8.0 起類似 Copilot「Response File Changes」：整輪所有文件 diff 平鋪一列，段頭文件名 + 目錄 + +A −R 滾動吸頂；可切統一／並排、展開 ⋯ N 行未改動；頂部整輪 保留／撤銷 |
| 會話側欄 | 每個會話行下方顯示該會話累計 +A −R（0.8.2 起顏色在面板外也有完整綠／紅回退鏈） |
大文件 diff 按行虛擬化（約 22px 行高），未改動區超過 40 行先摺疊，可繼續展開。
Keep、Undo 與檢查點¶
- 單次撤銷：每條記錄獨立 Undo，只回寫該次編輯替換掉的文本；若磁盤已不等於該次的
after，會拒絕並提示先撤較新的那次。 - 輪間邊界（0.8.1 起）：兩輪之間單獨一行（默認透明，懸停淡入），提供 恢復檢查點 與 分叉（在整輪末尾 seq 開新會話並切換）。
- Restore Checkpoint：確認後把文件恢復到該輪開始前（含之後輪次已記錄修改範圍內），聊天記錄保留；0.8.3 起邊界行排在用量統計行下一行，一輪只留一張文件卡（歸宿主
@deepseek-ai/dsh-client-ui-deliverables，保留／撤銷仍在右側審閱面板）。
命令行改寫保護¶
默認在執行前攔截：sed -i、perl -i、寫文件的 Python heredoc、tee／> 重定向、dd、truncate、git apply/checkout/restore、patch 等；node_modules、dist、build、output、/tmp 等目錄放行。命中時返回明確錯誤，引導改用 edit / write / apply_patch。
歷史會話¶
裝上插件前已發生的修改，可在打開舊會話時由服務端從 session.v4.jsonl(.zstd) 重放 tool/call + tool/result 補 diff（標爲「已保留」，不提供誠實回滾意義上的撤銷）。全量回填可運行：
node tools/backfill.mjs
與其它審閱插件的關係¶
可與 diff-approval 同時安裝：後者管改前改後審批，本插件管改完後的攤開審閱與逐條撤回。兩者若佔同一 tool.call.toolview key，後註冊的生效；只需其一可卸載另一個。能力對比表見倉庫 README「與現有三個插件的關係」一節。
安裝與啓用¶
推薦從 npm 安裝到 Web profile：
dsh plugin --profile web add dsh-copilot-diff
也可從 GitHub 添加（需 pnpm 支持 git 依賴）：
dsh plugin --profile web add github:huieric/dsh-copilot-diff
安裝後重啓 Web：
dsh web
插件自帶 cordis.patch.yml（dsh.bundle.patch），裝入 profile 後會自動插入插件行，一般無需手改配置。
裝不上或裝完不生效¶
- pnpm 鎖目錄無寫權限（容器或
$XDG_RUNTIME_DIR不可寫）：
XDG_RUNTIME_DIR="$HOME/.run" dsh plugin --profile web add dsh-copilot-diff
-
啓動摘要裏插件
did not activate：按摘要原因處理；0.1.0曾缺webServer注入，0.1.1已修復，升級到當前版即可。 -
與宿主 UI 插件 priority 衝突（如裝在
0.2.2-rc.1上整包加載失敗）：0.8.3已將tool.call.toolview與conversation.chat.node的turn-process註冊爲priority: -1，避免與宿主file-mutation-toolview等同 priority 佔位衝突。
完全不依賴 pnpm 時，可用倉庫內腳本（複製文件 + 註冊 bundle）：
./scripts/install-local.sh
要求 Node >=20.11（見 package.json engines）。
典型用法¶
安裝並 dsh web 後，在 Web 里正常讓智能體改文件即可，無需額外配置項。
輪次內：看到 編輯 … 1KB +22 −0 一類行時，點行首 > 展開就地 diff；點右側 +A −R 或文件名，右側 Changes 滾動到該次修改。
輪次末：在「已完成 … 步，用時 … +A −R」或文件卡上使用 審查 打開整輪 Changes；用 保留／撤銷 處理整輪，或在面板裏對單文件 Keep／Undo。
兩輪之間：鼠標移到輪間縫上，使用 恢復檢查點 回滾磁盤，或 分叉 從該輪末尾開新會話。
本地驗證 UI（合成數據，不含真實會話）：
npm test
node tools/preview.mjs > docs/preview.html
瀏覽器打開 docs/preview.html 可交互預覽組件；README 中 docs/screenshots/ 下有 overview、inline、expanded 等示意圖。
適用場景與注意¶
適合：長期在 DSH Web 裏做代碼類智能體開發、希望 diff 與 Copilot 審閱習慣對齊、需要逐次撤銷或輪前檢查點的用戶。
注意：
- 插件以當前 dsh 進程權限 讀寫工作區；安裝前請瀏覽源碼與 MIT 許可證，確認符合你的安全策略。
- 檢查點與撤銷依賴快照覆蓋範圍；README 明確超出範圍的文件不會假裝可恢復。
- 與
dsh-chat-import導入的 Copilot 歷史類似，無服務端記錄時 diff 可能僅由調用參數繪製。 - 社區目錄 skillhub.cn 插件頁 與 GitHub 爲獨立來源，與 DeepSeek／幻方無官方從屬關係；生態理念是「一切皆插件」。
結尾¶
dsh-copilot-diff 把「每次編輯一行 diff、右側整輪 Changes、Keep／Undo、恢復檢查點」接到 DSH Web 上，並默認擋住容易繞過工具管線的命令行改寫。若你已在用 DSH 做文件級智能體開發，可用官方命令裝進 web profile，按 Copilot 習慣審閱每一輪改動。
- 目錄頁：https://www.skillhub.cn/plugins/huieric/dsh-copilot-diff
- 源碼與文檔：https://github.com/huieric/dsh-copilot-diff
