当 msw-search 找不到合适 sprite…

在 msw-search 无合适 sprite RUID 时，直接绘制像素 sprite、渲染成 PNG，并通过 msw-mcp 上传注册得到 sprite RUID。

适用场景

解决思路

1. 先调用 msw-search 搜索 sprite 类别；只有没有任何合适 RUID 时才启用本 painter 流程。
2. 如果 msw-search 返回符合意图的 RUID，直接使用该 RUID，不要调用 painter。
3. 如果没有搜索结果或结果均不合适，进入 painter 直接绘制；如果用户明确要求手绘外观的角色/图标，也可直接进入 painter。
4. 从 SVG、Canvas、HTML 三种媒介中选一种：图标/Logo/简单角色/基于形状的像素画优先 SVG；程序化图案、循环逻辑/纹理/噪声优先 Canvas；可用 CSS 快速布局的复合页面用 HTML（少用，像素画通常 SVG/Canvas 更合适）。
5. 若使用 SVG，写 1px `<rect>` 点逐个放置；模板设置 `viewBox`、`width=100% height=100%`、`preserveAspectRatio=xMidYMid meet`、`image-rendering: pixelated`，不要写固定像素 width/height，否则 render.cjs 用更大 --width 时只填左上角。
6. 若使用 Canvas，利用 render.cjs 自动暴露的 `c` 与 `ctx`，并依赖自动设置的 `ctx.imageSmoothingEnabled = false`；用 `const scale = c.width / GRID` 从 `c.width` 推导缩放，不要硬编码 scale，否则不同 --width 会留空白。
7. 若使用 HTML，使用最小 HTML 模板，body 设置 `margin:0; image-rendering: pixelated;`，再按需绘制内容。
8. 选择风格：图标/按钮/图块/方块/简单道具选 `chunky`；角色/NPC/怪物/吉祥物/可爱请求/“画一个史莱姆”选 `maple`；用户说 retro/8-bit/NES/minimal 选 chunky；说 MapleStory/cute/cartoon/chibi/illustrated 选 maple。
9. 按 chunky 规则写代码：小逻辑网格（如 16×16、32×32）、黑色或白色 1px 描边、2–4 级阶梯明暗、完全无 AA。
10. 按 maple 规则写代码：较大逻辑网格（32×32 ~ 128×128）、使用 selout（比填充色更暗的描边）、4–6 级阶梯明暗、轮廓可选 AA、可选 2×2 抖动。
11. 两种风格共同禁止：曲线 API、渐变 API、分数坐标、`filter: blur`/`drop-shadow`；不要用 `arc()`/`bezierCurveTo()`/gradient 来制造平滑。
12. 决定输出尺寸：图标/按钮 48×48 ~ 64×64；角色/物品/NPC/怪物 96×96 ~ 128×128；图块/地面/方块 64×64 ~ 128×128；背景/大物体 256×256 或更大且仅在明确要求时使用；默认 128×128。
13. 查阅 `references/size-guide.md` 获取风格特定工作网格与 SD 角色比例；如果请求输出低于 64×64，maple 没有足够像素放 selout + AA + 五官，要么提高到 64+，要么回退到 chunky。
14. 写代码时参考 `references/style-chunky-pixel.md` 或 `references/style-maple-cartoon.md` 对应风格规则。
15. 第一次使用 painter 时在 `scripts` 目录运行 `npm ci` 安装 `puppeteer`（约 200MB，含 headless Chromium）；不要用 `npm install`，不要手改 `package-lock.json`；如需升级 puppeteer，本地运行 `npm install puppeteer@<version>` 并提交重新生成的 lockfile。
16. 用 `node scripts/render.cjs --type <svg|canvas|html> --in <code-file> --out <out.png> --width <W> --height <H>` 渲染 PNG；也可通过 stdin 传代码；`--type` 与 `--out` 必填，`--in` 可省略或为 `-`，`--width`/`--height` 默认 128。
17. 渲染成功时 stdout 单行输出 PNG 绝对路径、退出码 0；失败时 stderr 输出错误、退出码 1。
18. PNG 默认透明背景；如果需要背景色，在 SVG/Canvas/HTML 内部显式绘制。
19. 利用 render.cjs 默认安全措施：OS sandbox 开启、阻止页面所有网络请求、页面通过 data: URL 与严格 CSP（`default-src 'none'`）提供、SVG/HTML 输入会移除 `<script>`、`<foreignObject>`、内联 `on*` 处理器和非 data: URL；无需额外开启。
20. 如果在受限环境（某些 CI 容器、部分 WSL 设置）中 Chromium 无法启动 sandbox，调用前设置 `PAINTER_DISABLE_SANDBOX=1`；不要在开发者工作站上设置。
21. 上传前先 `Read` 输出 PNG；检查空白、尺寸不匹配、离屏、背景是否透明等，避免上传失败后重做两步上传。
22. 通过已连接的 `msw-mcp` 暴露的 asset upload（创建）工具上传；先查看该服务器的工具列表，使用它实际提供的、支持 sprite 的创建工具；以工具自身 schema 为准，不猜工具名。
23. 不要混淆创建工具与 `asset_update_resource_storage_data`（后者替换已有资产二进制）。
24. 如果连接的 MCP 没有上传工具，停止上传步骤，请用户通过 Maker 注册 PNG，然后继续使用用户提供的 RUID（或通过 `msw-search` 找到它）。
25. 按两步预签名模式调用同一个上传工具两次。
26. 安全处理 presigned URL：不要回显、引用、转述或把 URL/查询参数（如 `X-Amz-Signature`、`X-Amz-Credential`）放进面向用户的回复、提交信息、日志或后续提示；只在 agent 推理上下文保留。
27. 调用 shell 时通过 `PAINTER_PRESIGNED_URL` 环境变量传 presigned URL，不要作为命令行参数，因为 argv 可被 `/proc/*/cmdline` 或 `Get-Process` 看到并进入 shell 历史。
28. Step 1：调用上传工具并省略 `fileUrl`；按 schema 填写 `category: "sprite"`、与现有资产匹配的 `subcategory`、`name`、1–2 句 `description`，以及 schema 要求时的 `fileName`/`contentLength` 等文件元数据；响应中的 `presignedUrl` 只保留在推理上下文。
29. Step 2：用该 presigned URL PUT PNG 二进制；PUT 本身是普通二进制上传，不需要认证头（签名已嵌入 URL）。
30. 在 Windows PowerShell 5.1 中优先用 `curl.exe`，不要用 `Invoke-WebRequest`，因为后者默认走 IE 引擎，在 Windows 11 上可能因 IE 首次配置长时间卡住（字节已上传但调用看似冻结）；`curl.exe` 在 Windows 10 1803+ 与 Windows 11 的 System32 中，PowerShell 与 Git Bash 行为一致。
31. PowerShell 中用 `curl.exe -K -`：通过 stdin 配置传入 `url`、`request = PUT`、`upload-file = out.png`；把 URL 放入 `$env:PAINTER_PRESIGNED_URL`，结束后在 finally 中 `Remove-Item Env:\PAINTER_PRESIGNED_URL`。
32. bash（Git for Windows/WSL）中把 `export PAINTER_PRESIGNED_URL="..."` 作为单独语句赋值，不要用内联前缀 `VAR=… curl …`，否则同命令行会提前展开为空 URL；然后用 `printf` 生成 `url = ...`、`request = "PUT"`、`upload-file = "out.png"` 并通过 `curl -K -` 读取，最后 `unset PAINTER_PRESIGNED_URL`。
33. 仅在 `curl.exe` 确实不可用时回退到 `Invoke-WebRequest`：必须加 `-UseBasicParsing` 跳过 IE 引擎，并设置 `$ProgressPreference = 'SilentlyContinue'` 关闭进度条以避免 10–50× 变慢；仍通过环境变量传 URL 并在 finally 清除。
34. Step 3：再次调用与 Step 1 完全相同的上传工具和相同参数，只额外添加 `fileUrl` 为 Step 1 的 presigned URL；不要把 URL 先拷贝到代码块或 markdown 给用户看；响应中的 sprite RUID 是最终交付物，之后 URL 视为已消费。
35. Step 4：创建工具不接受 `properties`；Step 3 返回 RUID 后立即用资产 `guid` 调用 `mcp__msw-mcp__asset_update_resource_storage_info`。
36. 属性条目使用小写 `{ "key": "...", "value": "..." }`，value 为字符串；不要照搬 resource 响应里 `Properties: [{ "Key", "Value" }]` 的大小写。
37. 属性表：`pivot_x`/`pivot_y` 为数字字符串；`border_left`/`border_right`/`border_top`/`border_bottom` 为像素数字字符串；`filter_mode` 为 `Point`/`Bilinear`/`Trilinear`；`wrap_mode` 为 `Repeat`/`Clamp`/`Mirror`/`MirrorOnce`。
38. painter 默认属性：`filter_mode=Point`（Bilinear 会糊掉 chunky/maple 像素边缘）、`wrap_mode=Clamp`、`pivot_x=0.5`；图标/UI 面板 `pivot_y=0.5`，角色和站在地面的道具 `pivot_y=0.0`，只有视觉检查发现脚部漂移时才调整。
39. 仅当 sprite 是 9-slice UI 框（按钮/面板/仪表）时设置非零 `border_*`；`.ui` 侧还需要 `SpriteGUIRendererComponent.Type = Sliced(1)`（见 `component-api.md` 的 SpriteGUIRenderer — ImageType Selection）。
40. 不要发明属性表之外的 property key 或 enum 值；如果连接的 MCP 工具列表没有 `asset_update_resource_storage_info`，把打算设置的属性值报告给用户，不要调用其他工具。
41. 选择 subcategory：先用 `asset_search_resources` 或 `asset_list_account_resources` 查看已有 sprite 的 subcategory 分布并匹配；不确定时回退到通用值如 `object` / `etc`。
42. 任务完成后只交付：`RUID: <收到的 RUID>`、`Style: <chunky | maple>`、以及 1–2 句描述（画了什么、多大、注册成什么 sprite）。
43. 实体创建/移动/生成、脚本编写、UI 编辑等不在 painter 范围内，交给其他技能或后续步骤。
44. 常见坑：未先跑 `npm ci` 就运行 `render.cjs` 会报 `Cannot find module 'puppeteer'`；只需首次安装，且必须用 `npm ci` 安装 lockfile 固定版本。
45. 常见坑：省略 `--width` / `--height` 会回退 128×128；如果用户想要其他尺寸就得重画，所以始终显式指定。
46. 常见坑：SVG/Canvas 内容只出现在 PNG 左上角，通常因为绘制代码声明了自己的尺寸（如 SVG 固定 width/height 或 Canvas 硬编码 scale）而 render.cjs 用了更大的 --width/--height；修复：SVG 用 width=100% height=100%，Canvas 从 `c.width` 推导 scale。
47. 常见坑：背景变黑是因为在 SVG/Canvas/HTML 中画了背景；要保持透明就删除背景形状。
48. 常见坑：曲线看起来平滑：chunky 下是违规，移除 `arc()`/`bezierCurveTo()`/gradients 并用点重画；maple 的平滑应来自轮廓处的选择性 AA 像素，而不是 gradient/curve API，API 禁令仍适用。
49. 常见坑：maple sprite 看起来像加了很多颜色的 chunky：通常忘了个表面的 selout（1px 更暗描边）和/或轮廓选择性 AA；重新检查 `style-maple-cartoon.md` 的 Selout 与 Selective AA 部分。
50. 常见坑：chunky sprite 发糊/模糊：在边缘加了中间色像素；chunky 禁止所有抗锯齿，移除过渡像素并保持边缘锐利；如果想要更柔和，改用 maple。
51. 常见坑：maple sprite 在 32×32 输出下难看：maple 需要 ≥64×64 才能容纳 selout + AA + 五官；要么增大尺寸，要么改用 chunky。
52. 常见坑：PUT 步骤 401/403：presigned URL 过期或错误；丢弃该 URL 并从 Step 1 重新开始。
53. 常见坑：完成调用时改了其他参数：必须与 Step 1 完全相同的参数，只添加 `fileUrl`。

适用边界 · 注意事项

• 当 msw-search 返回符合意图的 RUID 时，不要调用 painter，直接用该 RUID。
• 本技能只处理 sprite 类别，不处理 animation、audio、avatar、atlas。
• 如果连接的 MCP 没有上传工具且用户无法通过 Maker 注册 PNG，或任务属于实体放置、脚本、UI 编辑，则不要使用 painter。