manifest schema 参考

manifest schema 参考

plugin.json 的完整字段参考（与 SDK 的 PluginManifest 类型对齐）。 入门说明见 plugin.json 规范。

PluginManifest 字段

字段	类型	必填	缺省	说明
id	string	✅	-	全局唯一，kebab-case（[a-z0-9-]，≤ 64 字符）；同时是安装目录名；plugin.json 的 id 必须与目录名一致（防目录伪造 / 串号）
name	string	✅	-	展示名（非空）
version	string	✅	-	版本号（非空，建议 semver）
apiVersion	number	-	1	声明的插件 API 版本；> SUPPORTED_API_VERSION（当前 3）拒绝加载
description	string	-	-	一句话描述
author	string	-	-	作者署名
minAppVersion	string	-	-	宿主版本下限（semver 比较）；不满足则拒绝加载（仅外部插件校验）
main	string	-	"main.js"	入口文件名，相对插件目录。校验：非空、不能含 /、\、..、不能以 . 开头（见「入口解析」）
capabilities	string[]	-	[]	能力声明；process / sidecar 任一进入 L1（sidecar 隐含 process）
dependencies	string[]	-	[]	前置依赖插件 id（kebab-case）；宿主按拓扑序加载，不可达则跳过
optionalDependencies	string[]	-	[]	可选依赖插件 id；只做尽力排序，缺失不阻止加载
sidecar	object	-	-	原生二进制声明（见下）
contributes	object	-	-	贡献点声明摘要（见下）
official	boolean	-	-	不要写：安装时一律剥离，任何包自带该字段无效

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	Record<string, string>	键为 <os>-<arch>（如 darwin-aarch64 / darwin-x86_64 / windows-x86_64），值为插件包内相对路径；非空
args	string[]	可选，固定启动参数

当前平台无对应二进制 → 插件可加载，ctx.sidecar.call 返回明确错误。

contributes

声明式摘要（设置页展示 + 信任提示用；真正注册在 activate() 里完成）：

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

入口解析

宿主读取入口脚本的规则（Rust 侧 bundle_path）：

• 取 plugin.json 的 main 字段，缺省 "main.js"；
• 校验：非空、不含 / 或 \、不含 ..、不以 . 开头——违规返回 「invalid bundle entry」；
• main.css 是固定的样式约定文件名（存在则随主脚本一并返回注入）。

校验规则（validateManifest）

SDK 的 validateManifest(raw) 逐条收集中文错误；ok: true 时返回 规范化后的 manifest（apiVersion 缺省已按 1 填入）：

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

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

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

apiVersion 规则速查

声明值	行为
缺省（视为 1）	正常加载（向后兼容）
≤ 3	正常加载
> 3	拒绝加载；toast「插件 X 需要更新的 Termii 版本」，其余插件不受影响

详见 apiVersion 契约。