Merge remote-tracking branch 'refs/remotes/origin/master' into feat/gptimage2to2.5

2026-09-19 15:39:41 +08:00
parent c8311a47b0 33f5ad68bf
commit 3da0936c1f
228 changed files with 15831 additions and 3162 deletions
@@ -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，不进入代码里程碑。
@@ -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,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 错误、多引用和路径来源均有测试。