创建第一个 Curio

开始前的准备#

你需要 macOS，以及一个已经获得的、可以运行的 Trove 构建。在 Trove 的开发页面安装或检查命令行工具，打开新终端，确认可执行文件可用：

trove --version
trove curio --help

Web 模板需要 Node.js 20.19+ 或 22.12+，以及你选择的包管理器。以下步骤使用 npm。静态模板不需要 Node、Rust 或依赖安装。目前公开安装包尚未发布。

创建并运行工程#

在准备存放新项目的父目录执行下面的命令。my-curio 必须不存在，即使已有目录为空也不能使用。

trove curio init my-curio --name "My Curio" --id dev.example.my-curio --template web --package-manager npm --yes
cd my-curio
npm install
trove curio check
trove curio dev

--yes 接受默认配置，不会自动安装依赖。也可以执行 trove curio init 进入交互问答，选择 Web 与包管理器，然后按生成的提示继续。

CLI 会启动或连接 Host，启动 UI 开发服务，并打开 Curio 窗口。保持终端运行。起始页展示 Host 连接状态，并提供通讯和存储两个示例按钮；调用成功后，页面和 Console 显示真实响应。

找到需要修改的文件#

模板支持系统深浅色。复用模板界面时，保留生成的组件许可证和第三方声明。

完成第一次调用#

把下面代码放在前端模块或异步事件处理函数中。echo 会原样返回你发送的 JSON 值。

import { trove } from "@trove/plugin-sdk";

await trove.ready();
const result = await trove.call<{ message: string }>(
  "host.runtime",
  "echo",
  { message: "Hello from my Curio" },
  { timeoutMs: 5_000 },
);
console.log(result.message);
console.log(trove.context.curioId);

预期输出为 Hello from my Curio，随后是 dev.example.my-curio。将响应显示到页面，并处理 Promise 拒绝；SDK 错误处理提供完整写法。修改 Web 模板后，Vite 开发服务会更新窗口中的页面。

在普通浏览器打开页面不会注入 Host Bridge。真实原生调用必须在 Trove 窗口中运行。浏览器测试应显式使用 Mock Bridge。

构建并验证安装包#

先按 Ctrl-C 停止开发会话，再执行：

trove curio pack
trove curio install

产物位于 dist/packages/<id>-<version>-<target>.curio。只有一个候选包时，install 会自动选择。保持开发服务器停止，在 Trove 中打开已安装的 Curio，再次执行通讯示例，确认生产入口与打包资源正确。

不使用构建工具的起点#

trove curio init my-static-curio --template static --yes
cd my-static-curio
trove curio check
trove curio dev

静态模板把 UI 和 SDK 放在 ui/index.html。修改文件后重新加载 Curio 窗口；它没有 Vite 热更新。如果需要直接编辑 JSX、样式源文件和 SDK import，选择 Web 模板。接下来阅读本地开发指南。