原生插件开发
本文档介绍 OxideTerm Native 插件模型。它和 Tauri/Web 插件模型不同:Native 插件不运行 React 组件,不注入 CSS,也不会通过 WebView 执行 main.js。Native 插件通过 plugin.json 被发现,然后要么只提供清单声明的元数据,要么通过宿主拥有的进程/WASM 运行时桥接运行。
专用包还支持 language、acp、remote-desktop、terminal-transport 和 helper 运行时。RDP、VNC 引擎由插件市场分发,保存配置和查看器由宿主管理。进程连接插件可提供独立连接实例和持续更新的工作台。
- 写出一个可运行插件
- 运行时通信过程
- 在插件代码里调用宿主
- 界面与事件写法
- 常见失败检查
- Native 插件模型
- Native 插件与 Tauri 插件的区别
- 插件目录
- 最小清单插件
- 背景素材包
- 编辑器语言插件
- 进程运行时插件
- 协议帧
- 运行时注册
- 插件连接类型
- 声明式 Native 界面
- 宿主 API 调用
- 权限与能力
- 设置、存储与凭据
- 终端、SFTP、转发、IDE 与 AI
- 打包与安装
- 接口参考
- 宿主 API 参考
- 事件参考
- 调试
- 迁移说明
写出一个可运行插件
Section titled “写出一个可运行插件”先从进程插件开始。进程运行时最容易调试,因为所有消息都是 stdin/stdout 上的一行一个 JSON 对象。
在用户插件目录里创建这个目录:
hello-native/ plugin.json bin/ hello.js进程入口必须是插件目录内的真实可执行文件。macOS/Linux 上需要给脚本加可执行权限:
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 监控。
运行时通信过程
Section titled “运行时通信过程”进程运行时只有一条按行分隔的通信通道。
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 文本。
在插件代码里调用宿主
Section titled “在插件代码里调用宿主”宿主调用不是全局 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 }}不要记录或回显密码、凭据值、终端缓冲区、连接配置、原始导入/导出载荷。
界面与事件写法
Section titled “界面与事件写法”注册标签页视图:
{ "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 作用域隔离,因此一个插件不能抢占任意全局事件名。
常见失败检查
Section titled “常见失败检查”如果插件没有激活:
- 检查
runtime.entry是否指向插件目录内存在的可执行文件。 - 检查进程是否只向 stdout 输出 JSON Lines。
- 检查激活响应是否同时包含 envelope
requestId和 payloadrequestId。 - 检查
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 或端口转发,确认具备对应能力。
- 对凭据和密码,确认插件没有通过日志或界面文本发送敏感值。
Native 插件模型
Section titled “Native 插件模型”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 传输句柄。原生进程插件拥有其用户的操作系统权限,宿主接口检查不会隔离可执行程序自身的文件与网络访问。
Native 插件与 Tauri 插件的区别
Section titled “Native 插件与 Tauri 插件的区别”| 区域 | Tauri/Web 插件 | Native 插件 |
|---|---|---|
| 运行时 | 通过动态导入加载 ESM main.js | 通用扩展使用 process、wasm、manifest-only,专用运行时见上文 |
| 界面 | React 组件和 CSS | GPUI 渲染的声明式 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 可以在无界面流程中启用、禁用和检查插件状态,但交互式安装、更新和卸载由桌面插件管理器负责。
最小清单插件
Section titled “最小清单插件”清单插件适合静态元数据、声明式设置、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 目录,便携版跟随自己的配置目录。
安装不改变浅色或深色外观当前选择的背景;同版本重装复用已有副本,新版本添加独立素材。
卸载素材包会保留已导入的文件,用户可以在外观素材库中删除。
编辑器语言插件
Section titled “编辑器语言插件”主程序保留 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 且包含语言加载能力的主程序。
进程运行时插件
Section titled “进程运行时插件”进程插件是插件目录内的可执行文件。宿主通过 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。释放注册是幂等的,并由宿主执行。
插件连接类型
Section titled “插件连接类型”进程插件通过 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":"..."}。此命令必须幂等,对未知实例和已取消的打开请求也应成功返回,
回复前释放该实例的网络连接、订阅和后台任务。切换页面不会断开,移动或拆分终端也不改变其所有者。
生命周期命令须在五秒内回复;传输超时或清理失败时,宿主停止整个提供方进程及其终端消费者。
停用、更新插件同样会停止运行实例,但保留配置。迟到的结果和界面更新不能重新打开已关闭的实例。
声明式 Native 界面
Section titled “声明式 Native 界面”持续更新与消息工作台
Section titled “持续更新与消息工作台”进程插件完成激活后,可以主动向 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。
宿主 API 调用
Section titled “宿主 API 调用”原生文本处理区
Section titled “原生文本处理区”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 }。宿主在点击时捕获选区,随后打开该插件声明的文本处理区。
之后切换窗格或终端输出变化都不会改变已捕获的输入;@ 菜单文案使用目标标签页的翻译。
文件预览插件
Section titled “文件预览插件”独立进程插件可以在现有文件预览窗口中提供分页文档预览,不需要注册标签页或侧边栏:
{ "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 | 插件作用域凭据存储 |
ui | toast、确认对话框、布局和进度 |
此表描述当前已实现的命名空间。调用默认可用的 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 等语义能力。这些声明用于描述工具行为,服务于宿主和模型侧展示;它们不会绕过运行时权限检查。
设置、存储与凭据
Section titled “设置、存储与凭据”按数据性质选择最小边界:
| 数据 | 边界 | 说明 |
|---|---|---|
| 用户可见插件选项 | contributes.settings 和 settings.* | 类型化值;不是凭据时可安全导入导出 |
| 插件内部缓存 | storage.* | 插件作用域 JSON KV,有大小限制 |
| token、密码、密钥 | secrets.* | 系统钥匙串支持的插件作用域凭据存储;读取原文需要 credentials.raw.read,set/has/delete 需要 credentials.manage |
| 跨机器插件偏好 | 插件设置导入导出或 .oxide | 不要包含原始凭据,除非加密便携流程明确支持 |
不要把凭据写进插件 id、名称、标签、日志、AI 提示词、事件载荷或支持包。
终端、SFTP、转发、IDE 与 AI
Section titled “终端、SFTP、转发、IDE 与 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。 - 除非入口本身可移植,否则运行时二进制应按平台分发。
插件市场保留每个发布版本的宿主范围和各平台安装包,选择当前可用的最高版本。 更高版本不兼容时单独说明要求,保留当前插件。安装和启动都会检查清单中的兼容范围, 应用升级和降级后同样生效。不兼容插件保留文件与设置,但停止加载。 启动激活前会刷新官方目录并缓存,离线时读取缓存;有记录的兼容性纠错优先于包内声明, 但不会改写安装包。未收录且未声明范围的旧安装包仍允许使用;旧版主应用不会因此自动获得兼容检查。 目录格式和发布流程见发布指南。
开发时:
- 将插件目录复制到
<config-dir>/plugins/。 - 打开桌面插件管理器。
- 启用或重新加载插件。
- 检查状态、错误和权限。
- 只在无界面状态/设置检查中使用 CLI:
oxideterm plugins list --jsonoxideterm plugins enable com.example.native-dashboard --dry-run --jsonoxideterm plugins settings export --jsoninterface 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;}出站消息接口
Section titled “出站消息接口”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;}| 注册类型 | 必需元数据 | 可选元数据 |
|---|---|---|
command | id 或 command、label | icon、shortcut、section |
keybinding | keybinding 或 key、command、label | when |
context-menu | target、items | 目标相关菜单项元数据 |
status-bar | text | alignment、icon、tooltip |
tab | tabId、schema | schema 内的 title |
sidebar-panel | panelId、schema | position、schema 内的 title |
activity-bar-item | itemId | 无;标题、图标、位置和命令均来自清单 |
event-subscription | event 或 namespace + method | 部分事件族支持 nodeId 过滤 |
terminal-input-interceptor | command 或 id | 无 |
terminal-output-processor | command 或 id | 无 |
terminal-shortcut | command 或 id | 使用清单里声明的快捷键 |
progress | id 或生成的 id | title、message |
声明式界面接口
Section titled “声明式界面接口”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 参考
Section titled “宿主 API 参考”所有宿主 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_stats | SSH 连接池统计 |
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_init | sftp.init 适配器 |
node_sftp_list_dir | sftp.listDir 适配器 |
node_sftp_stat | sftp.stat 适配器 |
node_sftp_preview | sftp.preview 适配器 |
node_sftp_write | sftp.write 适配器 |
node_sftp_download | sftp.download 适配器 |
node_sftp_upload | sftp.upload 适配器 |
node_sftp_mkdir | sftp.mkdir 适配器 |
node_sftp_delete | sftp.delete 适配器 |
node_sftp_delete_recursive | sftp.deleteRecursive 适配器 |
node_sftp_rename | sftp.rename 适配器 |
node_sftp_download_dir | sftp.downloadDir 适配器 |
node_sftp_upload_dir | sftp.uploadDir 适配器 |
node_sftp_tar_probe | sftp.tarProbe 适配器 |
node_sftp_tar_upload | sftp.tarUpload 适配器 |
node_sftp_tar_download | sftp.tarDownload 适配器 |
node_scp_probe | scp.capabilities 适配器 |
node_scp_download | scp.download 适配器 |
node_scp_upload | scp.upload 适配器 |
node_scp_download_dir | scp.downloadDirectory 适配器 |
node_scp_upload_dir | scp.uploadDirectory 适配器 |
list_port_forwards | forward.list 适配器 |
create_port_forward | forward.create 适配器 |
stop_port_forward | forward.stop 适配器 |
delete_port_forward | forward.delete 适配器 |
restart_port_forward | forward.restart 适配器 |
update_port_forward | forward.update 适配器 |
get_port_forward_stats | forward.getStats 适配器 |
stop_all_forwards | forward.stopAll 适配器 |
plugin_http_request | HTTP/HTTPS 请求适配器,正文上限 10 MiB |
App、布局、设置、i18n
Section titled “App、布局、设置、i18n”| 宿主 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 } | 事件日志条目 |
产品数据与控制
Section titled “产品数据与控制”connections.openForm 需要高于 2.2.0 的宿主版本。主机来源插件还应在启用时通过
app.getApiCatalog 检查接口是否存在。接口只接受连接基本信息,拒绝凭据、密钥路径、
命令及其他字段;认证和跳板机由用户在现有表单中设置。排队中的请求不会覆盖正在编辑的
表单,执行失败会显示在插件管理器中。主机发现不拥有 SSH 连接,也不自动修改已保存连接。
工作区修改操作在完成参数和权限预检后返回 { queued: true },随后由对应产品所有者执行,并反映到后续快照或事件中。Host Tools 因为需要返回类型化远端结果,所以采用同步返回。
| 宿主 API | 能力 | 参数 | 返回 |
|---|---|---|---|
notifications.getSummary | 默认 | {} | 不含正文的计数和免打扰状态 |
notifications.getAll | notifications.read | {} | 通知标题、正文、状态和作用域投影 |
notifications.markRead | notifications.manage | { id: number } | { queued: true } |
notifications.markAllRead | notifications.manage | {} | { queued: true } |
notifications.setDnd | notifications.manage | { enabled: boolean } | { queued: true } |
notifications.remove / notifications.clear | notifications.manage | { id: number } / {} | { queued: true } |
quickCommands.getMetadata | 默认 | {} | 不含命令正文的发现元数据 |
quickCommands.getAll | quick_commands.read | {} | 完整分类和命令定义 |
quickCommands.execute | quick_commands.execute | { id: string } | { queued: true };仍执行常规命令风险确认 |
quickCommands.upsert | quick_commands.manage | { id?, name, command, category?, description?, hostPattern?, hostPatterns?, parameters?, protocols?, confirmation? } | { queued: true } |
quickCommands.remove | quick_commands.manage | { id: string } | { queued: true } |
theme.getTokens | 默认 | {} | 完整有效终端、界面、指标、圆角、间距和动效 token |
theme.getAvailable | 默认 | {} | 当前、内置和自定义主题标识 |
theme.setActive | theme.write | { themeId: string } | { queued: true } |
hostTools.getSnapshot | host_tools.read | { nodeId: string } | 缓存的系统信息、指标、进程、Docker 和服务状态;不含完整进程参数 |
hostTools.getExtensions | 默认 | {} | 当前插件声明的监控元数据,不含命令字符串 |
hostTools.capture | host_tools.read | { nodeId, osType, resource, preset?, limit? } | docker、services、logs、tmux、ports、filesystems、packages 或 scheduledTasks 的类型化快照 |
hostTools.execute | host_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 } |
SFTP 与传输
Section titled “SFTP 与传输”| 宿主 API | 能力 | 参数 | 返回 |
|---|---|---|---|
sftp.init | filesystem.read | { nodeId: string } | 会话状态 |
sftp.listDir | filesystem.read | { nodeId: string, path: string } | 目录条目 |
sftp.stat | filesystem.read | { nodeId: string, path: string } | 文件元数据 |
sftp.readFile | filesystem.read | { nodeId: string, path: string } | 文件内容载荷 |
sftp.preview | filesystem.read | { nodeId: string, path: string } | 预览载荷 |
sftp.download | filesystem.read | { nodeId: string, remotePath: string, localPath: string } | 传输结果 |
sftp.downloadDir | filesystem.read | { nodeId: string, remotePath: string, localPath: string } | 传输结果 |
sftp.tarProbe | filesystem.read | { nodeId: string, path: string } | tar 能力/探测结果 |
sftp.tarDownload | filesystem.read | { nodeId: string, remotePath: string, localPath: string } | 传输结果 |
sftp.writeFile | filesystem.write | { nodeId: string, path: string, content: string } | 写入结果 |
sftp.write | filesystem.write | { nodeId: string, path: string, content: string } | 写入结果 |
sftp.upload | filesystem.write | { nodeId: string, localPath: string, remotePath: string } | 传输结果 |
sftp.uploadDir | filesystem.write | { nodeId: string, localPath: string, remotePath: string } | 传输结果 |
sftp.tarUpload | filesystem.write | { nodeId: string, localPath: string, remotePath: string } | 传输结果 |
sftp.mkdir | filesystem.write | { nodeId: string, path: string } | 目录结果 |
sftp.delete | filesystem.write | { nodeId: string, path: string } | 删除结果 |
sftp.deleteRecursive | filesystem.write | { nodeId: string, path: string } | 递归删除结果 |
sftp.rename | filesystem.write | { nodeId: string, oldPath: string, newPath: string } | 重命名结果 |
scp.capabilities | filesystem.read | { nodeId: string } | { supported, recursive, restartResume: false } |
scp.download | filesystem.read | { nodeId: string, remotePath: string, localPath: string, transferId?: string } | SCP 传输结果 |
scp.downloadDirectory | filesystem.read | { nodeId: string, remotePath: string, localPath: string, transferId?: string } | SCP 传输结果 |
scp.upload | filesystem.write | { nodeId: string, localPath: string, remotePath: string, transferId?: string } | SCP 传输结果 |
scp.uploadDirectory | filesystem.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.applySavedForwardsSnapshot | network.forward | { snapshot: object, strategy?: string } | 应用结果 |
forward.create | network.forward | { nodeId: string, type: 'local' | 'remote' | 'dynamic', localPort?: number, remoteHost?: string, remotePort?: number } | 创建的规则 |
forward.stop | network.forward | { id: string } | 停止结果 |
forward.delete | network.forward | { id: string } | 删除结果 |
forward.restart | network.forward | { id: string } | 重启结果 |
forward.update | network.forward | { id: string, ...changes } | 更新结果 |
forward.stopAll | network.forward | { nodeId?: string } | 全部停止结果 |
forward.getStats | 只读 | {} | 转发统计 |
同步、存储、凭据
Section titled “同步、存储、凭据”| 宿主 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 } | 导入结果 |
IDE、AI、Profiler
Section titled “IDE、AI、Profiler”| 宿主 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.onThemeChange | app.themeChanged | 无 |
app.onSettingsChange | app.settingsChanged | app.settings.read |
i18n.onLanguageChange | i18n.languageChanged | 无 |
settings.onChange | settings.changed | 无 |
ui.onLayoutChange | ui.layoutChanged | 无 |
sessions.onTreeChange | sessions.treeChanged | sessions.read |
sessions.onNodeStateChange | sessions.nodeStateChanged | 无 |
eventLog.onEntry | eventLog.entry | sessions.read |
forward.onSavedForwardsChange | forward.savedForwardsChanged | network.forward.read |
transfers.onProgress | transfers.progress | transfers.read |
transfers.onComplete | transfers.complete | transfers.read |
transfers.onError | transfers.error | transfers.read |
profiler.onMetrics | profiler.metrics | 无 |
ide.onFileOpen | ide.fileOpen | ide.read |
ide.onFileClose | ide.fileClose | ide.read |
ide.onActiveFileChange | ide.activeFileChanged | ide.read |
ai.onMessage | ai.message | 无(仅元数据,不含消息正文) |
events.onConnect | lifecycle.onConnect | 无 |
events.onDisconnect | lifecycle.onDisconnect | 无 |
events.onLinkDown | lifecycle.onLinkDown | 无 |
events.onReconnect | lifecycle.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 协议行为。