Host 服务

发现当前 Host 的 Contract#

下表按 Contract 列出参数；生成方法没有业务参数时直接调用，例如 host.runtime.getPaths()。JSON 数据返回 unknown，按你的数据结构检查后再使用。

通过 host.services 检查正在运行的 Host。返回结果包含已注册的服务及实际参数、返回值约定，可以识别不同构建间的能力差异。

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

await host.ready();
const available = await host.services.list({ prefix: "host." });
const storageContract = await host.services.describe({
  service: "host.storage",
});
console.log(available, storageContract);

版本范围不匹配会返回 service.version_mismatch。状态为 Declared、Starting、Available 或 Unavailable；声明了服务不代表 Backend 已经运行。

运行信息与目录#

最后四项需要桌面 Host。使用返回的目录，不要硬编码用户主目录或应用数据路径。data 保存持久文件，cache 放可重建内容，temp 用于会话临时工作。

保存小型 JSON 数据#

host.storage 根据 Host 绑定的 Curio ID 隔离 key。单个序列化值上限 1 MiB，整个序列化存储上限 16 MiB。它是 JSON 存储，不是钥匙串。

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

const key = `docs-demo-${crypto.randomUUID()}`;
try {
  await host.storage.set({ key, value: { theme: "system" } });
  const saved = await host.storage.get({ key });
  console.log(saved.found, saved.value);
} finally {
  await host.storage.delete({ key });
}

key 不存在时返回 found: false, value: null；存入 JSON null 时返回 found: true, value: null。先检查 found 再解释 value。较大的数据使用 data 目录中的文件。

读写文件#

host.fs.readText({ path }) 返回 { content: string }；writeText({ path, content }) 返回 { written: true }。参数是文件系统路径，不是浏览器 URL。当前文本和二进制传输每个文件上限 4 MiB。

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

const { temp } = await host.runtime.getPaths();
const path = `${temp}/docs-${crypto.randomUUID()}.txt`;
try {
  await host.fs.writeText({ path, content: "Hello Trove" });
  console.log((await host.fs.readText({ path })).content);
} finally {
  await host.fs.remove({ path });
}

适当时通过 host.dialog 让用户选择文件。调用 Host 文件服务不代表路径被限制在 Curio 独占沙箱中；遵守用户指定的文件范围和 macOS 权限。

桌面集成#

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

console.log((await host.clipboard.readText()).text);
await host.notification.show({ title: "Export complete", body: "Your file is ready." });

剪贴板支持 readText({}) → { text }、writeText({ text }) → { written: true } 和 clear({}) → { cleared: true }。通知当前只支持 show({ title, body }) → { shown: true, curioId }。

接入以下服务前，可用 describe 获取完整参数与结果 Contract：

系统信任与子窗口#

辅助功能、输入监控、屏幕录制等系统信任由 Trove 底座管理。Curio 展示能力状态即可；需要用户处理时，跳转底座权限页，由底座执行申请或打开系统设置：

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

const { permissions } = await host.permission.list();
const accessibility = permissions.find(item => item.id === "accessibility");
if (accessibility?.status !== "allowed") {
  await host.permission.openSettings({ id: "accessibility" });
}

openSettings 接受 accessibility、input 或 screen，打开 Trove 权限页，不由 Curio 直接申请系统权限。它不是 Curio 的访问白名单，也不限制作者自行实现原生能力。

剪贴板还有 getChangeCount、readCapture、writeImage、getPastePermission 与 paste({ pid })。自动粘贴依赖 Trove 获得辅助功能授权；前台应用与权限状态来自正在运行的底座，不由 Curio 猜测。

host.window.openChild 在同一 Curio 中打开独立窗口，参数包括 id、title、query、width、height 与可选最小尺寸。同 ID 窗口复用并聚焦。子窗口内的 host.window 操作针对调用它的窗口；隐藏主窗口与后台进程是否继续运行是不同职责。

已实现与规划中的能力#

不能根据架构草案里出现的服务名推断方法可用。处理 service.not_found、service.method_not_found，并在启用功能前确认已安装的 Host 版本。

按 ID 发现 Curio#

Web SDK 用 host.curios.has/status/get/start(id)，见完整接口语义。Wire 层注册的服务为 host.curios，方法为 has、status、describe、start，参数均为 { "id": "dev.example.text-tools" }。

has 返回 boolean；status/start 返回 CurioStatus；describe 返回 { id, version, services: ServiceContract[] }，只包含公开契约。get 是 SDK 通过 describe 组装引用的便利方法，Wire 没有 get 方法。Backend 也能用 Wire 调用这组方法，再按返回的 service / method 请求公开能力。所有请求都经过调用方身份和版本检查。