开发者总览

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

目标读者：MOD 作者、接私有 ASR/MT/TTS 的工程师、以及根据本文档直接实现插件的 AI 代理。
契约的单一事实来源是客户端源码（src/transbox/plugins/、src/transbox/ui/bridge/）。官网开发者文档与之对齐，冲突时以源码为准。插件契约已按主题拆为知识卡片，入口插件开发文档。

1. 能做什么

你想做的事	推荐 `type`	门槛	入口
游戏/行业专名对照（多语向）	`glossary`	零代码	仅 `terms.json`（四字段对象数组）
换字幕配色/透明度	`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`
端到端实时同传（绕过本地 ASR→MT→TTS）	`interpretation`	Python	继承 `BaseInterpretationProvider`
AI 面试/答辩副驾助手	`assistant`	Python	继承 `BaseAssistantPlugin`
划词翻译/全局快捷键工具	`tool`	Python	继承 `BaseToolPlugin`
界面翻译成更多语言	`i18n`	零代码	`xx.json` 字典
网页字幕桥（传输服务）	`caption_bridge`	工坊件	见 `community_web_caption_bridge`
给视频站加字幕提取	`caption_extractor`	JS	`extractor.js`

历史类型 audio_filter / bundle 已废弃，宿主不识别。

网页字幕桥从创意工坊安装，不在官方包里。给别的视频站加字幕用 caption_extractor，见视频站字幕提取；终端用户说明见浏览器原生字幕。

2. 整体流程

你的文件夹（含 mod.json）
        │
        ▼
PluginRegistry 扫描
  · 应用目录 extensions/
  · %APPDATA%/transbox/extensions/
  · Steam 工坊 content/<AppID=5521270>/   （自发行版跳过此项）
        │
        ▼
按 type 分发
  glossary/i18n/theme → 数据挂载
  asr/mt/tts/assistant/interpretation/middleware/tool → importlib 加载 Python 类
  caption_bridge / caption_extractor → 字幕桥链路
        │
        ▼
用户在「扩展工坊」开关启用
  · 引擎类：在设置页选为当前引擎
  · interpretation：切入同传模式，绕过标准 ASR+MT+TTS
  · 主题/语言包：启用即切换（常互斥）
  · 中间件/词库：挂进流水线
  · AI 助手/工具：注册热键或开启独立窗口

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

3. 快速开始

复制官方示例目录（如 extensions/example_glossary_gaming/、community_select_translate/、community_cloud_mimo_asr/）。
修改 mod.json 的 id / name（id 全局唯一，如 myteam.mt.deeplx）。
放入本地扩展目录 → 设置 → 扩展工坊 → 刷新 → 启用。
引擎类：再到 ASR/MT/TTS 设置里选中你的引擎；AI 助手类：呼出对应副驾窗口。
有 Steam：创意工坊中心 → 发布与更新。无 Steam / 自发行版：导出 Zip，用户解压到 %APPDATA%/transbox/extensions/。详见工坊与自发行。

4. 文档地图

页面	内容
本地源码与开发环境	Python/uv、跑起来
客户端内部实现	Python 类加载、配置装配、安全模型
插件开发文档（卡片树）	按主题查：起步 / 类型 / Host SPI / Provider / 配置 / UI / 发布 / 参考
插件规范（代码资产）	Prompt-and-Go 模板、SDK 存根、7 个完整可复制模板、AI 检查清单
UI 插槽与 HostContext	可替换槽位、注入属性
工坊与自发行发布	Steam 上传 + 本地扩展目录分发

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

只实现文档里的抽象方法，不要猜不存在的钩子。
entrypoint 必须指向真实文件与类名；省略类名时默认类名是 Plugin。
简单配置用 config_schema；需要「去获取 Key」「测试连接」、双 Base URL 切换等定制 UX 时，必须自带 ui_extensions.settings_view QML（见自定义设置页）。仅靠 config_schema 得不到官方云端表单那套按钮。
不要 pip install 运行时依赖到宿主环境；轻量依赖放 libs//vendor/，重依赖外挂本地 HTTP。
术语库、插槽名、发布方式以插件开发文档为准。

6. 已知限制（平台侧）

项	现状
云端设置表单	「去获取 Key」「测试连接」、MiMo Token Plan / API 双通道等 UX 不会从 `config_schema` 自动生成；官方云端插件靠自定义 `SettingsView.qml` + 宿主属性（如 `currentApiKey` / `currentDashscopeApiKey`）。第三方要同级 UX 须自带 QML。
术语库格式	SPI 契约：仅 `terms.json` 四字段对象数组（见 glossary）。`terms.txt` / `tsv`、扁平字典、`tgt` 为对象/数组、按语对分组的字典在契约上视为空表——请勿再教这些格式。
自发行版	`TRANSBOX_DISTRIBUTION=selfpub` 时跳过 Steam 初始化与创意工坊目录；扩展仍走应用 `extensions/` 与 `%APPDATA%/transbox/extensions/`。
`audio_filter` / `bundle`	已废弃，勿复活。

开发者总览 ​

1. 能做什么 ​

2. 整体流程 ​

3. 快速开始 ​

4. 文档地图 ​

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