用途 本技能用于向 GitHub 仓库提交一个可被他人跟进的 issue,既可以是缺陷报告,也可以是功能请求。其核心目标不是决定 issue 提交到哪里,而是确保 issue 的内容、格式和字段符合仓库预期。
主要能力
- 查重:调用 search_issues,以症状、错误文本或功能名称为关键词,并结合 repo:owner/name 与 is:issue 限定搜索范围;同时搜索已关闭的 issue,因为以“不计划处理”关闭的 issue 同样是一种答复。建议先用 perPage: 5,且只返回 number、title、state 字段;再用 in:title、state、label 等限定符缩小范围;不要靠 page 深翻。
- 阅读相近 issue:对看起来接近的 issue 调用 issue_read。若已存在相关 issue,添加评论通常比再提一条新报告更有用。
- 了解仓库规范:通过 list_issue_types 获取仓库或组织接受的类型;通过 list_issue_fields 获取字段定义,包括名称、类型,以及单选字段的合法选项名;通过 list_label 获取标签,按使用频率排序。
- 撰写并提交:调用 issue_write,method 设为 create,并给出 title 与 body;type、labels、assignees、milestone 和 issue_fields 都应来自上一步查询结果,而不是照搬其他项目。
- 拆分:当问题确实包含多个可分别处理的部分时,用 sub_issue_write(method 设为 add)把子 issue 挂到父 issue 下;不要仅因内容长就拆分。
- 报告 issue 编号与 URL。
可用的 issue 应包含
- 标题:应写明症状或预期结果,不要只写“bug”或“question”。
- 发生了什么与期望什么:按此顺序写明,并给出真实错误文本,而不是对错误的转述。
- 复现方式:让他人能够看到同样现象;如果无法复现,应明确说明。
- 环境:版本、分支或提交;如果平台可能相关,也需注明。
- 已排除项:阅读过的相近 issue 及为何不是同一问题。
- 功能请求:说明当前无法做到什么、为何重要、可接受的解决方式;除非愿意实现,否则不必给出实现方案。
关键字段
- method:新建用 create;更新已有 issue 时用 update,并给出 issue_number。
- type:仅在仓库启用类型时使用;传入臆造值会导致失败,列表为空时应省略。
- issue_fields:数组,每项包含 field_name,以及 value、field_option_name、delete 三者之一;单选字段用 field_option_name,以便在调用前校验选项。
- labels:必须已在仓库存在;该工具只应用标签,不创建标签。
- assignees:指派他人意味着占用其时间,因此只能在明确指令下设置。
- sub_issue_write 的 sub_issue_id 是内部标识,并非 issue 编号,应从 issue 中读取,不能假定编号可用。
提交前确认 调用前展示完整文本:标题、正文、类型、标签、负责人和字段。issue 一经创建即公开、会通知关注者且无法取消发布;事后编辑仍会在历史中保留原内容。确认仓库无误,这是最常见也最难撤销的错误;确认负责人及任何点名提及(两者都会通知);附加子 issue 会改动他人 issue,需确认父 issue,且不使用 replace_parent 而不说明当前父 issue;若搜索发现可能的重复项,应说明并询问是否仍要提交,同时提供在已有 issue 下评论的替代方案。
空结果与失败情形
- 搜索无结果只是弱信号:应分别用错误文本、症状和功能名称再试。
- 仓库禁用 issue:写入会失败;部分项目通过 discussion 或其他仓库接收报告,应先查看仓库。
- 类型或字段选项被拒:说明该值并非本仓库定义,应重新读取定义,不要用近似值重试。
- 标签不存在:可不带该标签提交,并说明原本想用的标签;创建标签是影响整个仓库的独立决定。
- 账户无写入权限:无法从此处提交,应给出完整文本以便手动提交。
- 报告不可复现且不具体:应说明缺失信息,而不是提交一个会因细节不足被关闭的 issue;未提交的问题尚可补救,含糊的 issue 会占用他人注意力后无果而终。
适用场景 适用于需要通过 GitHub 提交单个缺陷或功能请求、需要遵循仓库 issue 类型与字段规范、需要查重并判断是否应改为评论、或需要将大问题拆分为多个可独立处理子 issue 的情况。
限制 无法创建标签;不能绕过仓库禁用 issue 或账户无写入权限的限制;不提供仓库外的提交渠道;对于无法复现或不具体的问题,不应强行提交。