Palaiologos1453/dsh-worktree-studio

Worktree Studio

Worktree Studio 是面向 DeepSeek Harness 的人工操作 Git worktree 任务工作台。它为任务创建独立分支和 linked worktree，把检出目录作为原生 DSH Workspace 与 Session 打开，将验证结果绑定到精确的 Git 内容状态，并在合并前执行预检和完整复查。

插件不注册模型工具，不修改 System Prompt，也不增加工具 Schema。工作台和 /worktree-studio 命令都不进入模型上下文，因此安装后不会增加 Prompt token，也不会改变前缀缓存行为。

界面截图

Worktree 任务工作台

验证与交付检查

适用场景

当用户希望同时打开并监督多个隔离编码会话，并由自己掌握最终交付决定时，可以使用 Worktree Studio。它不是子代理编排器：插件负责创建检出目录和 Session，具体工作由用户或已有 Agent 工作流决定。

- 一个任务对应一个分支、linked worktree、DSH Workspace 和 Session。
- 侧边栏工作台集中显示多个仓库的提交、暂存、未暂存和未跟踪状态。
- 改动审阅包含有界 diff、stat 摘要和未跟踪路径。
- 验证结果绑定 SHA-256 token；token 覆盖 HEAD、Git 状态、tracked diff 字节和未忽略的 untracked 文件内容。
- 合并预检使用 git merge-tree，不修改目标 checkout 或 index。
- 交付时重新检查内容 token、验证结果、目标 HEAD、目标干净状态和可合并性。
- 归档保留任务记录；丢弃必须明确确认任务 ID。
- 原子状态写入、跨进程变更锁和启动恢复标记会暴露中断操作。

环境要求

- DeepSeek Harness 0.1.0-rc.7 或兼容的 0.1.x 版本。
- 带标准本地 subprocess provider 的 DSH Web profile。
- Node.js 22.19.0 或更高版本。
- 支持 merge-tree --write-tree 的 Git；建议使用 Git 2.38 或更高版本。
- 至少包含一个提交的本地 Git 仓库。

安装

npm 包发布后安装预构建版本：

dsh plugin --profile web add dsh-worktree-studio
dsh web

npm 发布前可以安装仓库构建：

dsh plugin --profile web add github:Palaiologos1453/dsh-worktree-studio
dsh web

本地开发时，在插件 checkout 中执行：

pnpm install
pnpm run build
dsh plugin --profile web add .

安装后，Web 侧边栏底部会出现 Worktree 任务入口。移除插件不会删除已管理的 worktree 或状态文件：

dsh plugin --profile web remove dsh-worktree-studio

工作流程

1. 打开 Worktree 任务，选择已注册的仓库并新建任务。
2. Worktree Studio 在 managed root 下创建 dsh/-，把路径注册为 DSH Workspace，在其中启动 Session，然后关闭工作台。
3. 在该 Session 中完成并提交改动。工作台会继续报告 staged、unstaged 和 untracked 文件，但交付要求任务 checkout 干净且至少包含一个新提交。
4. 输入 pnpm test 等验证命令并运行 验证。Shell 操作符不会被解释，命令会解析为 executable 和 argv。Windows 使用固定 PowerShell 适配器解析 .cmd 与 .exe shim，argv 以 JSON 通过 stdin 传入，不会拼接进脚本。
5. 使用 查看改动 检查有界 diff，再运行 合并检查，测试当前任务提交与目标 checkout 是否可合并。
6. 交付 会打开确认弹窗。Host 会重新执行所有安全检查，仅在任务和目标仍满足已检查条件时创建 non-fast-forward merge commit。
7. 归档 会移除干净的 linked worktree 并保留记录。丢弃 只有在独立风险确认和 Host 端精确任务 ID 确认后，才会强制移除 checkout。

命令

人工命令在本地处理，不会发给模型：

/worktree-studio list
/worktree-studio create
/worktree-studio inspect
/worktree-studio validate
/worktree-studio preview
/worktree-studio deliver
/worktree-studio archive
/worktree-studio recover

丢弃只在 Web 工作台提供，因为那里会展示风险确认。命令使用当前 Session workspace 作为仓库或交付目标。

配置

Bundle 会插入使用 Schema 默认值的 Host 和命令条目。部署需要修改路径或限制时，在 Web profile 最后应用的 cordis.patch.yml 中覆盖 dsh-worktree-studio 条目。

| 字段 | 默认值 | 含义 |
| --- | --- | --- |
| managedRoot | $DSH_HOME/plugins/dsh-worktree-studio/worktrees | 插件创建 worktree 的父目录。 |
| statePath | $DSH_HOME/plugins/dsh-worktree-studio/tasks.json | 原子 JSON 任务状态；不得位于 managedRoot 内。 |
| gitTimeoutMs | 60000 | 单次 Git 操作的截止时间。 |
| terminationGraceMs | 3000 | 受管进程树从 TERM 升级到 KILL 的等待时间。 |
| validationTimeoutMs | 600000 | 单次验证命令的截止时间。 |
| maxOutputBytes | 1048576 | Git 诊断和验证各输出流保留的最大字节数。 |
| reviewMaxBytes | 524288 | 审阅时保留的 diff 和未跟踪路径最大字节数。 |
| requireValidation | true | 交付前要求验证通过且结果绑定当前内容 token。 |

Host 加载时会解析相对路径。空路径、非正数限制，以及位于 managed worktree root 内的状态文件都会导致插件启动失败。

安全模型

Host 路由只接受 loopback 连接、loopback Host authority 和同源浏览器标记。它是执行边界，不是身份认证：以同一用户运行的本地进程仍可访问 loopback 服务，就像它可以直接运行 Git 一样。

Git 和验证命令通过 DSH 的受管 subprocess 服务运行。Provider 会移除名称类似凭据的环境变量和所有环境中的 DSH_* 变量，管理完整进程树，升级终止超时进程，并等待进程树退出。除 provider 清理后的基础环境外，验证只显式收到 CI 覆盖值。

交付不信任浏览器结果。Manager 会跨进程序列化变更，检查当前内容 token，要求任务改动已提交，在启用时核对验证 token，执行新的合并预检，持久化 pending operation，并在 git merge 前再次检查目标 HEAD 和干净状态。

如果合并失败后无法确认目标已恢复到原 HEAD 和干净状态，任务会进入 recovery-needed，而不是报告普通冲突。recover 会核对持久化标记与 Git worktree metadata，但不会删除身份不明的路径。

漏洞报告和信任假设见 SECURITY.md，状态与生命周期细节见 docs/architecture.md。

当前限制

- Worktree Studio 只管理本地仓库，不推送分支，也不创建 Pull Request。
- 交付合并已提交改动，不会把未提交 working tree 复制到目标 checkout。
- ignored 文件不进入 change token；验证可以生成普通 ignored 构建产物而不让自身结果失效。
- Web 工作台默认以任务创建时记录的仓库 checkout 为目标；Manager API 和命令适配器可以指定同一 Git common directory 下的其他 checkout。
- git merge-tree --write-tree 不修改目标 checkout 或 index，但 Git 可能向共享对象数据库写入临时对象。
- 已归档和已丢弃的记录会保留在 tasks.json；当前版本不会自动清理历史记录。

开发

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

测试使用真实临时 Git 仓库、真实 DSH Web server 和本地 subprocess provider，覆盖任务生命周期、内容 token 失效、验证、合并预检与交付、恢复、有界输出、凭据清理、Windows 命令 shim 和 loopback 请求信任。

许可证

MIT