github-issues

GitHub 问题管理

创建、获取、更新和管理 GitHub 问题，并集成全面的上下文和结构化工作流。

前提条件

• gh（GitHub CLI）：所有问题操作都需要；可从 https://cli.github.com 安装，或运行 brew install gh

何时使用此技能

在以下情况下启用此技能：

• 用户想要创建新的 GitHub 问题
• 用户要求查看或获取问题详情
• 用户需要更新现有问题
• 用户想要列出仓库中的问题
• 用户提到要在 GitHub 中管理问题、错误报告或功能请求
• 用户想要关闭、重新打开问题或修改问题属性
• 用户需要为问题添加评论或标签
• 用户想要搜索问题

关键规则

重要：创建或修改问题前，始终确认 owner/repo

始终使用描述清晰的问题标题，并提供结构化描述

切勿创建重复问题——适当时先搜索现有问题

可用的 CLI 命令

命令	用途
gh issue create	创建新问题
gh issue edit <number>	更新现有问题
gh issue view <number>	获取问题详情
gh search issues "<query>"	搜索问题
gh issue comment <number>	添加评论
gh issue list	列出仓库问题

工作流

1. 收集上下文

首先，收集有关当前仓库和上下文的信息：

• 确认仓库（所有者和仓库名称）
• 了解问题类型（错误、功能、任务等）
• 收集相关标签、里程碑和受指派人（如适用）

2. 验证仓库

执行任何操作前，确认仓库标识符正确：

• 确认仓库存在
• 了解仓库结构
• 检查可用标签和里程碑

3. 问题操作

创建新问题

创建问题时，收集完整上下文：

必需信息：

• owner：仓库所有者（组织或用户）
• repo：仓库名称
• title：清晰、描述明确的问题标题

可选但建议提供：

• body：Markdown 格式的详细描述
• labels：标签名称（例如，“bug,enhancement”）
• assignees：要指派的用户名
• milestone：里程碑编号（整数）

人在回路中——询问上下文

始终询问以澄清问题详情：

Question: "What type of issue is this?"
Options:
- "Bug report - something is not working correctly"
- "Feature request - new functionality needed"
- "Task - work item to complete"
- "Documentation - documentation needs update"
- "Other - let me describe it"

标题指南：

• 适用时以类型前缀开头：[Bug]、[Feature]、[Docs]
• 具体且可执行
• 控制在 72 个字符以内
• 示例：
  • [Bug] 启用 SSO 后登录失败
  • [Feature] 添加深色模式支持
  • 为 auth 模块添加单元测试

问题描述模板：

结构化描述，让内容清晰易读：

## Summary
[Brief description of the issue]

## Current Behavior
[What is happening now - for bugs]

## Expected Behavior
[What should happen - for bugs]

## Steps to Reproduce
[For bugs - numbered steps]

## Acceptance Criteria
[For features/tasks - what defines "done"]

## Additional Context
[Screenshots, logs, related issues, etc.]

获取问题详情

使用 gh issue view <number>，其中：

• <number>：问题编号（例如，42）

这会返回完整的问题信息，包括：

• 标题和正文
• 状态（open/closed）
• 标签和里程碑
• 受指派人和作者
• 创建/更新时间戳

列出问题

使用 gh issue list 并指定筛选条件：

• --state：“open”、“closed”或“all”
• --label：按标签筛选（逗号分隔）
• --assignee：按受指派人的用户名筛选
• --search：在标题和描述中搜索
• --sort：按“created”、“updated”或“comments”排序
• --order：“asc”或“desc”
• --limit：每页结果数（默认 30）

搜索问题

使用 gh search issues "<query>" 进行高级查询：

• 跨仓库搜索
• 使用 GitHub 搜索限定符（is:open、label:bug 等）
• 在标题和正文中进行全文搜索

更新问题

更新问题时，只提供发生更改的字段：

使用 gh issue edit <number> 并通过标志指定要更新的字段（--title、--body、--add-label、--remove-label、--add-assignee、--milestone 等）

状态更改：

• gh issue reopen <number> - 打开/重新打开问题
• gh issue close <number> - 关闭问题

添加评论

使用 gh issue comment <number> --body "<comment>"，其中：

• <number>：问题编号
• <comment>：Markdown 格式的评论内容

4. 执行操作（需要确认）

重要：创建或修改问题前，必须先征求用户确认

收集完所有信息后，向用户提供摘要以供批准：

Creating issue in repository: owner/repo
Title: [title]
Description: [summary]
Labels: [labels]
Assignee: [assignee]

Proceed with issue creation?

问题类型模板

错误报告

## Description
The [component] is experiencing [issue] when [condition].

## Steps to Reproduce
1. [First step]
2. [Second step]
3. [See error]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Environment
- Application Version: [version]

## Screenshots/Logs
[Attach relevant files]

## Possible Solution
[Optional: if you have ideas]

功能请求

## Summary
[One-line description of the feature]

## Motivation
[Why is this feature needed? What problem does it solve?]

## Proposed Solution
[How should this work?]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Alternatives Considered
[Other approaches considered]

## Additional Context
[Mockups, examples, references]

任务

## Task Description
[What needs to be done]

## Background
[Why is this needed?]

## Requirements
- [ ] [Requirement 1]
- [ ] [Requirement 2]

## Definition of Done
- [ ] [Criterion 1]
- [ ] [Criterion 2]

## Dependencies
[Related issues, blockers]

示例

示例 1：创建错误报告

用户：“创建一个错误问题——使用 SSO 时登录页面会崩溃”

AI 工作流：

1. 如果尚不清楚，询问仓库（owner/repo）
2. 询问有关错误的澄清问题
3. 生成结构化描述
4. 提供摘要以供确认
5. 使用 gh issue create --title "[Bug] Login page crashes when using SSO" --body "<description>" --label "bug" 创建问题

结果：

gh issue create \
  --title "[Bug] Login page crashes when using SSO" \
  --body "## Description
The login page crashes when users attempt to authenticate using SSO.

## Steps to Reproduce
1. Navigate to login page
2. Click 'Sign in with SSO'
3. Page crashes

## Expected Behavior
SSO authentication should complete and redirect to dashboard.

## Actual Behavior
Page becomes unresponsive and displays error.

## Environment
- Browser: [To be filled]
- OS: [To be filled]" \
  --label "bug"

示例 2：带优先级的功能请求

用户：“为深色模式提交功能请求，并设为高优先级”

AI 工作流：

1. 收集功能详情
2. 整理请求
3. 添加合适的标签
4. 确认并创建

结果：

gh issue create \
  --title "[Feature] Add dark mode support" \
  --body "## Summary
Add dark mode theme option for improved user experience and accessibility.

## Motivation
- Reduces eye strain in low-light environments
- Increasingly expected by users
- Improves accessibility

## Proposed Solution
Implement theme toggle with system preference detection.

## Acceptance Criteria
- [ ] Toggle switch in settings
- [ ] Persists user preference
- [ ] Respects system preference by default
- [ ] All UI components support both themes" \
  --label "enhancement,high-priority"

示例 3：列出并筛选问题

用户：“显示所有分配给我的未关闭错误问题”

AI 工作流：

1. 使用 gh issue list --state open --label bug --assignee @me

结果：

Found 3 open bug issues assigned to you:

#142 - [Bug] API timeout on large file uploads
      Labels: bug, priority-medium
      Created: 2024-01-15

#138 - [Bug] Dashboard graphs not rendering on Safari
      Labels: bug, frontend
      Created: 2024-01-12

#125 - [Bug] Email notifications delayed by 30+ minutes
      Labels: bug, priority-high
      Created: 2024-01-08

示例 4：添加评论并关闭问题

用户：“关闭问题 #142，并添加评论说明它已在 v2.4.0 中修复”

AI 工作流：

1. 首先，向问题添加评论：gh issue comment 142 --body "Fixed in v2.4.0. Closing this issue."
2. 然后关闭问题：gh issue close 142

结果：

Issue #142 has been commented and closed.

常见标签

适用时使用以下标准标签：

标签	用途
bug	某项功能无法正常工作
enhancement	新功能或改进
documentation	文档更新
good first issue	适合新手处理
help wanted	需要额外关注
question	需要进一步了解信息
wontfix	不会处理
duplicate	已存在
invalid	无效问题

重要说明

• 始终验证仓库访问权限 - 确保你有权创建或修改问题
• 一致地使用标签 - 遵循仓库的标签规范
• 标题要具体 - 使用 [Bug]、[Feature]、[Task] 前缀以便明确类型
• 包含复现步骤 - 这对错误报告至关重要
• 定义验收标准 - 为功能和任务明确“完成定义”
• 关联相关问题 - 在描述中使用“Related to #XX”或“Blocks #XX”
• 使用 @username 提及用户 - 以便对方看到并收到通知
• 使用里程碑 - 适用时将问题关联到发布版本

GitHub 问题最佳实践

编写有效的标题

• 简洁明了，同时准确描述问题
• 包含问题类型前缀：[Bug]、[Feature]、[Task]、[Docs]
• 适用时注明受影响的组件
• 避免使用“修复错误”或“更新代码”等含糊标题

组织描述内容

• 使用 Markdown 格式提升可读性
• 在开头提供所有相关背景信息
• 有帮助时添加截图或日志
• 链接相关问题、PR 或文档
• 使用任务列表跟踪子项

标签策略

• 将类型标签（bug、enhancement）与领域标签（frontend、api）结合使用
• 需要时使用优先级标签（priority-high、priority-low）
• 在各个仓库中保持标签体系一致

分配与工作流

• 将问题分配给具体的团队成员
• 使用里程碑进行发布规划
• 随着工作推进更新问题状态
• 关闭问题时注明修复它的 PR，例如：“Fixes #XX”