# @animated-waffle/react 中文文档

规范地址：https://npmcn.com/package/%40animated-waffle/react/

版本：0\.5\.11
npm 元数据更新时间：2026-11-05T03:17:00.206Z
中文译文更新时间：2026-11-06T19:52:07.615Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40animated-waffle/react
原文对照：https://npmcn.com/package/%40animated-waffle/react/?lang=original
项目主页：https://aniwaffle.com/docs/sdk
源码仓库：https://github.com/NaryaAI/animated-waffle

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

- 包体积（解压后）：33.1 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react \>=18
- 首次发布：2026-08-06T13:40:52.004Z
- 最新版本发布：2026-11-05T03:17:00.061Z
- 近 30 天下载量：2428（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 34 个）

## 中文简介

纳里亚动画"华夫饼"谈话代理商的反向钩和"神通"渲染器. 再出口@animated-waffle/客户.

## 安装

```sh
npm install @animated-waffle/react
```

也可以使用：`pnpm add @animated-waffle/react`、`yarn add @animated-waffle/react`、`bun add @animated-waffle/react`

## README

# `@animated-waffle/react`

用于嵌入已出版的"纳里亚会说话"代理机的反钩和"神通"渲染器. 此套件依赖于并再导出整个 [`@animated-waffle/client`](https://npmcn.com/package/%40animated-waffle/waffle-client),因此 React 应用程序安装 只有这个包裹.

安装当前 npm 发布而不复制可变注册版本 :

```bash
pnpm add @animated-waffle/react@latest
```

管理下的会期特性和 `sessionContext` 这里描述的API是 在0.3.1.版本中引入。 工作空间 [`package.json`](https://npmcn.com/package/%40animated-waffle/react/package.json) 实值 此寄存器版本的真相来源; `@latest` 决定 当前 npm 发布.

特工拥有它的外形,声音,和迅速。 媒体运行时间、API路线和 avatar 资产 URL 是 SDK 执行细节 。 制造器装入 Avatar 绑定到代理会话;呼叫者不会通过 `avatarUrl`。 。 。 . 生产是默认的 API 来源 。 试验和非生产结合 可能通过 `apiOrigin`; SDK 仍然拥有代理会话路由.

## 使用

将永久的工作空间 API 密钥保留在您的服务器上 。 换一个 短暂的代理会话符, 并给钩子一个获取一个的回调 每个连接 :

```tsx
import {
  AvatarStage,
  WaffleDeveloperFeedback,
  WaffleDiagnosticsPanel,
  useWaffle,
} from '@animated-waffle/react'

const waffle = useWaffle({
  agentId,
  inputAudioEnabled: false, // Text-triggered, output-only application.
  sessionContext: {
    userName: ' Space é ',
    timeZone: 'Asia/Shanghai',
  },
  sessionToken: () => getSessionToken(agentId),
  // Optional creator-only dev BFF. It returns the public snake_case grant.
  developerFeedback: ({ agentId, sourceSessionId, signal }) =>
    fetch('/api/narya-developer-feedback-grant', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ agentId, sourceSessionId }),
      signal,
    }),
})

return (
  <>
    <AvatarStage {...waffle.avatar} style={{ width: 480, height: 480 }} />
    <WaffleDeveloperFeedback waffle={waffle} />
    <WaffleDiagnosticsPanel waffle={waffle} />
  </>
)
```

使用回调,反馈组件只授权在 a 之后保存 连接会话存在 。 没有它,服务器作者 Studio 链接仍然 可供继续使用。 每一个都保存到一个私人的回合草稿的附件和 可区分保留/更改、整个会话/永久的助理答复, 首选答复,以及Persona/行为/记忆/Avatar/Voice/runtime维度. 它从未启动即时生成或发布; 服务器授权的 Dashboard 链接继续该工作流程。 组件保存一个项目 UUID 横跨一个 模糊失败的重试 .

`sessionContext?: { userName?: string; timeZone?: string }` 仅属于 默认 `sessionToken` 发起者. 非空白值的发送精确于 提供了空白值。 它相互排斥 高级 `startSession` 重新调用,所以信使路径 消费者不会重新创建 原始的管理会话请求.

钩子返回 App- face 客户端表面(`status`, (中文(简体) ), `session`, (中文(简体) ), `transcript`, (中文(简体) ), `transcriptProgress`, (中文(简体) ), `agentSpeaking`, (中文(简体) ), `decline`, (中文(简体) ), `error`, (中文(简体) ), `connect`, (中文(简体) ), `disconnect`, (中文(简体) ), `sendText`, (中文(简体) ), `muted` 编号 : `setMuted`)加上不透明 `avatar` 约束 `AvatarStage` 财务报告和审定财务报表 页:1 `avatarLoad` 预测。 传输音频音轨不属于此 默认反应 API. 其行动功能保持稳定身份, 所以效果和事件订阅可以直接依赖于它们.

`error` 是一个 `WaffleError` 输入 `stage`。钩子是单反射 错误所有者: 连接失败保留他们的客户端阶段, 而 Avatar 模式 和制造器失败的使用 `avatar-load` 财务报告和审定财务报表 `avatar-renderer` 不更改 连接状态。 钩子也接受客户端的可选性 `reportedSource`; 它默认为 `SDK`。 。 。 .

`AvatarStage` 拥有渲染器的寿命。 会话断开、重新连接和 替换仅重置性能信号; 它们不会去除可见的 画布 模型重置重用舞台,所以前相机会留下 可见,直到替换模型准备好。 舞台被摧毁了 当主机组件卸载时.

`waffle.avatarLoad` 报告Avatar探员的装载状态:

```tsx
const label = waffle.avatarLoad.fromCache
  ? 'Loading cached avatar…'
  : waffle.avatarLoad.progress === null
    ? 'Downloading avatar…'
    : `Downloading avatar… ${Math.round(waffle.avatarLoad.progress * 100)}%`
```

首个VRM下载以字节进度流出. SDK验证 模型与代理会话提供的内容散列相对并存储于 浏览器缓存存储 。 以后的会话会重新使用该内容,即使它们 短寿命资产URL不同.

`setMuted` 让特工的声音安静下来 一边继续表演 获取 回放完全是一个 `@animated-waffle/client` 选项: 此钩状手 返回没有音频音轨,所以应用程序不会播放.

对于一个故意沉默的特工来说, `decline` 包含最新的 `{ reason }`。用它来调节当前序列化反应.

神通的口音同步 运行一个音频工作 包裹携带 操作浏览器作为对象 URL,所以没有构建步骤需要复制资产 没有一个捆绑者能失去他们。 包含内容-安全政策的应用程序 需求 `blob:` 内 `script-src`。 。 。 .

见 [SDK 文档](https://aniwaffle.com/docs/sdk) 联 合 国 完整的整合指南.

## 发展诊断

`useWaffle` 自动显示已崩溃 **Aniwaffle 诊断** 按钮 发展权利底线建设。 点击它扩展; 再次点击或按 Escape 里面会倒塌 生产建筑把它藏起来。 设定 `diagnostics: false` 或者说 `true` 在钩子选项中覆盖。 默认遵循应用程序捆绑器 `process.env.NODE_ENV`。 。 。 .

读取 `client.diagnostics` 并订阅 `client.on('diagnostics', render)`。 。 。 . 反应返回相同的快照 `waffle.diagnostics`; 渲染 `<WaffleDiagnosticsPanel waffle={waffle} />` 从 `@animated-waffle/react` 用于内置 视图,与 `diagnostics: false` 以避免同时显示覆盖. 其他浏览器应用 `mountWaffleDiagnostics(host, client)` 从 `@animated-waffle/web`搭载面板从不启动连接或麦克风.

面板显示连接/ 媒体/ Avatar 状态, 连接阶段, 最新的客户端 输入端回放估计,安全出错和当前会话工作室链接. 更新的工人还报告使用ASR、LLM、TTS和工人-产出计时 工作室的减员。 客户端和服务器行有单独的关联ID和时钟; 不对阶段进行总和,也不将工人输出作为浏览器回放。 缺少数据 仍然无法使用。 语音输入活动和RTC/paired输出时间是估计数, 没有校正声学测量。 抓图不包括文本、音频、符号和原始 错误消息 。 面板是可选的;现有的计时遥测独立于面板.

## 微型手机计数器和设备选择器

```tsx
import { useWaffle, WaffleMicrophoneControls, WaffleInputMeter } from '@animated-waffle/react'

const waffle = useWaffle({ agentId, sessionToken })
// Includes the current input name, live meter, in-call device switch and input notices.
<WaffleMicrophoneControls waffle={waffle} />
// Or render your own controls around these primitives:
<WaffleInputMeter level={waffle.inputLevel} />
// waffle.microphone.devices, waffle.microphone.deviceId, waffle.setInputDevice(id)
```

这些组件不要求在挂载时捕获 。 首先连接以获取设备 标签和活的能量。 仪表显示的是麦克风能量 而不是ASR或证明 用户正在发言. `waffle.inputIssue` 单独包含非致命输入反馈 从连接出错。 设备开关错误留在选择器旁边 .

## 地区

使用 `useWaffle({ agentId, sessionToken, region: 'jp' })` 选择日本 API 和代理,或 `region: 'us'` 为美国. `connect({ region: 'jp' })` 覆盖新连接的默认值。 对于DEV, 也设定 `apiOrigin: 'https://dev.aniwaffle.com'`;自定义 API 来源保持不变。 见 [区域指南](https://aniwaffle.com/docs/sdk#regions)。 。 。 .

## 常见问题

### @animated-waffle/react 是什么？

纳里亚动画"华夫饼"谈话代理商的反向钩和"神通"渲染器\. 再出口@animated-waffle/客户\.

### 如何安装 @animated-waffle/react？

在项目目录运行 npm install @animated-waffle/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @animated-waffle/react 支持 TypeScript 吗？

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

### @animated-waffle/react 支持 ESM 还是 CommonJS？

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

### @animated-waffle/react 可以商用吗？

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

### @animated-waffle/react 的下载量有多少？

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

### @animated-waffle/react 还在维护吗？

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