# 系统能力

页面里只有标准的 Web 接口. 系统能力只有一个入口: `acde:` 内置模块, 写法和 `node:fs` 一样:

```js
import { fs } from 'acde:fs'
import { window } from 'acde:window'
import fs2 from 'acde:fs' // 默认导出也是同一个对象
```

没有 `acdev` 全局变量, 运行时也不往 `window` 上挂任何非标准的东西.

访问别的主机不需要申请能力: `fetch`、`WebSocket` 等标准接口照常可用, 系统设了代理时经系统代理. 见 [Web 兼容性](https://docs.dopame.ai/zh/reference/web.md#网络).

## 申请能力

应用能导入哪些模块, 由配置的 `capabilities` 决定:

```jsonc
{
  "capabilities": {
    "fs": true,
    "openFiles": true,
    "open": ["notes", "viewer"]
  }
}
```

| 能力 | 给什么 |
| --- | --- |
| `fs` | `acde:fs`. `true`: 应用的私有文件夹和用户为它选的文件夹. `{ "roots": ["downloads", … ] }` 再加上共享位置, 见 [文件与文件夹](https://docs.dopame.ai/zh/guide/files.md) |
| `terminal` | `acde:terminal`: 伪终端 |
| `network` | `acde:network`: 网络设置, Wi-Fi (仅 Linux, 包括 Dopame OS) |
| `system` | `acde:system`: 主机名、时区和时钟同步、存储、用户 (仅 Linux) |
| `bluetooth` | `acde:bluetooth`: 适配器、配对和设备 (仅 Linux) |
| `audio` | `acde:audio`: 声音设备、音量、音频流 (仅 Linux) |
| `devices` | `acde:devices`: 驱动器 (挂载、弹出、自动挂载) 和打印机 (仅 Linux) |
| `power` | `acde:power`: 电池、电源模式和设置、挂起、亮度 (仅 Linux) |
| `input` | `acde:input`: 键盘布局、鼠标和触摸板、输入法 (仅 Linux) |
| `display` | `acde:display`: 显示模式、缩放、旋转、亮度、夜间模式 (仅 Linux) |
| `office` | `acde:office`: 办公文档服务 (仅 Linux) |
| `open` | 用 `acde:open` 打开别的应用. `true` 是任意应用, 或应用 id 的列表 |
| `openFiles` | `acde:openPath` / `acde:handlers`, 以及不指定目标应用的 `open(request)`: 文件或链接交给它的默认应用 |
| `launch` | `acde:launch` 的 `start`: 起原生程序 |
| `slots` | `acde:launch` 的 `embed`: 嵌在自己窗口里的原生程序 (仅 Dopame OS) |
| `camera` / `microphone` | `navigator.mediaDevices.getUserMedia()` 的视频 / 音频 (Windows 上没有); 要问用户, 见[下文](#摄像头和麦克风) |
| `idleDetection` | `IdleDetector` (仅 Linux); 页面调用 `IdleDetector.requestPermission()` 时问用户 |

这些模块每个应用不用申请就能导入: `acde:window` (自己的窗口)、`acde:capabilities` (自己有哪些能力, 见[下文](#acdecapabilities))、`acde:apps` (`list()` 和 `open()`)、`acde:open` (打开别的应用仍然要有 `open`).

表里没有的名字, `acdev check` 会报错:

- **桌面服务**写在 `services` 里, 不写在 `capabilities` 里: `"services": ["clock"]`, 然后 `import { clock } from 'acde:clock'`. 这样应用只在跑着这个服务的桌面里启动. 见 [服务](https://docs.dopame.ai/zh/guide/services.md).
- **shell 模块** (`acde:windows`、`acde:packages`、`acde:session`、`acde:desktops`、`acde:inspect`、`acde:desktop`、`acde:setDefault`、`acde:permissions`) 属于桌面. 只有桌面页面、它的服务和桌面自带的应用 (系统应用) 拿得到, 见 [桌面](https://docs.dopame.ai/zh/guide/desktop.md#系统应用).

导入应用无权使用的模块会失败, 抛出 `AcdeError` (`name === 'AcdeError'` 的 `Error`, 带 `code: 'forbidden'`、`status: 403` 和 `module`, 即去掉 `acde:` 的模块名), 消息里指出缺的是哪项声明; 提供模块的服务停了时, 以同样的方式失败, `code` 是 `'service_not_running'`, `status` 是 503 (见 [错误](https://docs.dopame.ai/zh/reference/modules.md#错误)). `acdev check` 和 `acdev build` 在运行之前就对源码里的每个 `import` 报告同样的问题:

```text
error: app "notes": capability "clock" is not a system capability; list desktop services under services
error: src/main.js:1: app "notes": acde:terminal needs "terminal" in the capabilities of Notes
error: src/main.js:2: app "notes": acde:windows is a shell module: only the desktop, its services and system apps may import it, and Notes is not a system app
```

调用应用无权使用的方法会被拒绝, `status: 403` (`code: 'forbidden'`), 比如 `open` 里只列了别的应用时调 `open('mail')`.

## 摄像头和麦克风

声明了能力, 应用就能用它: 不问用户, `fs.roots` 里的共享位置、`terminal`、`network`、`launch` 和 `slots` 也一样. 只有摄像头和麦克风要问用户, 还有空闲检测 (`idleDetection`, 在页面调用 `IdleDetector.requestPermission()` 时), 问法相同. 桌面自带的应用 (系统应用) 不用问.

- **什么时候问**: 页面第一次调 `navigator.mediaDevices.getUserMedia()` (或下文的 `request()`) 时; 这次调用等着用户回答. 应用必需的摄像头或麦克风也是这样.
- **允许**: 决定按应用存下来 (`$XDG_CONFIG_HOME/acde/permissions.json`), 不会再问用户.
- **拒绝**: `getUserMedia()` 以 `NotAllowedError` reject, 和浏览器里一样. 应用照常运行, 也留在应用列表里, 被拒绝的是它必需的那一样时也是如此.
- **谁来问**: 在桌面里, 由桌面显示提示 (见 [桌面](https://docs.dopame.ai/zh/guide/desktop.md#摄像头和麦克风提示)). 在只跑一个应用的宿主窗口里, Windows 用一个对话框问, macOS 的宿主窗口用一个 sheet 问 (`Allow` / `Don't Allow`), Linux 的宿主窗口用一条带 Allow 和 Deny 按钮的桌面通知问 (没有通知服务时什么都不显示).
- **在 Dopame OS 会话里**: 摄像头和麦克风还不能用, 声明了也一样: `getUserMedia()` 立刻以 `NotAllowedError` reject, 也不问用户.
- **在开发会话里**: 用 `acdev allow` 或 `acdev deny` 回答 (什么都没显示时、headless 时也一样), 用 `acdev revoke` 收回决定; 见 [调试工具](https://docs.dopame.ai/zh/guide/tools.md#摄像头和麦克风). 测试用 `acde.allow()` 回答 (见 [端到端测试](https://docs.dopame.ai/zh/guide/testing.md#批准)).

## 可选能力

`capabilities` 里的每一项默认都是必需的: 平台没有其中一项, 应用就不启动. 应用没有也能跑的那些, 列在 `optional` 里:

```jsonc
{
  "capabilities": { "terminal": true },
  "optional": ["terminal"]
}
```

- 在没有这个能力的平台上, 应用也能启动.
- 可选的模块不能静态导入 (`acdev check`: `acde:terminal is optional ("terminal" is in optional): import it dynamically, await import('acde:terminal'), which rejects where this platform lacks it`). 动态导入它; 模块拿不到时 promise 会 reject.
- `camera` 和 `microphone` 没有可加载的模块: 页面调 `navigator.mediaDevices.getUserMedia()`, 第一次调用时由它问用户. 见 [Web 兼容性](https://docs.dopame.ai/zh/reference/web.md#媒体).

```js
const terminal = await import('acde:terminal').then((m) => m.default, () => null) // 这个平台没有它时是 null
```

把 `fs` 设成可选, 它的共享位置也就成了可选的.

## acde:capabilities

```js
import { capabilities } from 'acde:capabilities'

capabilities.level // 1: 运行时的契约级别
capabilities.platform // 'linux' | 'darwin' | 'win32'
capabilities.mode // 'session' (Dopame OS) | 'desktop' (宿主窗口里的桌面) | 'standalone' (宿主窗口里的单个应用)
capabilities.get('terminal') // { name, kind: 'system' | 'service', state, reason, optional }
capabilities.list() // 同上, 每个系统能力和 shell 模块、notifications, 以及应用声明的每个 fs.<位置> 和服务各一项
await capabilities.request('camera') // 为摄像头或麦克风问用户; resolve 成状态
```

| `state` | 含义 |
| --- | --- |
| `available` | 声明了, 这个平台也有 (摄像头、麦克风: 用户也已经允许) |
| `not-asked` | 摄像头或麦克风, 还没问过用户: `request()` 会问 |
| `asking` | 摄像头或麦克风的提示在等用户回答 |
| `not-declared` | 不在应用的 `capabilities` / `services` 里 |
| `unsupported` | 这个平台或这种运行方式没有它 |
| `service-not-running` | 桌面服务没在跑 |
| `shell-only` | 是 shell 模块, 而应用不是系统应用 |
| `denied` | 摄像头或麦克风: 用户拒绝了它, 或这个决定被收回了 |

对别的能力, 或用户已经回答过的能力调 `request()`, 马上 resolve 成当前的状态.

`notifications` 就是标准的 `Notification` 接口, 不用声明: 它是 `available`, 在这种运行方式不显示通知的地方 (Windows 上的单个应用) 是 `unsupported`.

## 类型

所有模块的类型在 SDK `@dopame/acde-api` 里, 引用适合工程的那个入口, 编辑器就认识它能导入的 `acde:*` 模块:

```js
/// <reference types="@dopame/acde-api/app" />
```

- `@dopame/acde-api/app`: 应用的模块 (`acde:fs`、`acde:window`、`acde:open` ……).
- `@dopame/acde-api/shell`: 上面这些再加 shell 模块, 给桌面和它自带的应用用.
- `@dopame/acde-api`: 全部.

## 在浏览器里

同一份代码要在普通浏览器里预览时:

- 动态导入 `acde:` 模块, 导入 reject 时退回别的做法 (浏览器里没有 `acde:` 模块):

```js
const fs = await import('acde:fs').then((m) => m.default, () => null)
```

## 模块一览

| 模块 | 用途 | 文档 |
| --- | --- | --- |
| `acde:window` | 自己的窗口: 标题、菜单、关闭、状态、快捷键、事件 | [窗口](https://docs.dopame.ai/zh/guide/window.md) |
| `acde:capabilities` | 应用有哪些能力、请求可选能力 | [上文](#acdecapabilities) |
| `acde:fs` | 文件 | [文件与文件夹](https://docs.dopame.ai/zh/guide/files.md) |
| `acde:apps` `acde:open` `acde:openPath` `acde:handlers` | 别的应用、打开文件和链接 | [打开应用](https://docs.dopame.ai/zh/guide/open.md) |
| `acde:launch` | 原生程序 | [参考](https://docs.dopame.ai/zh/reference/modules.md#acdelaunch) |
| `acde:terminal` | 伪终端 | [参考](https://docs.dopame.ai/zh/reference/modules.md#acdeterminal) |
| `acde:network` | 网络 | [参考](https://docs.dopame.ai/zh/reference/modules.md#acdenetwork) |
| `acde:windows` `acde:packages` `acde:desktop` `acde:inspect` `acde:permissions` `acde:session` `acde:desktops` `acde:setDefault` | shell 模块: 桌面和系统应用 | [桌面](https://docs.dopame.ai/zh/guide/desktop.md) |

完整签名见 [参考: acde: 模块](https://docs.dopame.ai/zh/reference/modules.md).
