类型参考

插件开发涉及的全部类型与数据结构。类型一律从 SDK 导入：

import type {
  PluginContext,
  PluginManifest,
  TermiiPlugin,
  PluginForwardInfo, // tunnels.list 的返回元素（含 hostId）
  SnippetSummary,    // 服务总线里 termii-snippets 的 "snippets" 服务返回元素
  ProcessHandle,     // ctx.process.spawn / hosts.execStream 的句柄
} from "@termii/plugin-sdk";

基础

类型	定义	说明
`Disposer`	`() => void`	注册即返回的清理函数；插件去激活时统一回放
`SUPPORTED_API_VERSION`	`3`	宿主支持的插件 API 版本（常量）
`PluginIcon`	`typeof Waypoints`（lucide 组件）	侧栏条目 / 视图贡献使用的图标
`ToastProgressShape`	`{ total: number; completed: number; stage: string }`	toast 进度条载荷；total 为 0 → indeterminate

插件与贡献点

类型	形状（摘要）	说明
`PluginManifest`	见 manifest schema 参考	插件清单
`PluginContributes`	`{ views?, commands?, settingsSections?, themes?, trayItems? }`	清单里的声明式摘要
`TermiiPlugin`	`{ manifest; activate(ctx); deactivate?() }`	`definePlugin` 的入参类型
`ViewContribution`	`{ id, icon, labelKey, ns?, component }`	视图贡献
`CommandContribution`	`{ id, group, title, sub?, icon, run }`	命令贡献
`SettingsSectionContribution`	`{ id, icon, labelKey, ns?, component }`	设置分区贡献
`ShortcutContribution`	`{ id, combo, run }`	快捷键贡献
`ThemeContribution`	`{ id, label, dark, vars, previewBg?, previewFg? }`	主题贡献
`TrayItemContribution`	`{ id, label, run }`	托盘项贡献

各贡献点的字段说明见 PluginContext 参考 → ui。

终端与会话

类型	形状	说明
`ActivePaneInfo`	`{ paneId: string; kind: "local" \| "ssh" \| "serial"; backendId: string }`	当前活跃终端 pane 的只读投影（`terminal.getActivePane`）
`OutputChunk`	`{ seq: number; data: string }`	单条输出（`terminal.onOutput`），seq 单调递增
`SessionsApi`	`{ openLocalTab(); openHostTab(hostId); focus(paneId) }`	终端会话创建原语

主机

类型	形状	说明
`HostSummary`	`{ id, name, host, port, username, group?, tags: string[], favorite }`	主机只读投影（`hosts.list`），不含任何凭证字段

隧道（端口转发）

类型	形状	说明
`ForwardKind`	`"local" \| "remote" \| "dynamic"`	转发类型
`ForwardSpec`	`{ kind, bindHost, bindPort, targetHost, targetPort }`	`tunnels.start` 的可执行视图
`ForwardInfo`	`{ id, sessionId, kind, bindHost, bindPort, targetHost, targetPort: string, actualPort, active }`	一条转发（`targetPort` 为 string：SSH 报告 actual_port 为 u16）
`PluginForwardInfo`	`ForwardInfo & { hostId: string }`	`tunnels.list` 的返回元素（带主机归属）
`TunnelRule`	`{ id, name, hostId, kind, bindHost, bindPort, targetHost, targetPort, description?, displayOrder?, autoStart? }`	隧道规则（`tunnels.saveRule`；与宿主规则库同形，只落库不启动）
`RemoteForwardProbe`	`{ sshdTSucceeded, sshdTError?, gatewayPorts?, allowTcpForwarding?, bindHost, bindHostSupported, limitationMessage, canAutoFix }`	`tunnels.probeRemote` 的结果：远端 sshd 是否会尊重 `-R` 的 bindHost

进程

类型	形状	说明
`ProcChunk`	`{ seq: number; data: string; stream: "stdout" \| "stderr" }`	流式进程输出块（stdout / stderr 分流）
`ProcessHandle`	`{ readonly id; write(data); kill(); onData(cb); onExit(cb) }`	流式进程句柄（本地 `process.spawn` 与 SSH `hosts.execStream` 同构）
`ProcessApi`	`{ spawn(cmd, args, opts?) }`	本地流式进程 API（L1 `process`）

ProcessHandle.onExit 回调：{ code: number | null; error?: string }—— code 为 null 表示被终止 / 传输中断，error 给出原因。

sidecar

类型	形状	说明
`SidecarApi`	`{ call<T>(method, params?, timeoutMs?) }`	原生能力桥（L1 `sidecar`）；协议为 stdio 上 NDJSON + JSON-RPC 2.0

服务总线

类型	形状	说明
`SnippetSummary`	`{ id: string; name: string; group?: string; command: string; variables: string[] }`	片段库条目只读投影（`plugins.invoke("termii-snippets", "snippets", "list")` 的返回元素；`variables` 为 `{{name}}` 占位符名，保留首次出现顺序）

插件对象

interface TermiiPlugin {
  manifest: PluginManifest;
  activate(ctx: PluginContext): void | Promise<void>;
  deactivate?(): void; // 可选：额外的清理（定时器、自建的连接等）
}