Persona

@laplace.live/persona-sdk 是 Persona 插件 API 的官方 TypeScript/JavaScript 客户端，同时提供通信传输 Schema 的类型定义。本页面为完整的类型与 API 参考；有关服务端配置、密钥生成以及可用 RPC 方法的详细说明，请参阅 插件 API。

该 SDK 兼容 Node.js 22+、Bun、现代 Web 浏览器以及 OBS 浏览器源等运行环境。其唯一的运行时依赖为 zod，用于定义并校验传输 Schema。

npm install @laplace.live/persona-sdk

你能用它做什么复制锚点链接

Persona Console 是基于该 SDK 构建的官方参考实现。它提供了一个全功能的 Web 控制台，可在单一浏览器标签页内集中管理场景、图层、素材库、表情、动作、参数映射、快捷键、捕捉源以及全局系统设置，其界面针对直播演播期间的移动端与触控操作进行了专门优化。

该控制台完全基于插件 API 构建，未引用任何桌面端专有代码，开发者可使用相同的 SDK 实现同等深度的控制能力。

开发客户端时建议遵循以下设计原则：

• 基于功能能力判断，而非格式或版本号：各实例控件应在读取 InstanceRuntime.capabilities 后按需启用或禁用，避免盲目调用导致 unsupported-for-format 错误；
• 断线重连视为状态重置：WebSocket 连接断开期间错过的广播事件不会重放，本地缓存可能与服务端最新状态脱节，重连建立后应清空本地缓存并重新拉取完整状态快照；
• 妥善处理终止性连接关闭码：状态码 4001（密钥失效/吊销）与 4002（服务端强制踢出）属于终止性关闭，应停止自动重连重试；其他异常关闭则建议执行指数退避重连；
• 事件订阅由 SDK 托管：通过 persona.on(…) 注册的事件监听器将在重连成功后自动重新订阅，业务代码无需手动维护重连后的监听生命周期。

LLM 提示词复制锚点链接

可将以下 Prompt 提供给 LLM 或加入项目的 CLAUDE.md / AGENTS.md 规则文件中，作为插件开发的完整上下文指引：

You are helping me build a plugin for LAPLACE Persona, a desktop VTuber app
(https://laplace.live/persona). Persona exposes a local WebSocket server called the
Plugin API, and `@laplace.live/persona-sdk` is its typed client.

Before writing any code, fetch the reference documents listed at the end — they are
the single source of truth for method names, events, error codes and types. Do not
rely on memory and do not invent names.

## Setup

- Install `@laplace.live/persona-sdk`. Isomorphic: Node 22+, Bun, browsers and OBS
  browser sources. Its only runtime dependency is zod.
- The user enables the server in Persona under Settings → Plugin API and creates an
  API key there. Tokens look like `sk-lp-v1-…`. Default endpoint: `ws://127.0.0.1:25034`.
- Everything — values and types — is exported from the package root; there is no
  other entry point.

## Client

```ts
import { PersonaClient } from "@laplace.live/persona-sdk";

const persona = new PersonaClient({
  token: "sk-lp-v1-…", // required; everything else is optional
  clientInfo: { name: "My Plugin", version: "1.0.0" }, // display-only identity
});
await persona.connect();

const { scenes, activeSceneId } = await persona.call("scene.list");
await persona.call("scene.patch", {
  background: { mode: "color", color: "#00ff00", imageAssetId: null },
});
persona.on("motion.started", (m) => console.log("playing", m.group));

const mouth = persona.driveParameter("MouthOpen", 0.8); // parameter lease
mouth.set(0.3);
mouth.release();
```

`call(method, params?)` is fully typed — the method name determines the request and
response shapes.

Methods cover scenes, model instances, stage objects, expressions, motions, speech,
hotkeys, automations, model and asset registration, settings, tracking and pose
input, per-key storage and parameter injection. Events notify you of scene,
selection, expression, motion, speech, tracking and registry changes.

The exact method and event names, parameter shapes, error codes and limits live in
the reference below — look them up instead of guessing. Gate features on the
capabilities reported by `app.info` and `instance.list`, never on version strings.

## Reference

Fetch these before writing code. The documentation is served as raw Markdown —
append `.mdx` to any page URL (`.en.mdx` for English):

- https://laplace.live/persona/plugin-api.en.mdx — server setup, API keys, and every
  method, event, error code and limit
- https://laplace.live/persona/sdk.en.mdx — the SDK client: options, auth modes and
  every exported type

客户端复制锚点链接

import { PersonaClient } from "@laplace.live/persona-sdk";

const persona = new PersonaClient({ token: "sk-lp-v1-…" });
await persona.connect();

const { scenes, activeSceneId } = await persona.call("scene.list");
await persona.call("scene.patch", {
  background: { mode: "color", color: "#00ff00", imageAssetId: null },
});
persona.on("motion.started", (m) => console.log("playing", m.group));

PersonaClient 支持通过配置选项创建实例，其中仅 token 为必填项：

ClientInfo复制锚点链接

clientInfo 用于向 Persona 声明客户端的身份标识，该标识将显示在客户端设置界面的已连接的客户端列表中。此字段为可选的声明性元数据，仅用于界面呈现，不参与鉴权逻辑。SDK 在每次断线重连时均会自动重新上报该信息。

const persona = new PersonaClient({
  token,
  clientInfo: { name: "My Overlay", version: "1.2.0", developer: "You" },
});

认证配置复制锚点链接

在浏览器环境中，API Token 统一通过 ?token= URL 查询参数传递（受限于浏览器 WebSocket API 的实现）。在 Node.js 或 Bun 等服务端环境中，可通过自定义 createWebSocket 钩子注入 Authorization: Bearer 请求头（配合 ws 等客户端库）：

import WebSocket from "ws";

const persona = new PersonaClient({
  token,
  auth: "header",
  createWebSocket: (url, headers) => new WebSocket(url, { headers }),
});

WebSocketLike 定义了 createWebSocket 必须返回的 Socket 抽象接口。全局 WebSocket 实例与 ws 客户端均在结构上完全满足该类型约束，无需额外的类型断言。

在 Node.js 22+ 中，全局 WebSocket 可以通过 WebSocketInit 扩展发送握手请求头。SDK 提供的 createNodeClient 辅助函数基于它创建客户端：

• 设置 auth: 'header'
• 使用 Node 的全局 WebSocket
• 将连接超时设为 5 秒
• 将 SDK 警告与终止性关闭（如 API Key 被吊销或被服务端强制断开）输出到传入的 log 函数

import { createNodeClient } from "@laplace.live/persona-sdk";

const persona = createNodeClient({
  token: "sk-lp-v1-…",
  log: console.warn,
});
await persona.connect();

参数租约驱动复制锚点链接

driveParameter 用于持续向模型参数写入目标值，并返回一个 InjectionHandle 控制句柄。SDK 在后台自动维系租约心跳，参数租约在最后一次写入约 1 秒后自动过期并平滑恢复默认值，从而避免客户端进程异常退出时导致参数僵死。

const mouth = persona.driveParameter("MouthOpen", 0.8);
mouth.set(0.3);
mouth.release();

同一模型参数在同一时间段内仅允许由单个会话独占租借；其他会话尝试重复租借将触发 conflict 错误。

该方法还支持传入可选的 weight（权重）以及 onError 异常回调函数。当后台心跳续租失败时将通过回调通知，无需在每次更新参数时调用 await。

连接关闭处理复制锚点链接

onClose 在服务端或网络导致连接关闭时触发。回调参数包含原始 Socket 关闭码、关闭原因，以及表示是否已停止重连的 terminal 标志。

• 回调在客户端重置内部状态并清理待决请求之后才触发，因此可以在回调中安全地调用 close()。
• 客户端主动调用 close() 不会触发 onClose。
• 配置 onClose 后，终止性关闭改由它上报，不再经过 onWarning。

PersonaClientState 与客户端错误复制锚点链接

type PersonaClientState = "closed" | "connecting" | "open" | "reconnecting";
type ClientErrorReason =
  | "connect-timeout"
  | "connection-closed"
  | "client-closed"
  | "not-connected"
  | "request-timeout";

当客户端自身或底层传输层无法完成 connect() 或 call() 时，Promise 会以 PersonaClientError 拒绝（带有 reason: ClientErrorReason，取值见 CLIENT_ERROR_REASONS）；服务端返回的错误帧则以 PersonaApiError（带有 code: ApiErrorCode）拒绝 call()。详见 插件 API：错误代码。

常量定义复制锚点链接

SDK 还导出了以下取值列表与辅助函数：

• API_ERROR_CODES、CLIENT_ERROR_REASONS、EVENT_NAMES、INPUT_NAMES、TIME_INPUT_NAMES、RANDOM_PULSE_INPUT_NAMES、MODIFIER_TOKENS、APP_CAPABILITIES、FPS_LIMIT_PRESETS、EFFECTS_QUALITY_LEVELS：as const 数组，便于在 UI 选择器中列出全部合法取值
• isApiErrorCode、isEventName、isAppCapability、isTimeInputName、isRandomPulseInputName：对应的 TypeScript 类型守卫
• injectTargetKey：生成标准化的注入目标标识符
• personaWsUrl：根据 { host, port, secure }（PersonaAddress，其中 host 须为纯主机名或 IP 地址）或用户输入的地址字符串（支持纯主机名、host:port、IPv4/IPv6 地址以及完整的 ws:// / wss:// URL）生成 WebSocket URL；API Token 由 PersonaClient 在连接时自动附加
• parseHost、parsePort、isValidPort：校验纯主机名/IP 地址（支持带或不带方括号的 IPv6，含协议、端口、路径或区域 ID 时返回 null）与端口号
• requestTimeoutMs(method, fallbackMs)：按方法名计算请求超时时间（scene.activate 与 asset.import 自动采用各自的长超时）

模型与素材复制锚点链接

模型与通用素材共享统一的元数据定义。kind 用于标识条目的资源类型，origin 用于标识其来源：bundled 表示应用内置资源或桌面端从 Persona 目录按需下载的资源，user 表示用户本地注册的文件，同时包含清单中声明的创作者署名信息。

type ModelFormat = "live2d" | "vrm";
type ContentOrigin = "bundled" | "user";
type AssetKind =
  | "image"
  | "video"
  | "audio"
  | "prop"
  | "ibl"
  | "lut"
  | "animation"
  | "cameraMotion"
  | "lyrics";
type InventoryKind = ModelFormat | AssetKind | "effect" | "addon";

effect 属于特殊的虚拟资产类型，不对应实际磁盘文件，素材库通过它枚举系统支持的 内置特效；addon 则代表扩展应用程序本身的可选附加组件（如 摄像头追踪附加组件），不会作为图层进入场景。

model.list 返回 ModelRef 数组，asset.list 返回 AssetRef 数组。二者都是 ContentRef，kind 分别收窄为 ModelFormat 与 AssetKind。

二者还带有布尔字段 exists：AssetRef 的文件在磁盘上被移动或删除后，该字段为 false；ModelRef 在模型入口文件丢失时同样为 false。

CatalogItem复制锚点链接

CatalogItem 提供了脱离具体传输协议的内容元数据抽象模型，本地注册表条目与远程资源目录均转换为此统一结构。它在 ContentRef 基础上移除了未安装状态下的 origin 字段，并扩展了多语言简介 description（LocalizedText）与目录检索属性。download（CatalogDownload）描述未安装条目的下载源信息；若该字段为空，表示该资产已存在于本地环境。

目录与多语言辅助项：

• CATALOG_FORMAT、MARKETPLACE_ITEMS_PATH、CATALOG_KINDS：目录清单格式版本号、公开目录 API 路径（/api/items）与目录支持的条目类型列表
• isCatalogId、healCatalog、healCatalogItem、healCatalogRows、healSha256：校验并规范化远程或本地目录清单数据
• payloadEntryPath、payloadEntryKey、catalogMediaFile（参数为 CatalogMediaRole）：计算解压后的目录资源入口路径，以及源目录下预渲染缩略图与预览视频的文件名（.thumbnail.avif 与 .preview.webm）
• pickLocalized(text, locale)、healLocalizedText：按当前界面语言从 LocalizedText 中选取匹配的展示文案并规范化多语言对象

空间排版与放置复制锚点链接

2D 屏幕空间以像素为单位，以舞台视窗中心为坐标原点（+y 轴向下）；3D 世界空间以米为单位。传输协议中所有旋转分量均严格采用弧度制表示（控制面板上为便于直观理解以角度呈现）。

Place2D 与 Place3D 为物体道具对应的排版类型，字段结构相同并额外包含 opacity 不透明度属性。

场景条目复制锚点链接

场景配置中的 items 数组依据渲染深度（Z-order）混合管理模型与物体图层：

type SceneItem = SceneModelItem | SceneObjectItem;

ObjectContent复制锚点链接

物体图层承载的实际内容结构依据 kind 字段区分。除 capture（屏幕采集）外，其余类型均可在桌面端界面中直接创建，详见 图层管理。

type ObjectContent =
  | { kind: "image"; assetId: string }
  | {
      kind: "video";
      assetId: string;
      loop: boolean;
      muted: boolean;
      volume: number;
    }
  | { kind: "prop"; assetId: string }
  | {
      kind: "web";
      url: string;
      width: number;
      height: number;
      fps: number;
      transparent: boolean;
      css: string;
      layer: WebLayer;
      shutdownWhenHidden: boolean;
    }
  | { kind: "capture"; source: CaptureKind; sourceId: string; label: string };

type ObjectSpace = "2d" | "3d";
type WebLayer = "behind" | "front";
type CaptureKind = "display" | "window";

钉附系统复制锚点链接

AttachAnchor复制锚点链接

type AttachAnchor =
  | { kind: "root" }
  | { kind: "bone"; bone: string }
  | {
      kind: "artMesh";
      id: string;
      verts: [number, number, number];
      weights: [number, number, number];
    };

object.anchors 返回父级对象可供绑定的挂载锚点列表（以 AnchorOption 结构呈现，包含锚点 ID 及对应的可读名称）。VRM 模型提供根节点及人形骨骼节点；Live2D 模型提供根节点及各 ArtMesh 部件，并带有 order 绘制层级序号。

AttachDepth复制锚点链接

type AttachDepth =
  { kind: "front" } | { kind: "behind" } | { kind: "artMesh"; id: string };

depth 用于控制 Live2D 道具 在父模型内部的渲染层深，可置于模型后方、前方，或指定 ArtMesh 的正上方。该属性仅适用于附着到 Live2D 父模型的 Live2D 实例，通过 instance.attach 配置。

钉附相关的辅助函数：

• depthStops(meshes)：由后到前列出可选的深度挡位（模型后方、按绘制顺序排列的各 ArtMesh 上方、模型前方）
• depthStopIndex(meshes, depth)：计算某个深度位于哪个挡位；关联的 ArtMesh 已不存在时按最顶层处理
• pinRiders(items, instanceId)：递归找出直接或间接附着在 instanceId 上的所有实例，用于防止循环附着
• pinnableParents(models, items, instanceId)：生成父级候选列表，并用 ridesThis 标记须禁用的非法项
• defaultAttach(parentInstanceId, screenSpace?)：生成默认附着配置（绑定根节点、位于模型最前方、不切分部件、无动态物理参数）；设置 screenSpace（Live2D 模型或 2D 物体）时，还会以默认响应跟随父模型头部转动

场景配置复制锚点链接

背景设置复制锚点链接

type BackgroundMode = "color" | "image";

相机设置复制锚点链接

cameraDistanceLimits(environment, radius) 计算轨道相机在鼠标导航时允许的距离范围。默认最小、最大距离分别为 DISTANCE_MIN（0.35 米）与 DISTANCE_MAX（20 米）；3D 环境的包围尺寸明显大于或小于标准空间（约 10 米跨度）时，限制会按比例缩放。radius 是 3D 场景的包围球半径，即 scene.inspect 返回的 environment.radius；场景加载完成前为 null，此时返回默认限制。

灯光系统复制锚点链接

type SceneLightType = "directional" | "point" | "ambient" | "area" | "spot";
type ShadowQuality = "off" | "low" | "medium" | "high" | "ultra";
type ShadowFilter = "pcf" | "pcss";

SCENE_LIGHT_TYPES、SHADOW_QUALITY_LEVELS 和 SHADOW_FILTERS 以 as const 数组提供光源类型、阴影档位和过滤方式，顺序与面板中的一致。

SceneLight 的以下三个字段让灯光跟随相机：

• followCamera：将光源的位置与旋转绑定到相机坐标系
• followCameraOptions：选择哪些运动自由度跟随相机；DEFAULT_LIGHT_FOLLOW_CAMERA_OPTIONS 启用全部
• followCameraReference：不跟随的维度所使用的固定参考变换

若要在不改变灯光实际照射角度的前提下切换跟随状态，请调用 scene.setLightFollowCamera，不要直接修改这些字段，详见 灯光系统。

iblAssetId 与 modelAssetId 分别指定环境贴图（IBL）与 3D 场景模型；具备 environment-map-model 能力的应用版本可以同时使用二者。

• 更新环境时建议使用 environmentWithAsset()：它设置新的资源、保留另一项现有资源，并清理与旧场景绑定的灯光覆盖项。
• 选中环境贴图会自动关闭 bakeFromModel；只有此前两项均为空时，加载新 3D 场景才会默认开启烘焙。
• environmentClearPatch(environment, slot) 生成清除 'model' 或 'map' 的补丁；slot 为 null 时两者都清除。
• applyEnvironmentLighting() 与 applyEnvironmentLook() 对应面板中的快捷操作，分别用于启用环境灯光与整体应用 EnvironmentLook 视觉风格。

体积光照按光源单独开启，通过 SceneLight.volumetric 配置。相关辅助项：

• SCENE_VOLUMETRIC_LIGHTING_SPECS：体积雾各滑块的取值范围
• defaultSceneVolumetricLighting()：默认的体积雾配置
• healSceneVolumetricLighting()：将越界参数钳制到合法范围
• sceneLightCanHaze(type)：判断某种光源类型能否产生体积光
• sceneLightHazes(light)：判断某个光源当前是否正在产生体积光

特效系统复制锚点链接

SceneEffects 采用扁平化的数据结构设计：每个具备开关及参数的后处理特效均直接挂载于顶层，便于开发工具进行通用的遍历与反射处理。具体特效在用户界面中的呈现分组属于视图层设计，不影响底层协议结构。

特效在 图层列表 中的呈现顺序由 environment.effectLayers 独立维护（为 ToggleEffectKey 数组）。该列表与特效自身的 enabled 状态相互独立：enabled 控制特效管线的运算开关，effectLayers 决定其在 UI 面板中是否作为图层列出。当通过 Patch 启用某个特效时，系统会自动补齐对应的图层条目，因此插件开发时通常只需修改 enabled 属性。

type SceneToneMapping = "none" | "neutral" | "aces" | "agx";

渐变特效提供 24 种混合模式 EffectBlendMode，EFFECT_BLEND_MODES 按面板中的顺序列出它们。

rain（降雨）与 snow（降雪）在数据结构上与其他特效保持一致，但在管线行为上具有本质区别：它们在场景中以实际的 3D 粒子几何体形式存在并参与渲染，而非传统的屏幕空间后处理通道，详见 雨景特效 与 雪景特效。

虚拟形象与物体图层也有各自的特效管线。SceneModelItem 与 SceneObjectItem 上的 effects 与 effectLayers 先于全屏场景特效执行，通过 instance.setEffects 修改。

• 图层特效支持 LayerEffectKey 定义的子集：color、levels、colorWheels、colorShift、selectColors、gradient、blur、bloom、diffusion、sketch、rim、outline 与 dropShadow。
• 辉光特效的颜色过滤仅在图层级别生效，详见 图层特效。

转场过渡复制锚点链接

transition 用于配置场景激活时的视觉过渡效果，详见 场景转场（未声明 scene-transitions 能力的版本不提供该特性）。SCENE_TRANSITION_TYPES 列出所有合法转场类型，defaultSceneTransition() 返回默认的硬切过渡，healSceneTransition() 用于将参数纠偏至合法范围。

environment.itemTransition 控制场景内模型、道具及动态生成物体的出现与消失动效，详见 显示与隐藏。ITEM_TRANSITION_STYLES 列出全部支持的过渡风格，defaultItemTransition() 默认采用 300 ms 的 glitch 故障效果，ITEM_TRANSITION_MAX_MS 限制最长过渡时间为 5000 ms。

场景预设复制锚点链接

presets 按显示顺序列出场景已保存的 场景预设；未声明 scene-presets 能力的版本不提供该字段。可通过 preset.create、preset.update、preset.rename、preset.setTransition、preset.delete 与 preset.apply 管理当前场景的预设，详见 插件 API：场景预设。

• SCENE_PRESET_TRANSITIONS：全部转场方式
• scenePresetIsCurrent()：判断舞台当前布局是否与某个预设吻合，桌面端与网页控制台据此高亮对应预设
• capturePresetItems()：采集图层布局
• presetStep()：计算应用预设时各图层的变化

运行时状态复制锚点链接

instance.list 动态返回当前舞台上每个活动实例支持的实际能力集，客户端可据此在 UI 层面精确禁用非支持的操作控件，而无需依赖被动捕获 RPC 异常：

type InstanceCapability =
  | "motions"
  | "expressions"
  | "placement-2d"
  | "placement-3d"
  | "mtoon"
  | "idle-clips"
  | "idle-motions"
  | "pose"
  | "breath"
  | "expression-weights"
  | "live2d-params"
  | "speech"
  | "post-fx";