From 756297d2df90d5f99e021463ea880de9d6a57176 Mon Sep 17 00:00:00 2001 From: suzmii Date: Sun, 27 Sep 2026 16:59:42 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=20AGC=20=E9=9A=8F=E5=8C=85?= =?UTF-8?q?=E8=B5=84=E6=BA=90=20staging=20=E5=BD=92=E4=BD=8D=E9=87=8C?= =?UTF-8?q?=E7=A8=8B=E7=A2=91=E4=B8=8E=E9=A6=96=E6=AE=B5=E5=AE=9E=E6=96=BD?= =?UTF-8?q?=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增三份里程碑规范：资源改由校验器读入、生成接入 dev 与发布入口、编辑器分支产物归位与症状层补丁清理 - 新增首个里程碑实施计划：修改边界、实现顺序、验证命令、风险与回滚点、待确认的实现形态 --- ...计划】AGC随包资源改由校验器读入-2026-09-26.md | 62 +++++++++++++++++++ ...辑器分支产物归位与症状层补丁清理-2026-09-26.md | 44 +++++++++++++ ...碑】AGC随包资源改由校验器读入-2026-09-26.md | 44 +++++++++++++ ...AGC随包资源生成接入dev与发布入口-2026-09-26.md | 46 ++++++++++++++ 4 files changed, 196 insertions(+) create mode 100644 docs/project-memory/plans/【实施计划】AGC随包资源改由校验器读入-2026-09-26.md create mode 100644 docs/project-memory/plans/【里程碑】AGC编辑器分支产物归位与症状层补丁清理-2026-09-26.md create mode 100644 docs/project-memory/plans/【里程碑】AGC随包资源改由校验器读入-2026-09-26.md create mode 100644 docs/project-memory/plans/【里程碑】AGC随包资源生成接入dev与发布入口-2026-09-26.md diff --git a/docs/project-memory/plans/【实施计划】AGC随包资源改由校验器读入-2026-09-26.md b/docs/project-memory/plans/【实施计划】AGC随包资源改由校验器读入-2026-09-26.md new file mode 100644 index 000000000..f609c1c72 --- /dev/null +++ b/docs/project-memory/plans/【实施计划】AGC随包资源改由校验器读入-2026-09-26.md @@ -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 重写」二者之一。 diff --git a/docs/project-memory/plans/【里程碑】AGC编辑器分支产物归位与症状层补丁清理-2026-09-26.md b/docs/project-memory/plans/【里程碑】AGC编辑器分支产物归位与症状层补丁清理-2026-09-26.md new file mode 100644 index 000000000..8fcc64b1e --- /dev/null +++ b/docs/project-memory/plans/【里程碑】AGC编辑器分支产物归位与症状层补丁清理-2026-09-26.md @@ -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 上一次完整打包与一次客户端启动，确认编辑器分支产物被读取。 +- 边界：缺少外部工具链、缺少组件、非目标平台三种情形下的失败与跳过语义。 diff --git a/docs/project-memory/plans/【里程碑】AGC随包资源改由校验器读入-2026-09-26.md b/docs/project-memory/plans/【里程碑】AGC随包资源改由校验器读入-2026-09-26.md new file mode 100644 index 000000000..57c6d8e2a --- /dev/null +++ b/docs/project-memory/plans/【里程碑】AGC随包资源改由校验器读入-2026-09-26.md @@ -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 节的合同（准备步骤合同、构建脚本退化后的职责边界）。 +- 现有随包资源与清单已由当前实现产出，可用于校验回归。 + +## 验收标准 + +- [ ] 资源合规时，校验路径可独立运行并通过，不依赖构建脚本的写入分支。 +- [ ] 上游锁定版本、平台、逐文件摘要、必需组件四类不一致各自被拒绝，并给出可定位的原因。 +- [ ] 重复执行资源生成，产物内容与文件时间戳不变（幂等）。 +- [ ] 同一份布局与组件白名单只有一处声明，构建期校验与准备步骤共用。 + +## 证据要求 + +- 自动化：资源校验的通过/拒绝用例；同输入重复生成后目录快照对比（内容 + 时间戳）。 +- 运行时：本机在既有随包资源上运行一次校验与一次构建，确认资源被正常读取且构建行为与改造前一致。 +- 边界：目标平台不支持、上游缺失、摘要不匹配、目录被非本工具内容占用四种场景各自的失败输出。 diff --git a/docs/project-memory/plans/【里程碑】AGC随包资源生成接入dev与发布入口-2026-09-26.md b/docs/project-memory/plans/【里程碑】AGC随包资源生成接入dev与发布入口-2026-09-26.md new file mode 100644 index 000000000..1f70aa288 --- /dev/null +++ b/docs/project-memory/plans/【里程碑】AGC随包资源生成接入dev与发布入口-2026-09-26.md @@ -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 各一次客户端启动，确认随包组件被读取而非回退到外部安装。 +- 边界：缺少准备步骤、缓存命中、上游锁定变化三种情形下的行为。