SuperAPI AI 工具集

file-followup-issue

编程与开发

查看项目

更新于 11-13 20:20

技能介绍

用途:该技能用于把「确实值得做、但不属于当前 PR 范围」的发现停放到 GitHub 议题中,避免污染当前 PR,同时给未来接手者留下足够上下文,使其能独立开启新的 PR。

主要能力:

  1. 准入判断(Gate)。仅当三项条件全部成立时才登记议题:当前 PR 已完整稳定(已关闭其原始议题,该发现并非其所需);发现真实且净收益为正(真正的缺陷或改进,而非吹毛求疵);工作非平凡且超出范围(在此修复会引入新的设计决策、存在未解决的不确定性,或把改动影响面扩大到原议题所需之外)。若条件不成立,应改走替代路径并且停止,不创建议题:平凡且在范围内则直接在当前 PR 修复;在范围内但规模较大则属于当前 PR 计划;并非真实问题则丢弃(若为评审线程则驳回)。
  2. 去重检索。创建前执行 gh issue list --state all --search "<3-5 distinctive keywords>" --limit 20;若存在明确匹配,则链接已有议题而非新建,并跳到记录步骤,引用已有议题;须保留该议题的归属与路由标签,去重不授权新的路由。
  3. 创建前确认(对外动作)。向用户展示起草的标题与正文并取得同意。
  4. 按模板创建议题,并给出标题与正文的写入方式:标题和正文会引用代码与评审文本,其中 $(...) 与反引号会在 gh 运行前被 shell 展开,因此应先用编辑工具分别写入标题文件与正文文件,再通过 cat 读取标题(shell 变量内容不会被再次解析替换),命令为:title=$(cat <path to the title file you wrote>);gh issue create --title "$title" --body-file <path to the body file you wrote)。
  5. 维护者路由机制。为维护者代办的议题应遵循其选定路由,否则应询问选择;该选择可与草稿批准合并确认。标签须先对照已入库的标签目录确认,缺失标签会导致命令失败。一般队列:创建时不加 --assignee 或 pydanty:skip,随后运行 gh issue edit <issue-number> --add-label pydanty:triage-issue,显式请求 Pydanty 分诊(团队自建议题默认会跳过分诊)。立即处理:创建时使用 --assignee <maintainer-login> --label pydanty:skip,指派负责该项工作的人类维护者,该标签抑制 Pydanty 分诊与 retry-pr 触发,并通过 PR 技能将归属延续到 PR 上。对外部贡献者不得套用这些维护者路由:外部贡献者无法应用仓库标签,其议题应留在常规分诊中。
  6. 记录延迟决定。在 pr-decisions.md 中记录为何停放而非就地修复:新建的维护者议题需在决定中写明所选路由与人类负责人(或无本地负责人);贡献者来源字段需用带引号的 heredoc 绑定(如 adopt-pr 中所述);当去重跳过了议题创建、第 3 步没有绑定标题时同样适用;切勿将贡献者文本粘贴进双引号命令参数。示例命令使用 append-pr-decision.sh 并传入 --title、--decision、--why、--source(source 为新议题 URL)。
  7. 报告议题 URL,且不要扩大当前 PR。

议题正文模板包含:## Background(在做什么、在哪里出现,链接来源 PR);## The problem(具体明确的缺陷或改进);## Why it's out of scope for the originating PR(具体原因:自有设计决策、未解决的不确定性或影响面);## Where(文件路径与符号,不含行号);## Suggested direction (low-confidence)(可选起点,明确标注为线索而非决定,没有则省略)。

适用场景:在完成并稳定某个 PR 后,发现真实但不属于该 PR 范围的缺陷或改进;或需要为维护者代办的后续工作确定路由与归属。

限制:仅针对 GitHub 议题流程;需要 gh 命令行与仓库标签目录;对外部贡献者不能应用维护者路由标签;创建议题属对外动作,必须先经用户确认;资料未提供其他平台或自动化集成信息。