前言¶
用 DSH 做开发时，agent 会话的工作目录通常就是一个 git 仓库。想切分支、同步远端、把当前改动提交推送，要么切回终端手动敲命令，要么在对话里让 agent 一步步生成并执行命令。前者要离开当前会话，后者每步都要经过模型。dsh-git-branch-switcher 把这个流程收进输入框工具行：一个显示当前分支的胶囊按钮，点开就能切换分支、fetch 远端、新建分支并切换。下面介绍这个插件。
DSH 的理念是「一切皆插件」，这类工具属于社区插件，与 DeepSeek / 幻方没有官方从属关系，不属于官方应用商店。
这是什么¶
dsh-git-branch-switcher 是 DeepSeek Harness 的客户端插件，维护者为 milestone-17，仓库地址 https://github.com/milestone-17/dsh-git-branch-switcher 。它在会话输入框工具行左侧显示当前工作目录的 git 分支，并提供分支切换、远端同步、新建分支、勾选提交推送、合并、暂存等操作。所有 git 调用都在本地通过 subprocess.spawn 无 shell 执行，除 git fetch / git push 外不访问网络，也不上传任何数据。
插件采用 Host / Client 半包结构：Host 半包 index.js 里是 TypertRemoteService 子类 branchSwitcher，负责实际的 git 调用；Client 半包 client.js 负责 UI，挂载在 conversation.input.left slot。当前包版本为 0.5.2，许可证 MIT，运行时要求 Node.js >=22、DSH >=0.2.1-rc.2。
核心功能¶
胶囊位置。渲染在输入框工具行左侧，紧贴打字位置，不用抬头看会话头部。非 git 目录自动隐藏，游离 HEAD 显示「游离 HEAD」。样式全部使用 --dsw-alias-* 主题变量，跟随浅色 / 深色主题；输入行宽度不足时通过容器查询自动收成纯图标。
分支菜单。顶部有搜索框，本地分支与远端分支分组显示；当前分支勾选高亮，远端跟踪分支带远端名标签。切换本地分支按最近提交排序，最多 500 条；目标分支只有远端跟踪形式时自动 git switch --track 建本地跟踪分支。
远端同步。一键执行 git fetch --all --prune，完成后提示结果，失败时显示 git 原始错误。
新建分支并切换。菜单底部「＋ 新建分支」，可选源分支，为本地分支或远端跟踪分支，默认 master（回退 main，再退当前分支）。执行 git switch -c <新分支> <源分支>，会话工作目录立即切到新分支，并把源分支写入 branch.<名>.dsh-base 本地配置供后续合并推断。
勾选提交并推送。「↑ 推送」把工作区改动按带类型的行解析，可勾选其中任意一部分，填提交信息后 git add → commit → 推送；无上游时自动 push -u origin HEAD；工作区干净时一键推送已有提交。远端拒绝时不 force push。
分支合并。「⇆ 合并」为来源 / 目标双下拉，目标默认推断为该分支的拉取来源（记录源 → 上游 → merge-base → master/main）。合并成功后自动切回原来分支，返回 fast-forward / true / up-to-date 模式；冲突时列出冲突文件并可一键放弃合并。
改动暂存。「≡ 暂存」把勾选项（可含未跟踪文件）存成一条带描述的 stash；「暂存列表」逐条查看涉及文件，可恢复（保留条目）或恢复并删除，也能删单条、清空全部。
安全确认。工作区不干净时，切换、新建、合并、恢复暂存前都会弹确认；分支名做白名单校验，拒绝以 - 开头、含空白 / 控制字符、..、以 ~ ^ : 结尾等名称；推送的路径按字面量 pathspec 传递，不给注入留口子。
会话级显示。每个会话按各自的工作目录独立显示分支，胶囊按会话记忆上次状态，切回对话时零等待渲染。
安装与启用¶
README 给出四种安装方式，下面列出原文命令。
方式一，Git 源安装（推荐）：
dsh plugin --profile desktop add github:milestone-17/dsh-git-branch-switcher
等价写法：
dsh plugin --profile desktop install git+https://github.com/milestone-17/dsh-git-branch-switcher.git
国内网络可用镜像通道，内容与官方仓库一致：
dsh plugin --profile desktop install git+https://ghproxy.net/https://github.com/milestone-17/dsh-git-branch-switcher.git
dsh plugin --profile desktop install git+https://gitclone.com/github.com/milestone-17/dsh-git-branch-switcher.git
方式二，预构建包，无需 git：
dsh plugin --profile desktop add https://github.com/milestone-17/dsh-git-branch-switcher/releases/latest/download/dsh-git-branch-switcher.tgz
或钉住当前版本的 Release 包：
dsh plugin --profile desktop add https://github.com/milestone-17/dsh-git-branch-switcher/releases/download/v0.3.0/dsh-git-branch-switcher-0.3.0.tgz
方式三，市场索引。仓库自带 market-index.json（DSH 官方 format-1），部署到静态地址后在插件页「发现」里添加该 URL：
https://ghproxy.net/https://raw.githubusercontent.com/milestone-17/dsh-git-branch-switcher/master/market-index.json
方式四，本地目录安装：
dsh plugin --profile desktop install /path/to/dsh-git-branch-switcher
安装 / 更新 / 卸载后需要重启 DeepSeek Harness 应用才生效，插件图在应用启动时组装；正在运行的会话不受影响，重启后从侧栏恢复即可。若重启后仍看不到分支胶囊，先确认会话工作目录确实是 git 仓库。
典型用法¶
安装并重启后，只要当前会话的工作目录是 git 仓库，输入框工具行左侧就会出现分支胶囊。典型流程如下。
- 点开胶囊菜单，确认当前分支，搜索并切换到本地分支，或选中远端跟踪分支让其自动建本地跟踪分支。
- 点「＋ 新建分支」，选好源分支，输入新分支名后创建并切换，会话工作目录立刻落到新分支。
- 有远端改动需要同步时，点「↑ 推送」前可先在菜单里做一次远端同步。
- 切分支、拉代码前若手头有未完成的改动，用「≡ 暂存」把改动清单中需要的部分存起来。
- 需要合并时用「⇆ 合并」选来源与目标；目标分支的拉取来源已在建分支时记入本地配置，可自动推断。
上述每一步的操作对象都是当前会话的工作目录，多开会话各自显示各自的分支。
适用场景与注意¶
适合在 DSH 里直接对着一个 git 仓库做开发的用户，尤其是频繁在分支间切换、需要同步远端或把改动分批提交推送的场景。它把高频的分支动作做成了界面操作，减少了在对话里反复生成命令的开销。
使用时需要留意几点。插件以当前 DSH 进程的权限运行，能执行该进程允许的任何 git 命令，安装前应先读一遍源码并确认许可证（MIT）。它只在本地跑 git，git fetch 和 git push 会按仓库自身的 remote 配置访问网络，其余命令均为本地操作，插件不上传数据。另外，工作区不干净的写操作会先弹确认，分支名和文件路径都有校验，这属于预期行为而非故障。
小结¶
dsh-git-branch-switcher 的价值在于把 git 分支这一高频操作从终端和对话指令里挪出来，做成输入框旁的一键入口，同时保留了分支切换、远端同步、新建、勾选提交、合并、暂存这一组完整能力，并且所有操作都可追溯到本地 git。它是客户端分类下的一个开源社区插件。
想了解完整功能与接口细节，可以看目录页 https://www.skillhub.cn/plugins/milestone-17/dsh-git-branch-switcher 或仓库 https://github.com/milestone-17/dsh-git-branch-switcher 。
