# manifest.json 飞块在加载插件时读取 `manifest.json`。这个文件放在插件根目录中，使用 JSON 格式。 ## 示例 下面的清单提供一个问候动作。你可以从它开始，再按需要向 `contributes` 添加功能。 ```json { "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`。这些类型的属性在各自参考页定义。 [字段索引](./fields.md)按完整路径列出所有字段，适合在已有清单中查找某个属性。 ## 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 消息。完整流程见[更新与迁移](../migrations/compatibility.md)。 ### `Manifest.main` `string` · 必填 后台入口相对插件根目录的路径，例如 `index.js` 或 `dist/index.js`。 ### `Manifest.hostPlatforms` `string[]` · 必填 插件支持的桌面系统，填写 `windows`、`macos` 或 `linux`。动作可选声明 `hostPlatforms`，必须是整包列表的非空子集；未声明时继承整包列表。macOS 专属动作可填写 `["macos"]`，宿主隐藏其动作及预设，并阻止直接执行。其他贡献目前仍须支持整包系统。`harmonyos` 是预留值。 ### `Manifest.permissions` `string[]` · 必填 插件使用的宿主能力权限。没有使用宿主能力时填写 `[]`；需要打开网页时加入 `system.openExternal`。完整列表见[权限与联网](./permissions.md)。 ### `Manifest.hostCapabilities` `HostCapabilityRequirements` · 可选 描述插件依赖的宿主接口最低版本，与 `permissions` 授权分开。未声明时不增加宿主能力最低版本要求；调用接口仍受权限和平台支持情况约束。对象只接受下面两个字段，同一名称不能同时出现在两个映射中。示例： ```json { "hostCapabilities": { "required": { "storage.paths": 1 }, "optional": { "system.getVolume": 1 } } } ``` ### `Manifest.hostCapabilities.required` `Record` · 可选 必须满足的接口及最低版本，最多 64 项。名称由字母数字组成的多个段以 `.` 分隔，每段首字符为字母，总长不超过 128；版本为正安全整数。宿主在安装、启动和依赖检查前阻止缺少必需能力或版本不足的插件，并显示具体原因。商店只校验声明结构，不按商店服务器的系统筛选可发布能力。 ### `Manifest.hostCapabilities.optional` `Record` · 可选 插件可使用的附加接口及最低版本，规则与 `required` 相同，最多 64 项。缺少这些能力仍可启动，插件通过 [`context.host.hasCapability()`](./host.md) 查询并决定是否启用对应功能。声明不授予权限，也不会自动隐藏插件贡献。各系统当前支持的接口见[宿主能力](./host.md#当前能力)。 ### `Manifest.configPage` `string` · 可选 插件全局设置 HTML 相对包根目录的路径，例如 `pages/settings/index.html`，最多 256 字符。必须声明顶层 `settingsSchema`；页面需要独立的公开资源目录，不能直接放在包根目录，不能包含隐藏目录、空路径段或父目录跳转。资源目录中的文件视为公开资源，不应放置后台代码或密钥。宿主在安装和打包时检查入口存在。配合 `settings.configPage: 1` 能力和 [FlyonDeckPluginConfig](./plugin-config-page.md) 使用；不影响 `widgets[].configPage`。 ### `Manifest.settingsSchema` `PluginSettings` · 可选 插件级全局设置，独立于超级块实例。宿主在拓展详情生成设置表单，后台通过 `context.settings` 读取和订阅变更，见[插件全局设置](./plugin-settings.md)。 ### `Manifest.contributes` `Contributions` · 必填 插件提供的功能。根据需要填写动作、状态和超级块等数组，见下一节。 ### `Manifest.description` `string` · 可选 解释插件的用途。提交商店时最多 2000 个字符。 ### `Manifest.author` `string` · 可选 作者名称，提交商店时最多 160 个字符。 ### `Manifest.icon` `string` · 可选 插件图标图片相对于包根目录的路径，例如 `assets/icon.png`。图片随插件包分发，支持 PNG、JPEG 和 WebP，单张最多 8 MiB。省略时使用默认插件图标。完整示例和资源读取规则见[插件图标与资源](./icons.md)。 ### `Manifest.category` `string` · 可选 桌面端显示的插件分类。商店项目的分类在开发者中心单独设置。 ### `Manifest.tags` `string[]` · 可选 帮助描述插件的标签。 ### `Manifest.dependencies` `Record` · 可选 必需插件的 ID 与 SemVer 包版本范围映射，最多 64 项。独立插件可省略或填写 `{}`。例如： ```json { "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 默认匹配规则](https://github.com/npm/node-semver#prerelease-tags)，需显式选择对应预发布版本。 安装和启动前会检查完整依赖链、目标系统、版本范围和服务接口；缺失、冲突或循环依赖会阻止操作。请先安装提供方，宿主不会自动下载依赖。启动消费方时会先确认依赖授权、按顺序启动提供方。停止或重启提供方前先停止运行中的消费方，卸载前先卸载所有直接或间接消费方；更新提供方也不能破坏已安装消费方的包版本或服务接口约束。 这是 FlyonDeck 插件包依赖，与 npm 包无关；Node 运行库仍需随插件打包。使用服务时必须同时填写对应 `dependencies` 和 [uses](./services.md)。 ### `Manifest.networkOrigins` `string[]` · 可选 `context.network.getJson()` 可请求的 HTTPS 来源，例如 `https://api.example.com`。最多 8 项；填写 `["*"]` 可请求任意公网 HTTPS 来源。 ### `Manifest.widgetConnectOrigins` `string[]` · 可选 超级块页面和配置页可连接的来源。最多 8 项；填写 `["*"]` 可放开页面连接来源，页面请求仍遵循浏览器跨域规则。 ### `Manifest.uses` `ServiceUse[]` · 可选 本插件要调用的外部服务，详见 [ServiceUse](./services.md#serviceuse)。 ### `Manifest.eventSubscriptions` `EventSubscription[]` · 可选 本插件允许订阅的事件，最多 128 项，每项为 `{pluginId,eventId,version}`。提供方必须同时出现在 dependencies，事件版本为正整数，同一提供方和事件不可重复。详见 [context.events.subscribe()](./events.md#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](./actions.md#category)。 ### `Contributions.actions` `Action[]` · 可选 用户可执行的动作。见 [Action](./actions.md#action)。 ### `Contributions.buttonPresets` `ButtonPreset[]` · 可选 按钮预设，最多 32 项。见 [ButtonPreset](./presets.md#buttonpreset)。 ### `Contributions.stateSources` `StateSource[]` · 可选 可发布的状态来源，最多 128 项。见 [StateSource](./states.md#statesource)。 ### `Contributions.widgets` `Widget[]` · 可选 可放置的超级块。见 [Widget](./widgets.md#widget)。 ### `Contributions.dataProviders` `DataProvider[]` · 可选 页面请求的一次性数据，最多 128 项。见 [DataProvider](./data-providers.md#dataprovider)。 ### `Contributions.events` `PluginEvent[]` · 可选 后台发给宿主的事件，最多 128 项。见 [PluginEvent](./events-manifest.md#pluginevent)。 ### `Contributions.services` `Service[]` · 可选 供其他插件调用的服务，最多 32 项。见 [Service](./services.md#service)。 ## 平台产物与运行时 可选字段 `target`、`runtime`、`nativeModules` 用于同版本的不同平台构建产物。`target` 包含 `platform`、`arch` 和可选的 Linux `libc`；`runtime` 包含可选的 `node`、`electron` SemVer 范围、`modules` 精确 ABI 字符串、`napi` 最低 Node-API 版本。含 `.node` 文件时必须完整声明 `nativeModules` 并指定目标及 ABI 或 Node-API 要求。字段的构建和校验流程见[打包与安装](../publishing/package.md)。 ## 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。