SuperAPI AI 工具集

gitkkal-pr

编程与开发

查看项目

更新于 10-21 04:08

技能介绍

用途

gitkkal-pr 用于在当前分支上创建或刷新 GitHub Pull Request,重点在于生成"面向非开发者"的 PR 描述:产品经理、设计师、支持工程师、业务方无需打开 diff 就能理解改动目的与影响。

主要能力

  • 用当前分支历史与意图生成或更新 PR 标题与正文。
  • 接受一个可选自由文本提示词,作为 PR 定位、标题侧重、摘要措辞的参考(非硬性约束)。
  • 纯语言请求与 /gitkkal:pr 斜杠命令等效。
  • 分阶段分析改动意图:先读提交信息与 git diff --stat,不清楚再看针对特定文件的 diff,仍不清楚则询问用户主要关注点,不猜测。
  • 写作前先对变更分类:面向用户(User-facing)、内部能力(Internal capability)、纯重构/维护(Pure refactor / maintenance),并按类别采用不同叙述角度。
  • 标题不超过 50 字符,使用祈使语气,以结果而非实现开场。
  • 正文结构固定为 Background、What Changes、Test Plan;仅当有对审查者有价值的实现细节时才加 Technical Notes。若仓库存在 PR 模板,沿用其结构,但仍在各段内应用受众友好原则。
  • 支持按配置的语言(en 或 ko)输出。

使用方式

  1. 解析仓库根目录,并在存在时加载 gitkkal 配置。
  2. 读取可选的用户提示词。
  3. 运行 gh auth status 检查 GitHub CLI 状态;若不可用或未登录,进入回退模式:仅输出 Markdown 格式的标题/正文,并给出用户之后可自行执行的确切 gh 命令,不尝试 gh pr create/edit。
  4. 正常模式下运行 gh pr view --json number,state 判断模式:已有打开的 PR 为更新模式,缺失/已关闭/已合并为创建模式。
  5. 校验分支安全性:禁止从 main 或 master 创建 PR,绝不使用 git push --force。
  6. 按分阶段方式分析分支意图,确定变更类别。
  7. 构建 PR 内容:标题 <50 字符、祈使语气、结果优先;正文含 Background、What Changes、Test Plan,必要时加 Technical Notes。
  8. 执行操作:创建时按需推送分支后运行 gh pr create --title ... --body ...;更新时用 gh pr edit 完整替换现有标题/正文。回退模式下只返回最终标题/正文文本与命令片段。
  9. 报告生成的 PR 编号、URL 以及模式(创建或更新)。

写作规范

  • Background:1–3 句说明问题、动机或上下文。
  • What Changes:2–6 条,每条一个可观察变化,按概念分组。
  • Technical Notes:0–6 条或一小段,没有有意义内容就整节省略。
  • Test Plan:2–6 个复选项。
  • 先讲问题或用户结果,不先讲文件或函数;用产品或业务词汇,首次出现术语时翻译,如"JWT token"写成"我们发给用户的登录令牌";尽可能量化影响,如"减少约 30% 注册失败"。
  • 纯重构 PR 不写"无用户影响"或留空 Background,而应转化为开发效率、可靠性或未来能力价值,如"未来改动更小、更易审查""构建期而非生产期捕获一类 bug"。

适用场景

  • 需要向产品、设计、支持等非开发角色说明变更价值时。
  • 希望 PR 标题与正文以用户/团队结果为导向而非罗列文件时。
  • 需要对现有 PR 描述做完整重写而非追加时。
  • 需要把重构类工作表述为工程收益时。

限制与约束

  • 必须有 GitHub CLI 且已登录才能实际创建/更新 PR;否则只能输出文本与命令。
  • 不允许从 main 或 master 创建 PR;不使用强制推送。
  • 永不修改已合并的 PR。
  • 更新模式下完整重写描述,不在旧内容上追加。
  • 意图不明确时向用户询问 PR 主要关注点,不自行猜测。
  • 提示词与分支改动冲突时,需先做一次澄清再创建/更新。
  • 交互式提问优先使用宿主提供的问题或选择工具,否则回退纯聊天;回退纯聊天时选项以 1) 2) 3) 单独编号行呈现,不使用 Markdown 有序列表语法,每题编号从 1) 重新开始。
  • PR 正文中省略 Co-Authored-By 行。
  • 产品费用、平台数量等细节暂未提供。