06_gstack发布运营：一键发布与文档同步机制
06_gstack发布运营：一键发布与文档同步机制
关键字：gstack、一键发布、ship技能、document-release、文档同步、发布流水线、CHANGELOG、PR自动化、retro、工程回顾
你上一次修改完代码到实际提交 PR，中间经历了多少步？
git stash，rebase main，处理冲突，运行测试，等 CI，写 PR 描述，贴上测试截图，通知 reviewer，顺便更新一下 README……
每一步都不难，但放在一起，这个流程很容易让工程师在"写完代码"和"代码进 main"之间消耗掉半小时到一小时。
更隐性的成本是：文档。多少工程师发完 PR 之后，CHANGELOG 还是上个版本的，README 里的接口说明还是旧的，CONTRIBUTING.md 里的架构图还对应着三个月前的代码？
gstack 的发布运营层，把这些碎片化的工作统一成两个指令：/ship和/document-release。
一、/ship：完整的发布流水线
/ship不是简单的git push，它是一个编排了所有发布前置工作的完整流水线：
/ship 执行序列（完全无人值守）： 步骤 1: 同步代码库 +-----------------------------------------------+ | git fetch origin | | git rebase origin/main | | 如果有冲突 --> 暂停，提示工程师手动解决 | +-----------------------------------------------+ | v 步骤 2: 运行测试套件 +-----------------------------------------------+ | npm test（或 bun test/pytest/cargo test） | | | | 输出： | | Tests: 42 → 51 (+9 新测试通过) | | Coverage: 14/14 代码路径（100%） | | | | 如果测试失败 --> 停止流程，报告失败原因 | +-----------------------------------------------+ | v 步骤 3: 解决 Greptile 代码审查 +-----------------------------------------------+ | 读取当前 PR 的 Greptile 评论 | | 逐条处理： | | 有效问题 --> 已在之前的 /review 中修复 | | --> 回复"已修复，见 commit xxx" | | 误报 --> 解释为什么不是问题 | | 疑问 --> 如果能确认则回复，否则标注待定 | +-----------------------------------------------+ | v 步骤 4: 推送代码 +-----------------------------------------------+ | git push origin feature/xxx | +-----------------------------------------------+ | v 步骤 5: 创建/更新 PR +-----------------------------------------------+ | 自动生成 PR 描述： | | | | ## Changes | | - 实现 CSV 导出功能（最多10万行） | | - 添加时间范围过滤 | | - 修复超时无提示的问题 | | | | ## Test Coverage | | - 新增 9 个测试用例 | | - 覆盖 7 个功能路径 | | - 端到端测试：桌面/移动/慢网络全部通过 | | | | ## Screenshots | | [自动附上 /qa 截图] | +-----------------------------------------------+ | v 步骤 6: 调用 /document-release +-----------------------------------------------+ | 同步受影响的文档文件 | | (详见下文) | +-----------------------------------------------+ | v 输出： PR URL: github.com/you/app/pull/42 分支：feature/export-csv 测试：51/51 通过 覆盖率：100% (14/14 路径)整个过程不需要工程师干预，除非出现冲突或测试失败。工程师的工作变成了：看一眼 PR，点击 Merge。
二、/document-release：解决文档欠债问题
文档落后于代码，是几乎所有工程团队的通病。原因很简单：改代码有明确的需求驱动，改文档没有。
/document-release的设计把文档更新变成了代码发布的强制附属步骤：
2.1 工作原理
/document-release 的处理流程： 输入：当前 PR 的代码 diff（21个变更文件） | v 扫描所有文档文件： README.md CHANGELOG.md CLAUDE.md CONTRIBUTING.md TODOS.md docs/api-reference.md docs/architecture.md ...（共扫描 15 个文档文件） | v 交叉引用：代码变更 vs 文档内容 对每个文档文件： - 文档里描述了哪些功能/接口/架构？ - 这次代码变更是否影响了这些描述？ - 如果影响了，哪些地方需要更新？ | v 识别需要更新的文件：8 个 （另外 7 个文件未受本次变更影响） | v 执行更新：2.2 具体更新内容
README.md 更新： 旧：支持功能：用户管理 | 数据看板 新：支持功能：用户管理 | 数据看板 | 数据导出（CSV） CHANGELOG.md 更新（关键：语气优化）： AI 原始生成的 CHANGELOG（不采用）： "Enhanced the platform by implementing CSV data export functionality with configurable parameters including temporal filtering capabilities and volumetric constraints." /document-release 优化后的 CHANGELOG： "新增数据导出功能：支持 CSV 格式，可按时间范围筛选， 单次最多导出 10 万条记录。超出时自动截断并提示。" CLAUDE.md 更新： - 项目结构新增 src/export/ 目录说明 - 新增 export_jobs 数据表说明 - 更新相关环境变量列表 TODOS.md 更新： 已完成项目标为 [x]： [x] CSV 导出基础功能 [x] 时间范围过滤 [ ] Excel/JSON 多格式支持（下个sprint） [ ] 定时导出任务（规划中） docs/api-reference.md 更新： 新增 POST /api/export 接口文档 包含：请求参数/响应格式/错误码说明 ...（共更新 8 个文件）2.3 PR 正文自动更新
文档更新完成后，/document-release会把文档变更摘要附加到 PR 正文：
## Documentation Changes Updated 8 documentation files: - **README.md**: 添加导出功能到功能列表 - **CHANGELOG.md**: 记录本次发布内容 - **CLAUDE.md**: 更新项目结构说明 - **TODOS.md**: 标记完成项，保留后续计划 - **docs/api-reference.md**: 添加导出 API 文档 - [...] Full diff: [查看文档变更]Code reviewer 在审查 PR 时，能同时看到代码变更和文档变更，确认两者是否对齐。
三、CHANGELOG 的语气问题
这是一个看似细节、实际上影响团队形象的问题。
大量使用 AI 辅助开发的团队，CHANGELOG 普遍有一个特征：读起来像翻译腔，充满了"Implemented comprehensive solution for…"、"Enhanced the functionality by…"之类的空话。
这种语气的问题不是"不准确"，而是让读者感觉这个 CHANGELOG 不是人写的——因为确实不是人写的。
gstack 的/document-release专门针对这个问题做了优化：
检测模式（会被替换）： "Implemented X functionality" "Enhanced Y by Z" "Resolved issues related to..." "Comprehensive solution for..." "Leveraging advanced algorithms to..." 替换为人类写法： "新增 X 功能" "修复 Y 问题" "优化 Z 性能" "支持 W 场景"这个细节在团队规模小的时候不重要，但当代码库有外部贡献者、有开源用户，或者需要给非技术 stakeholder 看 CHANGELOG 的时候，语气一致性就变成了信任成本的一部分。
四、/retro：数据驱动的工程回顾
传统的 sprint 回顾是定性的：大家说说这周哪里好、哪里不好、下周改什么。
这种方式的问题是：记忆会筛选信息。印象深刻的问题会被过度强调，重要但不显眼的趋势会被忽视。
/retro从代码库数据出发，提供客观的工程视角：
/retro --period 2026-03-01:2026-03-28 === 工程回顾报告 === 1. 贡献者分析 贡献者 提交数 行数变更 Bug修复 新功能 Alice 47 +8,234 12 23 Bob 31 +5,102 8 18 Carol 22 +3,876 15 5 注意：Carol 的 bug 修复比例（68%）明显高于团队平均（37%）， 可能需要关注负责的代码区域是否存在系统性问题。 2. 代码质量趋势 测试覆盖率： 03月01日 62% -------- 03月07日 68% ----------- 03月14日 71% ------------ 03月21日 75% --------------- 03月28日 79% ---------------- <-- 持续改善 PR 合并周期（平均）： 03月01日 2.3天 03月14日 1.8天 03月28日 1.1天 <-- 流程在提速 3. 技术债趋势 新增 TODO/FIXME 注释：+23 清理 TODO/FIXME 注释：-8 净增：+15（需要关注） 4. 识别的模式 [关注] 数据层集中了 41% 的 bug 修复，建议专项重构 [好转] CI 失败率从 18% 下降到 6% [新增] 引入了 3 个新的外部依赖，需要安全审查 5. 下周建议 优先级1：偿还数据层技术债（建议分配 2 天） 优先级2：Carol 的工作方向调整（讨论） 优先级3：安全审查新增依赖这种回顾有两个好处：一是客观，数字不会说谎；二是具体，"数据层集中了 41% 的 bug"比"感觉代码质量有点问题"更容易推动行动。
五、发布运营层的最佳实践
使用时序
功能开发完成，通过 /review 和 /qa 后： 1. 调用 /ship (完全无人值守，约5-8分钟) | v 2. 检查 PR 重点关注： - 测试报告是否全绿？ - 文档更新是否准确？ - Greptile 的 [ASK] 问题有没有处理？ | v 3. 请求 reviewer 审批 | v 4. Merge PR 整个过程工程师主动花的时间：< 5分钟发布后
每个 sprint 结束（或每周一次）： 1. /retro --period <起始日期>:<结束日期> 获取数据驱动的回顾报告 | v 2. 团队讨论报告里的关键发现 重点：趋势性问题 > 点状问题 | v 3. 制定下周的技术债偿还优先级六、一个容易被忽视的价值
/ship和/document-release带来的最大价值，不是"节省时间"——尽管它确实节省了时间。
最大价值是：让发布这件事变得不再有心理负担。
很多工程师不自觉地"囤积"改动——攒了几个小功能才发一次 PR，因为每次发 PR 都要经历繁琐的发布流程。这种行为会让每次合并的改动量变大，review 难度增加，出问题的风险也随之增加。
当发布的边际成本变得接近于零，工程师自然会倾向于更频繁地发布小改动。更小的批次，更快的反馈循环，更低的回滚风险——这才是频繁发布的真正价值所在。
下一篇我们进入 gstack 并行开发的核心：Git Worktrees 怎么配合 Conductor 工具实现"一个工程师跑 10-15 个并行 sprint"，以及 Garry Tan 每天早上的工作流是什么样的。
系列文章：本文是 gstack 深度解析系列第 06 篇，共 10 篇。
参考资料：gstack ship Skill 源码、document-release 实现逻辑