# context.system

`context.system` 让插件请求飞块执行系统操作。在使用方法前，先在清单的 `permissions` 中声明对应权限，见[权限参考](./permissions.md)。

`openExternal()` 和 `openPath()` 使用跨平台的系统打开方式。打开应用、热键、文本输入、截图、锁屏、音量读写和关闭显示器支持 Windows/macOS；整机睡眠及快捷指令目前仅支持 macOS。macOS 的输入还需要系统辅助功能与自动化权限。Windows 输入面向前台应用，受系统 UIPI 限制，不能自动向更高权限应用注入输入。

## openExternal()

在默认应用中打开 URL，需要 `system.openExternal`。

```ts
context.system.openExternal(url: string): Promise<{ opened: boolean }>
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `url` | `string` | 要打开的 URL。 |

### 返回值

Promise 解析为 `{ opened: boolean }`，表示打开请求是否成功。

### 示例

```js
await context.system.openExternal("https://example.com");
```

## openApplication()

启动电脑上的应用，需要 `system.openApplication`。

```ts
context.system.openApplication(nameOrPath: string): Promise<{ opened: boolean }>
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `nameOrPath` | `string` | macOS 使用应用名称或 `.app` 路径；Windows 使用存在的 `.exe` 或 `.lnk` 绝对路径，不接受附加参数或脚本。 |

### 返回值

Promise 解析为 `{ opened: boolean }`。

### 示例

```js
await context.system.openApplication(args.application);
```

## openPath()

使用系统默认应用打开文件或文件夹，需要 `system.openPath`。

```ts
context.system.openPath(path: string): Promise<{ opened: boolean }>
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `path` | `string` | 电脑上的文件或文件夹路径。 |

### 返回值

Promise 解析为 `{ opened: boolean }`。

## getVolume()

读取系统默认音频输出，使用已有的 `system.adjustVolume` 权限。

```ts
context.system.getVolume(): Promise<{ available: boolean; level: number; muted: boolean }>
```

Windows 使用 Core Audio 默认输出端点，macOS 使用系统音量设置。`level` 是 0–100 的整数，`muted` 表示静音。设备不可访问或权限未批准时拒绝请求；插件可据此显示不可用状态。协议内部仍使用 `system.adjustVolume` 能力，`operation: "get"`，不新增权限或绕过原有授权。

## adjustVolume()

调整系统音量，需要 `system.adjustVolume`。

```ts
context.system.adjustVolume(operation: 'up' | 'down' | 'toggleMute', step?: number): Promise<{ adjusted: boolean }>
context.system.adjustVolume(operation: 'set', level: number): Promise<{ adjusted: boolean }>
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `operation` | `string` | `up` 增大、`down` 减小、`toggleMute` 切换静音、`set` 设置音量。 |
| `step / level` | `number` | 增减步长默认 10，范围 1–100；设置音量时必填，范围 0–100。数值使用整数。 |

### 返回值

Promise 解析为 `{ adjusted: boolean }`。

### 示例

```js
await context.system.adjustVolume("set", 35);
```

## sendHotkey()

向当前前台应用发送热键，需要 `system.sendHotkey`。

```ts
context.system.sendHotkey(shortcut: string): Promise<{ sent: boolean }>
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `shortcut` | `string` | 标准化物理按键组合，例如 `Meta+Shift+KeyK`。使用 `format: "hotkey"` 可让编辑器录入此格式。 |

### 返回值

Promise 解析为 `{ sent: boolean }`。

## sendText()

向当前前台应用输入文本，需要 `system.sendText`。

```ts
context.system.sendText(text: string, mode?: 'paste' | 'type', pressEnter?: boolean): Promise<{ sent: boolean }>
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `text` | `string` | 输入内容，最多 4000 个字符。 |
| `mode` | `string` | 默认为 `paste`，会写入剪贴板再粘贴；`type` 模拟输入，内容最多 1000 个字符。 |
| `pressEnter` | `boolean` | 是否在输入后发送回车，默认 `false`。 |

### 返回值

Promise 解析为 `{ sent: boolean }`。SDK 在 `paste` 模式等待最多 15 秒，`type` 模式等待最多 60 秒。

### 示例

```js
await context.system.sendText(args.text, "paste", false);
```

## captureScreen()

调用系统截图，需要 `system.captureScreen`。

```ts
context.system.captureScreen(mode: 'full' | 'region' | 'window'): Promise<{ started: boolean }>
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `mode` | `string` | `full` 全屏、`region` 区域、`window` 窗口。区域和窗口模式会等待用户选择。 |

### 返回值

Promise 解析为 `{ started: boolean }`，表示截图工具已启动，不表示已经保存。Windows PNG 保存到用户图片目录的 `FlyonDeck Screenshots`，区域/窗口模式显示宿主选择界面，Esc 取消；窗口模式保存其范围内当时可见的画面。macOS 遵循系统截图设置。

## lockScreen()

请求锁定屏幕，需要 `system.lockScreen`。

```ts
context.system.lockScreen(): Promise<{ requested: boolean }>
```

### 返回值

Promise 解析为 `{ requested: boolean }`。

## sleepComputer()

请求电脑休眠，需要 `system.sleepComputer`。

```ts
context.system.sleepComputer(): Promise<{ requested: boolean }>
```

### 返回值

Promise 解析为 `{ requested: boolean }`。

## sleepDisplay()

请求显示器休眠，需要 `system.sleepDisplay`。

```ts
context.system.sleepDisplay(): Promise<{ requested: boolean }>
```

### 返回值

Promise 解析为 `{ requested: boolean }`。

## runShortcut()

运行 macOS“快捷指令”中的项目，需要 `system.runShortcut`。

```ts
context.system.runShortcut(shortcutName: string): Promise<{ requested: boolean }>
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `shortcutName` | `string` | 快捷指令名称。 |

### 返回值

Promise 解析为 `{ requested: boolean }`。

### 示例

```js
await context.system.runShortcut("开始工作");
```