开发者总览

TransBox 面向 Steam 创意工坊与本地扩展，开放七类可落地的插件能力。本文告诉你：能做什么、该选哪类、从哪抄起。

目标读者：MOD 作者、接私有 ASR/MT/TTS 的工程师、以及根据本文档直接实现插件的 AI 代理。

---

1. 能做什么

你想做的事	推荐 type	门槛	入口
游戏/行业专名强制翻译	glossary	零代码	terms.json 或 terms.txt
换字幕配色/透明度	theme	JSON	theme.json
换底板/音柱/装饰等视觉组件	theme + QML	中	ui_extensions
文本清洗、敏感词、音频特效	middleware	Python	file.py:ClassName
接私有语音识别	asr	Python	继承 BaseASRProvider
接 DeepL / LLM / 本地翻译	mt	Python	继承 BaseMTEngineProvider
接 Edge-TTS / SoVITS 等	tts	Python	继承 BaseTTSProvider
界面翻译成更多语言	i18n	零代码	xx.json 字典

另有内置类型 caption_bridge（浏览器字幕），第三方一般不实现。

---

2. 整体流程

你的文件夹（含 mod.json）
        │
        ▼
PluginRegistry 扫描
  · 应用目录 extensions/
  · %APPDATA%/transbox/extensions/
  · Steam 工坊 content/<AppID=1316080>/
        │
        ▼
按 type 分发
  glossary/i18n/theme → 数据挂载
  asr/mt/tts/middleware → importlib 加载 Python 类
        │
        ▼
用户在「扩展工坊」开关启用
  · 引擎类：在设置页选为当前引擎
  · 主题/语言包：启用即切换（常互斥）
  · 中间件/词库：挂进流水线

生命周期：发现 → 解析 mod.json → （启用时）实例化并 initialize(config) → 使用 → 停用 shutdown()。

---

3. 快速开始

1. 复制 extensions/example_custom_mt/ 或 example_glossary_gaming/。
2. 改 mod.json 的 id / name（id 全局唯一）。
3. 放入本地扩展目录 → 设置 → 扩展工坊 → 刷新 → 启用。
4. 引擎类：再到 ASR/MT/TTS 设置里选中你的引擎。
5. 稳定后导出 zip，见 工坊打包发布。

---

4. 文档地图

页面	内容
本地源码与开发环境	Python/uv、跑起来
架构与生命周期	流水线插入点、启用/禁用行为
插件规范（必读）	mod.json、基类 API、模板、AI 契约
UI 插槽与 HostContext	可替换槽位、注入属性
工坊打包发布	热调试、导出、Steam 发布事实

---

5. 设计原则（写代码前记住）

1. 只实现文档里的抽象方法，不要猜不存在的钩子。
2. entrypoint 必须指向真实文件与类名；省略类名时默认类名是 Plugin。
3. 配置用 config_schema 声明，在 initialize/update_config 里用 self._config["key"] 读取。
4. 不要 pip install 运行时依赖到宿主环境；需要重依赖时外挂本地 HTTP 服务。
5. 词库分隔符、插槽名、Steam 上传方式以 插件规范 为准，不要信任过时博客。