DeepSeek Harness 插件：dsh-git-status（實時 Git 狀態 + 分支切換）

前言¶

DeepSeek Harness (DSH) 的理念是“一切皆插件”。在會話開發過程中，頻繁查看分支狀態、ahead/behind 數值以及切換分支通常需要手動執行 Git 命令。dsh-git-status 插件通過官方 slot 將 Git 狀態集成到會話視圖中，在會話頭徽標和輸入區環境行展示實時狀態，並提供分支切換功能，減少切換上下文的成本。

安裝與啓用¶

安裝該插件需使用官方包管理命令，指定版本 v0.1.0。

dsh plugin --profile web add github:shenhuanageshei/dsh-git-status#v0.1.0

安裝後，插件會自動掛載至會話視圖的特定槽位。對於非 git 會話，兩處展示會自動隱藏。

核心功能¶

該插件主要提供以下能力：

實時狀態展示：在會話頭徽標和輸入區環境行展示當前工作目錄的 git 狀態，包括分支名稱、ahead/behind 數值、髒區計數、worktree 狀態、HEAD 提交信息以及相對時間。
分支切換與新建：點擊會話頭徽標彈出分支菜單，支持搜索、切換分支、新建分支。新建分支支持遠程 DWIM（Do What I Mean）跟蹤分支邏輯。
安全模型：寫操作僅使用 git switch（絕無 --force），通過 ref 白名單、spawn 參數數組無 shell 模式以及 check-ref-format 校驗新建名來保證安全。當工作區有未提交變更時，插件會拒絕可能導致數據丟失的切換操作。
智能交互：支持 per-cwd 互斥鎖串行切換，agent 運行中切換需二次確認。讀命令帶有 --no-optional-locks 參數，避免與 agent 的 git 操作搶索引鎖。

界面與交互¶

插件在界面設計上分爲兩個主要區域：

會話頭徽標：格式爲 ⎇ 分支名 ▾。
- 點擊後彈出分支菜單，支持搜索和操作。
- 當工作區有未提交變更時，徽標顯示琥珀色圓點提示。
- 當處於 detached HEAD 狀態時，顯示爲 ⎇ @短sha。
- 當存在 linked worktree 時，顯示 ⧉ 標記。
輸入區環境行：位於輸入卡下方，與官方統計行同槽位但爲 ambient 讀出行。
- 示例格式：⎇ main ↑2↓1 · +3 ~2 ?1 · ⧉ wt:feature-x · 0a1b2c3 10m前。
- 分段配色（⎇ 品牌藍、分支名 primary、髒區琥珀、worktree 紫、HEAD 弱灰），字體大小 13px，段距 14px，具有呼吸感。
- 懸停可顯示 cwd / 主倉 / HEAD / upstream / worktree 列表。

安全模型¶

插件的寫操作遵循嚴格的安全約束：

拒絕 Force：僅使用 git switch，不使用 --force。髒區有丟失風險時，由 git 自身拒絕並回顯錯誤原文。
Ref 校驗：新建分支名需通過 check-ref-format 校驗，切換目標爲已枚舉的 ref 白名單。
併發控制：使用 per-cwd 互斥鎖串行切換，成功切換後失效緩存。
鎖競爭：讀命令帶 --no-optional-locks，避免與 agent 的 git 操作爭搶索引鎖。

架構¶

插件採用“Node half + Client half”的零構建架構：

Node half（lib/index.mjs）：提供 HTTP API 路由，包括 GET /status（TTL 1.5s 輪詢緩存）、GET /branches（TTL 5s）和 POST /switch。會話上下文通過 ctx.sessions.get(id).header.cwd 獲取。
Client half（lib/client.js）：通過 ctx.slots.inject 掛載至官方槽位。客戶端負責 UI 渲染，輪詢策略爲 2s 起步，慢倉自適應退避至 8s，頁面隱藏時暫停輪詢。
零構建：Client 端手寫 CJS，使用 __ModuleLoader__ 包裝，與 task-status 編譯產物同構，改完即生效。

開發¶

若需本地調試或修改插件：

注入：運行時生效，無需重啓。

    dev_inject_plugin <本倉庫克隆目錄>

重載：修改 Node half 後執行，Client half 需刷新頁面。

    dev_reload_package dsh-git-status

卸載：

    dev_uninject_plugin dsh-git-status

注意事項¶

該插件以當前 DSH 進程的權限運行。安裝前應檢查源碼與許可證（MIT）。該插件由社區開發者維護，與 DeepSeek 或官方應用商店無從屬關係。

總結¶

dsh-git-status 通過將 Git 狀態和操作直接嵌入 DSH 會話界面，實現了從“外部命令行”到“界面內集成”的轉變。其零構建的架構和嚴格的安全模型使其適合在開發流程中直接使用。