示例

# 示例

这些示例使用公开的OneSay JavaScript SDK（`@onesay/sdk`）。该SDK尚未发布到软件包仓库。示例不会替你创建项目或房间：它们使用你的应用已有的资源、凭据和用户同意决定。

## 选择服务

| 服务 | 示例 | 演示内容 |
| --- | --- | --- |
| 语音任务 | [JavaScript快速入门](../guides/JAVASCRIPT_QUICKSTART.md) | 发送你提供的PCM音频、ACK和重放、任务完成，以及重新读取产物和用量。应用负责提供身份、现有资源和用户的同意决定。 |
| RTC音频、数据和RPC | 下文的JavaScript RTC浏览器示例 | 连接、发布、订阅、接收、结束和关闭，每一步都是一个显式按钮。 |
| RTC Agent | 同一个RTC示例 | 选择输入音轨，然后创建、读取和停止Agent运行。单独的收听方需要自己的授权，并要由用户操作触发，才能播放Agent的声音。 |

语音任务和RTC是两个独立的服务。连接RTC或发布麦克风，既不会启动任务，也不会启动Agent。流水线Agent的转写结果不是任务的听写服务。示例只使用公开的OneSay对象；SDK不暴露原生的房间、音轨或Token API。

设备端请参阅[ESP32快速入门](../guides/ESP32_QUICKSTART.md)。

## 运行RTC示例

RTC示例是一个普通的浏览器页面（`index.html`、`app.mjs`、`sample.mjs`、`style.css`），附带一个小型静态服务器`serve.mjs`。把这些文件放到已安装`@onesay/sdk`的目录中，然后运行`node serve.mjs`。服务器会输出`http://127.0.0.1:<port>/`；在浏览器中打开该地址，按Ctrl+C可停止服务器。它只提供页面、页面的模块和样式表：从不接触你的凭据，不转发任何API请求，也不授予任何权限。页面使用SDK的`staging`环境。

你需要已授权的房间、应用会话、音频源和音轨ID，以及通过你的应用自己的登录流程获得的短期Token（真人用户或应用会话）。把Token粘贴到密码字段，然后选择**仅在内存中使用Token**：页面只在内存中保存Token，并立即清空该字段。Control API必须通过CORS允许页面的源。不要把平台API密钥、服务密钥或服务商密钥放进浏览器页面。

## 处理生命周期

- 保留你用过的每个资源ID、幂等键和策略版本。响应丢失时，用同一个键重新发送同一请求，或读取原来的资源。
- 请求被接受只表示意图已记录：已接受的订阅、数据包策略、Agent停止或撤销，都不代表已经生效。
- 数据接收方必须选择对应的音轨并启动读取器。在示例中，`nextDataFrame`读取一帧后就会关闭该读取器。
- 取消本地等待，不会回滚服务器已经提交的操作。
- 用完后关闭RTC会话，并停止你创建的每个Agent运行：关闭会话不会停止Agent。
- 结果不确定时，读取原来的资源，并使用应用的用户同意流程。不要自动更换键、追逐新的策略版本，也不要自动创建替代工作。

要收听Agent，请用`client.rtc.agents.get(roomId, agentExecutionId)`读取它的运行。`playback`不为null时，会指明Agent的输出音轨；null表示未知，而不是没有声音。通过你的应用把公开ID分享给收听方。收听方用自己的身份和应用会话连接，订阅该音轨，并在用户操作中调用`session.audio.enablePlayback`。

## 报告问题

把操作、返回的错误码和资源ID一起记录在有访问控制的报告中。不要写入Bearer Token、连接信息、私有异常文本和客户媒体。