补充 AGC 随包资源归位的 M1 决策与文档

- 技术方案新增 §4.8 单一声明与实现形态（混合），§8 更新 M1 交付与停止条件，§9 未决问题 1 收口为已定 - M1 里程碑规范记录已定决策与校验收口边界；实施计划补充已定决策与实际验证命令 - M2 里程碑规范的依赖与前置条件补记 M1 已交付的准备步骤与声明门禁 - 开发运维文档补充声明、生成器、门禁、准备步骤与只读校验的用法；决策日志与排障经验同步本次口径
2026-09-27 18:36:09 +08:00
parent 05d455d4ef
commit a4b103a1b0
7 changed files with 56 additions and 13 deletions
@@ -144,6 +144,20 @@ build script 只写 `OUT_DIR`/`target`；随包资源是它的输入。凡需要
 2. **打包侧不变**：三份 tauri 配置的 `resources` 映射与 `check-config.mjs:1356-1424` 的逐字断言保持不变；`check-macos-bundle.mjs` 对包内 `coding-agent/mac-native`、`game-runtime/node`、`plugins/agc-cocos-editor` 的存在性、架构与 sha256 断言继续作为发布后门禁。
 3. **fail closed 已有兜底**：`tauri-build` 在资源缺失时以 `ResourcePathNotFound` 直接失败；校验器应比它更早、更明确地报错。

+### 4.8 单一声明与实现形态（M1 定案）
+
+准备步骤与构建期校验共用一份人工声明：`apps/ai-game-creator-shell/src-tauri/build_support/package-layout.json`。
+
+| 侧 | 读取方式 | 用途 |
+| --- | --- | --- |
+| Node 准备步骤（`scripts/prepare-bundled-resources.mjs`） | 直接读声明 JSON | 组件白名单、Codex 上游候选路径、插件随包子目录与跳过规则、平台与 feature 门槛、缓存 key 组成、manifest 序列化 |
+| Rust 构建期校验与运行期布局 | 读声明生成的 `build_support/package-layout.generated.rs`（编译期常量） | 只读校验既有产物、运行期定位随包组件（`codex_bundle.rs` 接口不变） |
+| 声明门禁 | `scripts/check-package-layout.mjs`（`npm run agc:bundled-resources:check`，已进 `agc:typecheck` 链） | 校验生成物与声明一致，并检查声明自身不变量：目标唯一、`executable` 属于白名单、每个目标恰有一条第三方声明来源、`codex.version` 与应用锁定的 `@openai/codex` 一致 |
+
+形态选择**混合**：生成归 Node（复用 `stage-node-runtime.mjs` / `prepare-macos-codex.mjs` 的下载、`integrity`、临时目录 + rename 原子替换范式），声明与校验归 Rust（复用 `codex_bundle.rs` / `godot_bundle.rs` 的布局与摘要校验，运行期模块不改公开接口）。理由：Rust 侧没有下载与 lockfile 解析能力（`[build-dependencies]` 无 HTTP 客户端），Node 侧没有 staging 能力；任选单一语言都要迁移另一侧既有资产。Rust 侧刻意不解析 JSON：声明经生成器变成编译期常量，避免运行期解析与生命周期妥协，也让 `&'static` 布局表与现有调用点保持不变。
+
+准备步骤的验证入口：`AGC_SKIP_RESOURCE_STAGING=1 cargo build/check …` 只跑只读校验、跳过写入分支，用于在既有产物上单独验证校验路径。
+
 ## 5. 兼容与迁移

 1. **产物兼容**：包内路径、manifest schema（`genarrative-codex-sidecar.v2`、`agc-node-runtime.v1`、插件 `plugin.json`）不变，安装包内容逐项对得上；升级路径不需要用户侧动作。
@@ -181,7 +195,7 @@ build script 只写 `OUT_DIR`/`target`；随包资源是它的输入。凡需要

 | 里程碑 | 交付 | 停止条件 |
 |---|---|---|
-| M1 校验器化 | `build.rs` 增加只读校验路径、准备步骤脚本骨架（codex + plugins 两条纯复制路径）、缓存与原子替换 | 校验器在既有 staging 产物上全绿，且不改变现有构建行为 |
+| M1 校验器化 | 单一声明 + 生成门禁、`build.rs` 只读校验路径、准备步骤脚本（codex + plugins 两条纯复制路径）、缓存与原子替换 | 校验器在既有 staging 产物上全绿（`AGC_SKIP_RESOURCE_STAGING=1` 单独可跑），且不改变现有构建行为 |
 | M2 入口接线 | dev 与两个发布入口调用准备步骤；codex/plugins 的写入分支从 build.rs 移除；`cargo` 新鲜度与 dev 不再重建达标 | macOS 与 Windows 均达到 §6 的前三行判据 |
 | M3 外部工具链归位与清理 | unity/godot/cocos 的产物生成移出 build.rs；删除 `prune_staging`、`STAGED_*`、`.taurignore` staging 条目与相关注释；文档收口 | 包内容逐项对得上，门禁全绿 |

@@ -189,6 +203,6 @@ build script 只写 `OUT_DIR`/`target`；随包资源是它的输入。凡需要

 ## 9. 未决问题

-1. 准备步骤用 Rust bin（可复用 `codex_bundle.rs` 的布局表与校验）还是 Node 脚本（与 `stage-node-runtime.mjs` 同构）？倾向前者以复用布局表与 sha256 校验，避免第二份白名单。
+1. ~~准备步骤用 Rust bin 还是 Node 脚本？~~ **已定（2026-09-27）：混合**——生成归 Node、声明与校验归 Rust，布局与白名单收敛为单一声明文件。机制、门禁与验证入口见 §4.8。
 2. unity/godot 的外部工具链步骤是否值得搬出 build script（它们本身是构建动作，搬出后需要显式前置顺序）——需在 Windows 上确认收益与风险。
 3. `resources/**` 是否需要继续保留在 crate 内（`bundle.resources` 相对路径解析要求），还是改用生成式配置指向 `target/` 下的 staging：前者改动小、后者更彻底，需与 Tauri 的资源解析规则一起评估。