前言¶

在 DeepSeek Harness（DSH）裏做代碼相關會話時，常見需求是：在不動當前工作目錄的前提下開一條隔離分支，並在界面裏看清「這個會話實際落在哪、相對 Git 有哪些改動」。有的工作流會把 worktree 管理做成獨立頁面或常駐目錄欄，佔用側欄空間。維護者 zxbingoo 的 dsh-minimalist-worktree 走另一條路：參考 Paseo 的交互思路做輕量 worktree 選擇，把目錄信息放進會話列表懸浮卡片，在會話內提供只讀文件樹與 unified Diff，不新增獨立工作樹管理頁。插件歸類爲客戶端，在 SkillHub 插件目錄 可查；源碼與說明見 GitHub（MIT 許可證）。SkillHub 頁顯示星標爲 0，不代表功能完整性，僅以公開資料爲準。

這是什麼¶

dsh-minimalist-worktree 是 DSH 的客戶端插件：在新會話裏可選「本地」或「新建 worktree」及起始分支；列表懸停可查看分支名與完整目錄；會話內可瀏覽工作區文件（含部分格式預覽）並查看 Git 變更與只讀 Diff。它不替代 DSH 自帶的歸檔與停止機制，在歸檔時按約定清理本插件創建的外部 worktree，並支持 worktree 丟失時的受控恢復與可選的 Codex 風格環境初始化。

宿主要求（package.json）：engines.dsh 爲 >=0.2.1-rc.5 <0.3.0-0；README 寫明當前開發/迴歸側重 DSH 0.2.2-rc.1，更換已安裝插件後需重啓 DSH 才能確保加載新構建的 client.js。

核心功能¶

新會話：本地 / 新建 worktree¶

兩個緊湊選擇器僅在：會話尚未發送消息且工作區爲 Git 倉庫時顯示。非 Git 工作區默認「本地」並隱藏選擇器；檢測完成前不閃現。權限或 Git 讀取錯誤不會被誤判爲「非 Git」或「沒有變更」。

典型步驟（摘自 README）：

1. 在新會話選擇 Git 工作目錄。
2. 默認「本地」：沿用當前目錄，不切換源倉庫分支。
3. 選「新建 worktree」並選起始分支，等待選擇保存完成後再發消息。
4. 宿主在首個模型步驟之前創建獨立分支與檢出目錄，並把本會話切過去。

新分支名採用 dsh/<形容詞>-<名詞>（內置英文詞表隨機組合，例如 dsh/ripe-bird）。目錄位於 ~/.dsh/worktrees/<項目名>-<規範倉庫路徑 SHA256 前 8 位>/...，不再嵌套在源項目 .agents 下。已有 worktree 不搬遷、不刪除；創建失敗會中止模型步驟，可能留下檢出目錄或分支，需自行檢查後處理。

工作目錄改變後需重新選擇；已開始或派生的會話不能補選，以免改變正在執行的任務。

會話列表：懸浮卡片中的目錄與分支¶

會話條目沿用 DSH 原生懸浮卡片：懸停顯示當前分支與當前目錄（跟被懸停的會話，而非當前打開會話）。無常駐圖標、無點擊複製；浮層打開時才查詢，關閉後釋放訂閱。非 Git、讀取失敗或無法實時查詢的歷史會話會明確提示，不編造分支。

右側：文件樹與 Git 變更（只讀）¶

自 0.5.0 起，原「工作區文件」類面板升級爲左側文件/變更導航、右側當前文件或行內 Diff（自動換行、收起目錄、複用 DSH 全屏與主題變量）。文件樹以 Session 的 workingDirectory 爲根，按層展開（每目錄 500 條）；點文件可只讀預覽 UTF-8 文本（512 KiB / 10000 行上限）。0.5.5 起支持 Markdown 等有界渲染、JSON 格式化、CSV/TSV 表格及常見圖像預覽；Office/PDF 等暫不嵌入。無暫存、提交、撤銷、推送等寫操作。

Git 變更以倉庫根爲比較基準，支持未提交 / 未暫存 / 已暫存等範圍，並可處理根倉與已登記子模塊分組（子模塊未初始化不自動拉取）。共享源目錄會包含其他工具的改動，不侷限於當前 AI。單次 Git 相關操作有 10 秒預算；列表與 patch 大小有明確上限，超限不僞裝完整結果。

變更視圖可在桌面分欄、窄屏上下佈局；會話 cwd 在子目錄時仍可看倉庫級 Diff，但超出 cwd 的文件不提供「打開文件」，防止目錄越界。

工作樹丟失、歸檔清理與初始化¶

工作樹丟失與回源（0.4.2）：在模型 pre-step 前後覈驗已創建 worktree 的目錄與分支；異常時在輸入框上方顯示恢復選項（非常駐）。可選「重建隔離工作樹」或「使用源目錄」，均需用戶確認；失敗 fail-closed，不提供模型可調用的 mutating recovery 工具。

Paseo 風格歸檔清理（0.4.1）：僅處理更新後的新歸檔，覈驗歸屬後對外部 worktree 執行 git worktree remove --force；不創建新快照，未提交與未跟蹤文件會被刪除，歸檔前需自行提交要保留的內容。清理失敗不影響歸檔本身。

Codex 本地環境初始化：在新檢出目錄讀取 .codex/environments/environment.toml，僅支持已覈實的 version = 1 且 [setup].script 非空時，在首個模型步驟前執行一次（最長 10 分鐘，受會話沙箱約束）。不執行 [[actions]]；Windows 上會暫停並提示不支持。首條用戶消息後可展示創建工作樹 / 運行初始化的輕量進度與日誌（脫敏展示，不保證識別所有自定義密鑰）。

安裝與啓用¶

安裝通過 DSH Plugin Manager 完成目錄 bundle 安裝，README 不要求改用戶配置文件。將 target 換成本地 clone 或解壓後的絕對路徑：

{ "action": "install_bundle", "target": "/absolute/path/to/dsh-minimalist-worktree" }

本地開發（README）：Node 24+，執行：

pnpm install --ignore-scripts
node build.mjs
node --test test/*.test.mjs

修改 src/client.js、src/changes-client.js 或語言資源後需重新 node build.mjs。client.js 爲生成產物。

插件以當前 DSH 進程權限運行，會通過會話掛載的文件系統、子進程與沙箱創建外部 worktree 並執行只讀 Git 查詢；安裝或使用前請自行查看源碼與 MIT 許可證，確認與團隊安全策略一致。

典型用法小結¶

1. 打開 Git 倉庫下的新會話，確認選擇器出現。
2. 需要隔離時選「新建 worktree」+ 起始分支，保存後發送首條消息，等待 worktree 創建（及可選 setup）進度結束。
3. 在會話內打開文件/變更面板，按範圍查看 Diff；列表懸停覈對分支與目錄。
4. 任務結束按 DSH 流程歸檔；知曉歸檔可能刪除未提交的 worktree 內文件。
5. 若目錄丟失，按界面恢復流程二次確認，成功後需重新發送原消息（不自動重發）。

適用場景與注意¶

適合：希望在 DSH 裏用 Git worktree 做會話級隔離、又不需要單獨 worktree 管理頁的開發者；需要在同一會話內只讀瀏覽變更、配合模型討論 patch 的場景。

注意：

• 僅查看 Git 與文件，不提供 Git 寫入與工作區寫回策略以外的越權操作。
• 未配置 .codex/environments/environment.toml 的 [setup].script 時不會自動跑 pnpm run setup 等命令。
• DSH 升級到不兼容版本時插件可能拒絕加載（見 README「DSH 升級兼容策略」）；應升級已驗證的插件版本或回退宿主，勿強行刪除持久狀態繞過檢查。
• SkillHub 爲社區目錄，與 DeepSeek / 幻方無官方從屬關係；插件非 DSH 內置應用商店條目。

結尾¶

dsh-minimalist-worktree 把 worktree 選擇、目錄可見性與只讀變更審查收進會話流，避免額外管理頁和常駐目錄欄，並與 DSH 歸檔、沙箱及主題體系對齊。查閱說明與版本信息可訪問 SkillHub 目錄頁 與 GitHub 倉庫。