按第五轮评审收尾 M3：跨平台用例、--no-bundle 与并发口径对齐

- package_layout 的 source_candidates 用例改用 Path 构造期望值（Windows 上 path.join 产出反斜杠，硬编码正斜杠会让该用例在 Windows 必红） - 运维文档与技术方案改为「--no-bundle 也执行 staging、只跳过总号发布」；M1 验收行里已删除的 AGC_SKIP_RESOURCE_STAGING 表述同步 - 技术方案 §4.3 第 8 条与风险表的并发口径改为「不做并发支持：失败可读、保留已生成 staging，需要并发时外部串行化」，与实现一致 - 评审结论（Windows 真机）：touch build.rs 后 resources 90 个文件 path/size/mtime 零变化；第二次 cargo build 1.13s fresh；三分支产物齐备；幂等、内容变更触发重建、fail-closed 均通过
2026-09-28 12:38:45 +08:00
parent ceca4a7669
commit c22eb38962
4 changed files with 24 additions and 11 deletions
@@ -767,13 +767,26 @@ mod tests {
        .iter()
        .map(|path| path.to_string_lossy().to_string())
        .collect::<Vec<_>>();
+        // 期望值必须用 Path 构造：Windows 上 path.join 产出反斜杠，硬编码正斜杠会让该用例在 Windows 必红。
+        let expected = |root: &str, nested: bool| {
+            let base = Path::new(root).join("node_modules/@openai");
+            if nested {
+                base.join(
+                    "codex/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin",
+                )
+            } else {
+                base.join("codex-darwin-arm64/vendor/aarch64-apple-darwin")
+            }
+            .to_string_lossy()
+            .to_string()
+        };
        assert_eq!(
            rendered,
            [
-                "/app/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin",
-                "/app/node_modules/@openai/codex/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin",
-                "/repo/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin",
-                "/repo/node_modules/@openai/codex/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin",
+                expected("/app", false),
+                expected("/app", true),
+                expected("/repo", false),
+                expected("/repo", true),
            ]
        );
        assert!(codex_source_candidates(
@@ -3,7 +3,7 @@
 | 字段        | 值                                                              |
 | ----------- | --------------------------------------------------------------- |
 | Version     | 1.0                                                              |
-| Status      | in-progress（2026-09-27 实现完成，待 Windows 真机验收）           |
+| Status      | in-progress（2026-09-28 已过 Windows 真机核心评审，剩打包一致性与客户端加载两项待验收） |
 | Date        | 2026-09-26                                                       |
 | Parent Spec | `docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md` |

@@ -101,7 +101,7 @@ build script 只写 `OUT_DIR`/`target`；随包资源是它的输入。凡需要
 5. **清理语义**：准备步骤负责删除本轮布局不再产出的残留（否则旧组件会继续被打包），删除范围限于自己的 staging 目录，不得触碰受版本控制的文件（例如 `resources/codex/win-x64/NOTICE.md`）。
 6. **失败语义**：上游缺失、integrity 不匹配、目标平台不支持、外部工具链缺失 → 立即失败并给出可执行提示；不允许「跳过生成、继续打包」。
 7. **可观测**：输出一行汇总（命中缓存 / 重新生成 / 跳过原因），供本地与 CI 排障。
-8. **并发安全**：同一 staging 目录的并发调用必须串行化或幂等收敛（dev 与 IDE 各自触发时不能互相破坏）。
+8. **并发**：不做并发支持（无实际场景）。同一 staging 目录的并发调用未加锁，会以可读错误失败并保留已生成的 staging 目录；需要并发时由调用方外部串行化。

 ### 4.4 build.rs 退化后的职责

@@ -135,7 +135,7 @@ build script 只写 `OUT_DIR`/`target`；随包资源是它的输入。凡需要
 | Windows 发布 | `build-release.mjs`（`runTauriBuild`，现有 `stageRuntime(target)` 紧邻 spawn tauri） | 只有 Node 运行时走准备步骤 | 同一挂点串上全部 staging |
 | macOS 发布 | `build-macos-ci.mjs`（复用 `runTauriBuild`）→ `check-macos-bundle.mjs` | 同上 | 同上 |
 | 本机 Rust 门禁 | `ai-game-creator-shell:check:rust:shell`（Windows 上 `cargo test --no-run` 会跑 build script） | 依赖 build script 生成资源 | 校验器在该场景必须能只读通过；需要真实资源的用例沿用既有 fixture，不得依赖本机 staging 产物 |
-| `tauri build --no-bundle` | `build-release.mjs` 的 no-bundle 分支（当前跳过 `stageRuntime`） | 不生成 Node 运行时 | 保持「不打包就不强制 staging」的口径，但校验器要按「未打包」放行 |
+| `tauri build --no-bundle` | `build-release.mjs` 的 no-bundle 分支（当前跳过 `stageRuntime`） | 不生成 Node 运行时 | 改为：`--no-bundle` 也执行 staging（app 构建本身需要随包资源），只跳过总号发布；校验器在资源缺失时仍然 fail closed |
 | CI（Linux） | `.gitea/workflows/project-ci.yml` 的 AGC 分组 | 五条 staging 全为 no-op | 不需要新增准备步骤；分片与 smoke 命令不变 |

 ### 4.7 与现有机制的关系
@@ -199,7 +199,7 @@ M2 之后构建脚本只做只读校验；M3 之后它也不再生成任何随
 | 忘记调用准备步骤（dev 或某个发布入口） | 资源缺失，打包或启动失败 | 校验器 fail closed + 入口测试断言「spawn tauri 前已调用准备步骤」 |
 | staging 缓存 key 不覆盖上游变化 | 静默发旧二进制 | key 含 lockfile `resolved`+`integrity`+布局版本+三元；manifest 校验作为第二道闸 |
 | 外部工具链步骤（unity/godot）搬出后顺序变化 | Windows 打包失败 | 准备步骤显式声明工具链前置检查；先在 Windows 上单独验证再合入 |
-| 并发调用（dev 与 IDE 同时触发） | staging 目录损坏 | 原子替换 + 所有权校验 + 有界重试 |
+| 并发调用同一 staging 目录 | 失败可读、不丢 staging | 不加锁也不支持并发：替换失败给出可执行提示并保留 staging 目录，需要并发时外部串行化 |
 | 迁移期两套生成并存 | 结果漂移 | 并存阶段以「准备步骤生成结果 == build script 生成结果」逐文件比对作为过渡判据 |

 回滚点：准备步骤上线但校验器未启用前，任一步失败都可直接恢复 build script 写入分支，无需数据迁移。
@@ -208,9 +208,9 @@ M2 之后构建脚本只做只读校验；M3 之后它也不再生成任何随

 | 里程碑 | 交付 | 停止条件 |
 |---|---|---|
-| M1 校验器化 | 单一声明 + 生成门禁、`build.rs` 只读校验路径、准备步骤脚本（codex + plugins 两条纯复制路径）、缓存与原子替换 | 校验器在既有 staging 产物上全绿（`AGC_SKIP_RESOURCE_STAGING=1` 单独可跑），且不改变现有构建行为 |
+| M1 校验器化 | 单一声明 + 生成门禁、`build.rs` 只读校验路径、准备步骤脚本（codex + plugins 两条纯复制路径）、缓存与原子替换 | 校验器在既有 staging 产物上全绿且不改变现有构建行为（写入分支与 `AGC_SKIP_RESOURCE_STAGING` 开关在 M3 一并删除） |
 | M2 入口接线 | dev 与两个发布入口调用准备步骤；codex/plugins 的写入分支从 build.rs 移除；`cargo` 新鲜度与 dev 不再重建达标 | 已交付（2026-09-27）：macOS 侧 §6 前三行达标（连续 `cargo build` 0.69 / 0.22 / 0.22 秒 fresh；`tauri dev` 全程 `Rebuilding application` 0 次、`Running DevCommand` 1 次）；Windows 新鲜度待 M3 归位三处构建期产物后复验 |
-| M3 外部工具链归位与清理 | unity/godot/cocos 的产物生成移出 build.rs；删除 `.taurignore` 的 staging 条目与相关注释；文档收口 | 已实现（2026-09-27）：三处产物改由准备步骤按声明运行 powershell/cargo 后复制，build.rs 只剩只读校验，两份 `.taurignore` 已删除；**待 Windows 真机按验收清单确认** |
+| M3 外部工具链归位与清理 | unity/godot/cocos 的产物生成移出 build.rs；删除 `.taurignore` 的 staging 条目与相关注释；文档收口 | 已实现（2026-09-27）：三处产物改由准备步骤按声明运行 powershell/cargo 后复制，build.rs 只剩只读校验，两份 `.taurignore` 已删除；已通过第五轮 Windows 真机评审：构建脚本不再写资源（90 个文件 0 变化）、第二次 `cargo build` 1.13s fresh、三分支产物齐备、幂等与 fail-closed 通过；仍待验收的是「安装包内产物路径/sha256 比对」与「三个编辑器分支客户端加载」 |

 里程碑规范与单里程碑实现计划按 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](../【协作规范】规范驱动开发工作流-2026-09-12.md) 另立 `docs/project-memory/plans/` 下的临时文件；本方案是它们的主规范来源。

@@ -88,7 +88,7 @@ Windows 本地 `npm run dev` / `npm run dev:api-server` / `npm run dev:bgfilter-

 AGC 随包资源（内置 Codex CLI、插件工作区）的布局与组件白名单只有一份人工声明：`apps/ai-game-creator-shell/src-tauri/build_support/package-layout.json`。Node 侧准备步骤直接读它，Rust 侧读由 `node scripts/check-package-layout.mjs --write`（仓库根 `npm run agc:bundled-resources:sync`）生成的 `build_support/package-layout.generated.rs`；门禁 `npm run agc:bundled-resources:check` 已进 `agc:typecheck` 链，两者不一致直接失败。改布局只能改声明文件再同步生成物，不要手改生成文件，也不要另写第二份白名单。准备步骤是 `node apps/ai-game-creator-shell/scripts/prepare-bundled-resources.mjs`：写临时目录后原子替换、命中缓存不写任何文件、只替换本工具产物、失败即退出并给出可执行提示；其用例为 `npm run agc:bundled-resources:test`。内置 Codex CLI 的上游平台包来自仓库根 `npm ci`，缺失时工具会直接提示重新安装。构建脚本对既有随包产物做只读校验（不再有写入分支，因此也没有跳过写入的开关）。

-随包资源由准备步骤在 Tauri 之前生成：`npm run agc` 在 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 里、spawn Tauri CLI 之前调用（日志以 `[ai-game-creator-shell]` 前缀给出命中缓存或重新生成）；发布链在 `build-release.mjs` 的 `runTauriBuild` 内与 Node 运行时 staging 并列调用，并传 `profile: 'release'`，`tauri build --no-bundle` 不强制 staging。**构建脚本完全不生成随包资源**（源码派生内容逐文件比对、已准备产物查存在性、Godot 随包库跑既有深度校验），源码不变时 `cargo build` 稳定 fresh。需要外部工具链或同一次 cargo 构建才能产出的内容（Unity publish 目录、Godot gdextension、Cocos bridge dll）也由准备步骤按 `build_support/package-layout.json` 的 `prepareSteps` 先运行 `powershell.exe -File build.ps1` 或 `cargo build -p … --target …` 再复制；这些步骤按内容指纹跳过未变化的情况。`resources/plugins` 由准备步骤拥有：不要手工往里放东西，准备步骤会按仓库 `plugins/` 与声明重建；dev 构建下客户端读的是 `target/debug/plugins/**`（Tauri 在 debug 配置下把随包资源拷到那里），所以改完资源要重跑准备步骤而不是手动改 `resources/`；`.taurignore` 的 staging 条目已删除（构建期不再写该目录）。
+随包资源由准备步骤在 Tauri 之前生成：`npm run agc` 在 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 里、spawn Tauri CLI 之前调用（日志以 `[ai-game-creator-shell]` 前缀给出命中缓存或重新生成）；发布链在 `build-release.mjs` 的 `runTauriBuild` 内与 Node 运行时 staging 并列调用，并传 `profile: 'release'`，`tauri build --no-bundle` 也会执行随包资源 staging（app 构建本身就需要这些资源），只跳过总号发布。**构建脚本完全不生成随包资源**（源码派生内容逐文件比对、已准备产物查存在性、Godot 随包库跑既有深度校验），源码不变时 `cargo build` 稳定 fresh。需要外部工具链或同一次 cargo 构建才能产出的内容（Unity publish 目录、Godot gdextension、Cocos bridge dll）也由准备步骤按 `build_support/package-layout.json` 的 `prepareSteps` 先运行 `powershell.exe -File build.ps1` 或 `cargo build -p … --target …` 再复制；这些步骤按内容指纹跳过未变化的情况。`resources/plugins` 由准备步骤拥有：不要手工往里放东西，准备步骤会按仓库 `plugins/` 与声明重建；dev 构建下客户端读的是 `target/debug/plugins/**`（Tauri 在 debug 配置下把随包资源拷到那里），所以改完资源要重跑准备步骤而不是手动改 `resources/`；`.taurignore` 的 staging 条目已删除（构建期不再写该目录）。

 ### 本地 Rust 构建缓存与磁盘上限