# @laplace\.live/persona-sdk 中文文档

规范地址：https://npmcn.com/package/%40laplace.live/persona-sdk/

版本：1\.35\.0
npm 元数据更新时间：2026-11-01T14:45:26.576Z
中文译文更新时间：2026-11-01T17:09:00.538Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40laplace.live/persona-sdk
原文对照：https://npmcn.com/package/%40laplace.live/persona-sdk/?lang=original
项目主页：https://laplace.live/persona
源码仓库：https://github.com/laplace-live/persona

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：873 kB，107 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- 首次发布：2026-08-11T08:36:55.682Z
- 最新版本发布：2026-11-01T14:45:26.365Z
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

拉普拉斯Persona插件API的TypeScript SDK和连线模式

## 安装

```sh
npm install @laplace.live/persona-sdk
```

也可以使用：`pnpm add @laplace.live/persona-sdk`、`yarn add @laplace.live/persona-sdk`、`bun add @laplace.live/persona-sdk`

## README

# @laplace.live / persona-sdk

的TypeScript SDK和连线模式 [拉普拉斯的角色](https://github.com/laplace-live/persona) 插件API -一个令牌认证的WebSocket API，用于驱动头像，场景，表达式， 动作，热键和跟踪参数从应用程序外部。

同构：运行在Node≥24、Bun、浏览器和OBS浏览器源上 `WebSocket`. 一个运行时依赖项([`zod`](https://zod.dev/)（支持连接模式）。

## 设置

启用角色中的API **高级→插件API**，创建密钥，并复制令牌。

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

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

// Typed request/response
const { scenes, activeSceneId } = await persona.call('scene.list')
await persona.call('expression.toggle', { name: 'Smile' })
await persona.call('scene.patch', {
  background: { mode: 'color', color: '#112233', imageAssetId: null },
})

// Events (subscriptions survive reconnects)
persona.on('motion.started', m => console.log('playing', m.group))

// Parameter leases: the value keeps applying until released; the SDK owns the
// heartbeat, and if your process dies the parameter reverts within ~1 s.
const mouth = persona.driveParameter('MouthOpen', 0.8)
mouth.set(0.3)
mouth.release()
```

缺省情况下，令牌以 `?token=` （适用于浏览器）。从节点, `createNodeClient` 将其作为 `Authorization: Bearer` 而不是Node的全局 `WebSocket`, 记录永久结束会话的关闭（密钥撤销或会话断开） 角色):

```ts
import { createNodeClient } from '@laplace.live/persona-sdk'

const persona = createNodeClient({ token, log: console.warn })
await persona.connect()
```

任何其他可以设置报头的套接字，例如 [`ws`](https://www.npmjs.com/package/ws) 包装、插头 `new PersonaClient({ token, auth: "header", createWebSocket })`.

## 识别你的应用

通过 `clientInfo` 你的应用按名称显示在 **连接的客户机** 在角色的 设置（可选-未识别的客户端工作相同）。SDK会在每个节点上重新声明它 重新连接;它是自我声明的，只显示，从不授权：

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

两个服务器关闭代码是终端并停止重新连接循环： `CLOSE_KEY_REVOKED` (4001年, 密钥已被撤销)和 `CLOSE_FORCE_DISCONNECTED` (4002，用户断开会话 在角色)。客户端通过 `onWarning` , `closed`.

将令牌视为密码：它授予对应用程序的控制，包括加载注册 模型和网页覆盖。服务器监听环回，除非局域网访问在启用 角色的设置。

## 注册中心和编目元数据

`model.list` / `asset.list` 返回裁判的来源和归属：每个裁判携带 `origin` （`'bundled'` 对于第一方内容，随应用程序一起发布或从 角色目录; `'user'` 对于用户添加的任何内容)，可以携带optional `author` / `url` 学分。

`CatalogItem` 选择器背后与传输无关的内容-元数据形状是否稳定 `id` （场景被关掉了），然后 `InventoryKind`、显示 `name`，可选 `description`， `thumbnailUrl`， `previewUrl` (缩略图中显示了一个简短的循环视频 的地方), `version`， `author`， `url`, `download` (一个 `CatalogDownload`： HTTPS压缩文件 它的字节大小和sha256)。角色市场将其目录服务为 `{ version, items }` 在 `https://marketplace.laplace.live` + `MARKETPLACE_ITEMS_PATH`. `healCatalog` 将已解析的文档转换为可用的行，删除 畸形的，和 `pickLocalized(item.description, locale)` 中的描述 读者的语言，回落到英语。

`healCatalogItem` 治愈一排，然后 `healCatalogRows(raw, healRow)` 通过 您自己的行治疗，保持两个id中的第一个等于忽略大小写。一行需要一个 Id通过 `isCatalogId` （一个路径安全段，因为id代表一个安装文件夹）， 一个非 `name`，和一种来自 `CATALOG_KINDS`； `CATALOG_FORMAT` 文件是 `version`. `healSha256` 将摘要读取为64个小写十六进制字符，并且 `payloadEntryPath` 检查有效负载压缩包的条目名称，回答相对POSIX路径和 提取器可以写，或者为空；负载的两个条目不能共享a `payloadEntryKey`. `healLocalizedText` 治愈一个 `LocalizedText` （`en` 必需的，其他发送的区域 （可选），并且永远不会将其他区域设置提升为 `en`.

## 常见问题

### @laplace\.live/persona-sdk 是什么？

拉普拉斯Persona插件API的TypeScript SDK和连线模式

### 如何安装 @laplace\.live/persona-sdk？

在项目目录运行 npm install @laplace\.live/persona-sdk，或使用 pnpm add / yarn add / bun add。

### @laplace\.live/persona-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @laplace\.live/persona-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @laplace\.live/persona-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @laplace\.live/persona-sdk 可以商用吗？

@laplace\.live/persona-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @laplace\.live/persona-sdk 还在维护吗？

最新版本 1\.35\.0 发布于 2026/11/01（1 天前）；至今共发布 62 个版本，其中过去 12 个月发布了 62 个；首次发布于 2026/08/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。