Curio 开发指南

让你的想法，
有一个自己的入口。

熟悉的前端技术，加上一条通往 macOS 底座的连接。

认识 Trove

Trove 是 macOS 上的 Host。Curio 是由 Host 安装、管理和运行的工具。UI 通过 Web Plugin SDK 发起调用，Host 负责身份、权限和消息路由。SDK 不要求使用特定的 UI 框架。

下面的流程适用于已经取得 Trove 开发版的作者。公开安装包尚未发布，发布状态见下载页。查看下载页

开始开发

启动 Trove，在「开发」页面检查并安装 CLI 命令。正式版使用 trove，开发版使用 trove-dev，可以并存。
在准备存放项目的父目录执行初始化命令。向导会始终创建一个新的项目文件夹，插件 ID 默认跟随你输入的名称。
选择 Web 或静态模板；Web 模板会询问包管理器，并可安装依赖。

trove curio init

# 进入刚刚创建的文件夹
cd my-curio
trove curio dev

如果使用的是 Trove 开发版，将上述 trove 替换为 trove-dev。Web 工程需要 Node.js 与所选包管理器；静态模板不需要前端构建步骤。

四个核心命令

命令	负责什么
`trove curio init`	交互式创建目录、清单与示例代码。
`trove curio check`	检查项目配置、声明和开发所需依赖。
`trove curio dev`	连接 Host，启动当前插件的开发会话。
`trove curio pack`	构建并校验发布内容，生成 .curio 安装包。

在不同插件目录的终端分别运行 dev，即可同时开发多个插件。具体参数可通过 trove curio <command> --help 查看。

连接 SDK

初始化模板已配置 @trove/plugin-sdk。导入客户端，等待连接就绪，再按“服务 ID、方法名、参数”发起调用：

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

await trove.ready()

const host = await trove.call(
  "host.runtime",
  "getHostInfo",
  {},
  { timeoutMs: 5_000 },
)

console.log(host)

这个示例返回当前 Host 的版本、平台与架构信息。直接在普通浏览器打开页面时，没有 Host 注入的桥接连接；请通过 trove curio dev 在 Trove 中运行。

插件之间通讯

同一套 SDK 也能调用另一个 Curio 提供的服务。例如截图插件把图片交给 OCR 插件识别，Host 负责定位服务、路由请求和返回结果。

// 概念示例：需要先安装提供该服务的 OCR Curio
await trove.ready()
const result = await trove.call(
  "ink.example.ocr.recognition",
  "recognize",
  { imagePath: sharedImagePath },
  { timeoutMs: 10_000 },
)
console.log(result)

提供方在 services.provides 中声明服务 ID、版本与契约，并由 Backend 实现处理逻辑。消费方在 services.requires 中声明依赖。服务 ID 必须位于提供方的 Curio ID 命名空间内。

// 调用方 curio.json 的 services 字段
"services": {
  "requires": [{
    "id": "ink.example.ocr.recognition",
    "version": "^1.0.0",
    "optional": false
  }]
}

Service Bus 的跨插件路由已实现。这里的 OCR 服务与参数是说明性契约，不代表已有可安装的官方 OCR 插件。图片路径需要双方明确约定并能访问；服务调用不会自动转移文件访问授权。@self 只连接插件自己的 Backend，不能用于插件间公开通讯。

由宿主承接系统能力

辅助功能与屏幕采集的设计是：用户向 Trove 授予 macOS 权限，由 Host 执行系统调用。通过 Host 服务调用的 Curio 复用 Trove 的授权身份，无需每个插件再次向系统申请同一项权限。

宿主服务	用途	当前状态
`host.accessibility`	读取焦点元素、查询界面、执行辅助操作	规划中；已有权限检测
`host.screen`	屏幕与窗口采集	规划中；已有权限检测

// 架构示例：以下两个服务尚未接入当前 Host
const element = await trove.call(
  "host.accessibility", "getFocusedElement", {},
)

const capture = await trove.call(
  "host.screen", "captureDisplay",
  { displayId: selectedDisplayId },
)

复用授权的前提是操作由 Host 执行。插件 Backend 直接调用系统 API 时，仍受自身的 macOS 身份与权限约束。系统权限可能被用户撤销，调用方需处理未授权与调用失败。实时录屏流也不能视为当前版本已提供的能力。

打包与分发

trove curio check
trove curio pack

pack 依据项目构建配置生成并验证产物，剥离开发配置，按文件清单打包。包含原生后端时，需要适用于目标平台的自包含可执行文件；Host 不捆绑 Node.js 或 Python 运行时。

软件源以 index.json 描述插件版本和平台产物，包含下载 URL、大小及 SHA-256。发布时先上传安装包，再发布索引，保证用户看到的版本可以下载。

了解 Curios

文档基于当前 v0.1.0 开发实现。命令参数以安装版本的 --help 为准。

让你的想法，有一个自己的入口。