GitHub CLI 安装器 muelabyte/control-github

一条命令搞定 DSH 的 GitHub CLI

面向 Windows 的单次运行安装器，装完就能在 DeepSeek Harness（DSH）和其他智能体里直接用 GitHub CLI（gh）：

- 安装 gh 便携版（不需要管理员权限，不用 MSI），
- 对照官方 release 校验 SHA256，
- 写进用户 PATH，
- 在 ~/.dsh/AGENTS.md 里配置 GitHub 区块，
- 引导网页登录，并说明 8 位验证码从哪来。

非官方项目。与 GitHub、DeepSeek 均无关联。

快速开始

一行命令（PowerShell 7）

irm https://raw.githubusercontent.com/muelabyte/control-github/v1.0.0/scripts/install-gh.ps1 | iex

只做诊断，不安装任何东西：

& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/muelabyte/control-github/v1.0.0/scripts/install-gh.ps1'))) -Check

本地副本（不执行远程代码）

git clone https://github.com/muelabyte/control-github.git
cd control-github
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-gh.ps1

从 release 安装

irm https://github.com/muelabyte/control-github/releases/download/v1.0.0/install-gh.ps1 | iex

环境要求

| 要求 | 说明 |
| Windows | 10 或 11 |
| PowerShell | 7（pwsh）。用 Windows PowerShell 5.1 时脚本会直接停下，避免把 AGENTS.md 里的重音字符弄乱 |
| 权限 | 普通用户即可，不需要管理员 |
| 网络 | 能访问 github.com 和 api.github.com |

没装 PowerShell 7：

winget install --id Microsoft.PowerShell -e

8 位验证码

验证码不来自 GitHub，也不来自你的账号：它由 gh 在你本机发起登录时生成。

1. 终端里会显示 First copy your one-time code: XXXX-XXXX（8 个字符，中间一个连字符）。
2. 通常会自动复制到剪贴板。
3. 打开 <https://github.com/login/device> 粘贴，然后授权。
4. 不是验证器里的 2FA 验证码。
5. 没看到就按 Ctrl+C，重跑命令会生成新的。有效期约 15 分钟。

安装器在启动登录流程前会打印这段说明；加上 -Login 还会显示验证码和 URL。

具体做了什么

1. 检查 %USERPROFILE%\.local\bin\gh.exe 里是否已有 gh。
2. 没有就下载 cli/cli 的官方 release，并校验 SHA256。
3. 解出 gh.exe，复制到用户目录。
4. 检查 PATH（缺了就加到用户 PATH）。
5. 读取或创建 %USERPROFILE%\.dsh\AGENTS.md，更新其中的受管区块，写入路径、版本和实际登录状态。
6. 没有会话就说明怎么登录；加 -Login 则直接启动。
7. 校验并给出下一条测试命令。
托管区块带有标记（dsh-github-cli:begin / end），并且是幂等的：可以多次执行，不会重复写入内容。如果已经存在手写的 GitHub 章节，会把它迁移到区块里，而不是重复一份。

选项

| 选项 | 作用 |
| -Check | 只做诊断：不下载、不写入、不改动任何东西 |
| -Login | 安装完成后启动 gh auth login --web 并显示验证码 |
| -Version <x.y.z> | 安装指定版本；latest 表示最新稳定版 |
| -Force | 即使版本一致也重新安装 |
| -NoPathUpdate | 不把文件夹加入用户 PATH |
| -UpdateInstructionsOnly | 不安装，只更新 AGENTS.md |
| -Uninstall | 删除 gh.exe 和 AGENTS.md 里的托管区块 |

示例

Diagnóstico
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-gh.ps1 -Check

Instalar (o dejar todo listo si ya está)
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-gh.ps1

Instalar y lanzar el login web
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-gh.ps1 -Login

Forzar la última estable
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-gh.ps1 -Version latest -Force

Tras autenticar, fijar el login en AGENTS.md
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-gh.ps1 -UpdateInstructionsOnly

Desinstalar (no cierra la sesión de GitHub)
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-gh.ps1 -Uninstall

手动验证：

gh --version
gh auth status
gh api user --jq .login
gh repo list --limit 5 --json name,visibility

如何与 DSH 集成

DSH 会在所有会话的第一次请求时加载 $DSH_HOME/AGENTS.md，与工作目录无关。安装脚本写入的区块会说明：

- 任何 GitHub 查询都用 gh，
- 回答前先检查 gh --version 和 gh auth status，
- 常用命令参考，
- 边界：默认只读，不把 token 写进文件，不使用 delete_repo。

效果：新会话无需额外配置，就能回答「列出我的公开仓库」。

安全

- 不把 token 写进文件。 凭据由 gh 保存在 Windows 凭据管理器中。
- 没有 delete_repo。 浏览器登录授予 repo、read:org、gist 和 workflow，不授予 delete_repo。正是这个缺失挡住了通过 API 删除仓库的操作。不要用 gh auth refresh 把它加上。
- 默认只读。 AGENTS.md 的区块禁止在没有明确请求时创建、删除或修改配置。
- 一行命令会执行远程代码。 所以它指向不可变的 tag，而不是 main，并且 release 会公布 SHA256。如果你想先审一遍：下载 .ps1，读一遍，再用 -File 执行。
- 分支与 force-push。 repo scope 确实允许写分支。要保护分支，请在 GitHub 上启用 branch protection 或 rulesets。

故障排查

| 症状 | 解决办法 |
| gh: no se reconoce | 打开新终端；脚本会把文件夹加入 PATH。如果不行，就用 C:\Users\<usuario>\.local\bin\gh.exe。 |
| You are not logged into any GitHub hosts | 执行 gh auth login --hostname github.com --git-protocol https --web。 |
| 看不到 8 位验证码 | 它在终端里；按 Ctrl+C，重来一次，会出现新的验证码。 |
| 不显示私有仓库 | gh auth refresh -s repo,read:org。 |
| 403/429 错误 | 请求频率限制（认证后 5.000/h）：把查询间隔拉开。 |
| necesita PowerShell 7 | 用 pwsh；用 winget install --id Microsoft.PowerShell -e 安装。 |
| 被 ExecutionPolicy 拦截 | 在命令后加 -ExecutionPolicy Bypass。 |
| AGENTS.md 不生效 | 检查 %USERPROFILE%\.dsh\AGENTS.md，并打开新会话。 |
| one-liner 不工作 | 仓库必须是公开的，tag 必须存在。改用本地副本。 |

结构

.
├── scripts/
│ └── install-gh.ps1 # Instalador de una sola ejecución
├── ANALISIS-ACCESO-GITHUB-AGENTES.md # Análisis de alternativas y decisión
├── PLAN-ACCESO-GITHUB-DSH.md # Plan original de implementación
├── SECURITY.md # Política de seguridad
├── LICENSE # MIT
└── .github/workflows/validate.yml # CI: sintaxis y smoke test

为什么这样设计

完整分析见 ANALISIS-ACCESO-GITHUB-AGENTES.md。简而言之：

- 用单个脚本而不是技能： 安装只发生一次；技能会多出发现和加载环节，没有收益。
- 用 gh 而不是 MCP 或插件： 不需要 Node、Docker、服务器，也不需要在文件里放 token，任何能执行 shell 的智能体都能用。
- MCP/插件 留作后续演进，等需要原生工具或硬性只读时再上。

许可证

MIT © 2026 muelabyte