跳转到内容

原生插件开发

本文档介绍 OxideTerm Native 插件模型。它和 Tauri/Web 插件模型不同:Native 插件不运行 React 组件,不注入 CSS,也不会通过 WebView 执行 main.js。Native 插件通过 plugin.json 被发现,然后要么只提供清单声明的元数据,要么通过宿主拥有的进程/WASM 运行时桥接运行。

专用包还支持 language、acp、remote-desktop、terminal-transport 和 helper 运行时。RDP、VNC 引擎由插件市场分发,保存配置和查看器由宿主管理。进程连接插件可提供独立连接实例和持续更新的工作台。

  1. 写出一个可运行插件
  2. 运行时通信过程
  3. 在插件代码里调用宿主
  4. 界面与事件写法
  5. 常见失败检查
  6. Native 插件模型
  7. Native 插件与 Tauri 插件的区别
  8. 插件目录
  9. 最小清单插件
  10. 背景素材包
  11. 编辑器语言插件
  12. 进程运行时插件
  13. 协议帧
  14. 运行时注册
  15. 插件连接类型
  16. 声明式 Native 界面
  17. 宿主 API 调用
  18. 权限与能力
  19. 设置、存储与凭据
  20. 终端、SFTP、转发、IDE 与 AI
  21. 打包与安装
  22. 接口参考
  23. 宿主 API 参考
  24. 事件参考
  25. 调试
  26. 迁移说明

先从进程插件开始。进程运行时最容易调试,因为所有消息都是 stdin/stdout 上的一行一个 JSON 对象。

在用户插件目录里创建这个目录:

hello-native/
plugin.json
bin/
hello.js

进程入口必须是插件目录内的真实可执行文件。macOS/Linux 上需要给脚本加可执行权限:

Terminal window
chmod +x hello-native/bin/hello.js

使用这个清单:

{
"id": "com.example.hello-native",
"name": "Hello Native",
"version": "0.1.0",
"description": "Minimal native process plugin.",
"runtime": {
"kind": "process",
"entry": "bin/hello.js"
},
"permissions": {
"capabilities": [
"legacy.invoke",
"ui.write"
]
},
"contributes": {
"sidebarPanels": [
{
"id": "hello-panel",
"title": "Hello",
"icon": "panel-left",
"position": "top"
}
],
"settings": [
{
"id": "message",
"type": "string",
"default": "Hello from a native plugin",
"title": "Message"
}
],
"apiCommands": [
"get_app_version"
]
}
}

使用这个进程入口:

#!/usr/bin/env node
const readline = require("node:readline");
const pluginId = "com.example.hello-native";
let nextHostRequest = 1;
const pendingHostCalls = new Map();
// Keep stdout reserved for protocol frames.
function writeFrame(payload, requestId = null) {
process.stdout.write(JSON.stringify({
protocolVersion: 1,
requestId,
payload
}) + "\n");
}
function respondOk(requestId, value) {
writeFrame({
requestId,
result: {
status: "ok",
value
}
}, requestId);
}
function respondError(requestId, code, message) {
writeFrame({
requestId,
result: {
status: "error",
error: {
code,
message,
recoverable: false
}
}
}, requestId);
}
function registerPanel() {
writeFrame({
type: "registerContribution",
registration: {
registrationId: "hello-panel-view",
pluginId,
kind: "sidebar-panel",
metadata: {
panelId: "hello-panel",
schema: {
kind: "form",
title: "Hello Native",
sections: [
{
id: "main",
controls: [
{
kind: "markdown",
text: "This panel was registered by a native process plugin."
},
{
kind: "button",
id: "refresh",
label: "Refresh"
}
]
}
]
}
}
}
});
}
// Returnable host calls are matched by requestId.
function callHost(namespace, method, args = {}) {
const requestId = `host-${nextHostRequest++}`;
writeFrame({
type: "callHostApi",
requestId,
namespace,
method,
args
});
return new Promise((resolve, reject) => {
pendingHostCalls.set(requestId, { resolve, reject });
});
}
// Host-call responses arrive on stdin like normal host requests.
function handleHostResponse(payload) {
const pending = pendingHostCalls.get(payload.requestId);
if (!pending) {
return false;
}
pendingHostCalls.delete(payload.requestId);
if (payload.result.status === "ok") {
pending.resolve(payload.result.value);
} else {
pending.reject(new Error(payload.result.error.message));
}
return true;
}
// Host requests and host-call responses share the same input stream.
async function handleRequest(envelope) {
const request = envelope.payload;
if (handleHostResponse(request)) {
return;
}
const requestId = request.requestId;
switch (request.kind.type) {
case "activate":
registerPanel();
writeFrame({
type: "runtimeReady"
});
respondOk(requestId, { activated: true });
break;
case "sendEvent":
respondOk(requestId, { received: request.kind.event.name });
break;
case "health":
respondOk(requestId, { ok: true });
break;
case "deactivate":
case "kill":
respondOk(requestId, { stopped: true });
process.exit(0);
break;
case "dispatchCommand":
try {
const version = await callHost("api", "invoke", {
command: "get_app_version",
args: {}
});
respondOk(requestId, { version });
} catch (error) {
respondError(requestId, "command_failed", error.message);
}
break;
default:
respondError(requestId, "unsupported_request", `Unsupported request ${request.kind.type}`);
}
}
readline.createInterface({
input: process.stdin,
crlfDelay: Infinity
}).on("line", (line) => {
if (!line.trim()) {
return;
}
handleRequest(JSON.parse(line)).catch((error) => {
process.stderr.write(`Plugin error: ${error.stack || error.message}\n`);
});
});

这个例子展示了最重要的约定:

  • stdout 只能写协议帧,一行一个 JSON 对象。
  • stderr 才能写给人看的诊断文本。
  • 插件必须用相同的 requestId 回答激活请求。
  • 运行时界面不是 React,而是通过 sidebar-panel 或 tab 注册的声明式结构。
  • 需要返回值的宿主调用用出站 callHostApi 帧发送;宿主会把结果写回插件的 stdin。

如果需要完整的仓库示例,可参考 Host Tools Dashboard。它会同时注册标签页和左侧活动栏面板,自动发现活动节点,并运行清单中声明的自定义 Host Tools 监控。

进程运行时只有一条按行分隔的通信通道。

sequenceDiagram
    participant Host as OxideTerm 宿主
    participant Plugin as 插件进程
    Host->>Plugin: stdin 写入 activate 请求
    Plugin-->>Host: stdout 写出 registerContribution sidebar-panel
    Plugin-->>Host: stdout 写出 runtimeReady
    Plugin-->>Host: stdout 写出 activate ok 响应
    Host->>Plugin: stdin 写入 sendEvent / dispatchCommand / health
    Plugin-->>Host: stdout 写出相同 requestId 的响应

宿主发给插件的激活请求。这里缩短了 manifest 和 allowedHostApis;真实请求会携带解析后的 plugin.json 和完整的最终生效白名单:

{
"protocolVersion": 1,
"requestId": "activate:com.example.hello-native",
"payload": {
"requestId": "activate:com.example.hello-native",
"kind": {
"type": "activate",
"manifest": {
"id": "com.example.hello-native",
"name": "Hello Native",
"version": "0.1.0"
},
"permissions": {
"capabilities": [
"legacy.invoke",
"runtime.process.trusted",
"ui.write"
],
"allowedHostApis": [
"api.invoke",
"app.getVersion",
"connections.getSummaries",
"settings.get",
"ui.registerSidebarPanel",
"ui.registerActivityBarItem"
]
}
},
"timeoutMs": 5000
}
}

插件回给宿主的激活响应:

{
"protocolVersion": 1,
"requestId": "activate:com.example.hello-native",
"payload": {
"requestId": "activate:com.example.hello-native",
"result": {
"status": "ok",
"value": {
"activated": true
}
}
}
}

错误响应:

{
"protocolVersion": 1,
"requestId": "activate:com.example.hello-native",
"payload": {
"requestId": "activate:com.example.hello-native",
"result": {
"status": "error",
"error": {
"code": "invalid_config",
"message": "Missing required plugin setting",
"recoverable": false
}
}
}
}

插件发给宿主的 Host API 调用:

{
"protocolVersion": 1,
"requestId": null,
"payload": {
"type": "callHostApi",
"requestId": "host-1",
"namespace": "app",
"method": "getVersion",
"args": {}
}
}

宿主写回插件的 Host API 响应:

{
"protocolVersion": 1,
"requestId": "host-1",
"payload": {
"requestId": "host-1",
"result": {
"status": "ok",
"value": "0.1.0"
}
}
}

进程桥会在消息进入工作区之前拒绝无效帧。常见拒绝原因包括 protocolVersion 不支持、响应缺少 requestId、响应 id 不匹配、注册信息不属于当前插件,以及 stdout 输出了非 JSON 文本。

宿主调用不是全局 JavaScript 函数,而是协议消息。只有名称出现在最终生效的 allowedHostApis 中,调用才会被接受。默认提供的脱敏只读接口会自动加入;敏感读取和副作用接口会在对应清单能力获批后加入。

api.invoke 还有一道检查:args.command 必须同时出现在 contributes.apiCommands 中。

读取插件设置:

{
"type": "callHostApi",
"requestId": "host-2",
"namespace": "settings",
"method": "get",
"args": {
"key": "message"
}
}

无需申请能力即可读取脱敏终端元数据:

{
"type": "callHostApi",
"requestId": "host-3",
"namespace": "terminal",
"method": "getMetadata",
"args": {}
}

向活跃终端写入文本:

{
"type": "callHostApi",
"requestId": "host-4",
"namespace": "terminal",
"method": "writeToActive",
"args": {
"text": "pwd\n"
}
}

该写入操作需要 terminal.write。读取终端正文或活动目标需要 terminal.content.read。

通过 SFTP 读取远程文件:

{
"type": "callHostApi",
"requestId": "host-5",
"namespace": "sftp",
"method": "readFile",
"args": {
"nodeId": "node-1",
"path": "/etc/hostname"
}
}

这个 SFTP 调用还需要 filesystem.read 能力。写入类操作需要 filesystem.write。传统 SCP 传输沿用同一组能力,并且必须指定在线节点。端口转发变更需要 network.forward。

导入 .oxide 包:

{
"type": "callHostApi",
"requestId": "host-6",
"namespace": "sync",
"method": "importOxide",
"args": {
"fileData": [1, 2, 3],
"password": "user-entered-password",
"conflictStrategy": "rename",
"importAppSettings": true,
"importPluginSettings": true
}
}

不要记录或回显密码、凭据值、终端缓冲区、连接配置、原始导入/导出载荷。

注册标签页视图:

{
"type": "registerContribution",
"registration": {
"registrationId": "hello-tab-view",
"pluginId": "com.example.hello-native",
"kind": "tab",
"metadata": {
"tabId": "hello-tab",
"schema": {
"componentVersion": 1,
"kind": "form",
"title": "Hello",
"controls": [
{
"kind": "markdown",
"text": "This tab is rendered by OxideTerm, not by plugin HTML."
}
]
}
}
}
}

通过 event-subscription 注册订阅:

{
"type": "registerContribution",
"registration": {
"registrationId": "watch-active-node",
"pluginId": "com.example.hello-native",
"kind": "event-subscription",
"metadata": {
"namespace": "sessions",
"method": "onNodeStateChange",
"nodeId": "node-1"
}
}
}

事件触发时,宿主会给进程发送普通的 sendEvent 请求:

{
"protocolVersion": 1,
"requestId": "event:sessions.nodeStateChanged",
"payload": {
"requestId": "event:sessions.nodeStateChanged",
"kind": {
"type": "sendEvent",
"event": {
"name": "sessions.nodeStateChanged",
"payload": {
"nodeId": "node-1"
}
}
}
}
}

插件仍然必须响应:

{
"protocolVersion": 1,
"requestId": "event:sessions.nodeStateChanged",
"payload": {
"requestId": "event:sessions.nodeStateChanged",
"result": {
"status": "ok",
"value": {
"handled": true
}
}
}
}

自定义插件事件使用 events.emit 和 events.on。事件会按插件 id 作用域隔离,因此一个插件不能抢占任意全局事件名。

如果插件没有激活:

  • 检查 runtime.entry 是否指向插件目录内存在的可执行文件。
  • 检查进程是否只向 stdout 输出 JSON Lines。
  • 检查激活响应是否同时包含 envelope requestId 和 payload requestId。
  • 检查 protocolVersion 是否为 1。
  • 检查 stderr 里的插件诊断信息。

如果界面没有出现:

  • contributes.tabs 或 contributes.sidebarPanels 必须声明界面 id。
  • 运行时注册必须使用相同的 tabId 或 panelId。
  • registration.pluginId 必须匹配清单 id。
  • metadata.schema.kind 应该是 form。
  • button、text、password、number、checkbox、select 等可交互控件需要稳定的 id。

如果独立活动栏动作没有出现或无法执行:

  • contributes.activityBarItems 必须声明动作 id、标题、图标、命令和位置。
  • 运行时必须使用 kind: "activity-bar-item" 和相同的 itemId 注册。
  • 插件必须请求 ui.write,并处理清单中声明的 dispatchCommand 值。
  • 运行时元数据不能覆盖清单声明的图标或命令。

如果 Host API 调用失败:

  • 确认调用出现在 allowedHostApis 中。
  • 确认方法名和参数名与下方参考表一致。
  • 对 api.invoke,确认命令出现在 contributes.apiCommands 中。
  • 对 SFTP 或端口转发,确认具备对应能力。
  • 对凭据和密码,确认插件没有通过日志或界面文本发送敏感值。
flowchart TB
    Manifest["plugin.json"] --> Discovery["Native 插件发现"]
    Discovery --> Registry["插件注册表"]
    Registry --> Contributions["清单贡献"]
    Registry --> RuntimePlan["运行计划"]

    RuntimePlan --> ManifestOnly["manifest-only"]
    RuntimePlan --> Process["process 运行时"]
    RuntimePlan --> Wasm["wasm 运行时"]
    RuntimePlan --> Legacy["legacy-js 可见但不执行"]

    Process --> Protocol["JSON Lines 协议"]
    Wasm --> Protocol
    Protocol --> HostApi["宿主 API 解析器"]
    Protocol --> RuntimeRegs["运行时注册"]
    RuntimeRegs --> UI["Native GPUI 页面"]
    HostApi --> Domains["SSH · SFTP · 终端 · IDE · AI · 同步 · 设置"]

宿主持有所有持久化和安全敏感边界:

  • 清单解析与校验。
  • 运行时启动和超时处理。
  • 贡献注册和清理。
  • 宿主 API 权限检查。
  • 插件设置、存储和凭据。
  • 通过 Native GPUI 控件渲染界面。

宿主接口不暴露原始 GPUI 元素、DOM 节点、React 实例或 SSH 传输句柄。原生进程插件拥有其用户的操作系统权限,宿主接口检查不会隔离可执行程序自身的文件与网络访问。

区域Tauri/Web 插件Native 插件
运行时通过动态导入加载 ESM main.js通用扩展使用 process、wasm、manifest-only,专用运行时见上文
界面React 组件和 CSSGPUI 渲染的声明式 Native UI 结构
共享模块window.__OXIDE__不可用
样式CSS 和主题变量只使用宿主拥有的 Native 控件
宿主 API冻结的 PluginContext 对象带命名空间、方法和参数的 JSON 协议调用
旧 JS 插件在 Tauri 中可执行显示为 legacy-js,不执行
安全边界浏览器膜层加 Tauri 命令运行时桥、权限门、作用域存储和凭据

如果插件只有 main 而没有 Native runtime 块,Native 会把它归类为旧 JS 插件。它可以出现在插件管理器中用于迁移,但不会被执行。

插件位于应用配置目录下:

<config-dir>/plugins/<plugin-id>/
plugin.json
bin/
plugin-runtime
assets/
locales/

使用 oxideterm paths --json 查看当前生效配置目录。CLI 可以在无界面流程中启用、禁用和检查插件状态,但交互式安装、更新和卸载由桌面插件管理器负责。

清单插件适合静态元数据、声明式设置、AI 工具元数据和未来包迁移。它不执行代码。

{
"id": "com.example.audit",
"name": "Audit Helper",
"version": "0.1.0",
"description": "Adds audit-related settings and tool metadata.",
"author": "Example",
"contributes": {
"settings": [
{
"id": "scanDepth",
"type": "number",
"default": 3,
"title": "Scan depth",
"description": "Maximum audit depth."
}
],
"aiTools": [
{
"name": "audit_summarize",
"description": "Summarize visible connection and terminal state.",
"capabilities": ["state.list", "terminal.observe"],
"risk": "read",
"targetKinds": ["ssh-node", "terminal-session"]
}
]
}
}

支持的设置类型是 string、number、boolean 和 select。select 设置必须提供 options,选项值必须是字符串或数字。

背景素材包复用现有安装器,只声明 contributes.backgrounds,列出素材相对于包根目录的路径:

{
"id": "com.example.backgrounds",
"name": "背景素材",
"version": "1.0.0",
"engines": { "oxideterm": ">2.2.2" },
"tags": ["backgrounds"],
"contributes": { "backgrounds": ["assets/day.mp4", "assets/night.mp4"] }
}

素材包不声明运行入口、权限或其他插件功能。已发布的 2.2.2 尚不支持此功能,需要后续包含背景素材包支持的主程序。 安装时,素材复制到当前设置文件旁的 backgrounds 目录,便携版跟随自己的配置目录。 安装不改变浅色或深色外观当前选择的背景;同版本重装复用已有副本,新版本添加独立素材。 卸载素材包会保留已导入的文件,用户可以在外观素材库中删除。

主程序保留 15 个内置语法条目:Bash、Zsh、Fish、PowerShell、JSON、YAML、TOML、Markdown、 Dockerfile、Make、CMake、Diff、Python、Lua 和 SQL。 另有 24 个语法条目通过语言插件提供:C、C++、C#、CSS、Common Lisp、Elixir、Go、HTML、Java、 JavaScript、Objective-C、Perl、PHP、R、Ruby、Rust、Scala、Swift、TypeScript、TSX、Zig、Nginx、Terraform/HCL 和 Protobuf。 Nginx 根据 nginx.conf 等专用文件名或 .nginx 扩展名识别,不覆盖通用 .conf。 HCL 识别 .tf、.tfvars 和 .hcl,JSON 变体仍按 JSON 处理;Protobuf 识别 .proto。 TypeScript 与 TSX 分别打包为独立插件。 文件类型识别保留在主程序中。未安装或已禁用时,文档仍可编辑,并提供插件管理器入口。 安装或启用后按需加载解析器;更新与禁用会刷新已打开文档的语法状态,保留文本和撤销历史。 .h 头文件继续识别为 C++。

语言包声明 runtime.kind: "language" 和 contributes.language,包含 Tree-sitter WebAssembly 解析器、高亮查询、各自的 SHA-256 校验值、宿主版本范围及上游许可证。 它不使用通用 WASI 插件的宿主接口。市场仓库维护 固定版本的构建配方与发布流程。 每种语言在 plugins/ 下有独立目录、版本和发布资产。 语言插件自身采用 Apache-2.0,上游许可证单独保留;安装需要严格高于 2.2.0 且包含语言加载能力的主程序。

进程插件是插件目录内的可执行文件。宿主通过 stdin/stdout 启动它,并交换换行分隔的 JSON 协议帧。

{
"id": "com.example.native-dashboard",
"name": "Native Dashboard",
"version": "0.1.0",
"runtime": {
"kind": "process",
"entry": "./bin/native-dashboard"
},
"permissions": {
"capabilities": [
"connections.read",
"legacy.invoke",
"ui.write"
]
},
"contributes": {
"tabs": [
{ "id": "dashboard", "title": "Dashboard", "icon": "LayoutDashboard" }
],
"sidebarPanels": [
{ "id": "dashboard-panel", "title": "Dashboard", "icon": "Activity", "position": "bottom" }
],
"activityBarItems": [
{ "id": "refresh", "title": "刷新仪表盘", "icon": "RefreshCw", "command": "dashboard.refresh", "position": "top" }
],
"terminalHooks": {
"shortcuts": [
{ "key": "Ctrl+Shift+D", "command": "dashboard.refresh" }
]
},
"apiCommands": [
"get_app_version"
]
}
}

规则:

  • runtime.entry 必须是插件目录内的相对路径。
  • process 和 wasm 运行时的入口文件必须存在。
  • 进程插件会隐式申请 runtime.process.trusted。由于进程在没有操作系统沙箱的环境中运行,插件管理器会把这项信任决定纳入启用时的集中批准。
  • 进程不能把普通人类日志写到 stdout。stdout 是协议通道。
  • 诊断文本写到 stderr。
  • 每个协议帧是一行 JSON 对象,以 \n 结尾。

宿主会把每个请求和响应包在 envelope 中。下面省略了部分默认白名单:

{
"protocolVersion": 1,
"requestId": "activate-1",
"payload": {
"requestId": "activate-1",
"kind": {
"type": "activate",
"manifest": {
"id": "com.example.runtime",
"name": "Example Runtime",
"version": "0.1.0"
},
"permissions": {
"capabilities": [],
"allowedHostApis": [
"app.getVersion",
"connections.getSummaries",
"sessions.getSummary",
"terminal.getMetadata"
]
}
},
"timeoutMs": 3000
}
}

插件需要用相同 requestId 响应:

{
"protocolVersion": 1,
"requestId": "activate-1",
"payload": {
"requestId": "activate-1",
"result": {
"status": "ok",
"value": { "activated": true }
}
}
}

宿主可能发送 activate、deactivate、dispatchCommand、sendEvent、callHostApi、health 和 kill 等请求。插件可以发出 runtimeReady、registerContribution、disposeContribution、callHostApi、emitEvent、reportProgress、log 和 runtimeError 等出站帧。

运行时注册让正在运行的进程/WASM 插件增加宿主持有的贡献:

{
"protocolVersion": 1,
"requestId": null,
"payload": {
"type": "registerContribution",
"registration": {
"registrationId": "cmd-refresh",
"pluginId": "com.example.native-dashboard",
"kind": "command",
"metadata": {
"id": "dashboard.refresh",
"label": "Refresh Dashboard",
"icon": "RefreshCw",
"section": "Dashboard"
}
}
}
}

常见注册类型:

类型用途
command添加命令面板动作,并派发回插件
keybinding在内置快捷键未命中后添加快捷键
context-menu为声明目标添加上下文菜单项
status-bar添加宿主持有的状态栏项
tab为已声明标签页注册声明式界面
sidebar-panel为已声明面板注册声明式界面
activity-bar-item注册清单中声明的独立左侧活动栏动作
event-subscription订阅宿主事件
terminal-input-interceptor转换或抑制终端输入
terminal-output-processor在解析器前处理终端输出
terminal-shortcut把终端快捷键处理附着到命令
progress创建宿主持有的进度报告器

注册必须使用发出它的同一个插件 id。释放注册是幂等的,并由宿主执行。

进程插件通过 contributes.connections 声明连接类型,直接进入现有的新建连接窗口和连接管理, 支持搜索、编辑、删除、批量选择和分组。同一配置每次打开都会创建独立实例。 此接口需要 OxideTerm 2.2.5 或更高版本;在 engines.oxideterm 中排除旧版本,并声明 ui.write 权限。

{
"connections": [{
"id": "device",
"title": "设备",
"icon": "plug",
"terminalEntry": "bin/terminal",
"form": {
"controls": [
{"kind": "text", "id": "address", "label": "@address"},
{"kind": "password", "id": "token", "label": "@token"}
],
"translations": {"zh-CN": {"address": "地址", "token": "令牌"}}
}
}]
}

正式插件应提供完整的 11 语言词典。表单复用原生控件,支持 text、password、number、 checkbox、select、textarea、stack、row、columns 和 markdown。 名称和分组由宿主提供。区段、字段标识不得包含 /,__profile 为宿主保留区段。 配置键采用 sectionId/controlId,顶层控件的区段为 root。数值输入框提交其文本表示。

密码字段需要用户批准 credentials.raw.read。凭据存入宿主的安全存储,连接配置只保存引用。 编辑时密码留空会保留原值;勾选“清除已保存的凭据”后,先移除旧凭据,再保存本次输入的新值。 表单草稿不会发送给插件。停用或卸载插件后,配置仍然保留,名称、分组仍可编辑,也可以删除。 插件连接纳入云同步的连接范围,也支持 .oxide 的选择、预览和冲突处理。 同步按 plugin_id 和 type_id 识别提供方;接收配置不要求本机已安装对应插件。 无法识别的配置字段会保留在存储和后续导出中,connection.open 只接收当前插件表单声明的字段, 因此旧版插件编辑连接时不会删除新版设置。密码字段同样按当前表单筛选。

凭据仅在开启敏感凭据同步,或加密导出时勾选包含密码后传输;导入文件还需勾选恢复已保存的凭据。 本机安全存储引用不会跨设备复制,恢复后会生成新的本机引用。缺少插件的连接保持不可连接状态, 安装并启用兼容插件后即可使用。两台设备的宿主都需支持插件连接。

插件激活后,宿主发送 connection.open 命令,参数为:

{
"instanceId": "host-generated-uuid",
"profileId": "saved-profile-uuid",
"typeId": "device",
"config": {"root/address": "device.local"},
"credentials": {"root/token": "user-provided-secret"}
}

运行中的资源应按 instanceId 管理,不能按 profileId 共用。命令返回以下结果之一:

  • {"kind":"workbench","schema":{...}}:显示声明式工作台,可与终端分屏。 交互事件 ui.event.surfaceId 就是实例标识。持续刷新时发送 tab 注册,在元数据中提供 connectionId: instanceId 和 schema;每个实例使用独立的注册标识。
  • {"kind":"terminal","args":[...]}:用宿主原生终端直接启动声明的 terminalEntry。 可执行文件必须位于插件目录内,参数保持独立,不会在失败后改用命令解释器。 凭据应由插件进程持有并提供给其辅助进程,不得放入启动参数或环境变量。
  • {"kind":"sshTerminal","shell":"posix","nodeId":"...","argv":["program","arg"]}: 获得 terminal.write 授权后,在已连接的节点上打开终端消费者。宿主按明确选择的 POSIX 命令解释器逐个转义参数,拒绝能修改或提交命令行的控制字符,不另建脱离节点管理的 SSH 连接。

断开连接或关闭对应工作台、终端时,宿主发送 connection.close,参数为 {"instanceId":"..."}。此命令必须幂等,对未知实例和已取消的打开请求也应成功返回, 回复前释放该实例的网络连接、订阅和后台任务。切换页面不会断开,移动或拆分终端也不改变其所有者。 生命周期命令须在五秒内回复;传输超时或清理失败时,宿主停止整个提供方进程及其终端消费者。 停用、更新插件同样会停止运行实例,但保留配置。迟到的结果和界面更新不能重新打开已关闭的实例。

进程插件完成激活后,可以主动向 stdout 写入协议帧,无需等待用户操作。 重新发送相同 registrationId 的 tab 或 sidebar-panel 注册即可更新界面; 权限校验与首次注册一致。宿主持续读取输出,按有界批次交付界面更新。 插件应合并短时间内的消息,只提交需要显示的有限数据,避免每条消息重发整个页面。 stdout 仍只用于 JSON Lines 协议,后台任务不得混入诊断文本。

切换或关闭普通注册标签页不会停止插件进程。插件负责自身网络连接和任务,提供明确的断开操作; 停用插件、卸载或退出工作区时,宿主终止运行时及其输出读取任务,并丢弃旧运行实例的更新。 这些能力需要 OxideTerm 2.2.5 或更高版本;依赖它们的插件应在 engines.oxideterm 中排除旧版本。

表格声明 id、selectable: true 和 rowKey 后支持鼠标选择,以及获得焦点后的方向键、 Home、End 选择。rowKey 指定行对象中的字段名,每行必须提供非空、唯一的字符串标识。 value 可设置选中行的标识;用户选择通过 ui.event 返回,type 为 change, value 为该行标识。未声明选择能力的旧表格保持只读。

{
"kind": "table",
"id": "messages",
"selectable": true,
"rowKey": "id",
"columns": ["topic", "preview"],
"rows": [{"id": "message-1", "topic": "devices/status", "preview": "ready"}]
}

带稳定 id 的表格和列表在刷新时保留滚动位置。提供 rowKey 时,插入、删除或重排后 继续显示原来的首个可见行;该行已删除时使用仍有效的邻近位置。选中行被删除时清除选择。 保持插件、页面、区段和控件标识不变,才能沿用这些状态。

使用 textarea 编辑多行消息正文:

{"kind": "textarea", "id": "body", "label": "@payload", "value": "first line\nsecond line"}

它复用原生文本编辑器的输入法、选择、撤销、复制粘贴和滚动行为,编辑后发送 ui.event(type: "input",value 为完整文本)。无关界面刷新保留正在编辑的草稿; 插件显式改变 value 时替换文本。disabled 禁止编辑。关闭所属页面后释放编辑器状态。 label、placeholder 等文案继续使用插件的 11 语言翻译词典。

Native 插件通过带版本的结构选择 OxideTerm 组件。插件提供数据并接收事件; 宿主提供真正的共享组件、主题令牌、密度、字体、焦点、输入法行为、无障碍语义 和响应式布局。插件运行时不会获得原始 GPUI 对象,也不能注入 HTML、CSS、 闭包或自绘代码。

{
"protocolVersion": 1,
"requestId": null,
"payload": {
"type": "registerContribution",
"registration": {
"registrationId": "tab-dashboard",
"pluginId": "com.example.native-dashboard",
"kind": "tab",
"metadata": {
"tabId": "dashboard",
"schema": {
"componentVersion": 1,
"kind": "form",
"title": "Dashboard",
"sections": [
{
"id": "overview",
"title": "Overview",
"controls": [
{ "kind": "markdown", "text": "Native plugin UI is host-rendered." },
{ "kind": "keyValue", "label": "Status", "value": "Ready" },
{ "kind": "progress", "label": "Sync", "value": 42 },
{ "kind": "button", "id": "refresh", "label": "Refresh" }
]
}
]
}
}
}
}
}

支持的控件类型:

类型说明
stack, row, card, toolbar布局组件,以有界的宿主布局渲染嵌套 children
columns等宽分栏,容器变窄时自动换行
actionRow首个子项占用剩余宽度,其余操作靠右对齐;首项为按钮时填满该区域
text, password, number, checkbox, select共享字段组件,需要稳定的 id
radioGroup, radio-group, segmentedControl, segmented-control, slider共享选择/范围组件,需要稳定的 id
button, iconButton, icon-button共享动作组件;有 id、未禁用且未加载时可操作;图标按钮还需要 icon 和 label
alert带语义色调、可选图标、标题和说明的宿主提示
markdown使用 OxideTerm 的 Markdown 渲染器解析;禁用后台图片和本地文件链接
code, codeBlock, code-block代码块
statusBadge, status-badge, badge带语义色调和强度的共享状态徽章
progress共享进度组件,数值可使用 0..1 或 0..100
table, list有界、虚拟化的共享数据组件
emptyState, empty-state带可选图标和说明的共享空状态
divider共享分隔线
keyValue, key-value, keyValueRow, key-value-row键值行

组件事件只会发给拥有该界面的插件:

{
"name": "ui.event",
"payload": {
"type": "change",
"componentKind": "select",
"surfaceKind": "tab",
"surfaceId": "dashboard",
"sectionId": "overview",
"controlId": "environment",
"value": "production"
}
}

按钮发出 click,文本字段发出 input,选择和范围组件发出 change。 密码草稿由宿主清零。没有明确获批的 credentials.raw.read 能力时,密码事件 只包含 { "present": boolean, "redacted": true };只有敏感内容权限获批后, 原文才会发给拥有该界面的插件。密码组件不能声明初始 value,因此凭据不会 被保留在已注册的界面结构中。

为保证安全和可预测性能,组件版本 1 最多接受 8 层嵌套、256 个组件、每个容器 64 个直接子项、每个选择组件 128 个选项、每个数据组件 2,000 行,以及 64 个 表格列。控件 ID 在其根区域或区段内必须唯一,root 不能用作区段 ID。 注册时会拒绝未知版本、变体、色调、尺寸、间距或非法子组件位置。完整编码结构 的上限是 2 MiB。

WASM 插件可以注册带稳定 id 的 textWorkbench 控件。options 中每个工具采用 { label, value: { command, group?, description?, parameterLabel?, parameterDefault? } }。 相同 group 的工具共用左侧分组入口,具体操作显示在编辑器上方。可选参数使用原生输入框; 切换到不同参数时采用声明的默认值,相同参数名称的操作之间保留当前值。 控件的 value 提供 input、output、execute、working、copy、useInput、 clear、limit、failed、line、column 及插件错误码对应的翻译文案。 界面结构可携带 translations: { "en": { key: text }, "zh-CN": { key: text }, ... }, 以 @ 开头的字符串会从该词典翻译,覆盖页面头部和工具选项。插件应包含全部 11 种语言, 且键集合一致。此能力要求 2.2.0 之后的宿主。

宿主持有输入和只读结果编辑器,处理选择、复制和草稿生命周期。点击执行时截取当前输入, 在新的 WASM 实例中调用选中命令,参数为 { input, parameter };返回值为 { output: string } 或 { error: { code, line?, column? } }。错误码对应控件提供的翻译, 未知错误统一显示 failed。输入限制为 256 KiB,参数 4 KiB,输出 2 MiB,执行时限五秒。 失败时保留输入和上次结果。输入不进入界面注册、设置或终端命令;关闭标签页释放编辑器并 取消结果回传,已开始执行的 WASM 调用受时限约束。计算实例不提供宿主调用、文件目录或网络权限。

运行时菜单注册 contextMenu 的 target 为 terminal,菜单项提供 { label, tabId, controlId }。宿主在点击时捕获选区,随后打开该插件声明的文本处理区。 之后切换窗格或终端输出变化都不会改变已捕获的输入;@ 菜单文案使用目标标签页的翻译。

独立进程插件可以在现有文件预览窗口中提供分页文档预览,不需要注册标签页或侧边栏:

{
"contributes": {
"filePreviews": [{"mimeTypes": ["application/pdf"], "command": "preview.render"}]
}
}

宿主按精确的 MIME 类型选择已启用、版本兼容且已获信任的插件。本地及 SFTP 下载的 PDF、SQLite、证书和二进制文件通过文档资源进入预览,第一版大小限制为 10 MiB。其他内置预览类型沿用原有实现。 每次渲染启动独立进程实例,使用现有 activate 和 dispatchCommand 协议。 命令接收 { path, page, width }:page 从零开始,width 为 256 至 2048 像素的期望图片宽度。 返回 { pageCount, page, png },其中 png 是 Base64 编码的 PNG 图片。 宿主限制解码后的图片不超过 800 万像素,并通过 GPUI 显示。预览实例只返回页面结果, 不要从中注册界面或调用宿主 API。

SQLite 插件注册 application/vnd.sqlite3,也可注册 application/x-sqlite3。 请求额外携带 table: string | null 和 snapshot: boolean。只有宿主管理的临时下载副本 会设置 snapshot: true,插件将其作为不可变文件打开,避免生成 WAL/SHM 辅助文件; 本地文件使用普通 SQLite 只读访问。返回结构为 { kind: "table", tables: string[], selectedTable: string | null, columns: string[], rows: (string | null)[][], rowCount, page, pageCount }。每页 50 行,末页可不足 50 行; 空表或空数据库保留一页。宿主检查表名、行结构和大小后使用原生表格显示。 限制为 256 个表名、64 列及每页 4 MiB 单元格文本。 远程文件存在非空 WAL/回滚日志或下载期间发生变化时拒绝预览,应使用停止写入后的完整备份。

证书插件注册 application/pkix-cert,二进制检查器注册 application/x-oxideterm-binary。 宿主根据扩展名及文件头选择这些入口,优先于文本预览。检查器返回 { kind, index, objects, fields },其中 index 对应请求的 page,objects 最多列出 64 个证书或架构,fields 使用宿主已翻译的字段键,元素格式为 { key, value }。 证书返回 kind: "certificate"、详细字段 details,以及以秒计的时间戳 notBefore、 notAfter。只返回证书的公开字段,混合 PEM 中的私钥块不得进入结果。界面单独判断有效期, 不将其等同于系统信任、证书链、签名或吊销检查。

二进制返回 kind: "binary"、完整文件大小 size,以及最多 1024 个节区 sections。 节区格式为 { name, address, offset, size };文件偏移相对于整个源文件,包括通用 Mach-O 文件。没有文件数据的节区使用 offset: null。宿主检查节区范围,并复用已有十六进制格式化 和只读编辑器,每次显示 512 字节,支持偏移跳转。插件仅解释文件,不编辑、反汇编或注册额外界面。

预览窗口持有取消句柄和源文件的生命周期。关闭窗口会取消渲染进程及待完成的 SFTP 预览下载,最后一个文件使用者释放后删除远程临时副本,不会断开共享 SSH 节点。 独立进程仍需用户确认信任;进程隔离用于防止解析器崩溃影响应用,不是文件系统沙箱。 禁用或卸载插件后,宿主不再选择它,并取消其正在打开的预览。

此能力在 2.2.0 之后新增。正式插件包必须排除旧宿主,本地试用版不得放宽正式发布包的兼容范围。

运行时插件通过命名空间、方法和 JSON 参数调用宿主 API:

{
"protocolVersion": 1,
"requestId": null,
"payload": {
"type": "callHostApi",
"requestId": "host-1",
"namespace": "connections",
"method": "getAll",
"args": {}
}
}

宿主会拒绝不在最终生效权限集中的调用。直接宿主 API 根据获批能力生成,不需要在 contributes.apiCommands 中重复声明。该列表只作为旧版 api.invoke 适配器所调用命令的第二层白名单。

常见命名空间:

命名空间常见用途
connections读取并控制保存/在线连接生命周期
sessions读取节点树和活跃节点状态
terminal观察缓冲区或发送已批准输入
sftp通过节点拥有的 SFTP 列出、读取、写入远端文件
scp在 SFTP 不可用时,通过节点拥有的传统 SCP 传输文件
forward列出、创建、停止转发
transfers观察传输状态
profiler读取节点指标
hostTools读取缓存宿主状态、采集类型化数据集并执行已验证动作
eventLog读取应用事件日志
notifications读取或管理通知中心条目
quickCommands读取、管理或执行保存的快捷命令
cloudSync读取安全同步状态/历史并控制同步操作
theme读取完整有效 token 并选择已安装主题
ide观察和编辑当前 IDE 项目
ai读取已脱敏 AI 数据并控制对话或生成
app主题、平台、版本和设置快照
settings插件设置和可同步设置
storage插件作用域 JSON KV
sync.oxide、保存连接、插件设置和同步元数据
secrets插件作用域凭据存储
uitoast、确认对话框、布局和进度

此表描述当前已实现的命名空间。调用默认可用的 app.getApiCatalog 可以发现当前宿主支持的准确直接 API,以及每个 API 的访问等级、所需能力和引入版本;版本与能力协商以该目录为准。

在清单顶层声明敏感读取和副作用:

{
"permissions": {
"capabilities": ["terminal.content.read", "terminal.write"]
}
}

省略 permissions.capabilities 或使用空数组,不会得到一个什么都不能做的插件。每个运行时插件默认都能调用实用的脱敏接口,包括 connections.getSummaries、sessions.getSummary、terminal.getMetadata、ai.getCatalog、ide.getSummary 和 app.getApiCatalog。默认元数据不包含终端原文、文件内容、AI 对话正文、凭据或修改操作。

当前能力名称如下:

能力含义
filesystem.read通过已批准宿主 API 读取文件元数据或内容
filesystem.write通过已批准宿主 API 修改文件
filesystem.delete通过已批准宿主 API 删除文件或目录树
network.forward.read读取保存和活动的转发规则
network.forward创建或管理转发/网络桥接行为
app.settings.read读取宿主设置分类
app.sync.refresh外部同步后刷新宿主状态
connections.read读取完整的保存连接和端点投影
connections.control连接、重连或显式断开产品拥有的现有节点
sessions.read读取完整会话树、活动节点投影和事件日志
terminal.content.read读取终端目标、选区、回滚缓冲或搜索结果
terminal.write写入终端输入、清空缓冲区或打开 Telnet 传输
credentials.raw.read返回插件作用域凭据原文
credentials.manage通过宿主代理保存、检查或删除插件作用域凭据
network.http允许通过旧版请求适配器发送 HTTP/HTTPS 请求
sync.read读取或导出同步数据
sync.write刷新、应用或导入同步数据
transfers.read读取和订阅传输状态
ide.read读取完整 IDE 项目和打开文件投影
ide.write在现有 IDE 项目中打开、编辑、保存、关闭文件或刷新项目
ai.content.read读取 AI 对话和消息正文
ai.write创建、选择或删除对话,发送文本或取消生成
host_tools.read读取缓存宿主状态或采集类型化 Host Tools 数据
host_tools.write执行已验证的非破坏性进程、容器、服务、tmux 或任务动作
host_tools.destructive终止进程或销毁 tmux 资源
host_tools.custom.execute执行当前插件清单中预先声明的静态自定义监控命令
notifications.read读取通知标题、正文和作用域投影
notifications.manage标为已读、删除、清空或修改免打扰状态
quick_commands.read读取完整的保存快捷命令定义
quick_commands.manage创建、更新或删除快捷命令
quick_commands.execute通过常规风险确认执行保存的快捷命令
theme.write选择已安装的内置或自定义主题
cloud_sync.read读取已脱敏的云同步历史
cloud_sync.control检查、上传、预览拉取或配置自动上传
cloud_sync.apply应用当前已审阅的远端预览
legacy.invoke调用兼容层 api.invoke 适配器
events.emit发出插件作用域自定义事件
plugin.settings.write修改插件设置或插件作用域存储
ui.write注册或打开插件界面,并显示宿主界面效果
runtime.process.trusted信任无沙箱的进程运行时;进程插件会隐式添加

插件管理器会在启用插件时集中展示所有申请的敏感能力。批准前不会激活插件;批准后,运行时会在 activate 请求里收到最终生效的权限集,插件应把它作为准确信息来源。仅升级版本不会再次提示,也不会扩大权限。新增能力或改变运行时边界需要重新审核;移除能力只会缩小权限,不会再次提示。

进程插件需要特别谨慎:它会隐式申请且不能移除 runtime.process.trusted。进程不受 OxideTerm 操作系统沙箱限制,因此其可执行文件可以绕过宿主 API 权限门,直接使用当前用户拥有的系统权限。只应安装并批准可信发布者的进程插件,不能把 WASM 与进程插件描述为具有相同的安全边界。

HTTP 请求当前通过兼容层适配器实现。插件必须同时申请 legacy.invoke 和 network.http,并在 contributes.apiCommands 中列出 plugin_http_request,才能通过 api.invoke 调用该命令。

AI 工具元数据还可以声明 terminal.observe、terminal.send、state.list、settings.read、settings.write 和 plugin.invoke 等语义能力。这些声明用于描述工具行为,服务于宿主和模型侧展示;它们不会绕过运行时权限检查。

按数据性质选择最小边界:

数据边界说明
用户可见插件选项contributes.settings 和 settings.*类型化值;不是凭据时可安全导入导出
插件内部缓存storage.*插件作用域 JSON KV,有大小限制
token、密码、密钥secrets.*系统钥匙串支持的插件作用域凭据存储;读取原文需要 credentials.raw.read,set/has/delete 需要 credentials.manage
跨机器插件偏好插件设置导入导出或 .oxide不要包含原始凭据,除非加密便携流程明确支持

不要把凭据写进插件 id、名称、标签、日志、AI 提示词、事件载荷或支持包。

Native 插件应尽量使用稳定节点 id:

  • 使用节点/会话快照,不要假设当前终端标签页就是所有者。
  • 终端输入钩子出错或超时时必须失败开放。
  • SFTP 修改操作需要文件写能力和在线节点。
  • SCP 调用共享节点拥有的 SSH 连接。在线通道可以暂停或取消,但失败或断线后的 SCP 重试会从零字节开始。
  • 转发调用需要网络转发能力,并应处理已挂起节点。
  • IDE API 暴露项目和打开文件元数据,不暴露任意编辑器内部状态。
  • AI API 暴露已脱敏元数据,避免暴露工具消息内容。

破坏性动作应表示为宿主可见命令或带清晰风险元数据的 AI 工具。

推荐包形状:

com.example.native-dashboard/
plugin.json
bin/
native-dashboard
README.md
LICENSE

打包规则:

  • 插件根目录或单层嵌套插件目录必须包含 plugin.json。
  • 归档条目不能逃逸插件目录。
  • 包大小和条目数量应低于宿主限制。
  • 一个包优先只包含一个插件 id。
  • 使用语义化版本,便于更新检查比较。
  • 根据实际兼容性测试,在 engines.oxideterm 中声明宿主范围,例如 >=2.3.0, <3.0.0。
  • 除非入口本身可移植,否则运行时二进制应按平台分发。

插件市场保留每个发布版本的宿主范围和各平台安装包,选择当前可用的最高版本。 更高版本不兼容时单独说明要求,保留当前插件。安装和启动都会检查清单中的兼容范围, 应用升级和降级后同样生效。不兼容插件保留文件与设置,但停止加载。 启动激活前会刷新官方目录并缓存,离线时读取缓存;有记录的兼容性纠错优先于包内声明, 但不会改写安装包。未收录且未声明范围的旧安装包仍允许使用;旧版主应用不会因此自动获得兼容检查。 目录格式和发布流程见发布指南。

开发时:

  1. 将插件目录复制到 <config-dir>/plugins/。
  2. 打开桌面插件管理器。
  3. 启用或重新加载插件。
  4. 检查状态、错误和权限。
  5. 只在无界面状态/设置检查中使用 CLI:
Terminal window
oxideterm plugins list --json
oxideterm plugins enable com.example.native-dashboard --dry-run --json
oxideterm plugins settings export --json
interface NativePluginManifest {
id: string;
name: string;
version: string;
description?: string;
author?: string;
main?: string; // Tauri 旧 JS 入口;Native 可见但不执行。
engines?: { oxideterm?: string };
manifestVersion?: number;
format?: string;
assets?: string;
styles?: string[];
sharedDependencies?: Record<string, string>;
repository?: string;
checksum?: string;
contributes?: NativePluginContributes;
locales?: string;
runtime?: NativePluginRuntime;
permissions?: NativePluginPermissions;
}
interface NativePluginPermissions {
capabilities?: string[];
}
interface NativePluginRuntime {
kind: 'wasm' | 'process' | 'manifest-only' | 'language' | 'acp' | 'remote-desktop' | 'terminal-transport' | 'helper';
entry: string;
}
interface NativePluginContributes {
backgrounds?: string[];
language?: {
id: string;
displayName?: string;
grammarName?: string;
extensions?: string[];
fileNames?: string[];
highlights: string;
parserSha256: string;
highlightsSha256: string;
};
tabs?: NativePluginTabDef[];
sidebarPanels?: NativePluginSidebarDef[];
activityBarItems?: NativePluginActivityBarItemDef[];
settings?: NativePluginSettingDef[];
terminalHooks?: NativePluginTerminalHooksDef;
terminalTransports?: string[];
connectionHooks?: Array<'onConnect' | 'onDisconnect' | 'onReconnect' | 'onLinkDown'>;
aiTools?: NativePluginAiToolDef[];
apiCommands?: string[];
hostMonitors?: NativePluginHostMonitorDef[];
}
interface NativePluginHostMonitorDef {
id: string;
title: string;
description?: string;
commands: Partial<Record<'linux' | 'macos' | 'bsd' | 'windows' | 'default', string>>;
output?: {
format?: 'json' | 'jsonLines' | 'tsv' | 'textLines';
columns?: string[]; // 仅 tsv 必填。
maxRows?: number; // 默认 1,000,最大 2,000。
};
timeoutSeconds?: number; // 默认 10,范围 1-30。
maxOutputBytes?: number; // 默认 262,144,范围 1 KiB-1 MiB。
}
interface NativePluginTabDef {
id: string;
title: string;
icon: string;
}
interface NativePluginSidebarDef {
id: string;
title: string;
icon: string;
position?: 'top' | 'bottom';
}
interface NativePluginActivityBarItemDef {
id: string;
title: string;
icon: string;
command: string;
position?: 'top' | 'bottom';
}
interface NativePluginSettingDef {
id: string;
type: 'string' | 'number' | 'boolean' | 'select';
default: unknown;
title: string;
description?: string;
options?: Array<{ label: string; value: string | number }>;
}
interface NativePluginTerminalHooksDef {
inputInterceptor?: boolean;
outputProcessor?: boolean;
shortcuts?: Array<{ key: string; command: string }>;
}
interface NativePluginAiToolDef {
name: string;
description: string;
parameters?: unknown;
capabilities?: string[];
risk?: 'read' | 'write-file' | 'execute-command' | 'interactive-input' | 'destructive' | 'network-expose' | 'settings-change' | 'credential-sensitive';
targetKinds?: Array<'local-shell' | 'ssh-node' | 'terminal-session' | 'sftp-session' | 'ide-workspace' | 'app-tab' | 'mcp-server' | 'rag-index'>;
resultSchema?: unknown;
}

校验规则:

  • id、name、version、贡献 id、标题和图标必须是非空文本。
  • 活动栏动作的命令必须非空,插件内的动作 id 必须唯一,position 只接受 top 或 bottom。
  • 标签页、侧栏面板和活动栏动作的图标从 OxideTerm 内置 Lucide 图标中解析;匹配时忽略 ASCII 大小写、连字符与下划线,不支持的名称回退为 Puzzle。
  • 相对路径必须留在插件目录内。
  • terminalTransports 当前接受 telnet。
  • apiCommands 条目是兼容层适配器命令,例如 get_app_version 或 plugin_http_request;直接宿主 API 不在这里声明。
  • 清单插件应省略 runtime;空运行时入口无法通过校验。
  • 只有旧 main 且没有 runtime 时,插件状态为 legacy-js,不会执行。
interface PluginProtocolEnvelope<T> {
protocolVersion: 1;
requestId?: string | null;
payload: T;
}
interface PluginRequest {
requestId: string;
kind:
| { type: 'activate'; manifest: NativePluginManifest; permissions: PluginPermissionSet }
| { type: 'deactivate' }
| { type: 'callHostApi'; namespace: string; method: string; args?: unknown }
| { type: 'dispatchCommand'; command: string; args?: unknown }
| { type: 'sendEvent'; event: PluginEvent }
| { type: 'cancelRequest'; requestId: string }
| { type: 'health' }
| { type: 'kill' };
timeoutMs?: number;
}
interface PluginResponse {
requestId: string;
result:
| { status: 'ok'; value: unknown }
| { status: 'error'; error: PluginError };
}
interface PluginError {
kind: string;
code: string;
message: string;
}
interface PluginPermissionSet {
capabilities: string[];
allowedHostApis: string[];
}
interface PluginEvent {
name: string;
payload?: unknown;
}
type PluginOutboundMessage =
| { type: 'registerContribution'; registration: PluginRegistration }
| { type: 'disposeContribution'; registrationId: string }
| { type: 'log'; level: 'debug' | 'info' | 'warn' | 'error'; message: string }
| { type: 'reportProgress'; registrationId: string; value: unknown }
| { type: 'runtimeReady' }
| { type: 'runtimeError'; error: PluginError }
| { type: 'emitEvent'; event: PluginEvent }
| { type: 'callHostApi'; requestId: string; namespace: string; method: string; args?: unknown };
interface PluginRegistration {
registrationId: string;
pluginId: string;
kind:
| 'command'
| 'keybinding'
| 'context-menu'
| 'status-bar'
| 'tab'
| 'sidebar-panel'
| 'activity-bar-item'
| 'terminal-input-interceptor'
| 'terminal-output-processor'
| 'terminal-shortcut'
| 'event-subscription'
| 'progress';
metadata?: unknown;
}
注册类型必需元数据可选元数据
commandid 或 command、labelicon、shortcut、section
keybindingkeybinding 或 key、command、labelwhen
context-menutarget、items目标相关菜单项元数据
status-bartextalignment、icon、tooltip
tabtabId、schemaschema 内的 title
sidebar-panelpanelId、schemaposition、schema 内的 title
activity-bar-itemitemId无;标题、图标、位置和命令均来自清单
event-subscriptionevent 或 namespace + method部分事件族支持 nodeId 过滤
terminal-input-interceptorcommand 或 id无
terminal-output-processorcommand 或 id无
terminal-shortcutcommand 或 id使用清单里声明的快捷键
progressid 或生成的 idtitle、message
interface NativePluginDeclarativeUiSchema {
translations?: Record<string, Record<string, string>>;
componentVersion?: 1;
kind?: 'form';
title?: string;
description?: string;
sections?: NativePluginDeclarativeUiSection[];
controls?: NativePluginDeclarativeUiControl[];
}
interface NativePluginDeclarativeUiSection {
id: string;
title?: string;
description?: string;
controls?: NativePluginDeclarativeUiControl[];
}
interface NativePluginDeclarativeUiControl {
kind:
| 'text'
| 'textWorkbench'
| 'password'
| 'number'
| 'checkbox'
| 'select'
| 'radioGroup'
| 'radio-group'
| 'slider'
| 'segmentedControl'
| 'segmented-control'
| 'button'
| 'iconButton'
| 'icon-button'
| 'stack'
| 'row'
| 'columns'
| 'actionRow'
| 'card'
| 'toolbar'
| 'alert'
| 'markdown'
| 'code'
| 'codeBlock'
| 'code-block'
| 'statusBadge'
| 'status-badge'
| 'badge'
| 'progress'
| 'table'
| 'list'
| 'emptyState'
| 'empty-state'
| 'divider'
| 'keyValue'
| 'key-value'
| 'keyValueRow'
| 'key-value-row';
id?: string;
label?: string;
description?: string;
placeholder?: string;
icon?: string;
variant?: 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link' | 'panel' | 'inset' | 'inspector';
tone?: 'neutral' | 'accent' | 'success' | 'warning' | 'error' | 'info';
size?: 'small' | 'default' | 'large' | 'icon';
gap?: 'none' | 'compact' | 'normal' | 'spacious';
value?: unknown;
text?: string;
language?: string;
options?: Array<{ label: string; value: unknown }>;
rows?: unknown[];
columns?: string[];
columnDefs?: Array<{ key: string; label: string; style?: 'primary' | 'meta' | 'mono' }>;
children?: NativePluginDeclarativeUiControl[];
min?: number;
max?: number;
step?: number;
indeterminate?: boolean;
strong?: boolean;
disabled?: boolean;
loading?: boolean;
}

所有交互组件都需要稳定的 id:text、password、number、 checkbox、select、单选组、分段选择、滑块、按钮和图标按钮。按钮只有在 disabled 和 loading 均为 false 时可操作。为兼容旧结构, componentVersion 省略时默认为 1,但插件应明确声明它,以便将来协商组件变化。

所有宿主 API 使用同一种调用结构:

interface HostCall {
requestId: string;
namespace: string;
method: string;
args?: unknown;
}

调用必须出现在 allowedHostApis 中。支持精确名称和命名空间通配,例如 connections.getAll 和 connections.*。

api.invoke 需要 legacy.invoke,并且还有额外白名单:args.command 必须同时出现在 contributes.apiCommands 中。plugin_http_request 命令还需要 network.http。

api.invoke 命令Native 适配器
ssh_get_pool_statsSSH 连接池统计
list_connections保存/已知连接快照
get_app_version应用版本
get_system_info平台、架构、系统和系统族
sftp_cancel_transfer按 transferId 取消传输
sftp_pause_transfer按 transferId 暂停传输
sftp_resume_transfer按 transferId 恢复传输
sftp_transfer_stats传输队列统计
node_sftp_initsftp.init 适配器
node_sftp_list_dirsftp.listDir 适配器
node_sftp_statsftp.stat 适配器
node_sftp_previewsftp.preview 适配器
node_sftp_writesftp.write 适配器
node_sftp_downloadsftp.download 适配器
node_sftp_uploadsftp.upload 适配器
node_sftp_mkdirsftp.mkdir 适配器
node_sftp_deletesftp.delete 适配器
node_sftp_delete_recursivesftp.deleteRecursive 适配器
node_sftp_renamesftp.rename 适配器
node_sftp_download_dirsftp.downloadDir 适配器
node_sftp_upload_dirsftp.uploadDir 适配器
node_sftp_tar_probesftp.tarProbe 适配器
node_sftp_tar_uploadsftp.tarUpload 适配器
node_sftp_tar_downloadsftp.tarDownload 适配器
node_scp_probescp.capabilities 适配器
node_scp_downloadscp.download 适配器
node_scp_uploadscp.upload 适配器
node_scp_download_dirscp.downloadDirectory 适配器
node_scp_upload_dirscp.uploadDirectory 适配器
list_port_forwardsforward.list 适配器
create_port_forwardforward.create 适配器
stop_port_forwardforward.stop 适配器
delete_port_forwardforward.delete 适配器
restart_port_forwardforward.restart 适配器
update_port_forwardforward.update 适配器
get_port_forward_statsforward.getStats 适配器
stop_all_forwardsforward.stopAll 适配器
plugin_http_requestHTTP/HTTPS 请求适配器,正文上限 10 MiB
宿主 API参数返回
api.invoke{ command: string, args?: object }contributes.apiCommands 已声明命令的适配器结果
app.getTheme{}{ name, isDark }
app.getSettings{ category: string }设置部分 JSON
app.getVersion{}版本字符串
app.getPlatform{}平台字符串
app.getLocale{}语言字符串
app.getApiCatalog{}已实现直接 API 及其访问等级、能力和引入版本
app.getPoolStats{}类似 { activeConnections, totalSessions } 的统计
app.refreshAfterExternalSync{}单向刷新工作区效果
ui.getLayout{}布局快照
ui.registerTabView{ tabId: string, schema: NativePluginDeclarativeUiSchema }声明式标签页注册结果
ui.registerSidebarPanel{ panelId: string, schema: NativePluginDeclarativeUiSchema }声明式侧边栏注册结果
ui.registerActivityBarItem{ itemId: string }独立活动栏动作注册结果
ui.openTab{ tabId: string }打开或聚焦已声明插件标签页
ui.showToast{ title?: string, description?: string, variant?: string }单向 toast 效果
ui.showNotification{ title?: string, body?: string, severity?: string }单向通知效果
ui.showConfirm{ title: string, description: string }boolean
ui.showProgress{ title?: string, message?: string, registrationId?: string, id?: string }{ id, registrationId }
events.emit{ name: string, payload?: unknown }{ emitted: true, event }
settings.get{ key: string }插件设置值或 null
settings.set{ key: string, value: unknown }单向设置写入
settings.exportSyncableSettings{}{ revision, exportedAt, payload, warnings }
settings.applySyncableSettings{ payload: object }{ revision, appliedPayload, warnings }
i18n.getLanguage{}语言字符串
i18n.t{ key: string }翻译文本或回退 key

2.2.0 之后的宿主新增工作概览接口:

  • app.getWorkspaceSummary({}) 需要 sessions.read,返回打开标签的标识、标题、类型和录制状态,节点的标识、标题、状态和活动转发数量,以及存在问题的插件标识和名称;不返回终端内容、路径或诊断原文。
  • ui.openWorkspace(destination) 需要 ui.write,校验目标后返回 { queued: true },复用宿主原有的页面打开和独立窗口聚焦流程。

目标格式为 { kind: "tab", id }、{ kind: "sftp", nodeId }、 { kind: "forwards", nodeId } 或 { kind: "page", page }。 页面名称支持 sessions、files、plugins、cloudSync、 notifications 和 localTerminal。已关闭的标签、已删除的节点及未知页面会被拒绝。 该接口不执行任意命令;打开保存连接仍使用 connections.connect 及其独立权限。 工作概览返回当前状态,不提供持久化的项目历史或工作区历史。

宿主 API参数返回
connections.getSummaries{}脱敏连接摘要;默认可用
connections.getSavedSummaries{}用于发现的脱敏保存连接 ID、名称和分组;默认可用
connections.getAll{}连接快照
connections.getSaved{}不含凭据、密钥路径、证书路径、连接后命令或代理凭据引用的保存连接投影
connections.get{ connectionId: string }连接快照或 null
connections.getState{ connectionId: string }连接状态或 null
connections.getByNode{ nodeId: string }连接快照或 null
connections.connect{ connectionId: string }{ queued: true };使用现有保存连接和提示流程
connections.openForm{ name: string, host: string, port: number, username?: string, group?: string }{ queued: true };打开原生 SSH 表单供用户检查,不保存或连接;需要 connections.control
connections.reconnect{ nodeId: string }{ queued: true };复用现有节点运行时
connections.disconnect{ nodeId: string }{ queued: true };先打开常规级联确认,再断开 NodeRouter 拥有的子树
sessions.getTree{}节点树快照
sessions.getSummary{}脱敏会话摘要;默认可用
sessions.getActiveNodes{}活跃/已连接节点快照
sessions.getNodeState{ nodeId: string }节点状态或 null
eventLog.getEntries{ severity?: string, category?: string, limit?: number }事件日志条目

connections.openForm 需要高于 2.2.0 的宿主版本。主机来源插件还应在启用时通过 app.getApiCatalog 检查接口是否存在。接口只接受连接基本信息,拒绝凭据、密钥路径、 命令及其他字段;认证和跳板机由用户在现有表单中设置。排队中的请求不会覆盖正在编辑的 表单,执行失败会显示在插件管理器中。主机发现不拥有 SSH 连接,也不自动修改已保存连接。

工作区修改操作在完成参数和权限预检后返回 { queued: true },随后由对应产品所有者执行,并反映到后续快照或事件中。Host Tools 因为需要返回类型化远端结果,所以采用同步返回。

宿主 API能力参数返回
notifications.getSummary默认{}不含正文的计数和免打扰状态
notifications.getAllnotifications.read{}通知标题、正文、状态和作用域投影
notifications.markReadnotifications.manage{ id: number }{ queued: true }
notifications.markAllReadnotifications.manage{}{ queued: true }
notifications.setDndnotifications.manage{ enabled: boolean }{ queued: true }
notifications.remove / notifications.clearnotifications.manage{ id: number } / {}{ queued: true }
quickCommands.getMetadata默认{}不含命令正文的发现元数据
quickCommands.getAllquick_commands.read{}完整分类和命令定义
quickCommands.executequick_commands.execute{ id: string }{ queued: true };仍执行常规命令风险确认
quickCommands.upsertquick_commands.manage{ id?, name, command, category?, description?, hostPattern?, hostPatterns?, parameters?, protocols?, confirmation? }{ queued: true }
quickCommands.removequick_commands.manage{ id: string }{ queued: true }
theme.getTokens默认{}完整有效终端、界面、指标、圆角、间距和动效 token
theme.getAvailable默认{}当前、内置和自定义主题标识
theme.setActivetheme.write{ themeId: string }{ queued: true }
hostTools.getSnapshothost_tools.read{ nodeId: string }缓存的系统信息、指标、进程、Docker 和服务状态;不含完整进程参数
hostTools.getExtensions默认{}当前插件声明的监控元数据,不含命令字符串
hostTools.capturehost_tools.read{ nodeId, osType, resource, preset?, limit? }docker、services、logs、tmux、ports、filesystems、packages 或 scheduledTasks 的类型化快照
hostTools.executehost_tools.write{ nodeId, osType, resource, action, target, ...actionArgs }{ success, exitCode, truncated }

| hostTools.terminate | host_tools.destructive | { nodeId, osType, resource: 'process' \| 'tmux', action, target } | { success, exitCode, truncated } | | hostTools.runExtension | host_tools.custom.execute | { nodeId, osType, monitorId } | { monitorId, success, data, rowCount, exitCode, truncated } | | cloudSync.getSummary | 默认 | {} | 安全状态、进度、脏状态和冲突元数据 | | cloudSync.getHistory | cloud_sync.read | {} | 不含错误、远端 revision、目标、凭据或载荷的历史 | | cloudSync.check | cloud_sync.control | {} | { queued: true } | | cloudSync.upload | cloud_sync.control | { force?: boolean } | { queued: true } | | cloudSync.pullPreview | cloud_sync.control | {} | { queued: true };不会应用数据或保存未提交的面板草稿 | | cloudSync.applyPreview | cloud_sync.apply | {} | { queued: true };只应用当前已审阅预览 | | cloudSync.setAutoUpload | cloud_sync.control | { enabled: boolean, intervalMinutes?: number } | { queued: true };间隔最小为五分钟 |

快捷命令参数使用 { name, label, kind?, defaultValue?, choices?, required? };kind 可取 text 或 choice。protocols 支持 local、ssh、mosh、telnet、serial 和 tmux,confirmation 可取 inherit 或 always。模板中的 {{param.name}} 会原样插入;需要把值作为一个 POSIX Shell 参数引用时,请使用 {{param.name|sh}}。

Host Tools 不会创建第二条 SSH 连接。它通过 NodeRouter 解析当前 nodeId,复用现有连接,以产品命令构建器验证每个参数,并省略原始标准错误;采集错误会在序列化前脱敏。

插件可以通过 contributes.hostMonitors 声明静态监控命令,把监控范围扩展到内置集合之外:

{
"permissions": {
"capabilities": ["host_tools.custom.execute"]
},
"contributes": {
"hostMonitors": [{
"id": "nginx-workers",
"title": "Nginx 工作进程",
"description": "报告工作进程的 PID 和状态",
"commands": {
"linux": "ps -C nginx -o pid=,stat= | awk '{printf \"{\\\"pid\\\":%s,\\\"state\\\":\\\"%s\\\"}\\n\", $1, $2}'"
},
"output": {
"format": "jsonLines",
"maxRows": 200
},
"timeoutSeconds": 10,
"maxOutputBytes": 262144
}]
}
}

宿主会按 linux、macos、bsd 或 windows 选择命令,未命中时再使用 default。命令必须是静态文本,刻意不支持运行时参数和模板替换,因此插件不能把 runExtension 变成任意命令入口。清单命令是插件包内的明文元数据,绝不能包含密码、令牌、私钥或其他凭据。宿主无法证明 Shell 命令一定只读,所以即使监控用途只是观察,执行仍需要独立的高风险能力 host_tools.custom.execute。宿主会限制执行时长、采集字节数和解析行数,不返回标准错误,也不返回失败命令的标准输出;成功输出会按 json、jsonLines、tsv 或 textLines 解析后再交给插件。

声明监控器不会自动向内置 Host Tools 添加页面。插件负责通过自己的声明式标签页或侧边栏展示和轮询数据:用 getExtensions 发现自身监控器,需要新样本时调用 runExtension。

Host Tools 动作名称是封闭枚举:process 通过 execute 支持 stop、continue 和 renice(nice),通过 terminate 支持 terminate 和 kill;docker 支持 start、stop、restart;service 支持 start、stop、restart、reload、enable、disable;tmux 支持 renameSession、renameWindow(name)和 sendPaneCommand(command),killSession、killWindow、killPane 则需要 terminate;scheduledTask 支持 runNow(unit)、enable、disable(source)。osType 只用于选择产品内已验证的 Linux、macOS/Darwin、BSD 或 Windows 命令构建器,不会直接插入 shell 命令。

宿主 API参数返回
terminal.getMetadata{}脱敏终端元数据;默认可用
terminal.getActiveTarget{}活跃终端目标快照
terminal.getNodeBuffer{ nodeId: string }终端缓冲文本或 null
terminal.getNodeSelection{ nodeId: string }选中文本或 null
terminal.search{ nodeId: string, query: string, regex?: boolean, caseSensitive?: boolean, wholeWord?: boolean, maxResults?: number }搜索匹配
terminal.getScrollBuffer{ nodeId: string, start?: number, limit?: number }有界滚动缓冲区行
terminal.getBufferSize{ nodeId: string }缓冲区大小摘要
terminal.writeToActive{ text: string }boolean
terminal.writeToNode{ nodeId: string, text: string }boolean
terminal.clearBuffer{ nodeId: string }清理结果
terminal.openTelnet{ host: string, port?: number }{ sessionId, info }
宿主 API能力参数返回
sftp.initfilesystem.read{ nodeId: string }会话状态
sftp.listDirfilesystem.read{ nodeId: string, path: string }目录条目
sftp.statfilesystem.read{ nodeId: string, path: string }文件元数据
sftp.readFilefilesystem.read{ nodeId: string, path: string }文件内容载荷
sftp.previewfilesystem.read{ nodeId: string, path: string }预览载荷
sftp.downloadfilesystem.read{ nodeId: string, remotePath: string, localPath: string }传输结果
sftp.downloadDirfilesystem.read{ nodeId: string, remotePath: string, localPath: string }传输结果
sftp.tarProbefilesystem.read{ nodeId: string, path: string }tar 能力/探测结果
sftp.tarDownloadfilesystem.read{ nodeId: string, remotePath: string, localPath: string }传输结果
sftp.writeFilefilesystem.write{ nodeId: string, path: string, content: string }写入结果
sftp.writefilesystem.write{ nodeId: string, path: string, content: string }写入结果
sftp.uploadfilesystem.write{ nodeId: string, localPath: string, remotePath: string }传输结果
sftp.uploadDirfilesystem.write{ nodeId: string, localPath: string, remotePath: string }传输结果
sftp.tarUploadfilesystem.write{ nodeId: string, localPath: string, remotePath: string }传输结果
sftp.mkdirfilesystem.write{ nodeId: string, path: string }目录结果
sftp.deletefilesystem.write{ nodeId: string, path: string }删除结果
sftp.deleteRecursivefilesystem.write{ nodeId: string, path: string }递归删除结果
sftp.renamefilesystem.write{ nodeId: string, oldPath: string, newPath: string }重命名结果
scp.capabilitiesfilesystem.read{ nodeId: string }{ supported, recursive, restartResume: false }
scp.downloadfilesystem.read{ nodeId: string, remotePath: string, localPath: string, transferId?: string }SCP 传输结果
scp.downloadDirectoryfilesystem.read{ nodeId: string, remotePath: string, localPath: string, transferId?: string }SCP 传输结果
scp.uploadfilesystem.write{ nodeId: string, localPath: string, remotePath: string, transferId?: string }SCP 传输结果
scp.uploadDirectoryfilesystem.write{ nodeId: string, localPath: string, remotePath: string, transferId?: string }SCP 传输结果
transfers.getAll只读{}传输快照
transfers.getByNode只读{ nodeId: string }节点传输快照

SCP 是面向 POSIX 主机的兼容传输,不是浏览接口。SFTP 可用时,应继续使用 sftp.listDir、sftp.stat 和预览接口。结果会返回 protocol: "scp" 与 restartResume: false;通道或节点丢失后的重试会重新传输整个对象,不会从字节偏移继续。

宿主 API能力参数返回
forward.list只读{ nodeId?: string }活跃转发规则
forward.listSavedForwards只读{}保存转发规则
forward.exportSavedForwardsSnapshot只读{}保存转发同步快照
forward.applySavedForwardsSnapshotnetwork.forward{ snapshot: object, strategy?: string }应用结果
forward.createnetwork.forward{ nodeId: string, type: 'local' | 'remote' | 'dynamic', localPort?: number, remoteHost?: string, remotePort?: number }创建的规则
forward.stopnetwork.forward{ id: string }停止结果
forward.deletenetwork.forward{ id: string }删除结果
forward.restartnetwork.forward{ id: string }重启结果
forward.updatenetwork.forward{ id: string, ...changes }更新结果
forward.stopAllnetwork.forward{ nodeId?: string }全部停止结果
forward.getStats只读{}转发统计
宿主 API参数返回
storage.get{ key: string }JSON 值或 null
storage.set{ key: string, value: unknown }单向写入
storage.remove{ key: string }单向删除
secrets.get{ key: string }凭据字符串或 null;需要 credentials.raw.read
secrets.getMany{ keys: string[] }key 到凭据/null 的映射;需要 credentials.raw.read
secrets.set{ key: string, value: string }空值表示删除;需要 credentials.manage
secrets.has{ key: string }boolean;需要 credentials.manage
secrets.delete{ key: string }删除结果;需要 credentials.manage
sync.listSavedConnections{}保存连接快照
sync.refreshSavedConnections{}刷新后的保存连接快照
sync.exportSavedConnectionsSnapshot{}保存连接同步快照
sync.applySavedConnectionsSnapshot{ snapshot: object, conflictStrategy?: 'rename' | 'skip' | 'replace' | 'merge' }应用结果
sync.getLocalSyncMetadata{}revision 元数据
sync.preflightExport{ connectionIds?: string[], embedKeys?: boolean, includeManagedKeys?: boolean }导出预检查结果。插件驱动的同步默认不包含托管密钥。
sync.exportOxide{ connectionIds?: string[], password: string, embedKeys?: boolean, includeManagedKeys?: boolean, includeManagedKeyPassphrases?: boolean, includeAppSettings?: boolean, selectedAppSettingsSections?: string[], includePluginSettings?: boolean, selectedPluginIds?: string[], progressRegistrationId?: string }.oxide 字节/元数据结果。插件驱动的同步默认不包含托管密钥。
sync.validateOxide{ fileData: number[] }.oxide 元数据
sync.previewImport{ fileData: number[], password: string, conflictStrategy?: string, progressRegistrationId?: string }导入预览
sync.importOxide{ fileData: number[], password: string, conflictStrategy?: string, progressRegistrationId?: string, selectedNames?: string[], selectedForwardIds?: string[], importForwards?: boolean, importPortableSecrets?: boolean, importAppSettings?: boolean, selectedAppSettingsSections?: string[], importPluginSettings?: boolean, selectedPluginIds?: string[], importQuickCommands?: boolean }导入结果
宿主 API参数返回
ide.isOpen{}boolean
ide.getSummary{}脱敏 IDE 状态摘要;默认可用
ide.getProject{}项目快照或 null
ide.getOpenFiles{}打开文件快照
ide.getActiveFile{}活跃文件快照或 null
ide.openFile{ path: string, nodeId?: string }{ queued: true }
ide.replaceActiveText{ text: string, nodeId?: string }{ queued: true }
ide.insertActiveText{ text: string, nodeId?: string }{ queued: true }
ide.saveActive{ nodeId?: string }{ queued: true };保留远端冲突检查
ide.closeFile{ path: string, nodeId?: string }{ queued: true };保留脏缓冲确认
ide.refreshProject{ nodeId?: string }{ queued: true }
ai.getConversations{}已脱敏对话摘要
ai.getCatalog{}脱敏供应商与模型目录;默认可用
ai.getMessages{ conversationId: string }已脱敏消息
ai.getActiveProvider{}活跃供应商摘要或 null
ai.getAvailableModels{}模型名称
ai.createConversation{ title?: string }{ queued: true }
ai.selectConversation{ conversationId: string }{ queued: true }
ai.sendMessage{ content: string }{ queued: true };构造模型上下文前会脱敏类似凭据的文本
ai.cancelGeneration{}{ queued: true }
ai.deleteConversation{ conversationId: string }{ queued: true }
ai.clearConversations{}{ queued: true }
profiler.getMetrics{ nodeId: string }指标快照或 null;可用时,systemInfo 包含远端系统名称、版本、架构、开机时间毫秒值和运行秒数
profiler.getHistory{ nodeId: string, limit?: number }指标历史
profiler.isRunning{ nodeId: string }boolean

通过 event-subscription 注册订阅,可以直接提供 event,也可以提供 Tauri 风格的 namespace + method。

Namespace + method事件 key所需能力
app.onThemeChangeapp.themeChanged无
app.onSettingsChangeapp.settingsChangedapp.settings.read
i18n.onLanguageChangei18n.languageChanged无
settings.onChangesettings.changed无
ui.onLayoutChangeui.layoutChanged无
sessions.onTreeChangesessions.treeChangedsessions.read
sessions.onNodeStateChangesessions.nodeStateChanged无
eventLog.onEntryeventLog.entrysessions.read
forward.onSavedForwardsChangeforward.savedForwardsChangednetwork.forward.read
transfers.onProgresstransfers.progresstransfers.read
transfers.onCompletetransfers.completetransfers.read
transfers.onErrortransfers.errortransfers.read
profiler.onMetricsprofiler.metrics无
ide.onFileOpenide.fileOpenide.read
ide.onFileCloseide.fileCloseide.read
ide.onActiveFileChangeide.activeFileChangedide.read
ai.onMessageai.message无(仅元数据,不含消息正文)
events.onConnectlifecycle.onConnect无
events.onDisconnectlifecycle.onDisconnect无
events.onLinkDownlifecycle.onLinkDown无
events.onReconnectlifecycle.onReconnect无

终端输入拦截器同时需要 terminal.content.read 和 terminal.write;终端输出处理器需要 terminal.content.read。

自定义插件事件走 events.on / events.emit 路径,并按插件 id 作用域隔离,避免插件抢占任意全局事件名。

先从插件管理器开始:

  • 检查插件是 ready、disabled、legacy-js、error 还是 auto-disabled。
  • 调试运行时代码前,先检查清单校验错误。
  • 进程诊断文本写 stderr。
  • stdout 严格保持 JSON Lines 协议。
  • 开发时一次只注册一个贡献。
  • 确认 registrationId 在插件内稳定且唯一。
  • 确认每个宿主调用都已声明并被允许。
  • 使用 oxideterm plugins list --json 检查无界面状态。
  • 使用 oxideterm plugins settings export --json 检查插件设置。

如果进程插件已激活但界面没有出现,检查两侧:

  • contributes.tabs 或 contributes.sidebarPanels 声明了页面 id。
  • 运行时注册使用相同的 tabId 或 panelId。
  • 界面结构的 kind 是 form。
  • 界面结构至少包含一个 section 或顶层控件。
  • 需要 id 的控件已经设置 id。

对于独立活动栏动作,应检查 contributes.activityBarItems、运行时 itemId、ui.write 能力和插件的 dispatchCommand 处理器,而不是查找声明式界面结构。

不要直接复制 Tauri 插件的 main.js。

Tauri 概念Native 替代
main.js ESM activate(ctx)使用 JSON 协议的进程/WASM 运行时
React 标签页/侧边栏组件声明式 Native UI 结构
CSS 文件宿主渲染控件和主题
window.__OXIDE__宿主 API 调用和协议帧
直接 JS 事件总线event-subscription 注册和 sendEvent 请求
Tauri 命令导入清单声明的宿主 API 调用
浏览器 asset URL未来宿主持有的资源句柄

尽量保留公共插件意图、清单 id、设置 id 和工具元数据。把浏览器实现细节替换为 Native 进程/WASM 协议行为。