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

- 技术方案新增 §4.8 单一声明与实现形态（混合），§8 更新 M1 交付与停止条件，§9 未决问题 1 收口为已定
- M1 里程碑规范记录已定决策与校验收口边界；实施计划补充已定决策与实际验证命令
- M2 里程碑规范的依赖与前置条件补记 M1 已交付的准备步骤与声明门禁
- 开发运维文档补充声明、生成器、门禁、准备步骤与只读校验的用法；决策日志与排障经验同步本次口径

docs/project-memory/shared-memory/decision-log.md

@@ -9578,3 +9578,13 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证：`cargo test -p module-runtime --lib agc_models::`（4 passed）、`cargo test -p api-server --bin api-server agc` 与 `llm::`、AGC 客户端 `configuration::`、admin-web 页面定向 Vitest 与 typecheck、两套 workspace 的 `cargo fmt -- --check`、`check:encoding`/`check:doc-index`/`check:spacetime-schema`/`git diff --check`。
 - 验证（真实上游 smoke，本地 dev DB）：清空 `agc_model_catalog` 后启动 api-server → 日志 `已按上游模型列表初始化 AGC 模型目录 revision=1 model_count=6`；登录后 `GET /api/llm/models` 返回同一批模型、`displayName` 即上游原名、默认项为排序后第一项；上游不可达/非 2xx 时启动只记录 error、AGC 接口 `503` 且目录保持未初始化；目录已存在时重启不重写。
 - 边界（未验证/残留）：上游在售模型超过 32 条时同步会失败（目录项上限未改）；`qwen-image-3.0` 这类图像模型会一起进入目录，是否对 AGC 隐藏由 owner 在后台停用；混合版本期间未升级的 api-server 会把自己的 AGC 接口打到 `503`，module 与 api-server 必须同批发布/回滚。
+
+## 2026-09-27 AGC 随包资源改为「单一声明 + 准备步骤生成 + 构建期只读校验」
+
+- 背景：随包资源（内置 Codex CLI、插件工作区）由 `build.rs` 在构建期写入 `src-tauri/resources/**`，而这些路径同时被 tauri 配置的 `bundle.resources` 登记成构建输入，cargo 因此永远判 stale：Windows/macOS 每次构建重编主 crate（41–87 秒），macOS dev 反复 `Rebuilding application`、客户端起不来（issue #519）。三轮症状层修复（内容比对、权限跳过、`.taurignore`）都只减少写入次数，没有改变「构建期写被登记文件」这一结构。
+- 决策（形态：混合）：准备步骤用 Node（复用 `stage-node-runtime.mjs` / `prepare-macos-codex.mjs` 的下载、`integrity`、临时目录 + rename 原子替换），布局与摘要校验留在 Rust（复用 `codex_bundle.rs` / `godot_bundle.rs`），运行期模块公开接口与取值不变。
+- 决策（单一声明）：唯一人工声明是 `apps/ai-game-creator-shell/src-tauri/build_support/package-layout.json`（Codex 三元表与组件白名单、上游候选路径、第三方声明来源、插件随包子目录与跳过规则、平台与 feature 门槛）。Node 直接读该 JSON；Rust 读由 `scripts/check-package-layout.mjs` 生成的 `package-layout.generated.rs` 编译期常量（不解析 JSON、不引入生命周期妥协）。门禁 `npm run agc:bundled-resources:check` 已进 `agc:typecheck` 链，同时校验声明自身不变量：目标唯一、`executable` 属于白名单、每个目标恰有一条第三方声明来源，且 `codex.version` 与应用锁定的 `@openai/codex` 一致。
+- 决策（校验与独立入口）：`build.rs` 新增只读校验——Codex 目录校验清单 schema/平台/版本、文件集合、逐文件 sha256、第三方声明、可执行位与白名单外文件；插件目录校验必需组件与整树符号链接。`AGC_SKIP_RESOURCE_STAGING=1` 可跳过写入分支、只跑校验，用于在既有产物上单独验证校验路径。插件产物的逐文件摘要校验留到 M2（届时准备步骤在树内写清单，不再被构建脚本整体重建覆盖）。
+- 影响面：`apps/ai-game-creator-shell/src-tauri/{build.rs,build_support/**}`、`apps/ai-game-creator-shell/scripts/{check-package-layout.mjs,prepare-bundled-resources.mjs,prepare-bundled-resources.test.mjs}`、`apps/ai-game-creator-shell/package.json`、根 `package.json`、`.gitignore`、AGC 技术方案 §4.8/§8/§9、M1 里程碑规范与实施计划、开发运维文档。三份 tauri 配置的 `resources` 映射与包内路径不变。
+- 验证：`npm run agc:bundled-resources:check`；`npm run agc:bundled-resources:test`（9 passed，含幂等、上游缺失、非本工具目录、目标不支持、dry-run）；`AGC_SKIP_RESOURCE_STAGING=1 cargo check --no-default-features --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` 在准备步骤产物上通过；准备步骤产物与构建脚本产物逐文件一致（相对路径、大小、sha256）；连续两次运行准备步骤第二次全部命中缓存，目录快照（含 mtime）不变。
+- 边界（未验证）：准备步骤尚未接入 dev 与发布入口（M2）；Windows 真机的构建新鲜度与打包未验证；Unity/Godot/Cocos 产物仍由构建脚本生成（M3）；Linux 上五条 staging 与校验均为 no-op。

docs/project-memory/shared-memory/pitfalls.md

@@ -12,6 +12,12 @@
 
 > 策划历史条目边界：旧策划 V1/V2 已全部退役，当前入口仅使用 Design Agent。下文带日期的旧 Planning V2、Fast GDD、`plan.submit_gdd`、旧 IPC/模块记录仅用于追溯，不能作为恢复旧代码、身份门禁或专属测试的依据；共享问题需在现役调用上核查。现行合同见[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。
 
+## 2026-09-27 AGC 随包资源的布局只能改声明文件，生成物由门禁锁死
+
+- **现象**：直接编辑 `apps/ai-game-creator-shell/src-tauri/build_support/package-layout.generated.rs`，或另写一份组件白名单，`npm run agc:typecheck`（链内含 `npm run agc:bundled-resources:check`）会立刻失败并报「随包资源声明与 Rust 常量不一致」。
+- **正确做法**：改 `build_support/package-layout.json`，运行 `npm run agc:bundled-resources:sync` 重新生成；改布局同时递增 `layoutVersion`（参与准备步骤的缓存 key）。声明里的 `codex.version` 必须与应用锁定的 `@openai/codex` 一致，门禁会对照 `apps/ai-game-creator-shell/package.json` 校验。
+- **边界（M1 完成时）**：准备步骤 `scripts/prepare-bundled-resources.mjs` 尚未接入 dev / 发布入口，`npm run agc` 仍由构建脚本 staging；构建脚本当前既写资源又做只读校验，`AGC_SKIP_RESOURCE_STAGING=1` 可只跑校验。构建脚本重建 `resources/plugins` 时会整体删除该目录，所以插件侧的准备步骤清单要等 M2 接管写入后才成立，插件目录现在只校验必需组件与符号链接。
+
 ## 2026-09-24 模型输出的围栏会粘在正文行里：聊天 Markdown 必须先归一化再解析
 
 - **现象**：AGC 对话里代码块解析错位——引言行被当成代码渲染（`…实现细节（game.js）：```js`），或者代码块收不住、把后面的正文一起吞进去（`… return centerOn(projection); }````）。文本本身「看起来没问题」，容易被当成渲染器坏了。