SuperAPI AI 工具集

issue-authoring

编程与开发

查看项目

更新于 11-16 05:45

技能介绍

用途 本技能用于向 GitHub 仓库提交一个可被他人跟进的 issue,既可以是缺陷报告,也可以是功能请求。其核心目标不是决定 issue 提交到哪里,而是确保 issue 的内容、格式和字段符合仓库预期。

主要能力

  1. 查重:调用 search_issues,以症状、错误文本或功能名称为关键词,并结合 repo:owner/name 与 is:issue 限定搜索范围;同时搜索已关闭的 issue,因为以“不计划处理”关闭的 issue 同样是一种答复。建议先用 perPage: 5,且只返回 number、title、state 字段;再用 in:title、state、label 等限定符缩小范围;不要靠 page 深翻。
  2. 阅读相近 issue:对看起来接近的 issue 调用 issue_read。若已存在相关 issue,添加评论通常比再提一条新报告更有用。
  3. 了解仓库规范:通过 list_issue_types 获取仓库或组织接受的类型;通过 list_issue_fields 获取字段定义,包括名称、类型,以及单选字段的合法选项名;通过 list_label 获取标签,按使用频率排序。
  4. 撰写并提交:调用 issue_write,method 设为 create,并给出 title 与 body;type、labels、assignees、milestone 和 issue_fields 都应来自上一步查询结果,而不是照搬其他项目。
  5. 拆分:当问题确实包含多个可分别处理的部分时,用 sub_issue_write(method 设为 add)把子 issue 挂到父 issue 下;不要仅因内容长就拆分。
  6. 报告 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 或账户无写入权限的限制;不提供仓库外的提交渠道;对于无法复现或不具体的问题,不应强行提交。