Git 分支面板 MYiYang/dsh-git-branch

dsh-git-branch

npm 包：dsh-git-branch-plugin（npm i dsh-git-branch-plugin /
dsh plugin add dsh-git-branch-plugin）。GitHub 仓库是
MYiYang/dsh-git-branch；插件内 id dsh-git-branch、路由前缀 /git-branch/api 和加载器行 id git-branch 都不受 npm 包名影响。

DSH Web 插件，把当前 Git 分支放进会话输入框，在那里列出所有本地和远程分支，支持切换本地分支，还能打开只读提交图。

- 只对 Git 项目可见。 会话工作目录不在 Git 仓库内时，这个标签隐藏。
- 位置： 消息输入框的紧凑控制行（conversation.input.left），在模型选择器左侧。
- 显示内容： 当前分支名；处于 detached HEAD 时显示 HEAD@<short commit>。
- 分支表格： 点击标签打开四列表格：

| 列 | 本地分支 | 远程分支 |
| 分支 | 名称（已检出时带对勾） | 名称（地球图标） |
| 上游 | 跟踪引用，例如 origin/main | 空 |
| 领先·落后 | 相对上游的 ↑2 ↓1，同步时显示 = | 空 |
| 最近提交 | 短哈希（提示框里显示主题/日期） | 短哈希 |

本地行排在前面，远程行排在后面。分支超过 8 个的仓库会出现搜索框，同时过滤两组。只有本地分支提供切换（git checkout <branch>）——远程行只用于展示，点击不会让 HEAD 脱离，也不会创建分支。失败情况（工作区有改动导致冲突、状态无效）在菜单内显示。
- 提交图： 菜单标题栏的按钮打开只读图面板（空间够时在标签上方，否则在下方）。它为从所有引用可达的历史（最多 200 个提交）绘制泳道和圆点，带分支、远程和标签徽标，以及主题、短哈希、作者和日期。按 Esc、点关闭按钮或点面板外部即可关闭。
- 刷新： 页面可见时每 15 秒重读一次状态，窗口获得焦点、页面变为可见、切换分支后立即重读——所以智能体或终端改动的分支也能显示出来。图在面板打开时读取，也可以从标题栏刷新。

目录结构

| 文件 | 作用 |
| index.js | 宿主端：挂载受信任围栏保护的 POST /git-branch/api/{status,checkout,graph} 路由，并解析会话的工作目录。 |
| git.js | git 层：只用 argv 调用 git，列出本地/远程分支（上游、领先/落后、最近提交），切换分支，读取提交图，检测 detached HEAD 和非仓库。 |
| graph.js | 纯提交日志解析器和 git log --graph 风格的泳道布局，供图面板使用——不访问仓库或 DOM，有完整单元测试。 |
| client.js | Web 客户端部分：编辑器芯片、四列分支表、提交图面板、轮询和语言环境接线。 |
| cordis.patch.yml | 打包补丁，插入 Host 行（git-branch）。 |
| locale/*.json | 插件管理器的标题和描述（英文和中文）。 |
| icon.svg | 插件图标。 |
| test/git.test.js | Git 层测试，跑在临时仓库上（包括一个真实远程仓库）。 |
| test/graph.test.js | 解析器和布局的单元测试，外加一个真实合并历史的冒烟测试。 |
| test/route.test.js | 路由测试，走真实的 apply 和 handler。 |

两部分如何通信

浏览器跑不了 git，所以客户端部分调用唯一的 Host 路由：

- status → { isRepo, root?, branch?, detached?, commit?, branches }，对应会话的实时工作目录（workingDirectory.get(session)，回退到会话头部的 cwd）。每个分支行是 { name, kind: 'local'|'remote', current?, upstream?, ahead?, behind?, lastCommit? }；远程行只带 name 和 lastCommit，客户端对它们留空 upstream / ahead-behind 单元格。
- checkout → 在那里执行 git checkout <branch>（仅本地名称），然后返回同样的 status 结构。
- graph → { root, rows }，每行是一个提交加上它的泳道几何信息： { hash, short, parents, author, time, subject, refs, head, lane, nodeColor, nodeFromTop, links: [{ from, to, color }], laneCount }。一条链接从顶部边缘的泳道（from）出发，经过提交的圆点（null，表示父提交），或到达底部边缘的泳道（to，表示此提交的父提交）。

路由通过 ctx.webServer 注册，并用 ctx.connection.requestRejection 围栏保护，所以只有已认证的 Harness 页面能调用它；它只接受 POST。目录从不来自请求，分支名在 checkout 前会对照仓库自己的 refs/heads 列表检查，所以请求无法到达任意路径或 git 标志。

安装

from npm
dsh plugin --profile web add dsh-git-branch-plugin

or a local checkout (development)
dsh plugin --profile web add ./dsh-git-branch

这个包是 DSH bundle（自带 cordis.patch.yml），所以添加它会安装依赖并激活 Host 行。确保包也列在配置档的 dsh.profile.bundles 中（~/.dsh/profiles/web/package.json）；没有该条目，bundle 虽已安装但永远不会被分层。

安装或编辑此包后，重启 DSH 让 Host 部分加载新路由，然后刷新 Harness 页面让浏览器加载当前的 client.js（已打开的页面可能保留它已加载的客户端模块）。

测试

在此目录下：

node --test test/git.test.js test/graph.test.js test/route.test.js

或 npm test。测试套件在操作系统临时目录下构建临时仓库，之后删除它们；一个 fixture 还会创建一个裸远程仓库用来验证远程跟踪引用、origin/HEAD 以及领先/落后计数。

说明与限制

- 只切换本地分支；远程分支仅以只读方式列出（检出远程分支会让 HEAD 脱离，或者需要新建本地分支——这两件事都属于终端/智能体的操作）。
- 提交图是只读的，最多显示所有引用中最近的 200 个提交。它从不带请求中给出的路径或版本执行 git log；仓库始终是会话自己的仓库。
- 使用 git checkout 而不是 git switch，这样在某些 Windows 主机自带的 Git 2.18 上也能用。
- 插件只解析一次 git——先查 subprocess 服务的执行环境，再扫描 PATH——并用 git --version 探测每个候选。不可执行的 PATH shim（例如 depot_tools 带来的 Windows git.bat）会被跳过，因此真实仓库绝不会被误报为「不是仓库」。当没有任何 git 能启动时，这个 chip 就直接隐藏。
- 每次请求都会重新解析工作目录，因此迁入链接工作树的会话会显示该工作树的分支。

许可证

MIT