DeepSeek Harness 工作樹：從建立到驗收
DeepSeek-V4 Team · 2026年10月14日 · 11 min read
讓 AI 代理嘗試修改程式碼時，獨立的工作目錄可以避免影響你正在編輯的檔案。DeepSeek Harness 在 2026 年 10 月 9 日釋出的 dsh-v0.2.1-alpha.2 中加入了實驗性的 Git Worktrees 外掛：建立新分支和工作目錄後，呼叫它的工作階段會切換到新目錄繼續工作。
本文依據 固定版本的外掛指南，安排一個小型驗收練習：建立工作樹，修改一處文件，檢查結果，再返回原目錄。這是基於官方文件設計的操作流程，不代表我們已經實際測試 Harness 桌面版。文中的工具呼叫範例用於說明 AI 代理如何呼叫工具，不能直接貼上到 shell 中執行。
啟用外掛前，先檢查儲存庫
建議使用測試用儲存庫，或選擇一個你清楚當前改動狀態的專案。工作樹執行階段文件 要求檔案系統所在的執行環境具備 Git 2.45 或更新版本，以及 Node。如果使用遠端環境，只檢查筆記型電腦上的版本並不夠。
先讓 AI 代理報告儲存庫根目錄、當前分支、當前提交和簡短的 Git 狀態。對應的唯讀 shell 命令如下：
git --version
node --version
git rev-parse --show-toplevel
git branch --show-current
git rev-parse HEAD
git status --short分支名為空可能表示當前處於 detached HEAD 狀態，應如實記錄。狀態輸出非空也不一定是錯誤，而是說明提交之外還有改動。先判斷新任務是否依賴這些改動；如果依賴，就先準備合適的提交，不要指望工作樹自動複製過去。
外掛不會複製已暫存、未暫存、未追蹤或被忽略的檔案。因此，即使原目錄可以正常執行，新工作樹也可能缺少依賴、本地環境檔案或生成產物。
這張圖說明文件規定的複製範圍，並非應用程式截圖。兩個工作目錄共享 Git 管理資料，檔案分開並不意味著提交歷史彼此獨立。
開啟 Git Worktrees，安排一個小任務
在介面中開啟 Plugins → Official → Git Worktrees，開啟開關。固定版本的外掛指南說明，這個可選外掛套件在所有隨版本提供的設定方案中預設關閉，啟用後會同時載入工作樹執行階段和建立工具。
第一次可以這樣提出要求：為一處文件修正建立工作樹，展示新目錄和起始提交，先等待檢查，不要立即編輯。選擇尚未使用的分支名，例如 docs-worktree-trial。該名稱也會用於相對工作目錄，簡短且有含義的命名便於後續查詢。
建立呼叫如下：
create_worktree({ name: "docs-worktree-trial", from: "HEAD" })from 必須能在本地解析。即使託管網站上存在某個遠端分支，只要本地儲存庫缺少對應物件，仍無法以它為起點建立工作樹。這個操作不會拉取缺失物件、初始化子模組或安裝依賴；重試之前，應先處理真正缺少的前提條件。
修改前，核對工具回傳的目錄
呼叫成功後會回傳 path、branch、baseCommit 和 repositoryRoot，請將四項一起記錄。子系統文件 說明，只有 Git 設定成功後，工作階段才會切換工作目錄。
預設路徑位於當前簽出目錄下的 .agents/worktrees/<name>。如果工作階段原本就在關聯工作樹中，新工作樹的存放目錄也會建在其中。以工具回傳的規範化絕對路徑為準，不要套用另一工作階段裡記下的路徑。
| 回傳欄位 | 檢查內容 |
|---|---|
path |
工作階段當前是否位於這個工作目錄 |
branch |
是否為剛才指定的新分支 |
baseCommit |
是否為預期的本地起始提交 |
repositoryRoot |
是否指向建立前所在的簽出目錄 |
讓 AI 代理在當前目錄再次檢查根目錄、分支和提交，並與建立結果對照。一般情況下，檔案應符合預期的起始版本。不過文件提醒，儲存庫本地的替換引用可能影響簽出內容，因此還應開啟準備修改的檔案，不能只看提交識別符號。
只改一處，再檢查差異
選擇已有 README 的一段文字，只要求補充一項事實說明。首次練習不要從依賴升級或全儲存庫格式化開始，大量差異會讓目錄錯誤更難被發現。
編輯完成後檢查當前分支和改動：
git branch --show-current
git status --short
git diff --check
git diff -- README.md如果修改的是其他檔案，請替換為實際檔名。最後一條命令顯示未暫存的變化；若 AI 代理已暫存改動，還要檢查暫存區差異。git diff --check 沒有報錯，只能說明未發現它檢查的空白字元問題，不能證明文案正確或專案可以建置。
按改動範圍執行必要的專案檢查，並記錄命令、目錄和結果。如果只是修改文件，檢視渲染後的文字往往比執行無關的測試套件更有幫助。
圖中的編號依次表示建立、核對、編輯、檢查、離開。保留下來的分支和目錄，仍需在之後決定如何整合或清理。
返回原目錄，保留後續審查所需資訊
返回時，讓 AI 代理呼叫 working_directory，傳入原簽出目錄的絕對路徑。例如，將下面的範例路徑替換為之前記錄的 repositoryRoot：
working_directory({ cd: "/absolute/path/to/original-checkout" })再次核對當前目錄。離開不會合併改動，也不會刪除工作目錄或分支。關閉 Git Worktrees 外掛同樣會保留已建立的工作樹，而內建的工作目錄工具仍可使用。
先審查差異，再決定如何整合。按專案現有流程提交後，可以選擇合併或 cherry-pick。不再需要工作樹時，先檢查其狀態並儲存改動，再使用 Git 的常規工作樹移除流程。不要一遇到未提交檔案，就直接強制刪除。
建立失敗時，先判斷原因
分支名或目標路徑已經存在，會導致建立失敗。換名字重試前，先檢查已有什麼，尤其是在取消操作之後：失敗過程可能留下部分檔案或 Git 記錄，錯誤會提示位置。不斷生成新名字，反而容易分不清哪一個目錄裡存著要保留的改動。
權限錯誤則要另行處理。已有沙箱策略需要允許寫入目標目錄和共享的 Git 中繼資料；外掛不會自動擴大權限。先確定被拒絕的是哪個位置，再考慮是否需要調整設定。
此外，簽出時會跳過已設定的 clean、smudge 和 process 過濾器，因此 Git LFS 指標或加密資料可能保持儲存庫中的儲存形式。下載真實檔案或解密應作為獨立操作處理。工作樹建立成功，並不意味著執行專案所需的環境已經齊備。
將工具回傳的四項資訊、審查過的差異和檢查結果儲存在一起，下次繼續時就無需猜測 AI 代理用過哪個目錄、從哪個提交開始。關於本次釋出的其他變化及 SDK 遷移，可閱讀 alpha.2 升級指南。