# 包清单

运行时只认**包**: 一个目录, `package.json` 的 `acde` 字段是清单. `acdev build` 从配置生成它; 你也可以手写.

```json
{
  "name": "my-pkg",
  "acdev": {
    "apiLevel": 1,
    "desktops": [{ "id": "dopame", "name": "Dopame", "entry": "desktop/index.html", "services": ["assistant"] }],
    "apps": [{ "id": "term", "label": "终端", "icon": "term", "entry": "/app/term/index.html", "capabilities": { "terminal": true } }],
    "assets": { "/app/term/": ["apps/term/web"], "/desktop/dopame/": ["desktop"] },
    "services": [{ "name": "assistant", "module": "services/assistant.js" }]
  }
}
```

清单的校验只有一份, 运行时和 `acdev check` / `acdev build` 用的是同一段代码 (`@dopame/acde-api/manifest`). `acdev check <dir>` 检查手写的包.

## PackageManifest

| 字段 | 说明 |
| --- | --- |
| `apiLevel` | 包是按哪个契约级别构建的, 正整数; 必填. 见 [契约级别](#契约级别) |
| `desktops` | 桌面列表 |
| `apps` | 应用列表. 在带桌面的包里, 它们是系统应用 |
| `assets` | 同源 URL 前缀 (`/…/`) → 包里的目录列表 |
| `services` | `{name, module}`: 服务名和模块文件. 名字不能是系统模块或能力的名字 |

## 契约级别

`apiLevel` 说明包遵循的是包和运行时之间哪一版契约. 现在的级别是 1 (`@dopame/acde-api` 里的 `API_LEVEL`; `acdev --version` 打印它自己的和运行时的, 运行时二进制 (安装目录的 `libexec/acdev`) 用 `--version` 打印它自己的). 运行时只载入和自己同一级别的包:

| 包 | 运行时和 `acdev check` 怎么说 |
| --- | --- |
| 没有 `apiLevel` (在有契约级别之前构建的) | `no acde.apiLevel: a package built before contract levels; rebuild it with the current acdev (level 1)` |
| 别的级别 | `acde.apiLevel 2: needs level 2, runtime is level 1` |

被运行时拒绝的包不在应用列表里, 也不在桌面列表里. 用现在的 `acdev` 重新构建它.

## DesktopManifest

| 字段 | 说明 |
| --- | --- |
| `id` / `name` / `description` | |
| `entry` | 桌面页面: 包里一个 HTML 文件的路径 (`desktop/index.html`), 不是 URL |
| `lock` | 可选. 锁屏页面, 写法同 `entry` (`desktop/lock.html`). 屏幕锁着时会话显示它; 它只拿得到 `acde:lock` (`user()`、`unlock(password)`) |
| `services` | 用到的服务: 一个名字, 或 `{name, modules}`, 其中 `modules` 列出这个服务可以从 `ctx.import()` 拿到的 shell 模块 (见 [服务接口](https://docs.dopame.ai/zh/reference/service.md)) |
| `heapMb` | 默认 1024, 最小 32 |

## AppManifest

| 字段 | 说明 |
| --- | --- |
| `id` | `[\w-]+`, 必填. 运行时认这个规则; 配置只允许 `[a-z0-9][a-z0-9-]*` (见 [acde.config.jsonc](https://docs.dopame.ai/zh/reference/config.md#appconfig)), 所以宽松的规则只对手写的包有意义 |
| `label` | 必填 |
| `icon` | 图标名, 或 assets 下以 `.svg` / `.png` 结尾的 URL, 必填 |
| `entry` | 以 `/` 开头的 URL, 必填. HTML 或模块; 以 `/` 结尾表示页面由后端渲染 (要有 `backend`) |
| `capabilities` | 系统能力, 见下 |
| `optional` | `capabilities` 里的名字中, 应用没有也能跑的那些 |
| `services` | 应用用到的桌面服务的名字 |
| `heapMb` | 默认 256, 最小 32 |
| `size` | `[宽, 高]`, 默认 800 × 600 |
| `multiple` | 默认 `false` |
| `frame` | 默认 `true` |
| `mimeTypes` | 应用能打开的文件类型: `type/subtype` 或 `type/*` |
| `schemes` | 应用能打开的链接的 URL scheme: 小写, 不带冒号, 不能是 `file` |
| `requests` | 应用从别的应用接受的请求种类: 小写的词, 不能是 `open-file` 或 `open-link` |
| `backend` | `{entry, port?}`: `entry` 是 assets 下的 `.js` / `.mjs` URL, `port` 默认 3000 |

## Capabilities

| 键 | 值 | 给什么 | 问用户 |
| --- | --- | --- | --- |
| `fs` | `true` \| `{roots: string[]}` | `acde:fs`: 私有文件夹和选中的文件夹; `roots` 写共享位置 (`desktop`、`documents`、`downloads`、`music`、`pictures`、`videos`) | |
| `terminal` | `true` | `acde:terminal` | |
| `network` | `true` | `acde:network` | |
| `system` | `true` | [`acde:system`](https://docs.dopame.ai/zh/reference/modules.md#acdesystem) (仅 Linux) | |
| `bluetooth` | `true` | [`acde:bluetooth`](https://docs.dopame.ai/zh/reference/modules.md#acdebluetooth) (仅 Linux) | |
| `audio` | `true` | [`acde:audio`](https://docs.dopame.ai/zh/reference/modules.md#acdeaudio) (仅 Linux) | |
| `devices` | `true` | [`acde:devices`](https://docs.dopame.ai/zh/reference/modules.md#acdedevices) (仅 Linux) | |
| `power` | `true` | [`acde:power`](https://docs.dopame.ai/zh/reference/modules.md#acdepower) (仅 Linux) | |
| `input` | `true` | [`acde:input`](https://docs.dopame.ai/zh/reference/modules.md#acdeinput) (仅 Linux) | |
| `display` | `true` | [`acde:display`](https://docs.dopame.ai/zh/reference/modules.md#acdedisplay) (仅 Linux) | |
| `office` | `true` | `acde:office` | |
| `launch` | `true` | `acde:launch` 的 `start` | |
| `slots` | `true` | `acde:launch` 的 `embed`: 嵌在应用窗口里的原生程序 | |
| `open` | `true` \| `string[]` | 用 `acde:open` 打开 (这些) 应用 | |
| `openFiles` | `true` | `acde:openPath`、`acde:handlers`, 以及不带目标应用的 `open(request)` | |
| `camera` / `microphone` | `true` | `getUserMedia()` 的视频 / 音频 | 是, 在第一次使用时 |
| `idleDetection` | `true` | `IdleDetector` (仅 Linux) | 是, 在页面调用 `IdleDetector.requestPermission()` 时 |
| `windows` `packages` `session` `desktops` `inspect` `desktop` `setDefault` `permissions` | `true` | 同名的 shell 模块. 只给系统应用: 写在别的包里是错误 | |

别的键都是错误: 桌面服务写在 `services` 里. 系统通知 (`new Notification()`) 不需要键; `acde:capabilities` 把它报告为 `notifications`. 系统应用从不需要用户批准.

`capabilities` 和 `services` 里的每一项都是必需的, 除非 `optional` 列了它 (`optional` 只收 `capabilities` 里的名字). 有必需项在这里缺失 (平台不支持、服务没在跑) 的应用不在应用列表里, 也拒绝启动: `Notes needs "network" (not available on macOS host windows); list it in "optional" to run without it` (404 `unsupported_app`; 地方是 `Windows host windows`、`Linux host windows` 或 `Linux sessions`), 或 `Notes needs "clock" (service not running)` (503 `service_not_running`). 声明了能力就给了它; 只有摄像头、麦克风和空闲检测问用户 (见 [系统能力](https://docs.dopame.ai/zh/guide/capabilities.md#摄像头和麦克风)).

## 地址

- 页面的源是 `http://acde.local`.
- 应用的文件在 `/app/<id>/`, 也挂在 `/` 下; 桌面在 `/desktop/<id>/`.
