evomeme 0.1.9 → 0.1.10-beta.13

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

@@ -11,6 +11,8 @@ description: 指导 Agent 创作 evomeme手机平台游戏，在开发过程中
 
 **具体游戏开发计划**：制定、拆解或更新具体的游戏开发计划时，必须参照`game-maker`开发技能。本技能只提供evomeme平台对游戏的特殊要求。如果用户需要发布到EvoMeme平台，游戏必须满足本技能的要求。
 
+**平台 UI 与自适应必读**：开发任何要在 evomeme平台运行、上线或发布的游戏时，必须阅读并遵守 [`evomeme-ui`](../evomeme-ui/SKILL.md)。Agent 需要构造游戏 UI 界面或进行自适应适配时，必须在设计、编码前加载该技能，并按其容器尺寸、安全区规则和测试矩阵执行。
+
 ## 平台要求
 
 ### 游戏形态
@@ -19,13 +21,13 @@ evomeme平台只支持竖屏手机游戏。开发的游戏必须适配竖屏 UI
 
 #### 竖屏全屏适配
 
-手机端游玩界面必须适配所有竖屏屏幕尺寸和宽高比，并始终占满整个可视屏幕：
+手机端游玩界面必须适配宿主提供的不同竖屏 WebView 尺寸和宽高比，并始终填满实际游戏容器。“全屏”指 WebView 可用区域；不得按手机整屏高度布局或再次扣除宿主栏位及安全区。具体实现和验收遵循 [`evomeme-ui`](../evomeme-ui/SKILL.md)：
 
 - 禁止使用固定宽高比容器、留黑边、上下或左右加黑条等方式维持设计稿比例。
-- 游戏根容器、渲染画布和背景必须覆盖完整 visual viewport；页面不得因默认边距、固定尺寸或父容器约束产生未覆盖区域。
+- 游戏根容器、渲染画布和背景必须覆盖完整 WebView 游戏区域；页面不得因默认边距、固定尺寸或父容器约束产生未覆盖区域。
 - 当屏幕宽高比与设计稿不同时，通过响应式布局、相机缩放、背景 `cover` 或允许裁切的扩展区域完成适配，不得把整个游玩画面等比缩小后留出黑边。
-- HUD、按钮和关键交互内容必须根据屏幕尺寸动态布局。安全区只用于调整关键 UI 的内边距，不得缩小游戏画面或背景的覆盖范围。
-- Web 页面应设置正确的移动端 viewport，并让 `html`、`body`、应用根节点及游戏容器占满视口；需要兼容动态浏览器栏时使用动态视口高度并提供合理回退。
+- HUD、按钮和关键交互内容必须根据实际容器尺寸动态布局。可以设置游戏内部留白，但不得再次扣除宿主已经处理的手机安全区，也不得缩小游戏画面或背景的覆盖范围。
+- Web 页面应设置正确的移动端 viewport，并让 `html`、`body`、应用根节点及游戏容器形成完整的 `100%` 高度链；容器尺寸变化时同步更新布局、渲染尺寸和输入映射。
 - 完成开发后必须在多种竖屏尺寸和宽高比下验证：游玩区域全屏覆盖、无黑边、无页面滚动条，且关键 UI 不被裁切或遮挡。
 
 ### Demo 图片素材
@@ -57,82 +59,82 @@ evomeme平台只支持竖屏手机游戏。开发的游戏必须适配竖屏 UI
 - `src/`：存放主要开发代码。
 - `index.html`：作为游戏工程的网页入口。
 
-#### 代码依赖与发布路径
-
-**强制交付门槛：** 只有生产构建命令（通常为 `npm run build`）以退出码 `0` 完成，生成真实且非空的 `dist/`，其中存在 `dist/index.html` 和全部被引用的本地文件，并通过本节的构建后路径检查，游戏任务才算完成。仅修改源码、开发服务器可运行、截图正常或推测“应该可以构建”，均不能作为交付结果。任一条件不满足时，必须继续修复、重新构建并重新检查。
-
-最终 `dist/` 可能被部署到任意 URL 子路径，不保证位于域名根目录。所有本地运行时引用都必须相对于当前文档或构建产物：
-
-- 项目内代码依赖使用 `./` 或 `../`；禁止写入本机绝对路径、工作区绝对路径、`file://` 地址或只能由开发服务器解析的源码 URL。
-- HTML 的本地 `src`、`href`、`poster`、`srcset`，CSS 的本地 `url(...)`，以及 JavaScript 的 `fetch()`、动态 `import()`、Worker、音频和其他本地资源地址，必须使用 `./...` 或等价相对路径。
-- 严禁任何以单个 `/` 开头的本地根绝对路径，例如 `/assets/...`、`/asset/...`、`/config.json`、`/src/...`。应分别写为 `./assets/...`、`./asset/...`、`./config.json`、`./src/...`。
-- 禁止通过 `location.origin`、`new URL(path, location.origin)` 或其他字符串拼接方式重新构造根绝对本地地址。
-- 可公开访问的 `http://`、`https://` 远程 URL 不受本地相对路径规则限制。
-- 修改现有项目时保留与任务无关的架构，但只要最终 `dist/` 仍包含根绝对本地引用，就必须做最小修复，不能交付。
-
-##### Vite 基址（强制）
-
-新建 Vite 项目必须创建 Vite 配置并显式设置 `base: './'`，不得依赖 Vite 默认值 `/`。React 项目示例：
-
-```js
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-
-export default defineConfig({
-  plugins: [react()],
-  base: './',
-});
-```
-
-其他构建工具必须设置等价的相对发布基路径。
-
-##### 新建 React + Vite 项目的完整 `index.html`（强制）
-
-新建 React + Vite 项目必须使用以下源码入口格式。JavaScript 项目使用 `./src/main.jsx`；TypeScript 项目只将其替换为 `./src/main.tsx`。入口禁止写成 `/src/main.jsx` 或 `/src/main.tsx`。
-
-```html
-<!doctype html>
-<html lang="zh-CN">
-<head>
-  <meta charset="UTF-8" />
-  <meta
-    name="viewport"
-    content="width=device-width,initial-scale=1,viewport-fit=cover,user-scalable=no"
-  />
-  <meta name="theme-color" content="#000000" />
-  <title>游戏名称</title>
-</head>
-<body>
-  <div id="root"></div>
-  <script type="module" src="./src/main.jsx"></script>
-</body>
-</html>
-```
-
-CSS 应从入口模块通过 `import './style.css'` 等相对路径导入，不要在源码 `index.html` 中预写或猜测带哈希的构建文件名。Vite 构建后的 `dist/index.html` 必须使用相对构建资源路径，例如：
-
-```html
-<script type="module" crossorigin src="./assets/index-HASH.js"></script>
-<link rel="stylesheet" crossorigin href="./assets/index-HASH.css">
-```
-
-`HASH` 代表 Vite 实际生成的哈希，不能硬编码。
-
-##### `dist/` 完整性和路径检查（阻断交付）
-
-每次生产构建完成后、宣布成功前，必须直接检查 `dist/index.html` 以及它引用的 JavaScript、CSS 和其他文本产物：
-
-1. 确认构建命令退出码为 `0`。
-2. 确认 `dist/` 真实存在且非空，并确认 `dist/index.html` 存在。
-3. 解析或逐一核对 `dist/index.html` 中的本地引用，确认每个目标文件真实存在于 `dist/` 内。
-4. 扫描 `dist/index.html`、构建后的 JavaScript 和 CSS，不得出现指向本地资源的 `src="/`、`src='/`、`href="/`、`href='/`、`poster="/`、`poster='/`、`url(/`、`fetch('/`、`fetch("/`、`import('/`、`import("/`、`new Worker('/`、`new Worker("/` 或等价根绝对形式。
-5. 明确检查并禁止 `/assets/...`、`/asset/...`、`/config.json`、`/src/...`；它们必须改为 `./assets/...`、`./asset/...`、`./config.json`、`./src/...` 或其他正确的相对路径。
-6. 检查 `dist/` 中不存在对 `src/`、`public/`、项目根目录、工作区文件、`localhost`、Vite 开发服务器、`.ts`、`.tsx` 或其他未构建源码的运行时依赖。
-7. 发现任何违规引用、缺失文件或不完整产物时，构建即判定无效；修复后必须重新执行生产构建，并从第 1 步重新检查。不能因为构建命令曾经退出码为 `0` 就跳过复查。
-
-`dist/` 必须是可以独立部署的完整运行目录。`dist/index.html`、构建后的 JavaScript、CSS 和配置只能依赖 `dist/` 内文件或公开远程 URL。`dist/` 内禁止存在图片、视频、音频、字体、模型等二进制文件；这些素材必须通过公开 URL 接入。禁止通过复制源码到 `dist/` 规避构建，源码依赖必须在生产构建中正确解析和打包。
-
-发布前还必须以 `dist/` 为静态服务根目录启动预览，并在该地址验证启动、资源加载和完整核心流程。开发服务器可以用于开发，但不能作为发布验收证据。
+#### 代码依赖与发布路径
+
+**强制交付门槛：** 只有生产构建命令（通常为 `npm run build`）以退出码 `0` 完成，生成真实且非空的 `dist/`，其中存在 `dist/index.html` 和全部被引用的本地文件，并通过本节的构建后路径检查，游戏任务才算完成。仅修改源码、开发服务器可运行、截图正常或推测“应该可以构建”，均不能作为交付结果。任一条件不满足时，必须继续修复、重新构建并重新检查。
+
+最终 `dist/` 可能被部署到任意 URL 子路径，不保证位于域名根目录。所有本地运行时引用都必须相对于当前文档或构建产物：
+
+- 项目内代码依赖使用 `./` 或 `../`；禁止写入本机绝对路径、工作区绝对路径、`file://` 地址或只能由开发服务器解析的源码 URL。
+- HTML 的本地 `src`、`href`、`poster`、`srcset`，CSS 的本地 `url(...)`，以及 JavaScript 的 `fetch()`、动态 `import()`、Worker、音频和其他本地资源地址，必须使用 `./...` 或等价相对路径。
+- 严禁任何以单个 `/` 开头的本地根绝对路径，例如 `/assets/...`、`/asset/...`、`/config.json`、`/src/...`。应分别写为 `./assets/...`、`./asset/...`、`./config.json`、`./src/...`。
+- 禁止通过 `location.origin`、`new URL(path, location.origin)` 或其他字符串拼接方式重新构造根绝对本地地址。
+- 可公开访问的 `http://`、`https://` 远程 URL 不受本地相对路径规则限制。
+- 修改现有项目时保留与任务无关的架构，但只要最终 `dist/` 仍包含根绝对本地引用，就必须做最小修复，不能交付。
+
+##### Vite 基址（强制）
+
+新建 Vite 项目必须创建 Vite 配置并显式设置 `base: './'`，不得依赖 Vite 默认值 `/`。React 项目示例：
+
+```js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  base: './',
+});
+```
+
+其他构建工具必须设置等价的相对发布基路径。
+
+##### 新建 React + Vite 项目的完整 `index.html`（强制）
+
+新建 React + Vite 项目必须使用以下源码入口格式。JavaScript 项目使用 `./src/main.jsx`；TypeScript 项目只将其替换为 `./src/main.tsx`。入口禁止写成 `/src/main.jsx` 或 `/src/main.tsx`。
+
+```html
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta
+    name="viewport"
+    content="width=device-width,initial-scale=1,viewport-fit=cover,user-scalable=no"
+  />
+  <meta name="theme-color" content="#000000" />
+  <title>游戏名称</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="./src/main.jsx"></script>
+</body>
+</html>
+```
+
+CSS 应从入口模块通过 `import './style.css'` 等相对路径导入，不要在源码 `index.html` 中预写或猜测带哈希的构建文件名。Vite 构建后的 `dist/index.html` 必须使用相对构建资源路径，例如：
+
+```html
+<script type="module" crossorigin src="./assets/index-HASH.js"></script>
+<link rel="stylesheet" crossorigin href="./assets/index-HASH.css">
+```
+
+`HASH` 代表 Vite 实际生成的哈希，不能硬编码。
+
+##### `dist/` 完整性和路径检查（阻断交付）
+
+每次生产构建完成后、宣布成功前，必须直接检查 `dist/index.html` 以及它引用的 JavaScript、CSS 和其他文本产物：
+
+1. 确认构建命令退出码为 `0`。
+2. 确认 `dist/` 真实存在且非空，并确认 `dist/index.html` 存在。
+3. 解析或逐一核对 `dist/index.html` 中的本地引用，确认每个目标文件真实存在于 `dist/` 内。
+4. 扫描 `dist/index.html`、构建后的 JavaScript 和 CSS，不得出现指向本地资源的 `src="/`、`src='/`、`href="/`、`href='/`、`poster="/`、`poster='/`、`url(/`、`fetch('/`、`fetch("/`、`import('/`、`import("/`、`new Worker('/`、`new Worker("/` 或等价根绝对形式。
+5. 明确检查并禁止 `/assets/...`、`/asset/...`、`/config.json`、`/src/...`；它们必须改为 `./assets/...`、`./asset/...`、`./config.json`、`./src/...` 或其他正确的相对路径。
+6. 检查 `dist/` 中不存在对 `src/`、`public/`、项目根目录、工作区文件、`localhost`、Vite 开发服务器、`.ts`、`.tsx` 或其他未构建源码的运行时依赖。
+7. 发现任何违规引用、缺失文件或不完整产物时，构建即判定无效；修复后必须重新执行生产构建，并从第 1 步重新检查。不能因为构建命令曾经退出码为 `0` 就跳过复查。
+
+`dist/` 必须是可以独立部署的完整运行目录。`dist/index.html`、构建后的 JavaScript、CSS 和配置只能依赖 `dist/` 内文件或公开远程 URL。`dist/` 内禁止存在图片、视频、音频、字体、模型等二进制文件；这些素材必须通过公开 URL 接入。禁止通过复制源码到 `dist/` 规避构建，源码依赖必须在生产构建中正确解析和打包。
+
+发布前还必须以 `dist/` 为静态服务根目录启动预览，并在该地址验证启动、资源加载和完整核心流程。开发服务器可以用于开发，但不能作为发布验收证据。
 
 #### `/public/config.json` 规则
 
@@ -256,20 +258,21 @@ key 以 `_` 开头，用于内部配置、资源映射、版本号和调试开
 仅在准备提交或发布游戏时检查以下事项：
 
 - [ ] 游戏使用竖屏 UI 布局，并支持触屏操作。
-- [ ] 在不同竖屏尺寸和宽高比下，游玩界面均占满整个可视屏幕，无任何黑边或未覆盖区域，关键 UI 保持可见可操作。
+- [ ] 已阅读并遵守 `evomeme-ui`，至少通过 375×524、402×646、412×732 三档游戏容器尺寸及运行中尺寸变化验证。
+- [ ] 在不同竖屏尺寸和宽高比下，游玩界面均填满宿主 WebView，无任何黑边或未覆盖区域，未重复扣除原生栏位及安全区，关键 UI 保持可见可操作。
 - [ ] Demo 不包含 SVG、线条绘制或大面积纯色游戏素材；所需游戏图片均已通过图片生成获得并实际接入。
 - [ ] 根目录包含 `dist/`、`public/config.json`、`src/` 和 `index.html`。
 - [ ] `public/config.json` 可解析、符合配置 schema，并在构建后原样输出为 `dist/config.json`。
 - [ ] `public/config.json` 以公开链接记录游戏使用的二进制素材。
 - [ ] 本地二进制文件路径已加入 `.evomemeignore`。
 - [ ] `.evomemeignore` 保持 `dist/` 在提交范围内。
-- [ ] `dist/` 来自完成资源链接替换后的最新生产构建。
-- [ ] 生产构建命令以退出码 `0` 完成，`dist/` 非空并包含 `dist/index.html`。
-- [ ] 新建 Vite 项目显式设置 `base: './'`；源码 `index.html` 使用 `./src/main.jsx` 或 `./src/main.tsx`。
-- [ ] `dist/index.html` 中引用的每个本地文件均真实存在于 `dist/` 内。
-- [ ] 已扫描 `dist/index.html` 及其引用的 JavaScript、CSS；不存在 `src="/`、`href="/`、`url(/`、`fetch('/`、`fetch("/`、`/assets/`、`/asset/`、`/config.json`、`/src/` 或等价根绝对本地引用。
-- [ ] 构建使用相对发布基路径；运行时配置和资源使用 `./...` 或等价相对 URL，不依赖域名根路径，也不通过 `location.origin` 重建根路径。
-- [ ] `dist/` 可独立部署，且其中没有对 `src/`、`public/`、项目根目录、`localhost`、开发服务器或未构建源码的运行时依赖。
+- [ ] `dist/` 来自完成资源链接替换后的最新生产构建。
+- [ ] 生产构建命令以退出码 `0` 完成，`dist/` 非空并包含 `dist/index.html`。
+- [ ] 新建 Vite 项目显式设置 `base: './'`；源码 `index.html` 使用 `./src/main.jsx` 或 `./src/main.tsx`。
+- [ ] `dist/index.html` 中引用的每个本地文件均真实存在于 `dist/` 内。
+- [ ] 已扫描 `dist/index.html` 及其引用的 JavaScript、CSS；不存在 `src="/`、`href="/`、`url(/`、`fetch('/`、`fetch("/`、`/assets/`、`/asset/`、`/config.json`、`/src/` 或等价根绝对本地引用。
+- [ ] 构建使用相对发布基路径；运行时配置和资源使用 `./...` 或等价相对 URL，不依赖域名根路径，也不通过 `location.origin` 重建根路径。
+- [ ] `dist/` 可独立部署，且其中没有对 `src/`、`public/`、项目根目录、`localhost`、开发服务器或未构建源码的运行时依赖。
 - [ ] 已以 `dist/` 为静态服务根目录完成预览，游戏能够启动、加载资源并跑通核心流程。
 - [ ] 提交文件集合只包含 UTF-8 文本文件。
 - [ ] 发布过程遵循 `evomeme-cloud-fs`。

package/{skills → dist/skills/zh-CN}/evomeme-login/SKILL.md

@@ -5,6 +5,11 @@ description: 在 evomeme_* MCP 或 init 出现登录 / token 错误后恢复 evo
 
 # evomeme登录恢复
 
+| 工具（中文名称） | 实际操作与结果 | 何时使用 |
+| --- | --- | --- |
+| `evomeme_check_login`（检查登录状态） | 检查已有凭证并返回登录状态；不创建素材或项目文件。 | 已发生鉴权失败后，按下文流程判断凭证是否需要恢复。 |
+| `evomeme_login`（登录账号） | 发起浏览器登录，成功后在本机保存凭证并返回登录结果。 | 凭证缺失、过期或无效时，恢复后续工具的鉴权能力。 |
+
 ## 何时使用（门控）
 
 **仅在已经出现登录 / 鉴权相关失败之后**再加载本技能并执行下方流程。

package/dist/skills/zh-CN/evomeme-mcp/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: evomeme-mcp
+description: 安装、启动、更新或排查 evomeme MCP。Agent 在配置 evomeme MCP、启动失败、连接关闭、工具缺失或更新不生效时必须阅读此技能。用于恢复 MCP 连接和确认工具可见，不替代正常素材生成技能。
+---
+
+# evomeme MCP 启动与故障排查
+
+## 功能与使用时机
+
+本技能指导 Agent 配置 IDE 启动 evomeme、定位连接失败并验证工具列表。结果是 IDE 的 MCP 配置文件得到安装或修复，以及有证据的连接状态；本技能本身不生成图片、视频或项目。
+
+- 用户要求安装、启动、更新 evomeme MCP，或工具不可见、进程启动失败时，阅读本技能。
+- 正常调用素材工具不必重复安装或检查登录。工具已经返回业务错误时，先按错误类别排查。
+- 本技能随 `init` 按当前语言复制到工作区；`install` 只配置 MCP，不复制技能。不修改已有其他技能名称。
+
+## 关键名词
+
+- **MCP（Model Context Protocol）**：IDE 中的 Agent 与外部工具服务交换请求的协议。evomeme 是提供 `evomeme_*` 工具的本地服务进程。
+- **stdio**：IDE 启动子进程，通过标准输入和标准输出交换协议消息。evomeme MCP 不需要监听 HTTP 端口；不要把后端 API 地址当成 MCP 连接地址，也不要向 MCP 的标准输出写普通日志。
+- **启动器（launcher）**：配置里的 `command` 与 `args`，分别是可执行程序及独立参数数组。Node.js 运行 JavaScript，npm 管理包，npx / npm exec 获取并运行包。Windows 安装器可能使用 Node 和 npm 脚本的绝对路径。
+- **initialize / tools/list**：分别表示协议握手与读取可用工具列表。成功说明该子进程可通信，不证明 IDE 已加载同一份配置，也不证明云端生成服务可用。
+- **配置文件与工作区**：MCP 配置决定 IDE 如何启动服务；工作区是游戏项目文件夹。技能是供 Agent 阅读的说明文件，复制技能不会自动启动 MCP。
+
+## 安装与启动
+
+支持 `codex`、`cursor`、`claude`（Claude Code）、`workbuddy`、`trae`（本安装器默认 Trae SOLO 国内版）。先确定用户实际使用的 IDE、配置文件和发布通道。
+
+```powershell
+npx -y evomeme@latest install --ide cursor
+```
+
+安装器先启动临时 MCP 子进程执行握手和工具列表自检，再合并 IDE 配置。保留其他 MCP 条目；已有文件内容变化时备份为原路径追加 `.evomeme-cli.bak.latest`。同名 `evomeme` 条目会被刷新。
+
+IDE 使用自定义配置位置时，指定**完整配置文件路径**：
+
+```powershell
+npx -y evomeme@latest install --ide cursor --config-path "D:\MyConfig\mcp.json"
+npx -y evomeme@latest install --ide codex --config-path "D:\MyConfig\config.toml"
+```
+
+- 路径必须是 IDE 实际读取的配置文件，不是 IDE 程序目录或可执行文件。移动 IDE 程序不一定会移动配置文件。
+- 支持绝对路径与相对当前终端目录的路径；含空格的路径加引号。文件及父目录不存在时会创建，但这不会改变 IDE 自己选择配置文件的规则。
+- `--config-path` 只能搭配一个 IDE；为多个 IDE 分别执行。省略该参数沿用默认路径。指定路径只影响本次执行，后续重装仍要传入同一路径。
+- Codex 写 TOML，其他安装器写 JSON。不要把同一文件交给不同格式的安装器。
+- 重新安装前读取已有 `evomeme` 的启动参数及环境配置。保留用户选择的 `--package` 固定版本/本地包，以及 `--api-base-url` 自定义后端；省略后端参数会刷新成使用发布包默认地址的配置。
+
+安装完成后重启 IDE 或重新连接其 MCP 服务，再在该 IDE 中确认工具列表含所需 `evomeme_*` 工具。仅看到“配置已更新”不能报告 IDE 已连接。
+
+IDE 配置中的服务启动参数应运行包的 **无子命令模式**，不能附带 `install`、`init` 或 `version`。直接在终端运行下面命令会进入等待协议输入的状态，不能凭“没有输出”判断卡死；通常应让 IDE 管理该进程：
+
+```powershell
+npx -y evomeme@latest
+```
+
+## init 与技能分发
+
+需要初始化工作区或刷新工作区技能时，在目标项目执行：
+
+```powershell
+npx -y evomeme@latest init --ide cursor
+```
+
+`init` 会校验登录、创建或复用云端作品绑定、建立忽略规则，再复制包内技能；它不是纯粹的连接检查。省略 `--ide` 会复制到所有支持的 IDE 工作区技能目录。当前版本覆盖同名包内技能、增加新技能、保留用户其他技能。
+
+技能位置：Codex 为 `.codex/skills/evomeme-mcp/`，Cursor 为 `.cursor/skills/evomeme-mcp/`，Claude Code 为 `.claude/skills/evomeme-mcp/`，WorkBuddy 为 `.codebuddy/skills/evomeme-mcp/`，Trae 为 `.trae/skills/evomeme-mcp/`。MCP 的 `--config-path` 不改变这些工作区技能目录。
+
+## 出现故障时
+
+阅读 [故障处理](references/troubleshooting.md)，按现象选择相关部分。优先收集实际配置路径、启动命令、进程版本、IDE 的 MCP 错误与当日日志。每次针对已有证据修复后验证一次；相同错误重复时停止盲目重装，报告已确认原因和仍缺少的证据。
+
+连接恢复只需握手和工具列表验证，不为此发起付费素材生成。恢复后继续用户原任务；若之前的生成是否提交成功尚不确定，先查询已有任务状态，避免重复提交。

package/dist/skills/zh-CN/evomeme-mcp/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "evomeme MCP 启动与排障"
+  short_description: "安装或修复 evomeme MCP 配置，排查启动失败与工具缺失"
+  default_prompt: "使用 $evomeme-mcp 配置或排查 evomeme MCP，确认实际配置路径并验证 IDE 的工具连接。"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/zh-CN/evomeme-mcp/references/troubleshooting.md

@@ -0,0 +1,55 @@
+# evomeme MCP 故障处理
+
+## 1. 定位实际配置
+
+以下是**本安装器未指定 `--config-path` 时**使用的路径；`~` 表示操作系统当前用户的主目录，不是 IDE 安装目录。
+
+| IDE | 默认配置文件 |
+| --- | --- |
+| Cursor | `~/.cursor/mcp.json` |
+| Codex | `~/.codex/config.toml` |
+| Claude Code | `~/.claude.json` |
+| WorkBuddy | `~/.workbuddy/mcp.json` |
+| Trae SOLO 国内版 / Windows | `%APPDATA%/TRAE SOLO CN/User/mcp.json`；无 APPDATA 时回退到用户目录下 `AppData/Roaming` |
+| Trae SOLO 国内版 / macOS | `~/Library/Application Support/TRAE SOLO CN/User/mcp.json` |
+| Trae SOLO 国内版 / Linux | `$XDG_CONFIG_HOME/TRAE SOLO CN/User/mcp.json`；未设置时为 `~/.config/TRAE SOLO CN/User/mcp.json` |
+
+当前 Codex 安装器未自动采用 `CODEX_HOME`；其他 IDE 的便携版、自定义配置目录或不同产品版本也不能仅凭默认位置推断。通过 IDE 设置或其实际启动配置确认文件，用 `--config-path` 显式传入。不要扫描全盘或同时写入多个猜测位置。
+
+只查看本次故障需要的字段，避免输出其他 MCP 的凭证。写入器保留其他 MCP 和配置；JSON 解析失败时会退出，不应删掉文件重新生成。TOML 安装器替换 evomeme 表并检测其重复表，不是完整 TOML 语法校验器，其他语法错误要结合 IDE 诊断处理。
+
+## 2. 按现象处理
+
+| 现象 | 核查与处理 |
+| --- | --- |
+| `--config-path` 缺值、指向目录或同时传多个 IDE | 传入一个 IDE 的完整配置文件路径。多 IDE 分开执行；参数错误会在自检和写配置前退出。 |
+| 安装成功，IDE 仍无工具 | 对比安装输出路径与 IDE 实际读取路径；检查 evomeme 服务是否启用、是否需用户在 IDE 中启用；重连或重启 IDE，再读工具列表。自检使用安装终端的环境，IDE 环境可能不同。 |
+| `spawn ... ENOENT`、找不到 `node` / `npx` | 运行 `node --version`、`npm --version` 并核对配置中的程序路径。Windows 可用 `Get-Command node,npm,npx`；macOS/Linux 可用 `command -v node npm npx`。Node/npm 移动或升级后，原绝对路径可能失效；在可用环境重跑 install 并保留原自定义参数。 |
+| PowerShell 提示 `npx.ps1` 禁止运行 | 核实机器有 `npx.cmd` 后使用它运行同一安装命令；无需全局放宽 PowerShell 执行策略。 |
+| `Connection closed` 或 initialize 失败 | 查看子进程 stderr 与启动日志，区分缺少可执行文件、缺包、运行时崩溃、启动了错误子命令和协议输出污染。该错误本身不能证明网络故障。 |
+| 安装器写“网络连接失败”，但详情为 ENOENT | 当前安装器把部分启动失败也归入该提示。以具体异常与 stderr 为依据，先修复程序或文件路径。 |
+| npm 超时、DNS/代理/证书错误、包或版本不存在 | 检查 npm stderr、当前网络、`npm config get registry` 和请求的包/版本。本地 tgz 还需确认文件存在且 IDE 可访问。按证据处理，不默认清空 npm 缓存、关闭证书验证或更换全局 registry。 |
+| 权限不足、JSON/TOML 无法解析 | 确认实际配置文件的访问权限与语法。利用 `.evomeme-cli.bak.latest` 对照修复；恢复整个备份前比较后续修改，保留其他 MCP，不覆盖用户新增配置。 |
+| 命令提示不认识 `--config-path`，或仍写默认路径 | 核对实际运行版本及该选项是否出现在 `npx -y evomeme@latest help` 中；旧版本可能静默忽略未知参数。仅在安装输出确认目标路径后才认为自定义路径生效。 |
+| 更新后工具仍旧或缺失 | 查看 IDE 启动配置是否固定旧版本、使用旧 tgz 或 `--dev` 对应的构建；比较日志中实际进程版本与工具列表。更新安装后重启 MCP；`init` 只更新工作区内容，不替换正在运行的 MCP 进程。 |
+| 开发模式报找不到 `dist/index.js` | `install --dev` 使用执行时当前目录下的 `dist/index.js`；在插件源码目录构建后重装。普通用户安装不要添加 `--dev`。 |
+| 服务已连接，工具返回未登录或 40100 | 进入登录恢复流程，已分发的 `evomeme-login` 技能可提供指导；告知用户后完成浏览器登录。MCP 连接正常时不要靠重装处理凭证错误。 |
+| 工具返回 HTTP 404、413、502、超时或响应结构不兼容 | 检查日志中的接口路径、状态码、实际发布通道与 `EVOMEME_API_BASE_URL`。`--api-base-url` 是云端 HTTP API 根地址；它不设置本地 stdio 地址。依据后端错误诊断，不仅凭协议不兼容就判定客户端过旧。 |
+| 单个生图/视频任务供应商失败或缺少响应字段 | 保存本地任务 ID、远端任务 ID 和具体错误。本地能调用工具不代表供应商链路成功；仅客户端日志不能证明 NewAPI 参数是否透传。需要后端证据时明确说明，不擅改供应商参数或循环付费重试。 |
+| Agent 等待超时，但后台仍在生成 | 先查看工作区 `.evomeme/tasks/` 的已有任务记录与日志中的状态变化；不要把客户端超时当作远端失败，也不要删除任务目录来“重置”服务。 |
+
+## 3. 日志与证据
+
+运行日志统一位于 `~/.evomeme/logs/YYYY-MM-DD.jsonl`，Windows 通常为 `C:\Users\<用户名>\.evomeme\logs\`。按本地日期每天一个文件，保留当天及之前六天，不按大小截断文件。JSONL 表示每行一条 JSON 记录。
+
+| 查什么 | 相关字段或事件 |
+| --- | --- |
+| 真正启动的是哪个版本 | `process.started`，以及 `version`、`channel`、`pid`、`sessionId`、`fields.nodeVersion` |
+| 命令执行失败 | `cli.failed`、`cli.error`、`process.failed` |
+| 某次工具调用 | `mcp.call_started`、`mcp.call_completed`、`mcp.call_failed`、`mcp.tool_error`，按 `fields.callId` 关联 |
+| 网络或后端错误 | `http.failed` 的 endpoint、status、durationMs、error；成功记录为 `http.completed` |
+| 后台执行过程 | `task.created`、`task.updated`、`task.execution_failed`、`task.worker_exited`，按 taskId、stepId、remoteJobId 关联 |
+
+工作区路径、调用与任务关联字段在记录具备相应上下文时才存在。日志包含客户端异常堆栈，但没有完整请求/响应正文、原始供应商响应或服务器内部堆栈。无日志也可能是程序尚未启动、旧包没有日志功能，或写入失败，不能单凭空目录定位原因。
+
+向用户报告：问题发生在哪一层、已确认的证据、修复了哪个配置文件、握手与 IDE 工具列表各自是否验证。提供与故障相关的脱敏片段，不输出 auth.json、完整环境变量或其他服务凭证。

package/{skills → dist/skills/zh-CN}/evomeme-tos-upload/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: evomeme-tos-upload
-description: 通过 evomeme_upload_game_asset 将受支持的本地图片、音频或视频上传到 evomemeTOS，内容审核通过后获取公开 asset_url。
+description: 通过 evomeme_upload_game_asset 将受支持的本地图片、音频、视频或常见 3D 模型上传到 evomemeTOS，内容审核通过后获取公开 asset_url。
 ---
 
 # evomeme-tos-upload
 
 ## Purpose
 
-将受支持的本地图片、音频或视频上传到 evomemeTOS，拿到公开可访问的 `asset_url`。
+将受支持的本地图片、音频、视频或常见 3D 模型上传到 evomemeTOS，拿到公开可访问的 `asset_url`。
 
-- 调用主 MCP（`evomeme`）工具 **`evomeme_upload_game_asset`**；plugin_client 按后缀选择图片同步接口或统一音视频接口并提交原始字节，由服务端上传 TOS。只有通过内容安全审核后才会返回链接。
+- 调用主 MCP（`evomeme`）工具 **`evomeme_upload_game_asset`**；plugin_client 按后缀选择图片 / 模型同步接口或统一音视频接口并提交原始字节，由服务端上传 TOS。只有通过内容安全审核后才会返回链接。
 - 不要手写 AK/SK，不要伪造 CDN 地址，不要把二进制直接塞进源码仓库。
 
 允许的后缀只有：
@@ -17,8 +17,9 @@ description: 通过 evomeme_upload_game_asset 将受支持的本地图片、音
 - 图片：PNG、JPG、JPEG、BMP、WEBP、TIFF、SVG、GIF、ICO、HEIC
 - 音频：MP3、WAV、AAC、WMA、OGG、M4A、AMR
 - 视频：AVI、FLV、MP4、MPG、ASF、WMV、MOV、WMA、RMVB、RM、FLASH、TS、M3U8
+- 模型：GLB、GLTF、FBX、OBJ、STL（有外部贴图或缓冲文件时建议先打包为 GLB）
 
-模型、字体、压缩包和其他未列出的类型禁止上传。WMA 按音频处理。
+字体、压缩包和其他未列出的类型禁止上传。WMA 按音频处理。图片与模型同步审核；音频与视频异步轮询审核。
 
 ## Upload Workflow
 
@@ -32,7 +33,7 @@ description: 通过 evomeme_upload_game_asset 将受支持的本地图片、音
 
 成功时工具返回公开可访问的 `asset_url`。
 
-本地媒体素材需要公开 URL 时走本上传流程；非媒体文件不支持。
+本地图片 / 音视频 / 常见 3D 模型需要公开 URL 时走本上传流程；未列出的类型不支持。
 
 ## Non-Negotiables
 

package/dist/skills/zh-CN/evomeme-ui/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: evomeme-ui
+description: 规定 evomeme平台游戏的 WebView 容器适配、UI 布局和多尺寸验收要求。开发任何计划在 evomeme平台运行、上线或发布的游戏时必须阅读；创建或修改 HUD、菜单、弹窗、触控区域、Canvas 尺寸和响应式布局时必须遵守。
+---
+
+# evomeme 游戏 UI 与自适应
+
+## 必读范围
+
+凡是要在 evomeme平台运行、上线或发布的游戏，在开始开发、迁移或改造前必须阅读本技能。构造游戏 UI、修改布局或处理自适应问题时，必须按本技能执行，不能等到发布阶段才补做适配。
+
+本技能规定平台容器与布局约束。游戏整体工程要求遵循 [`evomeme-game-maker`](../evomeme-game-maker/SKILL.md)；需要 UI 风格、信息层级或概念设计时结合 [`game-ui`](../game-ui/SKILL.md)。evomeme游戏的尺寸来源、安全区处理和适配验收以本技能为准。
+
+## 宿主容器约定
+
+**游戏运行在 App 已经计算完成的 WebView 可用区域内。游戏的“全屏”是填满这个区域。**
+
+1. 使用游戏容器实时的 `clientWidth`、`clientHeight` 或 `ResizeObserver` 测量结果作为布局依据；不得根据手机完整屏幕高度计算游戏高度。
+2. 不得再次扣除 App Tab Bar、游戏信息及操作区或手机安全区。不得将宿主原生层的 `3.75rem`、`4.5rem`、`8.25rem` 用于游戏网页布局。
+3. 游戏根节点、渲染画布和背景必须填满 WebView 容器，不得用固定宽高比容器、黑边或整幅等比缩小维持设计稿比例。
+4. 背景可以裁剪或延展；核心角色、HUD、文字、按钮和游戏判定区域必须保持可见、可操作。不得只按设计稿屏幕边缘的固定绝对坐标摆放关键内容。
+5. 容器尺寸变化时，重新计算布局、相机或可玩区域、Canvas 渲染尺寸及触控坐标映射。页面不得出现由布局溢出造成的滚动条。
+6. App 原生层 NativeWind 的动态 `rem` 不会自动传入 WebView。网页 CSS 的 `rem` 由网页根字号决定；逻辑尺寸使用 CSS px，不能直接使用设备物理分辨率。
+
+需要理解原生扣减公式、402px 设计基准或完整设备估算表时，读取 [`references/host-layout.md`](references/host-layout.md)。这些资料仅用于设计与测试，不得据此在游戏运行时硬编码高度。
+
+## 设计与布局
+
+以 **402×646 CSS px** 为主要设计基准。典型 WebView 宽高比约为 **1:1.60～1:1.78**，极端短屏约为 **1:1.40**；这些是测试参考，不能作为运行时尺寸限制。
+
+- 先在短屏中保证核心玩法、主要按钮和必要文字完整，再利用较高容器增加背景延展、元素间距或可玩区域。
+- HUD、菜单、弹窗和触控区域使用容器内的锚点、相对布局或响应式约束；内容长度变化后仍需保持可见和可点击。
+- 游戏内部可以有视觉留白和触控间距，但不得以“安全区适配”为由再次扣除宿主已经处理的手机安全区。
+- 背景裁切区域与关键内容区分开处理；不能为了铺满背景而裁掉角色、按钮或判定区域。
+- 全屏背景、DOM UI、游戏相机和输入坐标共用同一套容器尺寸，避免画面已经缩放而按钮或命中区域仍停留在旧坐标。
+
+## Web 页面基础样式
+
+设置移动端 viewport，例如：
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+```
+
+让尺寸从 WebView 逐层传递到游戏根容器。下面的 `#root`、`#game-root` 应对应项目实际挂载节点；有额外包装层时，也必须保证高度链完整。
+
+```css
+html,
+body,
+#root {
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  margin: 0;
+  overflow: hidden;
+}
+
+#game-root {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+}
+
+#game-root canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+  touch-action: none;
+}
+```
+
+不得使用 `100vh - App栏高度 - safe-area-inset` 一类公式再次扣减宿主布局。`overflow: hidden` 只用于控制页面滚动，不能用它掩盖关键内容超出容器的问题。
+
+## Canvas 与引擎尺寸同步
+
+监听游戏容器，而不是只在启动时读取一次窗口尺寸。下面示例说明尺寸分层；`resizeGameLayout` 代表项目实际的布局更新函数，必须接入 UI、可玩区域和输入映射更新。
+
+```js
+const container = document.querySelector('#game-root');
+const canvas = container.querySelector('canvas');
+
+const observer = new ResizeObserver(([entry]) => {
+  const { width, height } = entry.contentRect;
+  if (width <= 0 || height <= 0) return;
+  const dpr = Math.min(window.devicePixelRatio || 1, 2);
+
+  canvas.style.width = `${width}px`;
+  canvas.style.height = `${height}px`;
+  canvas.width = Math.round(width * dpr);
+  canvas.height = Math.round(height * dpr);
+
+  // 逻辑布局使用 CSS px；渲染缓冲区使用乘以 DPR 后的尺寸。
+  resizeGameLayout(width, height, dpr);
+});
+
+observer.observe(container);
+// 在组件卸载或场景销毁时调用 observer.disconnect()。
+```
+
+Phaser、Three.js 或其他引擎项目应通过现有引擎的 resize、相机和像素比接口实现同等行为，避免绕过引擎重复管理画布。使用原生 Canvas 2D 时，调整画布宽高后需恢复绘图变换和状态。建议限制 DPR 上限，避免高分辨率设备产生过大的渲染缓冲区。
+
+## 必须完成的适配验收
+
+至少以以下三档**游戏容器尺寸**验证；无需再从这些高度中扣除宿主 UI：
+
+| 测试目的 | 容器尺寸（CSS px） | 核心检查 |
+| --- | --- | --- |
+| 最小可用高度 | 375×524 | 核心玩法、HUD、弹窗和主要操作不溢出、不遮挡 |
+| 标准设计基准 | 402×646 | 主要视觉、信息层级和交互流程完整 |
+| Android 长屏 | 412×732 | 背景延展、纵向布局和触控坐标保持正确 |
+
+开发时可以使用浏览器或嵌入容器模拟；交付前以实际生产构建的 `dist/` 验证主要状态，并覆盖一次运行中的容器尺寸变化。
+
+- [ ] 根容器、Canvas 和背景始终填满 WebView，无黑边或未覆盖区域。
+- [ ] 没有使用手机整屏高度、固定宽高比或重复扣减原生栏位及安全区。
+- [ ] 三档尺寸下关键角色、按钮、文字、HUD 和判定区域完整可见。
+- [ ] 开始、游玩、暂停、结算及游戏实际提供的其他主要界面都能操作。
+- [ ] 缩放或尺寸变化后，UI、画面和触控命中区域保持一致。
+- [ ] 页面无意外滚动条，未用裁切隐藏关键内容溢出。
+
+交付时说明实际验证的尺寸、界面状态与结果。若未能进行真机或宿主 WebView 验证，应明确该验证范围；不能将浏览器模拟描述为真机验收。

package/dist/skills/zh-CN/evomeme-ui/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "evomeme UI"
+  short_description: "为 evomeme平台游戏落实 WebView 容器适配、UI 布局与多尺寸验收"
+  default_prompt: "请使用 $evomeme-ui 为将上线 evomeme平台的游戏实现 UI 与响应式适配，并验证三档游戏容器尺寸。"

package/dist/skills/zh-CN/evomeme-ui/references/host-layout.md

@@ -0,0 +1,69 @@
+# 宿主原生布局与 WebView 尺寸参考
+
+本资料整理自项目的《游戏 WebView 多设备尺寸适配规范》。用于理解设计基准、估算可用区域和建立测试矩阵。游戏运行时始终使用容器实时测量值，不能将以下原生公式移植到网页中再次扣减高度。
+
+## 402px 设计基准与原生 rem
+
+App 设计基准宽度为 402px，在该宽度下 `1rem = 16`。这里的设计尺寸对应 React Native 布局逻辑单位 dp，不是设备物理像素。
+
+原生层在 `app/_layout.tsx` 中按设备窗口逻辑宽度 `W` 调整 NativeWind 的 rem：
+
+```text
+缩放比例 S = W / 402
+原生 1rem = 16 × W / 402
+```
+
+| 窗口宽度 W | 原生 1rem（约） |
+| ---: | ---: |
+| 360 | 14.33 |
+| 375 | 14.93 |
+| 393 | 15.64 |
+| 402 | 16.00 |
+| 430 | 17.11 |
+
+WebView 内网页的 CSS rem 取决于网页自己的根字号，默认通常为 16 CSS px，不会继承上述 NativeWind 动态 rem。
+
+## 原生层游戏区域估算
+
+```text
+H_game ≈ H_window - safeTop - safeBottom - 8.25rem
+```
+
+| 原生区域 | NativeWind 尺寸 | 402px 基准下的逻辑高度 |
+| --- | --- | ---: |
+| Tab Bar 主体 | h-13 / 3.25rem | 52 |
+| Tab Bar 上下间距 | py-1 × 2 / 0.5rem | 8 |
+| 完整 Tab Bar | 3.75rem | 60 |
+| 游戏信息及操作区 | h-18 / 4.5rem | 72 |
+| 固定扣减合计 | 8.25rem | 132 |
+
+原生 rem 随宽度缩放，因此：
+
+```text
+固定扣减高度 = 8.25 × 16 × W / 402
+             = 132 × W / 402
+             ≈ 0.32836W
+
+预计 WebView 宽度 = W
+预计 WebView 高度 ≈ H - safeTop - safeBottom - 0.32836W
+```
+
+W 为 360、375、393、402、430 时，固定扣减高度分别约为 118.2、123.1、129.0、132、141.2 个逻辑单位。宿主已经完成这些扣减，游戏内部直接填充 WebView。
+
+## 设备估算矩阵
+
+以下是原规范给出的代表设备与安全区假设，不是设备检测规则。系统版本、显示缩放、横竖屏变化和 Android 厂商实现可能产生约 5–15px 差异；实际可用尺寸仍以测量为准。
+
+| 代表设备 | 屏幕逻辑尺寸 | 安全区假设（上/下） | 预计 WebView 尺寸 | 宽高比 W:H |
+| --- | --- | --- | --- | --- |
+| iPhone SE 2/3 | 375×667 | 20 / 0 | 375×524 | 1:1.40 |
+| iPhone 13 mini | 360×780 | 50 / 34 | 360×578 | 1:1.61 |
+| iPhone 12/13/14 | 390×844 | 47 / 34 | 390×635 | 1:1.63 |
+| iPhone 14 Pro / 15 | 393×852 | 59 / 34 | 393×630 | 1:1.60 |
+| iPhone 16 Pro / 17 | 402×874 | 62 / 34 | 402×646 | 1:1.61 |
+| iPhone Plus / Pro Max | 430×932 | 59 / 34 | 430×698 | 1:1.62 |
+| Android 紧凑型 | 360×800 | 24 / 24 | 360×634 | 1:1.76 |
+| Android 常规型 | 384×832 | 24 / 24 | 384×658 | 1:1.71 |
+| Android 大屏型 | 412×915 | 24 / 24 | 412×732 | 1:1.78 |
+
+原规范的估算范围约为 1:1.40～1:1.78；现代 iPhone 主要在 1:1.60～1:1.63，主流 Android 主要在 1:1.70～1:1.78。最低可用高度参考 375×524，主要设计参考 402×646，长屏参考 412×732。实际容器超出这个范围时，也应继续响应容器变化。