模板库线上对齐仓库源：递增版本重发并把说明文档纳入发布

- 7 个内容已变的模板 templateVersion 升到 0.1.1，blank-2d-canvas 与 blank-web 保持 0.1.0 - 发布脚本把仓库 README.md 覆盖写到 templates/README.md（上限 64 KiB，写在清单之前并回读校验），线上说明文档不再是手工副本 - 修复守卫拒绝时直接 process.exit(1) 触发 libuv 断言崩溃、看不到拒绝原因的问题 - 新增发布用例：说明文档随发布覆盖写且写在清单之前、源目录没有 README 时不写线上文档 - 模板库新增仓库侧 README.md 源文件（发布后与线上逐字节一致） - 技术方案补说明文档契约与 2026-09-21 重发布记录；决策记录与踩坑记录各补一条 - 验证：node --test 27 项、真实发布 28 个对象回读通过、线上清单与 README 核对一致、AGC 壳 3 项线上用例重跑通过、check:doc-index、check:encoding、eslint、git diff --check
2026-09-21 14:51:39 +08:00
parent 19ed1776f1
commit f4ebc45612
13 changed files with 128 additions and 27 deletions
@@ -1,5 +1,14 @@
 # 决策记录

+## 2026-09-21 模板库线上产物对齐仓库源：递增版本重发 + 说明文档纳入发布
+
+- 背景：`agc-dev` 上的 `templates/` 产物停在 2026-09-17 发布的那一版，仓库源在那之后改过（`5e4ff54a9` 删掉模板内嵌 `package-lock.json`、`game.js` / `main.js` 等内容调整），9 个模板里 7 个的 ZIP 与线上不一致；dry-run 被「同一 `templateVersion` 的 ZIP 不得变」门禁拒绝，发布器因此无法把仓库状态发上去。
+- 决策：按门禁要求为内容已变的 7 个模板递增 `templateVersion` 到 `0.1.1`（`blank-2d-canvas`、`blank-web` 内容未变，保持 `0.1.0`），并完成一次真实发布；对象使用内容寻址键 `v1/<id>/sha256/<摘要>/…`，`index.json` 与说明文档在发布锁内最后提交，历史对象不删除。
+- 决策（说明文档）：`templates/README.md` 不再是手工副本——它由发布脚本从仓库源 `apps/ai-game-creator-shell/template-library/README.md`（≤64 KiB）覆盖写入并回读校验，写在清单之前；改契约只改仓库源。
+- 决策（CLI 行为）：发布器遇到门禁拒绝时用 `process.exitCode = 1` 正常退出，不再 `process.exit(1)` 让 Node 在 fetch 句柄未关闭时抛 libuv 断言（此前现场只剩 `Assertion failed`，看不到拒绝原因）。
+- 影响范围：`apps/ai-game-creator-shell/template-library/v1/*/meta.json`、`apps/ai-game-creator-shell/template-library/README.md`、`scripts/agc-template-library-publish.mjs` 与其测试、本文件与模板库技术方案。
+- 验证方式：`node --test scripts/agc-template-library-publish.test.mjs`（27 项，含新增「说明文档随发布覆盖写且写在清单之前」「源目录没有 README 时不写线上文档」）；真实发布 28 个对象回读通过；匿名读取线上清单（9 个模板、7 个 `0.1.1`、全部内容寻址键）与 `templates/README.md`（与仓库源逐字节一致）；AGC 壳 3 项线上用例（读清单、下载安装、下载并原生建项 Cocos）重跑通过。
+
 ## 2026-09-21 macOS 发布改为只出 arm64 单架构（Intel 暂不支持）

 - 背景：Mac 发布管线按 `universal-apple-darwin` 构建，但随包 Node 便携运行时只有**单架构官方发行版**（`stage-node-runtime.mjs` 从 `process.execPath` 取材），于是 macOS Job #7~#13 连续失败在「Node 运行时不支持发布目标：universal-apple-darwin」。期间出现过一版「按宿主架构放行」的过渡实现，它能骗过通用包自检（`check-macos-bundle.mjs` 按 `process.arch` 校验），但 Intel 上那份 arm64 侧车不可执行，并且已发布的 dev-mac 0.1.86 就带着这个缺陷。
@@ -1,5 +1,13 @@
 # 踩坑与排障记录

+## 发布器守卫拒绝时不要把 process.exit 用在 fetch 句柄未关闭处
+
+- 现象：`agc-template-library-publish.mjs --dry-run` 撞上「同一 `templateVersion` 的 ZIP 不得变」门禁时，终端只剩一句 `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c`，看不到任何拒绝原因，看起来像脚本崩溃而不是被拒绝。
+- 原因：`main().catch(...)` 里直接 `process.exit(1)`；此时 dry-run 刚用 fetch 读过公共清单，句柄仍在关闭流程中，Node/libuv 在 Windows 上先抛断言，把真实错误信息挤掉。
+- 处理：`catch` 里只设 `process.exitCode = 1`，让事件循环自然退出；同批把说明文档纳入受管发布（见决策记录 2026-09-21 条目）。
+- 验证：把模板源复制到临时目录、把某个模板的 `templateVersion` 改回与线上同版本并改动一个字节，`--dry-run` 应打印 `同版本 ZIP 内容或尺寸变化，请递增 templateVersion` 且退出码为 1，不再出现 `Assertion failed`。
+- 关联：`scripts/agc-template-library-publish.mjs`。
+
 ## macOS 只出 arm64 单架构，universal 必须失败关闭

 `stage-node-runtime.mjs` 只把**构建宿主的 Node**打成便携运行时（官方发行版是单架构，没有 universal 发行版），而 2026-09-21 之前 `build-macos-ci.mjs` 构建的是 `universal-apple-darwin`：macOS Job #7~#13 因此在 `stageNodeRuntime` 直接抛「Node 运行时不支持发布目标：universal-apple-darwin」。期间出现过一版「按宿主架构放行」的过渡实现（`targetRuntime` 对 universal 返回宿主架构），它能骗过通用包自检（`check-macos-bundle.mjs` 按 `process.arch` 校验），但**Intel Mac 上这份 arm64 侧车不可执行**，等于把坏包发出去。当前决策：macOS 固定只构建 `aarch64-apple-darwin`，清单只登记 `darwin-aarch64`，`targetRuntime('universal-apple-darwin')` 保持失败关闭。恢复 Intel 的正确路径是先在 staging 支持按架构各带一份**同版本**运行时（另下载另一架构官方发行版）并让通用包自检按架构分别校验，再切回 universal 目标、把 `darwin-x86_64` 键登记回去；不得用「只带宿主架构」充数，也不得把 arm64 产物登记成 x86_64 键。