dsh-ghcli

dsh-ghCLI — GitHub CLI 管理插件

1. 插件介绍

dsh-ghCLI 是面向 DeepSeek Harness（DSH）的 **gh CLI 集成插件**，提供三大能力： - **gh 安装检测与自愈**：检测 gh 是否安装、一键安装/更新、手动指定 gh 路径、一键加入 PATH，并内置 **Windows 网络代理自愈**（git 不读系统代理导致连不上 GitHub 的踩坑解决方案）。 - **多账户认证管理**：Token 登录（支持企业版 GH_HOST）、账户切换/登出/刷新、Git 全局 user.name / user.email 读写。 - **Git 仓库高频操作**：克隆、当前仓库 Push / Pull / Create PR / 打开远程页面 / Fork / 创建仓库等。 所有功能集中在 DSH **设置页**（侧边栏 → 设置 → GitHub CLI），底层直接调用本机 gh 与 git 命令，无需额外 npm 依赖。 插件为标准 DSH 插件包（npm 包形态）：host 半区（src/host.js，即 package.json main）运行在宿主进程，注册 /api/dsh-ghcli/* 路由并执行 gh/git；client 半区（src/client.js，即 exports["./client"]）以 module-loader 束加载进 Web GUI，注册 settings.section 插槽。随 profile 常驻，DSH 重启后自动加载。

2. 插件使用：dsh 安装命令

插件安装通过 dsh plugin 命令完成（该命令会把参数透传给 profile 目录内的 pnpm）。以下两种方式任选其一。

方式 A：git 安装（源码）

``powershell

1. 克隆仓库

git clone https://github.com/sweven-tears/dsh-ghCLI-manager.git

2. 安装到 web profile（<仓库路径> 替换为克隆后的本地绝对路径）

dsh plugin --profile web add D:\path\to\dsh-ghCLI-manager -w `

方式 B：npm 安装（GitHub Packages 发布包）

插件已发布到 GitHub Packages：<https://github.com/users/sweven-tears/packages/npm/dsh-ghcli>。仓库已内置 .npmrc 作用域映射，无需手写 registry： `powershell

一次性认证：用户名 = GitHub 用户名，密码 = 带 read:packages 权限的 PAT

npm login --registry=https://npm.pkg.github.com/ --scope=@sweven-tears

安装到 web profile

dsh plugin --profile web add @sweven-tears/dsh-ghcli -w `

安装要点

- **-w 必须**：web profile 目录本身是 pnpm workspace root（pnpm-workspace.yaml 的 packages: [.]），不加会报 ERR_PNPM_ADDING_TO_ROOT。 - 若报 ERR_PNPM_UNEXPECTED_STORE（store 布局版本不符），把全局 pnpm 升到 v10 再重跑。 - 若提示 "Ignored build scripts"，在 profile 目录执行 pnpm approve-builds 放行。 - 装完验证 ~/.dsh/profiles/web/package.json 出现 dsh-ghcli 依赖与 dsh.profile.bundles 条目、node_modules/dsh-ghcli 存在；然后 **重启 dsh web**（client 插件集合变更需重启生效），刷新页面后在 设置 → GitHub CLI 查看。 - 卸载：dsh plugin --profile web remove dsh-ghcli。本地 file: 依赖通常为符号链接，改 src/ 后重启 dsh web 即生效。

3. 功能介绍

| Tab | 能力 | 底层命令 | | --- | --- | --- | | 📦 状态与安装 | gh 安装徽章（✅ 已安装 v2.x / ❌ 未安装）、重新检测、一键安装/更新、GH_HOST 展示、未安装引导 Banner（自动安装 / 手动指引）、**手动指定 gh 安装路径**、**一键加入 PATH**、**git 安装路径展示**（gitBin，同款三级兜底）、**网络代理自愈**（检测系统代理并写入 git 配置 / 测试连接） | gh --version、gh config get host、winget/brew/apt、reg add HKCU\Environment\Path / ~/.bashrc、git config http.proxy | | 🔐 账户与 Git | 活跃账户头像+用户名、账户列表（切换/登出）、Token 粘贴登录（企业版 GH_HOST）、刷新 Token、Git 全局 user.name/user.email 读写 | gh auth status、gh api user、gh auth login --with-token、gh auth switch --user、gh auth logout、gh auth refresh、git config --global | | 📁 仓库管理 | 克隆（目标非空弹确认框、浅克隆）、当前工作区仓库分支/未提交数/upstream 差异、Push/Pull/Create PR/打开远程页面、远程仓库 Star/Fork/最后推送、Fork、创建仓库 | gh repo clone、gh api repos/{owner}/{repo}、gh repo fork、gh repo create、git push/pull/status/remote、gh pr create |

网络代理自愈（踩坑内建）

**背景**：git（libcurl）不读取 Windows 系统代理（WinINET），在需要代理才能出网的环境中 git push/clone 会报「直连超时 / Connection was aborted」，而浏览器、curl 等走系统代理的应用正常——表现为「git 连不上 GitHub，其他都正常」。 **插件能力**（📦 状态与安装 → 网络与代理）： - 读取当前 git 代理配置（git config http.proxy / https.proxy） - 读取 Windows 系统代理（注册表 HKCU\...\Internet Settings 的 ProxyEnable / ProxyServer） - 「自动使用系统代理」：把检测到的系统代理一键写入 git 配置（可选当前仓库或全局） - 「测试连接」：git ls-remote 实测 GitHub 连通性，失败时给出「建议配置代理」提示 - 「清除代理」：恢复直连

实现要点

- **依赖最小化**：不安装任何 npm 包（无 simple-git）。Git 操作优先 gh CLI，本地仓库操作（状态/分支/upstream 差异/Push/Pull）直接调用系统 git 作为 fallback。 - **绝对路径执行**：所有 gh / git 命令都使用解析到的**绝对路径**（gh.exe / git.exe）执行，而非依赖 PATH 中的裸命令名。解析按「进程 PATH → 注册表用户+系统 PATH（Windows）→ 常见安装目录」三级兜底，任一级命中即缓存该绝对路径（gh.status 返回 path / gitBin 供界面展示）。只有完全找不到可执行文件时才回退到 PATH 裸命令，保证命令一定能执行。 - **宿主 PATH 快照陈旧兜底**：DSH 宿主进程启动时会把 PATH 快照进自身进程环境，之后 setx 新增的环境变量不会反映到已运行的宿主进程。为绕开这一点，gh 与 git 均内置「注册表 PATH（Windows，无需重启 DSH）+ 常见安装目录」兜底，新加环境变量 / 新装 Git 无需重启即可识别。 - **零额外 Token 消耗**：绝对路径解析在插件生命周期内**只做一次**（ghBinInit / gitBinInit 三态缓存），之后所有命令直接从内存 argv 复用，**不反复探测 PATH、不启动探测子进程**。仅当用户主动点「重新检测」时才清缓存重探，成本可预期。 - **执行通道**：Host 侧使用 ctx.subprocess.spawn（显式 argv，无 shell 注入面）；所有 gh/git 调用统一走 runArgv / runGit，每个调用都记录日志。 - **超时与取消**：runArgv 默认 30s；gh repo clone / install / create / fork 等长命令 300s（5 分钟），超时后终止进程树；客户端长操作显示「取消」按钮。 - **安全**：克隆非空目录必须先确认，确认后**重命名备份**原目录再克隆，绝不强制覆盖/删除；切换账户立即生效（每次调用全新 gh 进程），无需重启 DSH。

4. gh 安装指南

> 未安装 gh 时，设置页「📦 状态与安装」会显示引导 Banner；下面三种方式任选其一，也可直接在设置页点「一键安装」。

Windows

**方式 A — winget（推荐）** `powershell winget install --id GitHub.cli -e --source winget ` **方式 B — 官方安装器** 下载 <https://cli.github.com/> 的 gh_x.x.x_windows_amd64.zip，解压后把 bin/gh.exe 所在目录加入系统 PATH，重开终端验证： `powershell gh --version `

macOS

`bash brew install gh `

Linux（Debian/Ubuntu）

`bash sudo mkdir -p -m 755 /etc/apt/keyrings wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null sudo apt update sudo apt install gh `

安装后

1. 回到设置页点「重新检测」，徽章应变为 ✅ 已安装 v2.x.x。 2. 「🔐 账户与 Git」→ 粘贴 Personal Access Token（需 repo、read:org 权限）登录；或终端执行 gh auth login 走浏览器 Device Flow。 3. 可选：gh auth setup-git 让 git push/pull 复用 gh 凭证。

5. 使用注意

- 认证 Token 只经本机 gh auth login --with-token 写入 gh 的凭证存储，不经过网络上传。 - 克隆/安装等长命令可随时点「取消」终止（进程树级终止）。 - gh repo create --source <目录> --push` 会把当前目录内容推送到新建仓库，请先确认目录内容。 - Create PR 仅当仓库存在 upstream 差异且本地领先时可用（按钮会相应置灰并提示）。 - 未安装 gh 时插件不会报错：Status / Accounts / Repo 三个 Tab 均渲染引导 Banner 而非异常。