前言¶
DeepSeek Harness (DSH) 的核心設計理念是“一切皆插件”。在智能體開發與調試過程中，頻繁查看 Git 提交歷史、定位具體變更以及安全切換分支是常見操作。dsh-git-chain 插件旨在解決這些問題，它將倉庫歷史以 SVG 泳道圖的形式呈現，並提供在側邊欄工作流中直接查看詳情、Diff 和受保護的分支切換能力。
插件定位¶
dsh-git-chain 是一款面向 DSH 的客戶端插件，由 ShinonomeAya 維護。它不直接操作 Git 底層，而是作爲 DSH Web GUI 和 DSH Host 之間的橋樑：前端負責渲染 SVG 可視化與交互，後端通過 ctx.subprocess 調用 Git CLI 來執行具體的圖生成、Diff 和分支操作。
核心功能¶
歷史視圖與過濾¶
插件提供 SVG 泳道拓撲圖，展示提交節點、Merge 匯入線和分支出線。
- First-parent 主線視圖：專注於當前 HEAD 的第一父鏈，同時保留 Merge 元數據。
- 範圍過濾：支持查看全部 refs、當前分支、指定本地分支。
- 即時過濾：在已加載的歷史窗口內，可按主題、作者、引用或 Commit OID 進行篩選。
- 佈局策略：採用最小泳道策略，配合固定行高和虛擬滾動，適合較長的提交列表。
提交詳情與 Diff¶
- 點擊提交節點可查看作者、提交者、時間、父提交及變更文件。
- 提供文件狀態徽標和增刪行數統計。
- 懶加載 unified Diff，單次輸出上限爲 1 MB，防止大變更佔滿界面。
分支切換與保護¶
- 受保護切換：切換分支前，系統會自動檢查衝突、進行中的 Git 操作、其他 worktree 以及可能被覆蓋的文件。
- 安全機制：使用
git switch --no-guess避免隱式創建或猜測遠端分支；分支名和 commit OID 在命令執行前經過白名單校驗，使用 argv 而非拼接 shell 字符串。 - Fallback 機制：優先顯示在
dsh-better-sidebar中；若無該基座，則回退爲輸入欄芯片和浮動面板。
安裝與啓用¶
安裝前請確保環境滿足以下要求：
- DSH 版本 >= 0.1.1-rc.1
- Node.js 版本 >= 22.19.0
- Git 已加入系統 PATH
- 克隆倉庫：
git clone https://github.com/ShinonomeAya/dsh-git-chain.git
cd dsh-git-chain
- 安裝依賴並構建：
pnpm install
pnpm run build
- 添加插件到 DSH Desktop profile：
dsh plugin --profile desktop add link:/absolute/path/to/dsh-git-chain
- 重新啓動 DSH，在側邊欄中找到 Git 鏈路圖 標籤頁。
如需卸載：
dsh plugin --profile desktop remove dsh-git-chain
典型用法¶
- 查看提交詳情：點擊提交節點，側邊欄會展開顯示作者信息、父提交記錄以及變更文件列表。
- 瀏覽主線：在視圖選擇中啓用 first-parent，聚焦當前分支的主線歷史，便於梳理邏輯流。
- 安全切換：點擊分支列表中的分支名，系統會進行安全檢查（如是否有未提交的更改或衝突），確認無誤後切換。
- 篩選歷史：在已加載的歷史窗口內，輸入關鍵詞即可快速過濾出特定作者或主題的提交。
適用場景與注意事項¶
該插件適合需要頻繁在 DSH 中進行代碼審查、歷史回溯或分支管理的開發者。
需要注意以下已知限制：
- 過濾範圍：文本過濾目前僅作用於已加載窗口；全歷史的 subject、author 或文件級服務端搜索仍在路線圖中。
- 佈局限制：圖佈局採用最小泳道策略，少數複雜的菱形 merge 節點可能輕微重疊。
- 視覺截斷：虛擬滾動窗口上下緣會對泳道進行截斷，但通過 overscan 減少視覺跳變。
- Diff 大小：單次完整 Diff 輸出上限爲 1 MB。
此外，插件運行於 DSH 進程權限下，Git 路由只接受已註冊的 workspace，默認只接受 loopback 請求，安全性由 Host 層把控。
結語¶
dsh-git-chain 通過可視化的方式重構了 Git 歷史的查看體驗，同時將分支切換的安全檢查納入工作流。對於使用 DSH 進行智能體開發或代碼管理的用戶，它是一個能夠直接提升調試效率的工具。
