前言¶
在 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
