前言¶
用 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 。
