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