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