manifest.json

飞块在加载插件时读取 manifest.json。这个文件放在插件根目录中，使用 JSON 格式。

#示例

下面的清单提供一个问候动作。你可以从它开始，再按需要向 contributes 添加功能。

{
  "apiVersion": 1,
  "id": "example.hello",
  "name": "Hello 飞块",
  "version": "1.0.0",
  "description": "Hello 飞块教学示例",
  "hostPlatforms": [
    "windows",
    "macos",
    "linux"
  ],
  "main": "index.js",
  "permissions": [],
  "contributes": {
    "actions": [
      {
        "id": "hello",
        "title": "打个招呼",
        "argsSchema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "title": "名字",
              "maxLength": 80,
              "default": "飞块",
              "titleKey": "actions.hello.argsSchema.properties.name.title"
            }
          },
          "required": [
            "name"
          ],
          "additionalProperties": false
        },
        "outputSchema": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "titleKey": "actions.hello.title"
      }
    ]
  },
  "icon": "assets/icon.png",
  "i18n": {
    "defaultLocale": "zh-CN",
    "resources": {
      "zh-CN": "locales/zh-CN.json",
      "en-US": "locales/en-US.json"
    }
  },
  "nameKey": "plugin.name",
  "descriptionKey": "plugin.description"
}

#字段结构

顶层的 Manifest 保存插件身份和运行设置。contributes 中每一种功能使用自己的类型，例如 Action 和 Widget。这些类型的属性在各自参考页定义。

字段索引按完整路径列出所有字段，适合在已有清单中查找某个属性。

#Manifest

清单位置：manifest。

#Manifest.apiVersion

integer · 必填

插件协议版本。填写 1。

#Manifest.id

string · 必填

插件的唯一标识，最多 128 个字符。可使用字母、数字、.、_ 和 -，首字符为字母或数字。发布到商店时使用账号分配的命名空间。

#Manifest.name

string · 必填

插件在拓展管理中显示的名称，最多 128 个字符。

#Manifest.version

string · 必填

插件版本，例如 1.0.0。每次发布新包时增加版本号，采用 SemVer 格式。

#Manifest.configurationVersion

integer · 可选，默认 1

宿主管理的插件配置格式版本，范围 1–1000000，独立于插件包 SemVer 和 apiVersion。全局设置、超级块设置及已保存动作参数共用此版本。首次配置格式为 1；修改字段名、类型或动作标识时递增，并为旧格式声明逐版本迁移。插件自管 dataDir 文件不在此版本范围内。

#Manifest.configurationMigrations

integer[] · 可选，默认空数组

后台提供的迁移目标版本，最多 128 个，不能重复，每个版本至少 2 且不大于 configurationVersion。目标版本 N 对应 N-1 到 N 的迁移，在 definePlugin.configurationMigrations[N] 注册。存在旧配置时，缺少中间步骤会阻止升级；首次安装且没有该插件的已保存配置时直接记录当前版本。静态资源插件不能声明迁移处理器。

新就绪协议必须上报 configurationVersion 与 configurationMigrations，宿主严格核对；不会接受省略新字段的旧 SDK 消息。完整流程见更新与迁移。

#Manifest.main

string · 必填

后台入口相对插件根目录的路径，例如 index.js 或 dist/index.js。

#Manifest.hostPlatforms

string[] · 必填

插件支持的桌面系统，填写 windows、macos 或 linux。动作可选声明 hostPlatforms，必须是整包列表的非空子集；未声明时继承整包列表。macOS 专属动作可填写 ["macos"]，宿主隐藏其动作及预设，并阻止直接执行。其他贡献目前仍须支持整包系统。harmonyos 是预留值。

#Manifest.permissions

string[] · 必填

插件使用的宿主能力权限。没有使用宿主能力时填写 []；需要打开网页时加入 system.openExternal。完整列表见权限与联网。

#Manifest.hostCapabilities

HostCapabilityRequirements · 可选

描述插件依赖的宿主接口最低版本，与 permissions 授权分开。未声明时不增加宿主能力最低版本要求；调用接口仍受权限和平台支持情况约束。对象只接受下面两个字段，同一名称不能同时出现在两个映射中。示例：

{ "hostCapabilities": { "required": { "storage.paths": 1 }, "optional": { "system.getVolume": 1 } } }

#Manifest.hostCapabilities.required

Record<string, integer> · 可选

必须满足的接口及最低版本，最多 64 项。名称由字母数字组成的多个段以 . 分隔，每段首字符为字母，总长不超过 128；版本为正安全整数。宿主在安装、启动和依赖检查前阻止缺少必需能力或版本不足的插件，并显示具体原因。商店只校验声明结构，不按商店服务器的系统筛选可发布能力。

#Manifest.hostCapabilities.optional

Record<string, integer> · 可选

插件可使用的附加接口及最低版本，规则与 required 相同，最多 64 项。缺少这些能力仍可启动，插件通过 context.host.hasCapability() 查询并决定是否启用对应功能。声明不授予权限，也不会自动隐藏插件贡献。各系统当前支持的接口见宿主能力。

#Manifest.configPage

string · 可选

插件全局设置 HTML 相对包根目录的路径，例如 pages/settings/index.html，最多 256 字符。必须声明顶层 settingsSchema；页面需要独立的公开资源目录，不能直接放在包根目录，不能包含隐藏目录、空路径段或父目录跳转。资源目录中的文件视为公开资源，不应放置后台代码或密钥。宿主在安装和打包时检查入口存在。配合 settings.configPage: 1 能力和 FlyonDeckPluginConfig 使用；不影响 widgets[].configPage。

#Manifest.settingsSchema

PluginSettings · 可选

插件级全局设置，独立于超级块实例。宿主在拓展详情生成设置表单，后台通过 context.settings 读取和订阅变更，见插件全局设置。

#Manifest.contributes

Contributions · 必填

插件提供的功能。根据需要填写动作、状态和超级块等数组，见下一节。

#Manifest.description

string · 可选

解释插件的用途。提交商店时最多 2000 个字符。

#Manifest.author

string · 可选

作者名称，提交商店时最多 160 个字符。

#Manifest.icon

string · 可选

插件图标图片相对于包根目录的路径，例如 assets/icon.png。图片随插件包分发，支持 PNG、JPEG 和 WebP，单张最多 8 MiB。省略时使用默认插件图标。完整示例和资源读取规则见插件图标与资源。

#Manifest.category

string · 可选

桌面端显示的插件分类。商店项目的分类在开发者中心单独设置。

#Manifest.tags

string[] · 可选

帮助描述插件的标签。

#Manifest.dependencies

Record<string, string> · 可选

必需插件的 ID 与 SemVer 包版本范围映射，最多 64 项。独立插件可省略或填写 {}。例如：

{ "dependencies": { "example.service-provider": "^1.0.0" } }

支持 ^1.2.0、~1.2.0、>=1.0.0 <2.0.0、1.x、1.0.0 - 1.5.0、||。预发布版本遵循 node-semver 默认匹配规则，需显式选择对应预发布版本。

安装和启动前会检查完整依赖链、目标系统、版本范围和服务接口；缺失、冲突或循环依赖会阻止操作。请先安装提供方，宿主不会自动下载依赖。启动消费方时会先确认依赖授权、按顺序启动提供方。停止或重启提供方前先停止运行中的消费方，卸载前先卸载所有直接或间接消费方；更新提供方也不能破坏已安装消费方的包版本或服务接口约束。

这是 FlyonDeck 插件包依赖，与 npm 包无关；Node 运行库仍需随插件打包。使用服务时必须同时填写对应 dependencies 和 uses。

#Manifest.networkOrigins

string[] · 可选

context.network.getJson() 可请求的 HTTPS 来源，例如 https://api.example.com。最多 8 项；填写 ["*"] 可请求任意公网 HTTPS 来源。

#Manifest.widgetConnectOrigins

string[] · 可选

超级块页面和配置页可连接的来源。最多 8 项；填写 ["*"] 可放开页面连接来源，页面请求仍遵循浏览器跨域规则。

#Manifest.uses

ServiceUse[] · 可选

本插件要调用的外部服务，详见 ServiceUse。

#Manifest.eventSubscriptions

EventSubscription[] · 可选

本插件允许订阅的事件，最多 128 项，每项为 {pluginId,eventId,version}。提供方必须同时出现在 dependencies，事件版本为正整数，同一提供方和事件不可重复。详见 context.events.subscribe()。宿主安装/启动检查依赖契约，并在授权界面显示订阅清单；该声明不会自动注册回调。

#EventSubscription.pluginId

string · 必填

事件提供方的完整插件 ID，必须同时声明为 dependencies 中的包依赖。

#EventSubscription.eventId

string · 必填

提供方声明并允许 plugins 消费的事件 ID。不可使用通配符。

#EventSubscription.version

integer · 必填

从 1 开始的事件接口版本，必须与提供方完全匹配。

#Contributions

清单位置：manifest.contributes。

#Contributions.categories

Category[] · 可选

本插件的共享分类目录，最多 64 个。动作与按钮预设都通过 category 引用其中的 ID；分类不会因名称相同而与其他插件合并。每个分类可通过 group 显式加入公共功能分组，见 Category。

#Contributions.actions

Action[] · 可选

用户可执行的动作。见 Action。

#Contributions.buttonPresets

ButtonPreset[] · 可选

按钮预设，最多 32 项。见 ButtonPreset。

#Contributions.stateSources

StateSource[] · 可选

可发布的状态来源，最多 128 项。见 StateSource。

#Contributions.widgets

Widget[] · 可选

可放置的超级块。见 Widget。

#Contributions.dataProviders

DataProvider[] · 可选

页面请求的一次性数据，最多 128 项。见 DataProvider。

#Contributions.events

PluginEvent[] · 可选

后台发给宿主的事件，最多 128 项。见 PluginEvent。

#Contributions.services

Service[] · 可选

供其他插件调用的服务，最多 32 项。见 Service。

#平台产物与运行时

可选字段 target、runtime、nativeModules 用于同版本的不同平台构建产物。target 包含 platform、arch 和可选的 Linux libc；runtime 包含可选的 node、electron SemVer 范围、modules 精确 ABI 字符串、napi 最低 Node-API 版本。含 .node 文件时必须完整声明 nativeModules 并指定目标及 ABI 或 Node-API 要求。字段的构建和校验流程见打包与安装。

#Manifest.target

可选的分平台安装目标。未声明时表示通用包；含原生二进制的包必须声明目标。

#Manifest.target.platform

目标系统，必须与唯一的 hostPlatforms 项一致。

#Manifest.target.arch

目标 CPU 架构：x64、arm64、ia32 或 arm。

#Manifest.target.libc

仅 Linux 可声明 glibc 或 musl，用于区分运行环境。

#Manifest.runtime

可选的运行时兼容要求。安装及启动前检查宿主版本。

#Manifest.runtime.node

宿主 Node.js 版本的 SemVer 范围。

#Manifest.runtime.electron

宿主 Electron 版本的 SemVer 范围。

#Manifest.runtime.modules

使用 Node/V8 ABI 的原生模块所需的精确 NODE_MODULE_VERSION，使用数字字符串。

#Manifest.runtime.napi

仅使用稳定 Node-API 的原生模块要求的最低 Node-API 版本。

#Manifest.nativeModules

包内全部 .node 文件的相对路径列表。包含原生模块时必须声明 target 及 modules ABI 或 Node-API 要求；安装替换前会检查实际加载能力。

纯图标资源插件可以省略 main，permissions 为空、contributes 只包含 iconPacks，不声明运行时或原生模块要求；宿主静态加载，不启动后台进程。代码插件仍须填写 main。