---

name: pindou-pattern description: 生成拼豆图纸（perler bead pattern）。把任意图片或像素数据量化为 205 色、5 大品牌色号（MARD/COCO/漫漫/盼盼/咪小窝）的拼豆施工图 PNG，含格内色号、行列坐标、加重网格线、色号用量统计，并可导出 CSV 物料清单。当用户提到拼豆、拼豆图纸、色号、像素画导出、把图片转成 N×N 拼豆、串珠/珠子图案、perler bead pattern、bead pattern 时使用；当用户对已生成图纸不满意（效果不好/不好看/颜色太乱/太杂/优化一下/AI 优化/重新弄好看点）时，先用 AI 图像编辑（基于原图参考图的 chibi 白底像素风改绘）再重新生成图纸。

拼豆图纸生成（pindou-pattern）

把图片或像素数据变成可直接照着拼的拼豆图纸 PNG：深色标题栏 + 渐变品牌 Logo + 四周行列坐标 + 30px 色块网格（格内标品牌色号、每 10 格加重线）+ 色号用量统计区。

AI 优化效果（用户不满意时的处理流程）

当用户对已生成的图纸表达不满——如"效果不好"、"不好看"、"颜色太乱/太杂"、"细节糊了"、"帮我优化一下"、"AI 优化"、"重新弄好看点"——不要只调量化参数，走 AI 重绘 → 重新生成 两步。

第 1 步：AI 图像编辑（按优先级选择提供方）

优先：agent 自带的 imagegen 工具。 先检查你自己是否具备图像生成/编辑工具（如 Codex/WorkBuddy 会话内置的 image_gen、以 MCP 工具形式暴露的 imagegen 等）。若有，直接用它执行下面的默认 PROMPT 编辑原图（必须把原图作为参考图传入，纯文本提示会凭空重绘出无关内容），把结果保存为本地文件（如 原名_optimized.png），跳过 optimize.js：

图片修改为：chibi画风，背景白底。pixel art style, 16-bit, retro game aesthetic, sharp focus, high contrast, clean lines, detailed pixel art, masterpiece, best quality

没有自带工具时：运行 optimize.js，脚本自动选择提供方（--provider auto）：

node .agents/skills/pindou-pattern/scripts/optimize.js 原图.png
# 提供方优先级: codex（WorkBuddy 版）CLI 内置 imagegen（免积分，需已装并开启 image_generation）
#              → apiz CLI 图像编辑（约 60~65 积分/次，默认 openai/gpt-image-2/edit，兜底）

第 2 步：用优化图重新生成图纸

node .agents/skills/pindou-pattern/scripts/generate.js 原图_optimized.png --size 48 --system 盼盼 --blank-white --max-colors 16

要点：

• 优化图路径以第 1 步 stdout 打印的实际输出为准：codex 路径默认 _optimized.png，apiz 路径默认 _optimized.jpg，不要照抄示例里的扩展名。
• --max-colors 16 是 AI 优化后的推荐搭配：AI 输出通常为 ~1024px JPEG，压缩噪点会让直接量化散出 100+ 色；收敛到 12~24 色后物料清单才实用。实测 104 色 → 16 色，主体轮廓不受影响。
• 优化结果交给用户对比判断：把原图、优化图、最终图纸三个路径都报给用户，由用户查看确认。不做视觉模型复核。若用户反馈优化图与原图内容无关（参考图未生效的表现），检查 --params image_urls 传参后重试。
• --blank-white 只用于白底主体图（卡通角色等），风景/满幅图案不要用（天空云朵是要买的豆子）。AI 的"白底"常带 ±10 偏色（实测 245,251,251），默认阈值 240 已能接住。
• --prompt 可换自定义指令；apiz 路径 --model 可换编辑模型（默认 openai/gpt-image-2/edit）。
• 全部提供方不可用时，回退为仅调整 --max-colors / --size / --match 参数，并向用户说明。

环境

• Node.js（≥16）+ sharp（唯一 npm 依赖，skill 根目录已带 package.json）。首次使用在 skill 根目录执行一次 npm install 即可；若脚本报缺少 sharp，提示用户执行该命令。依赖按脚本所在路径向上查找 node_modules，与当前运行目录无关；仅当上游目录（如本仓库根 node_modules）已装 sharp 时可免安装直接运行。
• AI 优化为可选能力，额外依赖（按提供方）：agent 自带 imagegen 工具 / codex CLI / apiz CLI，三者任一即可，全部缺失时仅影响 AI 优化（出图不受影响）。

快速开始

# 图片 → 32×32 MARD 图纸（默认输出 <输入名>_pattern.png）
node .agents/skills/pindou-pattern/scripts/generate.js 素材/卡通猫.png

# 指定品牌、尺寸、标题、输出路径，并把近白背景当空格
node .agents/skills/pindou-pattern/scripts/generate.js 素材/卡通猫.png \
  --size 48 --system 盼盼 --title 卡通猫 --blank-white --out 图纸/猫.png

# JSON 像素数据 → 图纸 + CSV 物料清单
node .agents/skills/pindou-pattern/scripts/generate.js 作品.json --csv 物料.csv

输入格式

图片（png/jpg/webp/bmp/gif/tiff）或 JSON。JSON 格式：

{
  "gridSize": 16,
  "pixelData": ["#FFFFFF", "#FBED56", "..."]
}

• 图片输入：透明区域先合成白底再量化；非方形图片等比缩放（contain）、空缺处补白，不加 --blank-white 时补白会计入浅色豆
• pixelData 行优先一维数组，长度 = gridSize²，#FFFFFF 表示空格（不买豆）
• JSON 中的非调色板颜色默认自动吸附到最近的 205 色色号（保证能买到豆子）；--no-snap 关闭

常用选项

| 选项 | 说明 | 默认 | |------|------|------| | --size <n> | 网格 N×N（4~150），仅图片输入生效 | 32 | | --system <name> | 色号系统：MARD / COCO / 漫漫 / 盼盼 / 咪小窝 | MARD | | --match <mode> | 颜色匹配：rgb（欧氏距离）/ lab（感知色差，通常更准） | rgb | | --blank-white | 图片近白色当作空格 | 关 | | --white-threshold <n> | 近白判定阈值（配 --blank-white，默认 240；AI 白底常带 ±10 偏色，必要时可调低到 230 更激进留空） | 240 | | --max-colors <n> | 色数收敛：保留用量前 n 色，低频色并入最接近的保留色（照片/AI 优化图推荐 12~24） | 不限制 | | --title <text> / --watermark <text> | 标题 / 水印（空串去除） | 拼豆图纸 / pindou.348349.xyz | | --interval <n> / --grid-color <hex> | 加重线间隔 / 颜色 | 10 / #555555 | | --no-grid --no-coordinates --no-cellnumbers --no-stats | 关闭对应图层 | 全开 | | --csv <path> | 导出色号用量 CSV（Excel 友好带 BOM） | 无 | | --out <path> | 输出 PNG 路径 | <输入名>_pattern.png |

完整选项见 node .../generate.js --help。

回归测试（skill 改动后跑一次确认功能正常）：

node .agents/skills/pindou-pattern/scripts/generate.js .agents/skills/pindou-pattern/assets/sample-heart.json --out heart_test.png
# 预期: 16x16 | 用色 2 种 | 总豆数 128 颗 | F02 ×125 | E03 ×3（验证后删除 heart_test.png）

工作流程

1. 确认用户想要的：网格尺寸（16/24/32/48/100 是常用档位）、品牌色号系统、是否需要背景留空。若用户表达的是对已有图纸的不满，转到上面的「AI 优化效果」流程。
2. 运行 generate.js，命令会向 stdout 打印：输出路径、画布尺寸、用色数、总豆数、每个色号的用量。
3. 向用户报告：图纸路径 + 色号用量清单（直接引用 stdout 统计）+ 总豆数；有 CSV 时一并给出路径。

不做视觉目检。 生成流程是确定性的，客观指标以脚本 stdout 统计和（必要时）像素级检查为准；图纸好坏由用户自行查看判断。不要用视觉模型去"复核"图片内容——实测幻觉率高，会制造误判。

色号数据维护

• 色号映射表 scripts/colorData.js（205 色 × 5 品牌）已内联在本 skill 中，运行不依赖任何外部文件。如需更新数据，传入 colorData.ts 源文件路径重新提取（勿手改 colorData.js）：

  node .agents/skills/pindou-pattern/scripts/_extract.js <colorData.ts 的路径>
  

• 渲染链路：SVG → sharp → PNG。