Manifest 参考

在 curio.json 中声明身份、UI、Backend、服务依赖和打包内容。

核对日期：2026 年 9 月 11 日

本页目录

完整的 UI Manifest#

把 curio.json 放在工程根目录。以下示例采用 Web 模板的输出路径：

json

{
  "schemaVersion": 1,
  "id": "dev.example.notes",
  "name": "Notes",
  "description": "A small desktop notebook.",
  "version": "0.1.0",
  "engine": { "trove": ">=0.1.0 <1.0.0" },
  "ui": {
    "entry": "dist/ui/index.html",
    "window": { "title": "Notes", "width": 900, "height": 640 }
  },
  "development": {
    "ui": { "url": "http://127.0.0.1:0", "command": ["npm", "run", "dev"] }
  },
  "build": { "command": ["npm", "run", "build"] },
  "package": { "files": ["dist/ui"] }
}

端口 0 要求开发服务读取 TROVE_DEV_PORT。修改后执行 trove curio check。可下载 Manifest JSON Schema 接入编辑器，但仍需 CLI 的语义检查。

身份与兼容范围#

字段	必需	规则
`schemaVersion`	是	固定为 `1`
`id`	是	3–160 字符，小写字母、数字、点、短横线；首尾为字母或数字，不能使用 `host.`、`trove.` 前缀
`name`	是	显示名称，1–100 字符
`version`	是	语义化版本，如 `0.1.0`
`engine.trove`	是	支持的 Host 版本范围
`description`	否	最多 1,000 字符
`icon`	否	包内图片的相对路径，文件必须进入打包清单

Manifest 至少包含 ui 或 backend，也可以同时包含两者。Curio 版本、服务版本和 Schema/协议版本是不同值。修改 Curio ID 会改变身份，包括存储命名空间。

UI 与窗口#

声明 ui 时必须提供 ui.entry，指向相对 Curio 根目录的包内 HTML 文件。可选 ui.window 字段如下：

字段	值与范围
`title`	字符串，最多 200 字符
`width`、`height`	整数，宽 240–10,000，高 160–10,000
`minWidth`、`minHeight`	整数，宽 120–10,000，高 80–10,000
`resizable`、`transparent`、`alwaysOnTop`	布尔值

路径规范化后必须留在包内。绝对路径、父目录越界、指向包外的符号链接不能作为发布入口。

Backend 生命周期#

以下片段要求 backend/notes 是实际存在的可执行文件：

json

{
  "backend": {
    "entry": "backend/notes",
    "args": [],
    "transport": "unix",
    "lifecycle": "on-demand",
    "startWithUi": true,
    "startupTimeoutMs": 10000,
    "shutdownGraceMs": 2000,
    "idleTimeoutMs": 0
  }
}

entry、transport、lifecycle 必需。transport 固定 unix。on-demand 在需要时启动，关闭 Curio UI 后停止其 Backend 和子进程；app-start 随 Host 启动，可以在 UI 关闭后继续运行。startWithUi 默认 false。

启动超时默认 10,000 ms，允许 100–300,000；关闭宽限默认 2,000 ms，允许 0–60,000；空闲超时默认 0，允许 0–86,400,000。args 是字符串数组；可选 env 为具名字符串值。会话凭据由 Host 注入，不要硬编码。详见 Backend 接入。

服务与契约#

services.provides 的每项包含 { id, version, contract }。对外提供服务要求存在 Backend，服务 ID 必须位于 Curio ID 命名空间下。contract 是相对路径 JSON 文件，内部 service/version 要与声明一致。

services.requires 的每项包含 { id, version, optional? }。这里的 version 是兼容范围，optional 默认 false。可选依赖不会自动安装或实现服务，UI 需要处理服务缺失。详见服务示例。

开发与打包配置#

字段	含义
`development.ui.url`	使用 localhost 或 127.0.0.1 的本地 HTTP(S) 开发地址
`development.ui.command`	可选的 UI 启动 argv 数组
`development.ui.readyTimeoutMs`	默认 20,000 ms，范围 100–300,000
`development.backend.mode`	`managed` 或 `external`
`development.backend.command`	managed 模式必需，包含可执行文件与参数
`build.command`	打包暂存前执行的可选 argv 数组
`package.files`	明确的相对文件、目录清单，不支持 glob

命令是数组，不是隐式 Shell 字符串。需要 Shell 行为时显式使用 ["/bin/sh", "build.sh"]。发布包会去除 development、build、package 配置，不改写源文件。

未知 Manifest 字段会被拒绝。Schema 无法证明构建入口存在且可执行，pack 会对暂存的生产文件执行实际检查。详见打包与分发。