| name | brick-mosaic |
| description | 把任意图片转换成乐高(LEGO)积木马赛克像素画，使用官方乐高 Art 套装配色，生成预览图、SVG 拼搭说明书和零件采购清单；支持 AI 风格优化（效果不好时用 imageGen 图片编辑强化主体后再生成）。用户提到 乐高马赛克、LEGO mosaic、像素画、积木拼图、brick art、把照片/头像转成乐高风、马赛克拼搭说明书、用乐高套装拼人像、AI 优化像素画 等意图时使用——即使用户只是发一张图片说"做成像素风"或"乐高风格"也应触发。 |
brick-mosaic — 乐高 Art 套装马赛克生成器
将用户图片量化到乐高 Art 套装的官方配色，产出可直接拼搭的完整物料：马赛克预览图、A4 格式 SVG 拼搭说明书（总览页 + 16×16 分区页 + 颜色图例）、零件清单（Markdown/CSV）。算法与 brickMosaic 项目完全一致（贪心分配 + 交换优化），已通过等价性测试。
零依赖：只需 Node.js（≥14）。PNG/baseline JPEG 用内置解码器；progressive JPEG 及 webp 等格式自动回退系统 ffmpeg/magick（若有）。
快速开始
node .agents/skills/brick-mosaic/scripts/mosaic.js 照片.jpg \
--size 48x48 --sets beatles:1 --seed 42 --out ./mosaic-output
输出目录内容：
| 文件 | 说明 |
|---|
preview.png | 马赛克成品预览（每颗粒一个带凸点的方块） |
instructions/index.html | 浏览器打开查看全部说明书页，可 Ctrl+P 打印成 PDF |
instructions/page-*.svg | 标题页(总览+图例+用量) + 每区一页 16×16 编号网格 |
parts.md / parts.csv | 零件清单：颜色、Element ID、数量、来源套装 |
mosaic.json | 结构化结果（palette + 颜色索引网格），供二次加工 |
工作流程
- 收集参数（图片路径必填，其余给默认值并说明理由）：
- 尺寸
--size：默认 48x48（一个标准套装）。常见组合见下表。
- 套装
--sets：用户没说有什么套装时，按图片色调推荐一个（读 references/sets-guide.md 的套装色彩特点）。
- 宽高比检查（重要）：加载后比较原图宽高比与目标比例，差异 >15%（如 3:4 竖图 → 48x48 正方形）时默认加
--fit center（按目标比例裁中心）并明确告知用户："原图是竖幅/横幅，为避免拉伸变形已自动裁取中心区域；想保留完整画面可去掉该参数"。人像尤其要裁——压宽的脸明显失真。
- 用户提到"裁掉背景只留头像"→
--crop x,y,w,h（源图像素坐标，可先用 magick identify 或读图后估算）。
- 用户想调整色彩（更鲜艳/更亮/对比更强）→
--adjust。
- 首次生成加
--seed（如 42），效果不满意时同 seed 改参数可精确对比；用户认可后无需再提。
- 运行脚本，读 stderr 进度，检查 JSON 摘要（
usedColors、ignoredCount）。
- 用 Read 工具查看 preview.png 自查：主体是否可辨认？颜色是否大面积跑偏？若是，参照 references/tips.md 调整（换套装/调色/裁剪）后重跑。
- 汇报：预览图路径 + 零件清单摘要（用到几种颜色、总颗粒数）+ 说明书打开方式。
AI 风格优化（用户反馈"效果不好"时）
用户说"效果不好 / 太乱 / 颜色糊 / 主体不清晰 / 想要更艺术"时，优先试常规调整（换套装、--adjust、--fit）；用户明确要"AI 优化"或常规调整无效时，走 AI 风格优化。
AI 引擎按优先级二选一（两者独立，不可混淆）：
- agent 自带的 imageGen 工具（默认首选）：多数 agent 环境自带图片生成/编辑工具。若当前会话有此类工具，直接用它编辑源图，无需任何外部依赖。
- apiz CLI（替代方案）：环境没有自带 imageGen 时使用，调用
openai/gpt-image-2/edit 模型。需用户已配置 apiz 账号；未配置时指导用户安装/配置 apiz（apiz auth），或退回常规调整。完整命令模板与重试策略见 references/ai-optimize.md。
两条路径使用同一个固定 prompt（两段拼接，第一段为风格参考原文，第二段为保真约束——实测缺第二段时编辑模型会重新演绎人物、对不上原图）：
风格参考：{ "background": "纯黑色", "lighting": "戏剧性的低光", "style": "多边形艺术风格，锐利的线条和刻面，现代图形感，融合写实与抽象", "composition": "动态构图，焦点在 表情和姿势" }
重要：这是图片编辑任务，不是重新创作。必须严格保持输入图片中人物的原始特征——同一个人、相同的脸部特征、发型、表情、姿势、服装与构图位置，仅将渲染风格转换为上述风格参考，背景替换为纯黑色。不得改变人物身份，不得重新演绎。
生成优化图之后的流程两条路径完全一致（详见 references/ai-optimize.md）：
- 保存为
<outDir>/ai-optimized.png
- 用它重跑生成命令（其余参数不变），保持
--ignore-black 默认开启——纯黑背景不占颗粒、说明书标 '?'，主体颗粒更充裕，这正是设计意图
- 检查输出 JSON 的
ignoredCount > 0 确认黑背景衔接；为 0 时按 references/ai-optimize.md 归一化后重跑
- 对比新旧
preview.png，向用户展示差异
参数速查
--size WxH 尺寸 studs, 16~200（48x48=2304颗=1套装; 64x64=4096=2套; 96x96=9216=4套）
--sets key:N,... 套装及数量; N 支持小数如 0.9（限制颗粒库存，有艺术效果）
--fit stretch|center stretch=整图缩放(默认); center=按目标比例裁中心
--crop x,y,w,h 自定义裁剪(源图像素坐标)
--adjust k=v,... hue[-180,180]; sat/val/contrast/shadows/highlights[-100,100]
--ignore-black 忽略纯黑区域(默认开): 黑区不占颗粒, 说明书标 '?'——适合抠图后纯黑背景
--no-ignore-black 关闭(普通照片建议关闭, 避免暗部被误判)
--seed N 固定随机种子, 结果可复现
--no-optimize 跳过交换优化(快但质量略降); --max-rounds N 限制轮数
--name / --out / --preview-scale 作品名 / 输出目录 / 预览每颗粒像素数
套装 key：beatles monroe ironMan sith hogwarts mickey portrait world artProject elvis batman（详情读 references/sets-guide.md）
常见问题
- 效果不好/太乱/颜色糊：先试换套装（references/sets-guide.md）、
--adjust、--fit center；仍不满意 → AI 风格优化（见上方章节及 references/ai-optimize.md）。
- 颗粒不足报错：按提示加套装或缩尺寸。尺寸×尺寸 = 所需颗粒，必须 ≤ 套装总颗粒。
- 预览大片空白/灰色：图片背景为纯黑且开了 ignore-black——这是预期（黑区不拼颗粒）；不想要就
--no-ignore-black。
- 人物脸被压宽/变形：竖幅或横幅原图直接缩到正方形导致。加
--fit center 或 --crop。CLI 在宽高比差异 >15% 时也会打印提醒。
- 颜色太寡淡：图片色调与套装色板不匹配。换更匹配的套装（sets-guide.md），或
--adjust 提饱和度/调色相。
- 图歪了 90°：手机照片带 EXIF 旋转。先用
magick 照片.jpg -auto-orient 照片_fixed.jpg 转正再输入。
- 96×96 以上很慢（数分钟）：正常，优化阶段计算量大。先
--size 48x48 --no-optimize 快速预览效果，满意后再跑大尺寸。
- JPEG 报 progressive 不支持：需要系统装有 ffmpeg 或 magick 之一；都没有时让用户转存 PNG。
测试
改动 scripts/ 下任何文件后运行：
node .agents/skills/brick-mosaic/tests/run-tests.js
覆盖：PNG/JPEG 编解码器正确性（对照 ffmpeg/libjpeg）、两阶段算法与原版暴力实现的等价性、调色板一致性。18 项全部 PASS 才算通过。
