前言¶

在 DSH（DeepSeek Harness）裏讓 Agent 讀分支、看 diff、甚至改工作區，常見做法是自己在會話裏貼命令輸出，或把令牌寫進環境變量——前者信息零散，後者權限邊界難控。社區插件 @zjj/dsh-git-panel（倉庫 zjj1769404838/dsh-git-panel）把賬號接入、範圍閘門、圖形化工作臺和 8 個 git_* Agent 工具收進同一套插件：配置集中在 DSH 設置頁的 Git 分節，輸入框下方用 opencode 風格的分支 chip 作唯一入口。下面介紹它解決什麼問題、怎麼裝、以及使用前必須配好的授權範圍。

這是什麼¶

@zjj/dsh-git-panel 是 DSH 桌面端插件（npm 包名 @zjj/dsh-git-panel，當前資料中版本 0.1.0，MIT 許可證），維護者爲 zjj1769404838。定位是：Git 賬號接入 + 受控倉庫操作——OAuth 設備碼或個人訪問令牌（PAT）連接 GitHub / GitLab / Gitea，令牌 AES-256-GCM 落盤且界面與接口不回顯明文；本地 git 與平臺 REST 走統一閘門（allowedRoots、allowedRepos、賬號級 full / read / none）；同時提供 Git 工作臺 UI 與 Agent 可調工具。

DSH 生態是「一切皆插件」；插件目錄頁在 skillhub.cn，與 DeepSeek / 幻方無官方從屬關係，本文僅依據倉庫 README 與 package.json 說明能力。

核心功能¶

界面入口與 Git 工作臺¶

• 設置頁：宿主左側導航新增 Git 分節（settings.section，order: 20），含賬號、倉庫範圍、寫開關、界面偏好等。
• 輸入區 chip：會話輸入框下方左側顯示分支狀態（如 ⎇ main ↑2 3*）；非 Git 目錄時灰化 Git 入口；點擊彈出分組菜單（未初始化 → 初始化嚮導；已初始化 → 工作臺 / 刷新 / 分支詳情 / 打開目錄 / Git 設置）。狀態不在後臺輪詢，僅在 cwd 變化、窗口獲焦、頁面可見、打開菜單等時機刷新。
• Git 工作臺：居中模態，頂部頁簽爲改動 / 歷史 / 文件 / 標籤 / 貯藏；改動頁雙欄（左列表 + 右就地 diff）；歷史支持關鍵詞搜索與泳道拓撲；差異模塊支持行號、四種佈局、詞級高亮、Prism 語法高亮等。
• 初始化：未初始化目錄可走單頁表單 + 右側執行計劃，支持選已有遠程、新建遠程倉庫或手工 owner/repo，執行端爲 POST /repo/bootstrap（本地操作，不自動 push）。

賬號與權限¶

• 接入方式：OAuth 設備碼（需自備各平臺 OAuth App Client ID）或 PAT。
• 賬號 → 倉庫：每個賬號卡片內聯平臺側全部遠程倉庫；每行三檔 完整 / 只讀 / 無權限，點選即 POST /repo/permission 提交。
• 全局範圍（必須配置，否則 Agent 拒絕一切操作）：
• allowedRepos：每行 owner/repo，* 表示不限遠程倉庫白名單。
• allowedRoots：本機絕對路徑白名單，* 表示不限制目錄。
• allowWrite：默認關閉；開啓後仍默認 requireConfirm 二次確認。
• 遠端寫操作：fetch / pull / push / remotes-add 等按 remote 的 owner/repo 校驗賬號是否爲 full，否則 403。

Agent 工具（8 個）¶

約束要點：未授權路徑不泄露「是否爲 git 倉庫」；git_write 在 requireConfirm 開啓時先返回 pending 與 confirmToken，確認前狀態不變；執行走 execFile('git', args)，拒絕危險參數注入。README 註明寫操作白名單不含 push / reset --hard / clean -fdx，需人工處理時可自行在終端操作。

憑據與數據路徑¶

安裝與啓用¶

從 Git 源安裝（倉庫已含 lib/ 構建產物）：

dsh plugin --profile desktop add github:zjj1769404838/dsh-git-panel

本地開發時先構建再以 link 安裝：

npm install --include=dev
node scripts/build.mjs
dsh plugin --profile desktop add link:/absolute/path/to/dsh-git-panel

裝完後重啓 DSH 桌面端（node 側路由與工具在啓動時加載）；若只改 client 模塊，在 GUI 中 Ctrl+Shift+R 硬刷新即可。

卸載：

dsh plugin --profile desktop remove @zjj/dsh-git-panel

典型用法¶

1. 連接賬號¶

打開 設置 → Git → 賬號，點「連接賬號」：

• OAuth（本機有人點瀏覽器）：選平臺 → 接入方式 OAuth → 填寫 Client ID → 連接；GitHub 走設備碼流程，瀏覽器輸入 8 位代碼後輪詢換令牌。
• PAT（CI / 最小權限）：接入方式選 PAT → 粘貼令牌 → 連接；可在平臺側限制 scope 或 fine-grained 倉庫範圍。

多賬號時可指定默認賬號，Agent 側優先使用。

2. 配置倉庫範圍（必做）¶

在 設置 → Git → 倉庫範圍 填寫：

• 允許的遠程倉庫（例：myorg/my-app，或一行 *）。
• 允許的本機目錄（例：/home/you/projects/my-app 的絕對路徑）。
• 按需開啓「允許寫操作」；建議保持「寫操作需要二次確認」爲開啓。

範圍爲空時策略爲 fail-closed（全部拒絕）。路徑按段匹配，D:\repo-evil 不會命中 D:\repo。

3. 從 chip 進入日常工作流¶

在已授權且已初始化的項目會話中：

1. 看輸入框下 chip 的分支與 dirty 狀態。
2. 點 chip → Git 工作臺，在「改動」頁暫存、寫提交信息（可用「AI 生成」，依賴宿主 ctx.llm）、提交；右欄查看 diff。
3. 需要 push 且無上游時，界面會提示「發佈分支」（git push -u），仍受寫開關與遠端 full 權限約束。

未初始化目錄：菜單選 初始化 Git 項目，左側選賬號與遠程，右側看計劃清單後提交；目錄須已通過 allowedRoots 授權。

4. Agent 側受控寫入¶

在開啓 allowWrite 且 Agent 被允許調用插件工具的前提下，寫操作典型路徑爲：

1. Agent 調用 git_write（例如 add + commit）。
2. 若 requireConfirm 爲真，得到 summary 與 confirmToken，用戶或 Agent 再調 git_confirm 才真正執行。

未配置授權範圍或寫開關關閉時，工具與 HTTP 寫端點會直接拒絕。

適用場景與注意¶

適合：在 DSH 桌面端統一管 GitHub/GitLab/Gitea 賬號；希望 Agent 只讀查狀態、diff、log，或在明確閘門與二次確認下做有限寫操作；需要內置工作臺而不反覆切終端。

注意：

• 插件以當前 DSH 進程權限運行，安裝前請自行審閱 源碼與 LICENSE，勿把超出需要的 PAT 或過寬的 allowedRoots（如整盤 *）交給生產環境。
• OAuth 需自備 Client ID；插件不分發 Client Secret，也不做 OAuth 回調服務器。
• node 半邊改動需重啓 DSH；client 改動硬刷新即可。
• git_remote_info 受平臺 API 限流影響，限流時返回 429 提示。

結尾¶

@zjj/dsh-git-panel 把 Git 賬號、目錄與遠程倉庫三道閘門、圖形工作臺和 Agent 工具放在同一插件裏，默認偏安全（不寫盤、不泄露未授權路徑、寫操作可確認）。若要在目錄裏試用，可從社區頁瞭解收錄信息：https://www.skillhub.cn/plugins/zjj1769404838/dsh-git-panel；安裝與細節以 GitHub 倉庫爲準：https://github.com/zjj1769404838/dsh-git-panel。