evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/zh-CN/game-asset-mesh-generator/references/postprocess-contracts.md

@@ -0,0 +1,187 @@
+# 模型后处理与动画
+
+按需读取当前操作的章节。公共任务参数、结果、ID 含义和恢复规则见 [tool-reference.md](tool-reference.md)。示例为 MCP 参数，演示 ID 需替换成真实已成功的来源。
+
+## 目录
+
+- [公共输入](#公共输入)
+- [贴图](#texture)
+- [风格化](#stylize)
+- [分割](#segment)
+- [补全](#complete)
+- [减面](#decimate)
+- [转换](#convert)
+- [绑骨](#rig)
+- [重定向](#retarget)
+
+## 公共输入
+
+| 参数 | 类型 | 用途 |
+| --- | --- | --- |
+| `task_id` | string | 已成功的网关公共来源任务 ID。 |
+| `url` | string | 公开 HTTP(S) 模型 URL。 |
+| `input` | string | 公开模型 URL、已上传文件 token 或网关公共来源任务 ID。 |
+| `mesh_format` | string | 可选存储格式提示，默认 `glb`；仅贴图、风格化、分割、补全、减面接受此字段，不会据此转换文件。 |
+
+`task_id`、`url`、`input` 严格三选一。**补全和重定向只接受 `task_id` 或 `input`，内容必须是对应已成功的分割或绑骨公共 ID**；不接受 URL 或文件 token。其他操作支持 GLB/GLTF/FBX/OBJ/STL 来源模型，上限 150 MB；本地文件先上传。
+
+版本和默认值按操作定义，与生成阶段的 H/P 版本独立。不支持的字段完全省略，包括 `false`；支持的显式 `false`/`0` 保留。以下参数表不重复公共任务与来源参数，输出以实际返回格式为准。
+
+<a id="texture"></a>
+
+## 贴图 — evomeme_texture_mesh
+
+| 参数 | 类型 | 默认值与限制 |
+| --- | --- | --- |
+| `model_version` | string | 默认 `v3.0-20250812`，另有 `v2.5-20250123`、`v3.5-20260815`。 |
+| `texture_prompt` | object 或 string | 可选引导，形式见下文；字符串为文本简写。 |
+| `pbr` | boolean | `true`；PBR 材质。 |
+| `texture_seed` | integer | 省略随机，`0` 有效。 |
+| `texture_alignment` | string | `original_image` 或 `geometry`，默认 `original_image`。 |
+| `texture_quality` | string | 默认 `standard`，另有 `fast`、`detailed`、`extreme`（8K）。v2.5 必须省略；`fast` 要求本操作的 `model_version="v3.5-20260815"`。 |
+| `part_names` | string[] | 省略处理全部部件；使用真实分割名称。 |
+| `compress` | string | `geometry` 启用 meshopt，省略不压缩；v2.5 必须省略。 |
+| `bake` | boolean | `true`；烘焙材质效果。 |
+| `delight` | boolean | `true`；去除参考图烘焙光照，仅 v3.5 读取。 |
+
+`texture_prompt` 对象的 `text`、`image`、`images` 三选一，`style_image` 只能搭配 `text`。图像值接受 URL/文件 token 字符串，或只含 `url`/`file_token` 之一的对象。`images` 严格四项，顺序 front,left,back,right；风格图建议至少 256×256。已生成模型可以复用来源参考；导入模型应提供引导，图生模型重新贴图时应再次提供参考图。不传生成专用的几何参数。
+
+```json
+{"task_id":"task_public_model","texture_prompt":{"text":"Weathered oak bark and moss"},"model_version":"v3.5-20260815","texture_quality":"fast","texture_seed":0}
+```
+
+<a id="stylize"></a>
+
+## 风格化 — evomeme_stylize_mesh
+
+| 参数 | 类型 | 默认值与限制 |
+| --- | --- | --- |
+| `style` | string | 必填：`lego`、`voxel`、`voronoi`、`minecraft`。 |
+| `block_size` | integer | 可选正整数，省略保留上游默认。 |
+
+```json
+{"task_id":"task_public_model","style":"voxel","block_size":80}
+```
+
+<a id="segment"></a>
+
+## 分割 — evomeme_segment_mesh
+
+| 参数 | 类型 | 默认值与限制 |
+| --- | --- | --- |
+| `model_version` | string | 默认 `v1.0-20250506`（几何分割）；`v2.0-20260430` 为语义分割（Beta）。 |
+| `segmentation_granularity` | string | 仅 v2：`simple`、`balanced`（默认）、`detailed`。 |
+| `split_by_connectivity` | boolean | 仅 v2，默认 `true`。 |
+| `ref_image` | string | 仅 v2，可选参考图 URL/文件 token。 |
+
+v1 必须省略后三项。提供 `ref_image` 后，上游忽略 `segmentation_granularity` 和 `split_by_connectivity`。部件名称取自实际结果，不根据文件名猜测，也不假定固定的嵌套部件结构。
+
+```json
+{"task_id":"task_public_model","model_version":"v2.0-20260430","segmentation_granularity":"balanced","split_by_connectivity":false}
+```
+
+<a id="complete"></a>
+
+## 补全 — evomeme_complete_mesh
+
+| 参数 | 类型 | 默认值与限制 |
+| --- | --- | --- |
+| `model_version` | string | `v1.0-20250506`。 |
+| `part_names` | string[] | 省略补全全部部件；使用真实分割名称。 |
+| `completion_mode` | string | `ai_completion` 生成缺失几何，`quick_cap` 封闭孔洞；默认 `ai_completion`。 |
+
+来源必须是成功的 `evomeme_segment_mesh` 公共任务 ID，不能使用生成 ID 或其他种类的分割 ID 替代。
+
+```json
+{"task_id":"task_public_segment","completion_mode":"quick_cap"}
+```
+
+<a id="decimate"></a>
+
+## 减面 — evomeme_decimate_mesh
+
+| 参数 | 类型 | 默认值与限制 |
+| --- | --- | --- |
+| `model_version` | string | 默认 `v2.0`，另有 `v1.0`、`v3.0`。v1 为基础减面，v2/v3 为智能重拓扑。 |
+| `face_limit` | integer | v1 必填：三角面 1–2000000，四边面 1–150000。v2/v3 省略自适应；显式填写时三角面 500–20000，四边面 500–10000。 |
+| `quad` | boolean | `false`，三个版本均支持。 |
+| `smart_uv` | boolean | 仅 v3，默认 `false`；展开 UV，不输出 UV 图集预览。 |
+| `bake` | boolean | 仅 v2/v3，默认 `true`；烘焙贴图。 |
+| `part_names` | string[] | 仅 v2/v3，省略处理全部部件。 |
+
+v1 省略 `bake`/`part_names`；v1/v2 完全省略 `smart_uv`，包括 `false`。
+
+```json
+{"task_id":"task_public_model","model_version":"v3.0","face_limit":5000,"smart_uv":true,"bake":false}
+```
+
+<a id="convert"></a>
+
+## 转换 — evomeme_convert_mesh
+
+| 参数 | 类型 | 默认值与限制 |
+| --- | --- | --- |
+| `format` | string | 默认 `GLTF`，另有 `FBX`、`USDZ`、`OBJ`、`STL`、`3MF`。 |
+| `quad` | boolean | `false`；`true` 强制 FBX。 |
+| `face_limit` | integer 或 null | 省略/null 保留原面数，四边面除外，其默认 10000；显式整数必须大于零。 |
+| `force_symmetry` | boolean | `false`；开启要求 `quad=true`。 |
+| `flatten_bottom` | boolean | `false`；压平底部。 |
+| `flatten_bottom_threshold` | number | `0.01`；非负压平深度。 |
+| `texture_size` | integer | `4096`；正整数像素尺寸。 |
+| `texture_format` | string | 默认 `JPEG`，另有 `PNG`、`WEBP`、`BMP`、`DPX`、`HDR`、`OPEN_EXR`、`TARGA`、`TIFF`。 |
+| `bake` | boolean | `true`；烘焙材质效果。 |
+| `pack_uv` | boolean | `false`；统一 UV 布局。 |
+| `export_vertex_colors` | boolean | `false`；开启要求 OBJ/GLTF 且 `quad=false`。 |
+| `pivot_to_center_bottom` | boolean | `false`；轴心移到底部中心。 |
+| `scale_factor` | number | `1`；必须大于零。 |
+| `with_animation` | boolean 或 null | 默认 `true`，保留骨架与动画；null 表示不指定。 |
+| `animate_in_place` | boolean | `false`；移除根节点位移。 |
+| `part_names` | string[] | 省略导出全部部件。 |
+| `export_orientation` | string | 默认 `+x`，另有 `-x`、`+y`、`-y`；在此设置最终朝向。 |
+| `fbx_preset` | string | 默认 `blender`，另有 `3dsmax`、`mixamo`、`bake_scale`；`bake_scale` 将缩放烘焙到 FBX 几何。 |
+
+该工具不接受 `model_version` 或 `mesh_format`。`format=GLTF` 可能返回资源包，而不是单个 GLB。材质和动画能否保留取决于来源及目标格式；OBJ 不承载动画，STL 用于几何打印。按公共格式与就绪规则处理输出。
+
+```json
+{"task_id":"task_public_model","format":"GLTF","pivot_to_center_bottom":true,"with_animation":true}
+```
+
+<a id="rig"></a>
+
+## 绑骨 — evomeme_rig_mesh
+
+| 参数 | 类型 | 默认值与限制 |
+| --- | --- | --- |
+| `rig_type` | string | 默认 `biped`，另有 `quadruped`、`hexapod`、`octopod`、`avian`、`serpentine`、`aquatic`。 |
+| `model_version` | string | 根据身体结构推导：biped → `v1.0-20240301`，其他 → `v2.5-20260210`。显式版本优先；v1 仅支持双足。 |
+| `spec` | string | `tripo` 或 `mixamo`，默认 `tripo`；选择骨骼命名规范，使用 Tripo 动画预设时优先 `tripo`。 |
+| `out_format` | string | `glb` 或 `fbx`，默认 `glb`；动画流程优先 GLB。 |
+
+根据实际模型选择身体结构并检查骨架。v2.5 也有独立的双足预设目录。将返回的绑骨公共 `task_id` 交给重定向，而非原模型来源 ID。
+
+```json
+{"task_id":"task_public_model","rig_type":"quadruped","model_version":"v2.5-20260210","spec":"tripo","out_format":"glb"}
+```
+
+<a id="retarget"></a>
+
+## 重定向 — evomeme_retarget_mesh
+
+| 参数 | 类型 | 默认值与限制 |
+| --- | --- | --- |
+| `animation` | string | 一个完整的 `preset:` 标识，与 `animations` 互斥。 |
+| `animations` | string[] 或 string | 非空预设数组；兼容逗号字符串。两个选择字段均省略时，插件按下方骨架提示选择 walk。 |
+| `out_format` | string | `glb` 或 `fbx`，默认 `glb`。 |
+| `bake_animation` | boolean | `true`，仅 GLB 生效。 |
+| `export_with_geometry` | boolean | `true`；`false` 导出供已有匹配骨架使用的动画。 |
+| `animate_in_place` | boolean | `false`；`true` 移除根节点位移。 |
+| `rig_type` | string | 可选值同绑骨，默认 `biped`；为省略或逗号字符串预设提供兼容提示。 |
+| `model_version` | string | 按 `rig_type` 推导，同上；用于兼容预设映射。 |
+
+来源必须为成功的绑骨公共 ID。优先显式填写匹配骨架的完整预设：v1 双足使用 `preset:biped:*`，v2.5 双足使用 `preset:walk` 等。显式 `animation` 和数组 `animations` 原样传递。先读 [animation-presets.md](animation-presets.md)；当前目录未列出鸟类预设，不要编造。
+
+优先 `animate_in_place=false`，需要时在引擎中消除不需要的水平根位移。纯动画导出需要匹配骨架，不能作为独立可见角色。检查实际片段后再命名，不保证返回名称与顺序。
+
+```json
+{"task_id":"task_public_rig","animations":["preset:quadruped:walk"],"rig_type":"quadruped","model_version":"v2.5-20260210","out_format":"glb","animate_in_place":false}
+```

package/dist/skills/zh-CN/game-asset-mesh-generator/references/threejs-integration.md

@@ -0,0 +1,113 @@
+# Three.js Integration
+
+Use this after `game-asset-mesh-generator` generates or post-processes a model.
+
+## Preferred Outputs
+
+- Three.js 运行时优先 **GLB/PBR**。生成默认 `mesh_format=auto`，H 四边面输出 FBX；绑骨与重定向默认 `out_format=glb`。不兼容的文件先转换再导入。
+- MCP 成功时返回已下载的 `local_path` 和最终 `asset_url`。遵循公共[结果与就绪规则](tool-reference.md)，不能把原始 HTTP 的 pending URL 当作已完成资产。
+- Animation/game-engine interchange: use FBX only when explicitly required; otherwise keep GLB.
+- Static web asset exchange: GLTF/GLB.
+- 3D print only: STL or 3MF, not for textured game runtime.
+- Apple AR: USDZ.
+
+## Import Pattern
+
+运行时集成前，使用 `local_path` 指向的已下载 GLB，并遵循 [game-asset-align](../../game-asset-align/SKILL.md)。 Remote generation/postprocessing remains MCP; local intake and engine delivery use CLI. The [CLI contract](../../game-asset-align/references/tool-contract.md) defines launcher/version selection, relative paths, JSON results, and confirmation gates.
+
+```sh
+npx -y evomeme@latest asset import "<downloaded.glb>" --id character --workspace "<workspace>" --source tripo --type character --json
+npx -y evomeme@latest asset review character --workspace "<workspace>" --json
+npx -y evomeme@latest stage --asset character --workspace "<workspace>" --target three_js --json
+```
+
+Use the actual source/type for the asset; the example is a Tripo character. Keep Stage running in a persistent terminal/session and give the user `data.url`. After the user views and confirms the current version, run this in another terminal with the same CLI version:
+
+```sh
+npx -y evomeme@latest asset sync character --workspace "<workspace>" --target three_js --project "<project>" --json
+```
+
+Integrate through the synced canonical runtime described in [engine asset loading](../../threejs-3d-game/references/engine-asset-pipeline.md). Preserve the single alignment wrapper and reviewed appearance; a remote URL or a successful technical review alone does not authorize game import. Use the canonical loader's imported animation clips with the engine animation system.
+
+Animation intake notes (engine-side; remote MCP exposes `evomeme_rig_mesh` / `evomeme_retarget_mesh`):
+
+- Inspect the returned files and animation clips before assigning gameplay names. Generic `NlaTrack*` names may occur, but the API does not guarantee names, clip order, or one file per batch. Verify each motion before renaming it (`clip.name = 'walk'`); do not map presets by index without checking the actual clips.
+- Log `gltf.animations.map(c => `${c.name} ${c.tracks.length} tracks`)` after load. A healthy humanoid clip drives many bones; clips with only a handful of tracks mean the upstream auto-rig was degenerate — fix the rig, not the runtime.
+- Do NOT strip or neutralize twist-bone tracks (`UpperarmTwist`, `ForearmTwist`, …) on v1.0 rigs: Tripo skins most of the limb mesh to the twist bones, and their baked values differ greatly from the GLB rest pose — removing the tracks collapses the limbs into the torso. Tripo's slightly open, palm-forward hands are the preset house style, not corruption.
+- Prefer converting to in-place at import rather than trusting upstream `animate_in_place`. Use `animate_in_place=false` on `evomeme_retarget_mesh` (the default), then strip root motion precisely:
+  - Touch ONLY the top root bone's position track (`Root.position`). Tripo FBX clips bake position tracks on EVERY bone with values that differ from FBXLoader's rest transforms; filtering Hip/Pelvis or pattern-matching broadly collapses the skeleton into a hunch.
+  - Zero the HORIZONTAL components only — keep Y. Vertical root motion IS the animation for jumps (and the bob in gaits); deleting the whole track turns a jump into grounded hand-waving.
+
+```ts
+for (const clip of clips) {
+  for (const tr of clip.tracks) {
+    if (tr.name !== 'Root.position') continue;
+    const v = tr.values, x0 = v[0], z0 = v[2];
+    for (let i = 0; i < v.length; i += 3) { v[i] = x0; v[i + 2] = z0; }
+  }
+}
+```
+
+FBX intake specifics (only if the user explicitly required `out_format=fbx`; default path is GLB):
+
+- `FBXLoader` lives at `three/addons/loaders/FBXLoader.js` and imports `fflate`; bundler projects get it from npm automatically, but import-map/CDN pages must map it (e.g. `"fflate": "https://cdn.jsdelivr.net/npm/fflate@0.8.2/esm/browser.js"`).
+- Use ONE FBX per animation (the pipeline does this automatically) and play each file's `animations[0]` as exported. The variant order of duplicate takes differs per file — `animations[0]` is always the correct one.
+
+- `FBXLoader` emits each take twice under different node-path prefixes (`Armature.001|walk_…` and `Armature|Armature.001|walk_…`). Keep the variant with the SHALLOWER path (fewer `|` segments); the deep variant's tracks bind incorrectly.
+- Clips carry real names (`walk_normal_m_remap`, `idle_251105_remap`) — select by keyword (slash arrives as an attack/swing name), not by index.
+- Play the clips otherwise untouched. Every loader-side "fix" beyond the single root-position strip has been tested and makes things worse.
+- FBXLoader produces Phong materials (darker than GLB PBR). For final art parity, convert FBX→GLB offline (Blender import/export or FBX2glTF) — the corrected animation survives conversion.
+- Tripo preset retargeting only works on `spec=tripo` rigs. A `spec=mixamo` rig is for external animation pipelines (Mixamo clips, custom libraries) — retarget those in a DCC tool or at runtime with `SkeletonUtils.retargetClip`, and expect to supply bone-name mappings and check bind-pose orientation when skeleton conventions differ.
+
+## Asset Intake Checklist
+
+Inspect before shipping:
+
+- File size.
+- Triangle count.
+- Mesh count.
+- Material count.
+- Texture count and texture dimensions.
+- PBR material behavior under the game lighting rig.
+- Scale in meters and `auto_size` assumptions.
+- Pivot/origin and bounds.
+- Collision proxy separate from detailed mesh.
+- Animation clip names, durations, root motion, and in-place behavior.
+- Mobile memory/performance impact.
+
+## Game Asset Strategy
+
+- Use `game-asset-mesh-generator` for hero assets, characters, creatures, bosses, buildings, weapons, signature props, and complex pickups.
+- Use procedural Three.js kits for high-volume repeated detail such as bolts, windows, track plates, rails, debris, markers, and background silhouettes.
+- For concept art, texture references, decals, logos, UI icons, and backdrop images: prefer procedural/CSS/canvas; use user-supplied images or remote MCP `evomeme_generate_game_image` when needed.
+- Combine: 2D reference (user/remote/procedural) -> 3D-generator model -> canonical CLI intake, Stage confirmation and sync -> Three.js integration -> procedural set dressing -> visual scorecard.
+
+## Performance Discipline
+
+- Use `face_limit`, `smart_low_poly`, conversion, or low-poly postprocess for browser/mobile budgets.
+- Prefer one high-fidelity hero asset plus instanced/procedural supporting detail over many unique heavy models.
+- Keep textures compressed or reasonably sized.
+- Clone carefully. Share geometry/materials when possible.
+- Dispose loaded assets when leaving scenes.
+- Run renderer diagnostics after importing: calls, triangles, geometries, textures, materials, file sizes.
+
+## Common Fixes
+
+- Model too large/small: return to `game-asset-align` to measure the canonical scale recipe, review, and sync again.
+- Wrong orientation: update the canonical recipe through Stage or `asset align`, then review and sync again; do not add runtime compensation. Tripo image `orientation=align_image` can guide generation, but does not replace canonical review.
+- Animations move out of place: keep exported root motion intact (`animate_in_place=false` on MCP), then strip only horizontal root-position components in code as shown above. Do not rely on MCP `animate_in_place=true` for final quality.
+- 性能开销过高：降低 `face_limit`，仅 H3 可使用 `smart_low_poly`，或降低贴图质量/尺寸、转换时限制面数。
+- Materials too dark/bright: check color space, tone mapping, environment, and light exposure.
+- Collision too complex: build primitive proxies in Three.js and keep Tripo mesh visual-only.
+
+## Final Evidence
+
+Report:
+
+- MCP tool names used (`evomeme_text_to_mesh`, `evomeme_rig_mesh`, `evomeme_retarget_mesh`, …).
+- 各个已完成生成、绑骨、重定向阶段的网关公共 `task_id`，以及 `job_id` 和 `local_task_id`。
+- 各阶段已下载的 `local_path`、最终 `asset_url`、实际 `mesh_format` 和导入验证结果。
+- Model version and generation/postprocess options (`rig_type`, `animations`, `out_format`, `animate_in_place`).
+- Local CLI commands, canonical asset ID, Stage confirmation status, synced loader/import files, and any clip rename or root-motion strip.
+- Renderer diagnostics before/after import.
+- Screenshot evidence in active gameplay.

package/dist/skills/zh-CN/game-asset-mesh-generator/references/tool-reference.md

@@ -0,0 +1,67 @@
+# Mesh MCP 工具参考
+
+十个本地 `evomemeMCP` Mesh 工具的公共调用约定。按需读取具体操作的参数；以工具 schema 和实际返回结果为准。
+
+## 工具选择
+
+| 工具 | 用途 | 参数 |
+| --- | --- | --- |
+| `evomeme_text_to_mesh` | 文本生成模型 | [生成契约](generation-contracts.md) |
+| `evomeme_image_to_mesh` | 单图或多视图共同生成一个模型 | [生成契约](generation-contracts.md) |
+| `evomeme_texture_mesh` | 生成或替换贴图 | [贴图](postprocess-contracts.md#texture) |
+| `evomeme_stylize_mesh` | Lego、voxel、voronoi 或 minecraft 风格化 | [风格化](postprocess-contracts.md#stylize) |
+| `evomeme_segment_mesh` | 拆分模型部件 | [分割](postprocess-contracts.md#segment) |
+| `evomeme_complete_mesh` | 补全部件 | [补全](postprocess-contracts.md#complete) |
+| `evomeme_decimate_mesh` | 减面或重拓扑 | [减面](postprocess-contracts.md#decimate) |
+| `evomeme_convert_mesh` | 转换格式、尺度、轴心或朝向 | [转换](postprocess-contracts.md#convert) |
+| `evomeme_rig_mesh` | 自动绑骨 | [绑骨](postprocess-contracts.md#rig) |
+| `evomeme_retarget_mesh` | 为骨架应用预设动画 | [重定向](postprocess-contracts.md#retarget) |
+
+本地任务通过已鉴权的插件 API 提交请求，等待远端发布完成并下载结果。上游凭据留在服务端；不直连 Tripo，也不根据本地是否配置厂商密钥判断服务可用性。本地处理和游戏集成使用各自对应的工具。
+
+## 公共任务参数
+
+| 参数 | 类型 | 行为 |
+| --- | --- | --- |
+| `workspace_dir` | string | 可选工作区路径，默认 MCP 工作目录。多工作区场景建议显式传绝对路径。结果下载到 `assets/mesh/`。 |
+| `client_operation_id` | string | 可选操作标识，限 1–140 位 ASCII 字母、数字、`_`、`-`。省略会新建标识。同一工作区、工具、标识和参数复用同一任务；同标识改参数会冲突。不同操作或阶段使用不同标识。 |
+
+## 返回结果与标识
+
+成功返回为 MCP 文本，包含具名字段和末尾的 `result: <JSON>`。解析其中 JSON 以保留嵌套数据；它不是 HTTP 响应包。成功表示远端任务完成，且主文件已下载并登记到本地资产库。
+
+| 字段 | 含义 |
+| --- | --- |
+| `local_task_id` | 本地根任务 ID，不能作为模型来源。 |
+| `client_operation_id` | 恢复或复用本次操作的标识。 |
+| `job_id` | 插件服务端任务 ID，不能作为模型来源。 |
+| `task_id` | 本次操作的网关公共任务 ID；下游必须选择对应已成功阶段的 ID。 |
+| `role` | 根据操作为 `model`、`rigged` 或 `animated`。 |
+| `local_path` | 已下载的主文件。 |
+| `asset_url` | 已托管的主文件 URL。 |
+| `mesh_format` | 实际下载格式；压缩包仍是压缩包。 |
+| `asset_id` | 工作区资产 ID，同时位于 `result.id`。 |
+| `result` | 完整对象，含 `status`、`operation`、`operation_id`、`mime_type`、`bytes` 和 `generation`。 |
+| `result.generation` | 远端回执与结果元数据，含 `output`、`metadata`、`generationParameters`，以及可用的进度、类型、积分、时间字段。保留未知嵌套字段和 URL。 |
+
+生成操作的 `input`/`inputs` 可接受的上游**图像**任务 ID，与网关**模型**任务 ID 属于不同命名空间。`task_` 等前缀不能证明 ID 的归属或任务类型；不要编造 ID 或使用本地 ID 代替。
+
+## 结果就绪与任务串联
+
+- 使用成功且非 `isError` 的结果、已下载文件、最终 URL 和实际格式。单独一个 URL，或原始 HTTP 的 `pending=true` 回执，都不能证明完成。
+- MCP 任务负责轮询和下载，正常调用无需另行轮询 HTTP。进入引擎前，验证实际文件能够成功导入。
+- 每个操作下载自己的主结果；串联时保留各阶段文件和 URL。
+- 重定向使用成功的**绑骨** `task_id`，补全使用成功的**分割** `task_id`。生成任务 ID 和裸 URL 不能代替这些特定来源。
+- 保留 `result.generation.output` 的全部链接。仅主 `asset_url` 保证由插件托管，其他链接可能过期。分件任务的主文件可能只是一个部件或压缩包，并非完整组装模型。检查实际部件与动画，不假定名称或顺序。
+- 下载保留实际字节和格式，不能通过改后缀将 FBX/ZIP 变成 GLB；使用转换工具和相应导入方式。
+
+## 失败与恢复
+
+1. 保留 MCP `isError` 原文，以及返回的 `client_operation_id`、`local_task_id`、`job_id`、`stage`。传输断开不代表远端失败，本地 worker 可能仍在运行。
+2. 查询或下载中断时，以原工作区、原 `client_operation_id` 和完全相同的参数重新调用同一工具。它会等待已有任务、恢复可恢复的中断工作或返回缓存结果，避免主动新建生成任务。
+3. 提交回执不确定（`NEEDS_ATTENTION`）时需要检查。复用标识不会自动重试已终止的生成失败；不要只为绕过这些状态而更换标识。明确重新生成属于新的付费操作。
+4. 客户端负责认证更新；无法恢复登录时，先解决返回的认证问题，再恢复原任务。保留上游或审核错误，不自动替换成其他付费操作。
+
+## 角色组合
+
+内部 `character_pipeline` 任务编排可选生成 → 绑骨 → 可选重定向，并逐阶段记录和下载。MCP 只公开上述原子工具，不提供 pipeline 或 rig-check 工具。身体结构与预设要求见[后处理](postprocess-contracts.md#rig)和[动画预设](animation-presets.md)。

package/dist/skills/zh-CN/game-audio/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: game-audio
+description: 将已托管的 BGM / SFX 接入 Phaser / Three.js 运行时配置；CDN 清单不够时可经 MCP 文生新 BGM。在游戏需要 CDN/TOS 音频 URL、配置绑定、加载器接入或 AI 生成循环音乐时使用。
+---
+
+# 游戏音频
+
+## 概述
+
+将此技能用于已托管在 CDN 或对象存储中的游戏音频，以及 CDN 清单不够时通过 MCP 生成新的循环 BGM / 可选人声曲。拼出或拿到可加载的音频 URL 后，写入 `public/config.json` 或运行时加载器。
+
+**不在此生成短促音效（SFX）**。SFX 仍走 CDN 清单（或用户提供的 URL）。不得编造 CDN 路径；对象键缺失且用户未提供 URL 时，停止并询问。
+
+BGM 和 SFX 清单统一使用 `http://game-asset.evomeme.com/`。按照对应参考中的 `bgm/` 或 `sfx/` 前缀及编码后的文件名拼接完整 URL。优先从清单中选择已验证的曲目，并在写入运行时前确认音频 URL 可访问。
+
+## 何时使用此技能
+
+- 设计文档、配置文件或用户指定了某首 BGM 或 SFX 的文件名/键，需要给出可加载 URL
+- 填写 `bgm_main`、`audio_bgm_gameplay`、`audio_sfx_click`、`backgroundMusic`、`src`、`url` 等音频字段
+- 用户明确说音频来自公司 CDN、对象存储或固定托管 URL
+- 接入点击音、拾取音、碰撞音、射击音、爆炸音、成功/失败音等游戏反馈音效
+- 用户需要 CDN 清单中没有的**新**循环 BGM 或主题曲（使用下方 MCP 音乐生成）
+
+---
+
+## 阅读顺序
+
+1. 读完本节后，根据任务类型选择并**打开对应参考文档**，不得在未读参考的情况下拼接 CDN URL
+2. **BGM（循环背景音乐）** 走 CDN：`references/bgm-cdn.md`
+3. **SFX（短促触发音效）**：`references/sfx-cdn.md`
+4. 同时涉及 BGM 和 SFX 时，读取两个参考
+5. 需要生成新曲时，按下方 **经 MCP 生成 BGM** 执行，再用与托管 URL 相同的工作流把返回的 TOS URL 写入配置
+
+---
+
+## BGM 路由
+
+- 加载 BGM 参考文档，从中提取 CDN 根、路径前缀和曲目清单
+- 用于循环背景音乐，对应配置键如 `bgm_main`、`audio_bgm_gameplay`、`audio_bgm_menu`、`backgroundMusic`
+- 曲目不在清单中且用户要托管键时，不得编造路径；请用户确认对象键后再配置
+- 用户要的是**新** AI 曲而非清单曲目时，使用下方 MCP 生成
+
+推荐技能：`game-audio`；BGM 参考 `references/bgm-cdn.md`。
+
+## SFX 路由
+
+- 加载 `references/sfx-cdn.md`，提取 CDN 根和文件名规则
+- 用于短促触发音效，对应配置键如 `audio_sfx_click`、`audio_sfx_pickup`、`audio_sfx_impact`、`audio_sfx_shoot`、`audio_sfx_explosion`、`audio_sfx_success`、`audio_sfx_fail`
+- 高频触发音效（脚步、拖动、持续碰撞）作为节流或循环播放处理，不逐帧重触发
+
+推荐技能：`game-audio`；SFX 参考 `references/sfx-cdn.md`。
+
+---
+
+## 经 MCP 生成 BGM
+
+当游戏需要 CDN 清单中没有的新循环 BGM 或可选人声曲时，调用 `evomeme_generate_game_music`。
+
+1. 调用时必须把当前工作区根目录绝对路径传给 `workspace_dir`。
+2. 成功后工具会把音频下载到 `<workspace_dir>/assets/music/`，并返回 TOS URL。
+3. 将 TOS URL 按与 CDN URL 相同的方式写入配置 / 加载器。运行时禁止从 `assets/music/` 硬编码导入路径。
+
+默认 **纯音乐**（`is_instrumental=true`），适合菜单 / 战斗 / 探索循环 BGM。
+
+### 入参
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `prompt` | 是 | 风格、情绪、场景描述 |
+| `is_instrumental` | 否 | 默认 `true`。纯音乐时禁止填 `lyrics` / 开 `lyrics_optimizer` |
+| `lyrics` | 否 | 人声曲歌词；可用 `[Verse]` / `[Chorus]` 等结构标签 |
+| `lyrics_optimizer` | 否 | 人声且未提供歌词时，按 prompt 自动写词 |
+| `aigc_watermark` | 否 | 默认 `false` |
+| `music_model` | 否 | 仅 `music-3.0` |
+| `workspace_dir` | 是（实践上） | 工作区根目录绝对路径 |
+| `client_operation_id` | 否 | 本地任务标识，1–140 位字母、数字、下划线或连字符；恢复时复用同一标识和参数 |
+
+人声曲：设 `is_instrumental=false`，并提供 `lyrics` **或** `lyrics_optimizer=true`。
+
+### 出参（文本）
+
+- `job_id`、`tos_url` / `asset_url`、`local_path`、`mime_type`、`bytes`、`status`、`model`、`is_instrumental`
+- `client_operation_id`、`task_id`、`operation_id`、`asset_id`、`kind=audio`，用于关联本地任务、步骤和音频资产
+
+建议首次调用就提供并保存 `client_operation_id`。连接断开不会取消已启动的后台任务；轮询或下载中断后，在同一工作区用相同标识和参数再次调用，可复用原任务。成功任务直接返回保存的结果。新标识会创建新的生成任务；不要用它绕过 `NEEDS_ATTENTION`（提交结果不明）或 `FAILED`，应先核对错误。所有进程停止时不会自动恢复，需再次调用或启动该工作区的任务调度器。
+
+---
+
+## 工作流
+
+1. 确认任务类型：托管 BGM、托管 SFX、生成 BGM，或组合
+2. 托管音频：读取对应参考，提取 CDN 根、必需前缀和文件名规则；找到确切对象键；按列出的根地址拼出完整 URL
+3. 生成 BGM：用 `workspace_dir` 调用 `evomeme_generate_game_music`，使用返回的 TOS URL
+4. 将 URL 写入对应配置键、清单或运行时加载代码，保留项目现有音频架构
+5. 验证控制标志：BGM 遵守 `audio_music_enabled`，SFX 遵守 `audio_sfx_enabled`；游戏内循环不泄漏到菜单或结算页
+
+### 写入 2D 项目配置（`public/config.json`）
+
+```json
+"bgm_main":   { "value": "http://game-asset.evomeme.com/bgm/2048.mp3", "type": "audio", "label": "背景音乐" },
+"sfx_click":  { "value": "http://game-asset.evomeme.com/sfx/%E7%82%B9%E5%87%BB.mp3", "type": "audio", "label": "点击音效" }
+```
+
+### 写入 3D 项目配置
+
+按项目现有配置结构写入，config 键名遵循 `audio_bgm_*` / `audio_sfx_*` 命名规范。
+
+---
+
+## 护栏
+
+- 不编造文件名、CDN 域名、目录前缀或百分比编码片段
+- 不静默替换 BGM 和 SFX 的根路径
+- 不用音乐 MCP 工具生成 SFX；SFX 仍走 CDN 清单或用户提供的 URL
+- 运行时加载器使用清单或 MCP 结果中的托管音频 URL
+- 对象键缺失或用户未提供完整 URL（且未要求生成）时，停止并要求用户提供或更新参考，不猜测
+
+## References
+
+- BGM CDN 清单：`references/bgm-cdn.md`
+- SFX CDN 清单：`references/sfx-cdn.md`

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Game Audio"
+  short_description: "将已托管或 MCP 生成的 BGM/SFX 接入游戏配置与播放流程"
+  default_prompt: "请使用 $game-audio 为我的游戏选择或生成合适的背景音乐和音效，并接入现有配置与播放流程。"

package/dist/skills/zh-CN/game-audio/references/bgm-cdn.md

@@ -0,0 +1,123 @@
+# BGM CDN And URL Catalog
+
+This file is the authoritative source for hosted background-music routing. Read `../SKILL.md` first, then use this reference to compose final audio URLs for tracks stored under the BGM bucket path.
+
+## CDN Root
+
+Production public CDN root:
+
+```text
+http://game-asset.evomeme.com/
+```
+
+Use this root for every catalog entry.
+
+## Required Prefix
+
+All hosted background music objects live under:
+
+```text
+bgm/
+```
+
+## Final URL Shape
+
+```text
+{CDN root}bgm/{encoded filename}
+```
+
+- Keep the CDN root exactly as listed.
+- Keep the `bgm/` prefix exactly as listed.
+- The filename segment includes the extension such as `.mp3` or `.m4a`.
+- Encode the filename segment with UTF-8 percent-encoding when it contains non-ASCII or reserved characters.
+
+## Encoding Rule
+
+- Use the full stored filename, including extension, as the source string for `encodeURIComponent`.
+- Encode only the filename segment, not the entire URL.
+- Keep spaces encoded as `%20`.
+- Common examples:
+  - `–` -> `%E2%80%93`
+  - `（` -> `%EF%BC%88`
+  - `）` -> `%EF%BC%89`
+
+## Track Catalog
+
+Final URL = `http://game-asset.evomeme.com/bgm/` + filename fragment below.
+
+| Object key | Filename fragment |
+| --- | --- |
+| `2048.mp3` | `2048.mp3` |
+| `Arrows – Puzzle Escape（箭头逃脱）.mp3` | `Arrows%20%E2%80%93%20Puzzle%20Escape%EF%BC%88%E7%AE%AD%E5%A4%B4%E9%80%83%E8%84%B1%EF%BC%89.mp3` |
+| `Ballz 打砖块.mp3` | `Ballz%20%E6%89%93%E7%A0%96%E5%9D%97.mp3` |
+| `Block Blast! 方块消除1.mp3` | `Block%20Blast%21%20%E6%96%B9%E5%9D%97%E6%B6%88%E9%99%A41.mp3` |
+| `Block Blast! 方块消除2.mp3` | `Block%20Blast%21%20%E6%96%B9%E5%9D%97%E6%B6%88%E9%99%A42.mp3` |
+| `DOODLE JUMP2.mp3` | `DOODLE%20JUMP2.mp3` |
+| `Doodle Jump.mp3` | `Doodle%20Jump.mp3` |
+| `Flappy Bird1.mp3` | `Flappy%20Bird1.mp3` |
+| `Flappy Bird2.mp3` | `Flappy%20Bird2.mp3` |
+| `Vita Mahjong 麻将配对1.mp3` | `Vita%20Mahjong%20%E9%BA%BB%E5%B0%86%E9%85%8D%E5%AF%B91.mp3` |
+| `Vita Mahjong 麻将配对2.mp3` | `Vita%20Mahjong%20%E9%BA%BB%E5%B0%86%E9%85%8D%E5%AF%B92.mp3` |
+| `_疯狂的鸽子1.mp3` | `_%E7%96%AF%E7%8B%82%E7%9A%84%E9%B8%BD%E5%AD%901.mp3` |
+| `_疯狂的鸽子2.mp3` | `_%E7%96%AF%E7%8B%82%E7%9A%84%E9%B8%BD%E5%AD%902.mp3` |
+| `三消 _ 二合1.mp3` | `%E4%B8%89%E6%B6%88%20_%20%E4%BA%8C%E5%90%881.mp3` |
+| `三消 _ 二合2.mp3` | `%E4%B8%89%E6%B6%88%20_%20%E4%BA%8C%E5%90%882.mp3` |
+| `人格测试.mp3` | `%E4%BA%BA%E6%A0%BC%E6%B5%8B%E8%AF%95.mp3` |
+| `休闲小镇.mp3` | `%E4%BC%91%E9%97%B2%E5%B0%8F%E9%95%87.mp3` |
+| `休闲轻快.mp3` | `%E4%BC%91%E9%97%B2%E8%BD%BB%E5%BF%AB.mp3` |
+| `休闲拼图1.mp3` | `%E4%BC%91%E9%97%B2%E6%8B%BC%E5%9B%BE1.mp3` |
+| `休闲拼图2.mp3` | `%E4%BC%91%E9%97%B2%E6%8B%BC%E5%9B%BE2.mp3` |
+| `冰壶游戏.mp3` | `%E5%86%B0%E5%A3%B6%E6%B8%B8%E6%88%8F.mp3` |
+| `割绳子（Cut the Rope）1.mp3` | `%E5%89%B2%E7%BB%B3%E5%AD%90%EF%BC%88Cut%20the%20Rope%EF%BC%891.mp3` |
+| `割绳子（Cut the Rope）2.mp3` | `%E5%89%B2%E7%BB%B3%E5%AD%90%EF%BC%88Cut%20the%20Rope%EF%BC%892.mp3` |
+| `割草游戏1.mp3` | `%E5%89%B2%E8%8D%89%E6%B8%B8%E6%88%8F1.mp3` |
+| `割草游戏2.mp3` | `%E5%89%B2%E8%8D%89%E6%B8%B8%E6%88%8F2.mp3` |
+| `割草游戏3.mp3` | `%E5%89%B2%E8%8D%89%E6%B8%B8%E6%88%8F3.mp3` |
+| `华容道 _ 拼图1.mp3` | `%E5%8D%8E%E5%AE%B9%E9%81%93%20_%20%E6%8B%BC%E5%9B%BE1.mp3` |
+| `华容道 _ 拼图_2.mp3` | `%E5%8D%8E%E5%AE%B9%E9%81%93%20_%20%E6%8B%BC%E5%9B%BE_2.mp3` |
+| `发泄暴打.mp3` | `%E5%8F%91%E6%B3%84%E6%9A%B4%E6%89%93.mp3` |
+| `叠房子.mp3` | `%E5%8F%A0%E6%88%BF%E5%AD%90.mp3` |
+| `吃分避障.mp3` | `%E5%90%83%E5%88%86%E9%81%BF%E9%9A%9C.mp3` |
+| `合成大西瓜1.mp3` | `%E5%90%88%E6%88%90%E5%A4%A7%E8%A5%BF%E7%93%9C1.mp3` |
+| `合成大西瓜2.mp3` | `%E5%90%88%E6%88%90%E5%A4%A7%E8%A5%BF%E7%93%9C2.mp3` |
+| `哈基米南北绿豆.mp3` | `%E5%93%88%E5%9F%BA%E7%B1%B3%E5%8D%97%E5%8C%97%E7%BB%BF%E8%B1%86.mp3` |
+| `场景模拟对话1.mp3` | `%E5%9C%BA%E6%99%AF%E6%A8%A1%E6%8B%9F%E5%AF%B9%E8%AF%9D1.mp3` |
+| `场景模拟对话2.mp3` | `%E5%9C%BA%E6%99%AF%E6%A8%A1%E6%8B%9F%E5%AF%B9%E8%AF%9D2.mp3` |
+| `塔防.mp3` | `%E5%A1%94%E9%98%B2.mp3` |
+| `对抗类.mp3` | `%E5%AF%B9%E6%8A%97%E7%B1%BB.mp3` |
+| `奇幻冒险.m4a` | `%E5%A5%87%E5%B9%BB%E5%86%92%E9%99%A9.m4a` |
+| `愤怒的小鸟.mp3` | `%E6%84%A4%E6%80%92%E7%9A%84%E5%B0%8F%E9%B8%9F.mp3` |
+| `战斗.mp3` | `%E6%88%98%E6%96%97.mp3` |
+| `打地鼠.mp3` | `%E6%89%93%E5%9C%B0%E9%BC%A0.mp3` |
+| `搞笑.mp3` | `%E6%90%9E%E7%AC%91.mp3` |
+| `拧螺丝1.mp3` | `%E6%8B%A7%E8%9E%BA%E4%B8%9D1.mp3` |
+| `拧螺丝2.mp3` | `%E6%8B%A7%E8%9E%BA%E4%B8%9D2.mp3` |
+| `数值生存.mp3` | `%E6%95%B0%E5%80%BC%E7%94%9F%E5%AD%98.mp3` |
+| `数字门跑酷1.mp3` | `%E6%95%B0%E5%AD%97%E9%97%A8%E8%B7%91%E9%85%B71.mp3` |
+| `数字门跑酷2.mp3` | `%E6%95%B0%E5%AD%97%E9%97%A8%E8%B7%91%E9%85%B72.mp3` |
+| `是男人就下 100 层.mp3` | `%E6%98%AF%E7%94%B7%E4%BA%BA%E5%B0%B1%E4%B8%8B%20100%20%E5%B1%82.mp3` |
+| `是男人就下100层2.mp3` | `%E6%98%AF%E7%94%B7%E4%BA%BA%E5%B0%B1%E4%B8%8B100%E5%B1%822.mp3` |
+| `校准类.mp3` | `%E6%A0%A1%E5%87%86%E7%B1%BB.mp3` |
+| `横板过关.mp3` | `%E6%A8%AA%E6%9D%BF%E8%BF%87%E5%85%B3.mp3` |
+| `沙盒模拟类1.mp3` | `%E6%B2%99%E7%9B%92%E6%A8%A1%E6%8B%9F%E7%B1%BB1.mp3` |
+| `沙盒模拟类2.mp3` | `%E6%B2%99%E7%9B%92%E6%A8%A1%E6%8B%9F%E7%B1%BB2.mp3` |
+| `沙盒模拟类3.mp3` | `%E6%B2%99%E7%9B%92%E6%A8%A1%E6%8B%9F%E7%B1%BB3.mp3` |
+| `祖玛1.mp3` | `%E7%A5%96%E7%8E%9B1.mp3` |
+| `祖玛2.mp3` | `%E7%A5%96%E7%8E%9B2.mp3` |
+| `经营养成.mp3` | `%E7%BB%8F%E8%90%A5%E5%85%BB%E6%88%90.mp3` |
+| `经营养成2.mp3` | `%E7%BB%8F%E8%90%A5%E5%85%BB%E6%88%902.mp3` |
+| `背包堆叠（Stack_Backpack）.mp3` | `%E8%83%8C%E5%8C%85%E5%A0%86%E5%8F%A0%EF%BC%88Stack_Backpack%EF%BC%89.mp3` |
+| `节奏类（音游点击）.mp3` | `%E8%8A%82%E5%A5%8F%E7%B1%BB%EF%BC%88%E9%9F%B3%E6%B8%B8%E7%82%B9%E5%87%BB%EF%BC%89.mp3` |
+| `解绳游戏（Tangled Rope）1.mp3` | `%E8%A7%A3%E7%BB%B3%E6%B8%B8%E6%88%8F%EF%BC%88Tangled%20Rope%EF%BC%891.mp3` |
+| `解绳游戏（Tangled Rope）2.mp3` | `%E8%A7%A3%E7%BB%B3%E6%B8%B8%E6%88%8F%EF%BC%88Tangled%20Rope%EF%BC%892.mp3` |
+| `贪吃蛇.mp3` | `%E8%B4%AA%E5%90%83%E8%9B%87.mp3` |
+| `贪吃蛇2.mp3` | `%E8%B4%AA%E5%90%83%E8%9B%872.mp3` |
+| `跑酷避障.mp3` | `%E8%B7%91%E9%85%B7%E9%81%BF%E9%9A%9C.mp3` |
+| `跳一跳.mp3` | `%E8%B7%B3%E4%B8%80%E8%B7%B3.mp3` |
+| `跳一跳2.mp3` | `%E8%B7%B3%E4%B8%80%E8%B7%B32.mp3` |
+| `连击挑战1.mp3` | `%E8%BF%9E%E5%87%BB%E6%8C%91%E6%88%981.mp3` |
+| `连击挑战2.mp3` | `%E8%BF%9E%E5%87%BB%E6%8C%91%E6%88%982.mp3` |
+| `鉴别伪人.mp3` | `%E9%89%B4%E5%88%AB%E4%BC%AA%E4%BA%BA.mp3` |
+| `雷霆战机.mp3` | `%E9%9B%B7%E9%9C%86%E6%88%98%E6%9C%BA.mp3` |
+| `鬼抓人.mp3` | `%E9%AC%BC%E6%8A%93%E4%BA%BA.mp3` |
+| `黑洞（Tiles In Hole_ Black Hole）.mp3` | `%E9%BB%91%E6%B4%9E%EF%BC%88Tiles%20In%20Hole_%20Black%20Hole%EF%BC%89.mp3` |