apiVersion 契约

apiVersion 契约

宿主把插件的 API 面按大版本推进；apiVersion 是插件声明的「我需要的最 小宿主 API 版本」，宿主据此决定能否安全加载。

规则

• ctx.apiVersion：宿主支持版本，当前为 3（宿主内部常量 SUPPORTED_API_VERSION）。
• manifest.apiVersion：可选。缺省视为 1——不写该字段的插件向后 兼容，继续可以安装运行。
• 声明值 > 3 → 拒绝加载：设置页 toast「插件 <name> 需要更新的 Termii 版本」（描述里带出「插件声明 apiVersion X，当前应用支持 3」）， 插件不会被激活，其余插件不受影响。
• 声明值 ≤ 3（含缺省）→ 正常加载。
• 设置页的插件列表会展示每个插件声明的 apiVersion（缺省显示 1）。

// 模板 hello-world 的声明（plugin-template 仓库 hello/plugin.json）
{
  "id": "hello-world",
  "apiVersion": 2 // ← 可声明 2 或 3；宿主均接受（≤ SUPPORTED_API_VERSION）
}

当前 API 面（v3）包含

• ctx.process / hosts.execStream —— 流式进程
• ctx.sessions / terminal.writePane —— 终端会话原语
• ctx.plugins —— 插件服务总线（expose / invoke / isActive）
• capabilities —— 能力声明（L0 / L1）
• ctx.sftp / ctx.vault / ctx.dialog / ctx.fs 等投影
• 签名分发与 URL 安装

类型同步

SDK 的类型面由宿主侧自动生成（scripts/gen-sdk-types.mjs 从 src/lib/plugins/types.ts 生成 host-types.ts，经 sync-sdk-types CD 在 main push 时推送到 SDK 仓库）。写插件时以 SDK 导出的类型为准；若发现 SDK 与宿主签名分叉，以宿主实现为准并检查同步流程。详见 SDK 与打包脚手架 → 类型同步。