Host 服务
发现当前 Host 实际提供的 API，查阅常用能力的参数、返回值和完整示例。
核对日期：2026 年 9 月 11 日
本页目录
发现当前 Host 的 Contract#
通过 host.services 检查正在运行的 Host。返回结果包含已注册的服务及实际参数、返回值约定，可以识别不同构建间的能力差异。
import { trove } from "@trove/plugin-sdk";
await trove.ready();
const available = await trove.call("host.services", "list", { prefix: "host." });
const storageContract = await trove.call("host.services", "describe", {
service: "host.storage",
});
console.log(available, storageContract);
| 方法 | 参数 | 返回值 |
|---|---|---|
list | { prefix?: string } | { services: [{ id, version, provider }] } |
describe | { service: string, version?: string } | { descriptor, contract } |
resolve | { service: string, version?: string } | { id, version, provider } |
getStatus | { service: string, version?: string } | { id, version, state } |
版本范围不匹配会返回 service.version_mismatch。状态为 Declared、Starting、Available 或 Unavailable；声明了服务不代表 Backend 已经运行。
运行信息与目录#
| 方法 | 参数 | 返回值 |
|---|---|---|
echo | 任意 JSON 值 | 原样返回 |
getHostInfo | {} | { name, version, platform, arch, protocol } |
getContext | {} | 当前 Curio 身份与运行模式 |
getPaths | {} | { data, cache, logs, temp }，均为绝对路径 |
openCurio | { id } | { ok: true } |
closeSelf | {} | { ok: true } |
revealPath | { path } | { ok: true } |
openUrl | { url } | { ok: true } |
最后四项需要桌面 Host。使用返回的目录，不要硬编码用户主目录或应用数据路径。data 保存持久文件，cache 放可重建内容，temp 用于会话临时工作。
保存小型 JSON 数据#
host.storage 根据 Host 绑定的 Curio ID 隔离 key。单个序列化值上限 1 MiB，整个序列化存储上限 16 MiB。它是 JSON 存储，不是钥匙串。
| 方法 | 参数 | 返回值 |
|---|---|---|
set | { key: string, value: JSON } | { stored: true } |
get | { key: string } | { value: JSON, found: boolean } |
delete | { key: string } | { deleted: boolean } |
list | { prefix?: string } | { keys: string[] } |
clear | {} | { cleared: true } |
const storage = trove.service("host.storage");
const key = `docs-demo-${crypto.randomUUID()}`;
try {
await storage.call("set", { key, value: { theme: "system" } });
const saved = await storage.call<{
found: boolean;
value: { theme: string } | null;
}>("get", { key });
console.log(saved.found, saved.value);
} finally {
await storage.call("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。
const { temp } = await trove.call<{ temp: string }>("host.runtime", "getPaths", {});
const path = `${temp}/docs-${crypto.randomUUID()}.txt`;
try {
await trove.call("host.fs", "writeText", { path, content: "Hello Trove" });
const file = await trove.call<{ content: string }>("host.fs", "readText", { path });
console.log(file.content);
} finally {
await trove.call("host.fs", "remove", { path });
}
| 方法 | 参数 | 返回值 |
|---|---|---|
stat | { path } | { type, size, modifiedUnixMs } |
list | { path } | { entries: [{ name, path, type }] }，最多 20,000 项 |
exists | { path } | { exists: boolean } |
readBinary | { path } | { data: string }，Base64 编码 |
writeBinary | { path, data } | { written: true }，data 为 Base64 |
createDirectory | { path } | { created: true } |
copy / move | { from, to } | { copied: true } / { moved: true } |
remove | { path, recursive?: boolean } | { removed: true } |
createTempFile | {} | { path: string } |
适当时通过 host.dialog 让用户选择文件。调用 Host 文件服务不代表路径被限制在 Curio 独占沙箱中；遵守用户指定的文件范围和 macOS 权限。
桌面集成#
const clipboard = await trove.call<{ text: string }>("host.clipboard", "readText", {});
console.log(clipboard.text);
await trove.call("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：
| 服务 | 已注册方法与事件 |
|---|---|
host.window | show、hide、close、focus、getBounds、setBounds、center、setTitle、setAlwaysOnTop、setResizable、setDecorations、setIgnoreCursorEvents |
host.dialog | openFile、openDirectory、saveFile、message、confirm |
host.application | listInstalled、listRunning、launch、activate、terminate、open、getFrontmost |
host.shortcut | register、unregister、listSelf；triggered 事件 |
已实现与规划中的能力#
| 能力 | 当前实现 |
|---|---|
| 运行信息、服务发现、存储、文件系统 | 已实现 |
| 窗口、对话框、文本剪贴板、通知、应用管理、快捷键 | 桌面 Host 已实现，以实际 Contract 为准 |
host.clipboard.readFiles/writeFiles/getChangeCount | 仅草案 |
host.notification.remove/removeAllForCurio | 仅草案 |
host.fs.watch | 仅草案 |
host.process、host.accessibility、host.input、host.screen、host.keychain | 规划中，当前构建未注册 |
不能根据架构草案里出现的服务名推断方法可用。处理 service.not_found、service.method_not_found，并在启用功能前确认已安装的 Host 版本。