Manifest 规范

插件的唯一身份证明。宿主用 deny_unknown_fields 解析它 —— 写错的字段名不会警告，只会让插件加载失败。

12 个顶层字段Command：cmds / code / explain / overlayui：height / width

一份完整的 manifest

manifest.json

{
  "$schema": "https://tabtab.dev/schema/plugin-manifest-1.json",
  "id": "dev.tabtab.plugin.color",
  "name": "颜色取色器",
  "version": "1.0.0",
  "minHostVersion": "0.1.0",
  "description": "在屏幕上取任意一点的颜色。",
  "icon": "icon.svg",
  "main": "index.html",
  "commands": [
    {
      "code": "pick",
      "explain": "在屏幕上取色",
      "cmds": ["取色", "颜色", "吸色", "color", "qs"],
      "overlay": true
    },
    { "code": "palette", "explain": "查看色板", "cmds": ["色板", "palette"] }
  ],
  "permissions": ["screen:capture", "clipboard:write", "storage"],
  "ui": { "width": 680, "height": 560 }
}

字段

字段	类型	说明
`id`	`string`	反向域名，全局唯一。必须与索引条目、包内 Manifest 三处一致。填写错误的后果是「索引中不存在该插件」，而非「插件无法安装」。
`name`	`string`	展示名。用户于市场卡片与已安装列表中看到的即是此名。
`version`	`semver`	语义化版本号。非法版本会被索引校验直接拒绝，用户侧表现为「市场无法打开」，而非「该插件版本有误」。
`icon`	`string`	包内相对路径，通常是 icon.svg。索引里的 icon 是构建时从这个文件抽出来的绝对 https 地址。
`main`	`string`	入口 HTML。脚手架产出为 index.html。
`commands`	`Command[]`	这个插件往搜索结果里注入的条目。空数组是合法的（只能从已安装列表手动唤起）。
`description` 可选	`string`	一句话说明。市场卡片与插件详情页都直接用它。
`minHostVersion` 可选	`semver`	低于这个版本的宿主会拒绝安装并提示升级。宁可在装之前拒绝，也不要装出一个点不动的插件。
`permissions` 可选	`string[]`	声明权限。省略等于不声明 —— 空数组与不写效果相同。
`runtime` 可选	`object`	{ "kind": "webview" \| "process" }。声明 process 的包仅可本地导入，公开市场不予收录。
`ui` 可选	`object`	面板默认尺寸 { width, height }。用户可于设置中修改，改动将覆盖此值。

必填字段：id、name、version、icon、main、commands。其余为可选：$schema、description、minHostVersion、permissions、runtime、ui。

Command

字段	类型	说明
`code`	`string`	指令名，唤起面板时用它定位。同一个插件内必须唯一。
`explain`	`string`	一句话说明，显示在搜索结果副标题与文档页。
`cmds`	`string[]`	触发词。用户输入任意一个即可命中。中英文混排是常态 —— 用户不会为了一个插件切换输入法。
`overlay`	`boolean`	true 表示这条指令会接管屏幕（取色、框选）。宿主会为它准备覆盖层，并把它在结果里标出来。

validate plugin_id

id 会参与拼磁盘路径（插件目录就是 id 的最后一段），因此必须是反向域名，且每一段都不能是 . ..或空段。非法 id 会在安装入口就被拒 —— 这道检查早于任何解压动作。

几条会被构建期检查的约定

这些不是文档里的建议，是插件构建流程里的硬断言：权限缺失、权限多声明、禁声明清单、产物里找不到入口 —— 任何一条命中，构建会直接失败，而不是等你装到别人的机器上才发现。

权限缺失 —— 该插件用到的权限必须都声明，否则运行时才回 PERMISSION_DENIED。
权限多声明 —— 用户会在授权弹窗里多看一条他并不需要的能力。
禁声明清单 —— 例如剪贴板面板声明 screen:capture，几乎没有可能是有意的。
产物里找不到 main 指向的入口 —— 插件无法加载。