Relune TypeScript Guest SDK

@relune/plugin-guest 为 TypeScript 插件提供与 Client 合同一致的 WIT 类型、manifest schema 和少量纯 JavaScript 辅助函数。SDK 不包含 SpiderMonkey、WASI 适配器或插件运行时。

依赖

插件项目推荐固定 SDK 版本：

{
  "dependencies": {
    "@relune/plugin-guest": "1.1.0"
  }
}

import { paragraphJson, utf8ContentText, utf8Text } from "@relune/plugin-guest";
import type { ProcessorWorld } from "@relune/plugin-guest";
import { hashXxh364 } from "relune:client-plugin/[email protected]";

WIT worlds 与契约规范

SDK 使用 jco guest-types 从 wit/plugin.wit 为 processor-plugin 和 connector-plugin 两个 world 生成 TypeScript 声明。WIT 包为 relune:[email protected]；清单规范为 Plugin Spec 1.1（specVersion: "1.1"），模式文件位于 schema/plugin-manifest.schema.json。

ProcessorWorld 和 ConnectorWorld 类型分别描述两个 world 的导出。最小 TypeScript 示例保存在仓库的 examples/ 目录。

process(host, content, request) 中的 content 是可选只读资源，不在请求中包含文件字节。readContentAll / utf8ContentText 以最多 64 KiB 的重复 range 读取实现有界完整读取，必须由调用方指定文件长度上限。输出通过 host.createContentWriter(maxBytes)、分块 write、seal 创建只读资源；children 用 childCandidates 与 childContents 按序配对，人脸输出使用 typed faceDetections 和平行的 faceCrops。paragraphJson 生成 DocumentBlock schemaVersion: 2 的段落 JSON；utf8Text 对 guest 自有 Uint8Array 执行严格 UTF-8 解码。指纹哈希须调用 world 导入的 relune:client-plugin/utils hashXxh364，由宿主提供。

Guest 运行边界

组件必须只实现对应 world，不启用 WASI；构建使用 jco componentize --disable all。运行时只有 WIT host 和 utils 导入，没有 Node.js 运行时能力。插件逻辑不可调用 Node.js fs、http 等 Node 内建模块。