# 配置工程

工程的配置在根目录的 `acde.config.jsonc` (也可以叫 `acde.config.json`). JSONC 允许注释和尾逗号. 开头的 `$schema` 让编辑器有补全和校验:

```jsonc
{
  "$schema": "./acde.config.schema.json",
  "type": "app",
  "id": "notes",
  "label": "笔记",
  "icon": "editor",
  "entry": "index.html",
  "size": [960, 640],
  "capabilities": { "fs": true }
}
```

## 应用 (`"type": "app"`)

| 字段 | 说明 |
| --- | --- |
| `id` | 应用 id, 小写字母、数字和 `-`. 默认由 `package.json` 的 `name` 得出 |
| `label` | 显示名, 出现在标题栏和桌面上 |
| `icon` | 图标名或工程里的一张 `.svg` / `.png`, 见 [静态资源与图标](https://docs.dopame.ai/zh/guide/assets.md) |
| `entry` | 入口: HTML 页面 (默认 `index.html`), 或默认导出 `WindowApp` 的模块. 用框架构建时不写 |
| `framework` | 怎么构建, 默认 `auto`, 见 [前端框架](https://docs.dopame.ai/zh/guide/frameworks.md) |
| `capabilities` | 申请的系统能力, 如 `{ "fs": true }`, 见 [系统能力](https://docs.dopame.ai/zh/guide/capabilities.md). 声明了就给了; 摄像头、麦克风和空闲检测还要问用户 (见 [摄像头和麦克风](https://docs.dopame.ai/zh/guide/capabilities.md#摄像头和麦克风)) |
| `optional` | `capabilities` 里应用没有也能跑的那些名字; 这个平台没有它们时应用也启动, 用动态的 `import('acde:<name>')` 取. 见 [可选能力](https://docs.dopame.ai/zh/guide/capabilities.md#可选能力) |
| `services` | 应用用到的[桌面服务](https://docs.dopame.ai/zh/guide/services.md)的名字, 如 `["clock"]`. 只有在这些服务跑着的地方应用才启动 |
| `size` | 窗口内容区的默认尺寸 `[宽, 高]`, 逻辑像素, 默认 `[800, 600]`. 不含标题栏. 桌面按这个尺寸打开窗口; `acdev dev` 单独跑一个应用时, 应用铺满宿主窗口, 宿主窗口按这个尺寸打开 (见 [窗口](https://docs.dopame.ai/zh/guide/window.md#尺寸和标题栏)) |
| `frame` | 有没有系统标题栏, 默认 `true` |
| `multiple` | 能不能同时开多个窗口 |
| `mimeTypes` | 能打开的文件类型, 如 `["text/markdown", "image/*"]`, 见 [打开应用](https://docs.dopame.ai/zh/guide/open.md#文件和链接) |
| `schemes` | 能打开的链接的 URL scheme, 小写、不带冒号, 如 `["mailto"]` |
| `requests` | 应用从别的应用的 `open()` 接受的请求种类, 如 `["show-image"]`, 见 [打开应用](https://docs.dopame.ai/zh/guide/open.md#应用) |
| `heapMb` | 每个窗口的 JS 堆上限 (MB), 默认 256, 最小 32 |
| `backend` | 后端: `false` 表示没有; `{ "entry": "server.ts", "port": 3000 }`. 默认自动找, 见 [后端](https://docs.dopame.ai/zh/guide/backend.md) |
| `public` | 原样复制的静态文件目录, 默认 `public` |
| `name` / `version` | 包名和版本, 默认取 `package.json` |
| `apiLevel` | 这个包是按哪个契约级别构建的. 不用写: `acdev build` 会写上所装 SDK 的级别 |

## 桌面 (`"type": "desktop"`)

| 字段 | 说明 |
| --- | --- |
| `id` / `label` / `description` | 桌面的 id、名字、说明 |
| `entry` | 桌面页面, 默认 `index.html` |
| `heapMb` | 桌面页面的 JS 堆上限, 默认 1024 |
| `services` | 桌面服务: 名字 → 模块路径, 用到 shell 模块的服务则是 名字 → `{ "module": 路径, "modules": [shell 模块] }`; 见 [服务](https://docs.dopame.ai/zh/guide/services.md) |
| `apps` | 这个桌面自带的应用 (系统应用), 每项和应用的字段一样, 但 `id` 和 `entry` 必填; 它的 `capabilities` 里还可以写 shell 模块, 如 `"windows": true` |

见 [桌面](https://docs.dopame.ai/zh/guide/desktop.md).

## 检查

```sh
acdev check
```

会检查: id 合法、入口文件存在、图标是认得的名字或存在的图片、服务模块存在、框架能识别. 还会按运行时的规则检查各项声明: 能力名、`fs.roots` 里的共享位置、`optional`、`services`, 以及源码里的每个 `acde:` 导入和应用声明的是否对得上. 错误让命令以 1 退出, 警告和提示只打出来.

```text
error: app "notes": fs.roots "work" is not a shared place (desktop, documents, downloads, music, pictures, videos); any other folder is one the user picks (showDirectoryPicker() with "fs": true)
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
```

`fs.roots` 里写的是路径时, 报错会给出该写的名字: `fs.roots "~/Documents" is not a shared place: write "documents", the runtime finds that folder through the system (also when it was moved)`. `optional` 里的名字不在 `capabilities` 里时, 先单独报这一条: `error: app notes: optional "launch" is not in capabilities (optional lists declared capabilities that the app can run without)`. 这一行里的应用名确实不带引号, 和上面那几行不一样; 用程序读这些行时, 两种写法都要匹配.

`acdev check --platform windows` (或 `macos`、`linux`) 再加上那个平台缺的东西: 必需的能力它没有是错误, 可选的能力它没有只是一条提示.

完整的字段定义见 [参考: acde.config.jsonc](https://docs.dopame.ai/zh/reference/config.md).
