Github Manager Free

通过gh命令行工具查询和管理GitHub仓库的Issue、Pull Request及工作流，支持状态检查和结构化输出，适合个人开发者日常协作。

GitHub管理器(免费版)

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

概述

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

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

核心能力

Issue管理

bash

# 列出仓库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管理

bash

# 列出仓库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参数,支持创建/查询/导出操作

工作流管理

bash

# 列出最近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,便于自动化处理:

bash

# 提取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管理器(免费版)不适合处理：

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

触发条件

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

快速开始

依赖详情

bash

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

Step 2:基础查询

bash

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

Step 3:结构化输出

bash

# 使用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)"'

示例

常用命令别名

bash

# 配置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

跨仓库批量查询脚本

bash

#!/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

最佳实践

命令选择策略

任务	推荐命令	说明
快速浏览Issue	gh issue list	默认表格输出,适合人工查看
自动化处理	gh issue list --json --jq	结构化输出,适合脚本
查看PR diff	gh pr diff	比浏览器更清晰
检查CI状态	gh pr checks	一条命令查看所有检查
定位CI失败	gh run view --log-failed	仅显示失败步骤,节省时间

参数规范

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

JSON与jq组合技巧

bash

# 提取多个字段并格式化
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过滤)

第三方依赖

依赖项	类型	是否必需	获取方式
gh	CLI工具	必需	brew install gh 或参考官方安装文档
jq	命令行工具	可选	brew install jq 或apt install jq
GitHub账号	在线服务	必需	注册GitHub账号并完成gh auth login
LLM API	API	必需	由Agent平台内置LLM提供

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命令

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

输出格式

json

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