# @deepslate-labs/core 中文文档

规范地址：https://npmcn.com/package/%40deepslate-labs/core/

版本：0\.1\.23
npm 元数据更新时间：2026-10-16T11:00:11.850Z
中文译文更新时间：2026-11-11T20:36:05.185Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40deepslate-labs/core
原文对照：https://npmcn.com/package/%40deepslate-labs/core/?lang=original

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

- 包体积（解压后）：189 kB，52 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-06-28T13:22:12.360Z
- 最新版本发布：2026-10-16T11:00:11.636Z
- 近 30 天下载量：4105（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Deepslate SDK集成共享核心库(TypeScript)

## 安装

```sh
npm install @deepslate-labs/core
```

也可以使用：`pnpm add @deepslate-labs/core`、`yarn add @deepslate-labs/core`、`bun add @deepslate-labs/core`

## README

# @ deepslate-labs/ 分数

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Documentation](https://img.shields.io/badge/docs-deepslate.eu-green)](https://docs.deepslate.eu/) [![Node](https://img.shields.io/badge/node-18+-blue.svg)](https://nodejs.org/)

共享核心库 [深层的](https://deepslate.eu/) 实时语音AI SDKs(TypeScript).

> **你可能不需要直接安装这个.**
> 
> 安装 [`@deepslate-labs/livekit`](https://npmcn.com/package/%40deepslate-labs/livekit/README.md) 相反,它拉入 `@deepslate-labs/core` 自动。 这个软件包是给开发者的 **自定义深度集成** 外部 活猫.

`DeepslateSession` 是输入的 `EventEmitter` ——您订阅服务器事件 `session.on(event, …)`。 。 。 .

* * *

## 里面的东西

`@deepslate-labs/core` 提供从任何节点应用程序连接 Depslate Realtime API 所需的一切信息 :

-   **`DeepslateSession`** 管理整个WebSocket生命周期的高级别会议、原型布局、会议初始化、重新连接和事件调度。 键入 `EventEmitter`. 定制集成的主要构件.
-   **`DeepslateOptions` 编号 : `DeepslateModel`** - API 证书、模型选择和连接配置,与 `resolveOptions()` 编号 : `optionsFromEnv()` 常识者.
-   **`VadConfig`** ——服务器侧语音活动检测参数.
-   **`HostedTtsConfig` 编号 : `HostedTtsMode`** ——深层托管(克隆)语音TTS配置.
-   **`ElevenLabsTtsConfig` 编号 : `ElevenLabsLocation`** - 11Labs TTS配置(`elevenLabsConfigFromEnv()` 从env的负载).
-   **`BaseDeepslateClient`** ——低级WebSocket客户端有指数后退重联(由内部使用) `DeepslateSession`) (中文(简体) ).
-   **Protobuf 装订** - 通过下列方式再出口: [`@deepslate-labs/proto`](https://npmcn.com/package/%40deepslate-labs/proto/README.md) 深层实时电线协议.

* * *

## 安装

```bash
npm install @deepslate-labs/core
```

### 所需资源

-   节点.js 18或以上

### 依赖关系

-   `ws` – WebSocket 客户端
-   `@deepslate-labs/proto` ——所生成的原生活口装订(原生活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口活口

* * *

## 使用量

> 本节为自定义集成作者. 关于标准使用量,见 [活键](https://npmcn.com/package/%40deepslate-labs/livekit/README.md) 软件包.

### 全权证书

```ts
import { optionsFromEnv, resolveOptions } from "@deepslate-labs/core";

// Load from environment variables (recommended)
const opts = optionsFromEnv();

// Or configure manually
const opts = resolveOptions({
  vendorId: "your_vendor_id",
  organizationId: "your_org_id",
  apiKey: "your_api_key",
  systemPrompt: "You are a helpful assistant.",
});
```

所需的环境变量 :

```bash
DEEPSLATE_VENDOR_ID=your_vendor_id
DEEPSLATE_ORGANIZATION_ID=your_organization_id
DEEPSLATE_API_KEY=your_api_key
```

### 模式选择

```ts
import { DeepslateModel, optionsFromEnv } from "@deepslate-labs/core";

const opts = optionsFromEnv({ model: DeepslateModel.OPAL_V2_1 });
```

若为 `model` 未设置,则使用平台默认值.

见 [docs.deepslate.eu/opal#可用模式](https://docs.deepslate.eu/opal#available-models) 用于完整的模型列表.

### TTS 配置

支持两个TTS供应商. 通过配置为 `ttsConfig` 改为 `DeepslateSession.create()`。 。 。 .

**深层托管(克隆)声音** 不需要外部提供者证书:

```ts
import { HostedTtsMode, type HostedTtsConfig } from "@deepslate-labs/core";

const tts: HostedTtsConfig = {
  provider: "hosted",
  voiceId: "c3dfa73f-a1ab-4aad-b48a-0e9b9fe4a69f",
  mode: HostedTtsMode.HIGH_QUALITY, // or HostedTtsMode.LOW_LATENCY
};
```

**十一律仪:**

```ts
import { elevenLabsConfigFromEnv, ElevenLabsLocation } from "@deepslate-labs/core";

// Load from environment variables
const tts = elevenLabsConfigFromEnv();

// Or configure manually
const tts = {
  provider: "eleven_labs" as const,
  apiKey: "your_elevenlabs_key",
  voiceId: "21m00Tcm4TlvDq8ikWAM",
  modelId: "eleven_turbo_v2",
  location: ElevenLabsLocation.US, // US (default), EU, or INDIA
};
```

### 实验

> **没有稳定保障.** 实验可能会改变或消失,而不会出现版本的凸起或警告.

Deepslate可以让服务器侧实验用于一个会话. 把它们作为实验名称的平面图传递到参数值. 名称是不透明的字符串; 不需要参数的实验被启用 `null`数字 :

```ts
import { DeepslateSession } from "@deepslate-labs/core";

const session = DeepslateSession.create({
  vendorId, organizationId, apiKey,
  experiments: { "example-experiment:1": null },
});
```

每个实验都定义了自己的价值,所以一个价值意味着什么,是否需要一个价值,取决于实验. 值可以是 JSON 值 : `null`,布尔,数字,字符串,数组,或嵌入对象,一个参数对象可以被部分填入:

```ts
const session = DeepslateSession.create({
  vendorId, organizationId, apiKey,
  experiments: {
    "example-experiment:1": { someSetting: "value", anotherSetting: 3 },
  },
});
```

SDK没有关于实验的目录:它发送任何你通过的东西,服务器忽略它不知道的名字. 询问您的深层联系人, 哪些实验是可用的, 以及接受哪些值 .

### `DeepslateSession`

`DeepslateSession` 是自定义整合的推荐切入点。 它处理完整的协议 生命周期——会话初始化,protobuf序列化,再连接,以及服务器-事件路由—— 释放出强烈类型的事件,所以您的代码只处理应用逻辑.

使用 `DeepslateSession.create()` 当您的代码拥有连接时: 它会创建自己的连接 `BaseDeepslateClient` 并自动关闭 `close()` 名为.

```ts
import { DeepslateSession, optionsFromEnv, elevenLabsConfigFromEnv } from "@deepslate-labs/core";

const session = DeepslateSession.create(
  optionsFromEnv({ systemPrompt: "You are a helpful assistant." }),
  { ttsConfig: elevenLabsConfigFromEnv(), userAgent: "MyApp/1.0" },
);

session.on("sessionInitialized", () => {
  // Session is ready — safe to send the first message
  void session.sendText("What is the capital of France?");
});

session.on("textFragment", (text) => process.stdout.write(text));

session.on("audioChunk", (pcm, sampleRate, channels, transcript) => {
  // Forward PCM audio to your output device / transport
});

session.on("toolCall", async (callId, name, params) => {
  const result = await dispatchTool(name, params);
  await session.sendToolResponse(callId, result);
});

session.on("error", (category, message, traceId) => {
  console.error(`[${category}] ${message}`);
});

session.start();

// Initialize for text-only interaction (audio sessions initialize automatically).
// "sessionInitialized" fires once the session is ready.
await session.initialize(24000, 1);

// ... later
await session.close();
```

#### 发送音频

第一个音频会话自动初始化 `sendAudio()` 电话 会议也重新配置 如果音频格式改变会中段,则透明:

```ts
// pcm: raw signed 16-bit PCM (Uint8Array)
await session.sendAudio(pcm, 16000, 1);
```

#### 运行时更新工具

```ts
await session.updateTools([
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Get the weather for a city.",
      parameters: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
      },
    },
  },
]);
```

工具定义在每次重接后会自动重排.

#### 重新连接

`start()` 驱动器 `BaseDeepslateClient.runWithRetry()` 内部。 在断开连接时, 会话 重新设置状态, 重新发送初始化请求, 重新同步工具定义, 并恢复 —— 全部没有 您的代码需要任何动作 。 打电话 `close()` 以永久停止重试循环.

握手永久拒绝服务器( HTTP 4xx 除外, 408/429) —— 例如一个糟糕的 API 密钥, 未知 供应商/组织,或该组织无法接触的模型)没有经过再审: `fatalError` 火灾 即刻与一个 `HandshakeRejectedError` 谁 `status` 财务报告和审定财务报表 `model` 描述拒绝情况及其 留言说要检查什么.

* * *

## API 参考

### `DeepslateSession.create(options, opts?)`

与自己一起创建会场的工厂 `BaseDeepslateClient`。会话拥有客户端 并关闭它,当 `close()` 名为.

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `options` | `DeepslateOptions` | 所需经费 | API 证书和设置 |
| `opts.vadConfig` | `VadConfig` | 默认 | VAD 设置 |
| `opts.ttsConfig` | `TtsConfig` | `undefined` | 启用服务器侧 TTS 音频输出 |
| `opts.userAgent` | `string` | `buildUserAgent()` | `User-Agent` 连接时发送头 |

### `DeepslateSession` ——发送方法

| 方法 | 说明 |
| --- | --- |
| `session.sendAudio(pcm, sr, ch)` | 发送 PCM 音频; 格式更改的自动初始化和自动重组 |
| `session.sendText(text, trigger?)` | 发送文本 `UserInput` (默认触发 : `IMMEDIATE`(中文(简体) ) |
| `session.initialize(sr?, ch?)` | 明确初始化(仅限文本会议) |
| `session.triggerInference(instructions?)` | 手动触发模型回复 |
| `session.sendToolResponse(callId, result)` | 向服务器返回工具结果 |
| `session.updateTools(tools)` | 同步工具定义( 贯穿重联) |
| `session.reconfigure(systemPrompt?, temperature?)` | 实时更新推论设置 |
| `session.sendDirectSpeech(text, includeInHistory?, uninterruptable?)` | 通过 TTS 直接讲出文字, 绕过 LLM |
| `session.exportChatHistory(awaitPending?, excludeAudio?)` | 请求历史导出; 通过 `chatHistory` 事件 |
| `session.sendConversationQuery(queryId, prompt?, instructions?)` | 侧通道推论;通过 `conversationQueryResult` 事件 |

### `DeepslateSession` - 活动

订阅 `session.on(event, listener)`事件有效载荷通过 `DeepslateSessionEvents`。 。 。 .

| 活动 | 收听器签名 | 何时出院 |
| --- | --- | --- |
| `sessionInitialized` | `()` | 会话已完全初始化并准备接受消息 |
| `textFragment` | `(text: string, turnId: number | null)` | 模式流一个文本符号(比实时快,见下文注) |
| `audioChunk` | `(pcm: Uint8Array, sampleRate: number, channels: number, transcript: string | null)` | 模型流 a TTS 音频块 |
| `toolCall` | `(callId: string, name: string, params: Record<string, unknown>)` | 模型请求工具引用 |
| `responseBegin` | `()` | 模式响应开始 |
| `responseEnd` | `()` | 模型响应结束 |

> **`textFragment` 不是被听到的笔录.** 碎片到达 在TTS合成之前,它们比实时快 所以它们携带模型的 _计划_ 输出。 当旋转中断时, 服务器已经发送 从未到达发言者的文本。 不要用它来记录 打电话者听到的 永远不要直接同步到对话史上. | `userTranscription` | `(text: string, language: string \| null, turnId: number)` 用户语音转录到 | `playbackBufferClear` | `()` QQ 服务器清除了其音频回放缓冲器QQ | `chatHistory` | `(messages: ChatMessage[])` QQ 聊天历史导出收到QQ | `conversationQueryResult` | `(queryId: string, text: string)` QQ 侧道查询结果收到QQ | `error` | `(category: string, message: string, traceId: string \| null)` QQ 服务器发送了错误通知QQ | `fatalError` | `(err: Error)` 重新连接的复试已经用尽,或者握手被拒绝(`HandshakeRejectedError`) (中文(简体) ) | `socketError` | `(err: Error)` QQ 背景 WebSocket 出错( 仅限博客/ 可观察性; 不影响运行回路) QQ

### `DeepslateOptions`

| 外地 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `vendorId` | `string` | 内存 : `DEEPSLATE_VENDOR_ID` | 深层供应商标识 |
| `organizationId` | `string` | 内存 : `DEEPSLATE_ORGANIZATION_ID` | 深层组织ID |
| `apiKey` | `string` | 内存 : `DEEPSLATE_API_KEY` | 深解 API 密钥 |
| `model` | `DeepslateModelId` | 内存 : `DEEPSLATE_MODEL`,则 `undefined` (平台默认) | 实时模式 |
| `baseUrl` | `string` | `"https://app.deepslate.eu"` | 深层 API 的基础 URL |
| `systemPrompt` | `string` | `"You are a helpful assistant."` | 默认系统提示 |
| `temperature` | `number` | `0.3` | 取样温度(0.0-2.0) |
| `wsUrl` | `string` | `undefined` | 直接 WebSocket URL( 覆盖) `baseUrl`; 用于本地 dev) |
| `maxRetries` | `number` | `3` | 放弃前最大重联尝试 |
| `generateReplyTimeout` | `number` | `30.0` | 回复生成的超时( 0 = 无超时) |
| `experiments` | `Experiments` | `undefined` | 启用服务器侧实验 |

### `VadConfig`

| 外地 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `confidenceThreshold` | `number` | `0.4` | 将音频分类为语音的最低信任度( 0-1) |
| `minVolume` | `number` | `0.0` | 将音频分类为语音的最小音量 (0-1) |
| `startDurationMs` | `number` | `150` | 启动事件所需的发言时间 |
| `stopDurationMs` | `number` | `390` | 触发事件所需的沉默期限 |
| `backbufferDurationMs` | `number` | `1000` | 在语音检测触发前捕获音频缓冲器 |

* * *

## 文档

-   [深层文档](https://docs.deepslate.eu/)
-   [API 参考](https://docs.deepslate.eu/api-reference/)

* * *

## 许可证

Apache 许可证 2. 0 — 见 [自由主义](https://npmcn.com/LICENSE) 详细情况.

## 常见问题

### @deepslate-labs/core 是什么？

Deepslate SDK集成共享核心库\(TypeScript\)

### 如何安装 @deepslate-labs/core？

在项目目录运行 npm install @deepslate-labs/core，或使用 pnpm add / yarn add / bun add。

### @deepslate-labs/core 支持 TypeScript 吗？

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

### @deepslate-labs/core 支持 ESM 还是 CommonJS？

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

### @deepslate-labs/core 可以商用吗？

@deepslate-labs/core 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @deepslate-labs/core 的下载量有多少？

根据 npm 官方下载统计，@deepslate-labs/core 在 2026/10/12 – 2026/11/10 这 30 天内被下载 4,105 次，日均约 137 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deepslate-labs/core 还在维护吗？

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