零依赖图标生成器

零依赖图标生成器

这个技能解决什么

需要给一个工具、技能或应用配图标，但：

• 装不上 Pillow（pip install 超时 / SIGTERM / 无网络 / 代理问题）
• 目标是「打开即用」的交付物，不该引入二进制依赖
• 只想画个几何符号图标，不需要照片级图形

→ 用标准库手写 PNG。一个 256×256 RGBA 图标只要约 4KB，生成耗时 < 1 秒。

快速开始

PY="C:/Users/DELL/.workbuddy/binaries/python/versions/3.13.12/python.exe"
S="$HOME/.workbuddy/skills/zero-dep-icon-gen/scripts/gen_icons.py"

# 看有哪些符号
$PY "$S" --list-symbols

# 生成单个
$PY "$S" --spec "my-tool:#4F46E5,#818CF8,browser" -o out/

# 批量（推荐：写 specs 文件，可版本控制）
$PY "$S" --specs-file specs.txt -o out/

# 512 尺寸 + 圆角 96
$PY "$S" --spec "my-tool:#059669,#34D399,check" --size 512 --radius 96 -o out/

# 点阵文字图标
$PY "$S" --spec "wb:#1E293B,#64748B,text|text=WB" -o out/

spec 格式：slug:#主色,#次色,符号[|key=value,key=value]

specs 文件每行一条，# 开头为注释。

可用符号

三条设计铁律（踩过坑，别推翻）

1. 符号用实心剪影，不要空心描边

第一版想做「空心描边框 + 内挖空」，结果内挖空把符号本身吃掉了：浏览器成了光板方块、 盾牌里对勾消失、文件夹横线被吞、云朵箭头畸形。

实心剪影两个好处：32px 缩略图下辨识度更高；实现上只需一层 if 在形状内: return True， 不用处理「边框+内洞」的布尔运算。

2. 判定顺序：先外框 → 再挖空 → 最后挖细节

以 sym_browser 为例，顺序错了细节会被覆盖：

1. 不在窗口外框内      -> False
2. 在屏幕区（挖空）    -> 屏幕内容线 True，其余 False   ← 提前 return
3. 在标题栏且碰到圆点  -> False                        ← 最后挖
4. 其余                -> True

第 2 步必须提前 return，否则第 3、4 步的 True 会把屏幕重新填实。

3. 边缘抗锯齿用「超采样 + shape_a 归一」

sym_a = (cov_sym / total) / max(shape_a, 1e-6)

必须除以 shape_a。否则在圆角边缘，像素的符号覆盖本身就是被形状裁剪过的， 再乘一次形状 alpha 会二次衰减，符号边缘出现一圈深色描边。

技术实现要点

PNG 编码（write_png）

只需 3 个 chunk，全部标准库：

png  = b"\x89PNG\r\n\x1a\n"
png += chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 6, 0, 0, 0))  # 6 = RGBA
png += chunk(b"IDAT", zlib.compress(raw, 9))   # raw = 每行前加一个 \x00 (filter None)
png += chunk(b"IEND", b"")

def chunk(tag, data):
    return (struct.pack(">I", len(data)) + tag + data
            + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF))

坑：zlib.crc32 在旧版本返回有符号 int，& 0xFFFFFFFF 保证一致； IHDR 的 CRC 必须覆盖 b"IHDR" + data，漏掉 tag 会导致图片打不开。

几何工具函数

• seg_dist(px,py,ax,ay,bx,by) — 点到线段距离，用于对勾 / 箭头杆 / 任意角度笔画
• bar_dist(px,py,x0,x1,y0,y1) — 轴对齐矩形距离，<=0 在内部，用于窗口 / 文件夹 / 横线
• rounded_square_alpha(...) — 圆角方形覆盖度

尺寸与体积参考

超采样倍数 SS = 2（2×2）。改 4×4 渲染时间 ×4，肉眼几乎无差别，不建议。

常见错误排查

与图标上传链路的衔接

生成完图标只是第一半。若目标是发布到技能市场，图标还需上传：

• SkillHub：图标没有独立更新端点，iconUrl 只能随 publish 的 payload 提交。 换图标 = 发一个新版本。先 POST /api/v1/community/skill-icons/upload （multipart 字段名 file）拿到 iconUrl，再放进 payload.iconUrl。 判据：响应里 iconAuditStatus: "pending" 表示收到；null 表示没生效。 完整流程见 skillhub-publish-skill 技能的 references/icon-upload.md。

• 若平台方是「上传 zip 包」，把生成的 .png 放在技能目录根部 （文件名 = slug），发布脚本的 find_icon() 会自动兜底找到。

资源

• scripts/gen_icons.py — 生成器主体，含 10 个符号 + 点阵字体 + PNG 编码器。 加新符号只需写一个 sym_xxx(x, y) 函数并注册进 SYMBOLS 字典。
• references/design-notes.md — 配色方案与从真实截图反推主色的方法。