SuperAPI AI 工具集

ship-workflow-ship

部署与运维

查看项目

更新于 10-16 10:20

技能介绍

Ship — 发布与交付是 zeroz-lab/unified-skills 中的一个发布上线工作流技能,入口是通过 review 的代码或产物,出口是 docs/features/<name>/05-ship.md 与 docs/features/<name>/README.md(聚合 README + 事后总结),完成后可选进入 reflect-team-retro,输出路径指向 ship-workflow-land。前置加载 CANN.md + verify-workflow-review/SKILL.md。

何时不使用:纯配置变更(环境变量、DNS)可在监控下直接变更;功能尚未通过 review 必须先完成审查;依赖尚未就绪(数据库 migration 未审批、第三方服务未配置)时不适用。

Phase A 预发检查:先读取 spec 的 artifact_type。software(默认)加载 ship-infrastructure-deploy,按其 Pre-Launch 检查表逐项执行代码质量、安全、性能、基础设施和文档验证;document / article / deck / visual 加载 ship-artifact-export,执行导出、预览、归档和交付检查。验证命令(必须运行):npm test && npm run build && npm run lint && npx tsc --noEmit。

Phase B 质量门(Ship Audit Army 发布审计军团):预发检查通过后,按产物类型并行分派相应 auditor 做发布前专项审计,包括 ship-security-auditor(OWASP、输入边界、认证授权、数据暴露、依赖)、ship-performance-auditor(关键路径、N+1 查询、内存资源、Bundle 影响、退化)、ship-accessibility-auditor(WCAG 合规、屏幕阅读器、表单错误、动态内容)、ship-docs-auditor(CHANGELOG、README、迁移指南、API 文档、错误信息)、ship-artifact-export-auditor(非 software 导出 QA:source/final 对齐、格式、归档、交付包验证)。每个 auditor 输出 Blocking / Important / Suggestion 三级反馈:Blocking 必须解决才能上线;Important 强烈必须修复,不修复需在 ship 报告记录风险接受理由;Suggestion 自主判断,采纳后标注来源。

最少触发条件:小型变更(单文件、无安全/UI 敏感)可跳过 Audit Army;software 标准变更至少 security + docs 双审计;非 software 标准变更至少 artifact-export + docs 双审计;有 UI 变更加 accessibility;有性能敏感变更(数据处理、查询、前端 bundle)加 performance;用户指定 --full 当前产物类型相关角色全开。高风险变更也可加载专项审查技能 verify-quality-security、verify-quality-performance、verify-frontend-accessibility(向后兼容保留)。

Phase B.5 Staging 验证(仅 software 强制):部署到 staging 环境;在 staging 数据上运行完整测试套件 npm test;手动冒烟测试关键路径(用户注册、登录、核心流程);验证与下游依赖的集成(API mock 关闭,真实调用);确认数据 migration 向前兼容;确认回滚脚本可用。staging 不完全等于不上线,所有 software 验证必须全部绿色才能进入 Go/No-Go。非 software 产物在这一阶段改为执行最终交付包验证:打开 final 文件或预览;检查 source / final / review / ship 记录是否能互相追踪;核对文件名、格式、路径、版本说明;标记 human partner / CI 的最终打开验证结果。

Phase C Go/No-Go 决策:文档化阻塞项(无未解决的 Critical 问题)、已知风险、回滚计划(强制)。回滚计划模板包含触发条件(如错误率 > 2x 基准、P95 延迟 > [X]ms)、回滚步骤(禁用 feature flag 或 git revert <commit> && git push、验证回滚、沟通团队)、数据库执行(Migration 有 rollback、新功能插入数据保留/清理)、回滚时间(Feature flag < 1 分钟、重部署前一版本 < 5 分钟、DB rollback < 15 分钟)。

Phase D 文档聚合:自动生成 docs/features/<name>/README.md,包含 Feature Summary、Document Index(00-brainstorm.md 到 07-deploy-report.md 的阶段证据状态)、Timeline、Key Decisions、Delivery Outcome、Verification Evidence、Residual Risks、Follow-up Actions、Retro Notes,并检查记录 Documentation Sync(Updated project docs、Deferred project docs、CHANGELOG.md updated、README verified 及其他必须同步的项目级文档状态)。

Phase E 发布后闭环(推荐):发布完成后执行 ship-workflow-canary(金丝雀监控,curl 关键端点比对基线)、ship-workflow-land(合并 PR、等 CI、验证生产环境)、ship-workflow-doc-sync(交叉引用变更,同步更新过时文档)。分阶段上线策略、Feature Flag 生命周期和推进/回滚阈值详见 ship-infrastructure-deploy。

输出模板起点为 templates/feature/05-ship.md 与 templates/feature/README.md(聚合 README),Ship Report 包含基本信息、Delivery Scope、Review Carryover、Pre-ship Evidence、Ship Audit Results、Final Verification、Go/No-Go Decision、Rollback / Recovery Plan、Documentation Sync、Post-ship Monitoring、Handoff / Archive 等章节。聚合 README 必须使用 templates/feature/README.md,并至少保留 Feature Summary、Document Index、Timeline、Key Decisions、Delivery Outcome、Verification Evidence、Residual Risks、Follow-up Actions、Retro Notes。

监控与可观测性:应用级指标包括错误率(总数 + 按端点)、响应时间(p50 / p95 / p99)、请求量、活跃用户、关键业务指标(转化率、参与度)。上线后 1 小时内:健康检查 200、错误监控仪表盘(无新错误类型)、延迟仪表盘(无回归)、手动测试关键用户流程、确认日志正常流动、确认回滚机制就绪。

验证失败处理:Staging 测试失败为阻塞,修复后重新部署 staging,不可跳过直接上线;Go/No-Go 被否决回到对应阶段修复(review / build),重新走预发检查;上线后错误率飙升立即回滚(禁用 feature flag 或 revert),不“观察一下”;Feature flag 未就绪为阻塞,不上线,需在 staging 验证 flag 开关功能正常;DB migration 向前不兼容为阻塞,修复使其向前兼容,或拆分为两阶段部署;回滚计划不完整为阻塞,必须补全触发条件和步骤后才可上线。

验证证据要求输出或记录必须包含:输入/来源(读取的 spec、plan、代码、反馈或发布上下文)、执行动作(实际完成的检查、生成、修复、导出或发布步骤)、验证结果(命令、审查结论、产物路径、截图或人工确认)、阻塞/回退(未通过项、回退路径或需要 human partner 决策的问题)。

红旗包括:没有回滚计划就部署;没有监控或错误报告就上线;大爆炸式发布(一次性全量,没有 staging);Feature flag 没有 owner 或过期时间;上线后第一小时无人监控;生产环境配置靠记忆而不是代码;“周五下午了,发了吧”。

上线前验证清单:预发检查清单完成(全部绿色);Delivery Scope 已写清交付物、目标环境和不做范围;Review Carryover 已带入 04-review.md verdict、条件和残余风险;Pre-ship Evidence 已记录命令、路径、结果和 owner;Go/No-Go Decision 已记录 criterion、evidence、owner 和时间;Feature flag 已配置(如适用);Rollback / Recovery Plan 已文档化,包含触发条件、步骤、数据处理和 owner;Documentation Sync 已完成;Post-ship Monitoring 已写清观察窗口、指标、阈值和 owner;Handoff / Archive 已写清最终路径和下一命令;聚合 README 已覆盖 00-brainstorm.md 到 07-deploy-report.md 的证据状态;聚合 README 已写清剩余风险、后续动作、owner 和 tracking;团队已通知上线。上线后:健康检查 200、错误率正常、延迟正常、关键用户流程工作、日志正常流动。