前言¶
在 DSH 裏讓 agent 處理倉庫時，常見做法是讓模型連續調用宿主 shell，自己拼 git status、git diff、gh pr view 等命令，再從一大段終端輸出裏解析狀態。步驟多、格式不穩定，也容易在破壞性操作（force push、刪分支、合併 PR）上缺少明確的確認邊界。
dsh-repo-ops（維護者 Joker2377）把 git 與 GitHub CLI 的常用操作收成九個 DSH 工具，一次調用返回結構化、面向模型的緊湊文字。插件歸類爲「聯網工具」，倉庫與說明見 GitHub、SkillHub 目錄頁。
下面介紹它是什麼、提供哪些能力、如何安裝與典型調用方式，以及使用時的前提與限制。
這是什麼¶
一句話定位：把 git 與 gh 的日常工作包成九個結構化工具，覆蓋 status、diff、commit、push、分支、PR、CI、issue、release。
依賴本機已安裝 git（README 實測 2.51.0）與 gh（README 實測 2.92.0，且已完成 gh auth login）。不負責設備登錄流程；GitHub 相關能力在未登錄時會表現爲 gh 的 401/403，需在宿主機自行處理憑據。
插件以當前 DSH 進程的權限調用本機 git/gh，安裝與啓用前宜自行覈對源碼與 MIT 許可證。
核心功能：九個工具¶
README 用一張表歸納讀寫性質與職責，設計上是「一個工具一類工作」，每個工具有自己的 action，而不是爲每個 git 子命令單獨註冊一個工具。
| 工具 | 做什麼 | 讀寫 |
|---|---|---|
repo_status |
branch、HEAD、ahead/behind、未提交文件、默認分支，以及當前分支上的 PR 與 CI 摘要 | 唯讀 |
repo_diff |
改了哪些文件（+/-）、diff 原文、commit 列表、單個 commit 內容 | 唯讀 |
repo_commit |
stage 指定文件並 commit，支持 amend 與 undo（soft reset） | 寫入 |
repo_push |
推分支，返回推前/推後 sha 與遠端響應（含 GitHub 給出的 PR URL） | 寫入 |
repo_branch |
分支列表與各分支 ahead/behind、開/切/刪、fetch、pull、與 base 同步 | 寫入 |
repo_pr |
PR 的 status / list / view / create / update / comment / reply / diff / checkout / ready / merge | 混合 |
repo_ci |
GitHub Actions 的 status / list / view / logs / watch / rerun / workflow | 混合 |
repo_issue |
issue 的 list / view / create / comment / close / reopen | 混合 |
repo_release |
release 與 tag 的 list / view / create / edit / delete / tags | 混合 |
三個設計取向會直接體現在調用體驗上：
- 破壞性動作需要
confirm:true。例如裸--force推送、刪未合併分支、合併 PR、重跑 workflow、觸發workflow_dispatch、刪 release：當confirm不爲 true 時，只返回「將要執行」的那一行，不實際執行，避免工具靜默改動遠端。 - 不提供
--no-verify。pre-commit 與 pre-push hook 照常執行。 - 失敗以可讀字符串返回，不拋異常，便於模型看到原因與下一步建議。
安裝與啓用¶
環境¶
- 本機安裝
git與gh，並完成gh auth login（token 需具備reposcope，見 README 疑難排解）。 - DSH / Node 版本需滿足
package.json：node>= 22.19，dsh>= 0.1.1-rc.2 且 < 0.3.0-0。
安裝插件¶
安裝方式是把 倉庫首頁 交給 plugin_manager（不是 tarball URL），裝完後重載 profile：
github:Joker2377/dsh-repo-ops
倉庫首頁：https://github.com/Joker2377/dsh-repo-ops。也可直接指定 release 中的 tarball。
掛載配置¶
在 cordis.patch.yml 中手動掛載：
- insert:
- id: repo-ops
name: dsh-repo-ops
config: {}
config 使用 cordis standard-schema（lib/index.js 的 Config），鍵名或類型錯誤會返回可讀的 issues，而不是靜默忽略：
| 鍵 | 默認 | 意義 |
|---|---|---|
ghPath |
空字符串 | gh 不在 PATH 時的絕對路徑 |
gitPath |
空字符串 | git 不在 PATH 時的絕對路徑 |
timeoutMs |
60000 | 單條命令最長執行時間 |
watchTimeoutMs |
300000 | repo_ci 的 watch 默認等待上限 |
readOnly |
false | 爲 true 時拒絕所有寫入類 action，僅允許查詢 |
若曾安裝 0.1.1 並在 profile 加載階段報錯（Cannot read properties of undefined (reading 'validate')），README 建議先用 plugin_manager 移除再重裝 0.1.2 及以上；該版本起 Config 爲真正的 standard-schema。
典型用法¶
工具面向 agent。README 給出的一輪常見序列如下（示意輸出已壓縮）：
repo_status() -> branch=feat/login，+2/-0，3 個未提交文件，PR #41 open，checks: 1 FAIL
repo_diff(action=files) -> lib/auth.ts +12 -3 …
repo_commit(paths=["lib/auth.ts"], message="fix: reject empty token")
repo_push() -> 8f2a1c9 -> 41b7d02，遠端響應裏帶着 PR #41 的 URL
repo_ci(action=watch, runId=12345) -> completed / failure（等了 74s）
repo_ci(action=logs, runId=12345) -> 失敗 job 的 log 尾端 200 行
repo_pr(action=view) -> 含未結的 review 線程，回覆用的 commentId 在返回中
幾條參數語義需要記住：
path：倉庫內任意目錄的絕對路徑，會自動上溯到 repo 根；省略時使用當前 session 的工作目錄（exec.agent.session.header.cwd，不是 host 進程的cwd）。repo：owner/name或完整 GitHub URL，傳給 gh 的--repo；省略時由本機 git remote 推斷。confirm:true：僅對破壞性 action 有意義，表示已與用戶確認，不是「先試跑」。- 多行
message/body作爲單一參數傳給 CLI，不經 shell，引號與換行不會被錯誤展開。
分支尚無 upstream 時，ahead/behind 可能爲 null；首次推送可用 repo_push(setUpstream:true)。
適用場景與注意¶
適合誰
- 在 DSH 裏讓 agent 閉環完成「看狀態 → 看 diff → 提交 → 推送 → 盯 CI → 回 PR 評論」的 GitHub 工作流，且希望少拼 shell、少解析原始終端輸出。
- 需要只讀審計模式時，可將
readOnly: true打開，阻止一切寫入類 action。
前提與限制（摘自 README「已知限制」）
- 必須本機有
git與gh；無 libgit2、無內置 REST 備援。 - 僅 GitHub（PR/CI 面）；git porcelain 側與託管無關，但 GitLab/Gitea 的 PR 與 Actions 不支持。
- 不處理 git-lfs、submodule、worktree 創建；不做交互式 rebase；一次調用只針對一個 repo。
- 輸出是給模型讀的緊湊文字，不是彩色可視化報表。
安全與運維
- 插件繼承 DSH 進程權限執行本機二進制；
readOnly與confirm是刻意的安全閥，不能替代你對倉庫策略與 token scope 的管理。 - DSH 社區目錄（如 SkillHub）爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；本文以插件倉庫 README 與
package.json爲準。
結尾¶
dsh-repo-ops 用九個工具把 git 本地狀態與 GitHub 上的 PR、CI、issue、release 收口到同一套結構化調用裏，並用 confirm 與 readOnly 約束破壞性寫入。若你的 agent 經常要在一次會話裏串起倉庫操作，可先在本機滿足 git/gh 前提後，通過 plugin_manager 安裝 github:Joker2377/dsh-repo-ops，再在 profile 中按文檔掛載並重載。
- 目錄頁：https://www.skillhub.cn/plugins/Joker2377/dsh-repo-ops
- 源碼與完整說明：https://github.com/Joker2377/dsh-repo-ops
