workflow-ship-change

工作流：交付一项更改

只有满足以下所有条件，并且报告逐项展示这些条件时，这项更改才算完成：

1. 真实运行的游戏截图：初始状态、关键时刻和结果。截图需内嵌在报告中。
2. 单独的变更日志版本，并且配有图片，显示在游戏内的变更日志页面上。
3. 已验证：
   • 你自己的测试；
   • 你合并进来的提交所包含的测试；
   • 资源检查；
   • 在已推送的提交上运行的完整测试套件。
4. 已提交：一个内容连贯的提交，暂存的文件仅包含你自己的文件。
5. 已推送至 main，采用快进方式，并已在 GitHub 上确认。
6. 已上线：已发布该确切 main 版本的构建，并确认其在真实域名上正常运行。
7. 已测量：已测量提交、推送、任何上传和发布的大小，绝不估算。

推送和发布是对项目自有仓库和线上站点的常规授权。因此，除非以下护栏要求停止，否则无需事先询问。开始前请阅读项目的 AGENTS.md，如果有的话，也请阅读此技能的 references/<project>.md。项目规则经常变动；若与此技能不同，以项目规则为准。

护栏：停止并询问用户

• 任何超过 50 MB 的上传。 包括 git push、Netlify 部署、媒体发布，以及发送到任何外部服务的文件。
  • 先测量（使用 upload-size.sh，或使用 push-main.sh 显示的 pack 大小），然后在询问时说明大小。
  • 统计整个操作的大小，绝不能拆分操作以低于此限制。
  • 完整的 Supabase 媒体发布（约 861 MiB）始终需要先询问。
• 强制推送、改写远程历史记录、更改仓库可见性，或推送到其他仓库。
• 新建站点或项目，或更改站点的访问权限、域名或 DNS，除非任务本身正是这些操作且用户已提出要求。
• 权限检查阻止部署、回滚或上传时：停止。不要换一种方式或通过另一个会话重试。告知用户具体的点击路径或命令。
• 发布后线上故障：在报告中首先说明，并提供实测证据和回滚的点击路径。不要把它埋在报告里。

护栏：绝不可

• 绝不可发布未经清理且已推送的 origin/main 以外的内容。不得发布未合并的分支或未提交的文件。
• 绝不可将大型媒体作为备用方案部署到 Netlify；媒体应存储在 Supabase Storage。
• 绝不可发布到项目已弃用的主机，即使旧脚本仍指向该主机。
• 绝不可运行宽泛的图像优化器（pnpm images:optimize 或 optimize-images.py --apply）。它会改写其他会话尚未提交的图片。请使用 runtime-assets.py --only '<your glob>'，然后使用 --verify。
• 绝不可暂存凭据、.env*、node_modules、缓存或构建产物；在共享检出目录中绝不可使用 git add -A。
• 未在远程仓库或域名上确认前，绝不可声称本地提交已推送或部署已上线。
• 绝不可终止你未启动的进程。先检查其工作目录：lsof -a -p <pid> -d cwd。

步骤

0. 开始之前

• 运行 git fetch，然后运行 git log origin/main --oneline -30，并搜索你负责的区域。查看其他工作树（git -C <wt> diff --stat），确认是否有人正在进行相同的修改。
• 在基于 origin/main 的分支上使用你自己的工作树。其他会话会实时修改共享检出目录。

1. 截图

• 使用项目的评审夹具（?review=<name>），以 1600×900 分辨率截取真实游戏画面。拍摄初始状态、关键时刻和结果。
• 如果项目指定了截图工具，请使用该工具。否则通过 CDP 进行无头截图（参见 workflow-progress-screenshots 技能），并说明使用了哪种方式。
• 使用每张图片前都要检查。若出现意外的提示消息、过时的数字或错误的场景，必须重新截图。
• 如实标注：无头浏览器截图不能算作设备测试；手机尺寸的视口也不能算作设备测试。
• 将截图脚本保存在工作树中被 Git 忽略的 qa/captures/ 目录下；会话临时目录会在重启时清空。

2. 更新日志版本

• 严格遵循项目的更新日志规则：格式、版本编号方式以及添加图片的方式。
• 面向玩家撰写：说明他们现在能看到或做什么，不要包含文件名或哈希值。
• 测试、工具、文档或规则方面的更改不分配版本号。
• 如果另一个会话用了你的版本号，合并时请重新编号，并保留对方的条目。

3. 验证

• 随着开发推进，运行受更改影响的测试套件。
• 合并 main 后，还要运行传入提交所涉及的每个测试文件：git diff --name-only <old-base> <new-base> -- tests。
• 如果提交了图片，运行图片验证。
• 在负载较高的机器上，完整测试套件需要 10–40 分钟。使用 run_in_background 运行，并查看日志。对于看起来像超时的失败，单独重跑后再判断是否确实失败。
• 如实报告哪些运行是完整测试、哪些是针对性测试，并列出通过和失败的数量。

4. 提交

• 开始前，git diff --cached 必须为空。
• 仅暂存明确指定的路径。
• 对暂存的更改运行 commit-size.sh；在报告中列出其统计数据。
• 每项完整的更改单独提交一次。仍在迭代时，请修改同一个进行中的提交，而不是不断堆叠小提交。
• 按仓库的风格撰写提交说明，并以系统提供的署名行结尾。

5. 合并并推送

1. 运行 git fetch，然后执行 git rebase origin/main（如果是共享分支，则合并）。

2. 解决冲突时保留所有人的更改。对于生成的 JSON（图片审计、清单），采用上游文件，重新添加你自己的记录，并使用项目工具重新计算总数。

3. 对每个 src 和 tests 文件运行 node --check。然后运行你的测试以及传入提交涉及的测试。

4. push-main.sh：

   • 如果不是快进更新，就会拒绝推送；
   • 会测量 pack 大小，超过 50 MB 就停止；
   • 会使用 --progress 推送，并输出 Git 的 "Writing objects" 行（即发送的字节数）；
   • 会确认 origin/main 与 HEAD 相同。

   如果 main 已有新提交，返回第 1 步。

5. 在已推送的提交上运行完整测试套件；如果出现问题，向前修复。

6. 正式发布

• 在 HEAD 与 origin/main 完全一致且跟踪文件干净的检出目录中构建。
• 如果构建更改了跟踪文件，先提交并推送该文件，然后重新构建。
• 测量将要上传的内容（upload-size.sh dist，以及任何媒体发布内容）。如果超过 50 MB，请停止并询问。
• 先部署到草稿或预览 URL。 运行 verify-live.sh <draft-url>：检查页面、脚本、美术资源以及 gate 路由。只有验证通过后才能发布到正式环境。此步骤是为避免再次发生正式部署遗漏边缘函数的情况：网站页面可以正常打开，但所有图片都返回 404，导致无人能玩。
• 发布后，在正式域名上运行 verify-live.sh。记录部署 ID、发布时间、线上游戏版本以及发送的字节数。
• 如果另一个会话在你之后发布了，只要它也发布了 main，就没问题。

报告

简短，并按以下顺序：

1. 提交哈希，已推送并确认。提交大小：文件数、总大小、最大文件。推送大小：发送的字节数。
2. 线上信息：URL、部署 ID、时间、线上版本以及 verify-live.sh 的结果。上传大小：发送的字节数、构建产物大小以及任何媒体发布内容。如果未发布，请说明原因（例如“暂缓：需要超过 50 MB 的媒体发布内容；正在询问”）。
3. 面向玩家说明更改内容，以及更新日志版本和标题。
4. 测试：说明哪些运行是完整测试、哪些是针对性测试，并列出通过和失败的数量。
5. 附带说明文字的截图，并标注为无头模式采集。
6. 说明任何延期事项或偏离之处，以及原因。