合并最新master到游戏评价分支
合并origin/master的后台项目排序与AGC随包资源更新 保留网站评分评价功能和后台评价管理方案
This commit is contained in:
@@ -0,0 +1,64 @@
|
||||
# 【实施计划】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. 声明唯一性与门禁：`npm run agc:bundled-resources:check`（已进 `agc:typecheck` 链），不一致时用 `npm run agc:bundled-resources:sync` 重新生成。
|
||||
2. 准备工具用例（含幂等与失败关闭）：`npm run agc:bundled-resources:test`。
|
||||
3. 校验路径独立运行（跳过写入分支）：`AGC_SKIP_RESOURCE_STAGING=1 cargo check --no-default-features --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`。
|
||||
4. Rust 用例：`cargo test --no-default-features --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml package_layout` 与 `cargo test --no-default-features --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml codex_bundle`。
|
||||
5. 幂等（真实工作区）：连续两次 `node apps/ai-game-creator-shell/scripts/prepare-bundled-resources.mjs`，第二次必须全部「命中缓存」，且两次之后的目录快照（相对路径、大小、mtime、sha256）完全一致。
|
||||
6. 并存一致：准备步骤产物与构建脚本产物逐文件比对（相对路径、大小、sha256）一致。
|
||||
7. 行为不回归：`cargo build --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --no-default-features`（本里程碑不承诺构建变快，仅确认行为与改造前一致，并记录当前构建耗时作为后续里程碑基线）。
|
||||
8. 门禁：`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）**已定为混合**（2026-09-27，机制见主规范 §4.8）：
|
||||
|
||||
- 上游获取、`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` 已在 M2 因失去调用方删除。）
|
||||
|
||||
理由：避免出现第二份组件白名单，同时不必重写 registry 下载、`integrity` 与 tar 安全校验；缺点是声明需要经过一次生成步骤才能在 Rust 侧使用，由 `check-package-layout.mjs` 门禁保证两者一致。
|
||||
@@ -0,0 +1,115 @@
|
||||
# 【里程碑】AGC 编辑器分支产物归位与症状层补丁清理
|
||||
|
||||
| 字段 | 值 |
|
||||
| ----------- | --------------------------------------------------------------- |
|
||||
| Version | 1.0 |
|
||||
| Status | in-progress（2026-09-28 已过 Windows 真机核心评审；2026-09-29 完成打包一致性验收，客户端加载待有编辑器环境的机器；Cocos payload feature 集差异待裁决） |
|
||||
| Date | 2026-09-26 |
|
||||
| Parent Spec | `docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md` |
|
||||
|
||||
## 已实现（2026-09-27）
|
||||
|
||||
- 声明新增三类「准备步骤」产物：`subdirectories[origin=prepared]`（Unity publish 目录）、`libraryStaging[].prepare + files`（Godot gdextension）、`nativePayloads[]`（Cocos bridge dll）；`plugins.prepareSteps` 描述每个准备步骤的程序、工作目录、指纹与必需产物。
|
||||
- 准备步骤（`scripts/prepare-bundled-resources.mjs`）按声明执行 `powershell.exe -File build.ps1` 与 `cargo build -p … --target …`，用内容指纹跳过未变化的步骤，校验必需产物齐全后才复制；命中指纹且产物齐全时零写入。
|
||||
- 构建脚本删除了三处产物生成与整棵树复制（`prepare_unity_editor_helper`、`prepare_godot_editor_extension`、`stage_cocos_editor_payload`、`stage_build_generated_plugin_payloads` 及其辅助函数，共减少约 220 行），只保留只读校验：源码派生内容逐文件比对、已准备产物存在性、Godot 随包库沿用既有深度校验（`godot_bundle::validate`）。Godot 随包文件清单改由声明提供（单一来源）。
|
||||
- `.taurignore` 的两份 staging 条目已删除（构建期不再写 `resources/plugins`，无需忽略）。
|
||||
- 准备步骤的 Windows 侧命令路径已随系统性审计在真机复跑（powershell/cargo 两条路径、产物归位与幂等均已验证）。
|
||||
|
||||
## 目标
|
||||
|
||||
编辑器分支（Unity/Godot/Cocos）的随包产物也由准备步骤生成，构建脚本不再调用外部工具链产出随包资源；此前为绕开自触发问题而加入的症状层补丁与说明全部删除，实现形态与主规范一致。
|
||||
|
||||
## 范围
|
||||
|
||||
- 三个编辑器分支产物的生成职责迁出构建脚本，包括需要外部工具链的两条路径。
|
||||
- 构建脚本内与资源生成相关的规避手段删除：残留清理逻辑、为幂等而设的辅助常量与判断、开发监听忽略条目中与随包资源相关的部分。
|
||||
- 平台与特性开关（哪些平台、哪些特性才需要这些产物）在新形态下保持既有语义。
|
||||
- 与发布打包、包内资源门禁、运行时解析的一致性核对。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 编辑器分支本身的接入协议、宿主能力与运行时行为。
|
||||
- 外部工具链版本管理与安装流程（沿用现状）。
|
||||
- 随包组件与插件工作区的生成形态（上一里程碑已完成）。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- 前两个里程碑验收通过。
|
||||
- Windows 环境具备 Unity/Godot 分支所需的工具链（.NET 与 CMake 等），以便验证产物生成与打包。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 构建脚本中不再存在向随包资源目录写入的分支，也不再调用产出随包资源的外部工具链。
|
||||
- [ ] 三个编辑器分支的随包产物路径、内容摘要、可执行位与迁移前逐项一致，且由准备步骤稳定产出。（2026-09-29 验收：路径集合与源码派生内容、Unity/Godot 产物逐字节一致；Cocos payload 因声明只构建 `windows-injection` 而与迁移前不同，且 MSVC 链接产物本身不可字节复现，见下方验收记录，口径待裁决）
|
||||
- [ ] 此前为规避自触发而加入的补丁（残留清理、幂等辅助、监听忽略条目）在代码与文档中全部移除，不再有「为了绕开构建问题」的说明。
|
||||
- [ ] 平台与特性开关语义不变：不支持的平台不产出这些资源，且不因此失败。
|
||||
- [ ] 全量门禁通过，且客户端在具备条件与不具备条件两种环境下都能给出明确结论（可用 / 缺组件及原因）。
|
||||
|
||||
## 验收记录（2026-09-29，Windows 本机）
|
||||
|
||||
### 打包一致性（验收标准第 2 条）
|
||||
|
||||
准备步骤按发布入口同样的参数复跑（`prepareBundledResources({ target: 'x86_64-pc-windows-msvc', features: Set('unity-editor-execute','godot-editor-execute','cocos-editor-injection'), profile: 'release' })`）：`cocos-bridge-build 已构建`、`unity-helper-publish` / `godot-extension-build 命中缓存`、`plugins 重新生成`；随后连续三次复跑，`resources/plugins` 的 32 个文件内容与 mtime 均不再变化（稳定产出）。
|
||||
|
||||
出包走同一发布入口（`runTauriBuild` + `--bundles nsis`），并临时把 `bundle.createUpdaterArtifacts` 置 false——本机没有 updater 签名私钥，只出安装包；产物 `target/x86_64-pc-windows-msvc/release/bundle/nsis/陶泥儿开发版_0.1.67_x64-setup.exe`（166452206 B，sha256 `04a0be8ab8f54d8f032ce86d3e5c7a99c1dd6e81f71d49b63486827b11a01940`）。`tauri.windows.conf.json` 里 `resources/plugins → plugins` 是目录级映射。
|
||||
|
||||
包内核对：7z 解包得 2108 个文件，包内 `plugins/` 的 32 个文件与准备步骤产出的 `resources/plugins` **逐文件 sha256 完全一致**；`editor_adapters.rs` 的三个运行时相对路径（`UNITY_ATTACH_HELPER_RELATIVE` / `GODOT_BRIDGE_PAYLOAD_RELATIVE` / `COCOS_BRIDGE_PAYLOAD_RELATIVE`）加上声明里的必需产物共 17 项在包内全部命中。
|
||||
|
||||
迁移前对照取两份：本机已安装的 2026-09-24 包（`%LOCALAPPDATA%\陶泥儿开发版\plugins`，迁移前产品产物），以及把 `src-tauri` 整体切回合并基线 `8f59c034f` 后在同一个工作树里跑 `cargo build --release --target x86_64-pc-windows-msvc --features=unity-editor-execute,godot-editor-execute,cocos-editor-injection` 得到的 `resources/plugins`。三份对照路径集合一致，源码派生内容（JS/HTML/JSON/license/notice）逐字节一致，Unity helper、Godot 扩展逐字节一致。
|
||||
|
||||
两处已定性的差异：
|
||||
|
||||
1. **Cocos payload 的构建 feature 集不同（需裁决口径）**：迁移前由同一次应用构建产出（`windows-bootstrap` + `windows-injection`，345088 B）；准备步骤按声明只构建 `windows-injection`（26112 B，见 2026-09-27 决策日志条）。两者导出面完全相同（`DllMain`、`cocos_editor_bridge_bootstrap_source`），差掉的是宿主侧 bootstrap 传输（`reqwest`/`tungstenite`/`inspector`），注入进程不使用；但按「内容摘要与迁移前逐项一致」的字面判据不成立。
|
||||
2. **MSVC 链接产物不可字节复现**：同一 source / feature / profile / target 连续构建的 payload 摘要不同（除 PE `TimeDateStamp` 外还有 22 字节 RSDS GUID 差异）；.NET publish 相反是确定的（Unity helper 跨两次重新发布逐字节一致），Godot 因 `buildId` 早退未重链也保持逐字节一致。因此「摘要一致」只在源码派生物、.NET 产物与命中工具链内部缓存的产物上成立。
|
||||
|
||||
新发现的风险（本轮未修，不影响上述结论）：
|
||||
|
||||
- 准备步骤的 `cocos-bridge-build` 与同一次应用构建写同一个输出路径 `target/<triple>/<profile>/deps/cocos_editor_bridge.dll`（两个 feature 单元同名产物），准备步骤的候选查找可能取到另一单元刚写下的文件；本轮实测两者交替后 cargo 会多一次重链。建议让准备步骤在独立 target 目录构建，或与应用的 feature 集对齐后从同一单元取产物。
|
||||
|
||||
### 客户端编辑器分支（验收标准第 5 条）
|
||||
|
||||
本机未安装 Unity / Godot / Cocos Creator（`Program Files`、`UnityHub`、scoop shims 均无），进入编辑器分支只会停在「未检测到编辑器进程」，拿不到「helper/扩展被加载」的真机结论，因此**本轮未执行**，需在有三种编辑器的机器上补做。
|
||||
|
||||
已完成的自动化前段（本轮实测，用安装包解出的客户端、不安装）：
|
||||
|
||||
- 从 NSIS 包 7z 解出后直接运行 `genarrative-ai-game-creator-shell.exe`：窗口落在 `http://tauri.localhost/`（生产态嵌入前端，不是 `devUrl`），首页正常渲染，最近项目与模板库可见——说明包内 `plugins/`、`skills`、模板资源都被正确读取（对照：用 `cargo build --release` 直接编出来的 exe 没有 `custom-protocol`，会去连 `127.0.0.1:3080` 并落到 chrome 错误页，不能拿它当打包客户端）。
|
||||
- CDP 主世界（`page.target().createCDPSession()` + `Runtime.evaluate`）可读只读投影：`list_agc_plugins` 返回 `agc-cocos-editor` / `agc-unity-editor`（`builtin=true`、`hasRuntime=true`、`adapter` 正确），`list_agc_skill_catalog` 返回 8 条 —— 插件的 JS 入口与 Skill 包都按声明进包。
|
||||
- `agc-godot-editor` 插件不在该列表里符合现役语义：`plugin_host.rs::plugin_matches_project` 只在当前项目是 Godot 工程（根或一层子目录有 `project.godot`）时才让它可见。
|
||||
- 三种编辑器分支的判据入口：`require_plugin_adapter` 缺适配器时报「当前客户端不支持 X 编辑器桥接」，适配器在 payload/helper 缺失时报各自缺组件文案（如 Godot「插件缺少原生 DLL 资源」），编辑器没开时报探测失败——补做时要按这三类分开记录。
|
||||
|
||||
### 顺带定性：CI 唯一红项与本 PR 无关
|
||||
|
||||
run 2980（HEAD `0cf536b6`）唯一失败项是 `tests::sessions::background_agent_runtime_can_write_memory_and_project_files`（`src-tauri/src/tests/sessions.rs:405`，第二个 provider follow-up 请求 `recv_timeout(2s)` 超时）：
|
||||
|
||||
- 本 PR 对这条路径零改动：`src/` 下只有 `main.rs`（`#[cfg(test)]` 引入 `package_layout` 单测）与 `agent/codex_cli.rs`（去掉 `codex_package_metadata` 测试模块）两处**测试编译期**改动；`sessions.rs` 与 agent runtime 与合并基线逐字节相同。
|
||||
- 把 `src-tauri` 整体切回合并基线 `8f59c034f` 后，同一条命令在本机失败在同一断言（`second llm request: Timeout`）。
|
||||
- 本机实测第二个 follow-up 请求耗时 **5.18s / 4.87s**（两次），而测试预算 2s：该断言在本机裕量不足。master run 2979（lane 2 shard 3）也因另一条并发用例失败，属同一类时间预算抖动。
|
||||
- 结论：既有测试时间预算问题，不在本 PR 内顺手修。
|
||||
|
||||
## 验证步骤（Windows 侧执行清单）
|
||||
|
||||
准备：切到本里程碑分支，`npm ci`（需装上 `@openai/codex-win32-x64`），确认 `spacetime --version` 与 `server-rs` 锁定版本一致（仅本地 dev 需要）。
|
||||
|
||||
1. **准备步骤单独跑（不打包）**
|
||||
- `npm run agc:bundled-resources:prepare -- --target x86_64-pc-windows-msvc`
|
||||
- 预期：一行汇总日志；`src-tauri/resources/plugins/agc-unity-editor/dotnet/publish/win-x64/Agc.Unity.Attach.exe`、`agc-godot-editor/native/gdextension/` 下的扩展在位。
|
||||
- Cocos payload 只在 injection 构建下交付（与迁移前一致）：加 `--features=cocos-editor-execute,unity-editor-execute,godot-editor-execute,cocos-editor-injection` 再跑一次，确认 `agc-cocos-editor/native/payload/cocos-editor-bridge.dll` 同时出现在插件工作区与随包目录。
|
||||
- 再跑一次：预期全部「命中缓存」，且 `resources/**` 的文件时间戳不变。
|
||||
2. **构建期不再写随包资源**
|
||||
- 取 `src-tauri/resources` 全量快照（相对路径/大小/mtime/sha256）→ `touch apps/ai-game-creator-shell/src-tauri/build.rs` → 再 `cargo build` → 两次快照必须逐项一致。
|
||||
3. **构建新鲜度**：源码不变时连续两次 `cargo build --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`，第二次应为秒级 `Finished`，且不再出现 `Compiling genarrative-ai-game-creator-shell`。
|
||||
4. **打包一致性**：出一次 Windows 安装包，核对包内 `plugins/` 下三种编辑器分支产物的路径与 sha256 与迁移前一致；`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --no-run` 必须通过（会触发只读校验，所以要先跑过准备步骤）。
|
||||
5. **客户端启动**：进入 Unity/Godot/Cocos 编辑器分支各一次，确认对应 helper/扩展被加载，没有「缺少组件」类提示。
|
||||
6. **边界（负例）**
|
||||
- 删掉 `plugins/agc-unity-editor/dotnet/publish/` 且让工具链不可用后打包：准备步骤必须给出明确失败原因（缺工具链/缺产物），而不是静默产出缺组件的包。
|
||||
- 删掉 `target/agc-resource-staging.json` 再跑准备步骤：预期重新生成，产物内容不变（丢缓存只多一次哈希）。
|
||||
- 删掉 `plugins/agc-unity-editor/dotnet/publish/win-x64/.agc-source.sha256` 后重跑准备步骤：预期重新执行 dotnet publish，而不是复用旧产物。
|
||||
- 手工改 `resources/**` 一个字节后 `cargo build`：只读校验必须失败（该规则覆盖 source 派生内容；prepared 产物只查存在性，见排障经验）。
|
||||
|
||||
记录：把每步命令、关键输出与结论贴回本里程碑或对应 PR；未通过项回到主规范 §9 记为未决问题。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：编辑器分支产物的摘要对比、平台门槛用例、配置门禁与包内资源门禁。
|
||||
- 运行时：Windows 上一次完整打包与一次客户端启动，确认编辑器分支产物被读取。
|
||||
- 边界：缺少外部工具链、缺少组件、非目标平台三种情形下的失败与跳过语义。
|
||||
@@ -0,0 +1,51 @@
|
||||
# 【里程碑】AGC 随包资源改由校验器读入
|
||||
|
||||
| 字段 | 值 |
|
||||
| ----------- | ----------------------------------------------------------- |
|
||||
| Version | 1.0 |
|
||||
| Status | completed（2026-09-27） |
|
||||
| Date | 2026-09-26 |
|
||||
| Parent Spec | `docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md` |
|
||||
|
||||
## 已定决策（2026-09-27）
|
||||
|
||||
- **实现形态：混合**——生成归 Node（`scripts/prepare-bundled-resources.mjs`），声明与校验归 Rust。依据与对比见主规范 §4.8。
|
||||
- **单一声明**：`build_support/package-layout.json` 是唯一人工声明；Rust 侧使用由 `scripts/check-package-layout.mjs` 生成的编译期常量（`package-layout.generated.rs`），门禁 `npm run agc:bundled-resources:check` 已进 `agc:typecheck` 链；运行期 `codex_bundle.rs` 的公开接口与取值不变。
|
||||
- **校验收口边界**：本里程碑对随包 Codex 目录做全量校验（清单 schema/平台/版本、文件集合、逐文件摘要、第三方声明、可执行位、白名单外文件）；插件随包目录只校验必需组件与符号链接。插件产物的逐文件摘要校验在 M2 由准备步骤写入树内清单后启用——M1 期间构建脚本仍整体重建 `resources/plugins`，树内清单会被清掉。
|
||||
- **独立验证入口**：`AGC_SKIP_RESOURCE_STAGING=1` 让构建脚本只跑只读校验、跳过写入分支。
|
||||
|
||||
## 目标
|
||||
|
||||
构建脚本不再需要「自己写随包资源」才能成立：在约定目录已有合规资源时，构建只做只读校验并通过；校验失败时给出明确原因并拒绝继续，而不是静默重新生成。
|
||||
|
||||
## 范围
|
||||
|
||||
- 随包资源的合规性判定：平台目录存在、清单 schema 与平台一致、逐文件摘要一致、必需组件齐全、版本与上游锁定一致。
|
||||
- 资源生成能力的可复用化：同一份布局与摘要校验能力既能被构建期校验使用，也能被准备步骤使用，不得出现第二份组件白名单。
|
||||
- 生成结果的稳定性要求：同一输入重复生成时，产物内容与文件时间戳不发生变化。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 接入 dev 与发布入口（下一里程碑）。
|
||||
- 移除构建脚本里的资源写入分支。
|
||||
- 编辑器分支产物（Unity/Godot/Cocos）的生成方式与外部工具链调用。
|
||||
- 运行时资源解析顺序、完整性校验语义与打包配置里的资源映射。
|
||||
- Linux 产物支持。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- 主规范第 4.3 与第 4.4 节的合同（准备步骤合同、构建脚本退化后的职责边界）。
|
||||
- 现有随包资源与清单已由当前实现产出，可用于校验回归。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 资源合规时，校验路径可独立运行并通过，不依赖构建脚本的写入分支。
|
||||
- [ ] 上游锁定版本、平台、逐文件摘要、必需组件四类不一致各自被拒绝，并给出可定位的原因。
|
||||
- [ ] 重复执行资源生成，产物内容与文件时间戳不变（幂等）。
|
||||
- [ ] 同一份布局与组件白名单只有一处声明，构建期校验与准备步骤共用。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：资源校验的通过/拒绝用例；同输入重复生成后目录快照对比（内容 + 时间戳）。
|
||||
- 运行时：本机在既有随包资源上运行一次校验与一次构建，确认资源被正常读取且构建行为与改造前一致。
|
||||
- 边界：目标平台不支持、上游缺失、摘要不匹配、目录被非本工具内容占用四种场景各自的失败输出。
|
||||
@@ -0,0 +1,48 @@
|
||||
# 【里程碑】AGC 随包资源生成接入 dev 与发布入口
|
||||
|
||||
| 字段 | 值 |
|
||||
| ----------- | --------------------------------------------------------------- |
|
||||
| Version | 1.0 |
|
||||
| Status | in-progress（2026-09-27 起实施） |
|
||||
| Date | 2026-09-26 |
|
||||
| Parent Spec | `docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md` |
|
||||
|
||||
## 目标
|
||||
|
||||
随包资源在客户端开发与发布两条链上，都由启动/打包之前的准备步骤一次性生成；构建脚本不再承担生成职责，源码不变时构建不再重复编译。
|
||||
|
||||
## 范围
|
||||
|
||||
- 客户端开发的启动流程：在拉起客户端之前完成资源准备，命中缓存时不重写任何文件。
|
||||
- 发布打包流程：Windows 与 macOS 两条链在拉起打包工具之前完成资源准备，包括既有的运行时资源准备点。
|
||||
- 纯复制型资源（随包组件与插件工作区）的生成职责从构建脚本迁出。
|
||||
- 不打包场景（仅校验、不产包）的放行口径。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 编辑器分支产物（Unity/Godot/Cocos）的生成方式与外部工具链调用（下一里程碑）。
|
||||
- 打包配置里的资源映射、包内资源门禁与安装包形态。
|
||||
- 运行时资源解析与完整性校验语义。
|
||||
- 构建脚本中与资源无关的既有职责（配置能力、提示词产物、元数据）。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- 上一里程碑的验收通过：资源校验可只读通过、生成幂等、白名单唯一。
|
||||
- M1 交付的准备步骤与声明门禁已在位：`apps/ai-game-creator-shell/scripts/prepare-bundled-resources.mjs`（Codex 与插件两条纯复制路径，写临时目录后原子替换，命中缓存不重写）与 `npm run agc:bundled-resources:check`（已进 `agc:typecheck` 链）。本里程碑需要让准备步骤改为在 `resources/plugins` 内写入自己的清单，并停止构建脚本对该目录的整体重建，插件产物的逐文件摘要校验才能启用。
|
||||
- 开发与发布两条链在拉起客户端/打包工具之前都有明确可插入的准备阶段。
|
||||
- Windows 与 macOS 均需具备可验证的开发环境（两个平台各自验收）。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] 客户端开发启动一次成功：不再出现因资源变更而触发的重复构建，客户端与运行器进程稳定存活。（证据：清理 `AGC` dev 探针——`tauri dev` 全程 `Rebuilding application` 0 次、`Running DevCommand` 1 次、主 crate 仅编译 1 次，app 起来后持续处理项目；完整 `npm run agc` 在本机被 SpacetimeDB `Pre-publish check`（401 InvalidSignature / 502 Bad Gateway）阻断，属既有本机环境问题。）
|
||||
- [x] 源码不变时连续两次构建，第二次为秒级完成；构建脚本声明的输入中不再出现随包资源路径。（证据：`cargo build --no-default-features` 连续三次 0.69 / 0.22 / 0.22 秒；强制构建脚本重跑后 `resources/codex` 与 `resources/plugins` 快照逐项不变。）
|
||||
- [ ] Windows 与 macOS 打包产物中的随包资源，与迁移前逐项一致（路径、内容摘要、可执行位）。（macOS 侧 `check-macos-bundle.mjs` 待打包验证；Windows 待 M3 归位三处构建期产物后复验。）
|
||||
- [x] 准备步骤连续执行两次不改变产物内容与时间戳；缺少准备步骤时，打包与启动以明确错误失败，而不是静默产出缺组件的包。（证据：准备步骤 10 条用例含幂等、上游缺失、上游元数据漂移与失败关闭；`AGC_SKIP_RESOURCE_STAGING=1` 在既有产物上只读通过；构建脚本校验缺失组件时 fail closed。）
|
||||
- [ ] 本机 Rust 门禁（会触发构建脚本的测试入口）与不打包构建路径仍然可用。（macOS 侧已验；Windows 的 `check:rust:shell` 待真机确认。）
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：构建新鲜度日志、构建脚本输入清单、准备步骤幂等快照、包内资源门禁脚本结果。
|
||||
- 运行时：macOS 与 Windows 各一次客户端启动，确认随包组件被读取而非回退到外部安装。
|
||||
- 边界：缺少准备步骤、缓存命中、上游锁定变化三种情形下的行为。
|
||||
1
|
||||
Reference in New Issue
Block a user