dsh-git-worktree

dsh-git-worktree

让 Agent 在独立 Git Worktree 中完成任务，你看过修改后再决定是否保存。

dsh-git-worktree 是 DeepSeek Harness 的 Git Worktree 插件。它会为每个编码任务创建独立的 Worktree（工作目录），Agent 不会直接改动你正在使用的项目。任务完成后，你可以先预览结果，再选择保存、退回修改或放弃。

这套 Git Worktree 工作方式最初来自基于 Pi Agent Runtime 的开源桌面 coding 工作台 Domi，本插件是针对 DeepSeek Harness 独立适配的版本，可以单独安装和使用。

English · 完整使用指南 · 架构说明

为什么使用它？

让 Agent 直接修改当前项目时，它的改动可能与你尚未提交的内容混在一起；同时运行多个任务时，也更容易互相影响。使用本插件后：

• 每个任务都在自己的 Git Worktree（独立工作目录）中修改和测试；
• 多个任务可以同时进行，不会共用同一个工作目录；
• Agent 完成后，你可以先把修改临时显示在当前项目中查看；
• 只有确认后才会保存本轮修改，遇到冲突时不会自动覆盖你的内容。

核心能力

• Git Worktree 隔离：每个任务都有独立的工作目录和 Agent 对话。
• 多个 Worktree 并行：可以同时开发多个任务；为了避免混入修改，同一项目每次只验收一个任务。
• 提交前预览：先在当前项目中查看真实效果，不会立即创建 Git 提交。
• 不满意可以退回：撤回本次预览，继续让 Agent 修改，不影响其他本地改动。
• 只保存本轮任务：确认后只提交这个任务的修改，不把无关内容一起带入。
• 长任务可分阶段：先保存当前阶段的进度，再继续开发；最终仍合并为一次交付。
• 出错时保护现场：检测到分支变化、内容冲突或中断时停止操作，保留现场供你处理。
• 集中查看任务：同一项目的当前及历史 Worktree 会按 Host 导航归属聚合到侧边栏，归属不明确时保守保留原位置。
• 验收详情集中查看：从验收条打开只读详情，查看文件列表、验证记录与版本信息，不必翻找聊天工具记录。
• 空仓库安全起步：无提交仓库可在明确确认后创建不包含用户文件的空首次提交，再建立隔离 Worktree。
• 携带项目 Skills：首次及下一轮 Worktree 创建时一次性携带 .dsh/skills、.agents/skills 和 .claude/skills，辅助文件与 Git 交付隔离。
• 原对话继续下一轮：任务交付后，无需新开对话即可继续下一项修改。

当前版本管理单个项目中的 Git Worktree，暂不提供跨项目的全局管理界面。

工作流

flowchart LR
    A[当前项目] -->|创建隔离任务| B[独立 Git Worktree]
    B --> C[Agent 修改并测试]
    C --> D[查看验收结果]
    D -->|预览修改| E[在当前项目中查看效果]
    E -->|确认并保存| F[创建本轮提交]
    F --> G[在原对话继续下一轮]

    D -.->|保存阶段进度| H[继续开发]
    E -.->|撤回本次预览| I[返回修改]
    D -.->|跳过预览| F

怎么选？

目标	操作
先在当前项目中查看效果	预览修改
预览结果没有问题	确认并保存
任务很长，先固定当前进度	保存阶段并继续
还要让 Agent 改代码	继续修改或撤回本次预览
不需要先查看效果	跳过预览并保存

详细的操作、恢复场景和命令见完整使用指南。

快速开始

环境要求

• Node.js ^22.19.0 || >=24.0.0
• DeepSeek Harness：插件按 Host 版本分线——0.10.0 面向 DSH 0.2.0-rc.2（peers 精确锁定；已通过隔离源码 Host 的安装、启动、Worktree 开关与预会话创建真实验证，AI 对话与交付全流程仍待验收）；DSH 0.1.x 请使用 0.9.x 插件线。详见兼容矩阵与限制。
• Harness Web Client
• Git Workspace

从旧 Harness 升级时请先处理 Host 数据迁移：0.1.2-rc.1 已移除可选 SQLite Session 后端，旧数据需使用旧版 Harness 导出；Code Mode 已更名为 PTC mode，但现有会话记录仍可读取。应用和本插件统一通过 dsh Profile 启动与安装。

从旧版 Harness 升级后，如果 Web 界面提示 Failed to load plugins，先确认插件线与 Host 版本匹配：DSH 0.2.x 使用 0.10.0，DSH 0.1.x 使用 0.9.3；再按兼容矩阵排查并重启 Harness。历史版本 0.7.2 及更早依赖已停止发布的 dsh-client-runtime；0.7.3 在 rc.1 Web Client 中还可能形成 conversation / uiWorkspace 循环等待。

dsh plugin --profile web add dsh-git-worktree@0.10.0

安装

dsh plugin --profile web add dsh-git-worktree

也可以安装指定版本：

dsh plugin --profile web add github:wloops/dsh-git-worktree#v0.10.0

刚发布的新版本可能被 Harness 的供应链防护（minimumReleaseAge）暂时跳过而回退旧版，安装时报「与当前 DSH 不兼容」；此时请显式指定精确版本（如 dsh plugin --profile web add dsh-git-worktree@0.10.0），或待防护窗口过后重试。

安装后打开 Git Workspace，在新建 Session 时启用 Worktree；已有 Local Session 也可以让模型调用 worktree_create 创建隔离 Session。

第一次使用建议先完成一次“创建 → 预览修改 → 确认并保存 → cleanup”的完整流程。

如果 Git 源安装被 pnpm build approval 阻止，或需要查看完整命令和排错步骤，请阅读安装与使用指南。

界面预览

项目聚合与任务状态

准备验收

完整操作步骤见完整使用指南。

安全边界

每次把任务修改写回当前项目之前，插件都会重新确认任务版本、项目位置和文件状态仍与验收时一致。如果你切换了分支、修改发生冲突，或上一次操作意外中断，插件会停止写入并保留现场，而不是猜测后继续覆盖。

Worktree 隔离主要用于避免任务之间误改文件，不是用来运行不受信任代码的系统沙箱。

更详细的状态检查与恢复规则见：

• Worktree Console 架构
• Session Target 迁移说明

当前限制

• 只有归属关系明确的任务才会聚合到原项目；无法确认时仍保留原位置，避免任务被隐藏。
• 隔离任务可以重命名和归档，暂不支持从任务对话直接复制出新任务（Fork）。
• 子 Agent 与父任务使用同一个工作目录，不会再为每个子 Agent 创建新的 Worktree。
• 已保存的阶段记录暂不支持编辑、删除、调整顺序或回退到任意阶段。
• Domi 中更完整的跨项目管理、直接修复当前项目、依赖复用和协作交接能力不在本插件当前范围内。

本地开发

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm run check:publish

端到端启动：

pnpm run dev:dsh

更多开发命令见完整使用指南，发布前检查见发布清单。

文档

• 完整使用指南
• Worktree Console 架构
• Session Target 迁移说明
• UI 开发说明
• 发布清单
• 变更记录

许可证

MIT

界面语言

插件跟随 DSH 的中英文选择，不提供独立语言开关。请在 DSH 中明确选择 English，以便界面、工具和 /worktree 消息都使用英文；自动浏览器语言尚未写入 DSH 偏好时，工具和命令会回退中文。详见 语言传递与文案贡献说明。