工作树图谱 JinzhaoTian/git-worktree-graph

Git Worktree

一个原生 DSH 插件。它在 Harness Web UI 的右侧边栏标签页里放了一个 Git worktree 浏览器：当前工作区的 worktree、分支、分页提交图、提交与未提交详情，以及带防护的 worktree/rebase/cherry-pick 操作。标签页跟随发起调用的会话的工作区。

目录结构

| 路径 | 作用 |
| src/index.ts | 宿主端——同源 HTTP 路由及其 Git 载荷 |
| src/client.ts | 浏览器端——右侧边栏标签页注册与传输 |
| src/core/ | Git 核心：固定参数的 execFile 绑定、worktree/ref/graph/patch 读取器、历史操作 |
| src/ui/worktree.ts, src/ui/worktree.module.css | React 面板、响应式图列、diff 视图与主题感知的 CSS Module |
| lib/index.js, lib/client.js | 构建后的宿主端与浏览器端；已提交 |
| scripts/build.mjs | 用 esbuild 打包两端 |
| cordis.patch.yml | 本插件插入的那一行 Loader |

lib/ 是构建产物。改 src/，然后重新构建并提交两者。

构建

需要 Node 20+ 和 Git：

npm install
npm run check # typecheck, then build

npm run build 会写出 lib/index.js 和 lib/client.js。manifest 声明没有运行时依赖，所以安装时不会拉取或构建任何东西。

重新构建宿主端后，重启 Harness。插件重载会从缓存重新导入 lib/index.js，所以 apply() 不会重新执行，HTTP 路由保留旧值；只有新进程才会注册新值。浏览器端在页面加载时重新读取，所以那边刷新一下就够了。

安装

通过 plugin_manager 工具把这个目录作为 bundle 安装（action: install_bundle，target: <this repository>）。然后把它加进配置档的启用列表——<profile>/package.json 里的 dsh.profile.bundles——否则重启后不会加载：

"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@JinzhaoTian/git-worktree-graph"]

设置 patchReload: "live" 后，运行中的 Host 会拾取改动。用 plugin_manager list_plugins 确认：@JinzhaoTian/git-worktree-graph 应有一行 include:git-worktree-graph，且 fiberPhase: "active"。

使用

- 从标签栏的 + 引导打开标签页，或点它的 Git Worktree Graph 卡片。
- 工具栏显示会话所在的 worktree；刷新会重新读取 worktree 和状态。有改动时圆点是琥珀色，干净时是绿色，Host 读不到时是错误色。
- 行只画 worktree 标签和本地分支。展开未提交行会显示它的分支、完整路径、改动统计，以及用 Files 面板的文件夹和文件图标的变更文件树。文件夹行支持键盘访问。两种详情共用一套响应式元数据/文件布局：宽屏时两半是独立列——每侧各有一个标题栏压在自己的滚动区上——所以换行到第二行的提交哈希只会撑长元数据，变更摘要仍保持它该有的一行。
两半之间的分隔条是拖拽手柄：拖动它，或者聚焦后按 ←/→，就能改变宽度如何分配；双击它则恢复均分。分配比例按比例保存，所以面板被调整大小时依然有效，并且会记住，下次打开提交时继续沿用。宽度不够放两列时，两半改为堆叠成单个滚动区域。Show Remote Branches 用来限定图遍历的范围。
- 在任一侧变更文件树里点击文件，会在它自己的标签页中打开对应补丁，这样图保持原位，补丁也能离开再回来。类型是一个复用的页面，而不是每个文件一个：打开另一个文件会重新导航那个标签页，标题也随之改成它当前显示的文件。
- 补丁可以按单列阅读，也可以把旧文件和新文件并排阅读——在头部选项菜单里选 Split view，某一侧没有对应行可显示时，代码列会显示斜线阴影。两个文件的分隔方式，和行号与代码的分隔方式一样：靠几个像素的底色，而不是画一条线。无论哪种方式，代码都保留应用自己的语法配色，所以变更要从它的周边来读，而不是从文字本身：填充色横跨行号和代码，行号外缘有一条线，行号本身用变更的颜色——绿色表示只有新文件才有的行，红色表示只有旧文件才有的行。两列填充的色调略有差别——深色配色下行号比代码更深，浅色配色下更浅——这样行号读起来像是覆盖在变更之上的一列，而不是变更的一部分。它们靠几个像素的底色本身分隔，而不是靠画一条线，这样既能分开两者，又不会让一条线与变更自身的边缘争抢注意力。
那条线是按行画的，所以连续多行会堆叠成一条横跨整个区块的条。行号和其他所有内容站在同一片底色上，长行在它下面滚动时它保持不动——或者让长行换行，用 Wrap long lines，默认开启，因为这个标签页是侧边栏的一列。某个文件完全没有对应行时，表示这一点的斜线阴影只属于代码列：它旁边的行号保持素净，因为行号对不存在的行没什么可说的。
各 hunk 之间未改动的区段只计数、不打印，这正是让大改动保持可读的原因。
- 那个头部就是面板工具栏自带的 38px 条带，用同样的 28px 图标按钮和应用图标集：文件图标、路径和它的 +/- 总数一起放在左边，紧随其后是文件发生了什么以及它属于哪个提交，然后是一个 ⋯ 菜单（分栏视图、换行、复制路径），以及一个箭头，通过标签系统自己的资源地址在文档预览标签页中打开该文件。
- Git 无法按行显示的文件——二进制、太大读不了，或者已从磁盘上消失——会直接说明，而不是打开一个空 diff。
- 图会预留可见泳道所需的宽度。Description 占用剩余空间，Date 和 Author 则随面板宽度变化分摊。所有可见文本列先收缩到各自最小值，然后依次隐藏 Author、Date。提交的 hash 仍保留在所在行的 tooltip 和详情里。
- 受保护的写入会先预览再 Apply，之后才创建 worktree 或执行 rebase/cherry-pick。预览不改变任何东西；它的计划五分钟后过期，只能尝试一次，并会重新对照分支、HEAD 和目标做检查。
- 面板从不检出分支，也从不改变会话的工作目录。

Route

宿主侧负责 Git，并在 Web GUI 自己的服务器上注册 /git-worktree-graph/api，所以标签页读取的是同源地址——不需要 token，不需要 CORS，也不需要第二个端口。

读取是 GET /git-worktree-graph/api/<action>：worktrees、graph、diff、commit、uncommitted、file-diff。写入是 POST，带 JSON body：worktree-create、rebase-preview、rebase-apply、cherry-pick-preview、cherry-pick-apply。写入若指定了其他 origin，会以 403 拒绝；若未声明 application/json，会以 415 拒绝。每次 Git 绑定都是通过 execFile 传入固定参数数组；Git 失败时返回 { "ok": false, "error": "…" }，HTTP 状态码为 200，因为标签页会把它内联渲染出来。

file-diff 指定一个变更文件，并以带行号的 hunk 形式返回它的补丁：path 是文件，oid 是读取它时所在的提交，from 是重命名前它所在的路径——缺少重命名两端的任一端，Git 都会把这个文件报告为全新文件。没有 oid 时，读取的是工作区自身的变更；对于 Git 尚未跟踪的文件，任何 git diff 都答不上来；这种文件直接从磁盘读取，内容作为一个新增 hunk 报告。除非路径是相对路径、不含魔法字符、且不含 ..，否则一律拒绝，这样任何请求都无法触及检出目录之外。file-diff-v1 能力表示该路由存在，但浏览器侧并不据此做门控：那份列表只在标签页打开时读取一次，所以如果宿主之后才获得该路由，过期的答案会让每个文件行都失效。打开某一行会直接询问宿主，没有该路由的宿主会在面板里说明这一点。

Limits

- 未实现 merge 和 commit；已实现 rebase 和 cherry-pick。
- 图是确定性的泳道布局，以行内 SVG 绘制，从最新 → 最旧；追加一页永远不会移动已经画好的行。