SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场github-issues

github-issues

编程与开发

查看项目

更新于 10-15 16:16

技能介绍

用途

该技能用于管理 GitHub Issues，基于 @modelcontextprotocol/server-github MCP 服务器以及 GitHub CLI / REST API 完成 issue 的创建、更新、查询和评论等操作。当用户需要创建 bug 报告、功能请求或任务 issue，或更新已有 issue 时使用。

主要能力

MCP 工具（读操作）

  • mcp__github__issue_read：读取 issue 详情、子 issue、评论、标签（方法：get、get_comments、get_sub_issues、get_labels）
  • mcp__github__list_issues：按状态、标签、日期列出和筛选仓库 issue
  • mcp__github__search_issues：使用 GitHub 搜索语法跨仓库搜索 issue
  • mcp__github__projects_list：列出项目、项目字段、项目条目、状态更新
  • mcp__github__projects_get：获取项目、字段、条目或状态更新的详情
  • mcp__github__projects_write：添加/更新/删除项目条目，创建状态更新

MCP 工具（写操作）

  • mcp__github__issue_write：创建或更新 issue（方法：create、update），支持标题、正文、类型、标签、负责人、里程碑和 issue 字段
  • mcp__github__add_issue_comment：为 issue 添加评论或表情回应
  • mcp__github__sub_issue_write：添加、移除或重新排序子 issue

CLI / REST API（写操作）

当 MCP 服务器未连接，或需要 MCP 工具未暴露的 REST 字段时，可使用 gh api 完成相同的写操作。

  • 创建 issue：gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...
  • 更新 issue：gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...
  • 添加评论：gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...
  • 关闭 issue：gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed
  • 设置 issue 类型：在创建调用中包含 -f type=Bug（仅 REST API 支持，gh issue create CLI 不支持）

注意：gh issue create 可用于基本 issue 创建，但不支持 --type 标志。需要设置 issue 类型时使用 gh api。

使用方式

工作流

  1. 确定操作：创建、更新还是查询？
  2. 收集上下文：按需获取仓库信息、现有标签、里程碑
  3. 组织内容：使用 references/templates.md 中的合适模板
  4. 执行：读操作使用 MCP 工具，写操作使用 gh api
  5. 确认：向用户报告 issue URL

创建 Issue

使用 gh api 创建 issue，支持包括 issue 类型在内的所有参数。

gh api repos/{owner}/{repo}/issues \
  -X POST \
  -f title="Issue title" \
  -f body="Issue body in markdown" \
  -f type="Bug" \
  --jq '{number, html_url}'

可选参数（添加到 gh api 调用中）：

  • -f type="Bug"：issue 类型（Bug、Feature、Task、Epic 等）
  • -f 'labels[]=bug'：标签（多个可重复）
  • -f 'assignees[]=username'：负责人（多个可重复）
  • -f milestone=1：里程碑编号

需为整个 name[]=value 对加引号。[] 在 zsh（macOS 默认 shell）中是 glob 模式，未加引号的 -f labels[]=bug 无法传递给 gh，会报错：zsh: no matches found: labels[]=bug

Issue 类型是组织级元数据。要发现可用类型，可使用：

gh api graphql -f query='{ organization(login: "ORG") { issueTypes(first: 10) { nodes { name } } } }' --jq '.data.organization.issueTypes.nodes[].name'

优先使用 issue 类型而非标签进行分类。当 issue 类型可用（如 Bug、Feature、Task）时，使用 type 参数，而不是应用等效标签（如 bug 或 enhancement）。Issue 类型是 GitHub 上对 issue 进行分类的规范方式。仅当组织未配置 issue 类型时，才回退到标签。

标题规范

  • 具体且可操作
  • 保持在 72 个字符以内
  • 设置了 issue 类型时，不要添加 [Bug] 等冗余前缀

示例：

  • Login fails with SSO enabled（配合 type=Bug）
  • Add dark mode support（配合 type=Feature）
  • Add unit tests for auth module（配合 type=Task）

正文结构

始终使用 references/templates.md 中的模板。根据 issue 类型选择：

  • Bug、error、broken、not working → Bug Report
  • Feature、enhancement、add、new → Feature Request
  • Task、chore、refactor、update → Task

更新 Issue

使用 gh api 的 PATCH：

gh api repos/{owner}/{repo}/issues/{number} \
  -X PATCH \
  -f state=closed \
  -f title="Updated title" \
  --jq '{number, html_url}'

只包含要更改的字段。可用字段：title、body、state（open/closed）、labels、assignees、milestone。

示例

示例 1：Bug 报告

用户："Create a bug issue - the login page crashes when using SSO"

操作：

gh api repos/github/awesome-copilot/issues \
  -X POST \
  -f title="Login page crashes when using SSO" \
  -f type="Bug" \
  -f 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." \
  --jq '{number, html_url}'

示例 2：功能请求

用户："Create a feature request for dark mode with high priority"

操作：

gh api repos/github/awesome-copilot/issues \
  -X POST \
  -f title="Add dark mode support" \
  -f type="Feature" \
  -f 'labels[]=high-priority' \
  -f 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

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

## Acceptance Criteria
- [ ] Toggle switch in settings
- [ ] Persists user preference
- [ ] Respects system preference by default" \
  --jq '{number, html_url}'

常用标签

  • bug：Something isn't working
  • enhancement：New feature or improvement
  • documentation：Documentation updates
  • good first issue：Good for newcomers
  • help wanted：Extra attention needed
  • question：Further information requested
  • wontfix：Will not be addressed
  • duplicate：Already exists
  • high-priority：Urgent issues

提示

  • 创建 issue 前始终确认仓库上下文
  • 询问缺失的关键信息，而不是猜测
  • 已知时链接相关 issue：Related to #123
  • 更新时先获取当前 issue，以保留未更改的字段

扩展能力

以下功能需要超出基本 MCP 工具的 REST 或 GraphQL API。每项都在各自的参考文件中记录，以便智能体只加载所需知识。

  • 高级搜索：复杂布尔逻辑查询、日期范围、跨仓库搜索、issue 字段筛选（field.name:value）→ references/search.md
  • 子 issue 与父 issue：将工作拆分为层级任务 → references/sub-issues.md
  • 里程碑：创建、读取、更新、关闭、重新打开、删除里程碑及管理里程碑 issue → references/milestones.md
  • 标签：发现、创建、重命名、重新着色、删除仓库标签；为 issue 添加或替换标签 → references/labels.md
  • Issue 依赖：跟踪 blocked-by / blocking 关系 → references/dependencies.md
  • Issue 类型（高级）：超出 MCP list_issue_types / type 参数的 GraphQL 操作 → references/issue-types.md
  • Projects V2：项目看板、进度报告、字段管理 → references/projects.md
  • Issue 字段：自定义元数据：日期、优先级、文本、数字（私有预览）→ references/issue-fields.md
  • Issue 中的图片：通过 CLI 在 issue 正文和评论中嵌入图片 → references/images.md

适用场景

  • 创建 bug 报告、功能请求或任务 issue
  • 更新 issue 状态、标题、正文、标签、负责人或里程碑
  • 查询、列出或搜索仓库 issue
  • 管理子 issue、里程碑、标签、依赖关系和 Projects V2

限制

  • 部分扩展能力需要 REST 或 GraphQL API，超出基本 MCP 工具范围
  • gh issue create 不支持 --type 标志，设置 issue 类型需使用 gh api
  • Issue 字段为私有预览功能
  • 使用 zsh 时，name[]=value 对必须加引号，否则无法传递给 gh