HC3 设备图标
使用用户的语言回答。通过 scripts/icon_kit.py 生成图标（Python，需 pip install cairosvg pillow）：
该脚本包含样式辅助函数（渐变、软阴影、徽章、约 35 种徽章字形）、一个示例设备绘图（带卷帘的天窗，11 个位置）以及预览生成器。
样式（使这些图标贴合 HC3 界面的要点）
- 真实设备的写实绘制（形状、颜色、材质、视角）。向用户索要具体型号的照片并进行复制；绝不要描摹照片或复制制造商的徽标/商标（这样也能保持图标可分享）。如果用户明确想要一个个人使用的品牌徽标，请将该图标排除在任何公开发布的内容之外。
- 透明背景，每个状态一个文件——无需浅色/深色变体。为了在两个主题上保持可读性，请为深色设备添加浅色边缘（
stroke="#FFFFFF"1–2 像素或更浅的斜面），并且绝不绘制背景底板。 - 右下角小圆形徽章（中心点 100,100，半径约 22，白色圆环）：显示状态（绿：开，灰：空闲/关，红：警报，橙：警告，蓝：打开/级别，紫：自动……）或测量值（温度计、水滴、CO₂、风……）。设备绘图需避开该角落。
- 128 × 128 视口，绘图范围约 10–118 像素，落地式设备下方带有柔和椭圆阴影。
- 交付前检查预览图（
preview.png：每个图标在浅色/深色对角线背景上各显示一次）。
每个设备需要多少张图片（HC3 规则）
| 设备类型 | 一个图标集中的图片数量 | 上传字段 |
|---|---|---|
| 二进制（开关、binarySensor、门/窗、运动、烟雾……） | 2：空闲 / 激活 | icon0，icon100 |
| 多级（调光器、卷帘、阀门级别） | 11：0，10 … 100 | icon0 … icon100 |
| deviceController、大多数 QuickApp 父设备、multilevelSensor / 温度…… | 1 | icon0 |
单图片类型的设备无法自行更改其图标。对于状态依赖的 QA 图标（正常/警告/警报，或一种模式），请为每个状态上传一组图标，并通过 Lua 切换：self:updateProperty("deviceIcon", tonumber(self:optionalVariable("iconAlarm")))（ID 粘贴到变量中；模式参见 hc3-quickapp 技能中的 references/patterns.md §5）。 | ||
| 为每个有用的状态制作一个图标，并为 QuickApp 创建的每个设备（父设备和子设备）制作图标。 |
工作流程
- 列出设备（父设备、每个子设备、每个 Z-Wave 子设备）及其确切的
type（api.get("/devices/<id>")，例如com.fibaro.FGR224指 Fibaro 卷帘模块，com.fibaro.rollerShutter指 QA 子设备）。 - 索要真实模型的照片；商定状态和徽章含义。
- 复制
scripts/icon_kit.py，为每个设备编写一个绘图函数（128 框内的 SVG 片段，参见roof_window(pct)），将(name, title, body)行添加到ICONS中——每个状态一行——然后运行python3 icon_kit.py --out icons/。命名规则：<设备>-<状态>（shutter-000…shutter-100，boiler-on，boiler-off），这样 README 表格就能说明哪个图标对应哪个位置。 - 显示
preview.png；根据用户的反馈进行迭代（形状、颜色、类似表情符号的徽章清晰度）。 - 上传：将图标集列表添加到 QA 的
qa.json的icons部分，然后让build_fqa.py（技能hc3-packaging）生成<qa>-icons.sh，或手动上传：设置 → 设备 → 设备 → 图标 → 添加。
上传 API（在 5.2xx 固件上观察到）
POST /api/icons，multipart/form-data：type=device，deviceTemplate=<确切的设备类型>，每个状态一个文件（icon0、icon100 或 icon0…icon100），fileExtension=png（也支持 svg）。返回 201 {"id": 1055, "iconSetName": "User1055", "fileExtension": "png"}。应用：PUT /api/devices/<id> {"properties": {"deviceIcon": 1055}}（从外部调用——绝不要在 QA 内部对 QA 自身的 ID 使用，否则会重启；请使用 self:updateProperty）。删除：DELETE /api/icons?id=&type=device&name=&fileExtension=png。用户图标 ID 从大约 1000 开始。GET /api/icons 列出所有图标（固件之间存在两种响应格式：请同时接受）。房间和场景图标也存在（type=room / type=scene 可能 [V]）。
references/badges.md 列出了该工具包中可用的徽章颜色和字形。