From 6f2137cbb0df097a27b371e487eb2eba5cf0d11b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Tue, 15 Sep 2026 15:12:24 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85AGC=E8=B5=84=E6=BA=90kind?= =?UTF-8?q?=E6=9E=9A=E4=B8=BE=E5=8C=96=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增资源 kind 枚举化主规范与边界。 新增词汇审计、Rust 绑定、写入清理三个里程碑。 新增 shell-only 资源 kind 扫描 todo 清单。 通过文档索引、编码与 diff 检查。 --- docs/README.md | 2 + ...】AGC资源kind词汇审计与绑定架构-2026-09-15.md | 43 ++++++++++ ...C资源kind枚举化Rust绑定与内部收紧-2026-09-15.md | 38 ++++++++ ...AGC资源kind枚举化写入方清理与验证-2026-09-15.md | 37 ++++++++ ...C资源kind枚举化词汇审计与绑定架构-2026-09-15.md | 46 ++++++++++ ...办】AGC资源kind枚举化扫描清单-2026-09-15.md | 86 +++++++++++++++++++ ...案】AI游戏创作智能体App实施计划-2026-06-24.md | 16 +++- 7 files changed, 266 insertions(+), 2 deletions(-) create mode 100644 docs/project-memory/plans/【实施计划】AGC资源kind词汇审计与绑定架构-2026-09-15.md create mode 100644 docs/project-memory/plans/【里程碑】AGC资源kind枚举化Rust绑定与内部收紧-2026-09-15.md create mode 100644 docs/project-memory/plans/【里程碑】AGC资源kind枚举化写入方清理与验证-2026-09-15.md create mode 100644 docs/project-memory/plans/【里程碑】AGC资源kind枚举化词汇审计与绑定架构-2026-09-15.md create mode 100644 docs/project-memory/todos/【待办】AGC资源kind枚举化扫描清单-2026-09-15.md diff --git a/docs/README.md b/docs/README.md index 55a6fdd82..21d8cacb5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,6 +25,8 @@ ## AI 游戏创作与 Agent Runtime +- [AGC 资源 kind 枚举化契约](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#2026-09-15-gamecreationapp-资源-kind-枚举化当前权威口径)：GameCreationApp 资源 kind 的 Rust enum、ts-rs 绑定、Unknown 可观测性和 shell 内重构边界。 + - [策划 Agent 生产迁移与工作区浏览](./technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)：实施中；以自由协作原型为行为基线，复用生产基建，采用阶段审批与用户工作区文件浏览。无旧 V2 会话的策划入口切换到新设计 Agent。 - [LLM 累计额度结算](./technical/【技术方案】LLM累计额度结算-2026-09-05.md)：Router 累计额度、首次基线与原子钱包结算。 diff --git a/docs/project-memory/plans/【实施计划】AGC资源kind词汇审计与绑定架构-2026-09-15.md b/docs/project-memory/plans/【实施计划】AGC资源kind词汇审计与绑定架构-2026-09-15.md new file mode 100644 index 000000000..88e10dd9a --- /dev/null +++ b/docs/project-memory/plans/【实施计划】AGC资源kind词汇审计与绑定架构-2026-09-15.md @@ -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，不进入代码里程碑。 diff --git a/docs/project-memory/plans/【里程碑】AGC资源kind枚举化Rust绑定与内部收紧-2026-09-15.md b/docs/project-memory/plans/【里程碑】AGC资源kind枚举化Rust绑定与内部收紧-2026-09-15.md new file mode 100644 index 000000000..4ee51a9a0 --- /dev/null +++ b/docs/project-memory/plans/【里程碑】AGC资源kind枚举化Rust绑定与内部收紧-2026-09-15.md @@ -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。 diff --git a/docs/project-memory/plans/【里程碑】AGC资源kind枚举化写入方清理与验证-2026-09-15.md b/docs/project-memory/plans/【里程碑】AGC资源kind枚举化写入方清理与验证-2026-09-15.md new file mode 100644 index 000000000..cb8083312 --- /dev/null +++ b/docs/project-memory/plans/【里程碑】AGC资源kind枚举化写入方清理与验证-2026-09-15.md @@ -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 检查通过。 diff --git a/docs/project-memory/plans/【里程碑】AGC资源kind枚举化词汇审计与绑定架构-2026-09-15.md b/docs/project-memory/plans/【里程碑】AGC资源kind枚举化词汇审计与绑定架构-2026-09-15.md new file mode 100644 index 000000000..e77dc3cb3 --- /dev/null +++ b/docs/project-memory/plans/【里程碑】AGC资源kind枚举化词汇审计与绑定架构-2026-09-15.md @@ -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` 不误收编。 diff --git a/docs/project-memory/todos/【待办】AGC资源kind枚举化扫描清单-2026-09-15.md b/docs/project-memory/todos/【待办】AGC资源kind枚举化扫描清单-2026-09-15.md new file mode 100644 index 000000000..33b659538 --- /dev/null +++ b/docs/project-memory/todos/【待办】AGC资源kind枚举化扫描清单-2026-09-15.md @@ -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 实现。 diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md index 3917ebd68..b7c5a619e 100644 --- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md +++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md @@ -1,5 +1,17 @@ # AI 游戏创作智能体 App 实施计划 +## 2026-09-15 GameCreationApp 资源 kind 枚举化（当前权威口径） + +本节覆盖并替代下方 2026-09-09 资源 kind 别名、canonical fallback 与读时自愈相关口径。当前仍在开发期，不为旧本地 manifest 提供 migration、alias 兼容或静默转换；旧值只会在解析时落入 `Unknown` 并记录结构化日志，后续按扫描清单清理产生旧值的代码。 + +本次重构范围限定在 `apps/ai-game-creator-shell` 内表达 **GameCreationApp 资源 kind** 的字段、参数、投影、筛选和 manifest 读写边界。`mediaType`、MIME、文件扩展名、`source.kind`、`source.generationKind`、任务/工作流 kind、路径名，以及 server-side 其他 `asset_kind` 不在本次重构范围内，继续使用各自现有类型。 + +Rust 侧在 `server-rs/crates/shared-contracts` 维护唯一权威 `GameCreationAppAssetKind` enum，并使用 `serde` kebab-case 序列化；`Unknown` 是正式解析结果，序列化值为 `unknown`。TypeScript 绑定由 `ts-rs` 从 Rust 生成到 `apps/ai-game-creator-shell` 内，删除 `packages/shared/src/contracts/gameCreationApp.ts` 中重复的手写 kind 契约。正常写入路径不得主动构造 `Unknown`；未知外部值进入 `Unknown` 时必须记录原始值、来源和调用上下文的 `tracing`/日志。 + +当前候选正式成员以 api-server 仍有效的资源 kind 命名为基线，并保留 shell 已实际使用的字体与通用音频语义：`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`。`audio` 表示通用上传音频，`sound-effect` 与 `background-music` 表示更具体的生成/资源语义，不因同属 `audio` category 而合并。`asset`、`ui`、`animation`、`game-background`、`art-spritesheet` 等旧值必须逐处审计：进入 GameCreationAppAssetKind 的生产写入改为正式成员；仅作为 workflow、generation、路径或协议标识的值保持原字段，留待后续独立 PR。 + +实施要求：先完成 shell 内 raw kind / typed kind 扫描清单与生产写入审计，再分小提交实现 Rust enum、生成绑定、内部字段收紧、写入方修正、Unknown 可观测性和旧 alias 删除。每个提交只形成一个可验证的深模块，不把不同领域的字符串类型强行合并；完成后补充 `ts-rs` 生成/校验门禁、serde round-trip、未知值日志和所有 manifest writer 的 canonical/Unknown 边界测试。 + ## 2026-09-12 已有项目打开响应性 DirectProject 工作区只恢复自身对话，不按专业 Agent 默认任务占位行批量读取旧会话或生成专业 Agent 文本回执。专业 Agent 结果加载 effect 必须以当前 Runtime 模式为边界，并在模式切换时清空旧结果。仍供开发入口使用的 `read_local_conversation` 在 blocking worker 内完整执行权限校验、会话目录解析和历史读取，避免文件访问或锁等待阻塞 Tauri 窗口线程。 @@ -32,9 +44,9 @@ DirectProject 自身的 `read_direct_project_conversation` 也必须在 blocking ## 2026-09-09 manifest 资源功能分类与自定义标签（数据层） -本地 manifest 资产条目末尾新增 `category`（单值，6 类 `ui-interaction / character / scene / audio / document / unclassified`，默认 `unclassified`）与 `tags`（字符串数组，默认空数组）；字段始终序列化，不进 api-server、外部 OpenAPI 或 SpacetimeDB schema。默认分类由 `GAME_CREATION_APP_ASSET_CATEGORY_BY_KIND` 按 canonical kind 穷举映射：`icon / icon-spritesheet / icon-spec / ui-design → ui-interaction`，`character / character-animation → character`，`scene → scene`，`audio / sound-effect / background-music → audio`，`document / spec → document`，`image / video / code / publication-material → unclassified`；alias 表**大小写不敏感**（UI 设计资产的现役写入侧写的是大写 `"UI"`，`font` 是字体上传登记的 kind），`"UI" → ui-design → ui-interaction`、`font → document → document`；其余映射不到 canonical kind 的原始 kind（例如 `test`）才经 `canonicalGameCreationAppAssetKind` 落 `image`、归 `unclassified`。读显示口径在 TS（`gameCreationAppAssetCategory`）与 Rust（`game_creation_app_asset_effective_category`）同构，写回 manifest 必须用落盘原值 `gameCreationAppAssetPersistedCategory`。 +本地 manifest 资产条目末尾新增 `category`（单值，6 类 `ui-interaction / character / scene / audio / document / unclassified`，默认 `unclassified`）与 `tags`（字符串数组，默认空数组）；字段始终序列化，不进 api-server、外部 OpenAPI 或 SpacetimeDB schema。默认分类继续由资源 kind 到 category 的显式映射决定：`icon / icon-spritesheet / icon-spec / ui-design → ui-interaction`，`character / character-animation → character`，`scene → scene`，`audio / sound-effect / background-music → audio`，`document / spec / font → document`，`image / video / code / publication-material / unknown → unclassified`。kind 枚举、未知值与写入边界以本文件顶部 2026-09-15 口径为准；本节不再定义 alias、canonical fallback 或旧 manifest 自愈。 -历史 manifest 缺少字段时读取按 `kind` 派生分类、`tags` 取空数组；显式写入的合法分类原样保留，未知分类字符串按前向兼容退回 `kind` 派生。新建资源条目写 `kind` 派生默认值，更新既有条目保留已有 `category` / `tags`，不覆盖用户值。`tags` 归一化（trim、去空、去重）只以纯函数交付，本轮不接入写入路径。本轮不做任何 UI（画布功能画布与筛选、@ 面板标签筛选、标签管理面板）、数据迁移脚本、标签库聚合派生与 Agent 检索工具。 +开发期 manifest 只按当前枚举解析；旧字段兼容、迁移脚本与 alias 不属于当前目标。新建资源条目必须由已验证的 `GameCreationAppAssetKind` 写入；未知输入只能产生 `Unknown` 解析结果并记录日志，不能由 writer 静默改成其他 kind。`tags` 归一化（trim、去空、去重）保持现有规则。本节原有 UI、标签库和 Agent 检索范围不因本次 kind 枚举化扩大。 ## 2026-09-08 Web 游戏 npm 与 Phaser 4 产物合同