前言¶

DSH Web UI 的 composer 区域通常会放置命令入口和模式控件，但在日常使用中，当前工作区所在的 git 分支并不是总是一目了然。如果你经常在 DSH 和其他终端工具之间切换，dsh-git-branch 可以提供一个更轻量的信息位：把当前工作区 git 分支显示在 composer 模式控件旁边，并在窗口焦点、页面可见性、session/workspace 切换时立即刷新。

这是什么¶

dsh-git-branch 是由 hanyueqiang 维护的 DSH 插件，许可证为 MIT。

它作为 DSH bundle 安装，安装命令会把包加入 profile 的 bundles，并在下次启动时通过补丁层生效，因此不需要额外手动配置 host 与 client。

核心功能¶

显示位置¶

插件在 DSH Web UI 的 composer 模式控件后显示当前工作区 git 分支。

客户端会注册 conversation.input.left chip，并注册 conversation.chat.commandview 以隐藏传输命令。

分支显示¶

• 普通分支显示为 ⎇ main
• detached HEAD 显示为 ⎇ detached @ a1b2c3d
• 如果当前工作区不在 git 仓库中，则不渲染任何内容

刷新规则¶

以下事件会触发立即刷新：

1. 插件挂载
2. 切换 session/workspace
3. 窗口 focus
4. visibilitychange 变为可见
5. 点击分支 chip

另外，插件使用 60 秒轮询作为兜底刷新。

相关客户端常量：

POLL_INTERVAL_MS = 60000

POLL_INTERVAL_MS 控制兜底轮询间隔；设置 <= 0 可禁用该轮询。

host 与 client 分工¶

• host 注册 /git-branch 命令，并在命令的 text 字段返回 JSON 结果
• client 注册 conversation.input.left chip，并注册 conversation.chat.commandview 隐藏传输命令

安装与启用¶

1、安装插件：

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

2、如果使用本地 checkout：

dsh plugin --profile web add ./dsh-git-branch

3、重启 profile，并刷新页面。

dsh plugin add 会检测 dsh.bundle，并将包加入 dsh.profile.bundles；补丁层会在下次启动时生效。

典型用法¶

安装并刷新页面后，可以直接在 composer 模式控件旁看到分支 chip。

点击 chip 会立即刷新一次。

如果要修改命令名，可以在自己的 profile cordis.patch.yml 中覆盖同一 id 的行：

- id: git-branch
  name: dsh-git-branch
  config:
    commandName: git-branch   # optional; default is git-branch

注意：未知配置键会导致加载失败。

如果需要关闭兜底轮询，可以将 POLL_INTERVAL_MS 设置为小于或等于 0。

适用场景与注意¶

• 适合在 DSH Web UI 中需要快速确认当前工作区 git 分支的使用者
• 如果工作区不是 git 仓库，插件不会渲染分支 chip
• 配置覆盖时只使用已支持的配置键；未知配置键会导致加载失败
• 插件会随 profile 激活并加入 bundles。由于插件以当前 dsh 进程权限运行，安装前建议检查源码与 MIT 许可证

结尾¶

dsh-git-branch 的价值比较具体：把当前工作区 git 分支放到 composer 模式控件旁，并用焦点、可见性、session/workspace 切换触发刷新，再配合 60 秒兜底轮询。

社区插件目录页：

https://www.skillhub.cn/plugins/hanyueqiang/dsh-git-branch

GitHub：

https://github.com/hanyueqiang/dsh-git-branch