@playcraft/cli 0.1.53-beta → 0.1.55-beta

package/project-template/.claude/skills/playcraft-image-processing/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: playcraft-image-processing
-description: 可玩广告流程步骤 6。对生成的图片进行后处理：缩放、裁剪、旋转、翻转、填充、格式转换、滤镜、合成等。所有操作通过 `playcraft image` CLI 命令在沙箱本地执行，无需 backend，速度快。
+description: Use when processing playable images with local transforms, platform layer separation, object segmentation, nine-patch analysis, or sprite slicing through playcraft image.
 compatibility: agent,opencode
+version: 1.1.1
+surfaces:
+  - sandbox-agent
 ---
 
 ## Skill Definition
@@ -11,13 +14,14 @@ tools:
 - bash
 - read
   prompt_extension: |
-  你是图像处理工程师。不得向 /project/ 写入；所有输出路径必须在 ta-workspace（技术美术角色）。
-  通过 bash 工具运行 `playcraft image <command>` CLI 命令进行图片处理，所有操作在沙箱本地执行，无需往返 backend。
+  你是图像处理工程师。工作素材写入当前工程的 assets/ 或当前主题素材目录；最终交付导出到工程根目录 dist/。
+  通过 bash 工具运行 `playcraft image <command>` CLI (Command Line Interface, 命令行界面) 命令处理图片。几何、格式、滤镜和合成在本地执行；图层分离、目标分割、九宫格和自动精灵分析使用平台能力。
 
 ## 我做什么
 
 - 对生成的图片进行后处理，使其符合游戏引擎和可玩广告的规格
 - 支持：缩放、裁剪、旋转、翻转、填充边距、格式转换、灰度化、模糊、色调叠加、反色、图片合成、像素化、自动裁边
+- 支持：图层分离、目标分割、九宫格拉伸边距分析、精灵图自动检测与切片
 
 ## 何时用我
 
@@ -32,7 +36,28 @@ tools:
 
 ## 命令速查
 
-所有命令格式：`playcraft image <command> --input <路径> --output <路径> [选项]`
+先查看目标子命令的 `--help`。单文件处理通常使用 `--input` / `--output`；分层、分割和切片使用 `--output-dir`，合成使用 `--base` / `--overlay`。
+
+### 图层分离与九宫格分析
+
+```bash
+# 当前云工作区分层管线：底图、可编辑图层和重建元数据
+playcraft image decompose-layers --input assets/composite.png --output-dir assets/layers
+playcraft image decompose-layers --input assets/composite.png --prompt "背景、角色和文字分别成层" --size 1.5K --output-dir assets/layers-v2
+
+# 明确需要旧管线时才选 Qwen
+playcraft image decompose-layers --input assets/composite.png --engine qwen --num-layers 4 --output-dir assets/layers-qwen
+
+# 分析面板四边的拉伸边距
+playcraft image analyze-nine-patch --input assets/panel.png --output assets/panel-analysis.json
+
+# 自动分析精灵图的行列及帧边界后切片
+playcraft image sprite-split --input assets/sheet.png --auto-detect --output-dir assets/frames
+```
+
+`decompose-layers` 默认使用 `seedream` 工作区管线，保存底图、全部图层和 `decompose-layers-meta.json`。重建时保留元数据中的相对路径、层叠顺序和边界框，不能只取预览图。`--num-layers`、`--no-safety-checker` 和 `--output-format` 是旧 Qwen 参数，不与显式 `--engine seedream` 混用。平台处理使用当前沙箱或登录用户的授权。
+
+如果原图需要从共享素材库获取，先运行 `playcraft library search`、`get`、`files`、`download`。素材包下载到新目录并保留相对路径；素材库与生成任务的完整工作流见当前可用的 `playcraft-workspace-assets` 技能。
 
 ### 几何变换
 
@@ -99,43 +124,43 @@ playcraft image overlay --base bg.png --overlay icon.png --output out.png --x 10
 
 ### 语义分割（SAM3）
 
-通过 SAM3（Segment Anything Model 3）对图片进行**开放词汇语义分割**：用文字或框 prompt 精确抠出任意对象，返回 mask 和 RGBA 透明图。
+通过 SAM3 (Segment Anything Model 3, 第三代通用分割模型) 对图片进行**开放词汇语义分割**：用文字或框 prompt 精确抠出任意对象，返回 mask 和 RGBA (Red Green Blue Alpha, 红绿蓝透明通道) 透明图。
 需要经由 backend 代理，首次冷启动约 15s，热启动约 5-10s。
 
 ```bash
 # ── 单 prompt — 文本 ──
 # 找到图中所有"logo"区域，输出 mask + RGBA
 playcraft image segment \
-  --input ta-workspace/banner.png \
+  --input assets/banner.png \
   --text "logo" \
-  --output-dir ta-workspace/segment-out
+  --output-dir assets/segment-out
 
 # ── 单 prompt — 框选区域 ──
 # 用 [x1,y1,x2,y2] 绝对像素坐标指定目标区域
 playcraft image segment \
-  --input ta-workspace/banner.png \
+  --input assets/banner.png \
   --boxes "[[50,100,300,400]]" \
-  --output-dir ta-workspace/segment-out
+  --output-dir assets/segment-out
 
 # ── 多 prompt 批量（一次调用，多个目标）──
 playcraft image segment \
-  --input ta-workspace/banner.png \
+  --input assets/banner.png \
   --prompts '[{"text":"icon"},{"text":"button"},{"text":"logo"}]' \
-  --output-dir ta-workspace/segment-out
+  --output-dir assets/segment-out
 
 # ── 调节得分阈值（默认 0.3，越低召回越多）──
 playcraft image segment \
-  --input ta-workspace/hero.png \
+  --input assets/hero.png \
   --text "character" \
   --threshold 0.2 \
-  --output-dir ta-workspace/segment-out
+  --output-dir assets/segment-out
 
 # ── 不需要 RGBA 抠图，只要 mask ──
 playcraft image segment \
-  --input ta-workspace/hero.png \
+  --input assets/hero.png \
   --text "character" \
   --no-rgba \
-  --output-dir ta-workspace/segment-out
+  --output-dir assets/segment-out
 ```
 
 **输出目录结构**：
@@ -178,16 +203,16 @@ segment-out/
 ```bash
 # ── floodfill（默认）— 本地执行，AI 生成素材首选 ──
 # 从边缘 flood-fill 移除纯色/渐变/棋盘格背景，前景纹理零损失
-playcraft image remove-background --input ta-workspace/hero_raw.png --output ta-workspace/hero.png
+playcraft image remove-background --input assets/hero_raw.png --output assets/hero.png
 
 # 调节容差（背景与前景颜色接近时增大）
-playcraft image remove-background --input ta-workspace/tile.png --output ta-workspace/tile.png --tolerance 40
+playcraft image remove-background --input assets/tile.png --output assets/tile.png --tolerance 40
 
 # 关闭边缘平滑（需要硬边像素风时）
-playcraft image remove-background --input ta-workspace/pixel_art.png --output ta-workspace/pixel_art.png --edge-smooth 0
+playcraft image remove-background --input assets/pixel_art.png --output assets/pixel_art.png --edge-smooth 0
 
 # ── ai — 调用 backend AI 模型，复杂背景照片用 ──
-playcraft image remove-background --input ta-workspace/photo.jpg --output ta-workspace/photo.png --method ai
+playcraft image remove-background --input assets/photo.jpg --output assets/photo.png --method ai
 ```
 
 **方法选择指南**：
@@ -196,7 +221,7 @@ playcraft image remove-background --input ta-workspace/photo.jpg --output ta-wor
 | `floodfill`（默认） | AI 生成的素材（纯色/灰色/棋盘格背景） | <0.5s | 零损失 |
 | `ai` | 真实照片、复杂背景 | ~1-3s | 可能褪色 |
 
-> **注意**：`--method ai` 会调用 backend API（需要沙箱 token）；`floodfill` 完全本地执行。
+> **注意**：`--method ai` 会调用后端 API (Application Programming Interface, 应用程序编程接口)，需要有效的沙箱或用户凭据；`floodfill` 完全本地执行。
 
 ## 可玩广告常见规格
 
@@ -209,11 +234,11 @@ playcraft image remove-background --input ta-workspace/photo.jpg --output ta-wor
 
 ```bash
 # 生成图片 → 缩放到规格 → 转 webp 压缩
-playcraft tools generate-image --prompt "cute hero character, transparent background" --output ta-workspace/hero_raw.png
-playcraft image resize --input ta-workspace/hero_raw.png --output ta-workspace/hero_512.png --width 512 --height 512 --fit contain
-playcraft image convert --input ta-workspace/hero_512.png --output ta-workspace/hero_512.webp --quality 85
+playcraft tools generate-image --prompt "cute hero character" --background transparent --output assets/hero_raw.png
+playcraft image resize --input assets/hero_raw.png --output assets/hero_512.png --width 512 --height 512 --fit contain
+playcraft image convert --input assets/hero_512.png --output assets/hero_512.webp --quality 85
 
 # 制作角色颜色变体
-playcraft image tint --input ta-workspace/hero_512.png --output ta-workspace/hero_blue.png --color "#0055ff"
-playcraft image tint --input ta-workspace/hero_512.png --output ta-workspace/hero_red.png --color "#ff2200"
+playcraft image tint --input assets/hero_512.png --output assets/hero_blue.png --color "#0055ff"
+playcraft image tint --input assets/hero_512.png --output assets/hero_red.png --color "#ff2200"
 ```

package/project-template/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: playcraft-workspace-assets
+description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+compatibility: agent,opencode
+version: 1.0.0
+surfaces:
+  - sandbox-agent
+---
+
+# 工作区素材工作流
+
+使用 PlayCraft CLI (Command Line Interface, 命令行界面) 的 `library` 和 `assets` 命令。运行对应子命令的 `--help` 核对参数；当前命令行缺少这些入口时，先报告需要匹配的命令行与服务版本。凭据由工作区提供。
+
+## 查找并复用素材
+
+```bash
+playcraft library search "角色" --type texture --tags character --limit 20 --json
+playcraft library facets --json
+playcraft library get <assetId> --json
+playcraft library files <assetId> --json
+playcraft library download <assetId> --output ./assets/character
+```
+
+检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+
+`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+
+## 创建持久化生成任务
+
+从 `references/requests.json` 选取所需类型的示例，将**单个请求对象**写入工程内的请求文件，并改成完整的用户需求。六种类型分别为 `image`、`audio`、`sprite`、`animation`、`model`、`video`。请求使用 JSON (JavaScript Object Notation, 数据交换格式)；参考图需同时提供 `referenceImageBase64` 和对应 `referenceImageMimeType`。模型参数以可用配置和共享契约为准。
+
+```bash
+playcraft assets estimate --request .tmp/asset-request.json
+playcraft assets generate --request .tmp/asset-request.json --client-request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId> --timeout 1800
+playcraft assets download <taskId> --output ./assets/generated-result
+```
+
+同一次生成保持 `--client-request-id` 和请求内容不变。提交结果不确定时重用原请求；拿到 `taskId` 后用 `get` 或 `wait` 恢复，不能新建任务来代替查状态。新候选使用新请求编号。`--wait --output <path>` 可合并等待和下载。
+
+命令在当前工程推断工作区和工程目录；工程外须传 `--workspace <workspaceId> --directory <directoryName>`，范围应对应目标工程。`tasks` 列出该范围任务；`cancel <taskId>` 请求取消，上游已提交请求可能继续结算。等待超时返回退出状态 75，远端任务仍可查询。
+
+下载前任务应为 `awaiting_adoption` 或 `saved`。精灵图与动画输出为完整包目录，下载会校验各文件大小与内容摘要。`queued` 和 `running` 只表示任务尚未完成；`failed`、`cancelled`、`interrupted` 应根据真实状态汇报。
+
+## 结果保存和动画版本
+
+- 生成结果保存到共享素材库：先 `assets library-targets` 获取允许的目的地，再通过 `assets library-save <taskId> --request <save-request.json>` 保存。用 `library-saves <taskId>` 查看状态，失败时 `library-retry <taskId> --save-id <saveId>` 沿用原保存任务。请求字段以命令帮助和 `asset-library-save` 共享契约为准。
+- 动画编辑：`assets animation get <taskId>` 读取草稿及修订号，`draft`、`upload-frame`、`version` 使用请求文件更新草稿、替换帧和导出版本。草稿写入结果不确定时先重新读取草稿修订号。
+- 指定动画版本下载：`assets download <taskId> --version <versionId> --output <new-directory>`。
+- `assets saved` 和 `assets animation saved` 需要已有的平台写入回执，不能用普通本地下载路径声明已经采纳。
+
+工作素材写入工程的 `assets/`，请求与回执放在 `dist/` 外。最终交付使用工程根目录 `dist/`，包内依赖一起交付。单张图片的直接生成仍可用 `tools generate-image`；裁剪、分割、分层及九宫格分析使用 `image` 子命令，先查看各自帮助。

package/project-template/.claude/skills/playcraft-workspace-assets/references/requests.json

@@ -0,0 +1,32 @@
+{
+  "image": { "kind": "image", "prompt": "A transparent game character", "removeBackground": true },
+  "audio": { "kind": "audio", "category": "sfx", "description": "A short bright reward chime" },
+  "sprite": {
+    "kind": "sprite",
+    "prompt": "A character walking sequence",
+    "frameCount": 8,
+    "frameWidth": 256,
+    "frameHeight": 256,
+    "columns": 4,
+    "fps": 12
+  },
+  "animation": {
+    "kind": "animation",
+    "prompt": "A character waving in a loop",
+    "frameCount": 8,
+    "frameWidth": 256,
+    "frameHeight": 256,
+    "columns": 4,
+    "fps": 12
+  },
+  "model": { "kind": "model", "mode": "text", "prompt": "A low polygon treasure chest" },
+  "video": {
+    "kind": "video",
+    "mode": "text",
+    "prompt": "A treasure chest opening",
+    "duration": 5,
+    "aspectRatio": "16:9",
+    "resolution": "720P",
+    "audio": false
+  }
+}

package/project-template-v2/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -1,13 +1,40 @@
 ---
 name: playcraft-audio-generation
-description: PlayCraft AI 音频生成完整指南。涵盖 SFX 音效生成、BGM 背景音乐生成（prompt 套路、时长、风格参数）、本地音频后处理（compress/fade/loop/normalize/mix），以及完整的音频管线。Artist 和 TA 在生成音频资产前必读。
+description: Use when generating or replacing playable audio, reusing library audio, managing durable audio tasks, or locally compressing, trimming, looping, normalizing, and mixing sound.
 triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
+compatibility: agent,opencode
+version: 1.1.1
+surfaces:
+  - sandbox-agent
 ---
 
 # PlayCraft AI 音频生成指南
 
 ## 0. 开始前必读
 
+AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音效) 与 BGM (Background Music, 背景音乐)。工作素材写入当前工程的 `assets/audio/` 或当前主题素材目录；最终交付导出到工程根目录 `dist/`。请求文件和工作记录保存在 `dist/` 外。
+
+### 复用素材与持久化音频任务
+
+```bash
+# 共享素材按名称、路径与标签检索；保留返回的素材编号
+playcraft library search "reward" --type audio --json
+playcraft library get <assetId> --json
+playcraft library files <assetId> --json
+playcraft library download <assetId> --output ./assets/audio/reward.mp3
+
+# 需要任务记录和断线恢复时使用工作区任务
+playcraft assets estimate --request audio-request.json
+playcraft assets generate --request audio-request.json --client-request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId> --timeout 1800
+playcraft assets download <taskId> --output ./assets/audio/generated-reward.mp3
+```
+
+`audio-request.json` 使用 JSON (JavaScript Object Notation, 数据交换格式)，例如 `{"kind":"audio","category":"sfx","description":"A short bright reward chime","duration":1}`；背景音乐改用 `category: "bgm"`，可带 `style` 与 `bpm`。持久化任务请求使用 `description`，直接生成命令使用 `--prompt`，不要混用两条入口的参数。
+
+任务命令自动读取 `.playcraft/workspace-context.json`；工程外需指定 `--workspace <workspaceId> --directory basic` 或实际变体目录。一次提交复用同一 `--client-request-id` 与原请求；拿到任务编号后用 `get` / `wait` 恢复。等待超时返回状态码 75，任务仍可查询。下载目标必须尚不存在；素材包使用新目录并保留相对路径。下载只保存文件，平台采纳状态仍由有效写入回执确认。任务取消、保存到素材库和恢复保存任务见当前可用的 `playcraft-workspace-assets` 技能。
+
 音频资产分两类，使用不同工具：
 
 | 类型               | 工具                           | 是否需要后端 |
@@ -37,7 +64,7 @@ playcraft tools generate-sfx \
 | ------------ | --------------------------- | -------------------------- |
 | `--prompt`   | 音效描述（**必须英文**）    | 见下方 prompt 套路         |
 | `--output`   | 保存路径（`.mp3` / `.wav`） | —                          |
-| `--duration` | 时长（秒）                  | SFX：0.3–3.0；环境音：3–10 |
+| `--duration` | 时长（秒）                  | SFX：0.5–3.0；环境音：3–10 |
 | `--loop`     | 是否循环友好                | 环境音、引擎声用 `--loop`  |
 
 ### SFX Prompt 套路
@@ -80,7 +107,7 @@ const SFX_LIST = [
   {
     name: 'click',
     prompt: 'button click, game UI, soft satisfying, short',
-    duration: 0.3,
+    duration: 0.5,
   },
   {
     name: 'win',
@@ -95,7 +122,7 @@ const SFX_LIST = [
   {
     name: 'jump',
     prompt: 'jump sound, platform game, light spring bounce',
-    duration: 0.4,
+    duration: 0.5,
   },
 ];
 

package/project-template-v2/.claude/skills/playcraft-image-generation/SKILL.md

@@ -1,13 +1,42 @@
 ---
 name: playcraft-image-generation
-description: PlayCraft AI (Artificial Intelligence, 人工智能) 图片生成与素材替换指南。默认使用可用的 Image 2.5；替换素材时读取参考图，全新素材可无参考文生图；验证背景要求、目标尺寸和最终文件。
+description: Use when generating or replacing playable images, reusing shared visual assets, or managing durable image tasks. AI (Artificial Intelligence, 人工智能) 图片生成与替换指南，保持参考图、背景要求、目标尺寸和交付文件一致。
 triggers: 生成图片,generate image,选模型,model selection,reference image,参考图,风格一致,图生图,文生图,AI生图,图片质量,模型选择,500错误,模型失败,generate-image,list-image-models,ta-workspace,batch,批量,脚本,nodejs,edit模型,变体,绿幕,去背景,透明PNG,prompt,提示词,prompt套路,提示词技巧
+compatibility: agent,opencode
+version: 1.1.2
+surfaces:
+  - sandbox-agent
 ---
 
 # PlayCraft AI 图片生成指南
 
 ## 0. 开始前必读
 
+工作素材和脚本保存在当前工程，素材通常写 `assets/` 或当前主题目录；最终交付导出到工程根目录 `dist/`。云工作区的素材检索和持久化任务使用下列入口；任务请求文件和回执保存在 `dist/` 外。
+
+### 素材复用与可恢复生成
+
+```bash
+# 需要复用已有图片时，按名称、路径和标签查找共享素材
+playcraft library search "角色" --type texture --json
+playcraft library get <assetId> --json
+playcraft library files <assetId> --json
+playcraft library download <assetId> --output ./assets/library-character
+
+# 需要持久任务、精灵图或帧动画时，提交工作区任务
+playcraft assets estimate --request image-request.json
+playcraft assets generate --request image-request.json --client-request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId> --timeout 1800
+playcraft assets download <taskId> --output ./assets/generated-character
+```
+
+`image-request.json` 使用 JSON (JavaScript Object Notation, 数据交换格式)，例如 `{"kind":"image","prompt":"A cheerful game character","removeBackground":true}`。请求中的透明背景开关由下文交付约束决定；素材替换需要读取字段参考图和规格时，继续使用下文的 `tools image-context` 与 `tools generate-image`。这两条入口没有可互换的参数表。
+
+任务命令从 `.playcraft/workspace-context.json` 推断当前工作区和工程目录；在工程外运行时传 `--workspace <workspaceId> --directory basic`，或实际变体目录。提交结果不确定时复用同一个 `--client-request-id` 与原请求；已有任务编号后通过 `get` / `wait` 恢复。等待超时以状态码 75 退出，任务仍可查询。精灵图和动画必须下载完整包并保留相对路径；`download` 保存文件不代表平台已确认采纳。
+
+普通单图生成和替换使用本技能下方的直接工具与命令；素材库检索、生成任务保存到素材库、动画草稿及版本的详细流程见当前可用的 `playcraft-workspace-assets` 技能。下载目标必须尚不存在。
+
 替换现有素材时先读取目标字段的 schema 配置（resolution、ratio、prompt、remove_background、reference_image）及当前素材。全新素材按用户需求确定尺寸、格式和输出路径，不假定所有素材都是透明 PNG (Portable Network Graphics, 便携式网络图形)。
 
 项目没有素材 schema 时，从目标素材的尺寸、格式和用户需求确定交付规格；参考图只提供内容和风格，不改变目标画布。不要套用其他游戏的字段、路径或尺寸。
@@ -214,7 +243,7 @@ Artist 生成 MC 时**不得**套用上方通用决策树里的 gemini / flux /
 | `mulerouter/gpt-image-2`   | `gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*` |
 | `mulerouter/nano-banana-2` | 裸 `gpt-image-2`（会走 iegg-litellm 压扁五格）      |
 
-完整 prompt / 尺寸规范见 **`playcraft-storyboard`** skill。ASR 双板 `--image-model` 须与已选 MC **完全一致**。
+故事板的提示词与尺寸依据本节规格和当前工程的制作要求。ASR 双板 `--image-model` 须与已选 MC **完全一致**。
 
 **Phase 1（概念图）**：纯文生图，`--image-size 4K` + MC 白名单内模型。
 **Phase 2（批量生产）**：必须带 `--reference-image` 指向 Phase 1 确认的概念图，同一批次使用**相同模型 + 相同 reference image + 相同 image-size**。
@@ -325,13 +354,13 @@ playcraft image overlay \
 # 目视检查：无白边、无色幕残留色、无黑色不透明块、边缘干净
 ```
 
-**不通过时的修复**：见 `ta-pipeline-cookbook.md` Step 0e §3 及 Compliance Gate 失败修复表。
+**不通过时的修复**：检查实际模型、源图背景和去背参数，保留原始图与失败回执；按下方进阶参考的错误恢复策略处理。透明验收仍失败时报告具体阶段并停止，不交付未通过的文件。
 
 ---
 
 ## 3.1 ASR 专用分支（Artist · ring 3 build）
 
-> **Read `playcraft-asset-state-sheet` Skill first.** ASR 是制作期参考板，不是 runtime 透明资产。
+> 先核对当前工程素材状态表中的槽位、状态和交付尺寸。ASR 是制作期参考板，不是 runtime 透明资产。
 
 | 阶段              | Artist                                | TA                            |
 | ----------------- | ------------------------------------- | ----------------------------- |
@@ -354,11 +383,13 @@ playcraft image overlay \
 - **<=5 个文件** → 直接使用 CLI 命令
 - **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录；使用本次选定的模型与参考图，不直接沿用脚本中旧的默认模型。
 
+复制模板时，`SKILL_DIR` 表示本次实际加载的 `SKILL.md` 所在目录，由技能加载回执确定。将示例中的该变量设为真实目录后再运行；项目安装与冻结安装的目录可能不同。
+
 ---
 
 ## 5. 进阶参考
 
-需要以下进阶内容时，查阅 [`refs/ta-image-generation-detail.md`](../../agents/refs/ta-image-generation-detail.md)：
+需要以下进阶内容时，查阅 [`reference/ta-image-generation-detail.md`](reference/ta-image-generation-detail.md)：
 
 | 主题                  | 说明                                                             |
 | --------------------- | ---------------------------------------------------------------- |

package/project-template-v2/.claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs

@@ -3,7 +3,7 @@
 // 用途：将处理好的图片目录合并为精灵图（PNG + JSON 元数据）
 //
 // 使用方式：
-//   1. cp .claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs ta-workspace/scripts/build-<name>-atlas.mjs
+//   1. cp "$SKILL_DIR/reference/build-sprite-sheet.template.mjs" ta-workspace/scripts/build-<name>-atlas.mjs
 //   2. 修改下方 CONFIG 区域
 //   3. 如需控制帧顺序，填写 ORDERED_NAMES 数组（留空则按文件名排序）
 //   4. node ta-workspace/scripts/build-<name>-atlas.mjs

package/project-template-v2/.claude/skills/playcraft-image-generation/reference/compare-style.template.mjs

@@ -5,7 +5,7 @@
  * 用途：TA Micro-Batch Validation 辅助工具，对 AI 补全素材与 Artist 样本做客观色彩比较。
  *
  * 使用方法：
- *   cp .claude/skills/playcraft-image-generation/reference/compare-style.template.mjs \
+ *   cp "$SKILL_DIR/reference/compare-style.template.mjs" \
  *      ta-workspace/scripts/compare-style.mjs
  *   # 修改下方 CONFIG 区域后运行：
  *   node ta-workspace/scripts/compare-style.mjs

package/project-template-v2/.claude/skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs

@@ -10,7 +10,7 @@
 //   - 数字/字母贴图：一批 ≤16 个
 //
 // 使用方式：
-//   1. cp .claude/skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs ta-workspace/scripts/gen-<name>-sprite.mjs
+//   1. cp "$SKILL_DIR/reference/gen-batch-sprite.template.mjs" ta-workspace/scripts/gen-<name>-sprite.mjs
 //   2. 修改下方 CONFIG 和 BATCHES 区域
 //   3. node ta-workspace/scripts/gen-<name>-sprite.mjs
 // ============================================================

package/project-template-v2/.claude/skills/playcraft-image-generation/reference/gen-batch.template.mjs

@@ -3,7 +3,7 @@
 // 用途：从零批量生成一组风格一致的素材（reference-image 模式）
 //
 // 使用方式：
-//   1. cp .claude/skills/playcraft-image-generation/reference/gen-batch.template.mjs ta-workspace/scripts/gen-<name>.mjs
+//   1. cp "$SKILL_DIR/reference/gen-batch.template.mjs" ta-workspace/scripts/gen-<name>.mjs
 //   2. 修改下方 CONFIG 和 ITEMS 区域
 //   3. node ta-workspace/scripts/gen-<name>.mjs
 // ============================================================

package/project-template-v2/.claude/skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs

@@ -8,7 +8,7 @@
 //   - 图标集（换内容符号）
 //
 // 使用方式：
-//   1. cp .claude/skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs ta-workspace/scripts/gen-<name>-variants.mjs
+//   1. cp "$SKILL_DIR/reference/gen-edit-variants.template.mjs" ta-workspace/scripts/gen-<name>-variants.mjs
 //   2. Phase 1：先手动生成基图（见下方说明），存为 CONFIG.baseImage 路径
 //   3. 填写 CONFIG 和 VARIANTS，然后 node ta-workspace/scripts/gen-<name>-variants.mjs
 //

package/project-template-v2/.claude/skills/playcraft-image-generation/reference/process-batch.template.mjs

@@ -3,7 +3,7 @@
 // 用途：对一批图片执行去背景 / trim + resize + 验证
 //
 // 使用方式：
-//   1. cp .claude/skills/playcraft-image-generation/reference/process-batch.template.mjs ta-workspace/scripts/process-<name>.mjs
+//   1. cp "$SKILL_DIR/reference/process-batch.template.mjs" ta-workspace/scripts/process-<name>.mjs
 //   2. 修改下方 CONFIG 区域（特别是 SKIP_REMOVE_BG 选项）
 //   3. node ta-workspace/scripts/process-<name>.mjs
 //