87 lines
3.7 KiB
Markdown
87 lines
3.7 KiB
Markdown
---
|
||
name: github-gh-skill
|
||
description: 使用 GitHub CLI（`gh`）处理认证、仓库、Issue、Pull Request、Actions、Release，以及通过 JSON/JQ 调用 API 查询数据。适用于用户提到 `gh`、GitHub CLI、终端里的 GitHub、PR、Issue、Actions、Release，或需要不打开浏览器直接获取 GitHub 数据的场景。
|
||
---
|
||
|
||
# GitHub CLI（gh）技能
|
||
|
||
## 何时启用
|
||
|
||
用户提到：`gh`、GitHub CLI、命令行操作 GitHub、PR/Issue/Release/Actions、或需要从终端拉取 GitHub 信息时，优先按本技能执行。
|
||
|
||
## 前置检查（一次性）
|
||
|
||
1. **检查 `gh` 是否已安装**：执行 `gh --version`。
|
||
- 若命令不存在，**自动安装最新版**：根据系统包管理器执行安装（如 `apt install gh -y`、`yum install gh -y`、`brew install gh`）。
|
||
- 安装失败再**提示用户手动安装**（参考官网 <https://cli.github.com/>）。
|
||
2. 若需私有资源，执行 `gh auth status`；未登录则 `gh auth login`（非 CI 场景由用户完成交互）。
|
||
3. 需要脚本化检测时，运行跨平台脚本：`python scripts/check_gh.py`（或 `python3 ...`，仅需 Python 3.8+ 与标准库）。
|
||
|
||
## 高效原则（给 Agent）
|
||
|
||
- **优先机器可读**：能用 `--json` 就用；需要筛选时用 `--jq`（避免解析人类表格输出）。
|
||
- **减少交互**：批量操作用 `--yes` / `-y`；需要合并且非交互时用环境变量或文档中的标志位（见 [reference.md](reference.md)）。
|
||
- **先定目标再选子命令**：issue / pr / repo / workflow / release / api —— 不要猜，缺参数时 `gh <cmd> --help`。
|
||
- **API 兜底**：`gh` 子命令缺能力时用 `gh api`，路径以官方 REST 为准。
|
||
|
||
## 模块索引（按场景跳转）
|
||
|
||
| 模块 | 内容 |
|
||
|------|------|
|
||
| A. 认证与上下文 | `gh auth`，默认仓库 |
|
||
| B. 仓库 | `gh repo clone/view/create` |
|
||
| C. Issue | `gh issue list/create/view/close` |
|
||
| D. PR | `gh pr list/create/view/diff/merge/checkout` |
|
||
| E. Actions | `gh run list/view/watch/rerun` |
|
||
| F. Release | `gh release list/create` |
|
||
| G. 高级 | `gh api`，GraphQL |
|
||
|
||
**详细命令与模板**见 [reference.md](reference.md)。
|
||
|
||
## A. 认证与上下文
|
||
|
||
- 查看登录：`gh auth status`
|
||
- 设置默认仓库（减少重复 `-R`）：在仓库目录内 `gh repo set-default`
|
||
|
||
## B. 仓库
|
||
|
||
- 克隆：`gh repo clone owner/name`
|
||
- 当前仓库信息（JSON）：`gh repo view --json name,owner,url,defaultBranchRef`
|
||
|
||
## C. Issue
|
||
|
||
- 列表（JSON）：`gh issue list --json number,title,state,author,labels`
|
||
- 创建：`gh issue create --title "..." --body "..."`
|
||
|
||
## D. Pull Request
|
||
|
||
- 列表：`gh pr list --json number,title,state,headRefName`
|
||
- 检出本地分支：`gh pr checkout <number>`
|
||
- 查看差异：`gh pr diff <number>`
|
||
|
||
## E. GitHub Actions（workflow / run）
|
||
|
||
- 运行列表：`gh run list --limit 20`
|
||
- 单次运行详情 + 日志：`gh run view <run-id> --log`
|
||
|
||
## F. Release 与标签
|
||
|
||
- 列表：`gh release list --limit 20`
|
||
- 创建（需明确 tag 与说明）：`gh release create <tag> --notes "..."`
|
||
|
||
## G. `gh api`（REST）
|
||
|
||
- GET 示例：`gh api repos/{owner}/{repo}/issues --jq '.[0].title'`
|
||
- 占位符：`{owner}` `{repo}` 在已关联 git remote 时常可自动解析；不确定时显式传 `-R owner/repo`。
|
||
|
||
## 错误处理
|
||
|
||
- **401/403**：检查 `gh auth status`、token 权限（repo、workflow 等）。
|
||
- **未找到命令**：升级 `gh` 或改用 `gh api`。
|
||
- **交互阻塞**：CI/自动化中避免会打开编辑器的命令；为 `pr merge` 等加 `--merge`/`--squash`/`--rebase` 等非交互选项。
|
||
|
||
## 附加资源
|
||
|
||
- 完整命令表与 JSON 字段提示：[reference.md](reference.md)
|
||
- 环境检查脚本（模块化，中文注释；跨平台，仅标准库）：[scripts/check_gh.py](scripts/check_gh.py)
|