GitHub管理器(免费版)

通过gh命令行工具管理GitHub仓库的Issue、Pull Request与工作流,聚焦"查询-检查-定位"三步流程,帮助个人开发者高效完成日常协作。

概述

GitHub已成为代码协作的事实标准,但日常操作中,开发者经常需要在浏览器与终端间切换,效率低下。gh命令行工具提供了完整的GitHub操作能力,但命令繁多、参数复杂,新手难以快速掌握。本Skill封装常用gh命令,提供场景化指引,让开发者能在终端内完成大部分GitHub操作。

免费版聚焦基础查询与检查能力,适合个人开发者日常使用。

核心能力

Issue管理

# 列出仓库Issue(结构化输出)
gh issue list --repo owner/repo --json number,title,state --jq '.[] | "#(.number): (.title) [(.state)]"'
# ...
# 查看指定Issue详情
gh issue view 123 --repo owner/repo
# ...
# 查看Issue评论
gh issue view 123 --repo owner/repo --comments

输入: 用户提供Issue管理所需的指令和必要参数。 处理: 解析Issue管理的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回Issue管理的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

Pull Request管理

# 列出仓库PR
gh pr list --repo owner/repo --state open --json number,title,author
# ...
# 查看PR详情(含diff)
gh pr view 55 --repo owner/repo
# ...
# 检查PR的CI状态
gh pr checks 55 --repo owner/repo
# ...
# 查看PR的review状态
gh pr view 55 --repo owner/repo --json reviews --jq '.reviews[] | {author: .author.login, state: .state}'

输入: 用户提供Pull Request管理所需的指令和必要参数。 处理: 解析Pull Request管理的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回Pull Request管理的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

工作流管理

# 列出最近10次工作流运行
gh run list --repo owner/repo --limit 10
# ...
# 查看指定运行详情
gh run view <run-id> --repo owner/repo
# ...
# 仅查看失败步骤的日志
gh run view <run-id> --repo owner/repo --log-failed
# ...
# 重新运行失败的工作流
gh run rerun <run-id> --repo owner/repo --failed

输入: 用户提供工作流管理所需的指令和必要参数。 处理: 解析工作流管理的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回工作流管理的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

结构化输出与过滤

大多数gh命令支持--json与--jq,便于自动化处理:

# 提取Issue编号与标题
gh issue list --repo owner/repo --json number,title --jq '.[] | "(.number): (.title)"'
# ...
# 筛选特定状态的PR
gh pr list --repo owner/repo --json number,title,state --jq '.[] | select(.state == "OPEN") | .number'
# ...
# 统计各状态Issue数量
gh issue list --repo owner/repo --json state --jq 'group_by(.state) | map({state: .[0].state, count: length})'

输入: 用户提供结构化输出与过滤所需的指令和必要参数。 处理: 解析结构化输出与过滤的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结构化输出与过滤的响应数据,包含状态码、结果和日志。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：CLI、GitHub、仓库的、与工作流、支持基础查询、状态检查与结构化、适合个人开发者日、常协作、管理器、免费版、是一款面向个人开、发者的、日常协作助手、命令行工具封装常、用操作、帮助用户高效管理、核心能力、的基础查询、工作流运行列表查、看与失败步骤定位、提供常用命令速查、与故障排查指南等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

使用场景

场景1:每日站会前的快速状态检查

用户意图: "站会快开始了,帮我看看仓库今天的PR和Issue状态。"

推荐流程:

1. gh pr list --repo owner/repo --state open --json number,title,author,updatedAt
2. gh issue list --repo owner/repo --state open --json number,title,labels --jq 'sort_by(.updatedAt) | reverse | .[0:5]'
3. gh run list --repo owner/repo --limit 5 --json status,conclusion,name

场景2:CI失败快速定位

用户意图: "CI挂了,帮我看看哪个步骤失败了。"

推荐流程:

1. gh run list --repo owner/repo --limit 1 --status failure 找到失败的运行
2. gh run view <run-id> --repo owner/repo --log-failed 查看失败日志
3. 根据日志定位问题代码,修复后push
4. gh run rerun <run-id> --repo owner/repo --failed 重跑失败步骤

场景3:代码审查前的准备

用户意图: "我要审查一个PR,先看看改了什么。"

推荐流程:

1. gh pr view 55 --repo owner/repo 查看PR描述与元信息
2. gh pr diff 55 --repo owner/repo 查看代码变更
3. gh pr checks 55 --repo owner/repo 检查CI是否通过
4. gh pr view 55 --repo owner/repo --json reviews --jq '.reviews[]' 查看已有审查意见

不适用场景

以下场景GitHub管理器(免费版)不适合处理：

• 无明确技术栈的模糊需求
• 纯架构设计决策
• 运维部署管理

触发条件

需要代码生成、编程辅助、调试测试、开发部署时使用。不适用于非本工具能力范围的需求。

快速开始

依赖详情

# 安装gh(以macOS为例,其他平台参考官方文档)
brew install gh
# ...
# 完成认证
gh auth login
# ...
# 验证认证状态
gh auth status

Step 2:基础查询

# 查看当前用户仓库列表
gh repo list --limit 10
# ...
# 查看指定仓库信息
gh repo view owner/repo
# ...
# 查看仓库Issue
gh issue list --repo owner/repo --limit 10

Step 3:结构化输出

# 使用JSON输出
gh issue list --repo owner/repo --json number,title,state
# ...
# 使用jq过滤
gh pr list --repo owner/repo --json number,title,author --jq '.[] | "\(.number)\t\(.title)\t\(.author.login)"'

示例

常用命令别名

# 配置gh别名,提升效率
gh alias set issues 'issue list --json number,title,state --jq ".[] | \"#\(.number): \(.title) [\(.state)]\""'
gh alias set prs 'pr list --json number,title,author --jq ".[] | \"#\(.number): \(.title) by \(.author.login)\""'
gh alias set ci 'run list --limit 5'
# ...
# 使用别名
gh issues --repo owner/repo
gh prs --repo owner/repo
gh ci --repo owner/repo

跨仓库批量查询脚本

#!/bin/bash
# 批量查询多个仓库的开放Issue数
repos=("owner/repo1" "owner/repo2" "owner/repo3")
for repo in "${repos[@]}"; do
  count=$(gh issue list --repo "$repo" --state open --json number --jq 'length')
  echo "$repo: $count open issues"
done

最佳实践

命令选择策略

参数规范

• 必须指定--repo: 不在git目录中时,必须用--repo owner/repo指定仓库
• 使用URL替代: 也可直接传入GitHub URL,gh会自动解析
• 限制结果数: 大仓库务必加--limit,避免输出过长
• 状态过滤: 查询时明确指定--state open/closed/all,避免混淆

JSON与jq组合技巧

# 提取多个字段并格式化
gh pr list --json number,title,author,updatedAt --jq '.[] | "#\(.number) \(.title) (by \(.author.login), \(.updatedAt[0:10]))"'
# ...
# 按字段排序后取前N
gh issue list --json number,title,createdAt --jq 'sort_by(.createdAt) | reverse | .[0:5]'
# ...
# 条件筛选
gh pr list --json number,title,labels --jq '.[] | select(.labels[].name == "bug") | .number'
# ...
# 分组统计
gh issue list --json state --jq 'group_by(.state) | map({state: .[0].state, count: length})'

常见问题

Q1: 不在git目录中如何指定仓库?

A: 使用--repo owner/repo参数指定仓库。例如: gh issue list --repo octocat/hello-world。也可在仓库目录内直接执行gh issue list,gh会自动识别当前仓库。

Q2: gh命令返回认证错误怎么办?

A: 运行gh auth status检查认证状态。如未认证,运行gh auth login按提示完成认证。如token过期,运行gh auth refresh刷新。

Q3: 如何查看私有仓库?

A: 确保认证的账号有私有仓库访问权限。gh auth login时会请求相应scope,选择包含repo的scope即可访问私有仓库。

Q4: JSON输出字段不完整怎么办?

A: 默认--json只输出部分字段。使用--json时不指定字段名会输出所有可用字段,例如gh issue view 123 --json。或显式列出需要的字段: --json number,title,body,labels,assignees。

Q5: jq过滤报错怎么办?

A: 常见原因: (1)字段名拼写错误,先用--json不带jq查看完整字段名; (2)嵌套字段访问语法错误,用.[]遍历数组,用.field访问对象; (3)jq未安装,通过brew install jq或apt install jq安装。

已知限制

本免费体验版限制以下高级功能:

• 不支持批量Issue/PR操作(如批量关闭、批量打标签)
• 不支持高级API查询(如GraphQL、复杂搜索)
• 不支持自动化工作流(如定时检查、自动分配)
• 不支持团队协作仪表盘与统计报表
• 不支持Webhook管理与事件订阅

解锁全部功能请使用专业版: github-manager-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
• 操作系统: Windows / macOS / Linux
• gh CLI: 2.0+(GitHub官方命令行工具)
• jq: 1.6+(可选,用于JSON过滤)

第三方依赖

API Key 配置

• GitHub认证: 通过gh auth login完成OAuth认证,token存储于~/.config/gh/hosts.yml
• Token权限: 根据需要选择scope(建议包含repo、workflow、read:org)
• Token轮换: 建议每180天刷新一次,运行gh auth refresh
• 禁止: 在SKILL.md或脚本中硬编码GitHub Token

可用性分类

• 分类: MD+EXEC(Markdown指令+命令行工具执行)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行gh命令

错误处理

输出格式

{
  "success": true,
  "data": {
    "result": "GitHub管理器(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "github manager"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}