TransBox 插件开发文档
面向：MOD 作者 / 接私有 ASR・MT・TTS 的工程师 / 直接照文档实现插件的 AI 代理。
本文档按知识卡片组织：一页一个主题，每件事只写一遍，其它页只放链接。 想改文档 → 找到该主题唯一的那张卡片改，不要在多页里重复写同一件事。
契约的单一事实来源是客户端源码（src/transbox/plugins/、src/transbox/ui/bridge/）。 官网页与源码冲突时以源码为准；发现不符欢迎在插件工坊反馈。
本目录与客户端仓库的
docs/plugin-dev/同源同结构，两边保持一致。 只含可复制代码资产的《插件规范》仍保留在原 URL。
5 分钟上手
- 复制一个官方示例目录（
extensions/example_glossary_gaming/、extensions/community_select_translate/、extensions/community_cloud_mimo_asr/…） - 改
mod.json的id/name（id 全局唯一，形如myteam.mt.deeplx，禁止builtin.*段） - 放进扫描目录 → 设置 → 扩展工坊 → 刷新 → 打开开关启用
- 引擎类（asr / mt / tts）再到对应设置页把它选为当前引擎；data 类（theme / glossary / i18n）启用即生效
细节见 快速开始。
文档地图
起步
| 卡片 | 一句话 |
|---|---|
| 快速开始 | 最小可跑插件长什么样 |
| 目录结构与 mod.json | 一个插件文件夹必须是啥样，字段全都在这 |
| 运行架构与生命周期 | 扫描根 / 双轨分流 / 启用停用 / 互斥规则 |
按类型开发
| 卡片 | 一句话 |
|---|---|
| 类型总览与选型 | 12 种 type，我该选哪个 |
| glossary 术语库 | 零代码，只写 terms.json |
| theme 主题 | theme.json 令牌换肤 + 字幕窗参数 |
| UI 扩展（QML） | 替换底板 / 音柱 / 字幕视图 |
| middleware 中间件 | 在流水线任意阶段拦截 |
| asr 语音识别 | 接私有识别引擎 |
| mt 机器翻译 | 接 DeepL / LLM / 本地翻译 |
| tts 语音合成 | 音色表 / 克隆音色 / 流式 / 语速 |
| interpretation 同传直通 | 端到端同传（绕过本地 ASR→MT→TTS） |
| assistant AI 助手 | 面试副驾 / 答题浮窗 |
| tool 工具 | 划词翻译 / 全局快捷键工具 |
| i18n 语言包 | 整包界面翻译 + 插件自包含词条 |
| caption_extractor 视频站字幕 | 给别的视频站加字幕提取 |
Host SPI（插件调用宿主）
| 卡片 | 一句话 |
|---|---|
| SPI 索引与速查表 | 全部方法一眼看完 + 基类能力 |
| 字幕与翻译 | 把文本送进字幕 / 调活跃翻译引擎 |
| 配置与私有数据 | 读写本插件配置 / KV / 数据目录 |
| 会话与宿主状态 | 历史上下文 / 流水线状态 / 已装插件 |
| 全局热键 | 声明式热键与运行时注册 |
| 模型工件 | 声明权重仓库，宿主负责下载与就绪 |
| 事件总线 | 插件↔宿主双向事件与标准事件表 |
| 朗读与提示 | speak / toast / 防录屏 |
| 插件浮窗 | 多开、置顶、穿透、防录屏的 QML 窗 |
| 文件选择与长任务 | 系统文件对话框 / 可取消进度条 |
Provider 契约（强制签名）
| 卡片 | 一句话 |
|---|---|
| 能力声明与只读契约 | 宿主怎么在不启动你服务的前提下问能力 |
| Provider 签名与数据类型 | MT / ASR / TTS 方法签名 + Transcript 等 |
| 本地服务型引擎强制契约 | 惰性启动 / 端口 / 设备 / 子进程 / 持久化 |
配置与界面
| 卡片 | 一句话 |
|---|---|
| config_schema 声明式表单 | 字段类型、显隐、预设、计算设备 |
| 自定义设置页 | 需要「去获取 Key / 测试连接」时 |
| UI 插槽 | 可替换的槽位清单 + 背景插槽准则 |
调试与发布
| 卡片 | 一句话 |
|---|---|
| 热调试 | 改文件 → 刷新 → 看日志 |
| 打包与体积上限 | 导出 zip，20 MB 硬上限与出路 |
| 发布渠道 | Steam 创意工坊 / 官网插件工坊 |
| 前置插件依赖 | requires_plugins + 按 id 定位目录 |
| 宿主运行库 | requires_runtime，二进制别打进包 |
参考
| 卡片 | 一句话 |
|---|---|
| 示例库 | 每种类型照抄哪个目录 |
| 语言代码与可翻译语种 | target_langs / supported_langs 区别、代码归一、33 语种表 |
| 线程契约 | 哪些 API 能在哪个线程调 |
| 运行环境与安全红线 | 预置库 / libs vendor / 禁止 pip |
| 兼容与版本门禁 | target_app_version（必填）、命名迁移、min_app_version、废弃 type |
| 宿主实现清单 | 已开放的能力（别猜不存在的钩子） |
按目标找页面
| 我想… | 看这几页 |
|---|---|
| 先跑起来一个最小插件 | 快速开始 → 目录结构 |
| 接一个云端 ASR / MT / TTS | types 总览 → 对应类型页 → config/schema |
| 声明翻译模型能翻哪些语言 | mt → 语言代码与可翻译语种 |
| 接一个本地推理服务（llama-server 之类） | 本地服务型引擎强制契约（必读）→ 模型工件 |
| 做界面/主题相关 | UI 插槽 → theme |
| 加词库 / 语言包（零代码） | glossary / i18n |
| 让 AI 帮我写插件 | 快速开始 的「丢给 AI 的提示词」+ 目录结构 + 对应类型页 |
| 发布出去 | 打包与体积上限 → 发布渠道 |
三个最容易踩的坑
本地服务型插件（自己起
llama-server/tts-server/ 自研 HTTP 服务）务必先读 本地服务型引擎强制契约。这三条都是用户能直接看到的 BUG。
- 别在
initialize()里启动本地服务 —— 宿主会在打开设置页、查模型状态/音色时做只读查询； 旧写法会让用户「只是看一眼设置」就白等数秒并吃掉数 GB 显存。启动放ensure_loaded()或请求入口。 - 端口别用 8080/8081/8082 —— 实测常被 Steam
steamwebhelper等占用；用高位不常用段并让宿主/自己顺延。 - 服务端的音色/注册表必须自己落盘 —— 只存内存的话，用户每次重启都要重新注册（实测
tts-server就是这样）。
另外两条高频问题：
- 定位兄弟插件目录不要硬编码目录名 —— 工坊安装时目录名 = 插件 id。用
host.plugin_dir(id)（见 前置插件依赖）。 - 大体积二进制 / 大模型不要打进包 —— 上传通道上限 20 MB。二进制走 运行库，权重走 模型工件。
《插件规范》旧章节 → 新卡片
官网原《插件规范》（单页 1700+ 行）已按主题拆分为上面的卡片。 为避免同一件事写两遍，单页里只保留可复制的代码资产，其余章节改为指向卡片：
| 《插件规范》原章节 | 去哪 |
|---|---|
| §0 直接丢给 AI：系统提示词模板 | 保留在原页（§0 Prompt-and-Go） |
| §1 目录结构 | 目录结构与 mod.json |
§2 mod.json 字段表 | 目录结构与 mod.json |
§3 支持的 type | 类型总览与选型 |
§3.1 caption_extractor | 视频站字幕提取 |
§4 entrypoint 规则 | 目录结构与 mod.json |
| §5.1 Glossary | glossary 术语库 |
| §5.2 Theme | theme 主题 |
| §5.3 i18n（整包语言包） | i18n 语言包 |
| §5.4 插件自包含国际化 | i18n 语言包 |
| §5.5 tool | tool 工具 |
§6 config_schema | config_schema 声明式表单 |
| §6.2 QML 消费与免重启热响应 | UI 扩展（QML） |
| §6.3 云端定制设置页 | 自定义设置页 |
| §7.0 独立开发环境存根 (SDK Stub) | 保留在原页（没有宿主源码时开发用） |
| §7.1–7.9 基类签名 / 数据类型 / Host SPI | Provider 签名与数据类型 + SPI 索引与速查表 |
| §7.10 本地离线模型工件与外部运行时 | 模型工件 |
§7.11 requires_runtime | 宿主运行库 |
| §8 最小可运行模板（7 个） | 保留在原页（可直接复制改名的完整代码） |
| §9 本地热调试 | 热调试 |
| §10 创意工坊一键发布与增量更新 | 打包与体积上限 + 发布渠道 |
| §11 插件自包含国际化规范 | i18n 语言包 |
| §12 运行环境与红线 | 运行环境与安全红线 |
| §13 官方示例索引 | 示例库 |
| §14 给 AI 代理的实现检查清单 | 保留在原页 |
| §15 UI 插槽（摘要） | UI 插槽 + QML 界面插槽与 HostContext |
相关文档（开发者中心其它页）
| 文档 | 内容 |
|---|---|
| 插件规范 | Prompt-and-Go 提示词模板 / 独立开发 SDK Stub / 7 个完整可复制模板 / AI 实现检查清单 |
| 客户端内部实现 | Python 类加载、配置装配、安全模型（插件契约见本卡树） |
| QML 界面插槽与 HostContext | 插槽属性、hostContext 子系统、settings_view 注入 |
| 本地源码与开发环境 | 客户端源码环境（uv / Python 3.11–3.12） |
| 工坊与自发行发布 | 导出 zip、Steam 上传、本地扩展目录分发 |
| 官网插件工坊（作者/运维手册） | 作者中心上传、订阅、审核与运维 |
核心团队保留规范演进权。问题请开 GitHub Issue。