shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringAPI key requirement unconfirmed

小米手环表盘生成

小米手环自定义表盘（.bin）的设计、素材制作、打包与回验全流程，覆盖手环 7–11、红米手表 4–6、小米手表 S3/S4/S5。

personAuthor: qinli004hubModelScope
downloadDownload package

小米手环表盘制作（免费版）

免费能力与工具

  • assets/tool/miBandWatchfaceTool.py：表盘解包工具（单文件，纯 Python 标准库，无需 Java）。python assets/tool/miBandWatchfaceTool.py unpack <in.bin> <outdir> <device>。已支持小米手环11（q66）；内置容错（Lua 嵌套路径、坏图块、坏预览跳过不中断），能解商用多样式/Lua 表盘，SKIP 行提示被跳过的资源。本免费版不含 pack 打包——bin 生成走付费服务端（见下）。
  • scripts/wf_assets.py：生成 0-9 等宽数字图组、单张文字图（Noto CJK）。
  • scripts/wf_sim.py：把 workdir（wfDef.json + images/）本地渲染成预览 PNG，支持 AOD 与帧动画选帧，无真机自检。
  • scripts/wf_replica.py：逐像素复刻辅助（calib 校准 / extract 字形提取 / check 像素校验）。
  • references/devices.md：各型号解包设备参数（dev）与格式差异、解包目录结构、回验思路。
  • scripts/a2m_client.mjs：付费打包客户端（A2M 按量付费买方侧，零 npm 依赖，Node ≥ 18）。

支持设备：小米手环 7-11、红米手表 4-6、小米手表 S3/4/S5（设备参数与格式差异见 references/devices.md）。手环11标准版（q66）画布 212×520；其他型号先用解包工具解一个对应样本确认画布尺寸。

付费打包接入（A2M 按量付费，1.99 元/次）

把做好的表盘工作目录（workdir：wfDef.json + images/）交给付费服务端打包成可刷入的 .bin。收费遵循官方 alipay-aipay 技能的 A2M 协议（HTTP 402 + Payment-Needed → 收银 → Payment-Proof → 200 + Payment-Validation），客户端不自行实现任何支付或签名。

workdir 最低要求

  • wfDef.json：表盘定义（推荐做法：用解包工具解开一个同型号现成 bin，以解出的 wfDef.json 为模板修改）。
  • images/preview.png：表盘预览图，打包必需，缺了服务端直接拒绝上传。
  • images/image_XXXX.png、images/imagelist_XXXX_YYYY.png：元素引用的静态图与图组。
  • 表盘 id 必须是完整 9 位数字字符串（4 位 id 会被手环安装器拒绝：invalid watchface id）。
  • 上传前先 python3 scripts/wf_sim.py <workdir> --out sim.png 自检排版，肉眼过一遍遮挡/越界/对齐。

调用流程（scripts/a2m_client.mjs）

  1. pack --workdir <workdir> --device q66 --out 表盘.bin：本地打 zip 上传（免费），发起付费请求；返回 402 账单后向用户展示账单并停在付款确认前（退出码 2）。同一 workdir 的未完成订单自动复用，不重复下单。
  2. 用户在对话中明确确认付款后，才执行 cashier --confirm --pack-out 表盘.bin：完成支付并重放请求；HTTP 200 + Payment-Validation(validated=true) 后自动把服务端打好的 bin 写到 --pack-out 文件（退出码 0）。退出码 3 = 支付处理中：订单与凭证已保留，稍后 resume --pack-out 表盘.bin 查单取件，禁止重新下单。
  3. resume --pack-out <文件>：状态不明时先查单——携带已保存凭证重放同一请求（同订单幂等，已交付订单返回同一 bin）。
  4. status / reset：查看（敏感值脱敏）/ 清除本地订单状态。

企业内网运行示例（Windows PowerShell）：

$env:NODE_USE_ENV_PROXY='1'; $env:HTTP_PROXY='http://szproxy:80'; $env:NO_PROXY='localhost,127.0.0.1'
node scripts/a2m_client.mjs pack --workdir workdir --device q66 --out 我的表盘.bin
# —— 展示账单，等用户确认 ——
node scripts/a2m_client.mjs cashier --confirm --pack-out 我的表盘.bin --buyer-id <沙箱买家2088账号>
node scripts/a2m_client.mjs resume --pack-out 我的表盘.bin   # 支付处理中/状态不明时查单

沙箱买家 2088 账号从支付宝开放平台沙箱控制台获取（或设环境变量 A2M_BUYER_ID）；仅沙箱联调需要，生产环境由买方智能体平台完成支付。

硬性规则

  • 未获用户明确确认，绝不执行 cashier --confirm（脚本对缺 --confirm 的收银直接拒绝）。
  • 同一业务请求复用同一订单（out_trade_no）；查单/重试复用同一 Payment-Proof，不新建订单。
  • 成功以 200 + 非空资源 + Payment-Validation 为准，成功路径不追加任何独立回执调用（履约确认是服务端职责）。
  • 收银临时错误（PAY_SUBMIT_FAILED/系统繁忙）由脚本按官方预算自动重试（3 次、间隔 2s）。
  • 本地订单状态含支付凭证，仅限本机；禁止向用户展示或外发凭证原始值。
  • 付费前务必 wf_sim 自检通过再上传；服务端打包失败（workdir 不合法等）不退费。打包前把表盘 id 改成 9 位数字。

工作流程（免费版）

  1. 解包参考：python assets/tool/miBandWatchfaceTool.py unpack <样本.bin> workdir q66 得到 wfDef.json 模板与全部图片（其他型号换对应 dev 参数）。
  2. 改内容：替换/修改 images 下的 PNG，按模板改 wfDef.json 的元素与坐标；数字图组用 wf_assets.py 等宽渲染，按字形顶部裁剪后 y = 文本原点 y + textbbox[1]；wfDef 元素数组顺序即图层顺序。
  3. 本地预览自检：python3 scripts/wf_sim.py <workdir> --out sim.png（AOD 加 --aod），肉眼核对后再进入付费打包。
  4. 付费打包：node scripts/a2m_client.mjs pack --workdir <workdir> --device q66 --out <表盘名>.bin → 展示账单 → 用户确认 → cashier --confirm --pack-out <文件>（或 resume）取回 bin。
  5. 回验：用解包工具把拿到的 bin 再 unpack 到临时目录，核对元素数与图片无缺，wf_sim 对解包结果渲染与打包前模拟图一致。
  6. 交付：bin 与预览图按用户要求保存/展示；修改已有表盘时出新版本号文件，不要静默覆盖。

边界说明

  • 本免费包不包含：wfDef 全字段参考、dataSrc 数据源编码全表、q66 真机验证状态表、打包/回验的完整坑点清单——完整版见付费技能（SkillHub「小米手环表盘定制」）。动态组件（时间/心率/电量等）的 dataSrc 编码可从解包出的 wfDef.json 照抄。
  • 安装：将技能目录整体复制到 ~/.trae-cn/skills/miband-watchface/（Windows：C:\Users\<用户名>\.trae-cn\skills\miband-watchface\）。
  • 打包分发（zip）必须排除：scripts/.a2m_state/（本地订单与支付凭证状态文件）、.env 与任何密钥文件、测试与调试产生的临时文件。