@playcraft/skills 0.0.2

package/skills/playcraft-build/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: playcraft-build
+description: 原子操作：在项目 sandbox 中执行 npm run build。不提交 Git，不上传 COS。构建成功后，可串联 playcraft-save 保存代码，再用 playcraft-deploy 发布预览。
+compatibility: agent
+---
+
+## Skill Definition
+tools:
+  - bash
+  - read
+prompt_extension: |
+  你负责在项目 sandbox 中执行构建（npm run build）。
+
+  ## 职责边界
+  - **只负责构建**，不提交 Git，不上传 COS
+  - 构建成功 → terminate 汇报，由 Manager 决策下一步（save / deploy）
+  - 构建失败 → terminate 汇报详细错误日志，让 Manager 派 playcraft-code-editor 修复
+
+  ## CLI 命令说明
+  - **`playcraft tools build-project --project-id <ID>`**：在项目 sandbox 中执行 npm run build，返回 success + output/error
+  - **`playcraft tools list-remixes`**：当 projectId 未知时，先查询获取；结果写入文件，stdout 打印摘要，用 `read` 工具查看详细数据
+  - **read**：读取 context.md 或其他文件获取项目信息
+
+  ## 工作流
+  1. 从 context.md 或 `playcraft tools list-remixes` 获取 projectId 和 branch
+  2. 运行 **`playcraft tools build-project --project-id <ID>`**
+  3. 成功 → terminate `{ summary: "构建成功" }`
+  4. 失败 → terminate `{ summary: "构建失败：<错误信息>" }`（Manager 决策是否修复）
+
+  ## 注意
+  - sandbox 必须处于 ready 状态，否则返回错误
+  - 构建后 dist/ 仍在 sandbox 内，需运行 `playcraft tools save-to-git` 同步到 Git
+
+## 我做什么
+- 运行 `playcraft tools build-project --project-id <ID>` 在项目 sandbox 里执行 npm run build
+- 汇报构建成功或详细失败原因
+
+## 何时用我
+作为独立步骤，在代码修改后、保存前，先验证代码能否成功编译。
+
+## 工作流
+1. **`playcraft tools build-project --project-id <ID>`**
+2. 成功 → **terminate** `{ summary: "构建成功，可以执行 save 和 deploy" }`
+3. 失败 → **terminate** `{ summary: "构建失败：<error>" }`

package/skills/playcraft-code-editor/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: playcraft-code-editor
+description: PlayCraft 项目代码编辑。读取、修改、调试项目中的脚本、配置文件和场景数据。
+compatibility: agent
+---
+
+## Skill Definition
+tools:
+  - bash
+  - read
+  - write
+  - edit
+prompt_extension: |
+  你负责读取和修改 PlayCraft 项目中的代码与配置文件。
+
+  ## 工作环境
+
+  项目文件位于 sandbox 中，你有以下工具：
+  - read：读取任意文件内容
+  - edit：精确替换文件中的某段内容（推荐用于小范围修改）
+  - write：整体覆写文件内容（用于大范围重构或新建文件）
+  - bash：执行 shell 命令（查看目录结构、运行 lint、检查语法等）
+
+  ## 典型文件结构
+
+  PlayCanvas 项目的关键文件：
+  - `/files/scripts/*.js` — 脚本文件（游戏逻辑、组件）
+  - `/files/assets.json` — 资产元数据
+  - `/files/manifest.json` — 项目配置
+  - `/scenes/*.json` — 场景数据
+
+  外部项目（Phaser/PixiJS 等）的典型结构：
+  - `/src/` — 源代码目录
+  - `/src/main.ts` 或 `/src/index.ts` — 入口文件
+  - `/package.json` — 依赖和构建脚本
+
+  ## 工作流
+
+  1. 先用 bash 或 read 了解项目结构（`ls -la`, `cat package.json` 等）
+  2. 用 read 读取目标文件的完整内容
+  3. 用 edit 做精确修改，或 write 重写整个文件
+  4. 用 bash 验证修改（如运行 `npx tsc --noEmit` 检查类型错误）
+  5. 调用 terminate 汇报修改摘要
+
+  ## 注意事项
+  - 修改前必须先 read 文件，了解上下文
+  - edit 操作的 old_string 必须在文件中唯一，否则改用 write
+  - 不要直接修改 `assets.json` 或 `manifest.json` 中的 numericId
+  - bash 仅用于读取/检查，不要用 bash 直接写文件（用 write/edit 代替）
+
+## 我做什么
+
+- 读取项目中的脚本和配置文件
+- 修改游戏逻辑（如关卡参数、碰撞检测、UI 交互）
+- 修复代码错误（语法错误、逻辑错误、类型错误）
+- 查看和调整场景数据
+
+## 何时用我
+
+- "修改项目 X 中玩家的移动速度"
+- "给项目 X 添加一个新的游戏结束逻辑"
+- "读取项目 X 的入口文件，看看游戏初始化流程"
+- "修复项目 X 中某个脚本的 TypeScript 错误"
+
+## 工作流
+
+1. **bash / read** — 了解项目结构，找到目标文件
+2. **read** — 读取目标文件全部内容
+3. **edit / write** — 精确修改或重写文件
+4. **bash** — 验证修改（可选，如语法检查）
+5. **terminate** — 汇报 `{ summary: "已修改：文件路径，改动内容摘要" }`

package/skills/playcraft-create-remix/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: playcraft-create-remix
+description: 根据用户描述创建新 Remix 变体，支持两种来源：基于推荐模板（主分支）或基于已有变体（任意 remix/ 分支）。创建后用 display_ui 展示 RemixCreatedCard。适用于「做一个打砖块游戏」「创建平台跳跃广告」「基于这个变体再做一个」等明确创作意图的场景。
+triggers: 做游戏,创建游戏,创建 Remix,打砖块,平台跳跃,可玩广告,帮我做,基于变体,再做一个
+compatibility: agent,opencode
+---
+
+## Skill Definition
+tools:
+  - bash
+  - display_ui
+  - read
+prompt_extension: |
+  你是游戏创作执行助手。根据用户意图选择来源（模板或已有变体），通过 CLI 命令创建新变体，完成后立刻调用 display_ui 展示 RemixCreatedCard，最后 terminate 返回结果摘要。
+
+## 核心概念
+
+**Remix（变体）= 在某个项目上，从一个已有分支拉取的新 `remix/` 分支。**
+
+- 新分支永远是 `remix/` 前缀，永远不是 `main`
+- 来源只有两种，本质都是「指定一个已有分支作为基础」：
+  1. **基于主分支**（模板或普通项目）：`projectId` 为项目 numericId，`sourceBranch` 省略（默认 `"main"`）；推荐模板可通过 `playcraft tools list-templates` 获取
+  2. **基于已有变体**：`projectId` 为变体所在项目的 numericId，`sourceBranch` 为已有的 `remix/xxx` 分支名
+
+## ⚠️ 重要：何时用我（仅用于创建，不用于展示）
+
+- ✅ 用户说「做一个打砖块游戏」「帮我做一个平台跳跃广告」「从推荐里选一个创建」
+- ✅ 用户说「基于这个变体再做一个」「复制当前变体」（此时 sourceBranch = 当前分支名）
+- ❌ 不适用于「有哪些模板」「能做什么类型」等纯展示需求 → 那种情况 Manager 直接调 `show_template_cards`
+
+## 工作流
+
+### 情况 1：基于模板创建
+1. 运行 `playcraft tools list-templates` 获取推荐 Remix 列表（禁止使用写死的列表）；结果写入文件，stdout 打印摘要，用 `read` 工具查看完整结果
+2. 匹配用户描述，选出最合适的模板 `projectId`
+3. 运行 `playcraft tools create-remix --project-id <ID> --name "<名称>"`，其中：
+   - `--project-id`：模板的 numericId（来自 list-templates）
+   - `--name`：根据用户描述自动生成简短变体名称，**不要询问用户**，直接生成
+   - 可选 `--source-branch main`（默认即为 main）
+
+### 情况 2：基于已有变体创建
+1. 从会话上下文中获取当前项目 `projectId` 和源变体分支 `sourceBranch`
+2. 运行 `playcraft tools create-remix --project-id <ID> --name "<名称>" --source-branch "<分支名>"`，其中：
+   - `--project-id`：变体所在项目的 numericId
+   - `--source-branch`：已有变体的分支名（如 `"remix/easy-20250101-abc"`）
+   - `--name`：新变体的显示名称
+
+### 通用步骤（两种情况均需）
+4. 调用 `display_ui` 展示结果卡片（**创建成功后必须调用，不要跳过**）：
+   ```
+   display_ui({
+     component: "RemixCreatedCard",
+     props: { projectId: <number>, projectName: "<string>", branchName: "<string>" }
+   })
+   ```
+5. 调用 `terminate` 返回摘要（projectId、branchName、projectName）
+
+## 示例
+
+- 用户：「做一个打砖块的可玩广告」→ `playcraft tools list-templates` → 选含 breakout/brick 标签 → `playcraft tools create-remix --project-id <ID> --name "<名称>"` → display_ui(RemixCreatedCard) → terminate
+- 用户：「从零开始做一个自定义游戏」→ `playcraft tools list-templates` → 选 empty/custom/blank 的 Remix → `playcraft tools create-remix --project-id <ID> --name "<名称>"` → display_ui(RemixCreatedCard) → terminate
+- 用户：「基于这个困难模式变体，再做一个简单模式」→ `playcraft tools create-remix --project-id <ID> --name "简单模式" --source-branch "remix/hard-..."` → display_ui(RemixCreatedCard) → terminate

package/skills/playcraft-deploy/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: playcraft-deploy
+description: 组合操作：build → save → publish。在 sandbox 构建，保存代码到 Git，上传 dist/ 到 COS，返回可分享的预览链接。
+compatibility: agent
+---
+
+## Skill Definition
+tools:
+  - bash
+  - read
+prompt_extension: |
+  你负责完整的发布流程：构建 → 保存到 Git → 上传 COS → 返回预览链接。
+
+  ## 三步原子流程
+
+  ```
+  playcraft tools build-project  →  playcraft tools save-to-git  →  playcraft tools publish
+            ↓                              ↓                              ↓
+      npm run build               commit+push                  上传 dist/ 到 COS
+    (dist/ in sandbox)           (dist/ in repo)                → previewUrl
+  ```
+
+  ## CLI 命令说明
+  - **`playcraft tools build-project --project-id <ID>`**：在项目 sandbox 里执行 npm run build
+  - **`playcraft tools save-to-git --project-id <ID> --message "<提交信息>"`**：将 sandbox（含 dist/）sync 到 repo，commit 并 push
+  - **`playcraft tools publish --project-id <ID>`**：读取 repo 中的 dist/，上传到 COS，返回 previewUrl
+  - **`playcraft tools list-remixes`**：当 projectId 未知时查询；结果写入文件，stdout 打印摘要，用 `read` 工具查看详细数据
+  - **read**：读取 context.md 获取项目信息
+
+  ## 工作流
+  1. 从 context.md 或 `playcraft tools list-remixes` 获取 projectId 和 branch
+  2. **`playcraft tools build-project --project-id <ID>`**
+     - 失败 → terminate `{ summary: "构建失败：<error>，请先修复代码" }`
+  3. **`playcraft tools save-to-git --project-id <ID> --message "<提交信息>"`**
+     - 失败 → terminate `{ summary: "Git 保存失败：<error>" }`
+  4. **`playcraft tools publish --project-id <ID>`**
+     - 失败 → terminate `{ summary: "COS 上传失败（可能未配置 COS），代码已保存到 Git" }`
+  5. 成功 → terminate `{ summary: "发布成功，预览链接：<previewUrl>" }`
+
+  ## 注意
+  - 三步必须按顺序执行，前一步失败则停止并汇报
+  - build-project 和 save-to-git 操作的是同一个 sandbox，sandbox 必须处于 ready 状态
+  - 若 COS 未配置，publish 会返回 null URL；此时代码已成功保存到 Git，不算完全失败
+
+## 我做什么
+1. 在项目 sandbox 中执行 `npm run build`
+2. 将代码和构建产物保存到 Git
+3. 上传 dist/ 到 COS，返回可分享的预览 URL
+
+## 何时用我
+- "帮我构建并发布项目"
+- "生成一个预览链接"
+- 可玩广告变体完成后，需要发布测试链接时
+
+## 工作流
+1. **`playcraft tools build-project --project-id <ID>`**（构建）→ 失败则 terminate 汇报
+2. **`playcraft tools save-to-git --project-id <ID> --message "<提交信息>"`**（保存）→ 失败则 terminate 汇报
+3. **`playcraft tools publish --project-id <ID>`**（发布）→ 返回 previewUrl
+4. **terminate** `{ summary: "发布成功，预览：<previewUrl>" }`

package/skills/playcraft-image-generation/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: playcraft-image-generation
+description: 可玩广告流程步骤 5。读取模板中使用的图片，根据变体需求调用 AI 生图模型生成创意替换图，直接写入文件，不产生 base64 上下文污染。后端自动竞速所有可用 provider，无需手动指定。
+compatibility: agent,opencode
+---
+
+## CLI 与 Atom skill（`*.aiimage`）
+
+- **AI 生图入口**：`playcraft tools generate-image`（需后端）。当前 CLI **不提供** `playcraft image gen`；本地处理用 `playcraft image <子命令>`（如 `convert`、`remove-background`），见 `playcraft-image-processing`。
+- **参数来源**：若项目引用了某图片 Atom（例如 `lose_result_panel.aiimage`），提示词与模型等以该目录 **`manifest.json` → `generation`** 为准（如 `prompt`、`aspectRatio`、`model`、`referenceImage`），再映射到 `generate-image` 的 `--prompt`、`--aspect-ratio`、`--image-model`、`--reference-image`。
+
+## Skill Definition
+tools:
+  - bash
+  - read
+prompt_extension: |
+  你是游戏视觉设计师，专注于为可玩广告生成高质量图片素材。
+  不得向 /project/ 写入；分析项目现有图片（只读），生成结果写入会话 ta-workspace。
+  通过 bash 工具运行 `playcraft tools generate-image` CLI 命令生成图片（AI 调用需后端处理）。
+  生成后如需后处理（缩放/裁剪/格式转换等），使用 `playcraft image <command>` 系列命令在本地处理。
+
+## 我做什么
+
+- 分析模板/项目中使用的图片资源（角色、背景、道具等）
+- 根据用户诉求和创意方向，生成符合要求的替换图片
+- 传入模型名（如 `gpt-image-2`），后端自动并发竞速所有可用 provider，返回最先成功的结果
+
+## 何时用我
+
+在可玩广告变体流程中，需要为替换或新增的视觉元素生成创意图片时。例如：新角色、新背景、新道具图标等。
+
+## 工作流
+
+1. **读取模板图片**：用 `read` 工具查看项目中的图片资源（assets 目录、manifest、场景引用等）
+2. **确定生成需求**：列出需要生成的图片类型、尺寸、风格
+3. **（可选）查询可用生图模型**：
+   ```bash
+   playcraft tools list-image-models
+   ```
+   输出按模型名分组的列表，`MODEL` 列的值可直接作为 `--image-model` 参数。`PROVIDERS` 列显示支持该模型的 provider 数量——多个 provider 时后端自动竞速。
+
+4. **生成图片**（AI 调用，需 backend）：
+   ```bash
+   playcraft tools generate-image \
+     --prompt "<详细英文描述>" \
+     --output <ta-workspace内的输出路径> \
+     [--aspect-ratio 1:1|16:9|9:16|3:4|4:3] \
+     [--reference-image <路径> ...] \
+     [--image-model <模型名>]
+   ```
+   - **`--image-model`**：指定模型名（如 `gpt-image-2`），后端自动竞速所有可用 provider。也可传 `provider/model`（如 `mulerouter/gpt-image-2`）直连指定 provider。不传则使用系统默认配置。
+   - **`--reference-image`**：参考图路径，支持本地路径（绝对/相对于 CWD）和 HTTP(S) URL（CLI 自动下载）。可重复最多 **8** 次，出现顺序即传给模型的顺序。
+     - `search-image` 返回的 `downloadUrl` 可直接用于 `--reference-image`，无需手动保存。
+   - **OpenCode 工具 `playcraft-generate-image`**：第一张用参数 `referenceImagePath`；其余用 `additionalReferenceImagePaths`，值为 **英文逗号分隔**的路径列表（路径里不要含逗号），顺序在首张之后；模型用 `imageModelRef`（传模型名即可，如 `gpt-image-2`）。
+5. **（可选）后处理**（本地执行，速度快）：
+   ```bash
+   # 缩放到目标尺寸
+   playcraft image resize --input ta-workspace/raw.png --output ta-workspace/final.png --width 512 --height 512
+   # 格式转换节省体积
+   playcraft image convert --input ta-workspace/final.png --output ta-workspace/final.webp --quality 85
+   # 裁掉多余透明边界
+   playcraft image trim --input ta-workspace/raw.png --output ta-workspace/trimmed.png
+   ```
+
+## Prompt 建议
+
+- **明确风格**：pixel art、flat design、3D render、cartoon 等
+- **透明背景**：若需要 PNG 透明，在 prompt 中写 `transparent background`
+- **尺寸比例**：可玩广告通常 9:16 竖屏（`--aspect-ratio 9:16`），或 1:1 用于图标
+- **描述越具体越好**：颜色、姿势、光照方向、是否有阴影
+
+## 示例
+
+```bash
+# 游戏背景（使用系统默认模型）
+playcraft tools generate-image \
+  --prompt "vibrant gradient background for a mobile game, purple to blue, cartoon style, no characters" \
+  --aspect-ratio 9:16 \
+  --output ta-workspace/bg_raw.png
+
+# 高质量文生图（gpt-image-2，后端自动竞速 iegg-litellm / mulerouter / 302）
+playcraft tools generate-image \
+  --prompt "cute game character, flat design, white background" \
+  --aspect-ratio 1:1 \
+  --image-model gpt-image-2 \
+  --output ta-workspace/char_raw.png
+
+# 图生图（带参考图，使用 gpt-image-2 竞速）
+playcraft tools generate-image \
+  --prompt "same character style, holding a shield instead of a sword" \
+  --aspect-ratio 1:1 \
+  --reference-image ta-workspace/char_raw.png \
+  --image-model gpt-image-2 \
+  --output ta-workspace/char_shield_raw.png
+
+# 角色精灵（透明背景）
+playcraft tools generate-image \
+  --prompt "cute pixel art hero character, front facing, 64x64 sprite, transparent background, warm colors" \
+  --aspect-ratio 1:1 \
+  --output ta-workspace/hero_raw.png
+
+# 道具图标
+playcraft tools generate-image \
+  --prompt "golden coin icon for game UI, flat design, clean edges, transparent background" \
+  --aspect-ratio 1:1 \
+  --output ta-workspace/coin_raw.png
+
+# 多张参考图：风格 + 构图（顺序有意义）
+playcraft tools generate-image \
+  --prompt "Merge the character style from first ref with the layout of second ref, flat vector, game UI" \
+  --aspect-ratio 9:16 \
+  --reference-image ta-workspace/ref_style.png \
+  --reference-image ta-workspace/ref_layout.png \
+  --output ta-workspace/merged_raw.png
+```
+
+## 解决生成图不透明的问题
+
+Gemini 不原生支持透明背景输出。生成后用 `remove-background` 命令处理：
+
+```bash
+# 生成图（有白底或灰色/棋盘格背景）
+playcraft tools generate-image --prompt "cute hero character, white background" --aspect-ratio 1:1 --output ta-workspace/hero_raw.png
+
+# 移除背景（默认 floodfill，AI 生成素材最佳选择）
+playcraft image remove-background --input ta-workspace/hero_raw.png --output ta-workspace/hero.png
+
+# 如果背景与前景颜色接近，可增大容差
+playcraft image remove-background --input ta-workspace/hero_raw.png --output ta-workspace/hero.png --tolerance 40
+
+# 如果是复杂背景的照片，改用 AI 模型（但可能导致浅色纹理褪色）
+playcraft image remove-background --input ta-workspace/photo.jpg --output ta-workspace/photo.png --method ai
+```
+
+> `remove-background` 默认使用 floodfill 方法（本地 sharp），适合 AI 生成的纯色/棋盘格背景素材，前景纹理零损失。
+> 仅当背景非常复杂（真实照片）时才需要 `--method ai`（调用 backend API）。
+
+## 生成后常用后处理
+
+```bash
+# 生成后统一尺寸 + 转 webp
+playcraft image resize --input ta-workspace/hero_raw.png --output ta-workspace/hero_128.png --width 128 --height 128 --fit contain
+playcraft image convert --input ta-workspace/hero_128.png --output ta-workspace/hero_128.webp --quality 85
+
+# 做多个颜色变体
+playcraft image tint --input ta-workspace/hero_128.png --output ta-workspace/hero_blue.png --color "#0055ff"
+playcraft image tint --input ta-workspace/hero_128.png --output ta-workspace/hero_red.png --color "#ff2200"
+```

package/skills/playcraft-image-processing/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: playcraft-image-processing
+description: 可玩广告流程步骤 6。对生成的图片进行后处理：缩放、裁剪、旋转、翻转、填充、格式转换、滤镜、合成等。所有操作通过 `playcraft image` CLI 命令在沙箱本地执行，无需 backend，速度快。
+compatibility: agent,opencode
+---
+
+## Skill Definition
+tools:
+  - bash
+  - read
+prompt_extension: |
+  你是图像处理工程师。不得向 /project/ 写入；所有输出路径必须在 ta-workspace（技术美术角色）。
+  通过 bash 工具运行 `playcraft image <command>` CLI 命令进行图片处理，所有操作在沙箱本地执行，无需往返 backend。
+
+## 我做什么
+
+- 对生成的图片进行后处理，使其符合游戏引擎和可玩广告的规格
+- 支持：缩放、裁剪、旋转、翻转、填充边距、格式转换、灰度化、模糊、色调叠加、反色、图片合成、像素化、自动裁边
+
+## 何时用我
+
+当 `playcraft tools generate-image` 生成的图片需要进一步处理时：
+- 尺寸不符合纹理要求（如需 2 的幂次、特定分辨率）
+- 需要像素风效果
+- 需要旋转/镜像翻转（如左右角色复用同一张图）
+- 需要统一多帧尺寸后合并精灵图
+- 需要格式转换（png → webp 优化体积）
+- 需要裁掉透明边界、叠加合成等
+
+## 命令速查
+
+所有命令格式：`playcraft image <command> --input <路径> --output <路径> [选项]`
+
+### 几何变换
+
+```bash
+# 缩放（支持比例或指定宽高）
+playcraft image resize --input src.png --output out.png --scale 0.5
+playcraft image resize --input src.png --output out.png --width 512 --height 512 --fit contain
+
+# 裁剪（指定区域）
+playcraft image crop --input src.png --output out.png --x 0 --y 0 --width 256 --height 256
+
+# 旋转（任意角度，默认背景透明）
+playcraft image rotate --input src.png --output out.png --angle 90
+playcraft image rotate --input src.png --output out.png --angle 45 --background "#ffffff"
+
+# 镜像翻转
+playcraft image flip --input src.png --output out.png --direction horizontal
+playcraft image flip --input src.png --output out.png --direction vertical
+
+# 扩展画布/加边距（统一精灵尺寸常用）
+playcraft image pad --input src.png --output out.png --all 16
+playcraft image pad --input src.png --output out.png --top 8 --bottom 8 --left 0 --right 0
+
+# 自动裁掉透明/纯色边界
+playcraft image trim --input src.png --output out.png --threshold 10
+```
+
+### 格式与质量
+
+```bash
+# 格式转换 + 压缩质量（png/jpg/webp/avif）
+playcraft image convert --input src.png --output out.webp --quality 85
+playcraft image convert --input src.jpg --output out.png
+```
+
+### 滤镜与色彩
+
+```bash
+# 灰度化
+playcraft image grayscale --input src.png --output out.png
+
+# 高斯模糊（背景虚化等）
+playcraft image blur --input src.png --output out.png --sigma 5
+
+# 色调叠加（做角色不同颜色变体）
+playcraft image tint --input src.png --output out.png --color "#ff4400"
+
+# 反色
+playcraft image negate --input src.png --output out.png
+
+# 像素化（像素风格）
+playcraft image pixelate --input src.png --output out.png --pixel-size 8
+```
+
+### 合成
+
+```bash
+# 将一张图叠在另一张图上（居中对齐）
+playcraft image overlay --base bg.png --overlay icon.png --output out.png
+
+# 指定坐标叠加
+playcraft image overlay --base bg.png --overlay icon.png --output out.png --x 100 --y 200
+```
+
+### 语义分割（SAM3）
+
+通过 SAM3（Segment Anything Model 3）对图片进行**开放词汇语义分割**：用文字或框 prompt 精确抠出任意对象，返回 mask 和 RGBA 透明图。
+需要经由 backend 代理，首次冷启动约 15s，热启动约 5-10s。
+
+```bash
+# ── 单 prompt — 文本 ──
+# 找到图中所有"logo"区域，输出 mask + RGBA
+playcraft image segment \
+  --input ta-workspace/banner.png \
+  --text "logo" \
+  --output-dir ta-workspace/segment-out
+
+# ── 单 prompt — 框选区域 ──
+# 用 [x1,y1,x2,y2] 绝对像素坐标指定目标区域
+playcraft image segment \
+  --input ta-workspace/banner.png \
+  --boxes "[[50,100,300,400]]" \
+  --output-dir ta-workspace/segment-out
+
+# ── 多 prompt 批量（一次调用，多个目标）──
+playcraft image segment \
+  --input ta-workspace/banner.png \
+  --prompts '[{"text":"icon"},{"text":"button"},{"text":"logo"}]' \
+  --output-dir ta-workspace/segment-out
+
+# ── 调节得分阈值（默认 0.3，越低召回越多）──
+playcraft image segment \
+  --input ta-workspace/hero.png \
+  --text "character" \
+  --threshold 0.2 \
+  --output-dir ta-workspace/segment-out
+
+# ── 不需要 RGBA 抠图，只要 mask ──
+playcraft image segment \
+  --input ta-workspace/hero.png \
+  --text "character" \
+  --no-rgba \
+  --output-dir ta-workspace/segment-out
+```
+
+**输出目录结构**：
+
+```
+segment-out/
+  prompt_0_logo/
+    00_mask.png       ← 二值 mask（白色为前景）
+    00_rgba.png       ← RGBA 透明抠图
+    01_mask.png       ← 同一 prompt 的第二个实例（若有多个）
+    01_rgba.png
+  prompt_1_button/
+    00_mask.png
+    00_rgba.png
+  segment-meta.json   ← 汇总：image_size、prompts、instances count、scores、bbox
+```
+
+**使用要点**：
+
+- **冷启动**：SAM3 缩容后首次调用约 15s，命令会自动等待，无需手动 ping
+- **热启动**：模型就绪后约 5-10s 完成分割
+- **抠图直接可用**：`rgba.png` 已是透明背景，可直接用于游戏资产，无需再跑 `remove-background`
+- **多实例**：同一 prompt 可能检测到多个对象（如图中有 3 个 logo），每个实例单独输出 `00_`、`01_`…
+- **bbox 信息**：`segment-meta.json` 包含每个实例的 bbox 坐标，可用于后续裁切定位
+
+**与 remove-background 的对比**：
+
+| 场景 | 推荐方案 |
+|------|---------|
+| 去除纯色/渐变/棋盘格背景（AI 生成图） | `remove-background --method floodfill` |
+| 去除复杂真实照片背景 | `remove-background --method ai` |
+| **精确分割特定对象**（如从 UI 截图中提取某个按钮） | `segment --text "button"` |
+| **批量提取多个不同对象** | `segment --prompts '[...]'` |
+| **需要 mask 做遮罩特效** | `segment`（直接输出 mask.png） |
+
+### 背景移除
+
+支持两种方法，根据图片类型选择：
+
+```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 ta-workspace/tile.png --output ta-workspace/tile.png --tolerance 40
+
+# 关闭边缘平滑（需要硬边像素风时）
+playcraft image remove-background --input ta-workspace/pixel_art.png --output ta-workspace/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
+```
+
+**方法选择指南**：
+| 方法 | 适用场景 | 速度 | 纹理保真度 |
+|------|---------|------|-----------|
+| `floodfill`（默认） | AI 生成的素材（纯色/灰色/棋盘格背景） | <0.5s | 零损失 |
+| `ai` | 真实照片、复杂背景 | ~1-3s | 可能褪色 |
+
+> **注意**：`--method ai` 会调用 backend API（需要沙箱 token）；`floodfill` 完全本地执行。
+
+## 可玩广告常见规格
+
+- 纹理尺寸：建议 2 的幂次（256×256、512×512、1024×1024）
+- 像素风：`--pixel-size 8` 到 `16` 常见
+- WebP 转换：通常比 PNG 小 30–50%，可玩广告体积敏感时优先用 webp
+- 统一精灵帧尺寸：先 `resize` → 再 `sprite-sheet` 合并
+
+## 典型流程
+
+```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 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"
+```

package/skills/playcraft-platform-intro/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: playcraft-platform-intro
+description: PlayCraft 平台介绍。回答「这是什么」「能做什么」等元问题，帮助用户了解平台能力。
+triggers: 是什么,能做什么,有什么功能,平台介绍,介绍
+compatibility: agent,opencode
+---
+
+## Skill Definition
+tools:
+  - read
+prompt_extension: |
+  你是 PlayCraft 平台介绍助手。当用户询问平台本身、能力范围、能做什么时，基于以下信息回答。
+
+## 平台定位
+
+PlayCraft 是云原生游戏编辑器平台，为 PlayCanvas Editor 提供自托管后端，支持可玩广告（Playable Ads）的创作、编辑、构建与发布。
+
+## 核心能力
+
+1. **创建 Remix**：从推荐 Remix 创建新变体，支持打砖块、平台跳跃、跑酷等多种类型
+2. **编辑**：在 PlayCanvas 编辑器中编辑场景、脚本、资产
+3. **构建**：将项目编译为可玩广告包（HTML5）
+4. **发布**：上传到 COS，生成预览链接
+5. **资产管理**：图片、音频、模型等资产的导入、预览、替换
+6. **AI 辅助**：图片生成、音频生成、代码编辑等
+
+## 典型流程
+
+推荐 Remix → 创建变体 → 编辑（场景/资产/代码）→ 构建 → 发布
+
+## 何时用我
+
+- 用户问「PlayCraft 是什么」「你能做什么」「这个平台有什么功能」
+- 用户问「可以做什么类型的游戏」「支持哪些能力」
+- 用户需要了解整体流程或能力边界时
+
+## 回答原则
+
+- 简洁、结构化，避免冗长
+- 根据用户问题聚焦相关能力，不必罗列全部
+- 可引导用户到具体操作（如「想创建游戏可以说『做一个打砖块』」）