frederico-kluser/dsh-worktree-jump

dsh-worktree-jump

一个 DeepSeek Harness (DSH) 插件：在新对话界面中提供一个触发器，从所选文件夹创建 git worktree，并在其中启动对话。

在新对话中（选择工作区文件夹后），一个紧凑的标签会立即出现在 选择工作区 选择器的左侧——同一行，同样的样式：🌿 新建 worktree · 。点击它，输入一个名称（例如 my-feature），确认——对话就会在 /.worktrees/ 内启动，模型也在那里工作。该触发器仅在对话仍为空（尚未发送任何消息）且所选文件夹位于 git 仓库内时出现；一旦对话开始，它便不再显示。

┌──────────────────────────────────────────────────────────────┐
│  hero headline (fish …)                                       │
│  [🌿 New worktree ·   [📁 folder selector]  [mode selector]   │ ← the trigger (this plugin), left of the workspace chip
│   my-repo]                                                    │
│  ┌─ composer card ──────────────────────────────────────────┐ │
│  │  Type a message…                                          │ │
│  └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│ click the trigger
▼
┌─ Create a worktree ──────────────────────────────────────────┐
│  Worktree name  [ my-feature              ]                  │
│  Letters, digits, dots, underscores, hyphens.                │
│  Repository: /home/you/proj  ·  main                         │
│  Existing worktrees · start inside one instead               │
│  ┌──────────────────────────────────────────────────────┐    │
│  │ existing-branch                                      │    │  ← one button per existing worktree
│  │ hotfix-login                                         │    │
│  └──────────────────────────────────────────────────────┘    │
│                        [Cancel]  [Create and start]          │
└──────────────────────────────────────────────────────────────┘
│  host: git worktree add /.worktrees/ -b
│        + fork the blank Session with meta.cwd = worktree
▼
the conversation starts inside the worktree
(sidebar nests the child under the source; a Workspace is
created over the worktree directory)

现有的 worktree 是可选择的：每一个都渲染为一个按钮（其分支名称）；点击后会在该目录内启动对话——不会创建新的 worktree，而是运行相同的宿主端 fork 流程，并将 meta.cwd 指向所选目录。

本地化

触发器和其对话框已本地化为三种语言——英语（en，回退语言）、简体中文（zh）和葡萄牙语（pt，作为可选语言添加）。任何其他 DSH 区域设置都会回退到英语。按钮和模态框共享同一个字典，因此它们会一起切换。
为什么 fork 是传输机制

DSH Session 头部的 cwd 是冻结的创建元数据——harness 没有就地切换目录的能力（系统提示中的 {{cwd}}、shell 工具的默认工作目录以及沙箱根目录都派生自 session.header.cwd）。将对话带入新目录的文档化方式是 fork：harness 自身的 session.fork RPC 会原样继承源 cwd，因此本插件运行相同的宿主侧 fork 流程（sessionQuery 观察 → 使用平衡的已完成轮次种子、parentSession 谱系、源挂载的 agent 预设、当前默认模型调用 agents.create），唯一的产品所需差异是：meta.cwd 是 worktree 路径。

在“新建对话”流程中，源 Session 是工作区的空白占位符，因此种子为空，子会话全新开始——你输入的第一条消息会落在 worktree 中。对于已有对话，同一流程会将其转录内容携带至最后一个已完成轮次。

具体来说，点击创建并启动会按顺序执行以下操作：

1. 校验名称（1–64 个字符，首字符为字母/数字，随后为字母、数字、.、_、-；不得包含斜杠、空格或前导 ./-）——一个单一且安全的文件系统与 git 片段，复用为分支名。
2. 规划 worktree：默认根目录为 /.worktrees/，可通过配置覆盖。
3. 通过 .git/info/exclude（仓库本地、永不被跟踪的文件——绝不修改任何被跟踪文件）排除 worktree 根目录。
4. 创建：通过宿主的子进程运行时执行 git worktree add  -b （受管进程树、清理过的环境变量、每命令截止时间、GIT_TERMINAL_PROMPT=0，因此 git 永远不会等待人工输入）。
5. Fork：调用 agents.create，携带源截至最后一个已完成轮次的事件（isSeeded + 精确继承的长度）、parentSession 谱系、挂载源的 agent 预设，并将 meta.cwd 覆盖为 worktree 路径。尚无已完成轮次的源会作为空白延续进行 fork（没有可继承的持久内容；原始会话保持不变）。
6. 分组：在 worktree 目录上查找或创建 Workspace 并附加子会话，以便侧边栏将延续会话归组在其目录下。附加失败绝不会导致创建失败——无论哪种情况，会话都存在且可打开。
7. 浏览器端打开子会话（ctx.uiWorkspace.openSession，回退到会话列表）——相同的转录内容，新的工作目录。
降级而非失败： worktree 之上的 Workspace 是在 fork 之前 创建的，因此无论后续发生什么，它都存在。如果 fork 本身失败（worktree 已在磁盘上且其 Workspace 已处于活动状态），路由会返回 forked: false + workspaceId，浏览器会在该 Workspace 内启动一个全新的 Session——worktree 永远不会丢失，并且对话框会展示服务器自身给出的原因。重复检查也以同样的方式预先进行：已存在的 worktree 或分支会返回结构化的 409（worktree-exists / branch-exists），对话框会将其与可选的现有 worktree 按钮一并呈现，而不是走向死胡同。

原始 session 留在原始文件夹中；fork 是延续。这就是 DSH 模型（不可变的创建元数据），这也意味着只需在侧边栏中切换回去，该移动就是可逆的。

安装

该插件是独立的 ESM，具有零运行时依赖（宿主部分仅导入 node 内置模块；浏览器部分仅需要平台模块表词汇）。构建产物已提交在 lib/ 下，因此安装时永远不会运行构建脚本。

⚠️ 只选择一种激活路径。 bundle 安装和手动补丁条目会插入相同的加载器条目 id（worktree-jump）；两者同时激活会在启动时抛出 duplicate loader entry id: worktree-jump。要切换路径，请先移除另一个（如果存在，请用 dsh plugin --profile web remove dsh-worktree-jump 删除已安装的包）。将插入行粘贴到 profile 的 cordis.yml 中也是如此——该文件是 include 自身的条目列表，必须保持为 []；受支持的用户文件是 cordis.patch.yml。

从 GitHub 安装（git 托管的 bundle；没有 prepare 脚本，因此无需 allowBuilds 那一套）：

dsh plugin --profile web add github:frederico-kluser/dsh-worktree-jump

dsh plugin add 会将包追加到 profile 的 bundle 列表（dsh.profile.bundles），因为该包声明了 dsh.bundle.patch；bundle 层会自行插入插件行。不要同时为它添加手动 - insert: 行。 重启 dsh web（或者如果你的构建支持实时 profile 补丁，则重新加载它），按钮就会出现在每个工作区为 git 仓库的 session 中。

从本地检出安装（开发循环）：将用户补丁层指向构建后的入口——绝对路径是有效的加载器条目——并确保该包没有同时安装在 profile 中：

$DSH_HOME/profiles/web/cordis.patch.yml
- insert:
- id: worktree-jump
name: '/absolute/path/to/dsh-worktree-jump/lib/index.js'

移除该条目即可停用。优先级和四个补丁层记录在 DSH 插件文档中。

故障排除
- 启动时出现 duplicate loader entry id: worktree-jump —— 该插件被激活了两次（bundle 安装 + 手动插入，或 cordis.yml 中粘贴了一行）。只保留一个：要么卸载该包（dsh plugin --profile web remove dsh-worktree-jump），要么将你的 cordis.patch.yml 清空回 []。该 profile 的 cordis.yml 必须保持为空列表。

配置

在加载时进行校验；违反规则会导致加载大声失败（绝不使用宽松的回退）。

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| worktreeRoot | 按仓库 /.worktrees | 新 worktree 的创建位置。位于仓库之外的根目录会跳过排除文件步骤。 |
| gitTimeoutMs | 30000 | 每条 git 命令的截止时间（1–600000）。 |

- id: worktree-jump
name: 'dsh-worktree-jump'
config:
worktreeRoot: /srv/worktrees
gitTimeoutMs: 10000

安全模型

暴露面是位于组合现有信任围栏之后的两条回环路由——与每个第一方 web 路由首先询问的围栏相同（connection.requestRejection：针对 DNS 重绑定的 Host/Origin 围栏 + 浏览器认证）。在此之上：

- 绝不从网络接受任何路径。 status 和 create 路由接收 sessionId；工作区目录、仓库根目录和 worktree 路径均派生自会话自身的 header 和解析后的仓库。恶意页面无法探测任意目录。
- 对 create 请求体进行网络校验：必须恰好为 application/json，上限 64 KiB，字符串字段，以及上述名称语法。方法守卫返回 405；拒绝响应是结构化的，且每个错误码字节完全一致（无信息泄露）。
- 不使用 shell：git 通过宿主子进程接缝以显式 argv 运行（绝不经过 shell 解释），忽略 stdin，使用受限环境（GIT_TERMINAL_PROMPT=0、GIT_OPTIONAL_LOCKS=0），并设有可中止受管进程范围的截止时间。
- 不存储、记录或传输任何机密；该插件每次 create 只写入一个文件（.git/info/exclude）和一棵目录树（该 worktree）。
- 客户端的 POST 携带 JSON 内容类型，跨站页面无法在宿主从不授予的 CORS 预检的情况下发送该类型。

开发

构建和测试需要附近有一份 DeepSeek Harness 检出（用于 TypeScript 工具链和 @deepseek-ai/* 类型声明——仅构建时使用，以符号链接方式放入 node_modules/）：

DSH_CHECKOUT=/path/to/deepseek-harness npm run setup   # 或 pnpm run setup
npm run build      # tsc 类型检查 + tsdown（node 半部分 ESM + 浏览器 CJS 工厂 bundle）
npm test           # 41 个 node:test 用例
测试在构造上完全隔离：真实 git 仅在 os.tmpdir() 夹具内运行，无端口、无套接字、无 DSH_HOME 访问、无网络。替身遵循行为契约（子进程替身通过 spawn-spec 形状生成真实进程，因此运行时变更会大声地破坏测试）；补丁语义测试运行的是 vendored 测试框架代码（applyEntryPatches）本身。测试套件以对抗性方式断言安全行为：围栏顺序（在任何逻辑之前拒绝）、方法守卫、媒体类型和请求体大小拒绝、未知会话、非仓库、名称伪造，以及 fork 始终落在 worktree 路径上——绝不是原始文件夹。

已验证的 API 表面

插件触及的一切都已对照真实 DSH 源码而非文字描述进行核查：webServer.register 的确切路由和重复抛出语义（@deepseek-ai/dsh-host-webserver）、连接信任围栏（@deepseek-ai/dsh-client-connection 节点半边，与已发布的 open-in-app 宿主半边所做的调用相同）、subprocess spawn-spec 子进程、sessionQuery.observeSession（带投影的确切观察）、带 meta.cwd 覆盖 + seed/inheritedEventCount 的 agents.create（@deepseek-ai/dsh-agent CreateAgentOptions）、agentPresets.resolve/mount、workspaceRegistry.create/attachSession、conversation.input.overlay 槽位（已发布的 ui-commands 弹窗是参考）和 SessionSnapshot.blank 门控、客户端模块 dsh.client/exports["./client"] 浏览器名册、__ModuleLoader__.load({id, factory}) CJS 工厂 bundle 契约，以及实时用户补丁监视器（watchUserPatches → entry.update，它对未更改的条目无操作——正是这一属性使热激活安全）。

许可证

MIT