补充 AGC 随包资源 staging 归位里程碑与首段实施计划

- 新增三份里程碑规范：资源改由校验器读入、生成接入 dev 与发布入口、编辑器分支产物归位与症状层补丁清理 - 新增首个里程碑实施计划：修改边界、实现顺序、验证命令、风险与回滚点、待确认的实现形态
2026-09-27 16:59:42 +08:00
parent e02811588c
commit 756297d2df
4 changed files with 196 additions and 0 deletions
@@ -0,0 +1,62 @@
+# 【实施计划】AGC 随包资源改由校验器读入
+
+| 字段      | 值                                                              |
+| --------- | --------------------------------------------------------------- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC随包资源改由校验器读入-2026-09-26.md` |
+| Status    | ready（待里程碑规范评审通过后开工）                              |
+| Owner     | suzmii / Agent                                                  |
+
+## 修改边界
+
+允许修改：
+
+- `apps/ai-game-creator-shell/src-tauri/build.rs`：新增只读校验调用点；本里程碑内保持现有写入分支不变（不改变既有构建行为）。
+- `apps/ai-game-creator-shell/src-tauri/build_support/**`：把平台布局、组件白名单、摘要校验整理为可被构建脚本之外的独立工具复用的一处声明。
+- 新增随包资源准备工具及其测试（位置见「待确认决策」）。
+- 需要时扩展 `apps/ai-game-creator-shell/scripts/check-config.mjs` 的断言。
+- 文档：主规范未决问题收口、开发运维文档对应段落。
+
+明确不修改：
+
+- 三份 tauri 配置的 `resources` 映射、包内路径与安装包形态。
+- 运行时资源解析与完整性校验（`codex_cli.rs`、`plugin_host.rs`、`editor_adapters.rs`、`environment_check.rs`）。
+- 发布脚本流程、版本号机制、签名与上传。
+- dev 启动器与发布入口的接线（下一里程碑）。
+- 编辑器分支产物（Unity/Godot/Cocos）的生成方式（最后一个里程碑）。
+
+## 实现顺序
+
+1. **共用能力可复用**：确认 `build_support` 内的平台布局与组件白名单能被独立工具引用（现状先例：`src/agent/codex_cli.rs` 与 `main.rs` 已通过 `#[path]` 复用同一模块），把「布局 + 白名单 + 摘要校验」收敛为单一入口，避免准备工具另写一份清单。
+2. **准备工具骨架**：目标目录与清单写出、缓存 key（上游 lockfile 的 `resolved` + `integrity` + 布局版本 + 目标三元）、临时目录 + 原子替换、所有权与符号链接校验、并发串行化、单行汇总日志。先实现纯复制两条路径（随包组件、插件工作区），编辑器分支产物本轮仍由构建脚本生成。
+3. **幂等与失败关闭**：重复执行不改变内容与时间戳；上游缺失、摘要不匹配、目录被非本工具占用、目标平台不支持四类场景各自失败并给出可定位原因。
+4. **校验路径上线**：构建脚本在既有产物上执行只读校验（默认不影响现有写入行为），校验失败以明确原因中止。
+5. **测试与证据**：按里程碑「证据要求」补齐用例与运行记录。
+
+## 验证命令
+
+1. 布局与白名单唯一性：`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --no-default-features codex_bundle`
+2. 校验路径用例：`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --no-default-features <新增校验用例过滤名>`
+3. 幂等：连续两次运行准备工具，比对目标目录内容与时间戳快照（内容与 mtime 均不变）
+4. 失败关闭：对上游缺失、摘要篡改、非本工具目录、非目标平台四种场景各跑一次，记录错误输出
+5. 行为不回归：`cargo build --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --no-default-features`（本里程碑不承诺构建变快，仅确认行为与改造前一致，并记录当前构建耗时作为后续里程碑基线）
+6. 门禁：`node apps/ai-game-creator-shell/scripts/check-config.mjs`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`，以及改动范围内相关 vitest/Rust 测试
+
+## 风险与回滚点
+
+| 风险 | 影响 | 处理 |
+| --- | --- | --- |
+| 校验器误判把构建卡死 | 影响所有本机构建 | 只读校验先以「不影响写入行为」的方式接入；出现误判可先关闭校验调用点回滚 |
+| 准备工具与构建脚本并存产生双写 | 两处结果漂移、时间戳变化 | 并存期以「准备工具产物 == 构建脚本产物」逐文件比对作为过渡判据；不一致视为失败 |
+| 缓存 key 漏掉上游变化 | 静默用旧组件 | key 含 lockfile `resolved` + `integrity` + 布局版本 + 三元；清单校验作为第二道闸 |
+| 准备工具实现形态选错 | 返工 | 见「待确认决策」，评审时一次定清 |
+
+回滚点：本里程碑不改变既有构建行为，回滚只需移除校验调用点与准备工具，不影响产物与发布流程。
+
+## 待确认决策
+
+准备工具的实现形态（主规范未决问题 1）建议为**混合**：
+
+- 上游获取、`integrity` 校验、归档安全与原子替换复用 Node 侧既有范式（`scripts/stage-node-runtime.mjs`、`scripts/prepare-macos-codex.mjs`）；
+- 平台布局、组件白名单与逐文件摘要校验复用 Rust 侧既有声明（`build_support/codex_bundle.rs`、`build_support/godot_bundle.rs`、`build_support/codex_package_metadata.rs`），由准备工具调用或由校验路径承担。
+
+理由：避免出现第二份组件白名单；同时不必重写 registry 下载、`integrity` 与 tar 安全校验。若评审倾向单一语言实现，需接受「另写一份白名单」或「把 Node 侧下载能力用 Rust 重写」二者之一。
@@ -0,0 +1,44 @@
+# 【里程碑】AGC 编辑器分支产物归位与症状层补丁清理
+
+| 字段        | 值                                                              |
+| ----------- | --------------------------------------------------------------- |
+| Version     | 1.0                                                             |
+| Status      | proposed                                                        |
+| Date        | 2026-09-26                                                      |
+| Parent Spec | `docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md` |
+
+## 目标
+
+编辑器分支（Unity/Godot/Cocos）的随包产物也由准备步骤生成，构建脚本不再调用外部工具链产出随包资源；此前为绕开自触发问题而加入的症状层补丁与说明全部删除，实现形态与主规范一致。
+
+## 范围
+
+- 三个编辑器分支产物的生成职责迁出构建脚本，包括需要外部工具链的两条路径。
+- 构建脚本内与资源生成相关的规避手段删除：残留清理逻辑、为幂等而设的辅助常量与判断、开发监听忽略条目中与随包资源相关的部分。
+- 平台与特性开关（哪些平台、哪些特性才需要这些产物）在新形态下保持既有语义。
+- 与发布打包、包内资源门禁、运行时解析的一致性核对。
+
+## 不在范围内
+
+- 编辑器分支本身的接入协议、宿主能力与运行时行为。
+- 外部工具链版本管理与安装流程（沿用现状）。
+- 随包组件与插件工作区的生成形态（上一里程碑已完成）。
+
+## 依赖与前置条件
+
+- 前两个里程碑验收通过。
+- Windows 环境具备 Unity/Godot 分支所需的工具链（.NET 与 CMake 等），以便验证产物生成与打包。
+
+## 验收标准
+
+- [ ] 构建脚本中不再存在向随包资源目录写入的分支，也不再调用产出随包资源的外部工具链。
+- [ ] 三个编辑器分支的随包产物路径、内容摘要、可执行位与迁移前逐项一致，且由准备步骤稳定产出。
+- [ ] 此前为规避自触发而加入的补丁（残留清理、幂等辅助、监听忽略条目）在代码与文档中全部移除，不再有「为了绕开构建问题」的说明。
+- [ ] 平台与特性开关语义不变：不支持的平台不产出这些资源，且不因此失败。
+- [ ] 全量门禁通过，且客户端在具备条件与不具备条件两种环境下都能给出明确结论（可用 / 缺组件及原因）。
+
+## 证据要求
+
+- 自动化：编辑器分支产物的摘要对比、平台门槛用例、配置门禁与包内资源门禁。
+- 运行时：Windows 上一次完整打包与一次客户端启动，确认编辑器分支产物被读取。
+- 边界：缺少外部工具链、缺少组件、非目标平台三种情形下的失败与跳过语义。
@@ -0,0 +1,44 @@
+# 【里程碑】AGC 随包资源改由校验器读入
+
+| 字段        | 值                                                          |
+| ----------- | ----------------------------------------------------------- |
+| Version     | 1.0                                                         |
+| Status      | proposed                                                    |
+| Date        | 2026-09-26                                                  |
+| Parent Spec | `docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md` |
+
+## 目标
+
+构建脚本不再需要「自己写随包资源」才能成立：在约定目录已有合规资源时，构建只做只读校验并通过；校验失败时给出明确原因并拒绝继续，而不是静默重新生成。
+
+## 范围
+
+- 随包资源的合规性判定：平台目录存在、清单 schema 与平台一致、逐文件摘要一致、必需组件齐全、版本与上游锁定一致。
+- 资源生成能力的可复用化：同一份布局与摘要校验能力既能被构建期校验使用，也能被准备步骤使用，不得出现第二份组件白名单。
+- 生成结果的稳定性要求：同一输入重复生成时，产物内容与文件时间戳不发生变化。
+
+## 不在范围内
+
+- 接入 dev 与发布入口（下一里程碑）。
+- 移除构建脚本里的资源写入分支。
+- 编辑器分支产物（Unity/Godot/Cocos）的生成方式与外部工具链调用。
+- 运行时资源解析顺序、完整性校验语义与打包配置里的资源映射。
+- Linux 产物支持。
+
+## 依赖与前置条件
+
+- 主规范第 4.3 与第 4.4 节的合同（准备步骤合同、构建脚本退化后的职责边界）。
+- 现有随包资源与清单已由当前实现产出，可用于校验回归。
+
+## 验收标准
+
+- [ ] 资源合规时，校验路径可独立运行并通过，不依赖构建脚本的写入分支。
+- [ ] 上游锁定版本、平台、逐文件摘要、必需组件四类不一致各自被拒绝，并给出可定位的原因。
+- [ ] 重复执行资源生成，产物内容与文件时间戳不变（幂等）。
+- [ ] 同一份布局与组件白名单只有一处声明，构建期校验与准备步骤共用。
+
+## 证据要求
+
+- 自动化：资源校验的通过/拒绝用例；同输入重复生成后目录快照对比（内容 + 时间戳）。
+- 运行时：本机在既有随包资源上运行一次校验与一次构建，确认资源被正常读取且构建行为与改造前一致。
+- 边界：目标平台不支持、上游缺失、摘要不匹配、目录被非本工具内容占用四种场景各自的失败输出。
@@ -0,0 +1,46 @@
+# 【里程碑】AGC 随包资源生成接入 dev 与发布入口
+
+| 字段        | 值                                                              |
+| ----------- | --------------------------------------------------------------- |
+| Version     | 1.0                                                             |
+| Status      | proposed                                                        |
+| Date        | 2026-09-26                                                      |
+| Parent Spec | `docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md` |
+
+## 目标
+
+随包资源在客户端开发与发布两条链上，都由启动/打包之前的准备步骤一次性生成；构建脚本不再承担生成职责，源码不变时构建不再重复编译。
+
+## 范围
+
+- 客户端开发的启动流程：在拉起客户端之前完成资源准备，命中缓存时不重写任何文件。
+- 发布打包流程：Windows 与 macOS 两条链在拉起打包工具之前完成资源准备，包括既有的运行时资源准备点。
+- 纯复制型资源（随包组件与插件工作区）的生成职责从构建脚本迁出。
+- 不打包场景（仅校验、不产包）的放行口径。
+
+## 不在范围内
+
+- 编辑器分支产物（Unity/Godot/Cocos）的生成方式与外部工具链调用（下一里程碑）。
+- 打包配置里的资源映射、包内资源门禁与安装包形态。
+- 运行时资源解析与完整性校验语义。
+- 构建脚本中与资源无关的既有职责（配置能力、提示词产物、元数据）。
+
+## 依赖与前置条件
+
+- 上一里程碑的验收通过：资源校验可只读通过、生成幂等、白名单唯一。
+- 开发与发布两条链在拉起客户端/打包工具之前都有明确可插入的准备阶段。
+- Windows 与 macOS 均需具备可验证的开发环境（两个平台各自验收）。
+
+## 验收标准
+
+- [ ] 客户端开发启动一次成功：不再出现因资源变更而触发的重复构建，客户端与运行器进程稳定存活。
+- [ ] 源码不变时连续两次构建，第二次为秒级完成；构建脚本声明的输入中不再出现随包资源路径。
+- [ ] Windows 与 macOS 打包产物中的随包资源，与迁移前逐项一致（路径、内容摘要、可执行位）。
+- [ ] 准备步骤连续执行两次不改变产物内容与时间戳；缺少准备步骤时，打包与启动以明确错误失败，而不是静默产出缺组件的包。
+- [ ] 本机 Rust 门禁（会触发构建脚本的测试入口）与不打包构建路径仍然可用。
+
+## 证据要求
+
+- 自动化：构建新鲜度日志、构建脚本输入清单、准备步骤幂等快照、包内资源门禁脚本结果。
+- 运行时：macOS 与 Windows 各一次客户端启动，确认随包组件被读取而非回退到外部安装。
+- 边界：缺少准备步骤、缓存命中、上游锁定变化三种情形下的行为。