新增AGC资源kind绑定实施计划

限定首个代码切片为 Rust enum 与 ts-rs 生成边界。

明确不修改 manifest 字段和其他资源字符串领域。

列出绑定、serde round-trip 与定向验证门禁。
This commit is contained in:
2026-09-15 15:29:37 +08:00
parent 42969b2218
commit b14a533b17
@@ -0,0 +1,46 @@
# 【实施计划】AGC 资源 kind Rust 枚举与 ts-rs 绑定
| 字段 | 值 |
| --- | --- |
| Milestone | `docs/project-memory/plans/【里程碑】AGC资源kind枚举化Rust绑定与内部收紧-2026-09-15.md` |
| Status | ready |
| 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 证据。
明确不修改:
- manifest 结构体的 `kind: String` 字段及所有调用方(留给下一个小提交);
- `category``mediaType``source.kind``source.generationKind`
- api-server、SpacetimeDB schema、OpenAPI
- alias/fallback 删除和 Unknown writer 处理(留给后续切片)。
## 实现顺序
1. 新建独立 kind 模块,定义当前正式成员:17 个现有 canonical kind + `font` + `Unknown`serde 使用 kebab-case。
2. 为 enum 增加可选 ts-rs derive,默认 shared-contracts 构建不引入 ts-rs。
3. 让 shell 的 shared-contracts 依赖打开绑定 feature,在 shell 专属 contracts/generated 目录生成 TS。
4. 增加 Rust serde round-trip 与 Unknown 解析/序列化测试;增加 TS 生成文件存在和值集合测试。
5. 运行 shared-contracts 与 shell 定向测试;通过后暂停,等待下一个内部字段收紧切片。
## 验证命令
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 --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml exports_game_creation_app_asset_kind`
4. `npm run check:encoding`
5. `git diff --check`
## 风险与回滚点
- 风险:ts-rs 默认生成 enum/union 形态与 serde rename 不一致;必须以生成文件和 round-trip 测试为准。
- 风险:shared-contracts 被 SpacetimeDB/WASM 使用;ts-rs 必须是 optional feature,默认构建不可依赖。
- 回滚点:本切片仅新增 enum/绑定,不改变现有 manifest JSON 解析;若生成链路不稳定,可回滚本提交而不影响现有业务。