插件系统总览

Termii 的进阶能力（Docker、批量任务、隧道、命令片段……）全部以插件形式存在：按需安装、即用即装，不用时界面零打扰。官方插件与第三方插件完全等同——安装包不内置任何插件，无内置、无特权，走同一条安装 → 信任 → 启用 → 加载流程。

本文是开发者指南的入口：先建立整体概念，再沿学习路径深入。

一个插件是什么

插件是一个目录，至少包含两个文件：

my-plugin/
├── plugin.json   # 清单：id / name / version / apiVersion / capabilities …
└── main.js       # 入口（单文件 ES module，由 SDK 打包脚手架生成）

可选：main.css（插件样式，宿主自动注入，见 SDK 与打包脚手架）。

插件本身是纯前端代码：宿主把插件作为 ES module 加载，调用它导出的 activate(ctx)；ctx 是插件与宿主之间的唯一边界，提供终端、主机、进程、界面等全部宿主能力（见 API 参考）。

宿主按能力声明把插件分成两层，决定信任弹窗的内容：

层级	声明	含义
L0（默认）	`capabilities: []` 或省略	纯 JS + Host API 白名单，只需基础信任确认
L1	`capabilities: ["process"]` 或 `["sidecar"]`	可执行命令 / 运行原生二进制；信任弹窗逐项列出并警示「将以你的用户权限执行任意命令」

sidecar 隐含 process。未获授予时 ctx.process.spawn、 hosts.execStream、ctx.sidecar.call 会明确报错，插件其余功能不受影响。详见信任模型与安全边界。

发现（磁盘 plugins/<id>/）→ 信任确认 → 启用 → 加载（读 plugin.json 校验）
  → 激活（调用 activate(ctx)）→ 运行中 ⇄ 禁用 / 启用
  → 卸载（删目录 + 清状态）

加载：宿主校验 plugin.json（版本、apiVersion、依赖、能力声明），读取入口脚本（main 字段，缺省 main.js），以 Blob URL 动态加载。
激活：调用 activate(ctx)。插件在这里注册贡献点、订阅事件、启动进程。所有注册都返回清理函数（Disposer），插件被禁用 / 卸载时宿主统一回放，无需手动管理。
去激活兜底：插件视图正被显示时切回连接中心；其主题正在使用时回落到 dark；其 main.css 注入的 <style> 一并移除；其名下全部流式进程与 sidecar 被强制回收（孤儿防护）。
故障隔离：单个插件加载 / 激活失败只记录日志并 toast 提示，不影响宿主与其他插件。

插件通过 ctx.ui.* 注册六类贡献点：

贡献点	注册方法	出现位置
视图	`ctx.ui.registerView`	侧栏条目 + 主区 React 组件，自动获得 ⌘1..9 快捷键与命令面板入口
命令	`ctx.ui.registerCommand`	⌘K 命令面板条目
设置分区	`ctx.ui.registerSettingsSection`	设置页新分类
快捷键	`ctx.ui.registerShortcut`	全局快捷键，如 `Mod+Shift+D`
主题	`ctx.ui.registerTheme`	设置 → 外观的主题卡片
托盘项	`ctx.ui.registerTrayItem`	系统托盘右键菜单固定区

所有贡献点 id 必须以 <pluginId>. 开头（宿主会自动补全，但显式书写是推荐做法），详见贡献点。

ctx 提供插件可用的全部宿主能力：

分组	能力
`ui`	注册视图 / 命令 / 设置分区 / 快捷键 / 主题 / 托盘项；toast 与弹窗；导航
`terminal`	读写活跃 / 指定终端 pane，订阅输出流
`sessions`	新开本地 / 主机终端 tab 并聚焦
`hosts`	主机连接、一次性执行、本机执行、SSH 流式执行
`process`	宿主托管本地进程的启动 / 输出 / 终止（需 L1 `process`）
`sidecar`	调用随包分发的原生二进制（需 L1 `sidecar`）
`tunnels`	端口转发（隧道）的列表 / 启动 / 停止 / 规则保存
`sftp`	上传 / 下载文件（同步形态，可选进度回调）
`vault`	凭证保险库（keyring）：按 id 读写无门禁；`list/export/import` 批量能力需 L1 `process`
`config`	配置快照导出 / 导入（需 L1 `process`），供配置同步类插件使用
`paths`	应用数据目录等路径投影
`storage`	插件私有持久化 KV
`dialog` / `fs`	原生对话框（打开 / 另存为 / 选目录）+ 受限文件写（仅授权路径）
`events`	订阅白名单内的 Tauri 事件
`plugins`	服务总线：跨插件调用与依赖自检
`i18n`	注册文案包、读取 / 监听界面语言

文档按由浅入深组织：