狸想岛 · AI 实战学习社区

🎯 学 gstack 的旗舰级 /ship 工作流：不是 gh pr create 的简单封装，而是从平台检测、VERSION 碰撞检测、审查就绪仪表盘、CHANGELOG 自动生成到 PR 创建与远程推送的完整工程发布流程——确保每次合入都有审计追踪、版本一致性和文档完整性。 ⏱️ 预计时间：40 分钟

[!quote]- 📖 原Skill精要 技能名称：ship 核心功能：gstack 旗舰级发布工作流。检测+合并 base 分支、运行测试、审查 diff、升级 VERSION、更新 CHANGELOG、提交、推送、创建 PR。14 步完整管道：从平台检测→VERSION 碰撞→审查仪表盘检查→Greptile 分诊→CHANGELOG 生成→PR 创建。确保每次合入都有完整审计追踪。 所属体系：gstack 虚拟工程团队 协作关系：内置调用 [[L6-15-PR代码审查|review]] 确保审查门控，PR 创建后由 [[L6-26-自动部署落地|land-and-deploy]] 接管

§1 课程概览

/ship 是 gstack 的旗舰级发布工作流——它不只是一个 gh pr create 的封装，而是将发布从一个机械操作升级为工程判断行为。四大门禁（VERSION 碰撞检测 → 审查就绪检查 → Greptile 分诊 → Fix-First 修复循环）确保每次合入都经过充分验证。CHANGELOG 自动生成遵循"面向用户"的铁律：以 "You can now..." 风格描述变更，永不覆盖已有条目。VERSION 碰撞检测通过 gstack-next-version 自动发现并解决两个 PR 抢占同一版本号的冲突。PR 创建跨平台一致（GitHub/GitLab），标题强制以 v<VERSION> 开头。与 /land-and-deploy 的明确分工（ship = 发布准备，land-and-deploy = 发布执行）为人类审查者预留了判断窗口。

[!tip] 白话小课堂你以为 ship 就是帮你敲 gh pr create？那你大材小用了。ship 像一个发布管家——帮你检查版本号有没有人抢、审查做了没有、CHANGELOG 写了没有、代码质量过不过关，全过了才帮你开 PR。它把"发布"从随手操作变成了有审计追踪的工程流程。

§2 /ship 的定位——不是创建 PR，是发布

/ship 做什么

传统发布流程： → git push → gh pr create → 填标题 → 描述 → 等审查 → merge

/ship 发布流程： → 平台检测 → VERSION 碰撞检测 → 审查就绪检查 → 运行 /review（或检查已有审查） → Greptile 分诊（Step 3.75） → Fix-First 修复循环 → CHANGELOG 自动生成 → VERSION 自动 bump → PR 创建（跨平台：GitHub/GitLab） → 远程推送

/ship 把创建 PR 变成工程判断行为，不是机械操作。

💡 白话小课堂：你以为 ship 就是帮你敲 gh pr create？那你大材小用了。

§3 Step 0-1：平台检测与分支验证

Step 0: 平台与基准分支检测

ship 复用 review 的检测逻辑： → GitHub: gh pr view → gh repo view → GitLab: glab mr view → glab repo view → 原生 Git: symbolic-ref / rev-parse origin/main → origin/master → 回退: main

检测出基准分支后，所有 git diff / git log / git fetch 使用这个名字。

Step 1: 分支检查

→ git branch --show-current → 获取当前分支 → 如果在基准分支上 → "Nothing to ship" 并停止 → git fetch origin → git diff origin/ --stat → 无 diff → 同上停止

门控逻辑: 没有变化就不浪费后续所有步骤。

Step 1.5: PR 存在性检测

→ gh pr view / glab mr view → PR 已存在且 OPEN → 检查 VERSION/CHANGELOG 是否一致 → PR 已 MERGED → "Already merged" 停止 → PR 已 CLOSED → 询问是否重开 → 无 PR → 继续创建流程

§4 VERSION 碰撞检测——防止两个 PR 使用相同版本号

为什么 VERSION 碰撞是严重问题？

场景： → 分支 A: bump VERSION 到 1.7.0.0 → 分支 B: 同时 bump VERSION 到 1.7.0.0 → A 先合 → B 的 CHANGELOG 会覆盖 A 的 → A 的发布记录丢失

gstack-next-version 碰撞检测

/ship 在 bump VERSION 之前调用 gstack-next-version： → 查询目标分支上所有 open PR 的 VERSION → 返回下一个可用版本号 → 如果当前 VERSION 已被其他 PR 占用 → 自动 bump 到下一个 slot → 更新 VERSION + CHANGELOG header + PR 标题（原子操作）

四种 bump 级别

→ micro: X.Y.Z+1 → 微小修复 → patch: X.Y.Z+1.0 → 补丁版本 → minor: X.Y+1.0.0 → 功能版本 → major: X+1.0.0.0 → 破坏性变更

冲突时的行为

→ 检测到碰撞 → 自动 bump 到下一可用 slot → 发出 ALREADY_BUMPED 信号 → 更新所有引用 VERSION 的文件（package.json, etc.） → 确保 PR 标题以 v 开头

⚠️ 避坑指南： VERSION 碰撞是团队协作中最容易被忽视的严重问题。你和同事同时开了两个 PR，都 bump 到了 1.7.0.0。

§5 审查就绪仪表盘——合入前的质量门禁

/ship 如何与 /review 集成

/ship 在创建 PR 之前运行审查就绪检查：

Step 2.5: 审查状态读取

→ 运行 gstack-review-read → 检查审查仪表盘的状态： → 至少一次审查完成 → 继续 → 审查状态为 "clean" → 高质量合入 → 审查状态为 "issues_found" → 列出未解决问题 → 无审查记录 → 提示先运行 /review 或 /autoplan

Step 3: 审查就绪门控

→ 如果审查缺失或陈旧（4+ commits since） → 提供快速审查选项（2 min checklist） → 或运行完整 /review → 或跳过（用户明确选择） → 审查通过 → 继续 ship 流程 → 审查发现 CRITICAL → 阻止 ship

Step 3.75: Greptile 分诊（如果可用）

→ 抓取 Greptile 评论 → 分类：VALID & ACTIONABLE / ALREADY FIXED / FALSE POSITIVE → VALID & ACTIONABLE → 纳入修复循环 → ALREADY FIXED → 自动回复 → FALSE POSITIVE → 写入抑制列表 + 回复

门禁层次

→ Layer 1: VERSION 碰撞检测（防止覆盖） → Layer 2: 审查就绪检查（防止未审就合） → Layer 3: Greptile 分诊（利用外部审查信号） → Layer 4: Fix-First 修复循环（防止已知问题合入）

🔑 核心秘诀：四层门禁中，Layer 2（审查就绪检查）是最容易被跳过的——"我知道这段代码没问题，直接合吧"。

§6 CHANGELOG 自动生成——从 diff 到发布说明

CHANGELOG 生成原则

/ship 不要求开发者手动写 CHANGELOG——它从实际变更中生成：

生成过程

→ git log ..HEAD --oneline → 提交历史 → git diff ...HEAD --stat → 变更摘要 → 检测变更类型：新功能 / Bug 修复 / 重构 / 文档 → 按类别分组生成条目

条目标准

→ 以用户能理解的方式描述变更 → "You can now..." 风格，不是 commit message → 内部/贡献者变更放在 "For contributors" 部分 → 所有条目以 v header 开头

CHANGELOG 规则的铁律

→ 永不覆盖已有条目（用 Edit 不用 Write） → 永不删除其他版本的条目 → VERSION 必须 bump（永不静默 bump） → PR 标题必须以 v 开头

Release Summary 格式

每个版本条目以 release-summary 部分开头： → 两行粗体标题（10-14 词） → 导览段落（3-5 句） → "The N numbers that matter" 表格（BEFORE/AFTER/Δ） → 尾声段落（2-4 句总结） → 然后是 "### Itemized changes"

§7 PR 创建与推送——跨平台一致性

GitHub PR 创建

→ gh pr create --title "v <描述>" --body "<完整描述>" → 标题必须以 v 开头 → Body 包含：变更摘要 + 审查状态 + CHANGELOG 预览

GitLab MR 创建

→ glab mr create --title "v <描述>" --description "<描述>" → 相同的格式规范 → 跨平台一致的用户体验

推送策略

→ git push origin （如果尚未推送） → PR 创建前确保远程是最新的 → 创建失败时的回退策略

PR Body 结构

→ ## Summary — 变更摘要 → ## Reviews — 审查状态 → ## CHANGELOG Preview — 预览 → ## Documentation — 文档更新（如有） → 后续 /document-release 可更新此结构

§8 /ship 与 /land-and-deploy 的分工

为什么是两个命令？

/ship = 创建 PR → 确保代码质量 → 准备合入 /land-and-deploy = 合并 PR → 等待部署 → 验证生产

分工逻辑

→ /ship 是"发布准备"——代码还在分支上 → /land-and-deploy 是"发布执行"——代码进入主分支 → 两者之间 = 人类审查者的窗口 → 这不是设计缺陷——是人类判断的预留空间

/land-and-deploy 也检查 ship 的工作

→ VERSION 漂移检测（自 ship 后可能有其他 PR 合入） → 审查新鲜度复查 → CI 状态确认 → 部署后 canary 验证

SPAWNED_SESSION 模式

→ 在 OpenClaw 中自动选择推荐选项 → 跳过交互式提示 → 仅输出完成报告

§9 结构拆解

ship 结构模板

核心特征

管理对象: 从分支到 PR 的完整发布准备流程
核心原则: 四层门禁确保每次合入都有审计追踪——VERSION 碰撞检测 + 审查就绪 + Greptile 分诊 + Fix-First 修复
关键设计: CHANGELOG 铁律（永不覆盖 + 面向用户措辞）+ gstack-next-version 自动碰撞解决 + 跨平台 PR 创建一致性

通用结构

平台检测层 (Step 0-1): GitHub/GitLab/原生 Git 检测 → 基准分支确定 → 分支存在性验证 → PR 存在性检测
质量门禁层 (Step 2.5-3.75): 审查状态读取 → 审查就绪门控 → Greptile 分诊（VALID/ALREADY FIXED/FALSE POSITIVE）
版本管理层 (Step 7-9): gstack-next-version 碰撞检测 → 自动 bump → VERSION 文件更新 → 所有引用同步
文档生成层 (Step 10-14): CHANGELOG 自动生成（release-summary + itemized changes）→ VERSION bump → PR 创建与推送
协同接口: /review（审查输入）→ /document-release（文档补全）→ /land-and-deploy（发布执行）

§9.5 电商 Skill 案例：电商APP版本发布上线全流程——从PR到生产

🛒 实战案例：某电商平台5个开发团队并行开发Q4大版本（v2.5.0.0），包含支付团队的分期付款功能、物流团队的顺丰API集成、营销团队的推荐算法2.0、基础架构的Node.js v22升级、前端团队的商品详情页重构。使用/ship管理从PR到发布的完整流程——版本碰撞检测+审查门禁+CHANGELOG自动生成+PR创建。

Step 0-1 平台检测与分支验证：检测平台GitHub→基准分支main→当前分支feat/payment-installment-v2.5.0.0存在且与远程同步。PR存在性检测——无现有PR→创建新PR。

Step 2.5-3 审查就绪门禁（四层门控）：读取gstack-review-log→发现2次审查记录（第1次/issues_found Quality 3.5→第2次/clean Quality 8.5）→门控检查：(1)至少一次审查完成✓；(2)最后一次审查clean✓；(3)Quality >= 7.0（封网期阈值）✓；(4)所有CRITICAL已修复✓→通过，继续。Greptile分诊——PR上有4条Greptile评论，经分诊后2条VALID(已修复)、1条FALSE POSITIVE(抑制)、1条DUPLICATE(跳过)。

版本碰撞检测：gstack-next-version扫描main上已有PR——发现物流团队同时申请v2.5.0.0（feat/logistics-shunfeng-v2.5.0.0）。碰撞检测→物流团队PR已在open状态5天未更新→/ship自动建议物流团队升级到v2.6.0.0或等待支付团队先合。支付团队确认当前版本v2.5.0.0可用（先合先得）。

CHANGELOG自动生成：git diff origin/main...HEAD --stat→23个文件变更(+1247/-312行)。分析commit历史(7个commit)→生成CHANGELOG条目——release-summary"v2.5.0.0: 分期付款功能上线，支持3/6/12期分期，微信支付+支付宝双通道"、itemized changes(3个功能+2个修复+1个breaking change)。Breaking change检测——订单数据库表新增installment_plan字段(NOT NULL DEFAULT 'NONE')，旧版本代码读取订单时不包含该字段→自动标记为BREAKING并添加迁移说明。

PR创建与后续：创建PR feat/payment-installment-v2.5.0.0→PR Body包含Release Summary+完整CHANGELOG+审查状态摘要(2次审查/clean/Quality 8.5)+部署建议(先staging验证后生产金丝雀5%→全量)。PR合入后→/land-and-deploy读取PR中的CHANGELOG作为部署说明→staging验证通过→生产金丝雀5%监控15分钟→全量→部署报告归档。阻塞项处理——物流团队的v2.5.0.0版本冲突→升级到v2.6.0.0后重新/ship→独立发布。

🔑 启示：/ship的价值不在"创建PR"这个GitHub操作——而在发布流程中的三个自动协调：版本碰撞检测（防止两个团队无声地抢同一个版本号）、审查就绪门禁（确保/ship读取到/review的审查结果并自动判断是否满足合入条件）、CHANGELOG铁律（永不覆盖+面向用户措辞，确保每个版本的变更可追溯）。多团队并行开发中最大的协调成本不是代码冲突——而是"不知道别人的发布计划"。ship让版本编排从Slack上的@channel喊话变为系统自动检测碰撞。

[!info] 参考来源发布流程管理参考了 GitHub merge queue 功能和 Shopify Shipit 的部署协调系统。CHANGELOG 规范参考了 Keep a Changelog 标准。

§10 掌握检验

Q1：/ship 的 VERSION 碰撞检测解决的核心问题是什么？

A) 两个开发者使用不同的代码风格
B) 两个 PR 同时 bump 到同一版本号，导致后合入的 PR 覆盖前者的 CHANGELOG
C) PR 标题太长
D) 推送远程分支时发生冲突

Q2：四种 bump 级别中，"minor"对应什么规模的变更？

A) X.Y.Z+1 —— 微小修复
B) X.Y.Z+1.0 —— 补丁版本
C) X.Y+1.0.0 —— 功能版本
D) X+1.0.0.0 —— 破坏性变更

Q3：/ship 的四层门禁中，为什么 Layer 2（审查就绪检查）被描述为"最容易被跳过的"？请从开发者心理学和团队协作两个角度分析，为什么人类倾向于跳过代码审查。

Q4：CHANGELOG "永不覆盖已有条目"是一个硬性约束。如果两个 PR 同时 bump VERSION 到 1.7.0.0，先合入的 PR 在 CHANGELOG 中已有条目，后合入的 PR 如何处理才不会覆盖？请描述完整的技术流程。

Q5：/ship（发布准备）和 /land-and-deploy（发布执行）之间存在"人类审查者的窗口"。这个窗口在紧急 hotfix 场景下是否仍然必要？请从安全性和速度权衡的角度，分析为什么 gstack 即使在紧急情况下也不建议跳过这个窗口。

Q6：CHANGELOG 自动生成从 git log 和 git diff --stat 中提取信息。但如果 commit message 写得很差（如 "fix"、"wip"、"update"），自动生成的 CHANGELOG 会变成什么样？这个场景暴露了什么更深层的工程实践问题？

§11 答案

点击查看答案

Q1：B —— VERSION 碰撞检测防止两个 PR 同时使用相同版本号。

Q2：C —— minor = X.Y+1.0.0，对应功能版本（新功能添加，向后兼容）。

Q3：开发者心理学——对自己的代码有"完美感"（"这段代码没问题"），审查被感知为"额外的、不必要的步骤"而非"保护机制"。团队协作——在快节奏团队中，等同事审查 PR 是瓶颈（审查者正在忙自己的事），跳过审查能立即获得"快速发布"的正反馈，但放弃了"代码质量"的延迟奖励。人类天然倾向于即时满足——这也是为什么 ship 把审查检查自动化——不让"人性弱点"决定代码质量。

Q4：①碰撞检测发现 1.7.0.0 已被占用；②自动 bump 到下一个可用 slot（如 1.7.1.0 micro bump）；③VERSION 文件更新为 1.7.1.0；④CHANGELOG 以 Edit 追加新 v1.7.1.0 条目到文件顶部（不修改已有 v1.7.0.0 条目）；⑤PR 标题更新为 v1.7.1.0 开头；⑥所有引用 VERSION 的文件同步更新。核心原则：Edit 追加（不覆盖），VERSION 隔离（不同号），标题溯源。

Q5：即使在 hotfix 中这个窗口仍然必要。安全性——hotfix 通常是在压力下写的，压力和速度是 bug 的催化剂。没有人类审查者验证 hotfix 的正确性就自动合入，可能"修了 A 但引入更严重的 B"。速度权衡——hotfix 的窗口可以"紧缩"（从正常审查的 1-2 天压缩到 1 小时），但不应该"消除"（跳过审查）。gstack 的设计哲学：/ship 可以加速但不能跳过——通过提供审查仪表盘、快速审查清单、和并行专家来压缩窗口的时间，但不建议消除窗口本身。如果真的有"3 分钟必须上线否则全站挂"的场景——这是基础设施和运维流程的问题，不应该是"跳过审查"的合理化理由。

Q6：自动生成的 CHANGELOG 质量会极差——"fix"不会被正确分类为哪些是 bug 修复、哪些是重构，"update"无法让下游用户理解变更的影响。这暴露了团队缺乏"代码变更可追溯性"的工程纪律——commit message 是代码变更的唯一人类可读的意图声明。如果 commit message 无法被自动工具正确解析，意味着：①6 个月后你回看 git log 也无法理解变更意图；②新人无法通过 git blame 理解代码演化的原因；③自动化 changelog/release-note 工具完全失效。解决方案不是"手动写好的 changelog"，而是"从写好 commit message 开始"——这是更根本的工程实践。

（5/6 通过）