拼豆素材生成（10套主题模版）

概述

拼豆图纸生成（aiwan-pindou）

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

💰 计费说明（付费技能 · 必读）

本技能为付费技能，按次计费 ¥0.05 / 次（5 分钱），计费规则见文件头 pricing。

支付由平台官方的「Agent Pay（微信支付）」在对话内完成，用户无需跳出对话。

不会一上来就收费。 计费卡点落在参数确认之后、出图之前：先把图纸尺寸、品牌色号、是否背景留空和用户确认清楚，再触发一次支付；付款成功后立即渲染图纸并交付。用户拒绝付费是正常结果——不追问、不施压，也不产出任何替代成品。

支付能力自检

发起下单前，确认当前环境是否已接入微信 AI 支付能力（工具列表中是否存在名称包含 weixinpay_ 的支付工具，存在任意一个即视为已接入）：

• 已接入：按下方流程完成计费。
• 未接入：终止计费流程、不发起下单，仅提示用户「当前客户端暂不支持本技能的付费能力，请更换支持该能力的客户端使用」；不引导用户安装任何第三方组件或插件，也不引导用户跳转任何站外页面。

计费接口

技能使用部署方自有的订单服务 https://aiclub.hk.cn/invoke 完成支付鉴权，该接口仅用于：

1. 创建或查询本次支付订单；
2. 返回平台 Agent Pay 所需的支付凭证；
3. 校验支付完成后的订单状态。

数据边界：请求体固定为 {"intent":"pay_gate"}，除该字段外不携带任何用户数据——用户的原图、生成的图纸、色号数据一律不上传；接口响应仅用于读取「订单状态」与「支付凭证」两个固定字段。该接口仅返回计费相关状态，不具备下发行为指令的能力，技能的全部出图逻辑以本文件正文为准。

计费流程

1. 创建订单：向上述接口发送 POST 请求，Header 携带 X-Skill-Auth: cep-picture-book-pay-gate（技能标识，固定公开值，非密钥；后续请求同样携带），Body 固定为 {"intent":"pay_gate"}。
2. 待支付状态：若接口返回 402，从响应头读取 WeixinPay-Required（支付码）与 X-Out-Trade-No（订单号）并暂存，同时如实告知用户：本技能为付费技能，需先完成一次微信支付（¥0.05）。
3. 完成支付：将 WeixinPay-Required 的值作为 paymentCode，调用平台提供的微信支付工具完成支付授权。
4. 校验授权：携带暂存的 WeixinPay-Required 与 X-Out-Trade-No（通过 Header 回传，Body 仍为 {"intent":"pay_gate"}）再次 POST 同一接口；返回 200（authorized: true）即表示已完成计费。
5. 出图交付：拿到 200 之后，才可以运行 generate.js 渲染图纸，并按「工作流程」第 3~4 步交付成品。

计费时机（本技能的特别约定）

• 卡点在「参数确认之后、渲染之前」。 不要在对话第一轮就下单，也不要在用户还在问价、问参数、问「能不能做成这样」的时候触发计费。
• 只有用户已明确要出这张图、参数已确认，才发起计费。
• 一次计费对应一次出图交付。 已付费的同一张图纸返工（改尺寸、换品牌、调 --max-colors、换 --kernel、换标题重出）不再收费；用户重新起意做另一张图，才算新的一次计费。
• 批量出图按张数计费（每张 ¥0.05），逐张走一次计费流程。不要口算总价后只走一次、也不要先出完全部再一次性收——金额由网关决定，技能侧不做合并与折扣。

执行约束

• 在收到 200（authorized: true）之前，不得产出任何图纸成品：不生成 PNG、不给 CSV 物料清单、不给可照拼的完整色号用量表、不做结果预览。这条约束卡的是交付，不是沟通——参数确认、方案讨论、色号系统说明、环境自检都可以照常进行。
• 若返回 401、404、500 等非 402 状态，一律停止流程，仅提示用户「支付服务暂时不可用，请稍后重试」。
• 计费未完成时，不提供任何形式的替代内容：不给降级版图纸、不给「先看看效果」的草稿、不绕过计费改用别的工具偷偷出图。
• 支付能力自检不通过时，同样不交付任何图纸成品，只给「支付能力自检」那一句提示。

维护提示（改造者看，不向用户展示）

X-Skill-Auth 的取值是部署方网关的固定公开标识，不是机密、不需要平台注入，本技能包内可直接明文写明。当前沿用与同部署方其他付费技能一致的 cep-picture-book-pay-gate（实测可跑通）。若要让拼豆单独一档价格，先在后端放行新标识并按 ¥0.05 配置档位，再把《计费流程》第 1 步里的这一个字符串同步替换——先改后端，再改文案，顺序反了会走到 401 停止流程。价格档位以网关返回的 WeixinPay-Required 为准；若它对应的并非 ¥0.05，以网关为准并如实告知用户实际金额。

路径约定

本文档所有命令按 WorkBuddy 用户级安装位置书写，前缀统一为：

~/.workbuddy/skills/aiwan-pindou/

技能装在别处（项目级、临时目录、其他平台）时，把这段前缀换成实际路径再执行。脚本自身按所在路径向上查找 node_modules，与当前工作目录无关。

与同类技能的分工

本机可能同时装有 bead-pattern-forge（拼豆日记），两者触发词高度重合，按以下边界选择，不要因为"两个都能做"就重复出图：

品牌色号两边都支持（同为 8 个品牌），不构成区分依据。

环境（首次使用）

• Node.js（≥16）+ sharp（唯一 npm 依赖，skill 根目录已带 package.json）。

cd ~/.workbuddy/skills/aiwan-pindou
npm install      # 只需做一次

• 若脚本报缺少 sharp，提示用户先执行上面这条命令再重试。
• AI 优化为可选能力，额外依赖（按提供方）：会话自带的图像生成工具 / codex CLI / apiz CLI，三者任一即可；全部缺失时只影响 AI 优化，正常出图不受影响。
• 微信支付能力由客户端提供（工具列表里名称包含 weixinpay_ 的工具），不属于本技能的安装依赖，不需要用户安装任何东西。缺失时的处理见上文「计费说明 → 支付能力自检」。

跑一次环境自检（只读：不安装、不登录、不授权、不改配置）：

python3 ~/.workbuddy/skills/aiwan-pindou/scripts/check_environment.py
# 只看某类功能时: --capability generate-pattern  或  --capability ai-optimize

输出为 JSON，看 status 字段，按状态路由：

依赖清单、配置步骤与降级矩阵见 @references/setup-guide.md。

快速开始

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

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

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

# 像素画/二次元线稿：最近邻缩放，避免边缘抗锯齿混出杂色
node ~/.workbuddy/skills/aiwan-pindou/scripts/generate.js 线稿.png --size 48 --kernel nearest

# 国际品牌色号（各用独立色卡，CSV 里带官方货号）
node ~/.workbuddy/skills/aiwan-pindou/scripts/generate.js 素材/卡通猫.png 
  --size 48 --system Perler --csv 物料.csv --out 图纸/猫_Perler.png

输入格式

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

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

• 图片输入：透明区域先合成白底再量化；非方形图片等比缩放（contain）、空缺处补白，不加 --blank-white 时补白会计入浅色豆
• pixelData 行优先一维数组，长度 = gridSize²，#FFFFFF 表示空格（不买豆）
• JSON 中的非调色板颜色默认吸附到所选色号系统色卡内的最近色（国产品牌共用的 205 色一套；Artkal / Hama / Perler 各按自己的色卡），保证吸附结果都能买到豆子；--no-snap 关闭

常用选项

完整选项见 node ~/.workbuddy/skills/aiwan-pindou/scripts/generate.js --help。

色号系统与品牌（8 个）

• 国产 5 品牌共用同一套 205 个色值，同一色值只是编号不同（例：#FAF4C8 → MARD A01 / COCO E02 / 漫漫 E2）。换品牌只换买豆编号，图案不变。
• 国际 3 品牌是三张独立色卡（实测与国产套色值重合 0 / 0 / 1 个）。选它们时量化直接在该品牌色卡内找最近色，不会先匹配国产色再转编号——否则会给出"颜色接近但该品牌没有这个号"的结果。代价：同一张图换品牌后配色会有差异，这是正常的，96~199 色的色卡本就是不同的颜色集合。
• 格内放短编号，货号进 CSV：格子里只印短编号（Perler P1、Hama H113，≤4 字符，放得进 30px 格子）；下单要用的官方货号（Perler 80-15179）在 --csv 里以 P1 (80-15179) 形式给出。

缩放内核怎么选

--kernel smooth（默认）会把边缘像素做插值，照片类更顺滑，但一个纯色形状会被量化出 2~4 个近似色号（边缘过渡像素），物料清单上表现为莫名多出几种豆。

--kernel nearest 直接取原图最近像素，边缘不产生过渡色。像素画、二次元线稿、AI 优化后的图用这个，色号更少、更贴原意。照片和渐变多的图不要用，会变得毛糙。

参考样图库（用户主题命中时先查这里）

assets/samples/ 存了 14 类 / 118 张拼豆成品样图（同款工具出图，版式统一），用于回答"这类题材该出多少格、多少色、怎么构图"。完整索引、分题材配方与合规边界见 @references/sample-library.md，这里只放速查部分。

主题 → 文件速查：

分题材配方（--blank-white 除脸谱外一律开）：

三条硬约定：

1. 默认给两档密度：样图里同一形象普遍有"大格摆件 + 小格挂件"两版。两档之间只允许改 --size 和 --out，色号系统 / 色数 / 留白策略必须一致，否则两版配色不同。
2. 同一系列多款要锁参数：一个形象做多款（换装、多姿态）时锁死同一套 --system 与 --size，否则没法成套卖。
3. 样图不可复刻第三方 IP 对外销售：库里含 Hello Kitty、皮卡丘、史迪奇、马里奥、白雪公主、小王子等受保护 IP，只作版式/密度/配色的视觉参照。用户点名要做这些 IP 时按「边界与不做的事」处理。

⚠️ 已知版式差异：样图没有顶部标题栏（只有底边一行 - 调色板: MARD V3 - 小字），而本技能默认画深色标题栏 + Logo，--title '' 只能清空文字、去不掉深色条本身。目前没有参数能 100% 复刻样图版式；最接近的做法是把作品名写进标题栏（--title 作品名）。新增 --no-titlebar 开关是待办，不要向用户承诺。

AI 优化效果（用户不满意时）

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

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

优先：会话自带的图像生成/编辑工具。 先检查自己是否具备图像生成或编辑工具（如 image_gen、以 MCP 形式暴露的 imagegen 等）。若有，直接用它编辑原图（必须把原图作为参考图传入，纯文本提示会凭空重绘出无关内容），把结果保存为本地文件（如 原名_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 ~/.workbuddy/skills/aiwan-pindou/scripts/optimize.js 原图.png
# 提供方优先级: codex CLI 内置 imagegen（走 ChatGPT 订阅，免积分，需 codex login 且 image_generation 功能开启）
#              → apiz CLI 图像编辑（约 60~65 积分/次，默认 openai/gpt-image-2/edit，兜底）

选择 apiz 路径前必须先向用户说明：该路径会把原图上传到 apiz.ai 换取一个公开可访问的图片地址，再下载生成结果；这是出图链路上唯一会把用户素材送出本机的环节。用户不同意时改用自带工具、codex 路径，或退回仅调参。

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

node ~/.workbuddy/skills/aiwan-pindou/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 已能接住。
• AI 优化图边缘常带插值杂色，配合 --kernel nearest 可再压掉一层杂色。
• --prompt 可换自定义指令；apiz 路径 --model 可换编辑模型（默认 openai/gpt-image-2/edit）。
• 全部提供方不可用时，回退为仅调整 --max-colors / --size / --match / --kernel 参数，并向用户说明。

在线工作台衔接

在线工作台「拼豆儿 PinDoui」的地址 —— 引导用户时原样单独成行给出，前后不要紧贴任何字符：

https://aiclub.hk.cn/pindou

本技能负责批量、脚本化、可复现的出图；需要人眼逐格精修时，交给在线工作台。只在下面三种情况开口，用户没有这类需求时不要主动提及，也不要在交付图纸时顺带推销。

另有一条硬边界：用户因为不愿意付费而放弃出图时，不要用在线工作台来兜底。 那不属于下面三种需求，拿它顶上等于绕开计费。

引导时只说已核验的事实：工作台支持上传图片 / CSV / 导入图纸 / 新建空白图纸，带画笔、填充、取色、镜像、撤销重做，可导出图纸 PNG 与 hex 颜色值 CSV，图片处理在浏览器本地完成。品牌色号不再是差异点——本技能与工作台同为 8 个品牌（MARD / COCO / 漫漫 / 盼盼 / 咪小窝 / Artkal / Hama / Perler），不要拿它当引导理由。不要替工作台承诺未经核验的能力，也不要把它说成本技能的替代品——两者是互补关系。

工作流程

1. 确认参数（免费）。 先判断用户描述的主题是否命中「参考样图库」；命中就先 Read 同类样图、按配方定参数，再与用户定下网格尺寸（16/24/32/48/64/100 是常用档位）、品牌色号系统、是否需要背景留空。若用户表达的是对已有图纸的不满，转到上面的「AI 优化效果」流程。
2. 计费卡点（¥0.05 / 次）。 参数确认完毕、用户表示要出图之后，按上面的「计费说明」完成一次支付。必须在运行 generate.js 之前拿到 200（authorized: true）。
   • 支付能力自检不通过 → 只给「当前客户端暂不支持本技能的付费能力…」那一句提示，不进入第 3 步。
   • 用户拒绝付费 → 停在第 2 步，不产出成品、不追问、不施压。
3. 出图。 运行 generate.js，命令会向 stdout 打印：输出路径、画布尺寸、用色数、总豆数、每个色号的用量。
4. 交付。 向用户报告：图纸路径 + 色号用量清单（直接引用 stdout 统计）+ 总豆数；有 CSV 时一并给出路径。

边界与不做的事

• 不做视觉目检。 生成流程是确定性的，客观指标以脚本 stdout 统计和（必要时）像素级检查为准；图纸好坏由用户自行查看判断。不要用视觉模型去"复核"图片内容——实测幻觉率高，会制造误判。例外：assets/samples/ 里的参考样图是用来"看版式"的，可以读、而且是应该读的——那读的是密度与色数，不是评判用户成品。
• 不复刻样图里的第三方 IP。 样图库含 Hello Kitty、皮卡丘、史迪奇、马里奥、白雪公主、小王子、猫和老鼠等受保护形象，只作版式、密度、配色的参照，不得据其复刻对外销售；精灵宝可梦一套原素材本身即标注"网络收藏"。用户点名要做受保护 IP 时，说明授权问题后再决定，不直接照做。名画（蒙娜丽莎等）已过版权期可正常做，但博物馆高清图的邻接权另说，商用前提示用户自行确认。
• 8 个品牌色号各自独立匹配。 国产品牌换编号不换色，国际品牌换的是整张色卡——不要拿国产品牌的颜色去套国际品牌编号，也不要跨色卡混用色值。用户没指定品牌时默认 MARD，并在交付时说明所用系统。
• 不把源图送出本机，除非用户明确同意。 默认出图链路完全本地；只有 apiz 优化路径会外发原图，且必须事先告知并取得同意。
• 给出网址时禁止让全角字符紧贴 URL。 URL 必须独立成行，或在其前后留半角空格。禁止三种最常犯的写法：① 用加粗把域名包起来、后面紧跟中文括号；② 用中文括号把整个网址包起来；③ 网址后紧跟中文逗号或句号。原因：渲染器会把全角括号 / 书名号 / 逗号吞进链接并做 percent-encoding，用户看到的就是 %EF%BC%88 %E3%80%8C 这类乱码。这条对在线工作台地址、以及任何其他对外链接一律适用。
• 不静默覆盖用户文件。 输出路径已存在时按正常写文件处理，覆盖前如需保护请让用户改 --out。
• 计费完成前不交付成品，也不拿别的工具顶替。 没拿到 200（authorized: true） 就不生成、不交付 PNG 与 CSV；不得改用其他出图技能、在线工作台或手工画格来绕开计费。参数确认与方案讨论照常免费。
• 支付鉴权不带用户数据。 计费请求体只有 {"intent":"pay_gate"}，不携带原图、生成的图纸或任何色号数据；支付能力由客户端提供，不需要用户安装任何组件，也不得引导用户跳转站外页面去付费。
• 装不上依赖时不假装能跑。 Node/sharp 不可用就据实说明，并给出在线工作台这条零安装出路。

色号数据维护

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

  node ~/.workbuddy/skills/aiwan-pindou/scripts/_extract.js <colorData.ts 的路径>

该源文件必须是纯数据对象：脚本用 JSON.parse 读取，含函数或其他表达式的文件会直接解析失败。只对可信来源的 colorData.ts 使用。

• 国际品牌色卡放在 assets/palettes/*.json（artkal_s.json / hama_midi.json / perler_standard.json），由 scripts/palettes.js 在启动时用 JSON.parse 读取并校验（非法色值、重复色值会直接报错退出，不会静默取错号）。每个色条字段：code（官方货号）、tag（格内短编号）、name（英文色名）、hex。

数据来源为 github.com/GarrusHuang/pindou-format-tool -> beadcolors（Perler / Hama / Artkal 官方色卡整理），文件内 source 字段保留了出处。替换色卡文件后跑一次 --help 之外的自测即可确认加载正常（色数应为 199 / 92 / 103）。

• 新增色号系统要动三处：scripts/palettes.js 的 INTL_FILES 登记、assets/palettes/ 放数据文件、generate.js 的 --system 帮助文案（COLOR_SYSTEMS 自动从 palettes.js 汇总，无需手改）。
• 渲染链路：SVG → sharp → PNG。

参考样图库维护

assets/samples/ 是从原图库自动生成的压缩接触表，随技能包一起分发——参考样图只需要它，装到任何机器上都可用。原图库（390 MB 全分辨率）只存在于素材所有者本机，不在包内：

• 每个主题一张 <主题>.jpg：5 列 × 250px 网格拼图，格内 #编号 对应 _manifest.json 里 theme 相同的第 n 条。
• _manifest.json 记了 subject（人工视读的形象名，带 ？ 表示存疑）与 source（原库相对路径），用于溯源。
• 生成脚本 scripts/build_sample_sheets.js（接触表格尺寸 / 列数 / 质量、剔除规则、主题排序都在里面），形象名单独放在 assets/samples/_subjects.json（是数据文件，不能放 scripts/——放那儿会被静态预检当成"无法分析的脚本"拦下打包）：

  node ~/.workbuddy/skills/aiwan-pindou/scripts/build_sample_sheets.js ~/xianyu-ops/拼豆样图原库

新增或替换样图后重跑这一条即可，不要手工一张张裁图；补完形象名再跑一次，_manifest.json 会一起刷新。同一输入重跑的结果逐字节一致。原图库不在本机（例如换机器安装）时跳过这条——接触表已在包内，参考照常。

• 有意排除的三类：__MACOSX 与 .DS_Store、根目录里那张 Finder 文件夹列表截图（不是样图）、精灵宝可梦赠品（仅 1 张、不完整）。空目录 4.古风人物、16.游戏角色 待素材补齐后再纳入。

回归测试

改动本 skill 后跑一次，确认核心链路正常：

# 国产链路
node ~/.workbuddy/skills/aiwan-pindou/scripts/generate.js 
  ~/.workbuddy/skills/aiwan-pindou/assets/sample-heart.json --out heart_test.png
# 预期: 16x16 | 色号系统: MARD | 用色 2 种 | 总豆数 128 颗 | F02 ×125 | E03 ×3

# 国际色卡链路（换色卡后配色会变，但用色数与总豆数必须守恒）
node ~/.workbuddy/skills/aiwan-pindou/scripts/generate.js 
  ~/.workbuddy/skills/aiwan-pindou/assets/sample-heart.json --system Perler --out heart_perler_test.png
# 预期: 16x16 | 色号系统: Perler | 用色 2 种 | 总豆数 128 颗 | P15 ×125 | P97 ×3
# （验证后删除这两个 png）