evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/zh-CN/game-asset-align/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: game-asset-align
+description: 维护 Three.js、Godot 与 Blender 之间的 3D canonical 资产对齐。凡涉及 Tripo/生成模型入库、朝向/尺度/枢轴修复、视觉与语义核对、跨引擎导入不一致、资产修复状态或持续验收，必须先使用本技能。
+---
+
+# Game Asset Align
+
+## Ownership
+
+本技能拥有场景导出契约、资产对齐与修复生命周期。`godot-3d-game` 与 `threejs-3d-game` 消费当前目标已确认的包；Blender 提供建模源场景，导出器负责生成可核对的快照。
+
+只支持当前插件范围内的 Three.js、Godot 4、Blender。不要新增 Unity 或 Unreal 分支。
+
+## Required workflow
+
+默认使用本地 CLI。先读 [CLI 契约](references/tool-contract.md) 选择启动方式；下文 `evomeme` 是 `npx -y evomeme@latest` 或同版本本地构建的简写。指定 `--workspace`，机器读取时加 `--json`。Stage 需保持前台会话运行，拿到 URL 即交给用户，后续命令使用另一终端。
+
+1. 完整 Blender 场景先保存 `.blend`，调用 `evomeme scene export "<scene.blend>" --id <id>` 自动生成源快照、GLB、相机参考图和场景契约，流程见 [Blender 场景建模与导出](references/blender-scene-pipeline.md)。已有独立 GLB/GLTF 使用 `evomeme asset import "<model.glb>" --id <id>` 入库。
+2. **Blender 建模或修改后，必须先打开 Stage 展板，用户确认当前版本后才允许进入下一步引擎导入。** 调用 `evomeme asset review <id> --workspace "<workspace>" --json` 检查格式与依赖，再调用 `evomeme stage --asset <id> --workspace "<workspace>" --target <target> --json`。target 为 `three_js` 或 `godot`。查看相同机位的 Blender 与目标引擎原生画面，核对空间、结构、材质与灯光。
+3. 原点/落地修复使用 `evomeme asset repair <id>`；其他几何修改在 Blender 完成后重新导出，见 [修复策略](references/repair-policy.md)。修复会使旧配方失效，必须回展板重新验收。
+4. 用户在 Stage 点击 **“确认当前版本，允许导入”** 后，才能调用 export/sync/handoff。工具返回已启动、模型加载成功、格式检查通过或 `alignment.ready=true` 都不能代替确认。不得代用户点击、伪造查看/确认记录、用 `verified_by=spec/user_board` 绕过门禁或手动复制资产到引擎。等待确认期间可继续不依赖导入的工作。
+5. 引擎中只允许一个对齐根节点；禁止在玩法、动画或实体脚本里再补旋转、缩放或位置。
+
+`asset.json` v1 可以读取，但不能直接进入引擎。重新保存后升级为 v2 修复状态。
+
+export/sync 均强制检查 Stage 当前版本确认；Godot 同步还要求 Godot 原生预览对应的确认，不能用 Three.js 画面代替。修改模型、契约、纹理、Godot profile、材质、灯光或显示实现后必须重新打开 Stage 查看并确认；旧交接包保留原版本。Godot 配置与预览流程见 [Godot 基础视觉对齐](../godot-3d-game/references/appearance-alignment.md)。
+
+## Routing references
+
+- 当前单场景对比与历史兼容接口说明：读 [lightweight-review.md](references/lightweight-review.md)。
+- 图片参考建模、完整 Blender 场景导出与程序材质烘焙：读 [blender-scene-pipeline.md](references/blender-scene-pipeline.md)。
+- 需要理解 v2 字段、状态推导或版本失效：读 [alignment-contract.md](references/alignment-contract.md)。
+- 需要决定是改 metadata、wrapper 还是 Blender 几何：读 [repair-policy.md](references/repair-policy.md)。
+- 需要判断“看起来一致”或保存验收证据：读 [visual-review.md](references/visual-review.md)。
+- 需要比较 Three.js、Godot、Blender 能做什么：读 [engine-capabilities.md](references/engine-capabilities.md)。
+- 需要创建、替换或迁移 canonical 包：读 [canonical-package.md](references/canonical-package.md)。
+- 需要选择 CLI 命令、参数或处理门禁错误：读 [tool-contract.md](references/tool-contract.md)。
+
+## Completion gates
+
+- `asset.json` 是 `evomeme.canonical_asset.v2`。
+- 当前目标引擎已在 Stage 展示，用户确认记录为当前 revision；只有原任务用户实际确认才允许继续导入。
+- `alignment.overall_status` 为 `aligned`，`alignment.ready` 为 `true`。
+- recipe 绑定当前 `model.glb` SHA-256 和当前 intent revision，并包含 translation、quaternion、scale。
+- spatial、structural、semantic、render 四项均为 `aligned` 或有明确理由的 `waived`。
+- 当前单视窗不得把显示已载入说成视觉契约已全部通过。若任务另行要求导出，继续验证源、意图、配方和唯一 wrapper，不在玩法代码中补偿 Transform。
+- 视觉结论来自目标引擎截图或明确标注的展板近似，不把 Blender/Three.js 截图冒充 Godot 结果。

package/dist/skills/zh-CN/game-asset-align/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Game Asset Align"
+  short_description: "维护生成模型在 Three.js、Godot 与 Blender 间的可审计对齐状态"
+  default_prompt: "请使用 $game-asset-align 检查这个 3D 资产包，修复跨引擎朝向、尺度与视觉语义偏差，并给出可持续维护的验收状态。"
+
+policy:
+  allow_implicit_invocation: true
+

package/dist/skills/zh-CN/game-asset-align/references/alignment-contract.md

@@ -0,0 +1,61 @@
+# Alignment contract v2
+
+## Source of truth
+
+`asset.json` keeps the v1 flat fields for UI compatibility, but `alignment` is authoritative for engine readiness.
+
+```json
+{
+  "schema": "evomeme.canonical_asset.v2",
+  "forward_axis": "+z",
+  "up_axis": "+y",
+  "pivot": "ground_center",
+  "scale_hint_metres": 1.8,
+  "alignment": {
+    "schema": "evomeme.asset_alignment.v1",
+    "source": { "model_file": "model.glb", "sha256": "…", "bytes": 123 },
+    "recipe": {
+      "source_revision": "…",
+      "intent_revision": "…",
+      "translation_metres": [0, 0, 0],
+      "rotation_quaternion_xyzw": [0, 1, 0, 0],
+      "scale_xyz": [1, 1, 1],
+      "algorithm_version": "evomeme.stage.v2"
+    },
+    "conditions": {
+      "spatial": { "status": "aligned" },
+      "structural": { "status": "aligned" },
+      "semantic": { "status": "aligned" },
+      "render": { "status": "aligned" }
+    },
+    "overall_status": "aligned",
+    "ready": true,
+    "revisions": {
+      "source": "…",
+      "intent": "…",
+      "recipe": "…",
+      "alignment_key": "…"
+    }
+  }
+}
+```
+
+## Four conditions
+
+- `spatial`: position, pivot, grounding, facing, up-axis and size are correct.
+- `structural`: hierarchy, mesh parts, skeleton, sockets and animation bindings remain usable.
+- `semantic`: the object identity and functional details match the request.
+- `render`: materials, visibility, normals, texture assignment and target-engine presentation are acceptable.
+
+Allowed states are `aligned`, `needs_review`, `misaligned`, `stale`, and `waived`. A required aspect is ready only when `aligned` or explicitly `waived` with evidence.
+
+## Revision invariant
+
+An accepted recipe must reference the current source SHA-256 and current intent revision. `alignment_key` binds source + intent + recipe. A model replacement, Blender geometry edit, or intent field change invalidates the prior key. Never copy an old key into a new package.
+
+`ready` and `overall_status` are derived values. Export/sync recomputes the invariant and compares the current model bytes; editing `ready: true` by hand cannot bypass the gate.
+
+## v1 migration
+
+v1 flat fields are parsed for inspection, then represented as `needs_review` with no accepted recipe. Open the Stage, inspect the actual model, and save to produce v2. Do not bulk-mark legacy assets ready without visual evidence.
+

package/dist/skills/zh-CN/game-asset-align/references/blender-scene-pipeline.md

@@ -0,0 +1,35 @@
+# Blender 源场景 → Stage → 引擎
+
+## 从图片开始
+
+先读取图片，明确主体、比例、材质、主光和参考机位。单张图片未展示的背面与遮挡区域按合理假设建模，并在交付时说明。优先通过当前可用的 Blender MCP 完成建模；本插件提供导出和验收流程，不捆绑外部 Blender MCP 安装或图像转三维模型服务。没有 Blender MCP 时，若有本机 Blender，可用 Python 建模；只在缺失路径或不可执行时报告具体阻塞。
+
+先搭建空间和相机，输出低成本参考供迭代，再细化模型、材质和灯光。保存 `.blend` 后进行以下导出。源场景采用米制、unit scale=1，保留场景原点；导出器完成 Blender Z-up 到 glTF Y-up 的转换。不要再旋转整个世界。支持 Cycles/Eevee、透视相机；相机非单位缩放与 lens shift 会报错，需先处理。外链库及未能打包的序列/缓存应在 Blender 本地化后再导出。
+
+## 统一导出入口
+
+```sh
+npx -y evomeme@latest scene export "<scene.blend>" --id courtyard --workspace "<workspace>" --camera-names Reference,MaterialDetail --quality preview --width 960 --bake-materials --texture-size 1024 --godot-project-dir "<godot-project>" --json
+```
+
+启动版本与路径约定见 [CLI 契约](tool-contract.md)，结果在 JSON 的 `data` 中。相机名与 Godot 工程路径可省略；没有相机时自动建立参考机位，并补全 overview。最多 6 个指定透视相机。`--width` 为 320–1920；`--texture-size` 为 256/512/1024/2048。未指定目标工程时 Godot 默认 Compatibility，可用 `--godot-renderer` 指定 mobile/forward_plus/gl_compatibility；预览和同步工程必须一致。
+
+导出器在隔离 Blender 进程中读取已保存源文件，禁用自动脚本执行，保存自包含源快照，生成 GLB、各机位 Blender 原生参考图、源特征清单及两个目标 profile。原文件不改动；活动 Blender 中未保存的更改不会进入导出。失败不会替换当前包。更新同一场景用 `--replace-existing`；旧包保留在返回的 `data.backup_dir`，新版本重新确认。
+
+preview 使用快速采样；final 保留源场景采样设置。自由视角原生预览仍为快速模式并关闭景深，不能用它证明最终离线渲染完全一致。
+
+## 烘焙与源契约
+
+`--bake-materials` 为可选项，只处理直接连接 Principled BSDF 的受支持程序表面；按对象生成基础色、粗糙度、金属度、切线法线贴图，必要时建立 UV。源 `.blend` 保留原节点；导出模型使用烘焙版本。复杂闭包、混合 shader、体积和间接光不会被此通道烘焙自动转换。保留报告中的跳过原因，不能把部分对象烘焙说成整份材质完成。
+
+`scene.contract.json.source_features` 使用 evomeme.source_scene_features.v1，记录节点 ID、对象/材质关联、程序节点、未转换节点、已烘焙通道/对象、体积、世界环境、源渲染设置。ID 优先复用 evomeme_node_id；未设置时由资产和对象名派生，需要跨重命名稳定 ID 时应在源场景设置该属性。
+
+标准 PBR 与灯光事实共用一份源契约。`runtime/three.profile.json` 和 `runtime/godot.profile.json` 保存引擎覆盖；重新导出保留匹配 schema 的既有覆盖，未覆盖灯光从新源事实派生。修改 profile 后更新 contract.files 中的字节数与 SHA-256。
+
+烘焙材质为每个对象建立独立运行时材质；其精确名称记录在 source_features.materials[].runtime_materials。设置引擎材质覆盖时使用该 material_name。未烘焙版本使用 GLB 内的实际材质名。
+
+## 查看与交付
+
+运行 `evomeme stage --asset courtyard --workspace "<workspace>" --target <target> --json`（target 为 three_js/godot），保持前台会话运行并将 `data.url` 交给用户。展板逐项显示已映射、已烘焙、采用近似、尚未实现、待核对，提供相关机位和“记录修复要求”。修复要求会写入反馈记录，需要代理读取并继续修改；按钮不会自行完成修复。
+
+用户查看并确认目标引擎当前版本后，在另一终端执行 `evomeme asset sync courtyard --workspace "<workspace>" --target <target> --project "<project>" --json`。Three.js 游戏使用生成的 loadReviewedScene 和 runtime.render，与 Stage 共用显示实现；Godot 使用 load_scene 与同一原生显示适配器。完成导入后在实际工程复验。确认记录中的 visual_equivalence=not_evaluated 表示没有计算跨渲染器逐像素等价，不抹去已经记录的近似或缺失项。

package/dist/skills/zh-CN/game-asset-align/references/canonical-package.md

@@ -0,0 +1,26 @@
+# Canonical package
+
+## Required layout
+
+```text
+assets/canonical/<asset_id>/
+  model.glb
+  asset.json
+  preview/
+```
+
+`asset_id` is normalized and stable. `model_file` remains package-relative. Do not reference files outside the package.
+
+An optional `scene.contract.json` may define camera, world-coordinate and display-profile supplements. Its file manifest uses relative paths, byte sizes and SHA-256 hashes. Export/sync verifies the whole manifest and rejects traversal, missing files, stale hashes and coordinate conflicts.
+
+For a complete Blender source scene, `evomeme scene export "<scene.blend>" --id <id>` creates this contract, `source/scene.blend`, per-camera references and both engine profiles automatically. See [Blender scene pipeline](blender-scene-pipeline.md). `source_features` makes unsupported/approximate effects visible in Stage; a loaded GLB alone does not demonstrate material or lighting equivalence.
+
+## World-coordinate scenes
+
+For a complete meter-scale map already exported as Y-up, use `up_axis=+y`, `forward_axis=-z`, `pivot=origin`, `scale_hint_metres=null` and zero offsets unless evidence says otherwise. Do not center a whole world or normalize it by height.
+
+## Replacement and history
+
+`replace_existing=true` may reuse the asset ID and descriptive metadata, but new model bytes create a new source revision. Previous recipes and evidence become stale. Keep repair reports/backups inside the package repair area; never treat a backup as the active `model.glb`.
+
+The bounded alignment history explains creation, migration, acceptance and invalidation. It is an audit aid, not a substitute for current revision checks.

package/dist/skills/zh-CN/game-asset-align/references/engine-capabilities.md

@@ -0,0 +1,14 @@
+# Engine capabilities
+
+| Component | Owns | Must not own |
+|---|---|---|
+| Stage | Three.js live preview, native Godot/Blender preview, bounds/TRS, explicit user confirmation before import | substituting Three.js frames for Godot, agent acceptance on behalf of the user |
+| Blender | topology, normals, origin baking, mesh cleanup, GLB re-export | final engine readiness, hidden per-engine orientation |
+| Godot 4 | GLB import, one runtime wrapper, gameplay integration, target render/physics QA | guessing authored axes, accumulating compensation transforms |
+| Three.js game | one runtime wrapper, web presentation and gameplay QA | a second canonical schema or per-entity hard rotations |
+
+Tripo and other generators are sources, not alignment authorities. Preserve their task/model/version metadata in provenance, but compute readiness from the emitted file and current user intent.
+
+Use GLB as the canonical mesh payload. Blender source files may be retained as provenance or repair artifacts, but engines consume the package, not an arbitrary `.blend` working file.
+
+Unity and Unreal are intentionally outside this plugin plan. Do not add placeholder adapters that appear supported but bypass validation.

package/dist/skills/zh-CN/game-asset-align/references/lightweight-review.md

@@ -0,0 +1,34 @@
+# Stage 展板确认与引擎导入
+
+Blender 建模或修改后，必须打开 Stage 展板查看当前版本，由用户点击“确认当前版本，允许导入”，之后才能进行下一步导入。仅启动展板、格式检查通过、保存技术对齐状态或 ready=true 均不能放行。
+
+命令启动方式见 [CLI 契约](tool-contract.md)。Stage 以独立前台会话运行，`--json` 启动结果中的 `data.url` 可立即交给用户；验收期间保持会话存活。`asset review` 退出 0 只表示检查完成，还需读取 `data.technical_ok` 和 `data.confirmation.status`。
+
+## 顺序
+
+1. 完整 Blender 场景使用 `evomeme scene export "<scene.blend>" --id <id>` 生成 canonical 包、源快照、契约与原生参考图；已有 GLB 可单独入库。
+2. `evomeme asset review <id> --workspace "<workspace>" --json` 检查模型格式与文件摘要。
+3. `evomeme stage --asset <id> --workspace "<workspace>" --target <target> --json` 打开单场景视窗。target 为 three_js 或 godot。
+4. 以同机位、同画幅对比 Blender 与目标引擎原生渲染，检查空间、结构、材质和灯光。Godot 使用临时原生预览工程，不提前写最终游戏工程。
+   查看“效果转换与待核对项”的映射、烘焙、近似和缺失状态，可跳转相关机位或记录修复要求。状态来自源特征与适配器能力，不是图像相似度评分。
+5. 用户在页面确认。工具和代理不得代替用户点击，也不得直接构造确认文件。
+6. 执行 `evomeme asset sync <id> --target <target> --project "<project>" --workspace "<workspace>" --json`。Three.js 确认不能替代 Godot 确认；导出同样需要当前 Stage 确认。
+
+需要修改时回 Blender 或更新引擎 profile，然后重新载入、查看和确认。页面保留单场景范围，不加入资产列表、部件编辑或玩法。
+
+## 环境
+
+Blender 通过 EVOMEME_BLENDER / BLENDER_PATH 配置；Godot 通过 EVOMEME_GODOT / GODOT_PATH 或 PATH 上的 godot 配置。原生预览等待时不把旧图冒充当前视角，失败时不能确认当前画面。
+
+## 记录与失效
+
+.review/stage-view.json 记录实际展板机位、目标引擎和版本。Godot 查看还绑定原生渲染回执及 profile key。
+.review/confirmation.json 记录用户确认、当前资源/显示实现摘要、完整 TRS、机位、截图摘要和技术报告。
+
+模型、asset.json、场景契约、纹理、Godot profile、材质/灯光配置或显示模块变化会让确认过期。export/sync 在写目标前检查当前确认及对齐配方；设置 verified_by 或直接改 ready 不能绕过。
+
+## 交接与范围
+
+浏览器 handoff 只复现已确认的 Three.js 画面；Godot 用 `evomeme asset sync <id> --target godot --project "<project>"` 输出原生加载器和显示适配器，不把 Three.js 交接图当作 Godot 验收。
+
+Godot 基础流程保留 GLB PBR，重建灯光、环境、曝光与相机，支持材料参数校准。面光使用明确标注的近似；Three.js 专用烘焙着色器/LUT 不会在 Godot 自动执行。用户确认资产显示后，游戏集成与玩法仍需目标引擎复验。

package/dist/skills/zh-CN/game-asset-align/references/repair-policy.md

@@ -0,0 +1,30 @@
+# Repair policy
+
+Choose the shallowest layer that fixes the actual defect while preserving one canonical result.
+
+## Metadata repair
+
+Use the Stage or `evomeme asset align <id>` when geometry is sound but authored axes, pivot intent, scale target, semantic type or review evidence are wrong. Save a complete wrapper TRS. Do not bake a rotation into gameplay code.
+
+## Wrapper repair
+
+Use the canonical recipe for non-destructive translation, quaternion rotation and scale. The wrapper must be applied exactly once. It is appropriate for grounding, recentering, authored-forward conversion and size normalization.
+
+If `pivot=origin` and `scale_hint_metres=null`, a deterministic identity translation/unit scale recipe is possible. Bounds-dependent pivots or height normalization require a measured recipe from the board or another adapter.
+
+## Blender geometry repair
+
+Use `evomeme asset repair <id> --ground true` for the supported origin/grounding repair. It backs up the prior model and writes into the same canonical package. It is not a general topology or normals repair command. Edit detached/duplicate parts, normals, topology, or other export defects in Blender, then re-export. See the [CLI contract](tool-contract.md) for launcher, workspace, and JSON conventions.
+
+Any Blender result changes the source revision and invalidates all prior review states. Reopen the Stage and accept a new recipe before export or sync.
+
+## Never repair here
+
+- player/controller yaw offsets;
+- AnimationTree or animation-track compensations;
+- per-scene scale overrides;
+- a second Godot/Three wrapper;
+- a material tweak claimed as canonical without updating review evidence.
+
+These hide drift and cannot be maintained when the asset is regenerated.
+

package/dist/skills/zh-CN/game-asset-align/references/tool-contract.md

@@ -0,0 +1,69 @@
+# 本地资产 CLI 契约
+
+## 启动与结果
+
+本地资产包、Blender 源场景导出、Stage 和引擎同步默认使用 CLI。以下用 `evomeme` 简写启动命令；执行时替换为 `npx -y evomeme@latest`，不假设安装 IDE 插件后已有全局命令。已有可用本地构建时，也可用 `node "<plugin_client>/dist/index.js"`。先用同一入口执行 `asset --help` 确认版本支持；一次验收与同步使用同一版本，避免显示实现变化使确认失效。
+
+所有命令可加 `--workspace "<工作区>" --json`。工作区默认当前目录；源文件、`--input`、`--project` 等相对路径均相对**命令执行目录**，不是 `--workspace`。跨目录操作优先使用绝对路径。
+
+- JSON 成功：`{"ok":true,"data":...}`；失败：`{"ok":false,"error":{"code":"...","message":"..."}}`。
+- 退出码：`0` 操作完成，`2` 参数错误（`INVALID_ARGUMENT`），`1` 业务或文件错误（`OPERATION_FAILED`）。
+- `asset review` 退出 `0` 仅表示检查完成；继续读取 `data.technical_ok` 和 `data.confirmation.status`（`unconfirmed` / `confirmed` / `stale`），不能据此直接导入。
+- Stage 前台常驻。用可保持运行的终端/会话启动，读到启动结果的 `data.url` 即交给用户；不要等待进程退出，也不要在用户验收期间终止会话。后续命令使用另一终端，完成后 Ctrl+C 停止服务。无后台 `start/status/stop` 接口。
+
+## 本地命令
+
+这 12 项资产/Stage 能力已移除 MCP 实现和旧别名，只通过 CLI 调用原业务层。若版本缺少 CLI，使用包含新命令的版本或已有本地构建；不可回退到 MCP，也没有启用兼容入口的开关。门禁错误必须修复或重新验收。
+
+| CLI（省略公共参数） | 用途 |
+| --- | --- |
+| `asset import "<model.glb>" --id <id>` | GLB/GLTF 入库 |
+| `asset list` | 列出包 |
+| `asset show <id>` | 读取包 |
+| `asset align <id> --input "<alignment.json>"` | 技术对齐 |
+| `scene export "<scene.blend>" --id <id>` | Blender 源场景导出 |
+| `stage --asset <id> --target <target>` （three_js / godot） | Stage 验收 |
+| `asset review <id>` | 技术检查与确认状态 |
+| `asset repair <id> --ground true` | 原点/落地修复 |
+| `asset export <id>` | 校验并返回包目录 |
+| `asset sync <id> --target three_js --project "<project>"` | Three.js 同步 |
+| `asset sync <id> --target godot --project "<project>"` | Godot 同步 |
+| `asset handoff <id>` | Three.js 交接包 |
+
+`import` 接受 GLB/GLTF，新包通常为 `needs_review`；已有 ID 仅在明确替换时加 `--replace-existing`。`show` 读取完整包信息，`list` 可检查 `alignment_status` / `alignment_ready`。Blender 导出参数、烘焙与备份见 [blender-scene-pipeline.md](blender-scene-pipeline.md)。
+
+## 技术对齐
+
+`evomeme asset align <id> --input "<alignment.json>" --workspace "<工作区>" --json` 只写技术对齐，不能替代 Stage 用户确认。文件使用 UTF-8 JSON（可带 BOM），只放对齐字段，不放 `workspace_dir` 或 `asset_id`；显式 CLI 参数覆盖文件中的同名字段。例如：
+
+```json
+{
+  "forward_axis": "-z",
+  "up_axis": "+y",
+  "pivot": "origin",
+  "scale_hint_metres": null,
+  "alignment_recipe": {
+    "translation_metres": [0, 0, 0],
+    "rotation_quaternion_xyzw": [0, 0, 0, 1],
+    "scale_xyz": [1, 1, 1],
+    "algorithm_version": "adapter-name.v1"
+  },
+  "alignment_conditions": {
+    "spatial": { "status": "aligned", "evidence": "measured against reference" }
+  }
+}
+```
+
+示例数值与证据应替换为实际测量。配方若提供，必须含完整位置、非零四元数和正尺度；`algorithm_version` 可省略。四类条件为 `spatial`、`structural`、`semantic`、`render`，状态为 `aligned`、`needs_review`、`misaligned`、`stale`、`waived`。依赖边界的 pivot/尺度缺少完整配方时仍不可导入，应通过 Stage 测量，不能编造平移或尺度。
+
+简单意图也可用 `--forward-axis -z --up-axis +y --pivot origin --scale-hint-metres null`；另支持 `--type`、`--verified-by`、`--notes` 及 `--yaw-offset-degrees` / `--pitch-offset-degrees` / `--roll-offset-degrees`。`verified_by` 默认 `agent_vision`。命令语法见 `asset --help`，JSON 形状见 `asset align --help`。
+
+## 修复与交付
+
+- `asset repair` 使用本机 Blender 做支持的原点/落地修复，改变源并使旧对齐失效；通用几何编辑仍需在 Blender 修改后重新导出。
+- `asset export` 校验源字节、ready 与当前 Stage 确认，返回包目录，不生成压缩包。
+- Three.js 同步写入 `public/assets/canonical/<id>/`，生成 `src/evomeme-stage/<id>/canonical_loader.js`；用 Three.js 0.170.0、`loadReviewedScene` 与 `runtime.render` 保留验收时的显示管线。
+- Godot 同步要求已有 `project.godot`、匹配的渲染器及当前 Godot 原生 Stage 确认，写入 `assets/canonical/<id>/` 并生成加载器和显示适配器。场景用 `load_scene`，道具用 `load_package`。
+- 浏览器 `asset handoff` 仅支持已确认的 Three.js 版本；Godot 使用 `asset sync <id> --target godot --project "<project>"`。
+
+Blender 建模/修改必须经过目标引擎 Stage 查看与用户确认，代理不得代点或伪造记录。门禁失败时读取 pending/stale 原因，修复、重新查看确认后再同步；不直接编辑确认 JSON。

package/dist/skills/zh-CN/game-asset-align/references/visual-review.md

@@ -0,0 +1,26 @@
+# Visual review
+
+## Review sequence
+
+1. Load the exact current `model.glb`; confirm the displayed source revision.
+2. Compare against the user request or versioned reference, not memory.
+3. Inspect front/back/side/top and a gameplay camera view.
+4. Check spatial, structural, semantic and render conditions separately.
+5. Save the measured wrapper TRS and concise evidence.
+6. Verify again in the target engine after sync.
+
+## Practical checks
+
+- Spatial: feet/wheels/base touch the expected plane; forward direction is unambiguous; height and world scale are plausible; maps retain their intended origin.
+- Structural: named parts exist, transforms are not unexpectedly nested, skeleton and sockets remain attached, animations do not jump on frame zero.
+- Semantic: silhouette, part count, handedness, openings, controls, weapon muzzle, seats, doors and other requested affordances are correct.
+- Render: normals face outward, textures resolve, alpha/culling are correct, material response is credible and no parts disappear under the target camera/light setup.
+
+## Evidence quality
+
+Prefer a user-approved board view or target-engine screenshot. Agent visual review is acceptable when the comparison and limitations are recorded. Heuristics alone do not close structural, semantic or render review.
+
+Three.js Stage is a neutral inspection surface, not proof of Godot render parity. Blender Cycles, Three.js and Godot use different shading pipelines. Describe approximations explicitly; do not promise pixel identity unless a target-engine capture was compared.
+
+For `scene.contract.json`, keep reference camera, aspect ratio, near/far and framing fixed during comparison. Do not let auto-frame controls overwrite a contract camera.
+

package/dist/skills/zh-CN/game-asset-batch-generator/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: game-asset-batch-generator
+description: 使用 evomeme_generate_asset_batch 按俯视、等距斜视、侧视或自定义视角，一次生成统一风格的静态游戏素材整图，按需自动去底色并始终拆成独立 PNG。适用于制作场景搭建所需的建筑、植被、道具、墙面、地砖或平台素材包。解释工具步骤、实际产物、视角、色键和拆图术语，以及图片如何接入游戏；不用于已有整图的纯拆分、单张背景、动画或需要保证无缝的瓦片。
+---
+
+# 批量游戏素材生成
+
+使用本技能生成一组风格和视角一致、用于拼装场景的静态二维素材。先确定主题、观察角度、参考风格与背景模式，再调用 `evomeme_generate_asset_batch`，检查拆出的图片后交付。
+
+## 工具具体做什么
+
+MCP 与画布的批量素材功能共用 `generate_asset_batch` 任务及 `executeAssetBatchGeneration` 函数，由共享 task 层串联已有 image 函数。没有 MCP 调用 MCP，也没有通过画布功能入口串联其他画布入口。编排放在共享 task 层即可，不为移植工具另建流程或更改 image 内置提示词。
+
+一次调用依次执行：
+
+1. **一次 AI 生图**：根据主题、所选视角、可选参考图及原有素材类别要求，生成一张包含多个独立物件的整图。不是逐个物件分别发送生图请求，也不是每张参考图各生成一张。
+2. **下载整图**：保存到工作区 `assets/`，保留原始生成结果。
+3. **按背景模式处理**：默认生成纯色背景，再以固定强度 80 色键去底，保存透明 PNG；`transparent_background=true` 时只允许 Max，直接请求透明背景，跳过色键。
+4. **始终自动拆图**：按检测出的独立前景区域裁切为多个 PNG。不缩放主体、不补齐为相同尺寸。此工具没有关闭拆图的参数。
+
+成功拆出 N 个主体时，最终得到 **N 张独立 PNG（N 至少为 2）**。另外保留 1 张原始整图；经过色键时再保留 1 张去底色整图。因此本次正常成功新增的图片为 N+1 张或 N+2 张，不计原有参考素材。整图格式以其 `mime_type` 为准；去底色和拆图结果为 PNG。
+
+数量取决于生成内容和前景检测，不能保证请求几个物件就精确得到几个文件。输出是图片资源，不包含完整关卡、对象坐标、碰撞体、引擎预制体、图集坐标配置、动画帧序列或无缝拼接保证。
+
+## 什么时候使用
+
+| 需求 | 选择 |
+| --- | --- |
+| 为同一主题制作建筑、植被、道具、墙面等场景搭建素材包 | 使用本工具，统一视角和美术参考。 |
+| 为横版关卡准备平台、楼梯、坡面和装饰 | 使用 `side-view`，生成后检查物件是否保持纯侧面。 |
+| 只要一个物件或一张完整背景 | 使用 [通用图片生成](../game-asset-image-generator/SKILL.md)，避免强制拆图。 |
+| 要求可反复拼接的无缝瓦片或两种地形的过渡图集 | 使用 [瓦片地图技能](../game-tile-generator/SKILL.md)。这里生成的“地砖”不保证无缝。 |
+| 要循环卷轴背景、中景、前景 | 使用 [卷轴地图技能](../game-scroll-generator/SKILL.md)。 |
+| 要按钮、面板等 UI 皮肤及其使用说明 | 使用 [UI 组件技能](../game-ui-generator/SKILL.md)。 |
+| 已有一张素材整图，仅需裁出物件 | 使用已有图片处理能力；本工具会重新生图，不适合纯拆分。 |
+
+## 术语与视角选择
+
+- **素材整图／素材表（asset sheet）**：一张同时放置多个静态物件的图片，物件之间留空以便裁切。它不是已经排好的游戏场景，也不是按时间顺序播放的动画表。
+- **前景主体与自动拆图**：前景指应保留的物件区域。拆图通过像素、透明度和连通区域检测分离主体，不做“这张是树、那张是宝箱”的语义识别。连通区域是像素相邻构成的一块区域；物件粘连可能合并，悬空装饰可能误拆。自动拆图不是按固定行列均分，也不是图层拆解。
+- **色键去底（color key）**：把指定背景色及相近颜色变透明。当前使用 Oklab 感知颜色距离，即按更接近人眼感受的颜色差异判断相似度，固定强度 80，全图处理并柔化边缘。它可能同时去掉物件内的相近颜色，不等同于理解物体轮廓的智能抠图。
+- **原生透明／alpha 通道**：模型直接生成带透明区域的图像；alpha 记录像素的不透明程度，透明处应露出背后的场景，不应是画上去的白色或棋盘格。玻璃、发光和软阴影更适合先尝试 Max 原生透明，仍需检查结果。
+- **去溢色（despill）**：清理主体边缘残留的底色偏色。本流程固定关闭，因此检查洋红边缘、光晕和半透明细节；本工具不能调整该选项。
+- **同尺寸补齐（padding）**：在裁出的物件周围增加透明像素，让所有图片宽高一致。本流程固定 `pad_to_same_size=false`，不同图片通常大小不同，主体不会被缩放到统一大小。
+- **锚点／对齐基准（anchor / pivot）**：运行时用哪个位置放置图片，例如树根、建筑接地中心。拆图内部使用 `anchor=center`，但关闭补齐时不会替你建立游戏里的接地点、枢轴或碰撞范围；必须检查实际图片后设置。
+
+`asset_type` 表示**观察视角**，不是物件类别或文件格式：
+
+| 值 | 视觉含义、适用场景与现有生成内容 |
+| --- | --- |
+| `top-down`（默认） | 顶部俯视，从上向下观察，适合俯视地图的屋顶、地面、植被与摆件。内置类别包括地砖、墙面、栅栏、植被、建筑、道具及氛围装饰物。 |
+| `isometric` | 等距风格的正交斜视，通常同时看见顶部和侧面，强调远近物体保持一致比例，适合斜视场景搭建。现有预设文案为“正交斜45度俯视角”；这是生图视角约束，不是可验证的三维相机角度或精确网格。类别与俯视预设相同。 |
+| `side-view` | 从侧面观察，适合横版场景。除了建筑、植被等类别，还要求悬浮平台、侧面墙、上下楼梯和上下坡。不是角色朝向图，也不产生移动动画。 |
+| `custom` | 用 `custom_asset_type` 描述自定义观察方式，例如“正面正交视角，建筑外立面”。仍附加通用素材类别；不是替换类别清单或精确物件数量的接口。 |
+
+参考图用于风格、颜色、材质及设计方向，不能覆盖所选视角和独立排列要求。所有模式仍使用原有内置类别清单；用户 `prompt` 补充主题和内容要求，不保证只生成指定子集。
+
+## 参数与调用
+
+| 参数 | 实际含义 |
+| --- | --- |
+| `prompt` | 必填、非空。描述主题、画风、配色、材质、期望内容和比例关系。 |
+| `asset_type` | 可选，默认 `top-down`，其余见上表。 |
+| `custom_asset_type` | `custom` 时必填非空视角描述；其他模式不使用。 |
+| `model` | 默认 `asset-pro`，也可选 `asset-max`、`asset-lite`；本流程原生透明仅 Max。 |
+| `size` | 整张素材表的预设尺寸，默认 `1664x2496`，不是每件素材尺寸。须符合模型限制；Lite 不支持 `1024x1024`。 |
+| `reference_ids` | 工作区参考图 ID 数组，默认 `[]`。本流程最多 14 张，Pro 最多 10 张。 |
+| `background_color` | 默认 `#ff00ff`，支持 `#RGB` 或 `#RRGGBB`。作为纯色底和色键色，避开主体颜色；原生透明时不作为底色。 |
+| `transparent_background` | 默认 `false`，生成纯色底再自动色键；`true` 请求 Max 原生透明，仍会自动拆图。 |
+| `workspace_dir` | 工作区根目录绝对路径，建议显式传入；省略时使用 MCP 当前目录。 |
+
+没有 `count`、`components`、`rows`、`columns`、`auto_split`、`pad_to_same_size` 或色键强度输入参数；不要编造或传入这些字段。固定拆图行为通过返回值说明。
+
+参考图先放到所选工作区 `assets/`，确认真实可读，避免覆盖已有文件；外部可访问 URL 需先下载成工作区文件，再传 `assets/style.png` 这样的 ID。参数不接受 URL、Base64 或原附件绝对路径。已有 `asset_id` 可以复用。
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "prompt": "温暖的手绘中世纪村庄素材包，木材与浅色石砖，赭黄和绿色配色，统一左上方光照。建筑、树木、栅栏、木箱与路边装饰比例协调，所有物件完整且彼此留宽空隙，轮廓清晰，不画连续地面或完整场景，主体避免洋红色。",
+  "asset_type": "isometric",
+  "model": "asset-pro",
+  "size": "1664x2496",
+  "reference_ids": [],
+  "background_color": "#ff00ff",
+  "transparent_background": false
+}
+```
+
+使用自定义视角和原生透明的示例：
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "prompt": "童话小镇场景搭建素材，统一柔和配色与平涂风格，建筑外立面、花盆、路灯及装饰物完整独立摆放，保留细小轮廓，不生成文字或完整场景。",
+  "asset_type": "custom",
+  "custom_asset_type": "正面正交视角，不俯视，不展示侧面透视",
+  "model": "asset-max",
+  "transparent_background": true
+}
+```
+
+## 返回什么与如何使用
+
+MCP 返回文本元数据，数组/对象用 JSON 文本表示，不附图片字节或 Base64：
+
+- `images` 是最终拆出的 PNG 列表，包含 `id` / `asset_id`、`name`、`kind`、`url`、`operation_id`、`local_path`、`mime_type`。顶层 `asset_id` / `local_path` 对应第一张，不代表整个素材包。`url=/files/...` 是画布本地服务路径，不是公网素材地址。
+- `generated` 指原始生成整图，带远端 `job_id` 和 `tos_url`；`color_key` 在经过色键时指去底色整图，原生透明时可省略。查看整图时优先选 `color_key`，没有时选 `generated`。
+- `asset_type`、适用的 `custom_asset_type`、背景配置、`auto_split=true`、`pad_to_same_size=false` 描述实际处理。`color_key_strength=80` 仅色键路径适用。
+- `operation_id` 表示本地步骤，生成整图中的 `job_id` 表示远端 AI 生图任务。当前共享返回值不提供 `task_id`、`outputs`、拆分框或图片实际宽高；裁切框与输出尺寸保存在拆图步骤记录中。
+
+拆出的文件以批次标识加 `_asset_01.png` 等序号命名，不按物件语义命名。生成后查看整图和各 PNG，根据真实内容建立“文件 → 用途”清单，检查粘连、误拆、缺件、背景残留和不同批次的风格一致性，再按需命名。
+
+接入游戏时将独立 PNG 作为静态精灵／贴图使用：精灵是游戏里显示一张二维图片的对象。依据接地点设置枢轴，按统一世界比例缩放和摆放，并在引擎中另行配置遮挡层级与碰撞体。不要把图片边界直接当作碰撞范围；尺寸一致性、网格对齐和无缝性都需另外验收。需要打包图集时再用项目既有工具打包，记录裁边和枢轴信息。
+
+最终色键和拆图文件只保存本地，没有自动上传；需要公网 URL 时用 `evomeme_upload_game_asset` 上传对应最终 `local_path`，不要拿原整图的 URL 代替某个拆出物件。
+
+拆图至少需要两个可分离主体。若失败，先读取具体错误并通过任务记录或画布定位已生成的整图、可选去底色图和已写入的文件；失败不保证返回完整产物清单。不要因拆图失败就立即重新付费生成。检查原图后选择裁切/处理，确需重新生成时再调整间距、背景或提示词。

package/dist/skills/zh-CN/game-asset-batch-generator/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "批量游戏素材生成"
+  short_description: "生成统一视角和风格的游戏素材包，解释去底色、自动拆图及资源使用方式"
+  default_prompt: "使用 $game-asset-batch-generator 生成一套指定视角的游戏素材，说明生成步骤、文件产物及如何接入游戏。"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/zh-CN/game-asset-image-generator/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: game-asset-image-generator
+description: 使用 MCP 生成游戏概念图、背景与图片素材，或对已有图片智能抠图、剔除背景色。说明文生图、图生图和透明 PNG 的用途、参考图准备及输出；角色四视图、八方向和视频使用各自技能。
+---
+
+# 游戏图片素材生成与处理
+
+角色四视图或八方向需求使用 [角色四视图与八方向生成技能](../game-character-view-generator/SKILL.md)；视频使用 [游戏视频生成技能](../game-video-generator/SKILL.md)；生成瓦片地图或无缝砖块时必须使用 [瓦片地图资源生成、编辑与优化技能](../game-tile-generator/SKILL.md)，地块集生成及已有地块消缝也使用该技能。
+
+生成、编辑卷轴地图、横向循环背景或视差图层时，必须使用 [卷轴地图资源生成与编辑](../game-scroll-generator/SKILL.md)，其中同时说明已有卷轴图的左右消缝。
+
+## 工作区与产物
+
+调用图片工具时显式传入当前工作区根目录的绝对路径 `workspace_dir`。产物保存在该工作区的 `assets/` 中；记录返回的 `asset_id`、`local_path` 和远端 URL。
+
+平台游戏运行时通过项目配置（通常为 `public/config.json`）读取 TOS URL。颜色剔除只生成本地 PNG；需要将它用于平台游戏时，另行调用 `evomeme_upload_game_asset` 上传其 `local_path` 并记录返回 URL。
+
+## 参考图准备（调用前必须完成）
+
+使用用户上传附件、对话图片、概念图或其他本地图片作为生图参考时，必须先将图片放入本次 `workspace_dir` 对应的 `assets/`，再调用生图 MCP：
+
+1. 定位 IDE 提供的真实附件文件，并确认图片可以读取；只有可访问图片链接时，先下载为本地图片。无法取得实际图片文件时说明缺失，停止该次参考图调用，不得猜测路径或素材 ID。
+2. 图片已在当前工作区 `assets/` 内时直接复用；位于其他位置（包括工作区中 `assets/` 以外的目录）时，先复制到 `assets/` 或其子目录，例如 `assets/references/`。同名但不同内容的文件使用新文件名，避免覆盖已有素材。
+3. 确认复制后的图片存在且可读取，以它相对于工作区根目录的路径作为素材 ID，使用 `/` 分隔。例如 `D:/my-game/assets/references/hero.png` 对应 `assets/references/hero.png`。
+4. 普通图生图将这些 ID 放入 `reference_ids`；四视图和八方向使用 `character_reference_id`，已有四视图使用 `four_view_id`。显式传入同一个 `workspace_dir`。这些参数不接受原始附件绝对路径、URL 或图片 Base64。
+
+已有生图产物直接复用返回的 `asset_id`，不重复复制。这套步骤让参考图成为工作区素材，使生成任务能记录来源并供画布绘制依赖连线。无参考图的文生图不需要准备参考文件。
+
+## 三个平级图片工具
+
+| 工具（中文名称） | 具体操作与产物 | 使用情况 |
+| --- | --- | --- |
+| `evomeme_generate_game_image`（图片生成） | 根据提示词及可选参考图生成一张新图片，保存到 `assets/` 并返回路径和云端 URL。格式以返回的 `mime_type` 为准。 | 生成概念图、角色、道具、背景；无参考图为文生图，有参考图为图生图。 |
+| `evomeme_cutout_game_image`（智能抠图） | 识别原图主体、生成蒙版，再用蒙版合成一张透明 PNG，保存到 `assets/` 并上传。蒙版表示每个像素应保留或变透明的程度。 | 保留角色或道具主体，去掉背景，特别是背景并非单一颜色时。 |
+| `evomeme_color_key`（颜色剔除） | 在本地将与指定颜色匹配的像素变透明，生成一张新的 PNG，保存到 `assets/`；不会自动上传。 | 智能抠图不可用，且背景颜色明确时；例如去掉纯白或洋红底。 |
+
+三个工具与画布对应功能共用客户端底层函数。透明 PNG 的透明区域由 alpha 通道记录，可叠放到游戏场景；它不是涂成白色的背景。
+
+互不依赖的素材任务可以并行；生成图片之后再抠图或剔除颜色的步骤依赖前一步产物，须按顺序执行。图片生成不会自动抠图。
+
+## 图片生成
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `prompt` | 是 | 提示词。 |
+| `model` | 否 | `asset-max`、`asset-pro`、`asset-lite`，默认 `asset-pro`。 |
+| `background` | 否 | `opaque`、`transparent`、`auto`，默认 `opaque`。 |
+| `size` | 否 | 所选模型支持的预设，默认 `2048x2048`。 |
+| `reference_ids` | 否 | 工作区参考图片素材 ID 数组，例如 `["assets/hero.png"]`；省略或空数组为文生图。 |
+| `workspace_dir` | 否 | 当前工作区绝对路径，调用时显式指定。 |
+
+预设包括 `1024x1024`、`2048x2048`、`1728x2304`、`2304x1728`、`2560x1440`、`1440x2560`、`1664x2496`、`2496x1664`、`3024x1296`；`asset-lite` 不支持 `1024x1024`。
+
+透明文生图使用 `model="asset-max", background="transparent"`。`auto` 背景也仅适用于 `asset-max`。`asset-lite` 没有背景切换。`asset-pro` 的 `transparent` 要求 `reference_ids` 中恰好一张含透明像素的 PNG。参考图相对于 `workspace_dir`，可使用图片工具返回的 `asset_id`；`asset-pro` 最多 10 张，`asset-lite` 最多 14 张，`asset-max` 最多 16 张。参数及参考图处理与画布图片生成一致，但 MCP 只接受预设尺寸，不接受自定义尺寸或旧版图片类型参数。
+
+生成单个静态元素时先读取 [静态游戏元素提示词指南](references/static-game-assets.md)；完整背景先读取 [游戏背景提示词指南](references/background.md)。已有概念图时，读取其造型、配色和画风并写入提示词，需要直接引用时通过 `reference_ids` 提供工作区图片。
+
+## 智能抠图
+
+提供 `id` 或 `image_url` 中的一个，并指定 `workspace_dir`：
+
+- `id`：工作区图片素材 ID，例如 `assets/hero.png`，可使用生成工具返回的 `asset_id`。
+- `image_url`：可访问的 HTTP/HTTPS 原图 URL。
+
+工具等待蒙版任务完成，在本地合成透明 PNG 并上传。失败信息透传到 MCP；工具不会自行改用颜色剔除。
+
+## 颜色剔除
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `id` | 是 | 工作区原图素材 ID。 |
+| `color` | 否 | 剔除颜色，`#RRGGBB`，默认 `#ffffff`。 |
+| `strength` | 否 | 0–100，默认 80。 |
+| `contiguous_only` | 否 | 仅剔除与图像边界相连的连续区域，默认 `false`。 |
+| `despill` | 否 | 消除保留边缘像素中的背景色溢出，默认 `false`。 |
+| `workspace_dir` | 否 | 当前工作区绝对路径。 |
+
+本地执行，不依赖登录或智能抠图服务。先根据原图背景选择剔除颜色；它按颜色处理，不具备语义主体识别能力。
+
+`strength` 控制颜色匹配的容差，越大越容易连同相近颜色一起剔除。`contiguous_only` 为 `true` 时，只去掉能从图片边界连通到的匹配区域，减少主体内部同色区域被挖空的情况。`despill`（滤色）用于减轻保留下来的半透明边缘所混入的背景色，不会识别或重画主体。
+
+## 返回与失败
+
+三个工具成功后只返回文本元数据，不返回图片 Base64 或 MCP `image` 内容块。文本包含 `asset_id`、`local_path`、`mime_type` 和处理信息；生成与智能抠图还包含 `job_id`、`asset_url`/`tos_url`、`status` 和 `attempts`，颜色剔除包含本地 `operation_id` 与四个处理参数。通过 `asset_id` 继续处理素材，通过 URL 引用云端图片；需要查看图片内容时，按需使用 IDE 可用的图片查看工具读取 `local_path` 或打开图片 URL，不要把图片 Base64 写入对话或项目配置。
+
+失败时 `isError: true`，文本保留具体错误。记录失败原因并使用仍然保留的原图；智能抠图不可用时，按原图背景选择颜色剔除参数。

package/{skills → dist/skills/zh-CN}/game-asset-image-generator/references/background.md

@@ -1,10 +1,12 @@
 # 游戏背景提示词指南
 
+本指南用于普通完整单层背景。生成卷轴地图、横向循环背景、多层视差资源或修补卷轴接缝时，必须使用 [卷轴地图资源生成与编辑](../../game-scroll-generator/SKILL.md)；该技能会按需生成多层、消缝和去底色。
+
 游戏背景是铺满游戏画面的完整单层场景图片，例如森林、城市街道、太空区域、地下洞穴或室内空间。每张背景只生成一次，并作为单独的 `background` 图片使用。
 
 ## 使用概念图作为引用
 
-如果存在游戏概念图或当前场景的设定概念图，必须将概念图的可访问 URL 作为 `reference_image_url`：
+如果存在游戏概念图或当前场景的设定概念图，先读取其内容并将可继承的特征写入提示词；需要直接引用原图时，必须先将图片复制到当前工作区 `assets/`（已在其中则复用），确认可读取后再通过 `reference_ids` 提供工作区相对素材 ID，显式指定同一 `workspace_dir`：
 
 - 优先使用当前场景的设定概念图；没有时再使用整体游戏概念图。
 - 在提示词中明确需要继承的特征，例如世界观、场景结构、配色、材质、光照和画风。