名称: gh 描述: 此技能应用于使用GitHub CLI (gh)处理拉取请求、问题、发布和GitHub自动化。当用户提到gh命令、GitHub工作流、PR操作、问题管理或GitHub API访问时使用。对于理解gh的心智模型、命令结构以及与git工作流的集成至关重要。
GitHub CLI (gh)
概述
GitHub CLI (gh) 是GitHub的官方命令行工具，将拉取请求、问题、发布和其他GitHub概念带到终端。此技能提供使用gh简化GitHub工作流的全面指导，包括PR管理、问题跟踪、仓库操作和API访问。
何时使用此技能
在以下情况下调用此技能：
- 用户提到GitHub CLI (
gh) 命令或工作流 - 询问如何从命令行创建、查看或管理拉取请求
- 需要通过CLI帮助GitHub问题管理
- 想要理解gh的心智模型或命令结构
- 请求GitHub自动化或脚本编写指导
- 询问通过gh访问GitHub API
- 需要gh身份验证或配置帮助
- 请求gh、git和其他工具（如erk）的集成模式
核心概念
在提供指导之前，理解以下关键概念：
三层架构：
- 高级命令 (porcelain)：
gh pr、gh issue、gh repo- 用户友好的工作流 - API访问：
gh api- 直接REST/GraphQL访问，内置身份验证 - Git集成：从git远程仓库自动检测仓库，并使用当前分支
上下文解析：
gh自动从git远程仓库检测仓库- 使用当前分支推断PR上下文
- 当不明确时回退到交互式选择
心智模型：
将gh视为“GitHub工作流CLI原生” - 每个命令映射到优化终端使用的常见GitHub工作流。
使用参考文档
在提供gh指导时，加载全面的参考文档：
references/gh.md
此参考包含：
- 完整的心智模型和术语
- PR、问题、仓库、发布等的完整命令参考
- 身份验证和配置模式
- 常见场景的工作流模式
- 集成细节（erk、git、CI/CD）
- GitHub API访问模式
- 日常开发的实用示例
加载策略：
- 当用户询问gh相关问题时，总是加载
references/gh.md - 参考文档全面（约1480行），但优化为渐进式阅读
- 需要时使用grep模式查找特定部分：
gh pr- 拉取请求命令gh issue- 问题管理命令gh repo- 仓库操作gh api- API访问模式Pattern [0-9]:- 工作流模式Authentication- 身份验证设置erk Integration- 与erk的集成
常见操作
当用户请求gh帮助时，使用以下模式指导他们：
首次设置
- 检查gh是否安装：
gh --version - 身份验证：
gh auth login（交互式）或gh auth status（检查当前） - 配置默认值：
gh config set <key> <value> - 测试连接：
gh repo view（在git仓库中）
拉取请求操作
加载references/gh.md并搜索“gh pr”部分以提供：
- 创建PR：
gh pr create（交互式或使用标志） - 查看PR：
gh pr view、gh pr list - 检出PR：
gh pr checkout <number> - 审查PR：
gh pr review、gh pr diff - 合并PR：
gh pr merge - PR状态检查：
gh pr checks
问题管理
加载references/gh.md并搜索“gh issue”部分以提供：
- 创建问题：
gh issue create - 列出问题：
gh issue list（带过滤器） - 查看问题：
gh issue view <number> - 更新问题：
gh issue edit、gh issue close - 问题分配和标签
仓库操作
加载references/gh.md并搜索“gh repo”部分以提供：
- 查看仓库：
gh repo view - 克隆仓库：
gh repo clone - 创建仓库：
gh repo create - 分叉仓库：
gh repo fork - 仓库设置和可见性
API访问
加载references/gh.md并搜索“gh api”部分以提供：
- REST API调用：
gh api <endpoint> - GraphQL查询：
gh api graphql -f query='...' - 分页处理
- 使用
--jq进行JSON处理 - 身份验证细节
对于高级GraphQL用例，加载references/graphql.md：
- 项目V2管理（无REST API存在）
- 讨论API操作
- 跨多个仓库的批量查询
- 复杂嵌套数据检索
- 高级问题搜索
- 参见下面的GraphQL API参考部分
发布管理
加载references/gh.md并搜索“gh release”部分以提供：
- 创建发布：
gh release create - 列出发布：
gh release list - 下载资产：
gh release download - 上传资产：
gh release upload
工作流指导
当用户描述其工作流需求时，将其映射到参考中的模式：
模式1：日常PR工作流 - 创建、审查、合并PR 模式2：问题分类 - 列出、过滤和管理问题 模式3：发布自动化 - 脚本化发布创建和资产管理 模式4：PR检查和状态 - 监控CI/CD和审查状态 模式5：多仓库操作 - 跨多个仓库工作 模式6：GitHub API脚本编写 - 自动化复杂GitHub工作流 模式7：代码审查工作流 - 从命令行审查PR
根据用户需求从references/gh.md加载适当的模式部分。
输出格式化
当用户需要解析或格式化gh输出时：
- 从
references/gh.md加载输出格式化部分 - 解释格式选项：
--json、--jq、--template - 显示JSON字段选择：
gh pr list --json number,title,state - 演示jq过滤：
gh api /repos/{owner}/{repo}/pulls | jq '.[] | select(.draft==false)' - 提供自定义输出的模板示例
身份验证和配置
当用户需要身份验证或配置帮助时：
- 从
references/gh.md加载身份验证与配置部分 - 区分：
- 身份验证：
gh auth login、令牌管理 - 配置：
gh config set、每命令默认值
- 身份验证：
- 解释身份验证方法：浏览器、令牌、SSH
- 显示常见配置设置：
git_protocol、editor、pager - 处理多个账户和企业实例
集成指导
Erk集成
当用户提到erk或工作树工作流时：
- 从
references/gh.md加载Erk集成部分 - 解释gh如何在工作树中检测仓库
- 显示跨多个工作树的PR操作
- 指导在需要时使用
--repo标志 - 参考erk文档以获取工作树特定模式
Git集成
当用户需要理解gh + git工作流时：
- 从
references/gh.md加载Git集成部分 - 解释从git远程仓库的仓库检测
- 显示当前分支如何影响PR命令
- 演示组合的git + gh工作流
- 澄清何时使用git与gh命令
CI/CD集成
当用户想要将gh与CI/CD集成时：
- 从
references/gh.md加载CI/CD模式 - 显示CI环境中的身份验证：
GH_TOKEN - 提供自动化PR创建/合并的示例
- 演示状态检查监控
- 指导发布自动化
脚本编写和自动化
当用户想要脚本化GitHub工作流时：
- 从
references/gh.md加载脚本编写部分 - 显示如何在shell脚本中使用
gh - 演示错误处理：
--jq、退出代码 - 解释大数据集的分页
- 提供常见自动化模式的示例：
- 跨PR/问题的批量操作
- 自定义通知
- 发布工作流
- 仓库管理
高级功能
当用户需要高级功能时：
- 别名：通过
gh alias set自定义命令 - 扩展：第三方gh扩展
- GraphQL：超越REST API的复杂查询（参见GraphQL API参考）
- Webhooks：通过API触发工作流
- GitHub Actions：通过
gh workflow与工作流交互
为每个高级功能从references/gh.md加载相关部分。
GraphQL API参考
当标准gh命令不足时，通过gh api graphql使用GraphQL。加载references/graphql.md以获取全面的GraphQL指导。
何时使用GraphQL：
当porcelain命令（gh pr、gh issue等）无法完成任务时使用GraphQL：
-
项目V2：无REST API存在 - 所有操作都需要GraphQL
- 创建/更新项目
- 添加项目和更新字段值
- 查询自定义字段和项目数据
-
讨论：无porcelain命令可用
- 创建/管理讨论
- 添加评论和回复
- 查询讨论类别
-
批量操作：在一个API调用中查询多个资源
- 比较多个仓库
- 跨仓库聚合数据
- 减少速率限制消耗
-
复杂查询：高效获取嵌套数据
- 一个调用中包含审查、评论和状态检查的PR
- 包含时间线、反应和链接PR的问题
- 包含开放问题、PR和贡献者的仓库
-
高级搜索：超越基本命令的复杂过滤
- 多标准问题/PR搜索
- 布尔逻辑和日期范围
- 高级排序选项
-
自定义字段：精确字段选择
- 仅请求所需字段
- 优化性能
- 构建自定义数据聚合
GraphQL资源：
-
references/graphql.md- 完整的GraphQL指南，包括：- 需要GraphQL的用例
- 常见模式（变量、分页、批处理等）
- 完整示例（项目V2、讨论、批量查询）
- 最佳实践和故障排除
-
references/graphql-schema-core.md- 核心模式类型（仅在需要时加载）：- 仓库、问题、拉取请求等的详细字段信息
- 项目V2字段类型和突变
- 讨论类型和操作
- 输入类型和枚举
加载策略：
- 从
references/graphql.md开始，了解用例和模式 - 仅在需要详细模式信息时加载
references/graphql-schema-core.md - 使用grep模式查找特定部分：
Projects V2- 项目自动化示例Discussion- 讨论API示例Batch- 批量查询模式Pagination- 基于游标的分页Example [0-9]- 完整工作示例
速率限制和API后端
当用户遇到速率限制问题或需要优化API使用时：
- 加载
references/api-backend-audit.md以获取完整的命令到API映射 - 理解差异：
- REST：5,000请求/小时，按请求计数
- GraphQL：5,000点/小时，基于查询复杂性成本
- 搜索：30请求/分钟（单独限制）
- 关键见解：
- PR/问题命令使用GraphQL（查询成本可变）
- Run/Workflow/Gist命令使用REST（可预测成本）
- 项目命令仅需要GraphQL
- 搜索总是使用REST，限制更严格
- 检查当前限制：
gh api rate_limit --jq '.resources'
故障排除
当用户遇到问题时：
- 检查身份验证：
gh auth status - 验证仓库检测：
gh repo view - 测试API访问：
gh api user - 审查配置：
gh config list - 检查速率限制：
gh api rate_limit - 启用调试模式：
GH_DEBUG=api gh <command>
从references/gh.md加载故障排除部分以获取特定错误模式。
命令发现
当用户询问“gh能做什么？”时：
- 从主要命令概述开始：
pr、issue、repo、release、workflow - 显示命令帮助：
gh <command> --help - 演示交互式模式：大多数命令以交互方式工作
- 指向
gh api以处理未覆盖的porcelain命令内容 - 参考
references/gh.md中的完整命令参考
资源
references/
-
gh.md- 全面的GitHub CLI心智模型和命令参考（约1480行）- 加载以获取所有标准gh命令指导
- 完整的工作流模式和示例
- 集成模式（erk、git、CI/CD）
-
graphql.md- GitHub GraphQL API全面指南（约1000行）- 当porcelain命令不足时加载
- 需要GraphQL的用例（项目V2、讨论、批量查询）
- 完整的模式和示例
- 最佳实践和故障排除
-
graphql-schema-core.md- 核心GraphQL模式类型（约500行）- 仅在需要详细模式信息时加载
- 核心类型的详细字段定义
- 突变输入类型和示例
-
api-backend-audit.md- REST与GraphQL API后端审计（约850行）- 加载以理解命令使用哪种API类型
- 速率限制指导和优化策略
- 所有gh命令到其API后端的完整映射
- 批量操作替代方案和缓存策略
这些参考应根据需要加载以确保准确、详细的信息。使用渐进式披露：从主参考开始，然后在需要时加载专门的GraphQL文档。