打包与体积上限

一个插件就是一个文件夹 + 一份 mod.json。打包 = 把整个文件夹压成 zip。

打包内容

zip 的根目录必须直接是 mod.json（不能多套一层文件夹）：

text

my_mod.zip
├── mod.json          ← 根目录
├── my_mod.py
├── locales/
├── icon.svg
└── *.qml

客户端自带的导出功能会按这个规则打包；手工打包时注意别把外层目录也压进去。

环节	限制
客户端上传前预检	20 MB（超了本地直接拦下，一个字节都不发）
服务端（Pages Function）	20 MB

工坊跑在 Cloudflare Pages Function 上，45 MB 起的包会在上传中途被平台掐断 （客户端只会看到写失败，没有有用提示）——所以官方在 20 MB 就提前拦住。

东西	该怎么分发
模型权重（几百 MB ~ 几 GB）	`mod.json` 的 `model_artifacts` → 宿主从 HF / ModelScope 下到用户数据目录。见模型工件
原生运行库（`.dll` / `.exe`，几十 MB）	`requires_runtime` → 宿主按需下载校验解压。见宿主运行库
轻量 Python 依赖	`libs/` 或 `vendor/` 随包携带（见运行环境）
几十 MB 的自研二进制且官方没有对应运行库	联系官方走单独分发（不要塞进 `.tbmod`）

实测教训：曾经有作者把 88 MB 的 llama 运行库打进包，上传必然失败。现在的运行库组件就是为这个场景准备的。

[ ] zip 根目录直接是 mod.json（不是 my_mod/mod.json）
[ ] mod.json 写了 "target_app_version": "0.2"（不写就装不上，见兼容与版本门禁）
[ ] id 全局唯一，作者段不是保留名（transbox / official / builtin / community / example / workshop / steam / system / admin / root / support / web / test / tbmod）
[ ] version 是 x.y.z 且高于线上最高版本
[ ] entrypoint 指向的文件与类名真实存在
[ ] 包内没有 __pycache__ / .git / 临时文件
[ ] 合计体积 < 20 MB；没有大二进制/权重
[ ] locales/ 中英两份齐全（见 i18n）
[ ] 图标是矢量 SVG，不是 Emoji / 字符