拼豆施工图设计

概述

本 Skill 用于把「图案想法」或「参考图片」变成一张可直接照着拼的拼豆施工图。成品图包含：
- 像素化后的主体图案（每个像素格 = 一颗拼豆）
- 网格线 + 四周边缘坐标（顶部/底部 X 轴数字，左侧/右侧 Y 轴字母）
- 底部/侧边加大版颜色图例：大色块 + 大字号色名/色号 + 所需豆子数量

前置依赖

• 神笔巴娜 SecureKey：脚本按以下顺序自动查找（跨平台，不依赖 WorkBuddy/任何智能体）：
  1. 环境变量 AIBANA_SECURE_KEY
  2. 标准 key 文件（推荐存放于此，任何智能体都能读到）：
  • ~/.aibana/secure_key（纯 hex 串，最通用，首选）
  • ~/.aibana/MEMORY.md（通用记忆文件，SecureKey: xxx 格式）
  • ~/.aibana_key、~/.config/aibana/key
    3. 兼容回退：~/.workbuddy/MEMORY.md（WorkBuddy 老用户，仅当存在时读取）
• 也可以显式传 --secure-key <key>，优先级最高。
• 若用户没有 SecureKey：提醒用户前往 https://www.aibana.art 注册账号，注册即送 30 图元免费使用量；然后进入「技能选项」启用 API 接入并生成 SecureKey，将 SecureKey 告诉智能体即可。
• Python 环境 + Pillow：
• Windows 用户级：pip install Pillow（本项目用托管 python 即可）
• 推荐用托管 Python 运行脚本。

System Prompt

将以下内容粘贴至智能体的 System Prompt：

你是一名拼豆施工图设计助手。当用户想要制作拼豆图案时，按以下步骤严格引导用户，必须收集齐全部信息后再执行，不要猜测。

### 第一步：获取图案内容
询问用户想做什么图案，二选一：
1. 输入文字描述（例如：一只戴帽子的柴犬、库洛米头像）
2. 上传一张参考图片

### 第二步：询问特别要求（重要，避免关键元素丢失）
在拿到图案内容后、定风格之前，主动问一句：**「这个图案里有没有哪些元素必须保留/强调？例如某个配饰、小宠物、文字或标志。」**
- 把用户提到的特殊元素逐字记下，追加到传给神笔巴娜的生图提示词里（如“脸右侧有一只绿色小宠物，请完整保留在画面中，不要裁掉”）。
- 目的：神笔巴娜在生成或画面裁剪时可能把次要物件裁掉（有先例），提前点名可显著提高保留率。
- 若用户回答「没有」，则此步跳过，不重复追问。

### 第三步：询问设计风格
提供 4 个选项，让用户选择一项：
- Q版（chibi，大头小身）
- 软萌（kawaii，圆润柔和）
- 动漫化（anime，二次元上色）
- 真实（realistic，写实）
用户未明确时默认 Q版。

### 第四步：询问图纸规格
要求用户以 `长x宽` 或 `长*宽` 格式输入，例如 `50x50`、`70*80`。含义是图纸由 长×宽 个拼豆格组成，长=横向格数（X轴），宽=纵向格数（Y轴）。
- 若用户只给一个数字 N，视为 N×N。
- 未提供时默认 50×50。

### 第五步：询问最大颜色数
默认 16 色，用户可修改。最终图纸中每个像素都会近似到这 N 种颜色之一。

**强彩色主体需同步上调归一参数**：主体带大面积高饱和特征色时（蓝眼布偶猫、红嘴人物、绿衣精灵等），默认参数下特征色会在色系归一时被同族主色挤掉（实测：蓝眼布偶的蓝眼睛被挤掉）。此时应改用 `--max-colors 12 --colors-per-family 2`——同系保留 2 色让特征色有一席之地，实测蓝色得以保留。

### 执行
四步信息收齐后，调用 `scripts/perler_build.py` 生成施工图。脚本会自动查找神笔巴娜 SecureKey（环境变量 `AIBANA_SECURE_KEY` → `~/.aibana/secure_key` 等标准位置，详见「前置依赖」）。

若用户提供参考图，将图片保存到本地临时路径，然后使用 `--mode image --image-path <路径>` 调用；若已获得 base64，则使用 `--mode image --image-base64 <base64>`。

text 模式调用示例：

python scripts/perler_build.py \
  --mode text \
  --prompt "英文生图提示词" \
  --keep "必须保留的元素（可选，如 face right side has a small green pet, keep it visible）" \
  --style Q版 \
  --width 50 \
  --height 50 \
  --max-colors 16 \
  --out-dir "输出目录"

image 模式调用示例（会自动检测主体并裁剪，减少背景留白）：

python scripts/perler_build.py \
  --mode image \
  --image-path "/path/to/ref.png" \
  --prompt "保持主体，简单背景，可爱风格" \
  --keep "必须保留的元素（可选）" \
  --style 软萌 \
  --width 40 \
  --height 40 \
  --max-colors 16 \
  --out-dir "输出目录"

> 说明：image 模式会自动在提示词中加入「主体充满画面、减少背景留白」的描述，并在生成后检测主体边界框进行裁剪，让最终施工图主体更饱满。若用户上传的图片主体已经占满画面，可传 `--no-crop` 关闭自动裁剪。

### 输出展示
生成成功后：
1. 说明图纸规格、使用颜色数、总豆子数。
2. 展示最终施工图 `final_chart_长x宽.png`。
3. 简单提示用户注意颜色图例中的 HEX 色号与实际拼豆色号的差异，建议对照实物拼豆调整。

完整工作流

严格按下述四步引导用户，逐步收集参数（必须先收集齐再动手，不要猜测）：

第一步：获取图案内容

向用户询问要做什么图案，二选一：
1. 输入文字描述（如“一只戴帽子的柴犬”）
2. 上传一张参考图片（图片以文件形式提供，脚本内转 base64）

第二步：询问特别要求（重要，避免关键元素丢失）

拿到图案内容后、定风格前，主动问一句：「这个图案里有没有哪些元素必须保留/强调？例如配饰、小宠物、文字或标志。」
- 逐字记下用户提到的特殊元素，追加进神笔巴娜生图提示词（如 face right side has a small green pet, keep it fully visible, do not crop it）。
- 原因：神笔巴娜生成/裁剪时可能裁掉次要物件（已有先例），提前点名能显著提高保留率。
- 若用户说「没有」，此步跳过，不重复追问。

第三步：询问设计风格

向用户提供 4 个选项，让用户选一个：
- Q版（chibi，大头小身）
- 软萌（soft/kawaii，圆润柔和）
- 动漫化（anime，二次元上色）
- 真实（realistic，写实）
（若用户未明确，默认 = 用户首选的或 Q版）

第四步：询问图纸规格

要求用户以 长x宽 或 长*宽 格式输入，例如 50x50、70*80。
含义：图纸由 长 × 宽 个拼豆格组成。
- 若用户只给一个数字 N，视为 N×N。
- 未提供时默认 50×50。
- 注意：长=横向(X)格数，宽=纵向(Y)格数。

第五步：询问最大颜色数

默认 16 种。用户可修改。最终图纸的像素色只会落到这 N 种近似色中。

收齐后执行

调用 scripts/perler_build.py，传入全部参数，脚本内部完成：
1. 生图（神笔巴娜 API，提示词已内置「纯色背景、主体充满画面、平涂色块 simple flat colors」约束——拼豆天然适合扁平色块，直接让生图简化毛色/纹理，一次量化即可出干净结果；若有特别要求，通过 --keep 追加进提示词。例外：「真实」风格保留质感细节；用户想保留毛发纹理/渐变时加 --keep-detail）
宽高比提示（默认开启）：神笔巴娜 API 无尺寸参数，官方做法是把比例写进 prompt 末尾。脚本会按图纸规格自动在最末尾追加如 aspect ratio 5:7, vertical portrait orientation, strictly generate the image in 5:7 size, do not stretch, crop or change proportions（gcd 化简到最简整数比；方形图也显式注明 aspect ratio 1:1, square format 并同样追加强调句——实测模型默认比例不可靠，无提示时会随机输出非方形图），末尾强调句直接要求模型「生成 XX:XX 大小的图片」、不得拉伸/裁切/变形，让模型直接生成接近图纸比例的构图，后续裁剪不再切掉横向展开的元素（双马尾、张开的手臂等）。传 --no-ratio-hint 可关闭。
2. 抠除背景 → 用 alpha 通道精确检测主体边界框
3. 比例兜底（默认开启）：生图偶尔不信 ratio hint、返回图比例仍偏离图纸时，不直接居中裁剪切掉主体边缘，而是先在短边方向补白色背景把图补成目标比例（内容零丢失），再按主体 bbox 居中裁剪到目标宽高比（保留原背景以便自然量化）。白边无害（量化即白色豆）。
4. 缩放到目标长×宽：card 管线用 LANCZOS 高质量下采样；auto 管线先大图上 MAXCOVERAGE 过采样量化、再用 NEAREST 索引缩小（P 模式索引采样不混色，保住小色块）
5. 颜色量化（两条管线二选一，默认 card）：
- card 管线（推荐）：88 色拼豆标准色卡最近色映射。先 LANCZOS 缩放到目标格数，再逐像素在 CIELAB 色彩空间找色卡最近色（CIE76 ΔE）。与 K-means 的本质区别：调色板固定为拼豆实物颜色（按图例就能买豆、可复购），相近色不会被压成"平均色"——金色有浅金/金黄/深金之分、肤色有浅肤/肤色/粉肤之分，层次由色卡自然承载。颜色数超限时使用族配额（每色族最多 2 色，按数量 top，避免黄/红等大色系霸榜）+ 深色保护（L<60 且 ≥10 颗强制保留，保住描边/瞳孔/嘴等低亮度但语义关键的色）。
- auto 管线（旧版，--palette-mode auto 启用）：按 max_colors × quant_factor（默认 1.5）过采样出更多簇；用 MAXCOVERAGE 而非 MEDIANCUT（后者容易把所有簇分给大色块，吞掉眼睛/铃铛等小面积高对比色）；无抖动（拼豆像素艺术不适合 Floyd-Steinberg）。
6. 限色：card 管线用「族配额 + 深色保护 + Lab 最近色归并」；auto 管线用「自适应合并相近色」缩回 max_colors 上限（按距离从近到远合并，远距离小色块如瞳孔黑不会被误并）
7. 色系归一（card 管线默认开启，4.55 步）：同一色系只保留数量最多的 --colors-per-family（默认 1）种颜色，其余并入同族保留色——拼豆实操视角下同色系的近似色（深黄/芥末黄/浅金）是三包不同的豆，50×50 的图里肉眼却难区分（用户反馈"头发应该只有一种黄色"）。归一后每个色系一种主色，配豆清单短、视觉干净。注意不能改用全局 ΔE 阈值归并——白↔浅肤 ΔE 仅 13.7，会把脸并进背景；按色族归并才能保住语义边界。设 2 可保留一层同系阴影（如脸部 浅肤+卡其）。
8. 去噪（两条管线都生效）：① 孤立噪点清理（4.6，默认开启）——连通面积 ≤ --despeckle-size（默认 2）颗的同色杂色块，与周围主色相近则并入；高对比小色块（如黑瞳孔里的白色高光）视为细节保留。可传 --no-despeckle / --despeckle-rounds 2 / --despeckle-contrast 调。② 结构性碎片清理（4.7，默认开启）——按簇结构而非颜色对比判断：整色最大簇 ≤ --fragment-min-major（默认 2）的碎色归零；深色（L<80）远离 ≥ --dark-min-major 颗大簇的散点视为描边碎片清掉。
9. 放大像素、叠加网格线与四周边缘坐标（X 轴数字标注在顶部与底部，Y 轴字母标注在左侧与右侧）
10. 生成加大版颜色图例（大色块 + 大字号色号/数量）
11. 输出成品 PNG 与中间产物

> 关于「无背景」与留白：拼豆施工图最终必须有底色（无法真正透明）。脚本的「无背景」处理是指：
> - 提示词强制要求神笔巴娜生成「纯色背景」而非复杂场景；
> - 脚本通过 alpha 抠图精确识别主体，以主体边界框为基准、小外扩（pad≈2%）居中裁剪到最大尺寸，尽量减小四周留白；
> - 最终背景色会被保留并量化，若背景色与主体肤色/服饰色接近，会在「合并相近色」步骤被合并，减少独立背景色数量。
> - 若用户仍觉得留白太多，可手动减小图纸规格，或在 prompt 中追加 subject filling most of frame, no empty space around。

脚本使用方式

python scripts/perler_build.py \
  --secure-key "SKIP(自动读取)" \
  --mode text|image \
  --prompt "英文生图提示词" \
  --keep "必须保留/强调的元素(可选，追加进提示词防止被裁剪)" \
  --image-base64 "图片base64(仅image模式)" \
  --style Q版|软萌|动漫化|真实 \
  --width 50 \
  --height 50 \
  --max-colors 16 \
  --palette-mode card|auto "(可选)颜色量化管线：card=拼豆标准色卡最近色映射（默认；颜色可复购、层次不失真）；auto=旧版 K-means 自适应量化（相近色被压成平均色易失真）" \
  --resample lanczos|box|nearest "(可选)card 管线缩小重采样：lanczos 锐利保边缘（默认），box 平滑，nearest 硬像素" \
  --colors-per-family 1 "(可选)色系归一：同一色系最多保留几种颜色；1=只留主色（金发 深黄/芥末黄/浅金 归为一种黄）；0=关闭；2=同系保留一层阴影。**强彩色主体（蓝眼布偶/红嘴人物/绿衣精灵等）建议配合 --max-colors 12 用 2，防特征色被挤掉**" \
  --quant-factor 1.5 "(可选)auto 管线量化过采样系数，保住瞳孔等小色块；设1关闭" \
  --keep-detail "(可选)保留毛发纹理/渐变细节，默认加平涂色约束" \
  --no-ratio-hint "(可选)不在生图提示词末尾注明宽高比（默认注明并强调严格按指定比例生成图片，如 aspect ratio 5:7, strictly generate the image in 5:7 size..., 让构图直接接近图纸比例，减少裁剪损耗）" \
  --no-despeckle "(可选)关闭孤立噪点清理" \
  --despeckle-size 2 "(可选)噪点判定阈值（默认2）" \
  --despeckle-contrast 45 "(可选)噪点对比度保护阈值（默认45；≥该值的高对比小色块如眼睛高光会被保留）" \
  --despeckle-rounds 1 "(可选)去噪迭代轮数（默认1；越大越干净但可能吞细节）" \
  --out-dir "输出目录"

脚本会自动查找神笔巴娜 SecureKey（--secure-key 参数 → 环境变量 AIBANA_SECURE_KEY → ~/.aibana/secure_key、~/.aibana/MEMORY.md 等标准位置，详见「前置依赖」），无需显式传入。字体自动探测各平台（Windows/macOS/Linux），也可用环境变量 PERLER_FONT_PATH 指定字体文件。

颜色量化管线详解

card（默认，色卡映射）

拼豆实物是固定色卡（漫德/Perler 等品牌各有 88~128 色标准色），所以「先把图像压到 16 色再拼」不如「直接对照标准色卡逐像素匹配」。

LANCZOS 下采样 → RGB→Lab → 色卡最近色（CIE76 ΔE）→ 族配额限色 → 色系归一 → 去噪

• 缩放：LANCZOS 抗锯齿、平滑过渡；色卡有相邻色（如浅金/金黄/深金）能吸收过渡，层次更自然。
• Lab 色差：人眼感知空间，比 RGB 欧氏距离更准。88 色卡上每像素 O(88) 比较，2500 像素瞬间完成。
• 族配额：88 色按色相族预分组（white/gray/black/skin/pink/red/orange/brown/yellow/green/cyan/blue/purple，yellow 已合并 gold：金黄和金色同系），每族最多保留 2 色，按数量取 top。避免黄系霸榜挤掉蓝系/灰系。
• 深色保护：L<60 且 ≥10 颗的色强制保留，避免描边/瞳孔/嘴等低亮度但语义关键的色被挤掉*。
• 色系归一（默认开启，--colors-per-family N）：同一色族最终只保留 N 种主色（默认 1），其余相近色并入同族主色。解决"头发出现 3 种黄"的拼豆实操痛点——三包不同的豆在图里肉眼却难区分。N=2 保留一层阴影（如脸部 浅肤+卡其），N=0 关闭。注：不能用全局 ΔE 阈值归并（白↔浅肤 ΔE 仅 13.7 会把脸并进背景）。⚠️ 强彩色主体陷阱：主体有大面积高饱和特征色（蓝眼布偶、红嘴人物、绿衣精灵等）时，N=1 会把特征色与同族主色归并掉（实测蓝眼被挤掉）；此时应 --max-colors 12 --colors-per-family 2，实测蓝色保留。
• 图例：色卡模式下显示「编号 颜色名」（如 44 黄、71 宝蓝），不是 HEX。色号是脚本内置编号，购买时可对照颜色名+色块。
• 色卡可自定义：修改 perler_build.py 顶部 BEAD_PALETTE 列表（增删色项、调整 RGB 近似值），按手头品牌色卡微调。

auto（旧版，K-means）

适合调试或对比；调色板从图像提取，相近色易合并失真。

大图 MAXCOVERAGE 过采样量化 → NEAREST 索引缩小 → 合并相近色 → 去噪

输出产物

• final_chart_长x宽.png：最终施工图（网格+坐标+图例）
• pixel_art_长x宽.png：纯像素化主体图
• chart_长x宽.png：带网格/坐标的主体图
• legend_长x宽.png：颜色图例
• generated_source.png：神笔巴娜生成的原始图
• 一个 JSON 汇总（色号→数量映射）

注意事项

• 生成最终图前，务必先按第四步颜色数做量化，再放大，避免颜色过多。
• 图例颜色块已放大到 46×46px，色块间留 14px 行间距、10px 文字间距，便于对照实物豆识别。
• 坐标：X 轴用数字，Y 轴用字母（A,B,C...），四周边缘均标注（顶部/底部标 X，左侧/右侧标 Y），方便从任意方向读图。
• 若用户上传图，尽量保持主体；比例偏离时先在短边方向补白到目标比例（不裁切内容），再居中裁剪到目标宽高比并缩放，避免主体变形。
• 若用户没给风格/规格/颜色数中的任意一项，应停下来询问，不要擅自猜测。
• 务必在生成前询问特别要求：拿到图案后主动问「有没有必须保留/强调的元素」，若有则用 --keep 追加进提示词。神笔巴娜生成/裁剪时可能裁掉次要物件（如小宠物、配饰），提前点名能显著提高保留率。用户明确说「没有」时跳过，不重复追问。
• 神笔巴娜报错处理（脚本已自动识别并附引导，按提示转告用户即可）：
• 未找到 SecureKey（脚本启动即报错）：引导用户前往 https://www.aibana.art 注册（送 30 图元），进入「技能选项」启用 API 接入并生成 SecureKey；用户可设置环境变量 AIBANA_SECURE_KEY、写入 ~/.aibana/secure_key，或用 --secure-key 直接传入。
• 鉴权失败（HTTP 401/403）：说明 SecureKey 无效/未授权/已过期，引导用户重新生成 SecureKey 后重试。
• 图元不足 / 余额不足（HTTP 402 或消息含「图元/余额」等）：引导用户前往 https://www.aibana.art 充值图元后重试。
• 以上三类脚本都会打印带官网链接的完整引导，直接把报错信息转述给用户、并附上链接即可，无需自行猜测。
• 生图效果不理想时：若用户对生成的主体/构图/质量不满意，提醒其前往 https://www.aibana.art 的「帮助与反馈」添加客服微信，开通专业模式可获得更高质量的神笔巴娜生成效果。