图集切片模式改为必须显式声明并补齐决策要求 (#408)

## 背景

切图新增基于连通域的切分后，LLM 仍倾向显式传 `sliceMode=grid`：参数只存在于部分 LLM 可见面、带默认值、没有任何决策规则，生成结果也不回显生效模式。

## 变更

- 平台：`/api/editor/icon-spritesheets/generations` 与 `/api/external/v1/editor/icon-spritesheets/generations` 把 `sliceMode` 改为必填并移除默认值；缺失、空白或未知取值在引用解析、定价与任何 provider / OSS 副作用之前返回 `400`，错误统一带 `field` 与决策要求。
- 契约：`grid` 必须同时提供 `gridX`/`gridY`，`connected-components` 不接受网格尺寸；`sliceCount` 只约束连通域切分，请求与响应的公开上限统一为 `256`；OpenAPI 去掉默认值并补必填与失败语义。
- AGC：MCP 工具说明去掉默认值并补决策要求，桥接层新增可测试的切分声明校验；原生工具 `canvas.asset_generate` 暴露 `sliceMode/gridX/gridY/sliceCount` 并要求图集显式声明；生成结果回显 `sliceMode/gridX/gridY` 与 `slicePaths`；严格图集在本地提交前校验平台回显与请求声明一致。
- 标准美术包：显式声明 `connected-components` 加 `sliceCount=4`，并在四张 canonical 切片用途映射前校验数量，禁止截断或错位。
- 前端与画板：画板 Agent 工具装配与画板提交计划显式声明连通域切分；前端类型要求显式 `sliceMode` 并在本地校验声明自洽。
- 文档与 Skill：主规范、OpenAPI、AGC Skill、外部编辑器 Skill、里程碑与实施计划、共享决策记录同步更新。
- 测试环境：测试构建对提权 Windows 主机上系统临时目录的所有者偏差做一次性所有者初始化重试，临时目录之外的越权所有者继续失败关闭。

## 兼容性影响

省略 `sliceMode` 的旧调用方（含已发布但未更新的 AGC 客户端与第三方外部 API 调用方）会在图集生成上收到 `400`；这是本次"不允许默认值"的预期结果，仓库内自有调用方已全部改为显式声明。

## 验证

- 平台：`slice_mode_must_be_declared_*` 与 OpenAPI 契约测试通过；全量 `cargo test -p api-server` 1043 通过 / 11 失败（`wallet_refund_outbox` 临时文件 `拒绝访问`，已在改动前基线复现，属本机环境）。
- AGC：`slice` 30、`spritesheet` 21、`direct_tools_mcp` 23、`agent_native_tools` 16、`canvas_generation_tests` 83、提示词上限与桥接门禁各 1 条、`cargo check --tests` 全部通过。
- 前端：182 条定向测试与 `typecheck` 通过。
- 门禁：`cargo fmt --check`（两个 workspace）、`check:encoding`、`check:doc-index`、`git diff --check` 通过。
- 未验证：真实 Provider 与浏览器试玩、确定性 e2e 车道；整机全量 AGC 单进程运行在本机受提权 shell 的所有者与时序问题影响，不作为门禁信号。

---------

Co-authored-by: kdletters <61648117+kdletters@users.noreply.github.com>
Reviewed-on: http://192.168.35.82/git/GenarrativeAI/Genarrative/pulls/408

.codex/skills/genarrative-external-editor-api/SKILL.md

@@ -32,7 +32,7 @@ Prefer `scripts/genarrative_external_api.py` for runnable REST calls. It uses on
 - Use stable references such as `objectKey`, project resource ID, or asset ID where each operation permits them. Image edit/redraw is stricter: `sourceReferenceId` accepts only a registered project resource ID or asset ID; upload confirmation alone is not enough. Use `/assets/read-url` only for temporary preview/download access.
 - Preserve both warning channels after completion. A general `warning` can coexist with `sliceWarning`; do not discard either.
 - Do not invent missing derivatives. A source-preserved warning means the main source remains usable but requested post-processing failed. A slice warning means the complete transparent sheet is usable but individual slices are absent.
-- Icon spritesheet generation accepts `sliceMode="connected-components"` (default alpha-connectivity detection) or `sliceMode="grid"`. Grid mode requires `gridX` and `gridY` (1-32); use `sliceCount` only to constrain connected-component output.
+- Icon spritesheet generation requires an explicit `sliceMode` and has no default. Use `sliceMode="grid"` with the `gridX` and `gridY` the requirement actually names (1-32 each) only for equal grid cells or fixed slots; use `sliceMode="connected-components"` for free-form sheets or an open number of subjects, and constrain the count with `sliceCount` instead of inventing grid dimensions. `connected-components` must not carry `gridX`/`gridY`; an omitted, contradictory, or misapplied declaration returns 400 before billing.
 - For successful `style="pixelArt"`, treat completed-result and nested resource/asset dimensions as the final logical-grid PNG dimensions. They may differ from `size`, `imageSize`, the provider image, and `canvasCompletion.placeholder`; do not rescale or reject the artifact to match those inputs.
 - Keep generated artifacts in the canvas and asset library together. Character animation accepts `assetFolderId` and `assetLabel`; its completed result directly returns the final `assetKind="character-animation"` resource and asset with formal sequence fields. Do not create a duplicate first-frame record.
 

.codex/skills/genarrative-external-editor-api/references/api-operations.md

@@ -94,7 +94,7 @@ For image edit/redraw, confirming an upload is not sufficient: create a project
 
 The icon-spritesheet primary `referenceId` is intentionally stricter than ordinary image references: it accepts only a current-owner project resource ID or asset ID whose authoritative `assetKind` is `icon-spec`. It does not accept an `objectKey`, URL, Data URL, or Blob URL.
 
-`sliceMode` controls atlas splitting. Use `"connected-components"` (default) to detect independent opaque regions by alpha connectivity, or `"grid"` with positive `gridX` and `gridY` values (maximum 32 each). `sliceCount` optionally constrains the connected-component result.
+`sliceMode` is required and has no default, so every request must state it. Use `"connected-components"` to detect independent opaque regions by alpha connectivity, or `"grid"` with positive `gridX` and `gridY` values (maximum 32 each) only when the requirement names equal grid cells or fixed slots; the dimensions must come from that requirement. `connected-components` must not carry `gridX`/`gridY`, and `sliceCount` constrains the connected-component result instead of expressing a grid. Omitting `sliceMode`, or contradicting the declared mode with grid dimensions, returns 400 before pricing, enqueueing, or any provider call.
 
 ## Common Values
 

.codex/skills/genarrative-external-editor-api/references/capability-routing.md

@@ -79,9 +79,9 @@ Keep the existing autonomous-build task graph. Do not add a parallel task system
 
 1. `art-director` generates `assets/art-spec.png` with image generation, `kind: "spec"`, then registers it as `assetKind: "icon-spec"`. This image is the authoritative visual spec; `generationInputs.artSpec` is supporting structured context.
 2. `design-foundation` generates `assets/ui-prototype.png` with `kind: "ui-design"`, using the registered art-spec resource ID in `referenceImageSrcs`.
-3. `art-asset-plan` generates transparent `assets/art-spritesheet.png` through icon spritesheet generation, using the same registered art-spec resource ID as `referenceId` plus concrete `iconDescriptions`. For a fixed four-category game contract it may send `sliceMode: "grid"`; for free-form assets use `sliceMode: "connected-components"` (the default).
+3. `art-asset-plan` generates transparent `assets/art-spritesheet.png` through icon spritesheet generation, using the same registered art-spec resource ID as `referenceId` plus concrete `iconDescriptions`. `sliceMode` is required and has no default: send `sliceMode: "grid"` with `gridX`/`gridY` only when the requirement itself fixes the slots or names the column/row count, and otherwise send `sliceMode: "connected-components"` (with `sliceCount` when a subject count must be constrained); never invent a grid to express "kinds of assets", and never send `gridX`/`gridY` with `connected-components`.
 
-For a playable Canvas game, do not stop at generation. Make `code-prototype` depend on `art-asset-plan` and consume the persisted `iconImageSrcs` slices for core players, blocks or targets, scene obstacles, and feedback. When using the fixed four-category contract, require response `sliceMode: "grid"` and exactly four slices before registering the local runtime sheet; both fewer and extra components fail closed. Treat `art-spec.png` as reference-only. A full-sheet `<img>`, CSS background, path-only mention, guessed equal-grid crop, or code-drawn replacement for core entities is not runtime asset use. If slicing produces `sliceWarning`, keep the complete transparent sheet as a valid editor artifact, but fail the playable game asset gate until real slice files or verified atlas coordinates exist; never invent coordinates or replace the icon-spritesheet route with ordinary image generation.
+For a playable Canvas game, do not stop at generation. Make `code-prototype` depend on `art-asset-plan` and consume the persisted `iconImageSrcs` slices for core players, blocks or targets, scene obstacles, and feedback. When the requirement fixes grid slots, require the response `sliceMode` to match the declared `grid` request and exactly `gridX × gridY` slices before registering the local runtime sheet; a connected-components request is instead judged by its own `sliceCount` or by the requirement, and both fewer and extra components fail closed. Treat `art-spec.png` as reference-only. A full-sheet `<img>`, CSS background, path-only mention, guessed equal-grid crop, or code-drawn replacement for core entities is not runtime asset use. If slicing produces `sliceWarning`, keep the complete transparent sheet as a valid editor artifact, but fail the playable game asset gate until real slice files or verified atlas coordinates exist; never invent coordinates or replace the icon-spritesheet route with ordinary image generation.
 
 Never use `assets/ui-prototype.png` as the spritesheet visual-spec reference. UI extraction is outside this canonical DAG.
 

.codex/skills/genarrative-external-editor-api/scripts/genarrative_external_api.py

@@ -617,6 +617,7 @@ class GenarrativeExternalClient:
         self,
         reference_id: str,
         icon_descriptions: list[str],
+        slice_mode: str,
         **fields: Any,
     ) -> Any:
         reference_id = normalize_optional_text(reference_id)
@@ -625,6 +626,20 @@ class GenarrativeExternalClient:
         descriptions = [item.strip() for item in icon_descriptions if item.strip()]
         if not descriptions:
             raise GenarrativeApiError("icon_descriptions must contain at least one non-empty item")
+        slice_mode = normalize_optional_text(slice_mode)
+        if slice_mode not in ("connected-components", "grid"):
+            raise GenarrativeApiError(
+                "slice_mode must be declared explicitly as 'connected-components' or 'grid'; the API has no default"
+            )
+        grid_x = fields.get("gridX")
+        grid_y = fields.get("gridY")
+        if slice_mode == "grid":
+            if grid_x is None or grid_y is None:
+                raise GenarrativeApiError("slice_mode='grid' requires both gridX and gridY")
+        elif grid_x is not None or grid_y is not None:
+            raise GenarrativeApiError(
+                "slice_mode='connected-components' must not carry gridX/gridY"
+            )
         label = fields.get("assetLabel", "图标图集")
         self._apply_canvas_session_fields(fields, label, 1024, 1024)
         fields.setdefault("screenColor", "auto")
@@ -635,6 +650,7 @@ class GenarrativeExternalClient:
                 **fields,
                 "referenceId": reference_id,
                 "iconDescriptions": descriptions,
+                "sliceMode": slice_mode,
             },
             idempotency_key=idempotency_key,
         )
@@ -879,9 +895,9 @@ def _self_test() -> None:
     client.generate_icon_spritesheet(
         "editor-resource-spec",
         ["蛇头向上", "蛇身直线", "转角", "尾部", "四类食物"],
+        "connected-components",
         canvasSession=session,
         assetLabel="贪吃蛇透明图集",
-        sliceMode="connected-components",
         referenceId="must-not-override-explicit-reference",
         iconDescriptions=["不得覆盖显式图标描述"],
     )