热调试

改文件 → 刷新 → 看日志。宿主不会静默吞掉加载失败。

开发闭环

把插件文件夹放进扫描目录（开发时推荐 %APPDATA%/transbox/extensions/）
设置 → 扩展工坊 → 刷新（重新扫描）
打开插件开关启用
引擎类再去 设置 → ASR / MT / TTS 选为当前引擎
改代码 / QML → 重新加载：
- QML：开发期可用宿主热重载（TRANSBOX_QML_RELOAD=1，任意 .qml 保存自动重建）；发行环境里停用再启用插件即可重载
- Python：停用 → 启用（会重新 importlib 加载）。模块已被 import 过时，改同名文件不一定生效，必要时重启应用

出问题看哪里

症状	先看
插件根本不出现	`mod.json` 是否合法、`id` 是否为空、是否放对目录、是否被刷新到
出现但启用不了	工坊卡片上的提示（前置插件 / 运行库 / `min_app_version`）、日志里的 `[registry]` 行
启用了但没反应	引擎类是否已在设置页选为当前引擎；热键是否注册成功（冲突会返回 `False`）
界面不刷新	QML 是否监听了 `pluginConfigChanged`（见 UI 插槽）
想留证据	`self.host.log("info", "…", key=value)`

日志位置：<安装目录>/logs/app.log（含 [registry]、[plugin:xxx] 前缀的行）。另有 errors.log 与 faulthandler.log。

面向用户的提示用 host.show_toast() / host.show_error()，不要把异常栈弹给用户。

常用自检

python

def initialize(self, config=None):
    super().initialize(config)
    self.host.log("info", "插件初始化", plugin_dir=self.host.plugin_dir(self.id))
    self.host.log("info", "能力", caps=self.host.get_plugin_config(self.id))

打印 self.host.plugin_dir(self.id) 确认实际安装目录。
打印 self._config 确认配置键值符合预期（config_schema 的 default 有补齐）。
需要知道当前处于哪个渠道：host.get_app_version() / host.get_locale()；发行形态可看环境变量 TRANSBOX_DISTRIBUTION（selfpub / steam）。

别忘了

外部插件的 initialize() 跑在后台线程；宿主需要前会 wait_async_init()。
tool 类插件在扫描阶段就会预加载实例，别在 initialize() 里做重活。
日志与 toast 文案要能定位问题（「服务端口 18080 被占用，请换一个」而不是「启动失败」）。

热调试 ​

开发闭环 ​

出问题看哪里 ​

常用自检 ​

别忘了 ​

相关 ​

热调试

开发闭环

出问题看哪里

常用自检

别忘了

相关