补充AGC资源kind枚举化规范

新增资源 kind 枚举化主规范与边界。新增词汇审计、Rust 绑定、写入清理三个里程碑。新增 shell-only 资源 kind 扫描 todo 清单。通过文档索引、编码与 diff 检查。
2026-09-15 15:12:24 +08:00
parent 70a2246e8b
commit 6f2137cbb0
7 changed files with 266 additions and 2 deletions
@@ -0,0 +1,43 @@
+# 【实施计划】AGC 资源 kind 词汇审计与绑定架构
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC资源kind枚举化词汇审计与绑定架构-2026-09-15.md` |
+| Status | ready |
+| 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,38 @@
+# 【里程碑】AGC 资源 kind 枚举化 Rust 绑定与内部收紧
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | planned |
+| 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。
+- `source.kind`、`generationKind`、MIME 和文件格式。
+- 其他领域字段为配合本里程碑进行“顺手枚举化”。
+
+## 依赖与前置条件
+
+- 词汇审计里程碑通过并关闭所有阻塞项。
+- 生成目录、TS 导入路径、Unknown 日志字段和 writer 禁止主动写 Unknown 的规则已确认。
+
+## 验收标准
+
+- [ ] Rust enum 与生成的 TS 绑定值逐项一致，JSON 使用 kebab-case。
+- [ ] 未知输入得到 `Unknown`，日志包含原始值与调用上下文。
+- [ ] 生产 writer 不再接受裸 `string` 作为 GameCreationApp kind。
+- [ ] `font`、`audio`、`sound-effect`、`background-music` 均有真实生产路径或明确的测试证据。
+- [ ] 旧 alias 不再由共享契约转换为 canonical。
@@ -0,0 +1,37 @@
+# 【里程碑】AGC 资源 kind 枚举化写入方清理与验证
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | planned |
+| 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 生产逻辑及其只服务于旧值的测试。
+- 为每个仍保留的非 manifest kind 字符串补充 todo，转入后续独立 PR。
+
+## 不在范围内
+
+- 不改 `source.kind`、`generationKind` 等其他字段，即使它们恰好使用同名值。
+- 不修改 server-side 代码或公开 API。
+- 不实现字体格式/MIME enum；`font` 只作为本次 manifest asset kind 成员。
+
+## 依赖与前置条件
+
+- Rust/TS 绑定里程碑通过。
+- 写入方扫描清单中每个 alias 都已有“manifest kind / 其他领域 / 删除”结论。
+
+## 验收标准
+
+- [ ] 新建、导入、生成、恢复、替换路径不会写入未纳入 enum 的 manifest kind。
+- [ ] 未知外部值只进入 `Unknown` 并有 trace，不会被静默改成 `image` 或 `asset`。
+- [ ] `source.kind` 与 `generationKind` 的既有字符串行为不变。
+- [ ] 定向 Rust、TS、绑定生成、编码和 diff 检查通过。
@@ -0,0 +1,46 @@
+# 【里程碑】AGC 资源 kind 枚举化词汇审计与绑定架构
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | approved |
+| 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 当前仍有效的同语义 kind 作为命名与 serde 值参考，并评估 shell 当前实际生产 kind；排除 api-server legacy、billing/storage taxonomy 和其他开放领域。
+- 确认 Rust enum、`Unknown`、kebab-case JSON 和 ts-rs 生成文件的归属、生成命令与校验门禁。
+- 形成逐项 todo：当前值、真实语义、生产/测试状态、目标 enum、是否改写、验证方式。
+
+## 不在范围内
+
+- 不扫描或修改 server-side 代码；api-server 只提供词汇参考。
+- 不改 `mediaType`、MIME、文件扩展名、`source.kind`、`source.generationKind`、任务/工作流 kind、路径名或 tracking scope。
+- 不在本里程碑修改 manifest writer、前端消费方或公开 API。
+- 不实现旧 manifest migration、alias 表或 fallback 清理。
+
+## 依赖与前置条件
+
+- 主规范已确认资源 kind 候选集合、`Unknown` 语义和 shell 边界。
+- `shared-contracts` 当前被 server-rs 多个 crate 使用，ts-rs 生成能力必须 feature-gated 或由独立生成入口启用，不能污染默认 SpacetimeDB/WASM 构建。
+- 当前已有 Tauri ts-rs 生成测试可作为生成命令形态参考，但不复用 UI Editor 类型目录作为资源契约目录。
+
+## 验收标准
+
+- [ ] shell 内 manifest 资源 kind 的生产写入点、解析点、投影点和测试 fixture 有完整清单。
+- [ ] 每个旧值均已标注为：正式 GameCreationApp kind、其他领域字符串、legacy/错误 fallback；没有只按 grep 结果猜测的条目。
+- [ ] api-server 有效值、shell 扩展值和排除值各有明确依据。
+- [ ] 生成架构不会要求 server-side 默认构建安装 ts-rs。
+- [ ] todo 清单的每项都有关闭条件和对应验证证据。
+
+## 证据要求
+
+- 自动化：raw kind 扫描脚本/报告、Rust/TS 生成试验、serde kebab-case round-trip 试验。
+- 文档：主规范、todo 清单、下一里程碑实施计划互相链接且无冲突。
+- 边界：至少覆盖 `font`、`audio`、`sound-effect`、`background-music`、`Unknown`，以及 `source.kind`/`generationKind` 不误收编。
@@ -0,0 +1,86 @@
+# 【待办】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/`
+
+## 当前未决项
+
+- [ ] 逐处确认 `asset` 是错误 fallback 还是其他领域标识。
+- [ ] 逐处确认 `art-spritesheet` / `art-spritesheet-slice` 是 manifest kind 还是图集 workflow 标识。
+- [ ] 逐处确认 `game-background` / `game-art` / `illustration` / `character-art` 的写入边界。
+- [ ] 逐处确认 `ui` / `ui-prototype` 是否仍有生产 manifest writer。
+- [ ] 确认 `Unknown` 的 tracing 字段和 writer 禁止规则。
+- [ ] 确认 ts-rs 生成文件的实际路径、生成命令和 CI verify 实现。