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.0.1-alpha.1 <0.0.2" },
  "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 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 在需要时启动。已安装窗口关闭时，仅私有的 on-demand Backend 和子进程会停止；声明了公开服务的 Backend 独立于窗口继续服务其他 Curio。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 为具名字符串值。idleTimeoutMs 为 0 时不做空闲回收；活跃调用和订阅保持进程忙碌。关闭开发窗口会结束该开发会话。会话凭据由 Host 注入，不要硬编码。详见 Backend 接入。

服务与契约#

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

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

Alpha 阶段的 Host 与引擎兼容版本统一为 0.0.1-alpha.1。当前 Curio 使用 >=0.0.1-alpha.1 <0.0.2；Manifest/schema 与 Wire 帧版本仍独立演进。

开发与打包配置#

字段	含义
`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 模式可选 argv；省略时使用生产 Backend 入口和 args
`build.command`	打包暂存前执行的可选 argv 数组
`package.files`	明确的相对文件、目录清单，不支持 glob

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

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

契约与客户端生成#

原生模板已配置私有契约与输出位置。下例为字段片段：contract:export 必须是工程中真实的脚本，公开服务契约需由提供者交付。

json

{
  "backend": {
    "entry": "dist/backend/curio-backend",
    "transport": "unix",
    "lifecycle": "on-demand",
    "contract": "contracts/backend.json"
  },
  "bindings": {
    "generate": [
      "npm",
      "run",
      "contract:export"
    ],
    "backend": "src/generated/backend.ts",
    "services": [
      {
        "curio": "dev.example.text-tools",
        "contract": "contracts/text-tools.json",
        "output": "src/generated/text-tools.ts"
      }
    ]
  }
}

backend.contract 描述当前插件私有 Backend，不会自动公开服务。bindings.generate 是可选的导出命令 argv；bindings.backend 是私有客户端输出路径；bindings.services 将公开服务契约映射到客户端文件。

trove generate、dev、pack 执行导出和生成。check 只验证当前契约及输出，过期时报告 bindings.stale。路径相对工程根目录，不能越界。bindings 仅用于开发，会从发布 Manifest 中剥离。

backend.contract 和 bindings.backend 是可选的私有 RPC 便利配置，纯公开 Backend 或作者自有的内部通信层不需要它们。bindings.services[].curio 可选，指定公开契约的拥有者 ID，并生成 SDK CurioRegistry 类型声明；bindings.curios 可覆盖默认路径 src/generated/curios.d.ts。这些字段不会安装提供者，也不声明版本要求，见服务引用。