兼容与版本门禁

target_app_version（0.2 起必填）、命名迁移表、废弃类型、min_app_version 的判定规则。 改老插件之前先看这页。

`target_app_version`：适配断层强校验（0.2.0 起必填）

宿主用它回答一个问题：这个插件是给哪一代客户端写的？ 没声明 = 不知道 = 判定不匹配。

json

{ "target_app_version": "0.2" }

插件来源	是否必须声明	缺失时
引擎内置实现（`is_builtin`）	否	始终兼容
随安装包发布的 `extensions/`（bundled）	否	不参与该门禁
用户自制 / Steam 创意工坊 / 官网插件工坊	是	判定版本不匹配，直接拒绝

接受的值：0.2 / 0.2.0 / 0.2.x / >=0.2 / ^0.2（判定口径：以 0.2 开头即通过）。

历史别名 target_version / host_api 仍被接受，但不要再写 —— 统一用 target_app_version。

三道门都会拦

时机	行为	日志
扫描注册	不进入插件列表（用户以为「没装上」）	`[registry] 拒绝识别外部插件 <id>: 缺少 target_app_version 字段（未适配 0.2.0），判定版本不匹配`
创建实例	返回 `None`，启用/选引擎失败	`[registry] 拒绝加载 <id>: 缺少 target_app_version 或版本不匹配`
工坊安装	抛 `InstallError`，包不落盘	`插件 <id> 未声明 target_app_version 字段（未适配 0.2.0 版本），直接判定版本不匹配，已拒绝安装`

为什么要这么硬

0.1.x 的插件在 0.2.0 上不是「可能有点小问题」，而是会直接炸：SPI 改名（驼峰 → 蛇形）、运行库改为宿主统一提供、config_schema.type 拼法收紧等。与其让用户装上后看到一堆 traceback，不如在装载/安装前就拒绝。

老插件迁移（先加这一行）

mod.json 加 "target_app_version": "0.2"；
按命名迁移与废弃与迁移把旧写法换成蛇形；
依赖运行库的改用 requires_runtime + host.runtime_dir()；
本地自测：日志里不再出现 拒绝加载，设置页能把插件选为引擎。

两个版本字段的分工

字段	回答的问题	默认	缺省行为
`target_app_version`	你适配的是哪一代客户端	无	拒绝（须声明 `0.2`）
`min_app_version`	你最低要哪个客户端版本	`1.0.0`	不限制

实践中两个都写：target_app_version 标适配代次，真用到新 API 时再加 min_app_version。

命名迁移（驼峰 → 蛇形）

旧写法	规范名	现状
`host.feedDirectCaption`	`feed_direct_caption`	两名并存 ≥ 1 个小版本
`host.registerPluginHotkey`	`register_plugin_hotkey`	同上
`host.unregisterPluginHotkeys`	`unregister_plugin_hotkeys`	同上
`host.getPluginHotkeys`	`get_plugin_hotkeys`	同上
`host.getPluginConfig` 等驼峰配置 API	`get_plugin_config` / `set_plugin_config_value` / `save_plugin_config`	同上
`host.getRecentConversation`	`get_recent_conversation`	同上
`translate(..., source=)` 直打底层	在实现内部适配	已修社区 Hunyuan

新代码只用蛇形名。

废弃与迁移

现状	规范	迁移
`type: middleware` + `action_*`	`type: tool`	改清单元数据（工具/文本源不要挂 `middleware`）
`type: audio_filter`	—	已废弃，宿主不识别
`type: bundle`	—	已废弃，宿主不识别
bridge 上未文档化的方法	—	一律视为不稳定，改用 Host SPI

词表格式：只有对象数组一种（src / tgt / src_lang / tgt_lang）。扁平字典、tgt 为对象/数组、语言对分组、terms.txt / tsv 都载入为空表—— 别再教这些格式。见 glossary。

`min_app_version` 门禁

默认值 1.0.0，视为「不限制」（不会被当成真实下限）。另外 "" / "0" / "0.0.0" 也被视为不限制。
声明了真实下限时，宿主在创建实例前比较：当前应用版本 < min_app_version → 拒绝加载并在日志留痕（[registry] 拒绝加载 <id>: 需要应用版本 >= x.y.z，当前 a.b.c）。
因此：本地加载允许缺省；发布到插件工坊时 version 必填，而 min_app_version 建议只在真的用了新 API 时才写。

建议下限

你用了什么	建议
基础 Provider / 数据类插件	可省略（= 不限制）
下行事件 `handle_host_event`、`feed_caption`	`>= 0.3.0`（以实际上线版本为准）
模型工件 `model_artifacts`	见对应版本的变更说明
`requires_plugins` / `requires_runtime`	见对应版本的变更说明

平台保留的 id 段

插件 id 的第一段（作者段）不能使用保留名：

text

transbox  official  builtin  community  example  workshop
steam     system    admin    root       support  web  test  tbmod

服务端会以 reserved_id 拒绝；本地加载不受限，但也请遵守，否则上架必失败。

推荐格式：<你的名字>.<类型>.<名字>，例如 myteam.mt.deeplx。

版本号规则

mod.json 的 version：x.y.z 语义化版本。
发布到插件工坊时：必填 + 必须大于线上最高版本（否则 409 / 提示提新版本）。
客户端本地加载允许缺省（默认 1.0.0）。
消费端按「已安装收据版本 vs 线上 latest」判断是否有更新。

兼容与版本门禁 ​

target_app_version：适配断层强校验（0.2.0 起必填） ​

三道门都会拦 ​

为什么要这么硬 ​

老插件迁移（先加这一行） ​

两个版本字段的分工 ​

命名迁移（驼峰 → 蛇形） ​

废弃与迁移 ​

min_app_version 门禁 ​

建议下限 ​

平台保留的 id 段 ​

版本号规则 ​

相关 ​