evomeme 0.1.9 → 0.1.10-beta.13

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

@@ -0,0 +1,110 @@
+---
+name: game-scroll-generator
+description: 生成、编辑和优化横向卷轴地图图片资源，支持背景及可选中景、前景生成、逐层左右消缝和透明图层输出。生成卷轴地图、横向循环背景、视差滚动图层，或修补已有卷轴图的左右接缝时，必须使用此技能。解释两个 MCP 的实际流程、参数、文件产物及卷轴、视差、色键和消缝术语。
+---
+
+# 卷轴地图资源生成与编辑
+
+生成或编辑卷轴地图、横向循环背景、视差滚动图层时，必须使用本技能。它交付游戏场景的图片资源；滚动速度、方向、图层位置、碰撞和关卡数据由游戏工程或画布预览配置。
+
+| 工具 | 实际操作与产物 | 使用时机 |
+| --- | --- | --- |
+| `evomeme_generate_scroll_image`（卷轴场景生成） | 必定生成背景，可选生成中景、前景，每层请求 3024×1296；逐层可选左右消缝，中景/前景可自动去底色。最终提供 1～3 个图层文件，保留生成、消缝、色键的阶段文件。 | 从文字或参考图制作横向场景，或制作具有统一画风的多层视差背景。 |
+| `evomeme_eliminate_scroll_background_seam`（卷轴地图缝隙消除） | 对已有 3024×1296 图片进行一次 AI 左右接缝修补，保存并上传一张同尺寸新 PNG，保留源图。 | 已有卷轴背景、中景或前景，只需要改善水平循环接缝。 |
+
+正方形地块、上下左右平铺以及地形过渡图集使用 [瓦片地图资源生成与编辑](../game-tile-generator/SKILL.md)。普通单层插画和场景图使用 [图片素材生成与处理](../game-asset-image-generator/SKILL.md)。已有整图按语义拆层不是本工具的功能：这里的多图层是分别生成的图片。
+
+## 术语和范围
+
+- **卷轴图／横向循环背景**：横向移动的场景长图。循环使用时，将同一图片左右重复排列，移动出一端的内容从另一端接续。本工具固定请求宽 3024、高 1296 像素，不生成任意长度地图，也不保证上下可拼接。
+- **背景、中景、前景**：分别是远处的完整场景、中距离的独立景物、最靠近镜头的独立景物。它们是相同画布尺寸的独立图片，通过透明空白区域叠放，不是把三层横排在一张图里。
+- **视差滚动（parallax）**：不同远近的图层以不同速度移动，通常远景慢、近景快，从而产生深度感。工具生成可供叠放的资源，不会自动编写移动逻辑或输出动画视频。
+- **原生透明／alpha 通道**：模型直接输出透明区域；alpha 是像素的不透明程度，0 为全透明，完全不透明为最大值。透明区域可露出下方图层，与涂成白色不同。卷轴流程只允许 `asset-max` 请求原生透明。
+- **色键（color key）／去底色**：先在指定纯色底上生成景物，再按颜色相似度把底色像素变透明。本流程使用强度 80、Oklab 感知颜色空间（让颜色距离更接近人眼感受）及柔和边缘；处理全图相近颜色，不只处理与图片边缘连通的区域，也不开启去溢色。**去溢色**指压低主体边缘残留的底色偏色。底色出现在主体中也可能被删除，应选与主体明显不同的颜色。
+- **消缝／循环偏移／补全**：沿 X 轴循环偏移半张图，即移动 1512 像素，移出一侧的像素从另一侧进入；Y 轴不移动。原来的左右接缝来到中央，把中央竖向带设为透明，交给 AI 补全，再反向偏移。修补带约为图宽的 12.5%，即 378 像素。透明带是参考图上的待补区域标记，不表示最终图一定透明。
+- **卷轴消缝的范围**：当前实现保留 AI 返回的整张新图，然后复原偏移。即使提示词要求保留其他区域，也没有像瓦片工具那样在本地只合回修补带，其他景物可能随 AI 补全改变。使用后检查整图和左右接缝。
+
+## 工作区与参考图
+
+调用时显式传绝对路径 `workspace_dir`，例如 `D:/my-game`；省略时使用 MCP 进程当前目录。生成文件写入该工作区 `assets/`。
+
+`reference_ids` 和 `id` 使用相对于工作区根目录的图片路径，例如 `assets/references/forest.png`，不接受绝对路径、URL 或 Base64。用户附件或其他目录的图先定位实际文件，再复制到 `assets/`，使用不会覆盖原素材的名称；只有可访问链接时先下载。无法取得真实文件时说明缺少的参考图，不猜 ID。工作区内已有图和返回的 `asset_id` 可直接复用。
+
+## 卷轴场景生成
+
+| 参数 | 默认值／说明 |
+| --- | --- |
+| `prompt` | 必填且非空，描述背景主题、画风、配色、光照、水平构图和玩法留白。 |
+| `model` | `asset-pro`；可选 `asset-max`、`asset-lite`，三者均支持这里的 3024×1296 请求。 |
+| `reference_ids` | `[]`；Pro 最多 10 张，Max/Lite 在本工具最多 14 张。仅作为背景参考图。 |
+| `seam_elimination_enabled` | `false`；背景是否追加一次左右消缝。 |
+| `midground_enabled` / `foreground_enabled` | 均为 `false`；分别启用中景／前景。 |
+| `midground_prompt` / `foreground_prompt` | 对应层启用时必填非空描述，写该层景物、位置、疏密、遮挡关系，不重复完整背景。 |
+| `midground_transparent_background` / `foreground_transparent_background` | 均为 `false`；使用纯色底生成并自动色键。设 `true` 时必须选 Max，直接请求透明并跳过色键。 |
+| `midground_background_color` / `foreground_background_color` | 均为 `#ff00ff`；对应纯色底和色键颜色，支持 `#RGB`、`#RRGGBB`。原生透明时不使用该底色。 |
+| `midground_seam_elimination_enabled` / `foreground_seam_elimination_enabled` | 均为 `false`；对应层是否追加一次左右消缝。 |
+| `workspace_dir` | 工作区根目录，建议显式指定。 |
+
+不传 `size`、滚动速度或方向。默认只生成一层背景且不追加消缝。用户要求循环时可开启对应层消缝，不能把默认生成成功视为视觉上已经无缝。
+
+实际顺序：背景生成 → 可选背景消缝 → 以最终背景作参考，并行处理中景和前景。每个启用的叠加层内部依次生成 → 可选消缝 → 非原生透明时自动色键。参考图不会直接分别传给中景和前景；二者也不互相作为参考。MCP 和画布调用同一个原有 `executeScrollImage` 任务函数，复用已有 image 函数，不需要 agent 逐步调用其他 MCP。不要为移植工具擅自修改 image 实现或内置提示词。
+
+正常 AI 次数 = 启用层数（含背景）+ 开启消缝的层数，因此为 1～6 次，不含服务端重试。色键是本地处理，不增加 AI 次数。所有层和消缝都启用、且两个叠加层走色键时，共保存 8 个阶段文件，最终使用其中 3 个。只要启用非原生透明的中景/前景，就会自动色键；没有单独关闭自动色键的参数。
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "prompt": "横版森林关卡，远处蓝绿群山与薄雾，统一柔和光照，手绘风格，中央玩法区域清晰，无角色文字",
+  "model": "asset-pro",
+  "seam_elimination_enabled": true,
+  "midground_enabled": true,
+  "midground_prompt": "中距离树干和稀疏树冠，保持中央通路开阔，与背景配色光照一致",
+  "midground_background_color": "#ff00ff",
+  "midground_seam_elimination_enabled": true,
+  "foreground_enabled": true,
+  "foreground_prompt": "画面下沿少量近处草叶和岩石，上方大面积留空，避免遮挡中央玩法区域",
+  "foreground_background_color": "#ff00ff",
+  "foreground_seam_elimination_enabled": true
+}
+```
+
+基础生成文件以实际 `mime_type` 为准；消缝和色键产物为 PNG。色键后的最终透明 PNG 只保存本地，没有自动上传；需要远端素材 URL 时，用该层最终 `local_path` 调用 `evomeme_upload_game_asset`。不要使用该层 `base` 或 `seam` 的云端 URL 代替色键后的最终图。
+
+## 已有卷轴地图消缝
+
+| 参数 | 默认值／说明 |
+| --- | --- |
+| `id` | 必填，已有 3024×1296 图片的工作区 ID。尺寸从文件读取，不接受 `size`，不会自动缩放。 |
+| `model` | 默认 `asset-pro`；可选 Max、Lite。请求透明时仅 Max。 |
+| `prompt` | 可选，补充景物连续性、画风和保留要求。 |
+| `has_background` | 默认 `false`，不指定空白区域的背景约束；不是“选择背景图层”。需要保持纯色底或透明空白区域时设 `true`。 |
+| `transparent_background` | 默认 `false`，仅 `has_background=true` 时生效。`true` 请求透明背景并要求 Max；`false` 保持下方指定的纯色底。 |
+| `background_color` | 默认 `#ff00ff`，仅上项为 `false` 且 `has_background=true` 时用于约束纯色底；支持 `#RGB` 或 `#RRGGBB`。 |
+| `workspace_dir` | 工作区根目录，建议显式指定。 |
+
+普通不透明背景：仅提供 `id`、工作区及可选提示词即可。已有透明中景/前景：同时传 `has_background=true`、`transparent_background=true`、`model=asset-max`。已有纯色底图层：传 `has_background=true` 和实际底色；消缝后若要透明，再对返回的 ID 使用 `evomeme_color_key`，不会自动去底色。
+
+```json
+{
+  "id": "assets/foreground-transparent.png",
+  "workspace_dir": "D:/my-game",
+  "model": "asset-max",
+  "prompt": "让左右边缘的草叶与岩石自然接续，保持留白和原有画风",
+  "has_background": true,
+  "transparent_background": true
+}
+```
+
+流程为水平偏移 → 上传中央透明带参考图 → 一次 AI 补全 → 整张输出复原偏移 → 保存并上传最终 PNG。交付一张新图，源图保留。临时参考图和原始补全图不计入交付文件。最终 `asset_url` / `tos_url` 对应复原后的 PNG。透明配置是请求约束，不是额外抠图步骤。
+
+## 返回值、使用与失败处理
+
+MCP 返回文本元数据，不返回图片字节或 Base64。`operation_id` 标识本地步骤，`job_id` 标识远端 AI 请求；色键没有远端 AI 请求 ID。`status=SUCCEEDED` 表示处理完成，视觉质量仍需检查。独立消缝另有 `task_id`；场景生成复用原有返回值，不承诺该字段。
+
+场景生成返回 JSON 文本形式的 `background`、可选 `midground` / `foreground`。每层的 `id` / `asset_id`、`local_path`、`mime_type` 和适用的云端 URL 指向该层最终文件；`base` 是原始生成图，`color_key` 是可选色键结果。顶层图片信息始终对应最终背景，不能当作所有图层的合成图。原有场景结果没有 `outputs`、独立 `seam` 或 `ai_generation_count` 字段，也不自动读取实际宽高；需要中间文件或处理记录时查看工作区任务记录。
+
+独立消缝的 `outputs` 只有新 PNG，另有 `source_id`、模型、尺寸和背景约束字段。两类结果的 `transform` 记录 `offset_x`、`offset_y`、`mask_width`、`offset_restored`；场景内的 `feather=0` 表示没有本地羽化合成修补带，与色键边缘柔化不是同一处理。
+
+使用各层最终图片，按背景 → 中景 → 前景叠放，在引擎中设置各层的水平重复和滚动速度。检查两份图片左右拼接处、地平线和物体接续，同时检查透明区域、底色残留、主体误删以及遮挡玩法的情况。画布已有卷轴预览可用于观察速度和方向；这两个 MCP 不生成预览页面。
+
+失败时查看 `isError: true` 的具体原因，不覆盖原图。前一阶段或并行兄弟图层已经完成的产物及记录会保留；一条分支失败时会等待另一分支结束后报告失败。通过工作区任务记录或画布找到已完成素材，再决定补做消缝或色键。客户端等待中断时先查原任务状态，避免直接重提整套场景造成重复生成。

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "卷轴地图资源生成与编辑"
+  short_description: "生成横向卷轴背景与视差图层，修补已有卷轴接缝并输出透明图层"
+  default_prompt: "使用 $game-scroll-generator 生成、编辑或优化卷轴地图图片资源，按需制作背景、中景、前景，或修补已有卷轴图的左右接缝。"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/zh-CN/game-test/references/checklists/playtest-qa.md

@@ -0,0 +1,12 @@
+# Playtest QA Checklist
+
+- Start from a clean load.
+- Play through the main loop for at least 2 minutes.
+- Verify controls, camera, objective feedback, failure/retry, and progression.
+- Try rapid input changes and edge movement against arena boundaries.
+- Trigger collisions from multiple angles.
+- Pause, restart, resize, and refocus the tab if supported.
+- Check audio unlock and volume behavior after the first gesture.
+- Watch for unreadable moments, camera occlusion, jitter, and missed feedback.
+- Capture screenshots for desktop and mobile.
+- Record bugs as reproduction steps with expected and actual behavior.

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

@@ -0,0 +1,151 @@
+---
+name: game-tile-generator
+description: 主要用于瓦片地图资源的生成、编辑与优化。生成瓦片地图或无缝砖块时必须使用此技能；创建地形纹理、两种地形的过渡地块集，或修补已有地块的平铺接缝时也使用。通过 MCP 生成正方形地块、4×4过渡图集或消缝后的PNG，说明产物、使用场景和瓦片、平铺、图集、消缝等术语。
+---
+
+# 瓦片地图资源生成、编辑与优化
+
+生成瓦片地图或无缝砖块时，必须使用本技能。先判断需要生成单张可平铺纹理、制作两种地形的过渡地块集，还是对已有地块消缝，再选择对应工具。制作瓦片地图时，本技能负责地形图片资源的生成与优化；地图格子排布、碰撞和自动铺图规则在取得素材后按目标引擎实现。
+
+## 选择工具
+
+| 工具 | 具体做什么、生成什么 | 什么时候用 |
+| --- | --- | --- |
+| `evomeme_generate_seamless_tile`（无缝地块生成） | 用提示词及可选参考图生成一张正方形地形纹理；可追加一次 AI 消缝，保留基础图和最终修补图。 | 需要一块能向上下左右重复铺满的草地、石地、沙地、墙面等纹理。 |
+| `evomeme_generate_tile_transition_atlas`（无缝地块集生成／地块过渡图集生成） | 用两张不同的地形图，经过四次方向边缘生成和一次图集内部边界补全，合成一张固定 4×4、16 格的 PNG。 | 已有两种地形，需要它们之间的直边、转角等过渡地块，例如草地与泥地、沙地与石地相接。 |
+| `evomeme_eliminate_tile_seams`（瓦片砖块缝隙消除） | 直接对已有正方形瓦片砖块执行循环偏移、一次 AI 补全、局部合成和偏移复原；保留源图，新增一张同尺寸 PNG 并上传。 | 已有单张瓦片纹理平铺后出现上下或左右接缝，需要保留现有地块并改善拼接；卷轴地图的左右循环接缝由独立工具处理。 |
+
+三个工具共用画布的任务和图片处理流程，MCP 等待任务完成后返回文本元数据，图片保存到工作区 `assets/`。普通插画、角色、图标和整张场景背景使用 [游戏图片素材生成与处理](../game-asset-image-generator/SKILL.md)。
+
+## 术语与产物边界
+
+横向卷轴地图的背景、中景、前景及左右接缝修补使用 [卷轴地图资源生成与编辑](../game-scroll-generator/SKILL.md)。卷轴消缝工具为 `evomeme_eliminate_scroll_background_seam`，与本技能的正方形瓦片砖块消缝区分。
+
+- **瓦片／地块／砖块（tile）**：地图网格中的一个图片单元，不限定为建筑砖头。这里的单格是正方形，例如 128×128 像素；贴到地图上时可以缩放显示，图片像素尺寸不等于游戏中的物理大小。
+- **无缝／平铺（seamless / tiling）**：把图片复制到相邻位置后，边界处的纹理、颜色和形状应连续。单张地块需左右、上下边缘都能衔接；过渡地块集需选择边缘地形排列匹配的格子相接，不能把任意两个格子随意拼在一起。
+- **消缝（seam elimination）**：先将基础图水平、垂直循环偏移半张图，让原来四周的接缝移到中央；标记中央十字修补区，由 AI 补全，只把修补区合回原图，再反向偏移恢复位置。循环偏移指移出一侧的像素从另一侧进入，不裁掉内容。这是一次额外生图，不是抠图、模糊边缘或缩小图片。
+- **地块集（tileset）与图集（atlas）**：地块集是一组供地图复用的图片单元；图集把这些单元装在一张大图里。本工具将 16 格放在一张 PNG 内。`tile_size=128` 表示每格 128×128，整图为 512×512；不是 16 个独立文件。
+- **地形 0／地形 1**：分别是 `reference_ids[0]` 和 `reference_ids[1]`，例如草地和泥地。数字只表示输入次序；交换次序会交换模板中的地形分配，不表示海拔、图层深度或优先级。
+- **过渡（transition）**：在同一地块内让两种地形沿固定边界自然相接。直线和圆角等形状由内置模板决定，提示词补充交界处的材质、颜色与画风，不改变图集格数或排列。
+- **边缘协议（edge protocol）**：供相邻格子共用的像素带，约定边缘上哪部分属于哪种地形。`00`、`11` 表示同种地形；`01`、`10` 表示两种地形按相反次序衔接。水平和垂直各有四种，共八种；四种混合协议经 AI 生成，四种纯地形协议直接从原图提取。协议是内部拼接数据，不是联网协议或额外八张交付图。
+- **蒙版（mask）与边界补全（inpainting）**：蒙版标记哪些像素可以替换。地块集上传给 AI 的待补区域使用不透明洋红色 `#FF00FF`；本地按独立几何蒙版合成，仅替换指定区域。第五次生图修补图集内部的地形交界，保留已有边缘协议；不会把原图里所有洋红色都删掉。单张地块消缝使用的是透明十字修补区，与地块集的洋红色标记不同。
+- **瓦片地图（tilemap）与自动铺图（autotile）**：瓦片地图记录每个网格位置放哪块地砖，通过重复使用少量图片构成场景；自动铺图按邻居地形选择合适格子。这三个 MCP 工具交付图片，不直接输出地图 JSON、碰撞数据、导航信息或引擎自动铺图规则。
+
+## 工作区与参考图
+
+显式传入工作区根目录绝对路径 `workspace_dir`，例如 `D:/my-game`；省略时使用 MCP 进程当前目录。参考图必须是该工作区 `assets/` 内可读取的图片，ID 是相对于工作区根目录的路径，例如 `assets/terrain/grass.png`，不是绝对路径、URL 或 Base64。
+
+用户附件或其他目录中的图片先定位实际文件，再复制到工作区 `assets/`，使用不会覆盖已有素材的文件名；只有可访问链接时先下载。无法取得真实文件时说明缺少哪张参考图，不猜测 ID。已有生成结果直接复用 `asset_id`。无参考图的单张地块生成可以直接开始。
+
+地块集需要**恰好两张不同的地形图**，优先使用视角、光照、比例与画风一致且本身可平铺的正方形图。输入会被缩放到正方形，非正方形图片可能拉伸；角色图、带文字或大主体的场景图通常不适合作地形底纹。只有一种地形时先取得第二种；不能把同一个 ID 填两次。用户要从零制作两种地形时，先分别调用单张地块工具，再将返回的两个 `asset_id` 按顺序传给地块集。
+
+## 无缝地块 MCP
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `prompt` | 是 | 非空地形描述，写材质、颜色、纹理尺度、俯视视角和画风。底层补充平铺要求。 |
+| `model` | 否 | 默认 `asset-pro`；可选 `asset-max`、`asset-lite`。 |
+| `size` | 否 | 请求尺寸，仅 `1024x1024` 或 `2048x2048`；默认前者。`asset-lite` 必须显式选 `2048x2048`。 |
+| `reference_ids` | 否 | 默认 `[]`。Pro 最多 10 张，Max/Lite 在此工具中最多 14 张。 |
+| `seam_elimination_enabled` | 否 | 默认 `false`。开启后多一次 AI 生图，执行上述偏移、补全和复原流程。 |
+| `workspace_dir` | 否 | 工作区根目录绝对路径；调用时显式指定。 |
+
+```json
+{
+  "prompt": "正俯视森林草地，细密深绿草叶与少量苔藓，柔和均匀光照，无大石块和文字，手绘游戏风格",
+  "model": "asset-pro",
+  "size": "1024x1024",
+  "seam_elimination_enabled": true,
+  "workspace_dir": "D:/my-game"
+}
+```
+
+关闭消缝时：一次 AI 生图，保存一张基础图，`base` 与最终图片指向同一文件。基础图沿用服务端图片格式，以返回的 `mime_type` 为准，不承诺一律 PNG。
+
+开启消缝时：正常共两次 AI 生图，保存基础图和最终修补 PNG 两张图；临时修补参考图不属于交付产物。最终 PNG 会上传，顶层 `asset_url` / `tos_url` 对应**合成并复原后的图片**。`outputs` 按基础图、修补图排列，顶层 `asset_id` / `local_path` 指向修补图。
+
+该工具不接受 `background`、`transparent_background` 等参数，也不自动抠图。默认流程依靠提示词生成可平铺纹理；开启消缝增加修补步骤，仍需检查实际接缝，不能把任务成功当作视觉效果合格。
+
+## 瓦片砖块缝隙消除 MCP
+
+用户已经有地块、只要求修补平铺接缝时，调用 `evomeme_eliminate_tile_seams`。不要为此调用 `evomeme_generate_seamless_tile` 重新生成基础图；刚完成的新图也可以直接复用返回的 `asset_id`。
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `id` | 是 | 已有单张正方形地块的工作区图片 ID，例如 `assets/terrain/grass.png`。准备方法同上。 |
+| `model` | 否 | 默认 `asset-pro`；Pro/Max 支持 1024×1024 和 2048×2048，Lite 仅支持 2048×2048。 |
+| `prompt` | 否 | 补充纹理衔接、材质、颜色和画风要求。底层自动添加消缝及锁定非修补区域的说明。 |
+| `workspace_dir` | 否 | 当前工作区根目录绝对路径，调用时显式指定。 |
+
+```json
+{
+  "id": "assets/terrain/grass.png",
+  "model": "asset-pro",
+  "prompt": "保留原有草叶大小、深绿色调和手绘质感，使上下左右平铺边缘自然连续",
+  "workspace_dir": "D:/my-game"
+}
+```
+
+工具从源文件读取尺寸，当前只接受 **1024×1024 或 2048×2048**。不传 `size`、`reference_ids`、`seam_elimination_enabled` 或背景处理参数。非正方形、其他尺寸，以及 Lite 搭配 1024×1024 都会报错；工具不会自动拉伸或放大源图来绕过限制。
+
+实际流程为：循环偏移半张图 → 构造中央透明十字修补参考图并上传 → 一次 AI 补全 → 只合回修补区域 → 复原偏移 → 保存并上传新 PNG。源图保留，交付一张与源图尺寸相同的修补 PNG；临时参考图和模型原始补全图不作为交付产物。`local_path` 与 `asset_url` / `tos_url` 指向最终合成复原的图片。
+
+结果除通用字段外包含 `source_id`（被修补的源图 ID）、`model`、`size`、`width`、`height`、`job_id`，以及 `transform` 中的偏移量、修补带宽度和 `offset_restored=true`。`outputs` 只包含新生成的一张 PNG，不包含原图。后续制作地块集时使用修补结果的 `asset_id`。
+
+它针对**单张地块的四周平铺接缝**，不会逐格修复一张 4×4 图集的内部接缝，也不是横向卷轴背景消缝。需要整套地形过渡时使用地块集生成工具。独立消缝与生成工具的附加消缝复用同一处理流程；已经开启附加消缝并通过目视检查时，不需要再重复消缝。
+
+## 无缝地块集 MCP
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `reference_ids` | 是 | 两张不同的工作区图片 ID，严格按 `[地形0, 地形1]` 排列。 |
+| `tile_size` | 否 | 单格边长，8～2048 的整数，默认 128；整图宽高均为它的四倍。 |
+| `model` | 否 | 默认 `asset-pro`。Pro/Max 支持全部单格尺寸；Lite 仅支持 1025～2048，原因见下文。 |
+| `prompt` | 否 | 补充交界材质、融合方式和画风。省略或空白时，内部使用“地块1逐渐变化为地块2”的默认描述。 |
+| `workspace_dir` | 否 | 工作区根目录绝对路径；调用时显式指定。 |
+
+```json
+{
+  "reference_ids": ["assets/terrain/grass.png", "assets/terrain/dirt.png"],
+  "tile_size": 128,
+  "model": "asset-pro",
+  "prompt": "草叶沿泥地边缘自然稀疏，保留相同的俯视角度、光照和手绘风格",
+  "workspace_dir": "D:/my-game"
+}
+```
+
+正常流程固定五次 AI 生图：四种方向混合协议并行生成 → 提取并复用八种边缘协议 → 按固定模板本地拼合 → 第五次生图补全内部边界 → 合回并保存最终 PNG。五次生成不等于五张交付图；中间协议和补全图是临时文件，完成或失败后清理。最终只交付一张 `assets/tile-transition-atlas-…png`，不自动拆格，也不自动上传最终图；需要远端 URL 时再使用 `evomeme_upload_game_asset`。生成期间会上传内部参考图供 AI 使用。
+
+内部 AI 请求尺寸与最终尺寸不同：`tile_size ≤ 1024` 时协议生成使用 1024×1024，否则用 2048×2048；整图边界补全在最终边长 ≤ 1024 时使用 1024×1024，否则用 2048×2048，随后缩放合回目标图。Lite 不支持 1024×1024，因此当前共享流程仅允许 Lite 搭配 `tile_size > 1024`，不支持默认 128。通常保留默认 Pro 即可；不要为了绕过模型限制擅自放大用户要的单格尺寸。
+
+图集为四行四列、无外边距和格间距。按行优先编号时，自左至右、自上至下为：
+
+| | 第 1 列 | 第 2 列 | 第 3 列 | 第 4 列 |
+| --- | --- | --- | --- | --- |
+| 第 1 行 | 0 | 1 | 2 | 3 |
+| 第 2 行 | 4 | 5 | 6 | 7 |
+| 第 3 行 | 8 | 9 | 10 | 11 |
+| 第 4 行 | 12 | 13 | 14 | 15 |
+
+这是图集索引，不是引擎自动铺图的位掩码编号。按 `tile_size × tile_size` 从对应格子读取纹理，接入目标引擎时根据实际地形边缘建立规则；不宣称它直接符合某个引擎的自动铺图排列。
+
+## 返回值、检查与失败处理
+
+成功时返回 `status: SUCCEEDED`、`task_id`、`operation_id`、最终 `asset_id`、`local_path`、`mime_type` 和 JSON 文本形式的 `outputs`。`task_id` 标识整条流程，`operation_id` 标识最终图片对应的本地步骤，`job_id`（适用时）标识远端 AI 请求。`outputs` 列出实际保存的产物及名称、类型和适用的尺寸、URL；MCP 不附带图片字节或 Base64。
+
+单张地块另有 `base` 和 `seam_elimination_enabled`；开启消缝时 `transform` 记录 `offset_x` / `offset_y`（循环偏移量）、`mask_width`（修补带宽度）、`feather`（羽化混合宽度，当前为 0）和 `offset_restored`（是否已复原）。不要把 `base` 当成开启消缝后的最终结果。
+
+地块集另有 `tile_size`、`width`、`height`、`columns=4`、`rows=4`，以及：
+
+| 字段 | 含义 |
+| --- | --- |
+| `working_tile_size` | 方向协议的 AI 工作边长，1024 或 2048。 |
+| `atlas_generation_size` | 整图边界补全的 AI 工作边长，1024 或 2048。 |
+| `protocol_mask_width` | 在目标单格尺寸下共用的边缘像素带总宽度，包含接缝两侧。 |
+| `generated_protocol_count=4` / `protocol_count=8` | AI 生成的混合协议数／含纯地形协议的总数。 |
+| `ai_generation_count=5` | 正常流程的生成阶段数，不表示交付文件数量或重试次数。 |
+| `boundary_completion=true` | 已执行内部边界补全步骤，不是视觉验收标记。 |
+
+查看实际文件：单张地块用至少 2×2 平铺检查左右、上下及四角接点；地块集检查 4×4 布局、像素尺寸、地形次序和匹配边缘的拼接效果。图集会拒绝修补区域残留透明、半透明或纯洋红色的结果，但不能自动识别所有黑块、纹理错位或画风问题。
+
+失败时读取 `isError: true` 的具体错误，保留输入图。单张地块生成的第二步失败时，已经保存的基础图仍保留；通过工作区任务记录或画布找到它，确认原任务状态后，可将基础图 ID 传给独立消缝工具。查询中断时先检查原任务状态，避免盲目重提交；图集重调可能重新执行五次生图。消缝后仍需检查平铺效果，任务成功不等于接缝视觉验收通过。

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "瓦片地图资源生成与编辑"
+  short_description: "生成与优化瓦片地图资源，支持无缝砖块、过渡地块集和已有地块消缝"
+  default_prompt: "使用 $game-tile-generator 生成、编辑或优化瓦片地图资源，根据需求生成无缝砖块、过渡地块集或修补已有地块接缝。"
+
+policy:
+  allow_implicit_invocation: true

package/{skills → dist/skills/zh-CN}/game-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: game-ui
-description: 为游戏设计克制、清晰且具有类型感的 HUD、菜单、弹窗、触控区域、安全区和 UI 动效，并直接调用当前环境中的生图工具交付不同界面的 UI 概念图及其设计理念。当游戏需要确定或调整 UI 风格、信息层级、界面布局、交互反馈、移动端适配，或需要为开始、游玩、暂停、设置、胜负、结算和选择等状态生成 UI 概念图时使用。
+description: 为游戏设计克制、清晰且具有类型感的 HUD、菜单、弹窗、触控区域、安全区和 UI 动效，并直接调用当前环境中的生图工具交付不同界面的 UI 概念图及其设计理念。当游戏需要确定或调整 UI 风格、信息层级、界面布局、交互反馈、移动端适配，或需要为开始、游玩、暂停、设置、胜负、结算和选择等状态生成 UI 概念图时使用。面向 evomeme平台的游戏必须同时阅读并遵守 evomeme-ui。
 ---
 
 # 游戏 UI 设计
@@ -9,6 +9,12 @@ description: 为游戏设计克制、清晰且具有类型感的 HUD、菜单、
 
 根据游戏玩法、美术方向和目标设备完成 UI 设计，并为不同界面生成能够表现最终游戏效果的概念图。概念图应同时体现信息层级、操作意图、画面构图和统一的视觉语言。
 
+## evomeme平台前置要求
+
+如果开发的游戏要在 evomeme平台运行、上线或发布，必须在 UI 设计、概念图生成或自适应实现前阅读并遵守 [`evomeme-ui`](../evomeme-ui/SKILL.md)。以宿主已经分配的 WebView 容器为画幅，不按手机整屏或固定比例设计，不再次扣除 App 栏位及手机安全区。
+
+evomeme游戏的尺寸来源、安全区处理与适配验收以 `evomeme-ui` 为准。本技能及通用检查表中的移动端安全区建议不得导致重复扣减；其他平台继续按其实际宿主约束设计。
+
 ## 核心设计宗旨
 
 1. **少即是多**：让每个 UI 元素服务于玩家当前的判断、操作或反馈理解。
@@ -26,6 +32,7 @@ description: 为游戏设计克制、清晰且具有类型感的 HUD、菜单、
 
 - 核心玩法与玩家在每个状态下需要作出的决定；
 - 目标设备、横竖屏、画面比例和安全区；
+- 是否在 evomeme平台运行或发布；若是，必须先完成上方 `evomeme-ui` 前置阅读，并使用其中的游戏容器测试尺寸；
 - 键盘、鼠标、触控或原生输入方式；
 - 游戏美术风格、题材、气氛和已有视觉资产；
 - 需要设计的游戏状态及每个状态的主要行动。
@@ -162,6 +169,7 @@ description: 为游戏设计克制、清晰且具有类型感的 HUD、菜单、
 
 ## Reference Routing
 
+- 为 evomeme平台游戏设计或适配 UI 时，必须先读取并遵守 [`evomeme-ui`](../evomeme-ui/SKILL.md)。
 - 设计 HUD、菜单、覆盖层、触控控件和响应式布局时，读取 [`references/ui-patterns.md`](references/ui-patterns.md)。
 - 检查整体游戏感与界面质量时，读取 [`references/checklists/game-ui-quality.md`](references/checklists/game-ui-quality.md)。
 - 检查 HUD 信息层级和动态可读性时，读取 [`references/checklists/hud-readability.md`](references/checklists/hud-readability.md)。

package/dist/skills/zh-CN/game-ui/references/checklists/game-ui-quality.md

@@ -0,0 +1,14 @@
+# Game UI Quality Checklist
+
+- The first screen is the playable game or a deliberate modal state, not a landing page.
+- HUD hierarchy matches gameplay priority: survival/status, objective, feedback, secondary flavor.
+- UI visual language matches the game's genre, world materials, color, and motion.
+- Menus include expected states: pause, resume, restart, settings, win/lose when relevant.
+- Buttons and controls have stable dimensions plus hover, pressed, focus, and disabled states.
+- Icons are used for compact tool/actions when recognizable; ambiguous icons have labels or tooltips.
+- UI does not use nested cards, marketing-page layout, or generic dashboard styling.
+- UI does not block player, threats, goals, interactables, or near-future path unless intentionally modal.
+- Dynamic values such as score, time, health, combo, and ammo do not shift layout.
+- Reduced-motion and flash risk is considered for intense UI animation or damage feedback.
+- UI state is driven by the game state model and does not duplicate simulation rules.
+- Desktop and mobile screenshots show coherent composition and no clipped or overlapping controls.

package/dist/skills/zh-CN/game-ui/references/checklists/hud-readability.md

@@ -0,0 +1,12 @@
+# HUD Readability Checklist
+
+- Player health/status is readable during normal movement and high-action moments.
+- Objective/progress information is visible without competing with threats or pickups.
+- Text contrast remains legible over bright, dark, and moving scene backgrounds.
+- Critical status changes have at least two feedback channels when useful: shape, color, motion, sound, or text.
+- Meters, timers, and counters have fixed-width or stable containers.
+- HUD placement avoids the player focal area and likely spawn/threat lanes.
+- HUD scale is appropriate for desktop, laptop, and mobile viewports.
+- Touch controls and HUD elements do not overlap each other.
+- UI transitions do not delay input response or hide the next player decision.
+- Screenshot review confirms HUD readability before and after interaction.

package/dist/skills/zh-CN/game-ui/references/checklists/mobile-input.md

@@ -0,0 +1,12 @@
+# Mobile Input Checklist
+
+- Include `<meta name="viewport" content="width=device-width, initial-scale=1.0">`.
+- Set canvas and touch overlays to `touch-action: none` only where needed.
+- Use Pointer Events when possible.
+- Keep controls reachable with thumbs and away from safe-area edges.
+- Avoid tiny text or buttons below practical touch size.
+- Verify portrait and landscape if both are supported.
+- Check high-DPR canvas scaling and cap DPR if performance suffers.
+- Prevent page scroll/zoom gestures from stealing gameplay input.
+- Test virtual joystick/button release paths when the pointer leaves the control.
+- Verify with Playwright mobile emulation and real hardware when available.

package/dist/skills/zh-CN/game-ui/references/checklists/responsive-ui-fit.md

@@ -0,0 +1,12 @@
+# Responsive UI Fit Checklist
+
+- Desktop, laptop, narrow, and mobile viewports have been checked.
+- Safe-area padding is applied for mobile edges and notches when controls sit near edges.
+- No text clips, overflows, overlaps, or becomes unreadably small.
+- Long labels wrap or compress intentionally without breaking button height.
+- Controls keep stable hit targets and do not shift during score/time/state changes.
+- Layout uses grid/flex/container-aware constraints instead of viewport-only guesses where practical.
+- Menu content remains reachable without hidden offscreen controls.
+- Touch controls are large enough, separated enough, and do not trigger page scroll.
+- Canvas resizing does not desynchronize HUD placement from gameplay framing.
+- Screenshots or Playwright artifacts prove fit at the tested sizes.

package/dist/skills/zh-CN/game-ui/references/ui-patterns.md

@@ -0,0 +1,140 @@
+# Game UI Patterns
+
+Use this when designing HUDs, menus, overlays, pause/fail/win states, touch controls, typography, responsive layout, and UI/world cohesion.
+
+## UI Principles
+
+- Build the game interface, not a web dashboard.
+- Prioritize gameplay hierarchy: survival/status, objective/progress, immediate feedback, then flavor.
+- Use meters, icons, reticles, badges, alert strips, cooldown rings, inventory slots, minimaps, diegetic labels, and compact clusters before generic stat cards.
+- Keep UI outside the play path and away from threats, pickups, the player, and the next decision.
+- UI should reinforce the world art direction through material cues, color roles, icon shapes, and motion language.
+- Do not use visible text to explain obvious controls when an icon, affordance, or direct interaction can do the job.
+
+## Required States
+
+Inventory states before designing:
+
+- Gameplay HUD.
+- Pause/resume.
+- Settings or audio/accessibility controls when useful.
+- Fail/retry.
+- Win/milestone/level complete when relevant.
+- Loading/empty/error when async assets exist.
+- Mobile/touch controls when target includes mobile.
+- Debug/tuning UI gated separately from player UI.
+
+Premium games should not have only one HUD state.
+
+## HUD Composition
+
+Use intentional zones:
+
+- Top or top-left: objective, wave, distance, timer, route/progress.
+- Top or top-right: score, currency, combo, inventory, pause.
+- Bottom left/right: touch movement/action controls when needed.
+- Center top or near player: short event banners, combo, warnings.
+- Near-world labels: diegetic prompts, target markers, offscreen indicators.
+
+Rules:
+
+- Use fixed-width numeric containers for score, timer, ammo, speed, health, and best values.
+- Use icons plus short labels for unfamiliar resources.
+- Use meter fills for quantities the player must read quickly.
+- Use alert colors consistently: danger, reward, shield, boost, objective, disabled.
+- Animate state changes briefly: count-up, meter fill, pulse, slide/fade, snap, ring cooldown.
+- Do not stack multiple large banners over the play path.
+
+## Menus And Overlays
+
+Pause/fail/win overlays should support quick action:
+
+- Primary action first: resume, retry, continue, next.
+- Secondary actions: settings, quit, restart, level select.
+- Avoid marketing-page hero layouts inside a game.
+- Keep menu panels stable and readable across desktop/mobile.
+- Use icon buttons for pause, sound, restart, fullscreen, settings when familiar.
+- Provide focus/hover/pressed/disabled states.
+- Gate debug panels behind a dev flag or query param.
+
+## Touch Controls
+
+When mobile is in scope:
+
+- Use pointer events where possible.
+- Ensure controls emit the same game intents as keyboard/mouse.
+- Handle `pointerup`, `pointercancel`, `lostpointercapture`, blur, and visibility change.
+- Use safe-area insets.
+- Avoid controls overlapping HUD warnings or the play path.
+- Keep touch targets at least roughly 44 CSS pixels where practical.
+- Separate adjacent controls enough to prevent accidental presses.
+- Use `touch-action` to prevent unwanted page scrolling only in control regions or the game surface.
+
+## Responsive Constraints
+
+- Define stable dimensions with CSS variables, `clamp`, grid tracks, fixed icon slots, and fixed-width numbers.
+- Present a fixed-aspect game stage as the sole visual subject and maximize it within the viewport; keep extra desktop space as passive page background.
+- Do not scale text purely with viewport width.
+- Avoid negative letter spacing.
+- Check desktop, laptop, tablet/narrow, and phone viewports.
+- Test longest likely values: high score, long labels, multi-digit timers, localized-ish text if relevant.
+- No clipped text, overlapping controls, unreadably small labels, or layout shift from changing values.
+- Menus must remain reachable without offscreen controls.
+
+## Visual Style
+
+- Match the genre: arcade racers need speed/status readability; fighters need health/round/impact hierarchy; exploration games need inventory/objective clarity.
+- Prefer restrained panels with meaningful geometry, borders, ticks, glow accents, and material cues over nested cards.
+- Use a limited status palette plus neutral surfaces.
+- Avoid one-note purple/blue gradient UI unless it is strongly justified by the game world.
+- Connect UI motifs to world decals, faction marks, vehicle panels, pickups, or hazards.
+
+## 2D Asset Sourcing
+
+Prefer procedural/CSS/canvas UI art from this skill when hand-coded techniques are enough. When external 2D is needed:
+
+- User-supplied PNG/JPG/WebP wired via config or `<img>`/canvas textures.
+- Remote MCP `evomeme_generate_game_image` when available.
+- Procedural canvas exports saved under `assets/ui/` or `assets/textures/`.
+
+Use cases:
+
+- Faction logos, team crests, title marks.
+- Pickup, ability, weapon, inventory, achievement, and objective icons.
+- Hazard signs, decals, lane glyphs, cockpit labels, item badges.
+- Menu/loading/background plates, illustrated map panels, world-style UI textures.
+- GUI material references: glass panels, metal frames, holographic strips, paper/parchment, tactical screens.
+
+Use procedural geometry or a user-provided GLB only when the UI needs a 3D object: rotating character preview, vehicle garage, weapon inspect model, trophy, diorama, or diegetic 3D menu prop.
+
+## State Wiring
+
+- UI reads game state from a single source of truth.
+- UI events dispatch game intents; they should not mutate unrelated simulation internals directly.
+- UI should update on pause, restart, resize, mobile orientation, mute, fail/win, score, health, boost, combo, inventory, and accessibility settings.
+- Avoid stale values after restart.
+
+## Verification
+
+Capture evidence:
+
+- Gameplay HUD desktop screenshot.
+- Gameplay HUD mobile screenshot when in scope.
+- Pause/fail/retry state screenshot if changed.
+- Text-fit and overlap check with high values.
+- Touch target and safe-area check when mobile is in scope.
+- Interaction test for UI buttons and touch controls.
+- Console/page error check after UI events.
+- Sourced 2D asset path and source (procedural / user-provided / remote MCP) when external 2D was used.
+- Imported 3D preview model path and renderer diagnostics when a 3D UI prop/model was used.
+
+## Common Failures
+
+- Generic dashboard/stat-card HUD.
+- Nested cards and oversized decorative panels.
+- UI covers threats, pickups, player, or next decision.
+- Text explains obvious controls instead of designing affordances.
+- Mobile safe areas ignored.
+- Touch controls look correct but do not emit intents.
+- Values change width and shift layout during play.
+- Debug UI ships as player UI.

package/dist/skills/zh-CN/game-ui/references/ui-prompt-templates.md

@@ -0,0 +1,63 @@
+# Game UI Prompt Templates
+
+Reusable prompt templates packaged with this skill. Use only templates relevant to the current request, and adapt placeholders to the game/project context.
+
+---
+
+# Premium HUD/UI Pass Prompt
+
+Use `game-ui` to make this browser game's HUD and in-game UI feel premium, readable, and genre-specific.
+
+Context to gather:
+- Current screenshots at desktop and mobile sizes.
+- Game genre, core verb, target mood, and player decisions the HUD must support.
+- Current HUD/menu files, game state sources, input model, and touch controls.
+
+Design goals:
+- Keep the playable game as the first screen.
+- Make survival/status/objective information readable during motion.
+- Use stable dimensions for counters, buttons, meters, and labels.
+- Use icons where they reduce clutter, with labels where meaning is ambiguous.
+- Match the game's world materials, color, typography, and feedback language.
+
+Constraints:
+- Do not add marketing-page hero sections or explanatory feature copy.
+- Do not nest cards inside cards.
+- Do not let UI cover critical gameplay at desktop or mobile sizes.
+- Avoid text overflow, clipped controls, layout shift, and generic dashboard styling.
+
+Verification:
+- Build and run locally.
+- Capture desktop and mobile screenshots.
+- Check console/page errors.
+- Verify text fit, no overlap, no clipped controls, and at least one UI state change from real input.
+
+---
+
+# Responsive Game Menu Pass Prompt
+
+Use `game-ui` to design or improve this browser game's pause, start, settings, win, lose, or restart menus.
+
+Menu states needed:
+- 
+
+Target devices/orientations:
+- 
+
+Requirements:
+- Menus must feel like part of the game, not a website overlay.
+- Modal menus may pause or dim gameplay, but should not look like marketing cards.
+- Buttons need clear hover, pressed, focus, disabled, and touch states.
+- Settings must use appropriate controls: toggles, sliders, segmented controls, icon buttons, and select menus.
+- Layout must respect safe-area insets and remain usable on mobile.
+
+Implementation notes:
+- Prefer semantic HTML/CSS over canvas-rendered UI unless 3D placement is required.
+- Keep UI state driven by the game state model.
+- Keep dimensions stable so labels and counters do not shift layout.
+
+Verification:
+- Test every menu state.
+- Capture desktop and mobile screenshots.
+- Check keyboard/mouse and touch paths when both are supported.
+- Confirm no text overflow, overlap, clipping, or unreachable controls.