资源 kind 严格口径的文档补齐：单一解析入口与登记边界

- docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md：2026-09-17 节改为唯一解析入口 `parse_with_context()`（内部私有 `match_canonical()`，`from_str_lossy` / 公开 `from_str_or_unknown` 均已删除），并新增登记边界同口径、登记内容 kind 必须与内容相符、切片残留判据只看路径、sprite 身份不含展示串、TS 判据只留一份与「严格口径已知代价、不迁移」六条。
- docs/project-memory/shared-memory/decision-log.md：同一节补上单一解析入口、登记边界 kind 口径、判据不许散落、已知代价不补救四条决策，并把验证命令更新为实际跑过的定向用例。

docs/project-memory/shared-memory/decision-log.md

@@ -6,10 +6,13 @@
 
 - 背景：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>` 守住。
-- 决策（严格口径）：`from_str_or_unknown()` 只做等值匹配——不 trim、不 lowercase、不查别名、不迁移；认不出的值收口成 `Unknown`（分类落 `unclassified`）。这是有意接受的行为（历史误写的 kind 不会被"救回"正确栏目），不再提供任何兼容入口；`font` 是正式成员，不再走别名。
+- 决策（单一解析入口）：`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/兜底。栅格归一化的 `source_subtype` 只接受图片族成员，文档/字体/音频等一律按 `image` 登记；Agent 回执派生物按 `Text => Document` 落 `document`，不主动写 `unknown`。
+- 决策（判据不许散落）：切片残留登记只看 `assets/art-spritesheet-slices/` 路径（不再附带 `kind == Icon`）；sprite 身份比较忽略随 kind 派生的 `metadata.asset_type`；TS 侧「UI 编辑器文档资产」判据只留 `isGameCreationAppUiDesignDocAsset()` 一份，资源画布入口 / UI 编辑器桥接 / 资源引用缩略图统一调用。
+- 决策（已知代价，不补救）：既有项目里 legacy kind 读入即 `unknown`，依赖 kind 等值比较的运行门禁会按"缺少该资源"处理。这是「不迁移、不 fallback」的必然结果，本次明确不为存量数据做迁移；将来若要迁就必须单独立项（一次性迁移或读侧白名单），不得把别名表加回解析路径。
 - 决策（留痕必须真的落地）：原实现用 `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`。
 - 决策（平台/画板词汇表）：`AGENT_RUNTIME_CANVAS_ASSET_KINDS`（`canvas.asset_generate.assetKind` 的 enum）与 `platform_art_asset_manifest_kind()` 是「平台词汇 → manifest kind」的唯一映射点，保留原词汇但把认不出的原值改为留痕收口；对外 API 的 `EDITOR_IMAGE_EDIT_STATIC_IMAGE_ASSET_KINDS` 白名单保持原样（API 兼容面，不代表客户端归一规则）。
-- 验证：`cargo test -p shared-contracts`（含词汇表唯一性、严格性与留痕用例）、`cargo test --locked -p shared-contracts --features ts-bindings export_bindings` 后 `git diff` 为空、AGC bin 定向用例、`npx vitest run packages/shared/src/contracts/gameCreationApp.test.ts apps/ai-game-creator-shell/tests/assetKind.test.ts`。
+- 验证：`cargo test -p shared-contracts`（含词汇表唯一性、严格性与留痕用例）、`cargo test --locked -p shared-contracts --features ts-bindings export_bindings` 后 `git diff` 为空、AGC bin 定向用例（`platform_art_asset_manifest_kind_maps_platform_vocabulary_explicitly`、`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 深模块

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -6,7 +6,13 @@
 
 - **唯一词汇表**：kind 的变体、线上值（kebab-case）、`as_str()`、`ALL`、严格解析与 ts-rs 绑定全部由 `server-rs/crates/shared-contracts/src/game_creation_app/asset_kind.rs` 的声明表派生。`GAME_CREATION_APP_CANONICAL_ASSET_KINDS`、`canonical_game_creation_app_asset_kind()`（含 `font → document` 特例与 legacy 别名表）已删除；TS 侧同名的 `GAME_CREATION_APP_CANONICAL_ASSET_KINDS`、`GameCreationAppCanonicalAssetKind`、`GAME_CREATION_APP_LEGACY_ASSET_KINDS`、`canonicalGameCreationAppAssetKind()` 一并删除，仓库里不再有第二份 kind 列表。
 - **TS 生成路径**：`GameCreationAppAssetKind` 由 ts-rs 生成到 `packages/shared/src/contracts/generated/GameCreationAppAssetKind.ts`（不再是 `apps/ai-game-creator-shell/src/contracts/generated/`）；`packages/shared/src/contracts/gameCreationApp.ts` 直接 re-export 该 union，运行期 kind 列表只有一份 `GAME_CREATION_APP_ASSET_KINDS`（穷举 `Record<GameCreationAppAssetKind, true>` 保证不会与生成 union 分叉）。重新生成：`cargo test --locked -p shared-contracts --features ts-bindings export_bindings --manifest-path server-rs/Cargo.toml`，之后 `git diff` 必须为空。两张生成目录的忽略规则同步登记在 `.prettierignore` 与 `.eslintrc.cjs`。
-- **严格解析**：`GameCreationAppAssetKind::from_str_or_unknown()` 只做等值匹配——不 trim、不 lowercase、不查别名；`FromStr`、serde 与所有外部边界统一走 `parse_with_context(value, context)`。`"UI"`、`"ui"`、`" image "`、`"art-spritesheet-slice"` 一律收口成 `unknown`（分类落 `unclassified`），不做任何兼容归一。
+- **严格解析只有一个入口**：`GameCreationAppAssetKind::parse_with_context(value, context)` 是唯一公开解析入口（`FromStr`、serde、所有外部边界都走它），内部严格匹配是私有 `match_canonical()`；先前那批易混名字（`from_str_lossy()`、公开的 `from_str_or_unknown()`）都已删除，认不出 canonical 值只有这一处收口 + 留痕。口径是等值匹配——不 trim、不 lowercase、不查别名、不迁移；`"UI"`、`"ui"`、`" image "`、`"art-spritesheet-slice"` 一律收口成 `unknown`（分类落 `unclassified`）。**接受 unknown 是显式决定**：留痕日志给出原始串与上下文，供回查仍在写 legacy kind 的代码；不写兼容、不做迁移。
+- **登记边界同口径**：外部登记 kind（`commands::register_local_asset`、`import_canvas_asset_at`、`sync_canvas_project_assets_at`、平台导入）统一走 `assets::registration_asset_kind()`——空白入参按「没有信息」落中性 `image`（→「待归类」），非空但认不出的值走严格解析收口成 `Unknown` 并留痕。三条边界不再各写一份 trim/兜底分支。
+- **登记内容的 kind 必须与内容相符**：`normalize_local_project_raster_resource_at` 的源 subtype 只接受图片族成员（`image / scene / character / character-animation / icon / icon-spritesheet / icon-spec / ui-design`），音频、视频、文档、字体、代码等一律按 `image` 登记——`source_subtype` 是公开入参，只排除 `Unknown` 会让一张 PNG 被登记成 `background-music`。派生资源写回 manifest 时不得主动写 `Unknown`：Agent 回执派生物是 markdown 文本，按 `Text => Document` 同口径落 `document`。
+- **切片残留判据只看路径**：`register_existing_platform_art_slices_at` 判定「已有半成品切片登记」时只看 `assets/art-spritesheet-slices/` 前缀，不再附带 `kind == Icon`——历史切片刻写的是非 canonical kind，严格解析后是 `unknown`，再带 kind 判据会漏掉这些登记并静默跳过回填。
+- **sprite 身份不含展示串**：UI 工作流比较 sprite 资源身份时忽略 `metadata.asset_type`（它随 canonical kind 派生），只看真正影响渲染的字段；否则对既有 State 重跑工作流会误报「与已有 State 资源冲突」。
+- **TS 侧判据也只留一份**：`isGameCreationAppUiDesignDocAsset(asset)` 是「`kind == ui-design-doc` 且 `mediaType == application/json`」的唯一定义，资源画布入口、UI 编辑器桥接、资源引用缩略图三处统一调用它。
+- **严格口径的已知代价**：既有项目 manifest 里若存的是 legacy kind（`"UI"`、`"ui-prototype"`、`"art-spritesheet"`、`"game-background"`…），读入后就是 `unknown`，依赖 kind 等值比较的运行门禁会按「缺少该资源」处理。这是「不迁移、不 fallback」的必然结果，由项目决策接受；若将来要迁就存量数据，必须单独立项（一次性迁移或读侧白名单），不得把别名表加回解析路径。
 - **留痕走 `app_log!`**：`shared-contracts` 不再依赖 `tracing`（`kind-observability` feature 删除），改为暴露可注册回调 `set_non_canonical_asset_kind_reporter()`；AGC 壳在 `main()` 里注册成 `app_log!`，日志同时含**原始输入串**与调用上下文，用于回查还有谁在写 legacy kind。TS 侧对应 `parseGameCreationAppAssetKind()` 的 `console.warn`。
 - **分类映射**：`GAME_CREATION_APP_ASSET_CATEGORY_BY_KIND` 改为按 `GameCreationAppAssetKind` 变体穷举（含 `unknown → unclassified`），与 `GameCreationAppAssetKind::ALL` 的对齐由单测 `asset_category_mapping_covers_every_kind` 守住；TS 侧同表按生成 union 穷举。
 - **平台/画板词汇表**：`AGENT_RUNTIME_CANVAS_ASSET_KINDS` 与 `platform_art_asset_manifest_kind()` 仍是「画板词汇 → manifest kind」的唯一映射点（保留），但认不出的原值改为留痕收口；对外 API 的 `EDITOR_IMAGE_EDIT_STATIC_IMAGE_ASSET_KINDS` 白名单保持原样，属 API 兼容面，不代表客户端 kind 归一规则。