用途:为 GitHub Pull Request 撰写或更新正文,让评审者无需阅读 spec、提交历史或其他文档即可理解改动。正文遵循两条原则:自包含(说明做了什么、为什么、关键决策)与无状态(始终反映相对 origin/main 的当前范围,是快照而非日志,更新时重写受影响章节而非追加变更记录)。
主要能力:先创建有序工作流任务(收集上下文、撰写正文、应用),再按步骤执行。收集上下文时支持多种输入:提供 PR 编号则运行 gh pr diff <number> 与 gh pr view <number>;提供 SPEC.md 路径则读取 spec 并与实现交叉核对(以代码为准);输入 new 则运行 git diff main...HEAD --stat;无输入则从当前分支推断。若存在 tmp/ship/screenshots/ 可纳入截图章节。
正文模板章节:Summary、Key decisions、Recordings、Review setup、Verification、Related issues、Future considerations,不适用则省略。Verification 优先读取 tmp/ship/qa-progress.json,按用户故事汇总覆盖表、列出已验证与需人工验证场景及缺口类型;无该文件时沿用 PR 上已有的 Verification 或 Manual QA 章节,两者都无则写“No manual QA performed.”。Future considerations 可来自 tmp/ship/ship-summary.md 的 Deferred Scope 与 Surfaced Opportunities。
应用方式:先运行 gh auth status 确认 gh CLI 可用,否则输出正文供手动应用。交互模式询问草稿或正式 PR;headless 模式(参数含 --headless)直接创建正式 PR。创建用 git push -u origin <branch> 与 gh pr create [--draft] --title "..." --body "...";更新用 gh pr edit <number> --body "...",并整体重写正文。推送前运行 git status 检查未提交改动,交互模式询问是否纳入,headless 模式不提交未提交文件;不得 stash、reset 或丢弃改动,状态复杂时停止并报告。
适用场景:新功能、增强、缺陷修复、配置/基础设施/重构等改动,按改动类型调整正文深度。也可被 /review-cloud 等技能调用,接收其上下文并返回或直接应用正文。限制:依赖 gh CLI 与 git 环境;QA 证据、截图、ship 摘要等文件不存在时相应章节省略;不生成推测性测试场景。