# host：宿主能力

这里的宿主指运行插件的飞块桌面端。`context.host` 提供当前桌面端已实现的接口及版本，用于判断当前系统支持哪些功能。

接口支持、插件权限和执行条件分别检查。例如，桌面端提供读取音量接口时，插件仍需声明并获得相应权限；实际读取也可能因音频设备不可用而失败。

插件可以直接使用 SDK 提供的 `context.host` 和 `context.storage`。

## hasCapability()

```ts
context.host.hasCapability(name: string, minimumVersion = 1): boolean
```

同步查询接口是否达到最低版本。未知能力返回 `false`，版本必须为正安全整数。`context.host.capabilities` 是只读的名称到版本映射，生命周期内保持不变。

插件的必需能力写入 [`hostCapabilities.required`](./manifest.md#manifest-hostcapabilities-required)，宿主在安装、启动和检查插件依赖时验证；不兼容的已安装包仍显示原因，但不会出现在新增动作、预设或超级块列表中。`optional` 缺失不阻止启动，插件按当前系统支持的能力决定是否启用对应功能。例如，读取音量接口支持 Windows 和 macOS：

```js
if (context.host.hasCapability('system.getVolume', 1)) {
  const volume = await context.system.getVolume();
  // 仍需处理 volume.available、权限拒绝和设备读取失败。
}
```

能力版本使用正整数，查询时按声明的最低版本比较。当前能力版本均为 1；插件包的 SemVer、`apiVersion`、服务接口版本与能力版本分别描述不同的契约。

## 当前能力

下列接口当前均为 v1：

| 支持范围 | 能力名称 |
| --- | --- |
| 所有桌面平台 | `settings.global`、`settings.configPage`、`host.capabilities`、`storage.paths`、`widgets.instances`、`states.publish`、`events.emit`、`network.getJson`、`plugins.call`、`native.execute`、`deck.navigate`、`system.openExternal`、`system.openPath` |
| Windows、macOS | `system.openApplication`、`system.getVolume`、`system.adjustVolume`、`system.sendHotkey`、`system.sendText`、`system.captureScreen`、`system.lockScreen`、`system.sleepDisplay` |
| macOS | `system.sleepComputer`、`system.runShortcut` |

查询和目录分配无需权限。使用系统代理仍须声明对应 `permissions` 并获用户批准；`system.getVolume` 使用 `system.adjustVolume` 权限。插件业务能力通过自己的贡献或服务提供，不加入宿主能力表。

插件全局设置使用宿主能力 `settings.global: 1`，支持后台读取与运行期间的设置变更通知，见[插件全局设置](./plugin-settings.md)。