plugin.json 规范

plugin.json 规范

插件清单 plugin.json 是插件的身份证：宿主加载时先读它做校验，再读取 入口脚本。插件目录里至少要有它和 main.js 两个文件。

完整示例

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "description": "做什么用的一句话。",
  "author": "you",
  "minAppVersion": "0.3.6",
  "apiVersion": 3,
  "main": "main.js",
  "capabilities": ["process"],
  "dependencies": ["termii-snippets"],
  "optionalDependencies": ["termii-tunnels"],
  "sidecar": {
    "binaries": {
      "darwin-aarch64": "bin/sysinfo-darwin-aarch64",
      "darwin-x86_64": "bin/sysinfo-darwin-x86_64",
      "windows-x86_64": "bin/sysinfo-windows-x86_64.exe"
    },
    "args": ["--daemon"]
  },
  "contributes": {
    "views": [{ "id": "my-plugin.panel", "labelKey": "panelTitle" }],
    "commands": [{ "id": "my-plugin.sayHi", "title": "Say Hi" }],
    "settingsSections": [{ "id": "my-plugin.settings", "labelKey": "settingsTitle" }],
    "themes": [{ "id": "my-plugin.night", "label": "Night" }],
    "trayItems": [{ "id": "my-plugin.quick", "label": "Quick Action" }]
  }
}

字段总览

字段	类型	必填	说明
id	string	✅	全局唯一，kebab-case（[a-z0-9-]，≤ 64 字符），同时是安装目录名
name	string	✅	展示名（非空）
version	string	✅	版本号（非空，建议 semver）
apiVersion	number	缺省 1	插件 API 版本；大于宿主支持版本（当前 3）会被拒绝加载，见 apiVersion 契约
description	string	-	一句话描述
author	string	-	作者署名
minAppVersion	string	-	宿主版本下限（semver 比较），不满足则拒绝加载
main	string	缺省 main.js	入口文件名，相对插件目录。校验较严：必须非空，不能含 /、\、..，不能以 . 开头
capabilities	string[]	缺省 []	能力声明，见下
dependencies	string[]	-	前置依赖插件 id 列表，见 插件服务总线与依赖
optionalDependencies	string[]	-	可选依赖插件 id 列表，缺失时插件照常加载
sidecar	object	-	原生二进制声明，见下
contributes	object	-	贡献点声明摘要，见下

official 字段不要写：它在安装时一律被宿主剥离，任何包自带该字段 都无效（防止伪造官方身份）。官方标记只由市场目录条目标注，见 官方插件开发与发布。

能力声明（capabilities）

插件需要超出纯 UI 的能力时，必须在 capabilities 中声明：

能力	含义	层级
（缺省）	纯 JS + Host API 白名单	L0
process	宿主托管进程的执行（ctx.process.spawn / hosts.execStream）	L1
sidecar	调用随包分发的原生二进制（隐含 process）	L1

• 声明 process 或 sidecar 任一 → 插件进入 L1：信任弹窗逐项列出能力 并警示「将以你的用户权限执行任意命令」。
• 未获授予时相关 API 明确报错，插件其余功能（纯 UI 贡献点）仍可用。
• 官方插件与第三方完全等同，没有免确认特权。

sidecar 声明

{
  "sidecar": {
    "binaries": {
      "darwin-aarch64": "bin/sysinfo-darwin-aarch64",
      "darwin-x86_64": "bin/sysinfo-darwin-x86_64",
      "windows-x86_64": "bin/sysinfo-windows-x86_64.exe"
    },
    "args": ["--daemon"]
  }
}

• binaries 键为 <os>-<arch>（如 darwin-aarch64 / darwin-x86_64 / windows-x86_64 / linux-x86_64），值为插件包内相对路径；同一二进制 可声明多个平台。
• args 可选：启动时附加的固定参数。
• 当前平台无对应二进制时插件可加载，但 ctx.sidecar.call 返回明确 错误。协议与生命周期见 流式进程与 sidecar。

贡献点声明（contributes）

contributes 是声明式摘要：展示在设置页与信任提示里，让用户在启用前 知道插件会带来什么。真正的注册发生在 activate() 里通过 ctx.ui.register* 完成，两者应保持一致。

键	元素形状	说明
views	{ id, labelKey? }	侧栏视图摘要
commands	{ id, title }	命令摘要
settingsSections	{ id, labelKey? }	设置分区摘要
themes	{ id, label }	主题摘要
trayItems	{ id, label }	托盘项摘要

• 所有贡献点 id 必须以 <pluginId>. 开头（宿主对未加前缀的 id 会自动补全， 但显式书写是推荐做法，见 贡献点）。
• labelKey 对应运行时 ctx.i18n.addBundle 注入的文案键，默认在 views / settings 命名空间解析（见 界面反馈与文案）。

依赖声明

{
  "dependencies": ["termii-snippets"],
  "optionalDependencies": ["termii-tunnels"]
}

• dependencies（前置依赖）：宿主按依赖拓扑序加载，保证依赖先于使用方 激活。依赖未安装 / 未启用 / 未信任 / 加载失败 / 存在循环 → 本插件跳过 加载，原因显示在「设置 → 插件」与加载日志中。
• optionalDependencies（可选依赖）：宿主只做尽力排序，缺失时插件照常 加载，由插件运行时用 ctx.plugins.isActive 自检并隐藏 / 禁用相关功能。

完整语义见 插件服务总线与依赖。

校验

SDK 提供零依赖的 validateManifest，可在安装 / 加载前校验清单。错误为 中文、逐条收集；ok: true 时返回规范化后的 manifest（apiVersion 缺省已按 1 填入）：

import { validateManifest } from "@termii/plugin-sdk";

const result = validateManifest(raw);
if (result.ok) {
  // result.manifest：可直接使用的 PluginManifest
} else {
  console.error(result.errors.join("\n"));
}

校验规则摘要

字段	规则
id	必填，匹配 /^[a-z0-9-]+$/，≤ 64 字符
name / version	必填非空字符串
description / author / minAppVersion	可选；提供时必须是字符串
apiVersion	可选数字（有限数）；缺省按 1 处理并写入返回的 manifest
capabilities	可选字符串数组
dependencies	可选 kebab-case 插件 id 的字符串数组
sidecar	binaries 非空对象、键形如 <os>-<arch>、值为非空字符串；args 可选，须为 string[]
contributes	浅校验：views / commands / settingsSections / themes / trayItems 为对象数组（元素级字段由宿主 loader 校验）
official	不校验、不入输出（见上）

完整字段参考见 manifest schema 参考。