001.gh CLI（Github CLI）

GitHub CLI 是一个命令行工具，用于在终端中直接与 GitHub 交互。适合让 LLM 通过命令行查阅和阅读仓库内容，节省 MCP Token 消耗

• 官方文档
• 中文文档
• API 文档
• Github Releases

安装

# Windows (使用 winget 或 scoop)
# 或者 Github Releases 下载
winget install --id GitHub.cli
# 或
scoop install gh
 
# macOS
brew install gh
 
# Linux
# 参考：https://github.com/cli/cli/blob/trunk/docs/install_linux.md#debian
(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
    && sudo mkdir -p -m 755 /etc/apt/keyrings \
    && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
    && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
    && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
    && sudo mkdir -p -m 755 /etc/apt/sources.list.d \
    && 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 -y

身份验证：

gh auth login              # 交互式登录
gh auth status             # 查看认证状态
gh auth refresh            # 刷新 token

仓库信息

# 建议优先使用 JSON 输出，避免 README 导致输出过长
gh repo view {owner}/{repo} --json name,description,primaryLanguage,stargazerCount,url

文件内容（最常用）

# 读取文件内容（需解码）
gh api "repos/{owner}/{repo}/contents/{path/to/file}" --jq '.content' | base64 -d
 
# 读取 README
gh api "repos/{owner}/{repo}/readme" --jq '.content' | base64 -d
 
# 列出目录（仅显示名称，节省 Token）
gh api "repos/{owner}/{repo}/contents/{path}" --jq '.[].name'

分支和提交

# 列出所有分支名称
gh api "repos/{owner}/{repo}/branches" --jq '.[].name'
 
# 获取最近 3 条提交记录（格式化输出）
gh api "repos/{owner}/{repo}/commits?per_page=3" --jq '.[] | {sha: .sha[0:7], message: .commit.message, author: .commit.author.name}'

Issue 和 PR

# 列表显示（带限制）
gh issue list --repo {owner}/{repo} --limit 5
gh pr list --repo {owner}/{repo} --limit 5
 
# 搜索特定关键词的 Issue
gh issue list --repo {owner}/{repo} --search "{keyword}" --limit 5
 
# 获取 PR 详情（JSON）
gh api "repos/{owner}/{repo}/pulls/{number}" --jq '{title, body, state, html_url}'

通用 API

gh api {endpoint} --jq '.field'              # 任意 API + jq 过滤
gh api -X POST {endpoint} -f key=value       # POST 请求

使用场景

1. 快速查阅仓库结构：先用 gh repo view --json ... 了解概况，再用 gh api .../contents --jq '.[].name' 浏览根目录
2. 深度查看代码：定位文件后，使用 gh api .../contents/path --jq '.content' | base64 -d 读取
3. 排查历史：使用 gh api .../commits?per_page=5 查看最近变更