evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/en-US/threejs-3d-game/references/file-structure.md

@@ -0,0 +1,353 @@
+# 3D Game File Structure Specification
+
+This document defines the standard file structure for browser 3D games. The project is a Vite + React + React Three Fiber application: the 3D view is managed by R3F / Three.js, and the DOM UI is managed by React. **This is the only normative source for all 3D code structure and config files in this plugin**. `game-director`, `game-designer`, `game-art`, `threejs-aaa-graphics-builder`, and `game-test` MUST follow this file when a 3D project's config or directory structure is involved.
+
+**Core principle:** React Three Fiber (`<Canvas>`) owns the 3D / WebGL world; React DOM (`src/ui`) owns all formal HUDs, menus, dialogs, settings, inventory, quests, and narrative panels. R3F `<Html>` MUST NOT replace the formal HUD. Cross-layer communication goes through the **event bus**, **input actions**, and explicit **simulation state**.
+
+## `/public/config.json` Rules
+
+`/public/config.json` is the game's external runtime configuration file and is output unchanged as `/dist/config.json` after build.
+
+### Storage Rules
+
+1. All user-tunable colors, gameplay parameters, balance values, and asset URLs MUST be written into `/public/config.json`; hardcoding them in business code is prohibited.
+2. Game code MUST read config through `fetch("./config.json")` (relative path); using the absolute path `/config.json` is prohibited; directly `import config.json` from the `src` directory is prohibited.
+3. The same user-tunable value MUST NOT be repeatedly hardcoded in React, R3F, Three, or CSS.
+
+### Structure Requirement: Strictly Flat
+
+config **MUST be a flat top-level object**. Each parameter is a direct top-level key. Grouping by `assets`, `images`, `gameplay`, `colors`, `params`, etc. is **prohibited**:
+
+```json
+// Correct - flat
+{ "image_background": { ... }, "player_move_speed": { ... } }
+
+// Wrong - nested groups are prohibited
+{ "assets": { "background": { ... } }, "gameplay": { "speed": { ... } } }
+```
+
+Each key falls into one of two categories:
+
+- **Visible parameters** (keys that do not start with `_`): exposed for user editing and MUST use the standard schema below.
+- **Invisible parameters** (keys that start with `_`): internal fields (such as `_game_name`, `_config_version`); raw values are allowed and the schema is not used.
+
+### Visible Parameter Schema
+
+```json
+"key_name": {
+  "value": <actual value>,
+  "type": "int" | "float" | "color" | "bool" | "string" | "audio" | "image" | "video",
+  "label": "<user-language label, <=10 chars>",
+  "min": <number>,
+  "max": <number>
+}
+```
+
+Rules:
+
+- `type` can only be `int`, `float`, `color`, `bool`, `string`, `audio`, `image`, or `video`.
+- `label` uses the user's language and is at most 10 characters long.
+- `min`/`max` appear only for `int`/`float`, and both MUST be provided together.
+- `type: "color"` uses a hexadecimal color string.
+- `type: "image"` MUST additionally declare `"image_type": "Asset"` and `"size": "widthxheight"` (for example `"1440x2560"`) so display size can be judged when true image dimensions cannot be read.
+- For `audio`/`image`/`video`, `value` MUST be a real accessible external `http(s)` URL; local relative paths are prohibited. Images/meshes are generated asynchronously upstream; a transient 404 URL does not mean the asset is invalid, and the asset MUST NOT be rewritten, replaced, or deleted for that reason.
+
+### Example
+
+```json
+{
+  "_game_name": "Example 3D Game",
+  "_config_version": 1,
+  "player_move_speed": { "value": 4.5, "type": "float", "label": "Move Speed", "min": 1, "max": 12 },
+  "camera_follow_lag": { "value": 0.12, "type": "float", "label": "Cam Lag", "min": 0.01, "max": 0.5 },
+  "theme_background_color": { "value": "#0b1020", "type": "color", "label": "Bg Color" },
+  "enable_shake": { "value": true, "type": "bool", "label": "Shake" },
+  "start_button_text": { "value": "Start Game", "type": "string", "label": "Start Text" },
+  "bgm_main": { "value": "https://example.com/bgm.mp3", "type": "audio", "label": "BGM" },
+  "model_player": {
+    "value": "https://example.com/player.glb",
+    "type": "string",
+    "label": "Player"
+  }
+}
+```
+
+Code-side read pattern:
+
+```ts
+await loadConfig()
+const speed = getSetting<number>('player_move_speed', 4.5)
+```
+
+## `/user_upload` Directory Rules
+
+`/user_upload` is a virtual directory for user-uploaded assets. Files under it are not real asset files; they only store asset links or metadata.
+
+1. When user-uploaded assets are needed, first read the corresponding file under `/user_upload` and extract the real URL.
+2. Do not treat `/user_upload/...` as a local asset path; final code MUST reference the extracted real URL.
+
+## Deployment and Path Rules
+
+1. The final deployment artifact is fixed as `/dist`, deployed as a static site, and runtime resources MUST be directly accessible by the browser.
+2. `/dist` MUST run independently of the source directory: all runtime code, resources, chunks, CSS, audio, images, models, and configuration may reference only files inside `/dist` or external `http(s)` links. Relative paths or build-artifact internal paths MUST be used, and runtime references pointing to the source directory are strictly prohibited.
+3. `vite.config.ts` MUST set `base: './'`, making build artifacts use relative paths (`./assets/...`) so they work when deployed under any subpath.
+4. All runtime string paths (`fetch`, `Audio`, dynamic `import`, CSS `url()`, `GLTFLoader`) MUST use `./` relative paths or external `http(s)` URLs. Absolute paths starting with `/` (site root paths) are prohibited.
+
+## Required Files at Project Root
+
+- `/project.md`: the only source of game requirements (design document); all subsequent development is based on this file.
+- `/public/config.json`: the runtime configuration and asset-binding contract.
+- `/src`: Vite + React + R3F source code.
+- `/dist`: build artifact and deliverable.
+
+## Tech Stack
+
+| Tech | Role |
+| --- | --- |
+| Vite | Build and development server |
+| React | App shell and DOM UI |
+| React Three Fiber (R3F) | Mounts Three.js `Canvas`, lifecycle, and `useFrame` orchestration |
+| Three.js | WebGL rendering, camera, lights, meshes, `AnimationMixer`, GLB, etc. |
+| Tailwind CSS v4 | DOM UI styling |
+| mitt | Event bus between React UI and game runtime |
+| `public/config.json` | External runtime configuration |
+| pnpm | Package manager (`pnpm install` / `pnpm build`) |
+
+## Required Top-Level Structure
+
+```text
+.
++-- index.html
++-- package.json
++-- public/
+|   +-- config.json
+|   +-- assets/            # Optional static asset directory
++-- src/
+    +-- main.tsx
+```
+
+Full recommended tree:
+
+```text
+.
++-- index.html
++-- package.json
++-- pnpm-lock.yaml
++-- tsconfig.json
++-- vite.config.ts
++-- public/
+|   +-- config.json
+|   +-- assets/
++-- src/
+    +-- main.tsx
+    +-- App.tsx
+    +-- index.css
+    +-- config/
+    |   +-- config.ts          # fetch public/config.json -> loadConfig() / getSetting()
+    |   +-- types.ts           # Config types (optional)
+    +-- game/
+    |   +-- bridge/
+    |   |   +-- gameBus.ts     # mitt event bus
+    |   |   +-- gameCommands.ts
+    |   |   +-- gameEvents.ts
+    |   +-- simulation/
+    |   |   +-- state.ts       # Serializable, testable game state
+    |   |   +-- systems/       # Deterministic gameplay systems
+    |   |   +-- rules.ts       # Rules with no Three / React dependencies
+    |   +-- content/
+    |   |   +-- encounters/
+    |   |   +-- items/
+    |   |   +-- maps/
+    |   +-- input/
+    |   |   +-- actions.ts
+    |   |   +-- bindings.ts
+    |   |   +-- inputState.ts
+    |   +-- assets/
+    |   |   +-- manifest.ts    # Stable asset keys, URLs, metadata
+    |   +-- audio/
+    |   |   +-- audioManager.ts
+    |   |   +-- audioHooks.ts
+    |   |   +-- audioPrefs.ts
+    |   +-- three/             # No React import; unit-testable Three modules
+    |       +-- buildWorld.ts
+    |       +-- orbitCameraRig.ts
+    |       +-- character/
+    |       +-- creatures/
+    +-- ui/
+    |   +-- components/
+    |   |   +-- GameCanvas.tsx # R3F <Canvas>, useFrame, world mount
+    |   +-- hud/
+    |   +-- menus/
+    |   +-- overlays/
+    |   +-- store/
+    |       +-- useGameUiStore.ts
+    +-- components/            # Shared DOM UI primitives (non-game business UI)
+    +-- lib/
+        +-- utils.ts
+```
+
+## File Responsibilities
+
+| Path | Owner | Role |
+| --- | --- | --- |
+| `index.html` | tech | Shell page; mounts `#root` / `#app` and loads `/src/main.tsx`. |
+| `package.json` | tech | Scripts and dependencies; MUST expose `build` (usually also `dev`). |
+| `public/config.json` | product / ops | Runtime-tunable parameters and content pointers; prefer changing this over source. |
+| `src/main.tsx` | tech | Startup: after `loadConfig()`, `createRoot(...).render(<App />)`. |
+
+## Deliverables
+
+The game is not complete unless **both** exist:
+
+| Artifact | When | Why |
+| --- | --- | --- |
+| `public/config.json` | Always in the source tree | Ops/runtime configuration source; copied into `dist/` by Vite build. |
+| `dist/index.html` | After `pnpm build` | Deliverable static entry point. |
+
+After a successful build, `dist/config.json` (`public/config.json` runtime copy) should also exist.
+
+## Package Management and Scripts
+
+- Package manager: **pnpm** (default; do not use npm/yarn).
+- Install: `pnpm install`
+- Production build: `pnpm build`
+- Local development: `pnpm dev`
+
+Minimum script contract:
+
+```json
+{
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsc && vite build",
+    "preview": "vite preview --host 127.0.0.1"
+  }
+}
+```
+
+Verification before a new project is ready:
+
+1. `public/config.json` exists.
+2. `pnpm install` succeeds.
+3. `pnpm build` succeeds and outputs **`dist/index.html`** (and `dist/config.json`).
+4. Entry chain is healthy: `index.html` -> `src/main.tsx` -> `loadConfig()` -> `<App />` (`GameCanvas` + DOM HUD).
+
+## Startup Flow
+
+```text
+main.tsx
+  -> loadConfig()
+  -> createRoot(...).render(<App />)
+App.tsx
+  -> GameCanvas (R3F <Canvas>, World + useFrame)
+  -> Hud / MobileHud
+  -> PauseMenu, overlays (as needed)
+
+GameCanvas.tsx
+  -> buildWorldInto / GLTFLoader (via game/three)
+  -> useFrame: simulation step + scene sync + camera
+```
+
+`GameCanvas.tsx` is the **WebGL <-> React DOM boundary**. DOM UI is overlaid above Canvas (composed in `App`). On unmount, dispose Three resources and bus subscriptions.
+
+## Layering Rules
+
+### R3F / 3D Runtime (`src/ui/components/GameCanvas.tsx` + `src/game/three/`)
+
+**`GameCanvas.tsx` (mount boundary) is responsible for:**
+
+- Creating the R3F `<Canvas>` (shadows, `gl`, `dpr`, and other defaults are in `engine-runtime.md`)
+- `useFrame` orchestration: read input/simulation -> update `Object3D` or state -> `mixer.update` -> camera (rendering is left to R3F; unless offscreen, do not manually call `renderer.render`)
+- Assembling the scene root: `buildWorldInto(group)`, asynchronous GLB loading
+- Disposing geometry, materials, `AnimationMixer`, and bus subscriptions on StrictMode remount / unmount
+
+**`game/three/*` (pure Three modules) is responsible for:**
+
+- Scene construction, math, and loading helpers with no React imports
+- Not secretly changing DOM outside React refs
+
+Emit gameplay facts with `gameBus.emit()`; accept UI commands (pause, reset, use item, etc.) through `gameBus` / command types.
+
+**Prohibited:**
+
+- `import` React components or hooks inside `game/three`
+- Piling formal HUD/menus into R3F `<Html>`
+- Scattering touch joystick / gesture mapping in `useFrame` or random components (centralize in `game/input` or UI -> unified actions)
+
+### React DOM UI (`src/ui` + `src/components`)
+
+**Responsible for:** HUD, bars, buttons, main/pause/settings menus, inventory, quests, dialogs, results, toast; emits `command:*` through `gameBus`; reads runtime state through `useGameUiStore()` (or equivalent).
+
+**Prohibited:** directly taking `Mesh` / `Object3D` inside HUD and changing `position` every frame; writing core rules in UI components; putting per-game business UI into `src/components`; duplicating joystick bindings across multiple components without going through `game/input`.
+
+### Simulation (`src/game/simulation`)
+
+Responsible for player/enemy state, inventory, quests, combat values, pure rules, and serializable saves. Must have no Three.js / R3F / React dependencies.
+
+### Content (`src/game/content`)
+
+Responsible for levels, maps, encounters, waves, items, rewards, and other static design data. React components and the `Object3D` lifecycle are prohibited from coupling to it.
+
+### Input (`src/game/input`)
+
+Responsible for unified actions, keyboard/mouse/virtual joystick/touch bindings, and the semantic input surface shared by UI and `GameCanvas`. Undocumented scattered hardcoded bindings are prohibited; directly rewriting persistent simulation root state is prohibited.
+
+### Assets (`src/game/assets`)
+
+Responsible for stable keys, URLs, types, and metadata for glTF / textures / audio / VFX. Hardcoding `"/foo/bar.glb"` throughout gameplay, UI, and scene modules is prohibited.
+
+### Audio (`src/game/audio`)
+
+Responsible for reading BGM/SFX paths and toggles from config, Web Audio / HTMLAudio playback and dispose, listening to `gameBus` to map gameplay facts to sound, and applying `command:audio-prefs` emitted by HUD. Playing in-game SFX with `new Audio()` inside HUD is prohibited; creating new audio sources or footstep loops every frame in `useFrame` is prohibited; in-game BGM MUST NOT remain after exit/results/failure/restart. Unlock, event hooks, and cleanup details are in `engine-audio.md`.
+
+## Event Bridge Rules
+
+Files: `src/game/bridge/gameBus.ts`, `gameEvents.ts`, `gameCommands.ts`.
+
+Naming:
+
+- `command:*` - React -> game runtime
+- `game:*` - global session / world events
+- `player:*` - player state
+- `enemy:*` - enemy state
+- `ui:*` - UI-facing events
+- `game:feedback` / `player:movement` - in-game feedback cues (SFX + VFX); payload is plain data
+
+When adding events, update the `gameCommands.ts` / `gameEvents.ts` types in the same change.
+
+## Diagnostics and Test Hooks
+
+Install when `GameCanvas` mounts and clean up on unmount; type declarations go in `src/vite-env.d.ts`.
+
+- `window.__THREE_GAME_DIAGNOSTICS__`: renderer info, simulation snapshot, input state, entity count, etc. (for canvas inspector / AAA scorecard).
+- `window.__THREE_GAME_TEST_HOOKS__`: `seed` / `setState` / `setPausedForScreenshot` / `setReducedMotion` / `hideDebugUi` (for visual regression and bot playtest).
+
+Put deterministic random in `src/lib/random.ts` or `src/game/simulation/random.ts`; business paths are prohibited from using `Math.random`.
+
+## Hard Methodology
+
+- **Keep layering:** `game/three` MUST NOT import React; DOM UI MUST NOT directly drive `Object3D`. Prefer `gameBus` or a single input/simulation facade.
+- **Simulation first:** rules are in `game/simulation`, not in `useFrame` or `Hud.tsx`.
+- **Centralized input:** physical -> semantic mapping is in `game/input`.
+- **Content is data:** levels/maps/items are in `game/content`.
+- **Asset directory:** glTF / textures / audio go through `manifest.ts` or config keys.
+- **Centralized in-game audio:** only `game/audio`; preferences go through the bus.
+- **Centralized config:** tunable parameters are in `public/config.json`.
+- **UI placement:** business DOM UI is in `src/ui`; shared primitives are in `src/components`; formal HUD is never an R3F child node.
+- **Verification:** run `pnpm build` after meaningful changes.
+
+## Anti-Patterns
+
+- Building full menus / inventory / settings inside `useFrame`
+- Grabbing scene-internal refs from arbitrary React components and changing mesh everywhere
+- Putting combat rules into `Hud.tsx`
+- Using `Mesh.userData` as a persistent database for UI/saves
+- Input and state drifting from multiple sources
+- Copying the same touch action mapping across multiple files
+- Hardcoding the same glTF/texture URL string in multiple places
+- Using `src/main.ts` instead of `src/main.tsx` while following this specification
+- Replacing this layout with CRA, Next.js, or npm-only scaffolding (unless the user asks)
+
+## Output Expectations
+
+When adding features, state the owning layer (R3F/Three orchestration / React UI / Simulation / Content / Input / Assets / Audio) and why. Route cross-layer behavior through `gameBus` (or the agreed single facade), and update event types. Confirm with `pnpm build`.

package/dist/skills/en-US/threejs-aaa-graphics-builder/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: threejs-aaa-graphics-builder
+description: Upgrade Three.js scenes with high-quality art direction, materials, lighting, shaders, VFX, asset acquisition, and render budgets. Use when 3D browser games need measurable visual quality improvement beyond prototype graphics.
+---
+
+# Three.js AAA Graphics Builder
+
+## Purpose
+
+Own the production graphics pass. Convert basic screenshots into authored, high-density, performance-aware visual experiences.
+
+
+## Use When
+
+Screenshots still look basic, models look primitive, worlds are sparse, UI/world art feels generic, or the user asks for premium, AAA, high-fidelity, showcase, or less-basic graphics.
+
+## Required References
+
+These references are required phase-entry gates, not optional reading:
+
+- Load `../game-art/references/scene-profiles.md` and select a `scene_profile_id` before world kit, lighting polish, or any claim that World/environment is authored. Read only the **World + 3D · Lighting + Entities + Reject** sections for that profile; this skill executes the production pass against it.
+- Load `references/visual-scorecard.md` before scoring, judging completion, or making any premium/AAA/showcase claim.
+- Load `references/implementation-blueprint.md` before changing graphics architecture, materials, VFX, rendering, diagnostics, or broad visual systems.
+- Load `references/model-recipes.md` before building or upgrading hero/player, obstacle, enemy, pickup, world-kit, material, or prop models.
+- Load `references/render-recipes.md` before changing lighting, tone mapping, shadows, fog, post-processing, materials, or render composition.
+- Load `references/technical-art.md` before premium/AAA/showcase graphics work, shaders/material systems, VFX systems, generated/imported asset cleanup, LOD/instancing work, or visual changes that could affect browser performance.
+- Load `references/shader-cookbook.md` before writing any custom shader, `onBeforeCompile` injection, material recipe, sky, or post-processing chain; use its proven values and GLSL patterns instead of improvising.
+- Load `references/checklists/aaa-game-quality-gate.md` and `references/checklists/aaa-visual-scorecard.md` before declaring a game premium, AAA, showcase, complete, release-ready, or less basic.
+- Load the relevant checklist before focused work: `references/checklists/procedural-model-quality.md`, `references/checklists/material-lighting-quality.md`, `references/checklists/performance-safe-visual-detail.md`, or `references/checklists/technical-art-quality.md`.
+- Load `references/graphics-prompt-templates.md` only when the user asks for reusable prompts, a graphics-pass prompt, or a task template.
+
+For broad "still looks basic", premium, AAA, high-fidelity, showcase, or less-basic graphics work, load the scene-profiles paradigm (3D Lighting rail) plus all five core references (`visual-scorecard`, `implementation-blueprint`, `model-recipes`, `render-recipes`, `technical-art`) as the first action in the phase. Track them in a reference ledger with yes/no, path, and failure reason. Do not mark the graphics phase complete while any required reference is skipped.
+
+External asset sourcing gate:
+
+- For premium/AAA/showcase/high-fidelity/less-basic graphics with a hero/player, character, creature, boss, vehicle, ship, building, weapon, signature prop, complex pickup, or hero environment piece, load `../game-asset-mesh-generator` before deciding procedural geometry is enough.
+- For concept needs, texture/material references, decals, logos, faction marks, icons, GUI art, skies, backgrounds, title/menu art, or image-to-3D inputs: prefer procedural/CSS/canvas UI art; use user-supplied local images via `evomeme_upload_game_asset` + MCP `evomeme_image_to_mesh`, or remote MCP `evomeme_generate_game_image` when available.
+- Create an asset sourcing ledger for each high-value surface: procedural / ../game-asset-mesh-generator / hybrid / user-provided, plus outputs or skip reason.
+- `not-needed` is valid only after the relevant path was considered and the ledger explains why external generation would not improve a non-hero support surface, or why an attempted MCP/CDN call shows a real blocker.
+- For premium hero surfaces, procedural-only is not an allowed final answer unless there is real blocker evidence. At least one high-value surface must show a 3D generator task ID, downloaded GLB/GLTF/FBX path, user-provided/remote 2D asset path, or documented hybrid chain.
+
+## Workflow
+
+1. Capture or inspect active desktop/mobile screenshots.
+2. Confirm or select a `scene_profile_id` from `../game-art/references/scene-profiles.md` (World / 3D · Lighting / Entities). If missing, write it before upgrading surfaces.
+3. Score visuals across art direction, hero/player, obstacles, rewards, world, materials, render, VFX, UI, and performance evidence.
+4. Add missing graphics architecture: material library, procedural textures/decals, model factories, world prop kit, technical-art budget, VFX system, render pipeline, diagnostics.
+5. Fill the external asset sourcing ledger per surface: procedural Three.js factory, user-provided/remote 2D reference, `../game-asset-mesh-generator` 3D generation, or a hybrid.
+6. Upgrade every weak visible surface, not only one hero object. World layers must match the chosen scene-profiles paradigm (Play / Near / Mid / Far / Motion).
+7. Add lighting/render/material polish after authored forms exist, following the paradigm's Lighting stack intent and `references/render-recipes.md`.
+8. Add event-driven VFX tied to gameplay state.
+9. Re-score screenshots against the calibration anchors, citing the inspector's measured metrics. Continue until every premium category is at least 2/3 or report exact blockers.
+10. Run the fresh-eyes review per `references/visual-scorecard.md` before finalizing premium/AAA/showcase claims.
+11. Verify renderer diagnostics against the render budget table, technical-art budget, desktop/mobile screenshots, console/page errors, canvas pixels, imported asset budgets, and playability.
+
+## Core Rule
+
+Do not make primitives look AAA by adding glow. First build authored forms, then materials, then lighting, then effects.
+
+## Final Response
+
+Report the reference ledger, external asset sourcing ledger, technical art brief, score before/after, production surfaces upgraded, files changed, screenshots/artifacts, renderer diagnostics, imported asset diagnostics when relevant, VFX readability and render-budget tradeoffs, and remaining blockers. For premium/AAA/showcase claims, include the filled visual scorecard exactly as defined in `references/visual-scorecard.md`, including average and automatic failures remaining.

package/dist/skills/en-US/threejs-aaa-graphics-builder/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Three.js AAA Graphics Builder"
+  short_description: "Comprehensively improve a 3D game's models, materials, lighting, effects, and rendering quality"
+  default_prompt: "Please use $threejs-aaa-graphics-builder to improve this 3D game's overall visual quality, and refine its models, materials, lighting, effects, and performance presentation."
+
+policy:
+  allow_implicit_invocation: false

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

@@ -1,12 +1,18 @@
 ---
 name: evomeme-cloud-fs
-description: 讲解 evomeme工作区 init、.evomemeignore，以及源码提交等云端文件 MCP。在执行 npx -y evomeme@latest init、编辑忽略规则，或调用 evomeme_submit_game_code / evomeme_upload_game_asset 时使用。
+description: 讲解 evomeme工作区 init、.evomemeignore，以及云端文件 MCP。在执行 npx -y evomeme@latest init、编辑忽略规则，或调用 evomeme_reinit_project / evomeme_submit_game_code / evomeme_upload_game_asset 时使用。
 ---
 
 # evomeme云端文件系统
 
 讲解本地工作区初始化、提交忽略规则，以及源码提交 / 二进制上传相关 MCP。
 
+| 工具（中文名称） | 实际操作与结果 | 何时使用 |
+| --- | --- | --- |
+| `evomeme_reinit_project`（重新初始化项目） | 创建新的云端 thread，并更新当前工作区绑定，返回工作区与 `thread_id`。thread 是云端作品/提交归属标识，不是聊天记录或文件路径。 | 云端明确报 thread 不存在，且需要重新绑定当前工作区时；按下文确认要求执行。 |
+| `evomeme_submit_game_code`（提交游戏代码） | 提交允许的项目文件与构建产物，全量覆盖云端版本，返回 `thread_id`、`checkpoint_id` 与文件数量；checkpoint 是本次提交的云端版本标识。 | 项目已构建并需要提交到云端时。失败只返回真实错误，不自动重建 thread。 |
+| `evomeme_upload_game_asset`（上传云端素材） | 上传二进制素材，审核通过后返回公开 URL；不提交项目源码。 | 游戏或视频参考需要公开图片、模型、音频、视频链接时，使用 [上传技能](../evomeme-tos-upload/SKILL.md)。 |
+
 鉴权失败后再加载 `../evomeme-login/SKILL.md`；不要预防性加载登录技能。
 
 ---
@@ -20,6 +26,7 @@ description: 讲解 evomeme工作区 init、.evomemeignore，以及源码提交
 - 若不存在则生成默认 **`.evomemeignore`**
 - 把包内 skill 复制到工作区 **`.codex/skills/`**
 - 确认本机登录态（供后续 MCP 使用）
+- 若缺少本地绑定，创建云端作品并保存 thread_id；已有绑定时沿用，不检查远端是否失效
 
 npm 包名为 **`evomeme`**（可执行入口 `evomeme`）。
 
@@ -42,7 +49,7 @@ npx -y evomeme@latest install --ide codex
 ### 注意
 
 - init 是**工作区准备**（忽略规则、skills、登录态），不是做游戏前必须完成的门槛。
-- 开发过程中不必为了作品绑定去跑 init；需要提交时直接调用 `evomeme_submit_game_code` 即可（见下文）。
+- 提交前必须已有作品绑定，可通过 CLI init 或显式调用 `evomeme_reinit_project` 首次创建。已有 thread_id 失效时，CLI init 不会替换它；需要用户明确要求后调用重新绑定工具。
 - 已存在的 `.evomemeignore` **不会被覆盖**；skills 会按包内内容复制/更新到 `.codex/skills/`。
 
 ---
@@ -84,14 +91,34 @@ npx -y evomeme@latest install --ide codex
 
 | 工具名 | 功能 |
 | --- | --- |
+| `evomeme_reinit_project` | 显式创建新 thread 并替换工作区绑定，清除旧 checkpoint；不提交文件。也可用于首次绑定。 |
 | `evomeme_submit_game_code` | **游戏发布**（非纯源码上传）：按 `.evomemeignore` 收集并全量覆盖云端作品，**必须包含可运行的 `dist/`**；不可撤销。 |
-| `evomeme_upload_game_asset` | 将受支持的本地图片、音频或视频交给服务端上传 TOS；内容审核通过后才返回公开 `asset_url`。其他类型禁止上传。 |
+| `evomeme_upload_game_asset` | 将受支持的本地图片、音频、视频或常见 3D 模型（GLB/GLTF/FBX/OBJ/STL）交给服务端上传 TOS；内容审核通过后才返回公开 `asset_url`。其他类型禁止上传。 |
+
+### `evomeme_reinit_project`
+
+参数：`workspace_dir`（可选，默认 MCP 进程当前工作目录）、`name`（可选，新作品名称）。Agent 调用时应明确传入当前项目根目录的绝对路径，确保新 id 绑定到正确工作区。即使已有绑定也会创建新的云端 thread；成功后覆盖 `.evomeme/config.json` 并清除旧 checkpoint_id，不删除旧云端作品。创建失败则保留旧绑定并返回真实错误，不自动重试。
+
+只在用户明确要求初始化或重新绑定时调用。提交失败时应把原始错误交给用户，不得自动调用本工具恢复。重新绑定成功后，文件提交仍需单独调用提交工具。
+
+#### thread_id 报错后的处理
+
+当 `evomeme_submit_game_code` 明确报错「缺少 thread_id 绑定」「thread 不存在」或「thread 已失效」时，**重新创建 thread_id 的工具是 `evomeme_reinit_project`**。不要反复调用提交工具期待它自动创建 id，也不要使用 CLI `init` 修复已有的失效绑定（CLI 会沿用旧 id）。
+
+1. 先向用户展示提交工具返回的真实错误，说明重新绑定会创建新的云端作品并清除本地旧 checkpoint_id，旧云端作品不会被删除。
+2. 用户明确要求重新创建或重新绑定后，单独调用 `evomeme_reinit_project`，传入当前项目根目录 `workspace_dir`，可用 `name` 传入游戏当前正式名称。已有此授权时直接执行，不重复确认。
+3. 初始化成功后，使用返回的新 thread_id；工具已经写入工作区 `.evomeme/config.json`，无需手动修改。若仍需完成原提交，再单独调用 `evomeme_submit_game_code`，使用同一工作区及原提交的 `name`、`cover_url`，并遵守提交前检查。
+4. 重新初始化失败则展示原始错误并停止，不继续提交、不循环创建新 thread。
+
+应结合错误正文判断原因，不能把所有 `40401` 都当作 id 丢失。若错误表示无权访问、作品已发布，或属于登录、网络、文件校验问题，不要直接套用重建流程。
 
 ### `evomeme_submit_game_code`
 
 把当前工作区里按 `.evomemeignore` 收集到的 **utf-8 文本源码**，全量同步到云端作品。
 
-**硬性约束：任何二进制文件都不得通过本工具上传**（含图片、模型、音视频、字体、压缩包等）。源码提交只收集文本；受支持的图片、音频和视频只能经 `evomeme_upload_game_asset` 上 TOS，模型、字体、压缩包和其他类型不支持上传。提交前还必须通过下文的发布产物门禁；发现任一二进制或绝对本地依赖时，禁止调用本工具。
+只使用已有 thread_id 提交一次。缺少本地绑定、thread 失效或其他提交错误会直接返回；不创建新 thread，不在失败后重新登录并重提。失败不改写原绑定和 checkpoint_id。
+
+**硬性约束：任何二进制文件都不得通过本工具上传**（含图片、模型、音视频、字体、压缩包等）。源码提交只收集文本；受支持的图片、音频、视频和常见 3D 模型（GLB/GLTF/FBX/OBJ/STL）只能经 `evomeme_upload_game_asset` 上 TOS，字体、压缩包和其他未列出类型不支持上传。提交前还必须通过下文的发布产物门禁；发现任一二进制或绝对本地依赖时，禁止调用本工具。
 
 可选参数：
 
@@ -160,11 +187,11 @@ npx -y evomeme@latest install --ide codex
   https://www.evomeme.com/profile/works/draft
 
   同时告知：可在该页面查看草稿，并在 evomeme中自行将游戏发布出来。不要只报「提交成功」而不给链接。
-- **失败**：MCP 结果带 `isError`，正文为错误说明。把原文展示给用户；若错误指向登录 / token 失效，再加载 `../evomeme-login/SKILL.md` 恢复后重试原提交。
+- **失败**：MCP 结果带 `isError`，正文为错误说明。把原文展示给用户；若错误指向 thread_id 缺失、不存在或失效，按上文「thread_id 报错后的处理」使用 `evomeme_reinit_project` 重新创建绑定；若错误指向登录 / token 失效，再加载 `../evomeme-login/SKILL.md` 恢复后重试原提交。
 
 ### `evomeme_upload_game_asset`
 
-将受支持的本地图片、音频或视频交给服务端上传 TOS，内容安全审核通过后才返回公开 `asset_url`；其他类型禁止上传。提交源码前处理媒体资源时优先用本工具；说明见 `../evomeme-tos-upload/SKILL.md`。
+将受支持的本地图片、音频、视频或常见 3D 模型（GLB/GLTF/FBX/OBJ/STL）交给服务端上传 TOS，内容安全审核通过后才返回公开 `asset_url`；其他类型禁止上传。提交源码前处理媒体 / 模型资源时优先用本工具；说明见 `../evomeme-tos-upload/SKILL.md`。
 
 ---
 

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

@@ -35,7 +35,7 @@ description: 用生图 MCP 生成 9:16 竖屏游戏封面（含大字标题、
    - 一句话玩法与视觉主体；
    - 美术风格关键词（如像素、扁平卡通、赛博等）；
    - 主色与氛围。
-3. 可选：若已有强风格参考图的公开 URL，可作为 `reference_image_url`（须与本游戏一致）。
+3. 可选：查看与本游戏一致的风格参考图，将其配色、线条与渲染特点写入提示词。需要直接引用附件或其他目录的图片时，必须先将真实图片文件复制到本次工作区 `assets/`，确认可读取后再通过 `reference_ids` 提供其工作区相对素材 ID（例如 `assets/references/cover-style.png`），并显式传入同一工作区的 `workspace_dir`；已有 `assets/` 图片直接复用，避免覆盖同名不同内容的文件。不得传入原始附件绝对路径或猜测 ID。
 
 ---
 
@@ -45,13 +45,12 @@ description: 用生图 MCP 生成 9:16 竖屏游戏封面（含大字标题、
 
 | 参数 | 值 |
 | --- | --- |
-| `image_type` | `background`（封面为整幅竖构图，不要用 `asset` 抠图类型） |
+| `background` | `opaque`（完整不透明封面） |
 | `size` | **`1440x2560`**（强制，对应 9:16） |
-| `image_model` | **`asset-pro`**（封面用质量档；不要用 `asset-lite`） |
+| `model` | **`asset-pro`**（封面用质量档；不要用 `asset-lite`） |
 | `prompt` | 见下方提示词结构 |
-| `reference_image_url` | 可选 |
 
-禁止传入未在工具枚举中的 size（如 `1080x1920`）。`image_model` 仅允许 `asset-pro` / `asset-lite`。
+禁止传入未在工具枚举中的 size（如 `1080x1920`）。`model` 仅允许 `asset-max` / `asset-pro` / `asset-lite`。
 
 ### 提示词结构（必须覆盖）
 
@@ -67,7 +66,7 @@ description: 用生图 MCP 生成 9:16 竖屏游戏封面（含大字标题、
 
 ### 成功返回与永久保存（必须）
 
-工具会自行轮询到任务终态并返回文本元数据与 MCP `image` 内容块。从文本解析 `tos_url`（及 `job_id`、`local_path` 等）；`tos_url` 即封面公开地址。
+工具会自行轮询到任务终态，仅返回文本元数据，不返回图片 Base64 或 MCP `image` 内容块。从文本解析 `tos_url`（及 `job_id`、`local_path` 等）；`tos_url` 即封面公开地址。需要查看封面时，使用可用的图片查看工具读取 `local_path` 或打开 `tos_url`。
 
 **Agent 在生图成功后必须立刻**把该 URL 写入工作区 `public/config.json` 的固定键 **`_game_cover_url`**，作为封面永久记录。未写入不得视为封面流程完成。
 
@@ -110,8 +109,8 @@ description: 用生图 MCP 生成 9:16 竖屏游戏封面（含大字标题、
 调用前：
 
 - [ ] `size` 是否为 `1440x2560`
-- [ ] `image_type` 是否为 `background`
-- [ ] `image_model` 是否为 `asset-pro`
+- [ ] `background` 是否为 `opaque`
+- [ ] `model` 是否为 `asset-pro`
 - [ ] prompt 是否含**确切游戏名**且要求大字标题
 - [ ] prompt 背景是否与玩法/主体强相关
 - [ ] prompt 风格是否与当前游戏美术一致