前言¶

DSH 插件化扩展里，一个常见问题是多个子代理同时处理同一仓库时，工作目录容易互相干扰。dsh-worktree 的做法是让每个子代理进入自己的 git worktree：共享仓库对象库，但工作区彼此独立。

下面介绍这个插件的定位、安装方式、典型用法和已知限制。

这是什么¶

dsh-worktree 是一个 DeepSeek Harness 插件，用于给 DSH 子代理提供基于 git worktrees 的文件系统隔离。

• GitHub 仓库：CSY656/dsh-worktree
• 包名：dsh-worktree
• Owner：CSY656
• 许可证：MIT
• 版本要求：DeepSeek Harness next line，dsh >= 0.1.0-rc.6

它提供两种入口：面向插件作者的 ctx.worktree 服务，以及面向人的 /worktree 斜杠命令。

核心功能¶

隔离位置与命名¶

worktree 位于：

<repoRoot>/.dsh/worktrees/<flatSlug>/

如果 slug 是嵌套形式，/ 会被扁平化为 +。例如：

feature/demo → feature+demo
team/alice   → team+alice

对应分支使用 worktree-<flatSlug>，例如：

worktree-feature+demo

slug 校验¶

创建 worktree 前会严格校验 slug：

• 每段字符限制为 [a-zA-Z0-9._-]
• 每段长度不超过 64
• 拒绝 .、..、//
• 拒绝首尾分隔符

创建后的尽力配置¶

创建 worktree 后，插件会尽力执行 setup：

• 复制项目 .dsh 配置
• 继承 core.hooksPath
• 符号链接 node_modules、.venv、vendor
• 复制 .worktreeinclude 列出的忽略文件

变更保护¶

变更检测采用 fail-closed：git 失败会按“有变更”处理。因此，脏 worktree 会被保留并报告，而不是直接删除。

临时 worktree 清理¶

插件支持配置：

• sweepIntervalMs
• sweepMaxAgeMs

用于周期性清理 agent-* 临时 worktrees。

安装与启用¶

从 GitHub 安装¶

dsh plugin --profile default add github:you/dsh-worktree

pnpm >= 10 的处理¶

如果使用 pnpm >= 10，需要在 profile 的 pnpm-workspace.yaml 中允许构建：

allowBuilds:
  dsh-worktree: true

然后重新运行 add 命令。

npm 预构建安装¶

README 也给出 npm 预构建安装命令：

dsh plugin --profile default add dsh-worktree

安装前检查¶

dsh-worktree 以当前 DSH 进程权限运行。安装前建议检查源码、许可证与依赖，确认其行为符合你的安全要求。

典型用法¶

斜杠命令¶

/worktree create feature/demo
/worktree list
/worktree remove feature/demo

对应行为：

• /worktree create feature/demo：创建 .dsh/worktrees/feature+demo，分支为 worktree-feature+demo
• /worktree list：输出 name/path/branch 行
• /worktree remove feature/demo：worktree 脏时拒绝删除；加 --discard 可强制

Service API¶

插件作者可以通过 ctx.worktree 服务创建和管理 worktree：

const lease = await ctx.worktree.acquire('agent-abc1234', cwd)

// ... 将 worktree 路径交给独立子代理执行 ...

const { kept, path, branch } = await lease.release()

release 后：

• 干净的 worktree 会被移除
• 脏的 worktree 会被保留并报告

适用场景与注意¶

适合需要让多个子代理并行修改同一仓库，但不希望它们直接覆盖同一工作区的场景。

使用时的限制如下：

• 仅进程内隔离有效；acp、claude-code、codex、dsh-sdk 等 out-of-process backends 会忽略 child-session cwd overrides
• 不跨进程共享，一个 DSH 实例拥有其 worktrees
• 没有合并策略；保留下来的 worktree 由委派 agent 执行合并，例如：

git merge worktree-<flatSlug>

• 一行式 subagent 自动隔离需要 dsh-subagent/dsh-tool-subagent 的上游能力；在上游接受前，需要手动使用 ctx.worktree.acquire() 或 /worktree 命令

结尾¶

dsh-worktree 的价值在于把 DSH 子代理的文件系统隔离落到 git worktree 上，并通过 fail-closed 的变更保护降低误删脏工作区的风险。

它属于 DSH 插件生态中的一个独立插件；社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系，不应理解为官方应用商店。

本次已核实资料未给出可确认的目录页 URL；GitHub 仓库为 https://github.com/CSY656/dsh-worktree 。