# @happy-oyster/js-sdk 中文文档

规范地址：https://npmcn.com/package/%40happy-oyster/js-sdk/

版本：0\.1\.5
npm 元数据更新时间：2026-10-09T09:25:51.495Z
中文译文更新时间：2026-11-17T09:22:20.151Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40happy-oyster/js-sdk
原文对照：https://npmcn.com/package/%40happy-oyster/js-sdk/?lang=original

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

- 包体积（解压后）：262 kB，77 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-06-26T09:51:22.241Z
- 最新版本发布：2026-10-09T09:25:51.254Z
- 近 30 天下载量：5169（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

快乐牡蛎RTC 网络玩家 SDK.

## 安装

```sh
npm install @happy-oyster/js-sdk
```

也可以使用：`pnpm add @happy-oyster/js-sdk`、`yarn add @happy-oyster/js-sdk`、`bun add @happy-oyster/js-sdk`

## README

# @happy-oyster/js-sdk

Happy Oyster SDK 提供 Web 端实时音视频流播放与交互控制能力。SDK 通过 Travel ticket 创建 Travel，会话 ID、RTC 配置和后续生命周期操作都封装在 `Travel` 实例中。

## 安装

```bash
npm install @happy-oyster/js-sdk
```

`aliyun-rtc-sdk` 已作为依赖自动安装，版本要求 `7.3.4`。

## 快速上手

```html
<video id="player" playsinline></video>
```

```typescript
import { HappyOysterEngine } from "@happy-oyster/js-sdk";

const happyOyster = new HappyOysterEngine({
  APIHost: "open-platform.example.com",
  model: "happyoyster-1.0-adventure", // 必填；此处以 Adventure 模型为例
});

happyOyster.updateToken("open-platform-http-token");

const videoElement = document.getElementById("player") as HTMLVideoElement;
const travel = happyOyster.createTravel({
  ticket: "travel-ticket",
  videoElement,
  maxExperienceTimeSec: 90, // 可选，仅 Adventure 生效：60 / 90 / 120
});

travel.on("statusChanged", (status) => console.log("状态变更:", status));
travel.on("travelInfoReady", (info) =>
  console.log("进房信息已就绪:", info.mode, info.aspectRatio),
);
travel.on("firstFrameGenerated", (firstFrame) =>
  console.log("首帧已生成:", firstFrame),
);
travel.onError((err) => console.error("连接异常:", err));

const startResult = await travel.start();
console.log("Travel 已启动:", startResult);

travel.sendCommand({
  translation: "Front",
  rotation: "Mouse_Left",
  interaction: "Jump",
});

await travel.sendInstruct({ content: "镜头转向城堡，主角开始奔跑" });
await travel.pause();
await travel.resume();
await travel.rewind({ rewindToSec: 12 });
await travel.end();
```

## API

### `new HappyOysterEngine(config)`

创建 SDK client。`config.APIHost` 为必填裸 host（不含 `https://` 和路径）；`config.model` 必填，用于指定 Open Platform 模型，无默认值；`config.token` 可选，也可后续通过 `updateToken()` 设置或刷新。`config.logLevel` 控制 SDK 内部日志。

必须显式传入目标 `model`。一个 Engine 固定对应 `APIHost + model`，同一模型的多次 Travel 可复用该 Engine；切换模型前先结束当前 Travel，再使用目标模型的 Engine。World 和 ticket 应来自同一服务目标；SDK 不根据体验 mode 自动选择模型，也不会解析 ticket 来推断模型。

### `HappyOysterEngine` 方法

| 方法 | 说明 |
| --- | --- |
| `updateToken(token)` | 刷新 Open Platform HTTP API 的 Bearer token |
| `createTravel(config)` | 创建 Travel，返回尚未启动的 `Travel` |

当前实现每个 SDK 实例只允许一个 active `Travel`。如需创建下一次 Travel，请先调用 `await travel.end()`。

> 设置 token（构造时或 `updateToken`）后，SDK 内部会自动拉取功能开关（Feature Gate），用于远程关停 SDK 或强制升级旧版本。该逻辑为 SDK 内部实现，无需调用方介入；请求失败时 fail-open。

### `Travel.start()` 返回值

`start()` resolve 后返回 `StartTravelResult`：

| 字段 | 说明 |
| --- | --- |
| `encryptedTravelId` | 当前 Travel 会话 ID |
| `mode` | Travel 模式：`1` = Adventure、`2` = Directing、`3` = Acting |
| `creationModel` | Travel 创建模型 |
| `firstFrame` | Open Platform 返回的首帧 URL |
| `maxExperienceTimeSec` | Adventure 最大体验时间；Directing、Acting 或老服务未返回时为 `null` |
| `aspectRatio` | Acting 画幅：`9:16` / `16:9`；其他模式或老服务未返回时为 `null` |

### `Travel` 方法

| 方法 | 说明 |
| --- | --- |
| `start()` | 启动当前 Travel，返回 `Promise<StartTravelResult>` |
| `can(action)` | 判断当前状态、模式和版本下是否可以调用指定 Travel 方法 |
| `getInfo()` | 获取 enter-travel 已返回的 `TravelInfo`；尚未返回时为 `null` |
| `sendCommand(params)` | 通过 RTC DataChannel 发送操控指令 |
| `sendInstruct({ content })` | 发送导演/提示词，自动携带当前 `encryptedTravelId` |
| `pause()` | 暂停当前会话 |
| `resume()` | 恢复已暂停的会话 |
| `rewind({ rewindToSec })` | 仅支持回退的 Directing 会话可用；回退秒数仅支持 4 的整数倍，非整数倍由服务端向下取整 |
| `end()` | 结束会话并释放 RTC 资源 |

`can(action)` 支持的 `action`：`start` / `sendCommand` / `sendInstruct` / `pause` / `resume` / `rewind` / `end`。

Acting 支持 `sendInstruct`、`pause`、`resume` 和 `end`；暂停、恢复取决于会话能力，不支持 `sendCommand` 与 `rewind`。

暂停和恢复同时以 `videoElement` 的视频帧变化和后端 `rtcStatus` 确认状态：

-   `pause()`：暂停接口成功后，等待视频连续 500ms 没有新帧，并等待后端确认 `rtcStatus=PAUSED`（兼容大小写）。两项均满足且当前为 `running`，才变为 `paused`；随后调用 Core `leaveChannel()`，离会完成后完成 Promise。每个新帧都会重新开始计时；离会失败时 Promise 拒绝，状态保留为已经确认的 `paused`。
-   `resume()`：本地能力检查通过后，先触发一次 status 查询（若已有请求则复用），只有 `rtcStatus=PAUSED`（兼容大小写）才调用恢复接口。尚未暂停或出现临时查询失败时，等待现有每秒一次的 status 轮询继续确认，本地保持 `paused`。等待阶段使用 resume 超时配置（默认 15 秒）；超时返回 `RESUME_STREAM_TIMEOUT`，会话结束则取消等待；`can("resume")` 只检查本地条件。恢复接口成功后开始等待新帧和后端 `rtcStatus=STREAMING`，并通过 Core `connect()` 重新入会（内部调用 RTC `joinChannel()`）。入会完成、收到新帧且后端确认 STREAMING 后，当前状态为 `paused` 时变为 `running` 并完成 Promise。接口成功前的帧和残留的 `readyState` 不作为恢复依据。
-   优先使用 `requestVideoFrameCallback`，不支持时检查 `getVideoPlaybackQuality()` 的已显示帧计数增量。后台页面不累计暂停的无帧确认时间；无法观察帧或等待超时会使操作失败，保留原状态。
-   后端状态轮询继续处理完成和失败，`rtcStatus=paused/streaming` 不直接变更暂停或恢复状态。会话结束会取消帧等待。

### 事件

通过 `travel.on(event, callback)` 订阅当前 Travel 的事件。

| 事件名 | 回调签名 | 说明 |
| --- | --- | --- |
| `statusChanged` | `(status: TravelStatus) => void` | 会话状态变更 |
| `travelInfoReady` | `(info: TravelInfo) => void` | enter-travel 返回后、RTC 连接前触发一次 |
| `firstFrameGenerated` | `(firstFrame: string) => void` | `start()` 过程中收到首帧 URL |
| `error` | `(error: unknown) => void` | 发生连接/播放错误 |

`firstFrameGenerated` 为兼容事件：当 `TravelInfo.firstFrame` 非空时，它会紧随 `travelInfoReady` 继续触发。晚订阅方可用 `travel.getInfo()` 补读元信息。

### 控制指令取值

`sendCommand` 的 `translation`、`rotation`、`interaction` 都是选填字段；未传字段会按 `None` 发送。

**translation（移动方向）**：`Front` / `Back` / `Left` / `Right` / `Up` / `Down` / `Front_Left` / `Front_Right` / `Back_Left` / `Back_Right` / `None`

**rotation（视角旋转）**：`Mouse_Up` / `Mouse_Down` / `Mouse_Left` / `Mouse_Right` / `Mouse_Up_Left` / `Mouse_Up_Right` / `Mouse_Down_Left` / `Mouse_Down_Right` / `None`

**interaction（交互动作）**：`Jump` / `Attack` / `Crouch` / `Sprint` / `None`

## 开发

```bash
npm install
npm run build       # 输出到 lib/
npm test            # 运行 jest
```

## 许可

本 SDK 为专有软件，版权归 Alibaba Group 所有，保留所有权利。授予用户有限的、不可转让的权利，仅用于集成调用本 SDK 的公开接口；禁止反编译、逆向工程、提取源码或二次分发。详见根目录 [LICENSE](https://npmcn.com/package/%40happy-oyster/js-sdk/LICENSE) 文件。

## 常见问题

### @happy-oyster/js-sdk 是什么？

快乐牡蛎RTC 网络玩家 SDK\.

### 如何安装 @happy-oyster/js-sdk？

在项目目录运行 npm install @happy-oyster/js-sdk，或使用 pnpm add / yarn add / bun add。

### @happy-oyster/js-sdk 支持 TypeScript 吗？

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

### @happy-oyster/js-sdk 支持 ESM 还是 CommonJS？

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

### @happy-oyster/js-sdk 可以商用吗？

@happy-oyster/js-sdk 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @happy-oyster/js-sdk 的下载量有多少？

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

### @happy-oyster/js-sdk 还在维护吗？

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

