目录结构与 mod.json
本页是
mod.json字段的唯一权威表。其它卡片提到字段时只给链接，不重复列表。
目录结构
text
my_mod/
├── mod.json # 必选（或 manifest.json）
├── locales/ # 推荐：插件自包含多语言词条（全类型通用）
│ ├── zh-CN.json
│ └── en-US.json
├── assets/icons/ # 推荐：插件专属矢量 SVG 图标（拒绝 Emoji / 字符图标）
├── icon.svg # 推荐；也会自动探测 icon.png / webp / jpg
├── README.md # 可选，工坊展示说明
├── libs/ vendor/ # 可选：插件私有 Python 依赖（见运行时环境）
├── theme.json # type=theme
├── terms.json # type=glossary（唯一词表格式）
├── ja.json # type=i18n（整包语言包）
├── provider.py # Python 入口
└── *.qml # ui_extensions规则：
- 一个 MOD = 一个文件夹，
id全局唯一；目录名建议与id同形但不强制。 - 工坊安装后的目录名 = 插件 id（
<数据目录>/workshop/<id>/）——所以不要假设目录名，见 前置插件依赖。 - 二进制运行库放插件私有目录（
bin/、llama/之类），不要放进data/models/（那是纯权重目录，用户点「清除缓存」会误伤）。 - 单包体积上限 20 MB，见 打包与体积上限。
字段表
| 字段 | 必填 | 默认 | 说明 |
|---|---|---|---|
id | 是 | — | 全局唯一，形如 myteam.mt.deeplx。无 id 直接拒绝加载。禁止占用 builtin.* / community.* / workshop.* 官方保留段 |
name | 建议 | 未命名 MOD | 显示名 |
version | 建议 | 1.0.0 | 语义化版本。本地加载允许缺省；发布到插件工坊时必填 x.y.z，提新版本必须大于线上最高版本（发布页可直接改） |
author | 建议 | 未知作者 | — |
description | 否 | "" | 工坊简介 |
type | 建议 | glossary | 见 类型总览 |
entrypoint | 视类型 | "" | 见下方「entrypoint 规则」 |
icon | 否 | 自动探测 | svg / png / webp / jpg |
preview_image | 否 | — | 工坊预览图相对路径 |
tags | 否 | [] | 含 cloud → 视为云端 API；含 local / offline → 本地离线。决定设置页是否挂模型卡与硬件评级 |
documentation_url | 否 | "" | 官方文档外链（会显示在卡片上） |
target_app_version | 是（外部/工坊插件） | — | 适配代次。写 "0.2"。未声明一律判定「版本不匹配」，拒绝识别与安装（内置与随包 extensions/ 免检）；见 兼容与版本门禁 |
min_app_version | 否 | 1.0.0 | 最低兼容客户端版本。1.0.0 = 不限制；见 兼容与版本门禁 |
tier | 否 | free | free / pro / community |
supported_langs | 否 | [] | 源语言能力列表；用于音轨源语言收敛与卡片展示。MT 的目标语种请写 target_langs |
target_langs | 否（MT 建议） | 回落 supported_langs | 翻译目标语种能力全集，决定字幕「翻译语言」下拉框可激活的语种；支持 zh-TW / pt-BR 等代码，为空时按 33 语种通用能力处理。见 语言代码与可翻译语种 |
aliases | 否 | [] | 短名别名（如 ["cool"]），设置页/路由可解析回完整 ID |
requires_hf | 否 | 按 tags/id 推断 | false = 纯 API/云端，启动可跳过 transformers 预热；true = 需要 HF |
requires_cuda | 否 | — | false = 不强依赖 NVIDIA（AMD ROCm / Vulkan / CPU 都行）→ 宿主不再弹「需 CUDA」红框 |
model_artifacts | 否 | [] | 本地模型工件声明，见 模型工件 |
requires_plugins | 否 | [] | 前置插件依赖（≤ 8 条），见 前置插件依赖 |
requires_runtime | 否 | [] | 宿主运行库依赖（≤ 4 条），见 宿主运行库 |
capabilities | 否 | {} | 引擎能力声明（音色表 / 克隆 / 删除 / 原生语速），见 能力声明 |
config_schema | 否 | [] | 声明式配置表单，见 config_schema |
ui_extensions | 否 | {} | 插槽 → QML 文件映射，见 UI 插槽 |
hotkeys | 否 | [] | 声明式全局热键，见 全局热键 |
host_events | 否 | [] | 声明要接收的宿主事件名（["*"] = 全部），见 事件总线 |
permissions | 否 | [] | 能力声明字符串（net / clipboard / hotkey / window…），用于工坊展示与未来门禁 |
supports_glossary | 否 | 按 type/tags/id 推断 | true = 原生吃术语库/热词 |
style_layer | 否 | full（仅 theme） | full / material / typography / effects |
has_settings_tab / tab_id / tab_title | 否 | — | 独立设置 Tab，见 自定义设置页 |
language_code / language_name | 否 | — | 仅 i18n |
enabled | 否 | theme/i18n 为 false，其余 true | 首次启用状态（用户开关会覆盖它） |
source_lang / target_lang | 否 | "" | 词库类插件的默认语向 |
不要写在 mod.json 里的：window_backdrop（会被忽略）——它属于 theme.json，见 theme。
⚠️
target_app_version是唯一一个“不写就装不上”的字段。 没它的话：本地放进extensions/也不进列表、Steam/官网工坊包直接拒绝安装。 0.1.x 时代的老插件必须补上（一行）才能上 0.2.x，详见 兼容与版本门禁。
entrypoint 规则
| type | 格式 | 例 |
|---|---|---|
asr / mt / tts / middleware / assistant / interpretation / tool | file.py:ClassName | copilot.py:MyCopilot |
| 同上，省略类名 | file.py | 类名默认 Plugin |
glossary | 词表路径 | terms.json |
theme | 主题路径 | theme.json |
i18n | 字典路径 | ja.json |
caption_extractor | 脚本路径 | extractor.js |
caption_bridge | 工坊插件本身 | 一般不用自己写，见 类型总览 |
entrypoint 必须指向真实存在的文件与类名——宿主找不到会拒绝加载并在日志/卡片上说明。
关于「文件放哪」的路径约定
| 用途 | 路径 | 备注 |
|---|---|---|
| 模型权重 | <数据目录>/models/<org>--<name>/ | 由宿主下载，插件不要自己拼目录名，用 inspect_model_artifact()["target_dir"] |
| 插件私有数据（缓存、词库、导出） | <安装目录>/data/plugins/<plugin_id>/ | 用 self.get_data_dir() / host.get_plugin_data_dir(id) |
| 插件私有 Python 依赖 | <插件目录>/libs/ 或 vendor/ | 宿主自动注入 sys.path，见 运行环境与安全红线 |
| 私有二进制（llama-server 等） | <插件目录>/bin/ 之类 | 或直接走 宿主运行库 |