Merge remote-tracking branch 'origin/master' into fix/agc-acceptance-followup
Project CI / AI game creator shell Rust shard 2/4 (pull_request) Failing after 19s
Project CI / AI game creator shell Rust shard 4/4 (pull_request) Failing after 19s
Project CI / AI game creator shell Rust shard 3/4 (pull_request) Failing after 19s
Project CI / AI game creator shell Rust shard 1/4 (pull_request) Failing after 19s
Project CI / AI game creator shell Rust smoke (pull_request) Failing after 19s
Project CI / Native shell tests (pull_request) Failing after 19s
Project CI / AI game creator shell Rust crates (pull_request) Failing after 19s
Project CI / Backend tests (pull_request) Failing after 19s
Project CI / Frontend tests (pull_request) Failing after 7s
Project CI / AI game creator shell web tests (pull_request) Failing after 14s
Project CI / Repository checks (pull_request) Failing after 15s
Project CI / AI game creator shell Rust shard 2/4 (pull_request) Failing after 19s
Project CI / AI game creator shell Rust shard 4/4 (pull_request) Failing after 19s
Project CI / AI game creator shell Rust shard 3/4 (pull_request) Failing after 19s
Project CI / AI game creator shell Rust shard 1/4 (pull_request) Failing after 19s
Project CI / AI game creator shell Rust smoke (pull_request) Failing after 19s
Project CI / Native shell tests (pull_request) Failing after 19s
Project CI / AI game creator shell Rust crates (pull_request) Failing after 19s
Project CI / Backend tests (pull_request) Failing after 19s
Project CI / Frontend tests (pull_request) Failing after 7s
Project CI / AI game creator shell web tests (pull_request) Failing after 14s
Project CI / Repository checks (pull_request) Failing after 15s
This commit is contained in:
@@ -0,0 +1,61 @@
|
||||
# 【实施计划】AGC 资源 kind Rust 枚举与 ts-rs 绑定
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Milestone | `docs/project-memory/plans/【里程碑】AGC资源kind枚举化Rust绑定与内部收紧-2026-09-15.md` |
|
||||
| Status | complete |
|
||||
| Owner | Codex |
|
||||
|
||||
## 修改边界
|
||||
|
||||
允许修改：
|
||||
|
||||
- `server-rs/crates/shared-contracts` 内 GameCreationApp 资源 kind 的独立 Rust 模块；
|
||||
- shared-contracts 的可选 ts-rs 绑定 feature；
|
||||
- ai-game-creator-shell 的 shared-contracts feature 引用和生成测试入口；
|
||||
- shell 内生成的 GameCreationApp kind TypeScript 文件；
|
||||
- 对应 Rust/TS 定向测试与文档 todo 证据。
|
||||
|
||||
本切片已落地：
|
||||
|
||||
- `GameCreationAppAssetManifestEntry.kind` 由 `String` 收紧为 `GameCreationAppAssetKind`：这是公开 Rust 类型的破坏性变更，按「不写历史兼容代码」直接改类型，不加兼容层、不做数据迁移；manifest 反序列化未知值收口为 `Unknown`。
|
||||
- 上传内容推断的字体写入 `Font`，未知上传类型写入 `Unknown`；图集切片 manifest 写入 `Icon`。
|
||||
- shell 内 manifest kind 的写入侧与读取侧统一为正式枚举成员：资源登记、字体导入、direct runtime 产物、平台美术登记与恢复、manifest 必填校验、资源编辑派生、UI 设计桥接与工作流。
|
||||
- 资源编辑请求的 `sourceSubtype` 只传正式枚举成员；资源编辑内部源身份拆成「正式 kind / 项目版本 / Agent 回执」三类，项目版本与 Agent 回执不再冒充 manifest kind。
|
||||
- ts-rs 绑定改由 `cargo test export_bindings` 生成：枚举自带 `#[ts(export, export_to = …/src/contracts/generated/)]`；退役的 `BindingDTO` / `BindingChange` 不再导出，手写的 `exports_ui_editor_types` 已删除。
|
||||
- `packages/shared/src/contracts/generated/` 作为受控生成目录在 `.prettierrc.json` 中使用与 ts-rs 原始输出一致的格式选项，并在 `.gitattributes` 标记为 `linguist-generated`；生成文件仍参与 Prettier/ESLint 检查，`cargo test export_bindings` 可幂等复现且不再污染工作树。
|
||||
- `Unknown` 表示解析边界无法判定的输入；写入方可以保留该结果，但必须明确决定拒绝写入或交由后续归类，不得把它误写成某个具体 kind。
|
||||
- shell TS 资源引用边界消费生成绑定，资源 kind 集合从生成的 union 穷举派生，并为未知值保留原始值与上下文日志。
|
||||
- api-server 图片快速编辑来源校验改为严格解析 `GameCreationAppAssetKind`，只允许共享枚举的静态图片成员；删除原有 legacy/兼容字符串白名单，退役值不再放行。
|
||||
|
||||
明确不修改：
|
||||
|
||||
- `category`、`mediaType`、`source.kind`、`source.generationKind`；
|
||||
- api-server 的其他资源 taxonomy、SpacetimeDB schema、OpenAPI；本切片只改图片快速编辑的 GameCreationApp manifest 来源校验。
|
||||
- shared-contracts 的 canonical alias 表与读时自愈：alias 表已删除，严格解析和 `Unknown` 口径保持不变；
|
||||
- `packages/shared` 中重复的资源 kind 手写契约与其余前端裸 `string` 字段（后续切片）。
|
||||
|
||||
## 实现顺序
|
||||
|
||||
1. 新建独立 kind 模块，定义当前正式成员：17 个现有 canonical kind + `font` + `Unknown`，serde 使用 kebab-case。
|
||||
2. 为 enum 增加可选 ts-rs derive，默认 shared-contracts 构建不引入 ts-rs。
|
||||
3. 让 shell 的 shared-contracts 依赖打开绑定 feature；生成目录 2026-09-17 起收敛到 `packages/shared/src/contracts/generated/`（kind 是跨端契约，不再放 shell 私有目录）。
|
||||
4. 增加 Rust serde round-trip 与 Unknown 解析/序列化测试；TS 侧不再手写生成值集合，改为从生成 union 穷举派生。
|
||||
未知值通过 `parse_with_context` 收口到 `Unknown`，并把原始值与解析上下文交给壳层注册的 `app_log!` 回调（2026-09-17 起不再用 `tracing` / `kind-observability`）。
|
||||
5. 运行 shared-contracts 与 shell 定向测试，并用 `export_bindings` 复现生成文件；完成后将稳定结论回写里程碑并关闭本计划。
|
||||
|
||||
## 验证命令
|
||||
|
||||
1. `cargo fmt --all -- --check`
|
||||
2. `cargo test --locked -p shared-contracts game_creation_app --manifest-path server-rs/Cargo.toml`
|
||||
3. `cargo test --locked -p shared-contracts --features ts-bindings export_bindings --manifest-path server-rs/Cargo.toml`（生成 `packages/shared/src/contracts/generated/GameCreationAppAssetKind.ts`）
|
||||
4. `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml export_bindings`（生成 shell 自己的 ts-rs 绑定）
|
||||
5. `npx vitest run apps/ai-game-creator-shell/tests/assetKind.test.ts packages/shared/src/contracts/gameCreationApp.test.ts`（解析 Rust 源码的 `assetKindCanonicalMapping.test.ts` 2026-09-17 已删除：手写词汇表被移除后它没有比对对象）
|
||||
6. `npm run check:encoding`
|
||||
7. `git diff --check`
|
||||
|
||||
## 风险与回滚点
|
||||
|
||||
- 风险：ts-rs 默认生成 enum/union 形态与 serde rename 不一致；必须以生成文件和 round-trip 测试为准。
|
||||
- 风险：shared-contracts 被 SpacetimeDB/WASM 使用；ts-rs 必须是 optional feature，默认构建不可依赖。
|
||||
- 回滚点：本切片仅新增 enum/绑定，不改变现有 manifest JSON 解析；若生成链路不稳定，可回滚本提交而不影响现有业务。
|
||||
@@ -0,0 +1,43 @@
|
||||
# 【实施计划】AGC 资源 kind 词汇审计与绑定架构
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Milestone | `docs/project-memory/plans/【里程碑】AGC资源kind枚举化词汇审计与绑定架构-2026-09-15.md` |
|
||||
| Status | complete |
|
||||
| Owner | Codex |
|
||||
|
||||
## 修改边界
|
||||
|
||||
允许修改：
|
||||
|
||||
- 主规范中的资源 kind 当前口径；
|
||||
- `docs/project-memory/plans/` 下本任务的里程碑/实施计划；
|
||||
- `docs/project-memory/todos/` 下本任务的扫描清单；
|
||||
- 为审计提供只读扫描脚本（如确有必要，脚本也只覆盖 shell）。
|
||||
|
||||
明确不修改：
|
||||
|
||||
- 已完成的 `apps/ai-game-creator-shell` 业务收口不再属于未决范围；后续只允许按新里程碑变更；
|
||||
- server-side 代码、OpenAPI、SpacetimeDB schema；
|
||||
- MIME、`source.kind`、`generationKind` 和其他字符串领域。
|
||||
|
||||
## 实现顺序
|
||||
|
||||
1. 按“manifest asset kind / 其他字段 / 仅文本同名”三类扫描 shell 的 `kind`、`assetKind`、`asset_kind` 和 manifest 构造器。
|
||||
2. 对每个候选值回到调用上下文，标记生产写入、读取投影、协议输入、测试 fixture 或纯文本/路径。
|
||||
3. 对照 api-server 当前有效资源 kind，排除 legacy、billing/storage synthetic taxonomy 和开放字段。
|
||||
4. 记录正式候选 enum、Unknown 输入行为、保留字符串字段和后续 PR 边界。
|
||||
5. 形成下一里程碑的文件级修改顺序和验证矩阵；本里程碑结束后暂停，等待验收。
|
||||
|
||||
## 验证命令
|
||||
|
||||
1. `rg -n 'kind|assetKind|asset_kind' apps/ai-game-creator-shell/src apps/ai-game-creator-shell/src-tauri/src`
|
||||
2. `npm run check:doc-index`
|
||||
3. `npm run check:encoding`
|
||||
4. `git diff --check`
|
||||
|
||||
## 风险与回滚点
|
||||
|
||||
- 风险：同一字符串可能是 manifest kind、workflow kind 或路径名；任何未回到上下文确认的替换都禁止进入代码。
|
||||
- 风险：shared-contracts 被多个 server crate 使用；ts-rs 生成必须通过 feature/独立入口隔离默认构建。
|
||||
- 回滚点：本里程碑只有文档和审计清单变更；若词汇边界未能闭合，删除本计划和 todo，不进入代码里程碑。
|
||||
@@ -28,8 +28,8 @@
|
||||
|
||||
1. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_thread -- --nocapture`
|
||||
2. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml export_bindings`（生成 `src/features/project-workspace/generated/`），随后用 `prettier --write` 格式化生成目录，避免未格式化的 ts-rs 输出混进提交
|
||||
3. `npx vitest run apps/ai-game-creator-shell/tests/directThreadChat.test.ts apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts apps/ai-game-creator-shell/tests/directHistoryPaging.test.ts`
|
||||
4. `npx vitest run apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`
|
||||
3. `npm run test -- apps/ai-game-creator-shell/tests/directThreadChat.test.ts apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts apps/ai-game-creator-shell/tests/directHistoryPaging.test.ts apps/ai-game-creator-shell/tests/directHistoryAnchorGate.test.ts`
|
||||
4. `npm run test -- apps/ai-game-creator-shell/tests/appSurface.test.ts`（`project-development.suite.ts` 由该入口注册，不能作为独立测试入口；同时验证现役 Design Agent 的会话恢复与审批界面。）
|
||||
5. TypeScript 类型检查与 ESLint（范围同前次 DirectProject 迁移）。
|
||||
6. `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
|
||||
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# 【实施计划】UI设计文档引用代码上下文
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1 |
|
||||
| Status | ready |
|
||||
| Owner | Codex |
|
||||
| Milestone | `docs/project-memory/plans/【里程碑】UI设计文档引用代码上下文-2026-09-14.md` |
|
||||
|
||||
## 修改边界
|
||||
|
||||
允许修改：
|
||||
|
||||
- UI Editor persistence/resource bridge/workflow/command 中的 UI JSON 文档 kind 常量与校验。
|
||||
- `packages/shared` 的 canonical kind 与 Rust 对应映射。
|
||||
- `agent/direct_codex_user_item/wire.rs` 的 UI 引用 prompt 生成。
|
||||
- 相关 Rust、TypeScript 测试和当前 UI workflow/AGC 文档。
|
||||
- `decision-log.md` 的长期决策记录。
|
||||
|
||||
明确不修改：
|
||||
|
||||
- `ui-prototype` 图片生成和图片 workflow 语义。
|
||||
- UI State schema、`render_ui_design_state_js` 输出格式和 `ui/generated-*.js` 路径规则。
|
||||
- SpacetimeDB schema、External v1 OpenAPI、非 Direct Codex Supervisor 引用行为。
|
||||
- 用户已有 `.env` 未提交修改。
|
||||
|
||||
## 实现顺序
|
||||
|
||||
1. 更新 UI workflow 主规范与项目决策，明确 `ui-design-doc` 与 `ui-prototype` 的身份边界。
|
||||
2. 在 persistence 提取并导出 UI 文档 kind/media 常量，替换 Rust UI 文档校验。
|
||||
3. 同步所有 UI JSON 资源生产者、workflow 校验、命令筛选、shared contract 与前端 bridge。
|
||||
4. 在 Direct Codex 引用渲染中调用 `generate_ui_design_code_at`；成功追加生成文件相对路径，失败追加原始错误并继续发送。
|
||||
5. 补充旧 kind、图片、成功、文档错误、多引用和 renderer 输出的测试。
|
||||
6. 执行定向验证，复核 diff 中无 fallback、迁移或无关 `.env` 修改。
|
||||
|
||||
## 验证命令
|
||||
|
||||
1. `cargo fmt --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --check`
|
||||
2. `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml ui_editor::persistence`
|
||||
3. `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_codex_user_item`
|
||||
4. 相关 shared contract Vitest 测试与前端类型检查
|
||||
5. `npm run check:doc-index`
|
||||
6. `npm run check:encoding`
|
||||
7. `git diff --check`
|
||||
|
||||
## 风险与回滚点
|
||||
|
||||
- `ui-prototype` 与 UI JSON 文档共用部分分类展示逻辑，需确保分类映射不会让图片进入文档分支。
|
||||
- `generate_ui_design_code_at` 会持有项目写锁；多引用必须顺序调用，不能并行写同一项目。
|
||||
- 生成失败继续发送是已确认语义；测试必须证明错误文本进入 prompt 而不是被转成聊天失败。
|
||||
- 若发现生产者仍写入旧 `UI`，按开发阶段合同直接修生产者和 fixture，不增加运行时兼容分支。
|
||||
@@ -0,0 +1,92 @@
|
||||
# 【实施计划】退役策划 Agent V1/V2 解耦清理
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Milestone | `docs/project-memory/plans/【里程碑】退役策划Agent V1V2解耦清理-2026-09-15.md` |
|
||||
| Status | ready |
|
||||
| Owner | Codex |
|
||||
|
||||
## 一句话交付结果
|
||||
|
||||
删除退役策划 V1/V2 及其耦合的 Supervisor 产品残留，让当前 Design Agent 独立运行、做游戏走 DirectCodex 并恢复仓库编译；保留通用 Supervisor 和做游戏 16 Agent DAG。
|
||||
|
||||
## 验收判据
|
||||
|
||||
当前分支能够通过 AGC 前端 typecheck 和受影响定向测试；Design Agent 的新建、恢复、澄清、阶段审批和 reasoning 展示仍由当前 Design Agent 链路完成；旧 V2 IPC、旧 GDD 类型和旧前端测试契约不再存在。
|
||||
|
||||
## 修改边界
|
||||
|
||||
允许修改：
|
||||
|
||||
- `apps/ai-game-creator-shell/src/App.tsx` 中旧 V2 状态、helper、IPC 分支和旧 UI props。
|
||||
- `apps/ai-game-creator-shell/src/app/types.ts` 中旧 GDD 类型。
|
||||
- `apps/ai-game-creator-shell/src/features/project-workspace/planningSessionV2.ts` 及其直接调用方。
|
||||
- `apps/ai-game-creator-shell/tests/appSurface/harness.ts`、`home.suite.ts`、旧策划事件测试。
|
||||
- `apps/ai-game-creator-shell/src/styles.css` 中只属于旧 Plan GDD / planning lane 的样式。
|
||||
- 没有现役调用方的旧策划身份 fixture、注释和文档索引。
|
||||
- 为通过编译所需的最小共享残留删除或改名。
|
||||
|
||||
明确不修改：
|
||||
|
||||
- `directCodex` 主链路和当前 Design Agent。
|
||||
- 16 Agent DAG、`supervisor-swarm` 测试和通用 Runtime 编排；只处理删除策划耦合后直接造成的编译错误。
|
||||
- 当前 Design Agent Rust runtime、Design Agent 资源包和 Design Agent IPC 协议。
|
||||
- 公开 API、SpacetimeDB schema、迁移和历史持久化数据格式。
|
||||
|
||||
## 实现顺序与提交拆分
|
||||
|
||||
### 提交一：解耦 Design Agent 状态命名
|
||||
|
||||
- 将新版 Design Agent 实际使用的 `planningV2*` transient reply、reasoning、active ref 和相关 lane 控制改成 Design Agent 专属状态。
|
||||
- 保持行为不变，不删除旧 V2 会话代码。
|
||||
- 验证：AGC typecheck、`git diff --check`。
|
||||
|
||||
### 提交二：删除 App 旧 V2 会话控制流
|
||||
|
||||
- 删除仅服务旧策划的 Supervisor 产品入口、恢复、轮询和聊天提交分支。
|
||||
- 删除旧 V2 session/GDD 状态和 helper。
|
||||
- 删除项目打开、消息发送、问询回答、审批和旧流式事件分支。
|
||||
- 将“做方案”只连接到当前 Design Agent hydrate/continue/decide 路径，将“做游戏/做素材”只连接到 DirectCodex。
|
||||
- 保留 `planningStartMode` 作为入口路由字段，避免无关扩大重命名。
|
||||
- 验证：AGC typecheck；必要时运行 App 启动相关定向 suite。
|
||||
|
||||
### 提交三：删除旧 TypeScript 适配层和类型
|
||||
|
||||
- 删除 `planningSessionV2.ts`。
|
||||
- 删除 `PlanGddDecisionAction`、`PlanGddStateViewV1` 及所有直接导入。
|
||||
- 重新执行旧符号检索，确认没有残留调用方。
|
||||
- 验证：AGC typecheck、`npm run check:encoding`、`git diff --check`。
|
||||
|
||||
### 提交四：清理测试、事件契约和 CSS
|
||||
|
||||
- 精确删除 harness 中旧 V2/GDD 工厂、mock、调用记录和导出。
|
||||
- 精确删除首页 suite 中旧 V2 IPC 断言。
|
||||
- 删除旧 `planning-session-v2-stream` 事件测试。
|
||||
- 删除 Plan GDD、GDD 审批卡和 planning lane 专属 CSS 及过时说明。
|
||||
- 验证：appSurface 定向测试、事件订阅定向测试、AGC typecheck、编码和 diff 检查。
|
||||
|
||||
### 提交五：收口确定失效的身份残留和文档入口
|
||||
|
||||
- 只处理因 V1/V2 退役而确定失效的旧身份展示、测试 fixture、注释和文档索引。
|
||||
- 不扫描或重构做游戏 DAG；共享代码只在其旧策划用途已确定死且删除能直接解决编译/测试问题时处理。
|
||||
- 验证：旧策划符号定向检索、相关测试、编码和 diff 检查。
|
||||
|
||||
## 验证命令
|
||||
|
||||
1. `npm --prefix apps/ai-game-creator-shell run typecheck`
|
||||
2. `npm run check:encoding`
|
||||
3. `git diff --check`
|
||||
4. `npm --prefix apps/ai-game-creator-shell exec vitest run tests/appSurface.test.ts`
|
||||
5. 受影响 Rust 文件变化后运行 `cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`
|
||||
6. 完成全部提交后再次执行旧策划符号检索，并核对 `git status` 与提交边界
|
||||
|
||||
## 风险与回滚点
|
||||
|
||||
- 最大风险是新版 Design Agent 复用了旧变量名；必须先完成提交一，再删除旧 helper。
|
||||
- `ProjectSupervisorView` 已经移除旧 GDD props，App 传参残留会在提交二中一并删除。
|
||||
- 测试 harness 同时服务通用总控和 Design Agent，必须局部删除旧 mock，不能整段重写。
|
||||
- 若某次提交导致 Design Agent 测试失败，只回滚该独立提交，不恢复旧 V2 兼容层。
|
||||
|
||||
## 完成后的临时文档处理
|
||||
|
||||
全部里程碑验收通过后，删除本里程碑和实施计划两份临时文档；把仍然有效的长期边界同步回现行 Design Agent 技术方案和项目记忆，不保留阶段性提交步骤。
|
||||
@@ -0,0 +1,21 @@
|
||||
# 关联里程碑
|
||||
|
||||
`【里程碑】退役策划V2 Rust Runtime清理-2026-09-14.md`
|
||||
|
||||
# 修改顺序
|
||||
|
||||
1. 从 `runtime_protocol.rs` 移除 V2 模块声明与导出。
|
||||
2. 从 `main.rs` / `commands.rs` 移除 V2 command 注册和仅供 V2 的导入。
|
||||
3. 删除 V2 Rust 模块及其专属单元测试；保留共享 GDD 模型或新版设计会话仍使用的类型。
|
||||
4. 用 `rg` 检查 V2 Rust 符号残留，修复编译引用。
|
||||
|
||||
# 验证命令
|
||||
|
||||
- `cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`
|
||||
- `npm run check:encoding`
|
||||
- `git diff --check`
|
||||
|
||||
# 风险与回滚
|
||||
|
||||
- 风险：V2 类型可能被共享测试或前端桥接代码引用。处理方式是按编译错误逐项判断，保留真正共享类型。
|
||||
- 回滚：按提交粒度回退本里程碑提交，不触碰前序 V1 清理提交。
|
||||
@@ -0,0 +1,32 @@
|
||||
# 项目自动上传与后台工程下载实施计划
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Milestone | `docs/project-memory/plans/【里程碑】项目自动上传与后台工程下载-2026-09-19.md` |
|
||||
| Status | implemented-awaiting-runtime-validation |
|
||||
| Owner | 当前任务 Agent |
|
||||
|
||||
## 修改边界
|
||||
|
||||
- 客户端 project_snapshot 与实际窗口生命周期、相关定向测试。
|
||||
- shared-contracts 快照清单及后台 DTO、platform-oss 的受控清单枚举、api-server 管理员列表与 ZIP 下载、后台权限映射。
|
||||
- api-server 快照存储配置解析：默认目标与素材 bucket 分离，只有凭据可回退；不变更部署配置或搬迁对象。
|
||||
- admin-web 项目列表、现有路由/导航/API client 与相应测试。
|
||||
- 主规范、运维说明及必要共享约定。不修改 SpacetimeDB、External API、用户会话权威或线上配置。
|
||||
|
||||
## 实现顺序
|
||||
|
||||
1. 评审主规范与本里程碑，复现客户端项目枚举故障。
|
||||
2. 并行实现后台列表/ZIP、后台 UI；客户端只修已证实上传缺陷并补清单元数据。
|
||||
3. 集成契约、运行定向测试和 UI smoke，核查真实清单可还原目录；按证据更新验收状态。
|
||||
|
||||
## 验证命令
|
||||
|
||||
- `cargo test --locked -p platform-oss`、`cargo test --locked -p api-server project_snapshot`、`cargo test --locked -p shared-contracts`（server-rs）。
|
||||
- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_snapshot`。
|
||||
- `npm run admin-web:typecheck`、`npm run admin-web:build`、后台相关 Vitest。
|
||||
- `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
|
||||
|
||||
## 风险与回滚
|
||||
|
||||
旧清单无完整性声明，只能标记未知；完整工程含项目源码、素材和配置，排除依赖/构建缓存、凭据、会话与运行日志。下载失败不修改 OSS 或清单。本轮按用户授权提交推送，不部署；代码可独立回退。
|
||||
@@ -0,0 +1,37 @@
|
||||
# 里程碑：AGC 总版本号落地
|
||||
|
||||
状态：进行中（主规范已定稿，代码与 CI 已实现，等待首次真实统一构建验收）
|
||||
|
||||
## 关联文档
|
||||
|
||||
- 主规范：`docs/technical/【技术方案】AGC总版本号与发号-2026-09-20.md`
|
||||
|
||||
## 交付物
|
||||
|
||||
1. 发号模块与入口：`agc-global-version.mjs`、`issue-global-version.mjs`、`agc-global-version.test.mjs`。
|
||||
2. 构建侧改动：`build-release.mjs` 的 `prepareReleaseVersion()` 采用总号，高水位降级为断言。
|
||||
3. CI：发号 Job（`Jenkinsfile.agc-global-version-issue` + job config）、调度管线与手动管线接入发号 Job。
|
||||
4. 文档与项目记忆更新。
|
||||
|
||||
## 实现顺序与门禁
|
||||
|
||||
| 步骤 | 内容 | 门禁 |
|
||||
| --- | --- | --- |
|
||||
| 1 | 发号模块 + 单元测试 | `node --test apps/ai-game-creator-shell/scripts/agc-global-version.test.mjs` 全绿 |
|
||||
| 2 | 构建侧接入总号与断言 | `build-release.test.mjs` / `release-oss.test.mjs` / `cargo-features.test.mjs` 全绿 |
|
||||
| 3 | 发号 Job 与管线接入 | `npm run check:production-ops`、`npm run check:encoding` 通过 |
|
||||
| 4 | 一次性播种 | 发号 Job 勾选 `SEED_ONLY` 写入基线，回读一致 |
|
||||
| 5 | 首次统一构建 | dev-win 与 dev-mac 清单版本相同且等于总号 |
|
||||
| 6 | 单渠道热修回归 | 只有该渠道清单变化，总号 +1 |
|
||||
|
||||
## 当前证据
|
||||
|
||||
- `agc-global-version.test.mjs`：7/7 通过（播种基线、首发、递增、dry-run 不烧号、回退断言、并发写后回读失败关闭、patch 递增）。
|
||||
- AGC 相关脚本合跑：32/32 通过。
|
||||
- 真实 OSS 只读预览：`--dry-run --channel unified` 输出 `AGC_GLOBAL_VERSION=0.1.77`（基线 0.1.76，未写回）。
|
||||
- `npm run check:production-ops`、`npm run check:encoding` 通过。
|
||||
|
||||
## 未完成项
|
||||
|
||||
- 首次真实播种与统一构建尚未执行（避免在功能未合并前烧号）。
|
||||
- `feat/jenkins-mac-build` 分支上的 macOS 管线仍用旧的自增高水位逻辑；该分支合并 master 后才继承本方案的模块与断言，合并前 dev-mac 必须由发号 Job 显式传入 `AGC_RELEASE_VERSION`。
|
||||
@@ -0,0 +1,40 @@
|
||||
# 【里程碑】AGC 资源 kind 枚举化 Rust 绑定与内部收紧
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | complete |
|
||||
| Date | 2026-09-15 |
|
||||
| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` |
|
||||
|
||||
## 目标
|
||||
|
||||
将 GameCreationApp 资源 kind 从 shell 内裸字符串收紧为 Rust `GameCreationAppAssetKind`，并生成 shell 专属 TypeScript 绑定；所有同语义内部字段使用该类型，未知输入解析为 `Unknown` 并记录日志。
|
||||
|
||||
## 范围
|
||||
|
||||
- Rust enum、serde kebab-case、`Unknown` 与 category 派生边界。
|
||||
- ts-rs feature-gated 生成入口、生成文件和 verify 门禁。
|
||||
- `packages/shared/src/contracts/gameCreationApp.ts` 中重复的资源 kind 手写契约迁入 shell 生成绑定后的删除/收口。
|
||||
- shell 内资源 kind 参数、投影、筛选、Agent 资源引用和 manifest 读写边界的类型收紧。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- server-side 其他 `asset_kind`、External API DTO、SpacetimeDB schema；仅纳入 api-server 图片快速编辑对 GameCreationApp manifest 来源的严格校验。
|
||||
- `source.kind`、`generationKind`、MIME 和文件格式。
|
||||
- 其他领域字段为配合本里程碑进行“顺手枚举化”。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- 词汇审计里程碑通过并关闭所有阻塞项。
|
||||
- 生成目录、TS 导入路径、Unknown 日志字段和 writer 禁止主动写 Unknown 的规则已确认。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] Rust enum 与生成的 TS 绑定值逐项一致，JSON 使用 kebab-case；正式资源成员为当前 17 个 canonical kind 加 `font`，另有 `Unknown` 解析成员。TS 侧不再手写值集合，改为对生成 union 做穷举 `Record`。
|
||||
- [x] 未知输入得到 `Unknown`，日志包含原始值与调用上下文（`parse_with_context` + 壳层在 `main()` 注册的 `app_log!` 回调，见 2026-09-17 收敛）。
|
||||
- [x] 生产 writer 不再接受裸 `string` 作为 GameCreationApp kind（manifest 写入、资源登记、direct runtime、平台美术登记、资源编辑派生均只传枚举成员）；`Unknown` 仅表示解析边界无法判定，调用方可拒绝或交后续归类。
|
||||
- [x] `font`、`audio`、`sound-effect`、`background-music` 均有真实生产路径（字体导入、上传音频推断、资源编辑音频派生）。
|
||||
- [x] ts-rs 绑定由 `cargo test export_bindings` 生成，生成目录加入 `.prettierignore` / eslint `ignorePatterns`，可幂等复现且不污染工作树。
|
||||
- [x] 退役的 `BindingDTO` / `BindingChange` 不再导出，手写的 `exports_ui_editor_types` 已删除。
|
||||
- [x] 旧 alias 不再由共享契约把非 canonical 输入收口成 canonical；api-server 图片快速编辑不再保留 legacy 兼容白名单，非 canonical 来源直接失败。
|
||||
@@ -0,0 +1,37 @@
|
||||
# 【里程碑】AGC 资源 kind 枚举化写入方清理与验证
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | complete |
|
||||
| Date | 2026-09-15 |
|
||||
| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` |
|
||||
|
||||
## 目标
|
||||
|
||||
逐处修正 shell 内仍产生非正式 GameCreationApp kind 的生产代码；保留仅属于 workflow、generation、路径或其他领域的字符串，并为这些边界补充清晰类型/命名说明而不扩大本 PR。
|
||||
|
||||
## 范围
|
||||
|
||||
- manifest 登记、恢复、回填、资源替换、画板/图集导出、字体导入、上传推断和 Agent 资源登记。
|
||||
- shell 前端资源投影、筛选和资源引用消费方。
|
||||
- 删除 alias/fallback 生产逻辑及其只服务于旧值的测试。
|
||||
- 对仍保留的 workflow、generation、路径和其他领域字符串完成边界核对，不将其重新解释为 manifest kind。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 不改 `source.kind`、`generationKind` 等其他字段，即使它们恰好使用同名值。
|
||||
- 不修改 server-side 代码或公开 API。
|
||||
- 不实现字体格式/MIME enum；`font` 只作为本次 manifest asset kind 成员。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- Rust/TS 绑定里程碑通过。
|
||||
- 写入方扫描清单中每个 alias 都已有“manifest kind / 其他领域 / 删除”结论。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] 新建、导入、生成、恢复、替换路径不会写入未纳入 enum 的 manifest kind。
|
||||
- [x] 未知外部值只进入 `Unknown` 并有 trace；缺失输入的中性默认仅由明确登记入口决定。
|
||||
- [x] `source.kind` 与 `generationKind` 的既有字符串行为不变。
|
||||
- [x] 定向 Rust、TS、绑定生成、编码和 diff 检查通过。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 【里程碑】AGC 资源 kind 枚举化词汇审计与绑定架构
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | complete |
|
||||
| Date | 2026-09-15 |
|
||||
| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` |
|
||||
|
||||
## 目标
|
||||
|
||||
在 `apps/ai-game-creator-shell` 内建立唯一的 GameCreationApp 资源 kind 领域边界：Rust enum 是权威，TypeScript 由 `ts-rs` 生成；先完成全量词汇审计和生成架构合同，再进入业务代码替换。
|
||||
|
||||
## 范围
|
||||
|
||||
- 审计 shell 内所有可能表示 GameCreationApp 资源 kind 的字段、构造器、写入边界、筛选器、资源投影、Agent 资源引用和测试 fixture，并收紧 api-server 图片快速编辑的 manifest 来源边界。
|
||||
- 以 api-server 当前仍有效的同语义 kind 作为命名与 serde 值参考，并评估 shell 当前实际生产 kind；排除 api-server legacy、billing/storage taxonomy 和其他开放领域。
|
||||
- 确认 Rust enum、`Unknown`、kebab-case JSON 和 ts-rs 生成文件的归属、生成命令与校验门禁。
|
||||
- 形成逐项 todo：当前值、真实语义、生产/测试状态、目标 enum、是否改写、验证方式。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 不扫描或修改 api-server 其他领域的 `asset_kind`；图片快速编辑来源校验属于本次 GameCreationApp manifest 边界，必须复用共享枚举且不得保留 legacy 白名单。
|
||||
- 不改 `mediaType`、MIME、文件扩展名、`source.kind`、`source.generationKind`、任务/工作流 kind、路径名或 tracking scope。
|
||||
- manifest writer 与前端消费方已统一到共享 Rust enum/ts-rs binding；不扩展公开契约。
|
||||
- 不实现旧 manifest migration；无法解析的输入只在共享解析边界收口为 `Unknown`，由调用方拒绝或交后续归类，不增加 alias 表或 fallback。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- 主规范已确认资源 kind 候选集合、`Unknown` 语义和 shell 边界。
|
||||
- `shared-contracts` 当前被 server-rs 多个 crate 使用，ts-rs 生成能力必须 feature-gated 或由独立生成入口启用，不能污染默认 SpacetimeDB/WASM 构建。
|
||||
- 当前已有 Tauri ts-rs 生成测试可作为生成命令形态参考，但不复用 UI Editor 类型目录作为资源契约目录。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] shell 内 manifest 资源 kind 的生产写入点、解析点、投影点和测试 fixture 已完成审计并收口。
|
||||
- [x] 每个旧值均已标注为：正式 GameCreationApp kind、其他领域字符串、legacy/错误 fallback；没有只按 grep 结果猜测的条目。
|
||||
- [x] api-server 有效值、shell 扩展值和排除值各有明确依据。
|
||||
- [x] 生成架构不会要求 server-side 默认构建安装 ts-rs。
|
||||
- [x] todo 清单的每项都有关闭条件和对应验证证据；图片快速编辑不再维护兼容白名单，退役 kind 直接失败。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：raw kind 扫描脚本/报告、Rust/TS 生成试验、serde kebab-case round-trip 试验。
|
||||
- 文档：主规范、todo 清单、下一里程碑实施计划互相链接且无冲突。
|
||||
- 边界：至少覆盖 `font`、`audio`、`sound-effect`、`background-music`、`Unknown`，以及 `source.kind`/`generationKind` 不误收编。
|
||||
@@ -0,0 +1,49 @@
|
||||
# 【里程碑】UI设计文档引用代码上下文
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1 |
|
||||
| Status | in-progress |
|
||||
| Date | 2026-09-14 |
|
||||
| Parent Spec | `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md` |
|
||||
|
||||
## 目标
|
||||
|
||||
将可编辑 UI JSON 文档统一识别为 `ui-design-doc`，并在 Direct Codex 聊天引用该文档时复用 UI Editor 现有代码导出流程，为 LLM 提供生成的、带文档注释的 JS 代码路径或原始生成错误。
|
||||
|
||||
## 范围
|
||||
|
||||
- UI JSON 文档资产身份固定为 `kind=ui-design-doc`、`mediaType=application/json`。
|
||||
- 复用 `ui_editor::persistence::generate_ui_design_code_at` 读取并校验文档、调用 `render_ui_design_state_js`、写入 `ui/generated-*.js`。
|
||||
- Direct Codex 引用文本保留稳定 manifest 元数据，并追加代码路径或 `生成代码遇到错误{error}`。
|
||||
- 同步 Rust/TypeScript 的 UI 文档生产者、消费者、分类映射和测试。
|
||||
- `ui-prototype` 图片继续作为独立源图片类型。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 不接受旧 `UI`、`ui`、`ui-design` 作为 UI 文档类型。
|
||||
- 不增加兼容 fallback、数据迁移或旧数据转换逻辑。
|
||||
- 不把 `ui-prototype` 图片当作 UI 文档，不从图片生成替代 JSON 文档代码。
|
||||
- 不改变 UI State schema、renderer 输出格式、项目 revision 或 manifest 阶段。
|
||||
- 不改变旧 Supervisor 非 Direct Codex 引用链路。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- `generate_ui_design_code_at` 已存在并返回 `relative_path`。
|
||||
- `render_ui_design_state_js` 已生成包含文档注释的 JS 模块。
|
||||
- Direct Codex 结构化引用已传递 `resourceId`，manifest 是资源身份权威。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] UI 编辑器 JSON 资源创建、加载、保存、workflow 校验和引用分支均只接受 `ui-design-doc + application/json`。
|
||||
- [ ] Direct Codex 成功引用 UI 文档时，prompt 追加 `请先阅读生成的带有文档的代码片段: {relative_path}`。
|
||||
- [ ] UI 文档生成失败时，prompt 保留原 metadata 并追加 `生成代码遇到错误{error}`，不走图片或其它文件 fallback。
|
||||
- [ ] `ui-prototype` 图片引用不触发 UI 文档代码生成。
|
||||
- [ ] 多个引用按顺序处理，单个 UI 文档失败不丢失其它引用。
|
||||
- [ ] Rust/TypeScript kind 映射一致，旧 kind 不被隐式迁移。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：persistence、direct_codex_user_item、shared contract 定向测试；`cargo fmt --check`、`npm run check:encoding`、`git diff --check`。
|
||||
- 运行时：不要求真实 Provider；测试验证生成文件路径、renderer 文档注释和 prompt 注入结果。
|
||||
- 边界：旧 kind、图片 kind、损坏 JSON、renderer 错误、多引用和路径来源均有测试。
|
||||
@@ -0,0 +1,49 @@
|
||||
# 【里程碑】退役策划 Agent V1/V2 解耦清理
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | proposed |
|
||||
| Date | 2026-09-15 |
|
||||
| Parent Spec | `docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md` |
|
||||
|
||||
## 目标
|
||||
|
||||
移除旧版策划 Agent V1、V2 的前端会话、审批、数据适配、测试契约和确定失效的展示残留；仅在删除策划链路时遇到已退役 Supervisor 功能耦合时一并删除该耦合，使“做方案”只使用当前 Design Agent、做游戏只使用 DirectCodex。
|
||||
|
||||
## 范围
|
||||
|
||||
- 解除当前 Design Agent 与旧 `planningV2` / `PlanGdd` 状态命名和控制流的耦合。
|
||||
- 删除仅服务旧策划的 Supervisor 产品入口、会话恢复、Runtime 轮询和聊天提交分支；保留通用 Supervisor 与做游戏 DAG。
|
||||
- 删除旧 V2 会话 hydrate、start、continue、审批和用户问询分支。
|
||||
- 删除旧 V2 TypeScript 会话适配层、旧 GDD 前端类型、测试 mock、旧事件契约和专属样式。
|
||||
- 清理确定没有现役调用方的旧策划身份说明、测试 fixture 和文档当前入口。
|
||||
- 保留当前 Design Agent 的会话、澄清、阶段审批、工作区浏览和 reasoning 展示行为。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 不主动扫描、重构或整体删除做游戏 Agent 的 16 Agent DAG；只有策划删除直接造成编译或测试失败时才做最小修复。
|
||||
- 不删除 DirectCodex 或当前 Design Agent；必要时保留被两者复用的中性聊天表现组件。
|
||||
- 不为旧项目新增兼容层、迁移器、墓碑注释或退役行为测试。
|
||||
- 不修改 SpacetimeDB schema、公开 API、持久化迁移和现役 Design Agent 协议。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- PR #159 的合并提交 `3d8e0211` 代表旧 Fast GDD / 策划 V1 的引入。
|
||||
- PR #305 的合并提交 `04128eb6` 同时包含 V1 大范围退役、策划 V2 会话链路和后续 Design Agent 迁移。
|
||||
- 当前分支已经删除 Rust V1/V2 Runtime 模块和旧审批组件，但前端仍残留旧 V2 调用方；实现前须保持工作树干净。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] “做方案”入口和已有 Design Agent 项目只调用当前 Design Agent IPC，不再调用旧 `planning_*_v2` IPC。
|
||||
- [ ] 当前 Design Agent 的消息、reasoning、澄清、阶段审批和重试行为不依赖旧 V2 状态变量。
|
||||
- [ ] 源码中不再存在旧 V2 TypeScript 会话适配层、旧 `PlanGdd` 类型和旧前端审批契约。
|
||||
- [ ] 旧前端测试、事件测试和样式残留被删除或改为当前 Design Agent 契约。
|
||||
- [ ] 不主动修改做游戏 Supervisor + 16 Agent DAG；因共享退役代码删除产生的编译错误得到最小修复。
|
||||
- [ ] 前端 typecheck、相关定向测试、编码检查和 diff 检查通过；触及 Rust 时对应 cargo check 通过。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：`npm --prefix apps/ai-game-creator-shell run typecheck`、相关 appSurface 定向测试、`npm run check:encoding`、`git diff --check`。
|
||||
- 运行时：至少验证“做方案”新项目进入 Design Agent、已有 Design Agent 会话恢复、澄清/审批回合可继续。
|
||||
- 边界：确认 DirectCodex 和做游戏既有入口未被旧策划清理改动；确认旧 V2 IPC 字符串和旧事件契约不再进入现役前端。
|
||||
@@ -0,0 +1,38 @@
|
||||
# Version
|
||||
|
||||
V2-RUST-RETIRE-1
|
||||
|
||||
# Status
|
||||
|
||||
in-progress
|
||||
|
||||
# Date
|
||||
|
||||
2026-09-14
|
||||
|
||||
# Parent Spec
|
||||
|
||||
`docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`
|
||||
|
||||
# 目标
|
||||
|
||||
删除已经被独立 Design Agent 取代的旧策划 V2 Rust Runtime、Tauri 命令注册和仅服务 V2 的模块导出，使桌面壳继续编译并保留做游戏 Agent 与新版 Design Agent。
|
||||
|
||||
# 边界
|
||||
|
||||
- 删除 `planning_policy_v2`、`planning_session_v2` 及仅供这两者使用的 V2 注册和调用。
|
||||
- 删除 V2 专属的 Tauri command 注册、模块导出和测试入口。
|
||||
- 保留 `design_runtime`、`design_tools`、`design_session`、通用 runtime、DirectProject 和做游戏 Agent。
|
||||
- 本里程碑不处理前端 V2 数据层、UI、文档索引和共享运行时中的可选清理。
|
||||
|
||||
# 验收标准
|
||||
|
||||
1. Rust 源码不再编译 `planning_policy_v2.rs` 或 `planning_session_v2.rs`。
|
||||
2. `main.rs`、`commands.rs` 和 runtime protocol 不再注册或导出 V2 命令。
|
||||
3. 新版 Design Agent 与做游戏 Agent 的 Rust 编译路径保持可用。
|
||||
4. 相关定向 Rust 测试和 `cargo check` 通过。
|
||||
|
||||
# 依赖
|
||||
|
||||
- 当前分支已包含 PR159 的 V1 清理。
|
||||
- 前端 V2 调用暂时保留，待后续里程碑同步删除。
|
||||
@@ -0,0 +1,55 @@
|
||||
# 项目自动上传与后台工程下载
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | implemented-awaiting-runtime-validation |
|
||||
| Date | 2026-09-19 |
|
||||
| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的项目快照上传与后台工程下载合同 |
|
||||
|
||||
## 目标与范围
|
||||
|
||||
修复实际项目自动上传的已证实故障，并让有权限的后台管理员按项目查看远端快照、一键下载按原始目录还原的工程 ZIP。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
客户端上传 UI、跨设备恢复、版本历史、数据库 schema、线上部署、自动补传全部未打开项目。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
延续现有私有 OSS 项目快照、平台会话与后台权限。真实 bucket 已只读确认只有两份历史模板清单；上传根因必须经确定性复现后修正。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 正式项目窗口可被同步调度识别；周期与关闭触发保持有界，失败有项目级诊断。
|
||||
- [ ] 未单独配置快照目标时仍使用 agc-dev，只复用资源存储凭据；显式快照目标保持有效，不迁移现存对象。
|
||||
- [ ] 后台列表显示项目名/ID、用户 ID、同步时间、文件数、体积和完整性，支持刷新与分页。
|
||||
- [ ] ZIP 按清单还原相对路径；不含对象存储摘要目录；空文件可上传与导出。
|
||||
- [ ] 清单名称/完整性变化在无内容差异时也提交，partial 可恢复 ready，历史缺字段不冒充 ready。
|
||||
- [ ] 缺失、损坏、越界路径和非完整清单失败关闭；历史未声明完整性的清单明确标记，允许导出已有文件但不称为完整工程。
|
||||
- [ ] 无后台权限不能读取项目或 ZIP；不泄漏凭据；ZIP 构建有体积、并发和临时文件清理边界。
|
||||
- [ ] 定向 Rust 测试、后台类型检查/构建、UI smoke、编码、文档索引和 diff 检查完成，运行时证据与未验证部分分别列出。
|
||||
|
||||
## 证据要求
|
||||
|
||||
自动化覆盖窗口身份、上传零字节、清单统计、目录还原、路径与校验和校验、后台路由权限。运行时优先只读现有 OSS 清单；测试不上传真实用户工程、不修改线上数据。
|
||||
|
||||
## 已取得证据
|
||||
|
||||
| 层次 | 结果 |
|
||||
| --- | --- |
|
||||
| 客户端 Rust `project_snapshot` | 22 通过、1 忽略（写入式真实上传 smoke 未运行）；含排队退出等待回归 |
|
||||
| 客户端前端生命周期与启动器 | 3 文件、10 测试通过；完整 AGC typecheck、skill-pack、check-config 通过 |
|
||||
| 后台页面、API client、路由与样式 | 44 测试通过；admin-web typecheck/build 通过 |
|
||||
| 后端快照与权限 | 14 定向测试通过；未认证路由矩阵与页签映射 2 测试通过 |
|
||||
| 默认存储目标 | 真实 AppConfig::from_env 配置回归 1 通过 |
|
||||
| OSS 存储层 | 全量 55 测试通过，含签名、特殊字符路径、读取上限与零字节 |
|
||||
| 真实 OSS 只读导出 | `project_snapshots_live_readonly_list_and_archive` 通过；limit=1 分页、2 清单、12 文件、73,424 字节，ZIP 解压路径/长度/摘要全匹配、临时文件清理通过；两份均为历史 unverified |
|
||||
| 浏览器 smoke | 模拟 API 的 1280 桌面与 390 窄屏通过；下载按钮可见，无整页横向溢出；中文 ZIP 文件名、Authorization、409 错误呈现通过 |
|
||||
| 通用门禁 | 编码、文档索引、production-ops、Rust 格式、客户端 Prettier 与 diff 检查通过 |
|
||||
|
||||
## 剩余验证与环境边界
|
||||
|
||||
`npm run dev:api-server -- --api-port 4198 --bgfilter-worker-port 4199 --api-timeout-seconds 600` 编译成功，但当前工作区配置的本地数据库 `xushi-p4wfr` 在 `127.0.0.1:3101` 返回 404，启动认证投影无法完成，故 `/healthz` 及完整 HTTP smoke 未通过。仅本任务启动的 API/worker 已停止；没有清库、迁移数据库、改 `.env` 或替换其它项目的验证目标。
|
||||
|
||||
尚未替换安装版、构建新客户端发布包或部署；提交推送按用户本轮授权执行。当前条款已有上述自动化与只读存储证据，最终验收仍等待当前工作区数据库就绪后的 HTTP 联调，以及新客户端的隔离实机自动上传验证；完成后再关闭里程碑并清理两份计划。
|
||||
@@ -1,7 +1,51 @@
|
||||
# 决策记录
|
||||
|
||||
## Unity 与 Godot 常用操作指导
|
||||
|
||||
两种编辑器的操作指导复用客户端审核 Skill pack：DirectProject 通过原生 Skill 或既有审核资源读取入口按需取得，Agent Runtime 的对应执行工具说明嵌入同源参考。指南不改变插件可用性、执行授权或 Runner 回执；只读说明不能证明编辑器已连接。常用示例与执行失败/部分修改、保存、撤销边界在同一参考中维护，避免提示词和文档各存一份代码。
|
||||
|
||||
## 2026-09-20 Godot 编辑器执行接入
|
||||
|
||||
可用性边界按引擎区分：Cocos/Unity 保持不按工程类型过滤，Godot 仍绑定当前 Godot 项目，切项目撤销旧插件上下文；前端统一根据宿主投影启动插件。Runtime 工具目录只对 Godot 追加项目条件，编辑器说明沿用外置提示词及审核 Skill 参考。
|
||||
|
||||
Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和不确定执行回执合同，编辑器实现留在 `plugins/agc-godot-editor`。用户选择 DLL 原件随 AGC 安装资源分发，并确认按编辑器实例在 AGC 私有缓存准备临时加载副本，以满足 Godot Windows 加载器的同目录 `~DLL` 写入要求；项目内不复制 DLL，只用受管 `.gdextension` 引导。Godot 自动 UID 伴生文件必须记录归属并在确认卸载后按内容匹配清理。工作区根不迁移到 Godot 子目录，原始项目配置与场景只通过明确编辑操作修改。完整合同及验证范围见 [Godot 编辑器插件接入](<../../technical/【技术方案】AGC Godot编辑器插件接入-2026-09-20.md>)。
|
||||
|
||||
> 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
|
||||
> 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
|
||||
> 当前口径（2026-09-18）：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据。策划 Agent V1/V2 的 Runtime、专用命令、审批卡、展示适配和旧测试已删除；当前策划入口统一使用 Design Agent。如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
|
||||
|
||||
## 2026-09-17 GameCreationApp 资源 kind 只保留一份词汇表：严格解析 + `app_log!` 留痕
|
||||
|
||||
- 背景：kind 曾经有三份实现——Rust 手写 `GAME_CREATION_APP_CANONICAL_ASSET_KINDS` + `canonical_game_creation_app_asset_kind()`（带 legacy 别名表与 `font → document` 特例）、TS 手写 `GAME_CREATION_APP_CANONICAL_ASSET_KINDS` + `GAME_CREATION_APP_LEGACY_ASSET_KINDS` + `canonicalGameCreationAppAssetKind()`、以及 ts-rs 生成的 TS union。两份手写表互相引用又各自收口，判据直接分叉（同一个 `"UI"` 一边归一成 `ui-design`、一边收口成 `unknown`），跨语言一致性只能靠正则解析源码的测试来钉。
|
||||
- 决策（唯一真源）：kind 的变体、线上值、`as_str()`、`ALL`、严格解析与 ts-rs 绑定全部由 `server-rs/crates/shared-contracts/src/game_creation_app/asset_kind.rs` 的声明表派生。两份手写 canonical 列表、legacy 别名表、`canonical_*()` 函数一律删除；生成的 TS union 落在 `packages/shared/src/contracts/generated/GameCreationAppAssetKind.ts`，`packages/shared/src/contracts/gameCreationApp.ts` 只 re-export 它，运行期列表 `GAME_CREATION_APP_ASSET_KINDS` 用穷举 `Record<GameCreationAppAssetKind, true>` 守住。
|
||||
- 决策（单一解析入口）：`GameCreationAppAssetKind::parse_with_context()` 是唯一公开解析入口，严格匹配降为私有 `match_canonical()`；易混的 `from_str_lossy()` 与公开 `from_str_or_unknown()` 都已删除，认不出 canonical 值只有这一处收口并留痕（读侧回捞 legacy kind 只查 `ALL` 判真值，不另开解析函数）。口径是等值匹配——不 trim、不 lowercase、不查别名、不迁移；认不出的值收口成 `Unknown`（分类落 `unclassified`）。这是有意接受的行为（历史误写的 kind 不会被"救回"正确栏目），不再提供任何兼容入口；`font` 是正式成员，不再走别名。
|
||||
- 决策（登记边界的 kind 口径）：外部登记统一走 `assets::registration_asset_kind()`——空白入参落中性 `image`，非空认不出的值严格收口成 `unknown` 并留痕；三条登记边界（Tauri `register_local_asset`、画板导入、平台导入）不再各写一份 trim/兜底。`Unknown` 是无法解析的边界结果，具体写入方必须自行决定拒绝或保留待后续归类，不能静默猜成其他 kind。栅格归一化的 `source_subtype` 只接受图片族成员，文档/字体/音频等一律按 `image` 登记；Agent 回执派生物按 `Text => Document` 落 `document`。
|
||||
- 决策（判据不许散落）：切片残留登记只看 `assets/art-spritesheet-slices/` 路径（不再附带 `kind == Icon`）；sprite 身份比较忽略随 kind 派生的 `metadata.asset_type`；TS 侧「UI 编辑器文档资产」判据只留 `isGameCreationAppUiDesignDocAsset()` 一份，资源画布入口 / UI 编辑器桥接 / 资源引用缩略图统一调用。
|
||||
- 决策（已知代价，不补救）：既有项目里无法解析的 kind 读入即 `unknown`，依赖 kind 等值比较的运行门禁会按"缺少该资源"处理。这是严格解析的必然结果，本次明确不为存量数据做迁移；将来若要迁就必须单独立项，不能改写解析边界。
|
||||
- 决策（留痕必须真的落地）：原实现用 `tracing::warn!`，而 AGC 壳没有 tracing subscriber，等于没有日志。现在 `shared-contracts` 只暴露可注册回调 `set_non_canonical_asset_kind_reporter()`，AGC 壳在 `main()` 里接到 `app_log!`，日志同时含原始输入串与调用上下文；`kind-observability` feature 与 `tracing` 依赖一并删除。TS 侧对应 `parseGameCreationAppAssetKind()` 的 `console.warn`。
|
||||
- 决策（平台/画板词汇表）：平台生成输入先严格解析为 `GameCreationAppAssetKind`，登记时直接写入已解析的 enum，不再保留 `platform_art_asset_manifest_kind()` 或任何平台别名/fallback 映射；图片快速编辑来源同样只允许 canonical 静态图片成员并要求 `mediaType=image`，原 `EDITOR_IMAGE_EDIT_STATIC_IMAGE_ASSET_KINDS` 兼容白名单已删除。
|
||||
- 验证：`cargo test -p shared-contracts`（含词汇表唯一性、严格性与留痕用例）、`cargo test --locked -p shared-contracts --features ts-bindings export_bindings` 后 `git diff` 为空、AGC bin 定向用例（`derived_asset_manifest_kind_is_never_unknown_for_text_derivatives`、`non_canonical_manifest_asset_kinds_report_raw_values_only`）、`npx vitest run packages/shared/src/contracts/gameCreationApp.test.ts apps/ai-game-creator-shell/tests/uiDesignResourceBridge.test.ts apps/ai-game-creator-shell/tests/appSurface.test.ts`。
|
||||
- 关联文档：[AI 游戏创作智能体 App 实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md) 的 2026-09-17 节。
|
||||
|
||||
## 2026-09-16 DirectProject 引用渲染收敛到 canonical user item 深模块
|
||||
|
||||
- 背景：`agent/direct_codex_references.rs`（平行 `DirectCodexTurnReference` DTO 与渲染路径）已退役，引用身份、上限与投影收敛到 `agent/direct_codex_user_item/`；本轮 prompt 里引用只投影为 `[素材引用 resourceId=…；项目路径=…]` 摘要，`MAX_DIRECT_CODEX_REFERENCES` 归 `direct_codex_user_item/validation.rs`。
|
||||
- 决策：2026-09-14「Direct Codex 引用 UI 设计文档生成代码上下文」的 prompt 注入改落在 `agent/direct_codex_user_item/wire.rs`，入口是 `direct_codex_user_item_to_prompt`：引用命中 `ui-design-doc` + `application/json` 时顺序调用 `generate_ui_design_code_at`，成功追加 `请先阅读生成的带有文档的代码片段: {relative_path}`，失败追加原始 `生成代码遇到错误{error}`，其它引用继续处理，manifest 身份摘要不变。
|
||||
- 决策（无写副作用）：只在生成本轮 prompt 时展开该上下文；历史 item 回读走 `direct_codex_user_item_to_response_item` 的纯投影，不得触发 UI 代码导出或任何项目写入。
|
||||
- 验证：`agent::direct_codex_user_item` 定向 16 条通过，覆盖成功注入、生成失败保留引用摘要、非 UI 文档不触发与历史回读不产生 `ui/generated-*.js`。
|
||||
|
||||
|
||||
## 2026-09-19 AGC Direct 删除每回合四项媒体资源请求上限
|
||||
|
||||
- 背景：2026-08-24 引入的单回合四项上限以「整个 agent run（一条用户消息到回合结束）」为窗口，计数只增不减、请求完成不释放额度；autonomous 游戏构建要求 agent 不停下跑完整局，额度耗尽后的报错实际是终态，与技能的三次重试纪律冲突，现场表现为长时间无效重试。2026-09-18 先将不计费的抠图豁免，但付费 create/derive 仍受同一窗口问题影响。
|
||||
- 决策：整体删除该上限机制。移除 `DIRECT_TOOL_BRIDGE_MAX_RESOURCE_CALLS_PER_TURN` 常量、回合授权状态中的 `resource_request_ids` 计数 map 与 `resource_request_ids()` 方法；`agc_create_or_derive_resource`（含 `agc_edit_image` 委托）与 `agc_remove_background` 统一按回合身份 + 请求指纹确定性派生 operation/idempotency id，同指纹重试复用与 pending 对账语义不变。付费提交串行仍由 `resource_generation_gate` 互斥保证，成本控制由服务端计费与泥点余额兜底，客户端不再按回合计数设限。
|
||||
- 验证方式：`cargo check`（ai-game-creator-shell src-tauri）通过，203 项警告与基线一致；无测试断言该上限，未新增测试。
|
||||
|
||||
## 2026-09-18 AGC Direct 抠图不占每回合四项付费媒体额度
|
||||
|
||||
- 状态：2026-09-19 起该上限机制整体删除（见上条），本条目仅作追溯。
|
||||
- 背景：2026-08-24 起 `agc_create_or_derive_resource` 与 `agc_remove_background` 共用每回合四项媒体资源请求上限。抠图服务端持久化 `generation_cost_mud_points: 0`（不计费），bgfilter 实测单张约 1 秒，上限导致一回合抠超过四张时后续请求被直接拒绝、agent 反复无效重试。
|
||||
- 决策：`agc_remove_background` 不再经过 `resource_request_ids` 计数，直接按回合身份与请求指纹确定性派生 operation/idempotency id（与 map 复用结果一致），同指纹重试与 pending 对账语义不变。付费的 create/derive（含 `agc_edit_image` 委托）维持四项上限与原有报错文案，且抠图请求不再挤占其额度。
|
||||
- 验证方式：`cargo check`（ai-game-creator-shell src-tauri）与 `git diff --check` 通过；未新增测试。
|
||||
|
||||
## 2026-09-18 AGC 未提交快速编辑草稿按资源路径归属，正式恢复账本不动
|
||||
|
||||
@@ -29,6 +73,13 @@
|
||||
- 验证方式：`provider_transient_retry_` 7 项中重写后的档位用例与 upstream-400 用例通过（断言 `maxRetries` 直取设置值、400 与其它瞬态共用同一预算），`provider_retry_` 其余 26/28 通过；该组 2 项（`provider_transient_retry_transport_failure_closes_then_stable_retry_succeeds`、`provider_transient_retry_backoff_is_exponential_and_capped_at_thirty_seconds`）与 `provider_retry_waiting_final_reply_*` 2 项在本机改动前后同为失败（`stash` 基线复跑确认，现象是等待自动重试唤醒超时）。本机串行全量套件另有既有环境失败（`tempfile::tempdir()` 归属校验、缺少 npm 构建产物、Windows 启动失败 MessageBox 阻塞 `startup_log_slot_fail_without_path...`）；抽查其中 5 项在 `stash` 基线上同样失败，与本次改动无关。仓库 `cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过。
|
||||
- 关联文档：[AI游戏创作智能体App实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)、[踩坑记录](pitfalls.md)。
|
||||
|
||||
## 2026-09-18 AGC backend 采用共享 Runtime、本地宿主与云端控制面分层
|
||||
|
||||
- 决策：AGC backend 统一按“`agent-runtime-core`/`agent-runtime-orchestration` 共享内核 + Tauri 本地执行宿主 + `server-rs` 云端控制面 + `module-*`/`platform-*` 领域与外部适配器”整理；先建立 application facade、能力合同和跨边界状态映射，不新建第二套 Agent Runtime、会话库或业务真相。
|
||||
- 数据边界：本地项目文件、manifest、JSONL、checkpoint、锁和 Runner 状态由 AGC 本地宿主持有；认证、模型目录、编辑器资源、异步生成、计费、快照元数据和诊断由云端持有；大对象按现有 OSS 合同保存。
|
||||
- 约束：Runtime core 不依赖 Tauri/Axum/SpacetimeDB/Provider；领域规则留在 `module-*`；HTTP/SSE/BFF 留在 `api-server`；SpacetimeDB 访问统一经 `spacetime-client`；外部服务统一经 `platform-*`；前端只消费后端或本地宿主投影。
|
||||
- 权威文档：[AGC 后端框架整理与演进路线](../../technical/【技术方案】AGC后端框架整理与演进路线-2026-09-18.md)。
|
||||
|
||||
## 2026-09-17 AGC 抠图提交使用远端画布项目身份
|
||||
|
||||
- 背景：AGC 已通过本地项目 ID 建立并持久化本地项目到主站远端画布项目的绑定，但 `agc_remove_background` 提交请求仍把本地 `manifest.project_id` 放入 `projectId`；`assetFolderId` 已使用远端素材目录 ID。主站因此按项目不存在或不属于当前账号返回 404，主站抠图和 BgFilter 本身均正常。
|
||||
@@ -208,7 +259,7 @@
|
||||
|
||||
- 决策：待实施的生产迁移以自由协作策划原型为行为基线，仅复用 Provider、恢复、文件操作、审计和 UI 通信；不继承旧 Planning V2 的强制工具、问询轮数、GDD 内容校验和版本审批。保留五阶段与顾问态、当前阶段资源注入和产物存在性检查，系统阶段空必需清单不增加解析或登记功能。
|
||||
- 交互边界：正式审批由 ✅/❌ 决定；❌ 只取消待审批、不唤醒 Agent，等待审批时禁止发送消息但允许浏览工作区。用户可直接查看工作区，编辑可暂不做，不引入用户与 Agent 协同编辑锁或冲突合并。
|
||||
- 影响范围：策划入口、会话与工具实现、资源打包、文件浏览；实施中。无旧 Planning V2 会话的策划项目走新设计 Agent，已有 V2 会话仍走原链路。
|
||||
- 影响范围：策划入口、会话与工具实现、资源打包、文件浏览；迁移已完成。当前入口统一使用新 Design Agent，旧 Planning V2 会话不再继续运行。
|
||||
- 关联文档：[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。
|
||||
|
||||
## 记录格式
|
||||
@@ -8840,11 +8891,12 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
- 验证方式：`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`（423 passed，含新增 6 条：栏目分流与总览不渲染、UI 栏 5 个入口载荷、前置缺失可点击说明且零请求、角色栏 2 个入口、音频入口走既有链路、上传 + 配对读清单，另 1 条工具栏与 Dock 的 CSS 几何契约）；`resourceCanvasBottomToolbar.test.tsx` 15 passed（新增）；`resourceCanvasGenerationEntry.test.tsx` 11 passed（新增单类型用例 1 条）；`projectResourceLiveIntegration.test.tsx` 25 passed（「生成素材」面板改名断言同步更新）；`npm run agc:typecheck` 全绿（**其中的 `check-config.mjs` 报错已因本轮落地调用方而消失**）、`npm run check:encoding`、`git diff --check` 干净。未 commit。
|
||||
- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.10 / §7.9 / §8）、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（S11 / S11a / §7.3）。
|
||||
|
||||
## 2026-09-13 Cocos 插件按当前项目类型暴露
|
||||
## 2026-09-20 Cocos 与 Unity 插件独立于工程类型
|
||||
|
||||
- 决策：`agc-cocos-editor` 只有在当前受控项目通过 Cocos Creator 根目录识别（`package.json.creator.version` + 普通 `assets/`）时才暴露插件、面板和 Cocos 工具；无项目或其它项目类型均隐藏并失败关闭。
|
||||
- 决策：项目切换离开 Cocos 时立即停止已运行的插件实例；启动、面板读取、插件 RPC、Runtime execute 和 DirectProject MCP 工具目录/执行入口全部再次校验项目类型。Cocos 编辑器操作优先经内置插件入口，禁止回退到项目 `extensions/`、`package.json` 插件或第三方 MCP。
|
||||
- 验证：新增 builtin/plugin host 项目级门禁测试，Direct MCP fixture 补最小 Cocos 工程结构；Rust 定向测试、显式 `cocos-editor-execute` feature 编译、编码检查和 `git diff --check` 已执行。
|
||||
- 决策：`agc-cocos-editor` 与 `agc-unity-editor` 的插件列表、启动、面板、插件 RPC、Runtime 与 DirectProject 工具暴露不按当前工程类型过滤；无项目、普通 AGC、Godot、Cocos、Unity 上下文遵循同一套 enable、原生适配器、平台与 feature 规则。前端根据宿主列表中各插件状态分别自动启动，不按项目类型二选一，也不自动展开面板。
|
||||
- 决策：跨工程类型切换保留插件实例及管理能力，继续更新受控项目上下文、失效旧连接并隔离旧请求回执。实际编辑器操作仍要求当前受控项目匹配真实引擎工程与编辑器目标；显式跨项目路径、缺失项目、无目标进程、身份或握手不匹配均在派发前失败，权限、并发、期限与执行不确定阻断保持有效。
|
||||
- 边界：插件可见和工具可调用不能证明任意非引擎目录可成为编辑器执行目标；不改变项目类型、导入或持久数据。Cocos 编辑器操作继续使用内置插件，禁止回退到项目 `extensions/`、`package.json` 插件或第三方 MCP。
|
||||
- 验收口径：分别取得宿主/内置开关、工具目录、前端启动投影与真实目标拒绝证据；真实编辑器、安装包和 CI 与定向测试分层报告。
|
||||
|
||||
## 2026-09-14 DirectProject Codex 取消路径白名单并启用完整 sandbox
|
||||
|
||||
@@ -8901,6 +8953,12 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
- 决策：采用后台继续运行语义。Direct 回合由进程内项目身份锁持有，页面离开不取消；重进项目通过活动回合只读快照与 Thread Manager bootstrap/consume 恢复忙碌态和进度。左上角面板复用同一快照列出正在运行的 Direct 项目并支持进入。
|
||||
- 边界：快照不写项目文件、不进入公共 API、不跨应用重启恢复；读取失败保留上一份结果并单独提示，不改写成权限或审批失败。身份锁排他性、付费身份和项目写锁不变。
|
||||
|
||||
## 2026-09-14 Direct Codex 引用 UI 设计文档生成代码上下文
|
||||
|
||||
- 决策：UI Editor JSON 文档资产唯一使用 `kind:"ui-design-doc"` 且 `mediaType:"application/json"`；`ui-prototype` 保持图片语义，旧 `UI` / `ui` / `ui-design` 不作为该文档分支输入，不做 fallback 或迁移。
|
||||
- 决策：Direct Codex 结构化资源引用命中该 kind 时，顺序调用 UI Editor persistence 的 `generate_ui_design_code_at`，生成 `ui/generated-*.js`，并把 `请先阅读生成的带有文档的代码片段: {relative_path}` 追加到当前 prompt。生成失败不阻断本轮引用，追加原始 `生成代码遇到错误{error}`，其它引用继续处理。
|
||||
- 原因：复用 `html_renderer/mod.rs` 统一产物，确保 LLM 读取的代码包含 UI 节点元数据和文档注释；严格 kind + mediaType 判定避免图片资产误走代码生成。
|
||||
|
||||
## 2026-09-17 AGC 模板库落在 oss://agc-dev/templates/
|
||||
|
||||
- 背景：AGC 需要「真·游戏模板」库，让用户能浏览、筛选、下载模板并直接由模板创建项目，且模板内容更新不依赖客户端发版。
|
||||
@@ -8963,3 +9021,20 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
- 决策：`pick_local_project_directory` 增加可选 `title`（限 24 字符、无控制字符，其余回退默认标题），使「选择项目创建目录」不再冒用「选择游戏项目目录」文案。
|
||||
- 关联规范：`docs/project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md`、`docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`。
|
||||
- 验证：`cargo test --bin genarrative-ai-game-creator-shell creation_root`（2 项）、模板库定向单测 14 项、偏好模型 3 项、`appSurface` 472 项（含设置页「工作区」选择/恢复目录与「设置里选目录后建项带 `projectsRoot`」两条场景）、`tsc`、`check:encoding` 与 `check-doc-index` 通过。
|
||||
|
||||
## 2026-09-20 Rust 工具链升到 1.98.1：仓库侧四处同步 + runner 镜像必须重建
|
||||
|
||||
- 背景：macOS 27（CLT for Xcode 27.0）冷构建时 proc-macro dylib 被链接成畸形 Mach-O（`mis-aligned LINKEDIT string pool`），上游 rust-lang/rust#157750 已修复，而仓库锁的 stable `1.96.0` 仍复现（Issue #431）。
|
||||
- 决策：根 `rust-toolchain.toml` 的 channel 由 `1.96.0` 改为 `1.98.1`；`deploy/container/gitea-ci-job.Dockerfile` 的 Rust stage 由 `rust:1.96-bookworm@sha256:19817ead…` 换成 `rust:1.98-bookworm@sha256:93ce27a88655056a51dbdd8f5f2d7ddc071c7b0070fb288a37b5a285fc83971e`（按 registry 配置实测该 digest 的 `RUST_VERSION=1.98.1`，与 channel 逐字一致）。
|
||||
- 决策（版本标签）：镜像 tag / label 一并从 `20260807.1`、`2026.08.07.1` 升为 `20260920.1`、`2026.09.20.1`（同一次核对发现 Dockerfile 里有两处 `org.opencontainers.image.version`：一处 `2026.07.23.1`、一处 `2026.08.07.1`，后写的覆盖先写的，本次一并统一为 `2026.09.20.1`）（`scripts/gitea-ci-job-image.sh`、`deploy/container/gitea-ci-job.Dockerfile`），`deploy/container/README.md` 与开发运维文档同步 digest、Rust 版本和归档示例名。镜像内容变了却沿用旧 tag，排障和回滚都会认错版本。
|
||||
- 不变口径：镜像继续 `RUSTUP_AUTO_INSTALL=0`，job 现场不下载工具链；`scripts/check-gitea-ci-job-image.sh` 仍按 `rust-toolchain.toml` 的 channel 逐字校验镜像内工具链名，所以基础镜像的 `RUST_VERSION` 必须与 channel 完全相同。`std::os::windows::fs::MetadataExt::number_of_links`（rust-lang#63010）在 `1.98.1` 上实测仍未稳定，`#[cfg(windows)]` 侧继续使用自行声明 `ByHandleFileInformation` 的实现。
|
||||
- 新增护栏：`scripts/project-ci-workflow.test.ts` 增加一条一致性用例——Dockerfile 的 `ARG RUST_IMAGE` 版本段必须等于 `rust-toolchain.toml` 的 channel 主次版本、其 digest 必须同时出现在两份运维文档里、镜像 tag 日期戳必须与 Dockerfile 的 `org.opencontainers.image.version` 一致，避免本次这种「改了 Dockerfile 忘了文档」的漂移。
|
||||
- 待办（不在本次仓库改动内）：在 station 上执行 `build / verify / export / load-runner`，备份 runner config 后把 `genarrative-ci` 映射切到新 Image ID 并 `docker restart --timeout 660 gitea-runner`；内层只有 1.96 时 PR 的 job 必然失败。macOS 与 Windows AGC 构建机（`jenkins/Jenkinsfile.ai-game-creator-shell-build`，preflight 只校验 rustc/cargo 是否存在）需确认已装 `1.98.1`，macOS 冷构建是本次问题的原始验证目标。`deploy/container/api-server.Dockerfile` 的 `FROM rust:1.93-bookworm` 是另一处未加 digest 的 Rust 版本 pin，本次未动。
|
||||
- 验证：分支 `chore/rust-toolchain-1-98` / PR #432；`npx vitest run scripts/project-ci-workflow.test.ts`、`npm run check:encoding`、`git diff --check` 通过。Windows：`1.98.1` 下 `npm run agc:build -- --debug` 的前端构建、Rust 编译与 NSIS 安装包生成成功（见 PR 描述记录）；macOS 与镜像重建后的 CI 结果仍待验证。
|
||||
|
||||
## 2026-09-20 AGC 客户端版本号收敛为单一发号源
|
||||
|
||||
- 客户端版本号唯一事实源改为 OSS `agc/global-version.json`；渠道清单只写本次拿到的号，仓库里 5 个版本文件只作构建输入参考。
|
||||
- 发号顺序固定「先写总号 → 再构建 → 再发渠道清单」，失败不回滚只烧号；统一构建发一次号供 `dev-win` / `dev-mac` 共用，单渠道热修只作用于该渠道。
|
||||
- 发号收口到 Jenkins Job `Genarrative-Agc-Global-Version-Issue`（`disableConcurrentBuilds()`；集群无 `lockable-resources`，以写后回读不一致即失败关闭兜底并发）。
|
||||
- 原渠道高水位逻辑降级为断言：请求号低于本渠道清单版本即失败关闭；`AGC_RELEASE_DRY_RUN` 只预览不烧号。
|
||||
|
||||
@@ -20,46 +20,54 @@
|
||||
|
||||
完整规则和模板见 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](../../【协作规范】规范驱动开发工作流-2026-09-12.md)。小型局部修改仍直接使用下方轻量流程；执行中若触及公开行为，立即升级到 SDD。
|
||||
|
||||
任务开始时先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序。先完成修改、定向验证和边界检查组成的最小闭环；设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项。不要让工具探测、历史整理或验证便利自行改变任务目标。
|
||||
任务开始时先写清一句话交付结果、验收判据和修改范围，再按“必须项 / 风险项 / 可选项”排序。先完成修改、定向验证和边界检查组成的最小闭环；设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，其余记录为后续事项。
|
||||
|
||||
## 开始前
|
||||
|
||||
- worktree 复用 `node_modules` 时，测试与构建的 workspace alias 必须指向当前工作树源码，不能经依赖软链接读取另一工作树的共享包。遇到仅 worktree 出现的 JSX 编译错误时先核对解析路径，不用给组件补全局变量来掩盖错误来源。
|
||||
- worktree 复用 `node_modules` 时，测试与构建的 workspace alias 必须指向当前工作树源码。遇到仅 worktree 出现的 JSX 编译错误时先核对解析路径，修复错误的依赖解析。
|
||||
|
||||
- 运行 `git status --short`，保留用户已有的未提交修改；不要在共享工作树中使用破坏性 Git 命令。
|
||||
- 复杂任务先读 `AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`、`docs/README.md` 和对应专题。
|
||||
- 需要完整 SDD 的任务先确认主规范位置和验收证据，再创建 `docs/project-memory/plans/` 下的里程碑规范与实现计划；计划完成、取消或合并后删除。
|
||||
- 后端事实以 `server-rs/crates/api-server/src/app.rs`、`server-rs/crates/api-server/src/modules.rs`、Cargo manifest、SpacetimeDB schema 和源码为准；现役 API 不从未挂载模块推导。
|
||||
- 后端事实以 `server-rs/crates/api-server/src/app.rs`、`server-rs/crates/api-server/src/modules.rs`、Cargo manifest、SpacetimeDB schema 和源码为准；现役 API 按实际挂载路由核对。
|
||||
- External v1 以 `docs/openapi/genarrative-external-v1.openapi.json` 与 `modules/external_api.rs` 为准。
|
||||
- 本地端口的默认值只用于启动配置；实际运行端口以 `.app/dev-stack.json` 和启动日志为准。
|
||||
- 任务涉及 SpacetimeDB schema 时，先读 `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 与现有 schema 检查脚本，不依赖仓库中已不存在的旧表目录或基线文件。
|
||||
- 任务涉及 SpacetimeDB schema 时，先读 `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 与现有 schema 检查脚本。
|
||||
|
||||
## 修改边界
|
||||
|
||||
- 后端路线固定为 `server-rs + Axum + SpacetimeDB`，访问 SpacetimeDB 统一经 `spacetime-client` facade。
|
||||
- `module-*` 放领域规则，`spacetime-module` 放表和事务，`api-server` 放 HTTP/SSE/BFF，`platform-*` 放外部副作用，`shared-contracts` 放 DTO 与公开契约。
|
||||
- 前端不承接正式业务真相；页面状态必须来自后端投影、API 或持久化合同。
|
||||
- 旧模板、旧公开作品、旧运行态、旧 Node/Express/PostgreSQL/Go/maincloud 路线和人工 `spacetime --root-dir` 命令不作为新实现目标。
|
||||
- 已退役对象没有现役 caller、公开契约、持久化迁移或活跃实例时，不添加兼容代码、兼容测试、墓碑注释或墓碑文档。
|
||||
- 修改中文文件优先局部补丁，保持 UTF-8；不把中文文案替换成英文。
|
||||
- 前端负责表现与交互；页面正式状态来自后端投影、API 或持久化合同。
|
||||
- 本地 SpacetimeDB 数据隔离使用项目脚本或 `--data-dir`，发布目标显式传 `--server` / `--server-url`。
|
||||
- 已退役对象没有现役 caller、公开契约、持久化数据、活跃实例或迁移要求时，清理实现、专属测试和说明，权威文档保持当前状态；公开契约、持久化数据和正式迁移按实际需求保留最小兼容及对应测试。
|
||||
- 修改中文文件优先局部补丁，保持中文与 UTF-8。
|
||||
|
||||
## 文档维护
|
||||
|
||||
- 当前稳定合同进入 `docs/`；长期决策、通用流程、排障经验进入 `shared-memory/`。
|
||||
- 文档现行、历史、待复核、开放事项和活动计划的分类以 [`docs/【协作规范】文档生命周期与现状索引-2026-09-12.md`](../../【协作规范】文档生命周期与现状索引-2026-09-12.md) 为准；`historical` 和 `review` 文件开头保留状态头，不能直接作为实现依据。
|
||||
- `plans/` 只保存正在执行且有明确下一门禁的计划；`todos/` 只保存真实开放且有关闭条件的事项。完成或作废后删除或融合。
|
||||
- 不把分支名、一次性测试轮次、提交流水账和个人路径写成长期规则。
|
||||
- 长期规则记录可复用的当前合同与验证方法，执行历史由 Git 保存。
|
||||
- H5 HostBridge 真实调用链的临时替身词扫描必须覆盖生产调用链；宿主壳真实能力以现行 HostBridge 协议与代码为准。
|
||||
|
||||
## 验证路由
|
||||
|
||||
提示词外置变更运行 `runtime_prompt_bundle_build` 与 `prompt_source_boundaries` 两个 Rust 集成测试，验证编译期文本、目录登记和源码边界；现有 `agc-rust-shard-1` 本地/CI 入口先执行这组检查，再运行分片单测。
|
||||
|
||||
提示词测试验证实际请求中的片段来源、动态参数和工具结构；措辞不作为逐字契约。已有行为测试覆盖的限制不再另设整段文案检查。Direct 回合测试复用生产的消息转换和文件投影函数，不维护仅供测试调用的回合编排副本。
|
||||
|
||||
AGC 预览快捷操作的界面测试按独立命令或有状态短流程注册，每例重新建立 fixture、原生调用 mock 和页面，并等待项目打开后再记录调用计数。预览启停、导出确认与取消等连续行为保留在同一用例；互不依赖的只读命令不串成一条长对话，也不共享 DOM 或提高超时来容纳整组流程。
|
||||
|
||||
Rust 分片失败日志保留有界的失败详情，包括 panic 位置、断言和最终通过/失败数量；分片选中数量标为 selected，避免误读为失败数量。修改分片日志时运行 `node --test apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.test.mjs`，用最小 Rust fixture 验证失败详情和成功摘要。
|
||||
|
||||
AGC 运行时配置默认值调整时，同步核对 Rust 默认值、分发配置模板、设置弹窗默认草稿和 `runtime-settings.suite.ts` 的恢复默认断言；显式传入旧值的配置读取用例仍验证原值保留，不批量替换测试数据。
|
||||
|
||||
AGC 测试构造单 HTML 项目时，必须在初始化之前写入 HTML，避免自动建立 npm 工程；npm 预览和导出测试应提供 dist 产物。已有图片生成 pending/operation 属于持久化恢复合同，修改工具默认参数后仍须验证旧动作恢复不重复提交、不因默认值变化被误判为新意图。
|
||||
|
||||
SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.md`；该项目适配层按需调用已安装的官方 `spacetimedb` 插件 skill，插件提供通用 SDK/CLI/MCP 知识，项目 skill 负责 Genarrative 架构边界和验证门禁。
|
||||
|
||||
按改动范围选择定向门禁，不以无关全量扫描代替契约验证：
|
||||
按改动范围选择定向门禁：
|
||||
|
||||
| 范围 | 至少运行 |
|
||||
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
|
||||
@@ -24,10 +24,10 @@
|
||||
AI 游戏创作 / DirectProject / UI workflow：
|
||||
|
||||
1. `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`
|
||||
2. `docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`
|
||||
2. `docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`（历史方案，仅供追溯）
|
||||
3. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`
|
||||
4. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`
|
||||
5. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`（仅存量旧链路）
|
||||
5. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`（历史 V1 方案，仅供追溯）
|
||||
2. `docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md`
|
||||
3. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`
|
||||
4. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`
|
||||
|
||||
@@ -1,5 +1,28 @@
|
||||
# 踩坑与排障记录
|
||||
|
||||
## Rust 同步回调的测试记录按线程隔离
|
||||
|
||||
- `shared-contracts` 的资源 kind reporter 是进程级回调。仅给注册和断言加锁，无法阻止其他并行 manifest 测试触发该回调，导致日志数量和内容断言偶发混入其他测试记录。
|
||||
- kind 解析与回调在调用线程同步执行，测试收集器使用线程局部存储，各用例开始时清空本线程记录；生产 reporter 保持不变。保留完整记录断言，并用两个线程分别解析和核对记录，验证隔离；不要通过全局串行测试或放宽断言掩盖干扰。
|
||||
|
||||
## AGC 自动同步必须绑定真实项目生命周期
|
||||
|
||||
- 正式客户端在单窗口中用 React 状态打开/切换工程，窗口 URL 不代表当前工程。原生后台同步应读取由当前窗口显式登记的活动工程；首次打开、离开、切换、关窗及退出等待分别验证，不能只用携带 `projectPath` 的独立测试窗口证明正式入口可用。
|
||||
- 增量文件没有变化不等于远端清单没有变化。项目名和完整性元数据也参与提交判据，避免临时跳过恢复后永久停留在 partial，或新出现超限文件后仍显示 ready。历史清单缺少完整性字段属于未知，不能默认成完整。
|
||||
- ZIP 导出按一次冻结清单恢复相对路径并逐文件核验；直接下载内容寻址的 OSS 目录不能得到可用工程。源码/素材归档不包含依赖缓存、凭据和 AGC 对话运行状态。
|
||||
|
||||
## 2026-09-19 资源 kind 词汇收敛后，前端判据与 fixture 必须一起按 canonical 成员重写
|
||||
|
||||
- **现象**：工具栏入口的 `assetKind` 换成共享 `GameCreationAppAssetKind`（图集从平台词 `art-spritesheet` 改成 `icon-spritesheet`）后，「图集不接受用户参考」的判据仍写在旧的 `['art-spritesheet']` 字符串清单里，判据恒假：生成面板重新给图集渲染参考图选择器，原生提交再按合同显式拒绝多余参考。
|
||||
- **同类第二处**：把 `hasRegisteredArtImageAssets` 从 `kind === 'art-spritesheet'` 直接换成「kind ∈ 视觉族」会把候选 UI 原型图（`ui-design`）算成美术图片产出，提前顶掉「美术资源计划已完成，尚未生成或登记图片」；判据必须显式排除 `GAME_CREATION_APP_UI_DESIGN_ASSET_KIND`。
|
||||
- **处理（现行口径）**：前端的资源 kind 判据只比较 canonical 成员或共享契约导出的谓词，不再维护第二份字符串清单；词汇收敛时先 grep 旧词在 `src/` 与 `tests/` 两侧的落点，fixture 同步按 canonical 成员重写。
|
||||
- **易错点**：fixture 与生产代码写着同一个旧词时，单测会陪着一起变绿，用例证明不了任何事；另外 `tests/appSurface.test.ts` 不是全部同族用例，资源画布 / 画布生成参考等用例散在 `tests/*.test.ts(x)`，词汇收敛必须连这些一起跑。
|
||||
|
||||
## 2026-09-17 ts-rs 生成物换目录后，忘记同步忽略规则会让「生成物抖动」假装成代码改动
|
||||
|
||||
- **现象**：`GameCreationAppAssetKind` 的 ts-rs `export_to` 从 `apps/ai-game-creator-shell/src/contracts/generated/` 换到 `packages/shared/src/contracts/generated/` 后，任何 `cargo build` / `cargo test` 都会重写生成文件；若新目录没进 `.prettierignore` 与 `.eslintrc.cjs` 的 `ignorePatterns`，lint-staged / prettier 会把生成物重新格式化，于是每次提交都出现「生成物被改」，`cargo test export_bindings` 也不再幂等（跑完 `git diff` 不为空）。
|
||||
- **处理（现行口径）**：生成目录一律成对登记 `.prettierignore` + eslint `ignorePatterns`；改 `export_to` 时同步改这两处，并用 `cargo test --locked -p shared-contracts --features ts-bindings export_bindings --manifest-path server-rs/Cargo.toml` 后 `git diff` 为空来验证幂等。
|
||||
- **易错点**：旧的 `apps/ai-game-creator-shell/src/contracts/generated/` 目录下的同名文件不会自动删除，换目录后必须显式删除旧文件，否则会出现「两个同名 union，改动只落在一个目录」的假绿。
|
||||
## 生成草稿与异步展示边界必须按身份隔离
|
||||
|
||||
非模态生成浮层切换占位时按 draftId 分实例，卸载保留未提交/失败草稿，成功提交不再复活草稿；旧项目占位不存在时丢弃其保存回调。失败重试保留原请求输入和引用身份，引用失效不能静默过滤；修改已绑定输入须明确另起请求，不伪装成原请求重试。
|
||||
@@ -337,7 +360,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
## 2026-08-15 `#[cfg(windows)]` 里的代码不参与 Linux CI 编译，CI 绿不代表能构建
|
||||
|
||||
- 现象：把 master（`9f5c84ee7`）合进 `feat/five_min_design` 后，`cargo check --all-targets` 在 Windows 上直接 `error[E0658]: use of unstable library feature 'windows_by_handle'`，位置是 `apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs` 的 `metadata.number_of_links()`。该文件与 `origin/master` **逐字节相同**，即 master 自身在 Windows 上就构建不过。
|
||||
- 原因：`std::os::windows::fs::MetadataExt::number_of_links` 至今未稳定（rust-lang#63010），而 `rust-toolchain.toml` 锁的是 stable `1.96.0`。引入它的提交是 `578f8019f`（优化 AGC 项目入口并识别 Godot 工作区），其中 unix 分支用 `MetadataExt::nlink()`（已稳定）、windows 分支用了未稳定的对应物。**Linux CI 上 `#[cfg(windows)]` 整块不参与编译，所以 CI 全绿。**
|
||||
- 原因：`std::os::windows::fs::MetadataExt::number_of_links` 至今未稳定（rust-lang#63010）；当时 `rust-toolchain.toml` 锁的 stable 是 `1.96.0`，2026-09-20 升到 `1.98.1` 后在同一台 Windows 机器上用该 stable 实测仍报 `error[E0658]: use of unstable library feature 'windows_by_handle'`（见 decision-log 同日条），因此本条的处置口径不变。引入它的提交是 `578f8019f`（优化 AGC 项目入口并识别 Godot 工作区），其中 unix 分支用 `MetadataExt::nlink()`（已稳定）、windows 分支用了未稳定的对应物。**Linux CI 上 `#[cfg(windows)]` 整块不参与编译，所以 CI 全绿。**
|
||||
- 更普遍的形状：只要一段代码只在某个 `#[cfg(target_os)]` 下编译，它就完全绕过了其它平台的 CI——不只是 unstable feature，还包括类型错误、借用错误、缺失 import。跨平台分支是「双写」，两侧都得有人真的编译过。
|
||||
- 处理：本仓库对「文件是不是无硬链接普通文件」统一自行声明 `ByHandleFileInformation` 并调用 `GetFileInformationByHandle`，见 `runner/endpoint.rs`、`tool_plan_handoff/storage_windows.rs`、`project/agent_db.rs`、`git_inspect.rs`、`image_inspect.rs`、`agent/generation/canvas_generation.rs`。`manifest.rs` 当前已采用同一实现，并保留 fail-closed 语义：无法取得句柄信息或确认存在硬链接时均拒绝，同时拒绝 directory / reparse point。
|
||||
- 验证：改后 `cargo check --offline --all-targets` 通过、`cargo fmt --check` 通过、`project::manifest` 与 godot 相关定向测试 65 passed / 0 failed。判断「是不是本次合并引入」的通用手法：`git diff origin/master -- <file>` 为空即说明该文件就是 master 原样，问题不在合并。
|
||||
@@ -4607,7 +4630,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
|
||||
- 现象：`Repository checks`、`Frontend tests`、`Backend tests` 和 `Native shell tests` 都从全新 job 容器开始，apt、setup-node、rustup 和原生系统库在不同 job 里重复安装；后端与原生壳的安装时间可达数分钟，并把软件源和代理瞬时失败放大为四份。
|
||||
- 原因：Gitea Actions job 彼此隔离，上一个 job 在容器内安装的包不会自动进入下一个 job；把同一套不随 PR 变化的工具链写在 workflow step 中，必然每次重做。
|
||||
- 处理：用 `deploy/container/gitea-ci-job.Dockerfile` 预装 Node 22、固定 npm、Rust 1.96、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并按锁预热唯一根 npm workspace、server-rs、桌面壳与 AI 游戏创作壳 Cargo 四份下载缓存。四个 job 统一 `runs-on: genarrative-ci`，先用镜像内脚本直接从 Gitea checkout，再以 runtime 模式运行 `scripts/check-gitea-ci-job-image.sh`，同时检查四份缓存锁、工具链、完整 bwrap 与 Chrome headless。`RUSTUP_AUTO_INSTALL=0`；`rust-toolchain.toml` 变更时先重建镜像，不把下载 fallback 放回 job。
|
||||
- 处理：用 `deploy/container/gitea-ci-job.Dockerfile` 预装 Node 22、固定 npm、Rust 1.98.1、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并按锁预热唯一根 npm workspace、server-rs、桌面壳与 AI 游戏创作壳 Cargo 四份下载缓存。四个 job 统一 `runs-on: genarrative-ci`，先用镜像内脚本直接从 Gitea checkout，再以 runtime 模式运行 `scripts/check-gitea-ci-job-image.sh`，同时检查四份缓存锁、工具链、完整 bwrap 与 Chrome headless。`RUSTUP_AUTO_INSTALL=0`；`rust-toolchain.toml` 变更时先重建镜像，不把下载 fallback 放回 job。
|
||||
- 依赖边界：每个 job 仍必须各自执行 `npm ci`，让当前 lockfile 和 PR 依赖在干净环境中验证；区别是命中镜像 cache 时只做本地解包，锁新增依赖时才走受控网络。不要把 `node_modules` 或 Cargo `target` 烘进镜像，也不要向不受信任 PR 挂载跨 job 可写 cache。
|
||||
- 锁漂移边界：runtime 校验输出任一 `*_cache_lock=partial` 说明镜像内 lock 与当前 checkout 不同，不代表新增依赖已经缓存；必须同时输出 Actions warning，提示可信分支落地后刷新镜像。必须在新镜像中对 server-rs、桌面壳和 AI 游戏创作壳当前 lock 执行真实 `cargo fetch --locked --offline`；`cargo metadata --no-deps` 不会证明依赖 archive 可用，不能作为替代。
|
||||
- 构建网络边界：`CARGO_NET_RETRY` 只覆盖部分 crate 下载，registry `config.json` / index TLS 握手仍可能直接终止整次 fetch。Dockerfile 对每个 `cargo fetch --locked` 再做最多 5 次整命令级有界重试，最终仍执行断网 fetch，不能降低为无锁重试或省略离线闭合验证。
|
||||
@@ -5462,11 +5485,12 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
## 资源 kind 别名只救新登记，不救存量 category（2026-09-10）
|
||||
|
||||
- 现象：真机 `What do u wanna do kitten` 的 66 项资源里 58 项落「待归类」，其中 57 项是 `kind:"ui"` 的 UI 资产，本该在「UI 交互」。
|
||||
- 成因链：`ui` 不在 `GAME_CREATION_APP_CANONICAL_ASSET_KINDS` 里、也没有别名，于是走 `canonicalGameCreationAppAssetKind` 的 `image` 兜底，再经 `image → unclassified` 被误分到「待归类」。它并不是历史遗留值——`assets.rs:1656` 的 `infer_canvas_export_asset_kind`（画板导出导入）**现在仍在写出** `ui` / `animation` / `asset`。
|
||||
- 成因链：`ui` 不在 canonical 词汇表里、也没有别名，于是落「待归类」。它并不是历史遗留值——`assets.rs` 的 `infer_canvas_export_asset_kind`（画板导出导入）当时仍在写出 `ui` / `animation` / `asset`。
|
||||
- **现行口径（2026-09-17 起，改这里之前必读）**：kind 只有一份词汇表（Rust `GameCreationAppAssetKind` 声明表 → ts-rs 生成 TS union），解析是**严格等值匹配**：不 trim、不 lowercase、不查别名、不迁移；非 canonical 原值收口成 `unknown`（分类 `unclassified`）并把**原始串 + 调用上下文**交给壳层注册的 `app_log!` 回调。**别名表已整体删除，不要再加回来**——这条现象现在的表现是「日志里能查到谁还在写旧值」，先修写入方，不要在读侧做兼容。
|
||||
- **关键陷阱（2026-09-11 已修）**：补别名只影响「今后新登记」的资产。`register_local_asset_entry`（`assets.rs`）命中同 `localPath` 的既有资产时，旧实现只覆盖 `kind` / `media_type` / `source`、**不重算 `category`**；而读取侧优先信任落盘 `category`、只在它缺失或非法时才按 `kind` 派生。所以这 57 条的落盘 `category: "unclassified"` 会一直有效，重导入也自愈不了。**修法与必须保留的不变量**：更新分支只在 `kind` 真的变化时才重派生 `category`，否则「同路径重登记且 kind 变了」会留下「新 kind + 旧分类」的错位，而陈旧的非 `unclassified` 值会被无条件信任、自愈也不触发；反过来同 kind 重登记**禁止**动 `category`，落盘分类是权威值，被 `register_local_asset_keeps_explicit_category_when_kind_is_unchanged` 钉住。
|
||||
- 为什么读取侧要信任落盘值：存在用户手动改分类的正式链路 `update_manifest_asset_classification_at`（`project/manifest.rs:1110`），读时无条件重派生会吃掉用户的手动设置。
|
||||
- 根治选项（需产品拍板）：① 读时把 `unclassified` 当作「未设置」再按 kind 派生（简单但失去"我就是要 unclassified"的表达力）；② 一次性回填这 57 条（保留人工设置语义，需迁移脚本）；③ 只改写入侧让新素材 canonical 化（治不了存量）。
|
||||
- 另一处必须成对维护：别名表有**两份实现**——TS 侧 `packages/shared/src/contracts/gameCreationApp.ts` 的 `GAME_CREATION_APP_LEGACY_ASSET_KINDS`（读投影用）与 Rust 侧 `server-rs/crates/shared-contracts/src/game_creation_app.rs` 的 `canonical_game_creation_app_asset_kind`（写入侧按 kind 派生 category 用）。只改一边就会让落盘 category 与读侧栏目互相矛盾。交叉守卫见 `apps/ai-game-creator-shell/tests/assetKindCanonicalMapping.test.ts`（直接解析 Rust 源码比对）。
|
||||
- 成对维护点（**2026-09-17 起不再存在**）：当时别名表有**两份实现**——TS 侧 `GAME_CREATION_APP_LEGACY_ASSET_KINDS` 与 Rust 侧 `canonical_game_creation_app_asset_kind`，靠 `apps/ai-game-creator-shell/tests/assetKindCanonicalMapping.test.ts` 正则解析 Rust 源码交叉钉住。现在两份手写表与那个守卫测试都已删除：唯一词汇表由 Rust 枚举声明表派生、经 ts-rs 生成 union，跨语言一致性回到**编译期**（TS 侧 `Record<GameCreationAppAssetKind, …>` 穷举，少一个成员就编译不过）。不要再引入"正则解析 Rust 源码"的跨语言守卫。
|
||||
- 真机计数守卫见 `apps/ai-game-creator-shell/tests/resourceCardPreviewRealManifest.test.ts`。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/assets.rs`、`apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs`、`packages/shared/src/contracts/gameCreationApp.ts`、`server-rs/crates/shared-contracts/src/game_creation_app.rs`。
|
||||
|
||||
@@ -5475,20 +5499,20 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
- 规则（已拍板落地）：`gameCreationAppAssetCategory` 在「落盘 `category === 'unclassified'` **且** 该资产 `kind` 能派生出明确的非 `unclassified` 分类」时采用派生值，其余情况信任落盘值。
|
||||
- 为什么需要这条：`register_local_asset_entry`（`assets.rs`）命中同 `localPath` 的既有资产时**只在 `kind` 变化时**重算 `category`（2026-09-11 起）；所以历史上被写成 `unclassified` 的资产（典型是 `kind:"ui"` / `kind:"UI"` 因不在 canonical 目录而落到 `image → unclassified`）在补齐别名后**不会自愈**。选读时重派生而不是写迁移脚本：不需要迁移、且永久自愈（任何历史上被系统错判成 unclassified 的都会自动归位）。真机验证：`What do u wanna do kitten` 的待归类从 58 降到 1（只剩 code 类 `game-entry`），UI 交互从 2 升到 59。
|
||||
- **两个口径不能混用（2026-09-11 收口）**：`gameCreationAppAssetCategory` / `game_creation_app_asset_effective_category` 是**读显示**口径；写回 manifest 必须用 `gameCreationAppAssetPersistedCategory`（只做缺失 / 非法兜底），它等于 Rust 反序列化后的落盘原值。把自愈值回写会把「只改标签」变成静默改分类——真机上同一条 `kind:"ui"` 资产因此同时存在 `unclassified` 与 `ui-interaction` 两种落盘值。
|
||||
- **跨端必须同构**：Agent 侧资源投影（`direct_tool_bridge.rs`）走 Rust 的 `game_creation_app_asset_effective_category`，不许直接透传落盘 `category`；两侧不一致时同一条资产会出现「UI 显示 UI 交互、Agent 读到待归类」（真机 55 条）。守卫是 `assetKindCanonicalMapping.test.ts` 解析 Rust 源码里的 `EFFECTIVE_CATEGORY_CONTRACT` 决策矩阵。
|
||||
- **跨端必须同构**：Agent 侧资源投影（`direct_tool_bridge.rs`）走 Rust 的 `game_creation_app_asset_effective_category`，不许直接透传落盘 `category`；两侧不一致时同一条资产会出现「UI 显示 UI 交互、Agent 读到待归类」（真机 55 条）。**现行守卫（2026-09-17 起）**：`shared-contracts` 的 `EFFECTIVE_CATEGORY_CONTRACT` 决策矩阵用例 + `packages/shared` 的 `gameCreationApp.test.ts` 同口径用例；解析 Rust 源码的 `assetKindCanonicalMapping.test.ts` 已删除。
|
||||
- 为什么可以覆盖落盘值：落盘 `category` 的权威性来自「用户可在分类与标签面板手动设置」（`update_manifest_asset_classification_at`，`project/manifest.rs`）。收窄条件把覆盖窗口压到最小——只有当落盘值是 `unclassified`（即"没有明确分类"）时才覆盖。
|
||||
- **唯一盲区**：用户**手动**把一个 kind 已能明确分类的资产设成「待归类」时，该手动值会被覆盖。这是有意接受的取舍：「手动设为待归类」意图边缘，且 kind 已经表达了分类；而漏掉这条规则，所有历史误判都无法自愈。若将来产品需要"显式待归类"，应改成在 manifest 里区分"未设置"与"显式 unclassified"（例如 `category` 缺省 vs 显式写入），而不是取消本条规则。
|
||||
- 不受影响：`image` / `video` / `code` / `publication-material` 的 canonical 分类本身就是 `unclassified`，派生结果等于落盘值，规则不触发（已用断言钉住）。
|
||||
- 写入侧已同步 canonical 化：`infer_canvas_export_asset_kind`（`assets.rs`）现在直接产出 canonical kind（`ui → ui-design`、`animation → character-animation`、`asset → image`），不再依赖别名表兜底；`canvas_export_asset_kind_is_always_canonical` 用例逐分支钉死，别名表从此只承担存量兼容。
|
||||
- 写入侧已同步 canonical 化：`infer_canvas_export_asset_kind`（`assets.rs`）现在直接产出 canonical kind（`ui → ui-design`、`animation → character-animation`、`asset → image`），不再依赖别名表兜底；`canvas_export_asset_kind_is_always_canonical` 用例逐分支钉死。**2026-09-17 起别名表整体删除**，存量兼容也不做：读侧严格解析，认不出的原值只留痕。
|
||||
- 关联：`packages/shared/src/contracts/gameCreationApp.ts` 的 `gameCreationAppAssetCategory`、`apps/ai-game-creator-shell/src-tauri/src/assets.rs`、`apps/ai-game-creator-shell/tests/resourceCardPreviewRealManifest.test.ts`。
|
||||
|
||||
## 大写 `UI` / `font` 不在 alias 表 → 8 条真机 UI 资产永远落「待归类」，且自愈救不回（2026-09-11）
|
||||
|
||||
- 现象：真机 `What do u wanna do kitten` 有 8 条资产的 `kind` 是**大写** `"UI"`、`mediaType` 是 `application/json`、`localPath` 是 `ui/UI 设计 N.json`，永远停在「待归类」。
|
||||
- 成因链：写入侧写大写——`ui_editor/resource_bridge.rs` 的 `register_local_asset_at(root, &relative_path, "UI", "application/json", …)`，`workflow.rs` / `persistence.rs` 同；而 alias 表只有小写 `"ui" => "ui-design"`，于是 `"UI"` 落到 `canonical_game_creation_app_asset_kind` 的 `image` 兜底 → `image → unclassified`。
|
||||
- **为什么读时自愈救不回来**：自愈规则的前提是「派生值不是 unclassified」，而 `"UI"` 的派生值**就是** `unclassified`，规则永不触发。所以只能在 alias 表收口——别名表必须**大小写不敏感**（`UI` / `ui` / `ui-prototype` 都要落 `ui-design`），并把 `font`（`ttf / otf / woff / woff2` 上传登记的 kind，见 `commands.rs` 的 `register_local_asset_entry(root, &relative_path, "font", …)`）一并补进别名表落 `document`。
|
||||
- 守卫三层：Rust `asset_category_mapping_covers_every_canonical_kind` 逐条断言（旧断言曾把 `"UI" → unclassified` 钉死，正是这条 bug 的护栏反向加固）；`ui_editor/resource_bridge.rs` 的 `bridge_is_idempotent_and_installs_source_image` 走真实生产函数 → 真实写入 → 断言落盘 `category`；TS `assetKindCanonicalMapping.test.ts` 的「写侧 kind 字面量 → 分类」直接解析写侧源码的第 3 个实参，写点换个新字面量就会红。
|
||||
- 关联：`server-rs/crates/shared-contracts/src/game_creation_app.rs`、`packages/shared/src/contracts/gameCreationApp.ts`、`apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource_bridge.rs`、`apps/ai-game-creator-shell/tests/assetKindCanonicalMapping.test.ts`。
|
||||
- 成因链：写入侧写大写——`ui_editor/resource_bridge.rs` 的 `register_local_asset_at(root, &relative_path, "UI", "application/json", …)`，`workflow.rs` / `persistence.rs` 同；当时的 alias 表只有小写 `"ui" => "ui-design"`，`"UI"` 因此落 `image` 兜底 → `unclassified`。**注意 `font` 早已是正式 canonical 成员（不再靠别名落 `document`）**。
|
||||
- **为什么读时自愈救不回来**：自愈规则的前提是「派生值不是 unclassified」，而 `"UI"` 的派生值**就是** `unclassified`，规则永不触发。**现行口径（2026-09-17 起）**：不给 `"UI"` 找归一口径，而是修写入侧写 canonical 字面量；读侧严格解析，认不出的原值收口 `unknown` + `app_log!` 留痕（原始串 + 上下文）。
|
||||
- 守卫三层：Rust `asset_category_mapping_covers_every_kind` 穷举断言（旧的 `"UI" → unclassified` 断言正是这条 bug 的反向加固，已删）；`ui_editor/resource_bridge.rs` 的 `bridge_is_idempotent_and_installs_source_image` 走真实生产函数 → 真实写入 → 断言落盘 `category`；TS `parseGameCreationAppAssetKind` / `console.warn` 用例钉住"非 canonical 值收口 + 留痕原值"。
|
||||
- 关联：`server-rs/crates/shared-contracts/src/game_creation_app/asset_kind.rs`、`packages/shared/src/contracts/gameCreationApp.ts`、`apps/ai-game-creator-shell/src-tauri/src/ui_editor/resource_bridge.rs`、`apps/ai-game-creator-shell/tests/assetKind.test.ts`。
|
||||
|
||||
## AGC 资源搜索栏改成「临时叫出」的浮层，工具条带与它的下移逻辑一并撤掉（2026-09-11）
|
||||
|
||||
@@ -5738,3 +5762,25 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
- **处理（现行口径）**：① 依赖里只放数据，回调走 ref（`openActiveProjectRef`）——effect 不再因回调换身份而重跑；② `useDirectActiveTurns` 轮询只在快照内容变化时才 `setActiveTurns`（并给空态做引用稳定），避免每 5 秒换一次数组身份去带动下游 effect；③ `WindowChrome` 的 context value 用 `useMemo` 收口。判断类问题的通行判据：**凡是把"每次渲染新生成的函数/对象"写进 effect 依赖的，一律视为 bug**。
|
||||
- **验证**：修复后同一台机器、同一路径下 35 秒内新增 `Maximum update depth` **0 条**，renderer 工作集 **254 MB**（修复前 4.2–4.4 GB）；`apps/ai-game-creator-shell/tests/directActiveTurns.test.tsx` 断言轮询返回值不变时快照引用不变。
|
||||
- **关联**：`apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx`、`apps/ai-game-creator-shell/src/features/agent-runtime/directActiveTurns.ts`、`apps/ai-game-creator-shell/src/components/WindowChrome.tsx`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`。
|
||||
|
||||
## 2026-09-20 复用注册端口段时可能连到别的 worktree 的 SpacetimeDB
|
||||
|
||||
- **现象**：在 `/data/dsk/Genarrative` 跑 `npm run dev:api-server` 后，日志显示端口段 `10000-10099 (dsk)`、spacetime `http://127.0.0.1:10002`，但 api-server 反复报 `ws://127.0.0.1:10002/v1/database/xushi-p4wfr/subscribe` 返回 `HTTP error: 404 Not Found`，且始终不响应 `/healthz`。
|
||||
- **原因**：该端口段是**按用户**登记的，同一用户的其他 worktree 实例已占用 `10002`；启动器只探测到端口被占用就按"已复用"继续，api-server 于是连到了另一份 data-dir 的 standalone，那里没有当前 database，发布步骤也没有落到这个实例上。api-server 在启动恢复阶段会一直重试，**accept 了连接但不返回任何响应**，所以 `curl` 表现为超时而不是连接拒绝。
|
||||
- **处理（现行口径）**：核对 `ss -ltnp | grep :10002` 的进程与 `--data-dir` 是否属于当前仓库；不属于就换用空闲端口段（`GENARRATIVE_DEV_PORT_RANGE` / `--port-range`）或先停掉确认无用的实例，不要把 404 当作 schema 缺失去改代码。排查"健康检查通过但接口 404"时不要只跑 `/healthz`。
|
||||
- **关联**：`scripts/dev.mjs`、`scripts/dev-stack-port-utils.mjs`、`/var/tmp/genarrative-dev-port-ranges/registry.json`、[`.codex/skills/genarrative-dev-stack-port-routing/SKILL.md`](../../../.codex/skills/genarrative-dev-stack-port-routing/SKILL.md)。
|
||||
|
||||
## 2026-09-20 新增 API 命名空间在本地返回 404：Vite 代理是前缀白名单
|
||||
|
||||
- **现象**：api-server 上 `GET /api/game-distribution/games` 直连返回 200，但浏览器里 `http://127.0.0.1:<web>/games` 报 `404`，页面显示「读取游戏目录失败」。同一 URL 换成 `curl` 直连后端却正常。
|
||||
- **原因**：`vite.config.ts` 的 `server.proxy` 是**逐个前缀白名单**（`/api/auth`、`/api/profile`、`/api/runtime`、`/api/editor`、`/api/assets`、`/api/llm`、`/api/ws`），没有兜底 `/api/`。未登记的新命名空间不会转发到 Rust 后端，而是回退到 SPA 静态资源，前端再按 JSON 解析就失败。生产 nginx 走的是通用 `location ^~ /api/`，所以症状只出现在本地 dev。
|
||||
- **处理（现行口径）**：新增任何 `/api/<namespace>` 时，同一次变更里补 `vite.config.ts` 代理项和 `src/config/viteProxyConfig.test.ts` 断言；`src/config/**` 已加入 `vitest.config.ts` 的 include，漏测会直接红。注意该测试文件里可能残留已退役前缀（例如已退役的 `/api/creation-entry`）的断言，退役命名空间按「四不写」直接删断言，不要为它补代理。
|
||||
- **关联**：`vite.config.ts`、`src/config/viteProxyConfig.test.ts`、`vitest.config.ts`、`server-rs/crates/api-server/src/app.rs`、`deploy/nginx/genarrative.conf`。
|
||||
|
||||
## 2026-09-20 发行网关用 CORP same-origin 会让沙箱内游戏加载不了自己的脚本
|
||||
|
||||
- **现象**：平台游玩页的 iframe 明明 `onLoad` 了（加载遮罩消失、`game-player-frame--ready`），但控制台出现 `net::ERR_BLOCKED_BY_RESPONSE.NotSameOrigin … /releases/<gameId>/assets/app.js`，游戏内的脚本从未执行；直接在新标签页打开同一个 `index.html` 却一切正常，很容易误判成「已经能玩」。
|
||||
- **原因**：按安全合同 iframe 必须只用 `sandbox="allow-scripts"`（禁止 `allow-same-origin`），文档因此是不透明来源（opaque origin）。此时它对同包资源的请求不再与网关同源，而响应上的 `Cross-Origin-Resource-Policy: same-origin` 会把请求判为跨来源并拦下；ES modules 还会额外走 CORS，需要 `Access-Control-Allow-Origin`。
|
||||
- **处理（现行口径）**：发行网关的公开静态响应使用 `Cross-Origin-Resource-Policy: cross-origin` 与不带 credentials 的 `Access-Control-Allow-Origin: *`，继续保留 `X-Content-Type-Options: nosniff`、内容类型白名单、HTML 最小权限 CSP 和「带 Cookie 一律 403」。这些都是公开静态文件，放宽 CORP/CORS 不暴露凭据；容器隔离靠沙箱、CSP 与独立来源，不靠 CORP。
|
||||
- **验证方式**：不要只用 `onLoad` 判断可玩。要在真实浏览器里点「开始游戏」，确认控制台没有 `ERR_BLOCKED_BY_RESPONSE`/CSP 报错，并核对 api-server 访问日志里该版本资源的 `http.response.status_code=200`。
|
||||
- **关联**：`server-rs/crates/api-server/src/modules/game_distribution.rs`（`release_asset_response`）、`src/components/game-distribution/GamePlayPage.tsx`、[`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)。
|
||||
|
||||
@@ -63,6 +63,7 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐
|
||||
- 通用 Agent Rust 分层为 `agent-runtime-core`（catalog、执行生命周期、ToolHost/spawn/all-join/Provider 契约）、`agent-runtime-orchestration`（动态无环任务图、ready、依赖波次、返工下游闭包和受限自主扩图提案）与 `platform-agent` 游戏适配器；循环返工通过新 pass / epoch 表达，不在单张依赖图中建立回边。LLM 可经宿主结构化 function call 提出新增节点/边，编排层只生成经校验的新候选图，epoch 与持久化仍由宿主掌控。
|
||||
- DirectProject 始终连接客户端内置的 `agc_tools` STDIO MCP，并在启动时额外读取客户端扩展仓库中已启用的第三方 MCP 独立项。第三方 STDIO/HTTP 配置只写入本次隔离 `CODEX_HOME`，单项非 required，启停、重命名和内容指纹进入 app-server pool identity；完整 Plugin Runtime、hooks/apps 和单文件脚本手动指定入口仍关闭。Skill 正文与 references 由 Codex 原生按需读取；`agc_tools` 负责标准美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive、已登记图片去背景、desktop/mobile 浏览器试玩和受控 `agc_web_search`；付费资源调用仍由客户端绑定回合、幂等账本、请求上限和投影权威。
|
||||
- 2026-09-09 起，AGC 已新增遵循 OpenAI Agent Plugins 组合模型的通用 Plugin Host/SDK：Plugin、Skill 和 MCP 进入统一扩展 catalog；插件生命周期、行分隔 JSON-RPC、UI 面板、Capability Registry、权限和审计由 `plugin_host` 统一承接，Skill/MCP 仍分别交给各自现有 loader/transport；目标编辑器只通过通用 `EditorAdapter` 扩展点接入。详见 `docs/technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md`。
|
||||
- Unity 编辑器能力以 `plugins/agc-unity-editor` 内置插件提供，固定复用 Apache-2.0 的 DotCraft Attach 核心；Windows x64 / Unity Mono 接入不安装项目包。GUI、Runtime 与 DirectProject 通过现有 Runner 统一执行归属，跨进程回执与持久不确定阻断统一处理。首次打开 Unity 工程只初始化 AGC `.agent` 元数据，保留原引擎工程；详见 `docs/technical/【技术方案】AGC Unity编辑器插件接入-2026-09-18.md`。
|
||||
- DirectProject 的 Codex 原生文件、搜索、命令、图片查看和 Skill 仅在用户项目 cwd 与 `workspaceWrite(writableRoots=[project])` 内可用；原生命令允许联网以支持 npm 安装，npm 缓存位于项目内 `.npm-cache/`。多 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制保持关闭。app-server 使用隔离 `CODEX_HOME`，provider 凭据只由 AGC 客户端代理持有，不能进入模型上下文或 shell 环境。
|
||||
- `ui-prototype`（设计图片）与 UI 编辑器 `UI` JSON 是不同资源。白名单 `ui.workflow.run` 按页面执行 `prepare → recognize → status → finalize`，由 provider-backed 识别、合并和组件绑定持久化 State/revision，并把 `reference-ready → structure-ready → merge-ready → binding-ready → application-ready → completed` 投影到 manifest。Provider 缺失、请求失败、工具缺失、结果不匹配或仍有待审节点时保留真实阶段并返回 blocker，不得用 deterministic seed 伪造完成。
|
||||
- UI workflow 的资源桥接与 Runtime 边界以 `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md` 和 AGC 实施计划的 2026-08-24 覆盖段为准；只生成图片、登记空 JSON 或进入普通图片画布都不构成 workflow 完成。
|
||||
|
||||
@@ -16,23 +16,35 @@
|
||||
|
||||
## 开发中
|
||||
|
||||
- AGC 思考与执行入口共用共享单行摘要骨架；Markdown 只在展开正文走既有安全渲染，折叠预览只取纯文本，不在 summary 嵌套链接或按钮。耗时统一复用中文时分秒格式（不足一分钟一位小数，达到分钟后整数秒），格式化与各层计时边界分离。过程行在运行中和完成后的折叠层内保持同一紧凑间距；失败状态按明确终态与非零退出码呈现红色，不由自然语言输出猜测。
|
||||
- AGC 主模型追溯保存在项目 `.agent/model-usage.jsonl`，请求目录标识与响应确认的型号分别记录；旧项目当前配置补录必须标注来源，不冒充历史事实。仅保存有界模型与回合身份字段，不保存配置、凭据或对话正文，不增加 UI 展示。详见 AGC 实施计划“项目主模型使用记录”。
|
||||
|
||||
- Agent 提示词正文与工具说明放在所属组件的 `prompts/`；AGC 通过现有 Prompt Bundle 编译加载，服务端独立 crate 编译包含自己的提示词文件。代码负责变量填充、结构化 schema 与执行校验。
|
||||
|
||||
- 策划 Agent 的顾问态由用户指示驱动，不自主推进项目、主动安排下一步或提交阶段审批；完成单次请求不结束顾问态。五个策划阶段的审批用于检阅已完成产物，关键选择先问询；过程文档按需记录且不重复正式正文。顶层设计按需保留易混淆方向及排除理由，提示词精简应保留这些行为与设计边界。详见策划 Agent 生产迁移与工作区浏览方案。
|
||||
|
||||
- AGC 思考与执行入口共用共享单行摘要骨架；Markdown 在展开正文走既有安全渲染，折叠预览使用纯文本。耗时统一复用中文时分秒格式（不足一分钟一位小数，达到分钟后整数秒），格式化与各层计时边界分离。过程行在运行中和完成后的折叠层内保持同一紧凑间距；失败状态按明确终态与非零退出码呈现红色。
|
||||
|
||||
- Direct 对话计时区分条目展示时间与生命周期事件时间：整轮用用户发送到明确终态的跨度，工具用各自开始/完成边界；运行时用 100ms 叶子时钟刷新一位小数，终态冻结，旧历史缺边界不推测。不得用整秒时间的大小比较取代 Thread Manager 的事件顺序判定新回合。
|
||||
|
||||
- AGC 批量追加素材标签由原生在一次项目写锁与 revision CAS 下合并各项原标签，先校验全批再写 manifest；前端不能循环单素材分类命令，不回传展示层推导的分类或旧标签全集，以免部分写入或覆盖未编辑字段。
|
||||
|
||||
- AGC 平台服务固定为 `https://dev.genarrative.world`，会话凭据按 origin 隔离。发布渠道为 `dev/release/自定义名称`，Windows/Mac 是系统，OSS 的 `<channel>-win/mac` 仅是延续既有地址的分区。官网通过服务端 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`（默认 dev）选择渠道，公开同源 `/api/client-downloads` 汇总其各系统首装包与真实版本；未发布隐藏，单系统失败不影响其它下载，不跨渠道补齐。发布先上传 EXE/DMG 再写对应分区清单，不维护会互相覆盖的共享 OSS 索引。主站 Vite 代理复用实际 `runtimeServerTarget`。完整约定见 AGC 客户端更新检查与下载专题。
|
||||
- AGC 模板库灰度复用 `agc:template-library`：未配置关闭，已配置时遵循现有灰度启停、用户 ID/标签和比例规则；服务端返回权威结论，客户端入口和原生清单/下载/建项均执行门禁，主体切换丢弃旧异步结果。公开 OSS 不是保密边界，已创建项目不受影响。
|
||||
|
||||
- 画布卡片类型与信息角标共用 `CanvasCardCornerActions`；菜单收纳共用 `OverflowActions`，宿主决定展示数量和资源命令。AGC 选中菜单前 5 项直显，Web 默认不折叠；浮层 portal 继续接入现有画布关闭与滚轮归属判据。
|
||||
- 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本，不新建平行入口或业务真相。
|
||||
- UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用，禁止在业务页复制同类 UI。共享组件只承载通用表现与交互，不下沉领域规则、后端副作用或正式业务状态。
|
||||
- AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；宿主不按 Agent 类型重新定义过程字号和颜色，错误状态保留语义色。
|
||||
- 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本。
|
||||
- Agent 可见内容直接描述当前任务、输入和成功条件，细节按调用需要提供。
|
||||
- UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用。共享组件承载通用表现与交互，领域规则、后端副作用和正式业务状态由后端负责。
|
||||
- AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；过程字号和颜色由共享组件统一定义，错误状态保留语义色。
|
||||
- 后端遵循 `module-*`、`spacetime-module`、`spacetime-client`、`api-server`、`platform-*`、`shared-contracts` 的现役边界。
|
||||
- 前端只负责表现、交互和临时 UI 状态；正式状态来自后端投影、API 或持久化契约。
|
||||
- 对已明确退役且无现役调用方、公开契约、持久化迁移或活跃实例的对象，不写兼容实现、维持旧行为的测试、墓碑注释或墓碑文档。
|
||||
- 对已明确退役且无现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，直接清理实现、专属测试和说明，将权威文档更新为当前状态；历史由 Git 保存。公开契约、持久化数据和正式迁移按实际需求保留最小兼容及对应测试。
|
||||
- 修改 `/api/external/v1` 时，同批更新 `docs/openapi/genarrative-external-v1.openapi.json` 与契约测试。
|
||||
- 修改 SpacetimeDB schema 时遵守字段追加/default 约束，同步 migration、表目录、生成绑定，并运行 schema 检查；删除、改名、重排或改类型前先确认迁移计划。
|
||||
- 日志不递归输出完整配置、应用状态或 provider client；新增字段默认不进入安全摘要。
|
||||
- 中文文案、注释和文档保持 UTF-8，优先局部补丁，不擅自翻译成英文。
|
||||
- HTTP 横切能力集中在 Axum/Tower 中间件：正常与降级路由复用追踪层；指标与 trace 使用 `MatchedPath` 模板及固定兜底，不把请求 ID、实际资源 ID 或 query 放入指标标签。在途请求通过 RAII guard 覆盖 Future 取消与 panic unwind；请求执行和响应体存活分别计量，不能把 handler 耗时当作 SSE 全生命周期。
|
||||
- 业务依赖在组合根显式装配，Axum `FromRef` 只抽取可浅拷贝的窄能力。项目元数据与 External API 鉴权不持有完整 `AppState`，测试经相同接口注入替代依赖。集中鉴权仍保留方法级 fallback、公开入口、MCP 和 body limit 顺序；Provider span 跳过完整参数，不隐藏计费、重试、幂等或事务规则。
|
||||
- 中文文案、注释和文档保持中文与 UTF-8，优先局部补丁。
|
||||
|
||||
## 文档生命周期
|
||||
|
||||
|
||||
@@ -0,0 +1,221 @@
|
||||
# 【待办】AGC 资源 kind 枚举化扫描清单
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| 状态 | open |
|
||||
| 创建日期 | 2026-09-15 |
|
||||
| 所属主规范 | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` |
|
||||
| 关闭条件 | shell 内所有 GameCreationApp 资源 kind 候选均完成语义归类、代码处理决定和验证证据记录 |
|
||||
|
||||
## 扫描规则
|
||||
|
||||
只扫描 `apps/ai-game-creator-shell`。`server-rs` 只作为 api-server 有效词汇参考，不把 server-side `asset_kind` 纳入本清单迁移。
|
||||
|
||||
每个命中必须回到上下文并填写：位置、当前值、真实语义、是否进入 manifest、是否生产写入、目标类型、处理动作、验证证据。
|
||||
|
||||
## 首轮候选分组
|
||||
|
||||
### 必须审计为 GameCreationAppAssetKind
|
||||
|
||||
- `image`
|
||||
- `scene`
|
||||
- `character`
|
||||
- `character-animation`
|
||||
- `icon`
|
||||
- `icon-spritesheet`
|
||||
- `icon-spec`
|
||||
- `ui-design`
|
||||
- `ui-design-doc`
|
||||
- `publication-material`
|
||||
- `spec`
|
||||
- `video`
|
||||
- `audio`
|
||||
- `sound-effect`
|
||||
- `background-music`
|
||||
- `font`
|
||||
- `document`
|
||||
- `code`
|
||||
- `unknown`
|
||||
|
||||
### 已发现的非 canonical 候选，必须逐处判定
|
||||
|
||||
- `asset`
|
||||
- `ui`
|
||||
- `animation`
|
||||
- `game-background`
|
||||
- `character-art`
|
||||
- `game-art`
|
||||
- `illustration`
|
||||
- `art-spritesheet`
|
||||
- `art-spritesheet-slice`
|
||||
- `ui-prototype`
|
||||
- `game-entry`
|
||||
- `game-script`
|
||||
- `game-style`
|
||||
|
||||
### 明确暂不纳入本 PR
|
||||
|
||||
- `source.kind`
|
||||
- `source.generationKind`
|
||||
- MIME / `mediaType` / 文件扩展名
|
||||
- workflow、generation、task、path、tracking、plugin 等其他 kind 字段
|
||||
|
||||
## 初始文件入口
|
||||
|
||||
- `src-tauri/src/assets.rs`
|
||||
- `src-tauri/src/commands.rs`
|
||||
- `src-tauri/src/project/manifest.rs`
|
||||
- `src-tauri/src/project/resource_editor.rs`
|
||||
- `src-tauri/src/ui_editor/`
|
||||
- `src-tauri/src/agent/direct_runtime.rs`
|
||||
- `src-tauri/src/agent/direct_tool_bridge.rs`
|
||||
- `src-tauri/src/agent/generation/`
|
||||
- `src-tauri/src/agent/runtime_actions/`
|
||||
- `src/features/project-development/`
|
||||
- `src/features/project-workspace/`
|
||||
- `src/features/resource-canvas/`
|
||||
- `src/features/ui-editor/`
|
||||
|
||||
## 当前未决项
|
||||
|
||||
- [x] `asset`：确认是上传推断的兜底值，已改为无法判断时写 `Unknown`，不再回落到 `asset`。
|
||||
- [x] `art-spritesheet` / `art-spritesheet-slice`：确认是平台请求与图集 workflow 词汇；manifest 写入分别收口为 `IconSpritesheet` / `Icon`，协议标识只留在各自字符串字段。
|
||||
- [x] `game-background` / `game-art` / `illustration` / `character-art`：确认只出现在平台请求词汇；写入 manifest 前经显式转换函数收口为 `scene` / `image` / `character`。
|
||||
- [x] `ui` / `ui-prototype`：确认 UI 设计桥接与工作流已无生产 manifest writer，只写 `ui-design` / `ui-design-doc`。
|
||||
- [x] 非 canonical 原值留痕为「原始串 + 调用上下文」，由 `shared-contracts` 的可注册回调 `set_non_canonical_asset_kind_reporter()` 交给 AGC 壳的 `app_log!`（2026-09-17 起不再用 `tracing` / `kind-observability`）；生产 writer 只传正式枚举成员。
|
||||
- [x] ts-rs 生成路径为 `packages/shared/src/contracts/generated/`（2026-09-17 从 `apps/ai-game-creator-shell/src/contracts/generated/` 迁出），命令为 `cargo test -p shared-contracts --features ts-bindings export_bindings`（枚举自带 `export_to`），生成目录已在 `.prettierignore` / eslint `ignorePatterns` 中保持原始格式。
|
||||
- [ ] 接入 CI verify（在 CI 中跑一次 `export_bindings` 并断言生成文件无 diff）。
|
||||
|
||||
## 已确认的 manifest kind 入口（M0 审计结果）
|
||||
|
||||
下列位置已经确认直接承载或生产 `GameCreationAppAssetManifestEntry.kind`，后续迁移必须逐项完成：
|
||||
|
||||
| 位置 | 当前事实 | 后续动作 |
|
||||
| --- | --- | --- |
|
||||
| `src-tauri/src/assets.rs:584-604` | `register_local_asset_at` 以 `&str` 接受 kind 并转交登记 | 参数改为 Rust enum；边界字符串集中解析 |
|
||||
| `src-tauri/src/assets.rs:563-566` | 普通上传根据内容推断 kind 后登记 | 推断函数返回 enum；无法判断返回 `Unknown` 并 trace，禁止 `asset` fallback |
|
||||
| `src-tauri/src/assets.rs:791-806` | 画板导出图层登记资源 | 推断结果直接使用 enum |
|
||||
| `src-tauri/src/assets.rs:916-934` | 平台资源同步从 payload `assetKind` 登记 | 入口解析成 enum；未知值 `Unknown` + trace |
|
||||
| `src-tauri/src/assets.rs:1871-1916` | manifest 新增/更新资产并写入 kind | 禁止裸字符串和隐式 alias/fallback |
|
||||
| `src-tauri/src/commands.rs:2094-2129` | Tauri `register_local_asset` 接收外部 kind | 解析边界收紧为 enum/Unknown |
|
||||
| `src-tauri/src/commands.rs:2672-2711` | 字体导入生产路径登记 `"font"` | 正式保留 `Font` enum variant |
|
||||
| `src-tauri/src/commands.rs:2784-2803` | 字体登记测试/辅助路径 | 与生产字体 kind 一致 |
|
||||
| `src-tauri/src/project/resource_editor.rs:3806-4065` | 资源派生/替换构造 manifest asset | `source_subtype` / `asset_kind` 只在确认是 manifest kind 时改 enum；operation 临时类型另行排除 |
|
||||
| `src-tauri/src/ui_editor/workflow.rs:687-749` | UI 设计文档与图片资源登记 | `ui-design-doc` / `ui-design` 使用 enum |
|
||||
| `src-tauri/src/ui_editor/resource_bridge.rs:121-139` | UI 设计文档生产登记 | 使用 `UiDesignDoc` enum variant |
|
||||
| `src-tauri/src/agent/direct_runtime.rs:2462-2469` | 恢复图集登记仍传 `"art-spritesheet"` | manifest 写入改为 `IconSpritesheet`；恢复协议字符串单独审计 |
|
||||
| `src-tauri/src/agent/generation/canvas_generation.rs:6816-6828` | 切片 manifest 条目仍写 `"art-spritesheet-slice"` | manifest 写入改为 `Icon`；切片协议标识不自动替换 |
|
||||
| `src-tauri/src/agent/direct_tool_bridge.rs:1126-1183` | Agent 资源投影读取 manifest kind | 改为消费 enum，序列化边界仍输出 kebab-case |
|
||||
| `src-tauri/src/agent/direct_codex_user_item/wire.rs:66-96` | Agent 引用投影按 manifest 身份解析资源；不再展示裸 kind | 已消费 enum；UI 文档分支只用 `UiDesignDoc` 身份判据，无字符串展示 |
|
||||
|
||||
## 已确认的 shell TS 消费方
|
||||
|
||||
这些文件目前通过 `packages/shared/src/contracts/gameCreationApp.ts` 或手写 `string` 消费资源 kind，需迁入 shell 生成绑定：
|
||||
|
||||
- `src/features/project-workspace/resourceReferences.ts`
|
||||
- `src/features/project-workspace/ResourceReferenceInput.tsx`
|
||||
- `src/features/project-workspace/SupervisorChatOnlyView.tsx`
|
||||
- `src/features/project-workspace/ProjectSupervisorView.tsx`
|
||||
- `src/features/project-workspace/ProjectWorkspaceChatPane.tsx`
|
||||
- `src/view/project-development/index.tsx`
|
||||
- `src/view/project-development/ResourceClassificationPanel.tsx`
|
||||
- `src/view/project-development/ResourceRenameDialog.tsx`
|
||||
- `src/view/project-development/resourceProjectionModel.ts`
|
||||
- `src/features/resource-canvas/resourceCanvasBottomToolbarModel.ts`
|
||||
- `src/features/resource-canvas/resourceCanvasGenerationPanelView.tsx`
|
||||
- `src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx`
|
||||
- `src/features/resource-canvas/resourceVersionReplacementModel.ts`
|
||||
- `src/components/AssetImporter/utils.ts`
|
||||
- `src/components/AssetImporter/index.tsx`
|
||||
- `src/components/AssetImporter/settings.ts`
|
||||
- `src/services/clientApi.ts`
|
||||
- `src/view/ui-editor/useUiEditorPage.ts`
|
||||
- `src/features/ui-editor/uiDesignResourceBridge.ts`
|
||||
|
||||
其中 `resourceCanvasBottomToolbarModel.ts:243,258` 和 `resourceProjectionModel.ts:326` 已明确出现 `art-spritesheet` / `ui-prototype`，需回到调用链判断它们是 manifest kind 还是生成入口协议值，不能文本全局替换。
|
||||
|
||||
## 旧值生产状态初判
|
||||
|
||||
| 值 | 已发现位置 | 初判 |
|
||||
| --- | --- | --- |
|
||||
| `font` | `commands.rs:2672,2787`；UI Editor 字体登记 | 正式 manifest kind，保留 |
|
||||
| `audio` | `assets.rs:495`；上传推断与本地文件类型 | 正式 manifest kind，保留 |
|
||||
| `sound-effect` | `direct_tool_bridge.rs:104-116`；Agent 音频工具 | 正式 manifest kind，保留 |
|
||||
| `background-music` | `direct_tool_bridge.rs:104-116`；Agent 音频工具 | 正式 manifest kind，保留 |
|
||||
| `asset` | `assets.rs:537` 未知上传兜底；`assets.rs:1882` 空 kind 兜底 | 错误 fallback，改为 Unknown/显式失败后删除 |
|
||||
| `art-spritesheet` | `direct_runtime.rs:2465`；canvas generation 多处 | 既有 manifest/协议混用，逐处拆开 |
|
||||
| `art-spritesheet-slice` | `canvas_generation.rs:6818`；direct runtime 多处 | manifest kind 改为 `icon`，协议标识另留 |
|
||||
| `game-background` | canvas generation 选项与 runtime 阶段 | manifest kind 改为 `scene`，阶段标识另留 |
|
||||
| `game-art` | canvas generation 默认值/测试 | manifest kind 改为 `image`，生成请求字段另审 |
|
||||
| `illustration` | direct runtime 测试/恢复路径 | manifest kind 改为 `image`，其他用途另审 |
|
||||
| `character-art` | manifest/API 白名单与测试 | manifest kind 改为 `character`，API 参考不改 |
|
||||
| `ui-prototype` | UI workflow 检查、资源 bridge、TS 画布选项 | manifest kind 改为 `ui-design`；workflow 输入另审 |
|
||||
| `ui` | 旧 bridge/测试与外部输入 | 不再 alias；未知值进入 `Unknown`，逐处确认生产残留 |
|
||||
| `animation` | 旧映射及文本/阶段判断 | 不再 alias；仅 manifest kind 的位置改为 `character-animation` |
|
||||
| `game-entry` / `game-script` / `game-style` | runtime 代码文件登记 | manifest kind 改为 `code`；文件阶段标识不改 |
|
||||
|
||||
## 本轮明确排除的同名字段
|
||||
|
||||
以下命中不属于本 PR 的 `GameCreationAppAssetKind`，只记录边界，不修改：
|
||||
|
||||
- `source.kind`：`Uploaded / Generated / Canvas`，表达资源来源。
|
||||
- `source.generationKind`：包含 `ui-workflow.completed`、`project-file`、`icon-spritesheet` 等工作流/生成标识。
|
||||
- `mediaType`、MIME、扩展名和文件分类器。
|
||||
- Agent group、task kind、workflow stage、路径/目录名、tracking scope、插件 kind。
|
||||
|
||||
## 下一步审计动作
|
||||
|
||||
- [ ] 为每个“旧值生产状态初判”补充真实调用链和测试证据。
|
||||
- [ ] 将 manifest kind 与 generation/request kind 的复用关系改为显式转换，不共享裸字符串。
|
||||
- [ ] 确认 `Unknown` 在上传推断、外部 payload、manifest 读取三条入口的日志字段。
|
||||
- [ ] 完成 `packages/shared` import 使用方迁移清单，确认删除文件不会留下跨包引用。
|
||||
- [ ] 完成后更新本文件，关闭 M0 里程碑，再创建代码里程碑的实施计划。
|
||||
|
||||
## manifest 构造器逐处清单
|
||||
|
||||
| 位置 | 当前 kind | 生产/测试 | 决定 |
|
||||
| --- | --- | --- | --- |
|
||||
| `src-tauri/src/assets.rs:1914-1916` | 上游 `kind.to_string()` | 生产公共写入边界 | 改为接收 `GameCreationAppAssetKind`，统一负责序列化 |
|
||||
| `src-tauri/src/project/resource_editor.rs:3806-3809` | `source_subtype.to_string()` | 生产派生资源 | 先把 `source_subtype` 解析/转换为 manifest enum；临时 operation subtype 不得混入 |
|
||||
| `src-tauri/src/project/resource_editor.rs:4059-4065` | `asset_kind` | 生产派生资源 | 改为 manifest enum；调用方显式转换 |
|
||||
| `src-tauri/src/agent/generation/canvas_generation.rs:6816-6828` | `art-spritesheet-slice` | 生产切片回写 | 改为 `Icon`；只保留协议层切片标识在独立字符串字段 |
|
||||
| `src-tauri/src/ui_editor/workflow.rs:1468-1475` | 测试 helper 参数 `kind` | 测试 | helper 改为 enum，fixture 只使用正式成员 |
|
||||
| `src-tauri/src/project/manifest/recovery_tests.rs:181-183` | `character` | 测试 fixture | 改为 enum variant |
|
||||
| `src-tauri/src/agent/direct_tool_bridge.rs:3189-3192` | `art-spritesheet-slice` | 测试 fixture | 如果测试 manifest 语义，改为 `Icon`；协议测试另造明确协议字段 |
|
||||
| `src-tauri/src/agent/direct_tool_bridge.rs:3246-3249` | `character-animation` | 测试 fixture | 改为 enum variant |
|
||||
| `src-tauri/src/agent/direct_tool_bridge.rs:3297-3299` | `spec` | 测试 fixture | 改为 enum variant |
|
||||
| `src-tauri/src/agent/direct_tool_bridge.rs:3339-3342` | `ui` | 旧兼容测试 | 删除 alias 断言；改为 `Unknown` + trace 测试或移至 parser 边界测试 |
|
||||
| `src-tauri/src/project/resource_dependency_graph.rs:652-656` | `test` | 测试 fixture | 改为 `Unknown`，明确测试未知 kind 投影，不得继续写任意字符串 |
|
||||
| `src-tauri/src/commands.rs:2888-2892` | `font` | 测试 fixture | 改为 `Font` enum variant |
|
||||
|
||||
## shell TS 类型迁移清单（已发现裸 string）
|
||||
|
||||
以下字段目前仍是 `string` / `string | null`，但若其语义是 manifest `assetKind`，必须改为生成的 `GameCreationAppAssetKind`；若只是外部 API 开放值，保留并在清单中标注转换边界：
|
||||
|
||||
- `src/services/clientApi.ts:198`
|
||||
- `src/view/ui-editor/useUiEditorPage.ts:81,1077`
|
||||
- `src/components/AssetImporter/utils.ts:7,32,114`
|
||||
- `src/components/AssetImporter/index.tsx:61`
|
||||
- `src/features/resource-canvas/resourceCanvasBottomToolbarModel.ts:79`
|
||||
- `src/features/project-workspace/DeveloperProjectPanels.tsx:15`
|
||||
- `src/features/project-workspace/ResourceReferenceInput.tsx:104`
|
||||
- `src/features/resource-canvas/resourceVersionReplacementModel.ts:232-245`
|
||||
- `src/features/project-workspace/resourceReferences.ts:101-134`
|
||||
- `src/view/project-development/resourceProjectionModel.ts:319-345`
|
||||
- `src/features/ui-editor/uiDesignResourceBridge.ts:55-87`
|
||||
- `src/App.tsx:1262,10083`
|
||||
|
||||
特别处理：
|
||||
|
||||
- `resourceCanvasBottomToolbarModel.ts:243` 的 `art-spritesheet` 和 `:258` 的 `ui-prototype` 当前位于生成入口选项，需先确认该字段是否传入 manifest 登记；若只是 API/生成请求 kind，使用显式转换函数，不把旧值加入 manifest enum。
|
||||
- `resourceProjectionModel.ts:326`、`uiDesignResourceBridge.ts:87` 是直接比较 manifest asset kind 的消费点，必须跟随生成绑定迁移到 enum。
|
||||
- `SupervisorChatOnlyView.tsx`、`ProjectSupervisorView.tsx` 等仍直接从 `packages/shared` 导入 manifest 类型，需在删除旧文件前完成 shell 内导入收口。
|
||||
|
||||
## 已迁移的 TS 边界（增量）
|
||||
|
||||
- `packages/shared/src/contracts/gameCreationApp.ts`：直接 re-export Rust 生成的 `GameCreationAppAssetKind`，`parseGameCreationAppAssetKind(raw, context)` 未知输入 `console.warn` 记录 `rawKind` / `sourceContext` 并返回 `unknown`，不做旧 alias 转换；`src/contracts/assetKind.ts` 这层 shell 内重复实现已删除（2026-09-17）。
|
||||
- `src/features/project-workspace/resourceReferences.ts`：资源引用 kind 改为生成枚举类型并通过 parser 收口。
|
||||
- `src/view/project-development/index.tsx`：画布引用入口通过同一 parser 构造资源引用 kind。
|
||||
- `src/features/ui-editor/uiDesignResourceBridge.ts`：UI 原型 manifest kind 只接受 `ui-design`，UI 文档链接只接受 `ui-design-doc`；旧 `ui-prototype` 不再 alias。
|
||||
|
||||
其余 `packages/shared` import 和前端 manifest `kind: string` 字段仍未迁移，继续作为后续小切片，不在本次提交中伪装完成。
|
||||
Reference in New Issue
Block a user