Ship 是一个完全自动化的交付(ship)工作流技能,以 /ship 命令触发。它的定位是把从代码合并到创建 PR 的整条发布链路自动化,属于非交互式流程:用户执行 /ship 即表示直接执行,工作流不会在每一步请求确认,最终输出 PR 的 URL。
用途与整体流程 该工作流按固定步骤推进:检测平台与基线分支、预检、合并基线分支、运行测试、测试覆盖率审计、上线前审查、范围漂移检测、计划完成度审计、版本号递增、生成 CHANGELOG、提交、验证门、推送、创建 PR。
平台与基线分支检测 首先通过 git remote get-url origin 判断托管平台:URL 含 github.com 则视为 GitHub,否则视为未知并只使用 git 原生命令。基线分支的确定顺序为:GitHub 下先用 gh pr view 获取目标分支,再用 gh repo view 获取默认分支;否则用 git symbolic-ref 读取 origin/HEAD,失败则依次尝试 origin/main、origin/master,全部失败时回退到 main。
预检与合并 预检会检查当前分支,若处于基线分支则中止并提示应从功能分支发布;随后运行 git status(不使用 -uall),未提交的改动一律包含在内,并通过 git diff 与 git log 了解本次要发布的内容。之后先拉取并合并基线分支(git fetch origin <base> && git merge origin/<base> --no-edit),使测试针对合并后的状态运行;简单冲突(如 VERSION、CHANGELOG 顺序)可尝试自动解决,复杂或含糊的冲突则停止并展示。
测试与失败归属判定 测试阶段运行 pnpm run build、pnpm run lint、pnpm run test,输出分别写入临时文件后读取判断通过与否。若测试失败,不会立即停止,而是进行失败归属判定:通过 git diff origin/<base>...HEAD --name-only 获取本分支改动文件,将失败归类为「分支内」或「疑似既有」;含糊时默认归为分支内。分支内失败会停止并展示;疑似既有失败会通过提问让用户选择「立即调查修复」或「跳过并继续发布」。
覆盖率审计与上线前审查 覆盖率审计以子代理方式在全新上下文中执行,针对 NestJS 单体仓库的四层整洁架构(domain、application、infrastructure、api)追踪改动代码路径,读取完整文件并沿各分支(if/else、switch、guard、提前返回、错误路径)追踪数据流,对照现有 .spec.ts 测试并按三星标准评分,输出 ASCII 覆盖率图;在存在测试框架时会按既有约定生成缺失路径的单元测试,测试通过则保留、失败修复一次、仍失败则静默删除,最后以 JSON 形式返回覆盖率百分比、缺口数、图表与新增测试列表。上线前审查分两轮:第一轮为关键项(SQL 与数据安全、安全、破坏性变更),第二轮为信息项(架构、错误处理、性能、代码质量);每条发现都需给出 1-10 的置信度,并按 AUTO-FIX 与 ASK 分类处理,自动修复项直接修改,需用户判断的项集中提问;若有修复则提交并重新运行测试。
范围与计划审计 范围漂移检测读取提交信息与改动统计,判断是否存在范围蔓延或缺失需求,结果仅作信息提示、不阻塞流程。计划完成度审计同样以子代理执行,搜索近期计划文件并与 diff 交叉比对,将条目分类为 DONE、PARTIAL、NOT DONE、CHANGED,若有延期项则向用户提问,摘要会写入 PR 正文。
版本号与 CHANGELOG 版本号采用四位格式 MAJOR.MINOR.PATCH.MICRO。工作流先做幂等检查:若 VERSION 与基线分支不同则视为已递增并跳过。否则按改动规模自动决定:少于 50 行或琐碎改动、配置改动递增 MICRO;50 行以上且无功能信号递增 PATCH;检测到功能信号(新路由、迁移、feat/ 分支)时递增 MINOR 并询问;MAJOR 仅用于里程碑或破坏性变更并询问。CHANGELOG 会读取现有文件头部格式,枚举全部提交并读取完整 diff,按主题分组,使用 ### Added、### Changed、### Fixed、### Removed 分节,条目格式为 ## [X.Y.Z.W] - YYYY-MM-DD,并确保每个提交至少对应一条要点。
提交、验证与推送 提交按可二分定位的粒度拆分,顺序为基础设施、领域与应用、基础设施实现、API 层,VERSION 与 CHANGELOG 始终放在最后一个提交;服务与其测试文件放在同一提交,每个提交需独立有效。提交信息通过 /git-commit-format 技能生成,且不包含 Co-Authored-By 或任何 AI 署名尾注。推送前设有验证门:若第 3 步测试之后代码有改动,必须重新运行 build、lint、test,测试失败则停止、不得推送。推送与创建 PR 均做幂等检查:已推送则跳过,已存在打开的 PR 则更新正文而非新建。PR 正文包含 Summary、Test Coverage、Pre-Landing Review、Scope Drift、Plan Completion 与 Test plan 等部分,创建命令为 gh pr create --base <base> --title ... --body ...,最终输出 PR URL。
适用场景与限制 适用于使用 Git 与 GitHub、以 pnpm 作为构建与测试工具链、采用四位版本号与 CHANGELOG 约定的项目,尤其是 NestJS 四层整洁架构仓库。限制与约束包括:处于基线分支时中止;复杂合并冲突、分支内测试失败、需要用户判断的审查项、MINOR 或 MAJOR 版本递增会停止或询问;从不跳过测试、从不强制推送、不请求琐碎确认;必须使用 VERSION 文件中的四位版本格式;CHANGELOG 日期格式为 YYYY-MM-DD;没有新的验证证据不得推送。非 GitHub 平台仅使用 git 原生命令,PR 相关能力可能不可用。