dsh-workflow-worktree: DeepSeek Harness 工作流的 Git worktree 隔離後端

前言¶

DeepSeek Harness（DSH）的 @dsh-external/workflow 插件預留了 registerIsolationAdapter() 接口，但未實現具體邏輯。根據其 README，當工作流任務聲明 isolation: 'worktree' 但未配置適配器時，會直接報錯。

dsh-workflow-worktree 插件填補了這一空白。它作爲隔離後端，讓每個具備寫權限的智能體擁有獨立的代碼檢出，且這些檢出在任務結束後仍能保留，不會污染主工作區。

插件定位¶

名稱: dsh-workflow-worktree
核心價值: Git worktree isolation backend for DeepSeek Harness workflows
維護者: lisycotana
許可協議: MIT
分類: 工作流

核心功能¶

該插件實現了 registerIsolationAdapter() 接口，使得 DSH 工作流可以調用 isolation: 'worktree' 模式。主要功能包括：
* 獨立檢出: 爲每個寫權限的工作流智能體提供獨立的 Git worktree。
* 崩潰存活: 通過 manifest 記錄狀態，確保服務崩潰後能恢復 lane 信息。
* 指紋清潔: 通過將 worktree 目錄添加到 .git/info/exclude，確保主倉庫的 git status 保持乾淨。

安裝與啓用¶

安裝前請確保已安裝 @dsh-external/workflow。通過以下命令安裝該插件：

dsh plugin --profile web add @dsh-external/workflow
dsh plugin --profile web add dsh-workflow-worktree

安裝完成後，工作流任務即可請求隔離模式。

典型用法¶

在 workflow 腳本中，直接在 spawnAgent 配置中指定 isolation: 'worktree'。

await wf.spawnAgent({
  name: 'refactor-auth',
  prompt: '…',
  isolation: 'worktree',  // 啓用隔離
})

設計約束與行爲¶

該插件遵循以下設計原則以確保安全性：

拒絕降級: 如果目錄不是有效的 Git 工作樹，或無法創建 worktree，prepare() 會拒絕初始化，直接導致任務失敗。這比靜默運行在主樹中更安全。
返回新 Agent: 返回的 Agent 是全新的實例，其會話（session）必須在 worktree 內部創建，而不是繼承父會話。
保留未提交變更: 任務結束時，如果 lane 仍有未提交的變更，它不會被丟棄，而是被標記爲 retained-dirty。Git 本身禁止刪除 dirty worktree，該插件遵循此行爲。
保持狀態清潔: 工作區指紋校驗依賴於乾淨的 git status。該插件通過 .git/info/exclude 排除 worktree 目錄，防止其被誤判爲未跟蹤文件。
冪等的 Dispose: dispose() 方法可被多次調用，不會報錯。

存儲結構¶

插件會在倉庫根目錄下維護一個 manifest 文件和目錄結構：
* <repo>/.dsh-worktrees/lanes.json: 記錄 lane 的元數據（runId, taskId, path, branch, base commit, session id, status）。
* <repo>/.dsh-worktrees/wf-<runId>-<taskId>: 具體的 checkout 目錄。
* <repo>/dsh/wf-<runId>-<taskId>: 對應的 Git 分支。

可以通過 worktree_lanes 工具查看 lanes 狀態。

已知限制¶

不支持合併: v1 版本僅負責創建和恢復隔離工作區，不處理 Diff/合併邏輯。
髒 lane 累積: 爲了安全，插件只會移除 Git 不再認識的 lane，不會主動清理仍在使用的 dirty lane。
單倉庫限制: 一個 lane 僅支持一個倉庫。如果任務的 cwd 不在倉庫根目錄，該任務會被拒絕。

參考信息¶

目錄頁: https://www.skillhub.cn/plugins/lisycotana/dsh-workflow-worktree
GitHub: https://github.com/lisycotana/dsh-workflow-worktree
驗證環境: @deepseek-ai/dsh@0.1.0-rc.6, @dsh-external/workflow@0.1.2, git 2.47, Node 24, Windows