# @eloquentai/chat-sdk 中文文档

规范地址：https://npmcn.com/package/%40eloquentai/chat-sdk/

版本：0\.36\.1
npm 元数据更新时间：2026-11-12T05:05:37.540Z
中文译文更新时间：2026-11-13T13:45:23.693Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40eloquentai/chat-sdk
原文对照：https://npmcn.com/package/%40eloquentai/chat-sdk/?lang=original
项目主页：https://github.com/Eloquent-AI/eloquent-ai-chat-sdk#readme
源码仓库：https://github.com/Eloquent-AI/eloquent-ai-chat-sdk

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

- 包体积（解压后）：3.6 MB，95 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：12 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2025-01-10T12:08:16.054Z
- 最新版本发布：2026-11-12T05:05:37.311Z
- 近 30 天下载量：5929（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：303（近 12 个月 152 个）

## 中文简介

反应 SDK 用于将 Eloalent AI 的聊天功能整合到您的应用程序中.

## 安装

```sh
npm install @eloquentai/chat-sdk
```

也可以使用：`pnpm add @eloquentai/chat-sdk`、`yarn add @eloquentai/chat-sdk`、`bun add @eloquentai/chat-sdk`

## README

# @elocalentai/chat-sdk (英语)

反应 SDK 用于将 Eloalent AI 的聊天功能整合到您的应用程序中.

## 先决条件

-   反应 18 或更高(仅用于执行反应)
-   节点.js 18或以上
-   支持ES6+的现代浏览器

## 安装

```bash
# Using npm
npm install @eloquentai/chat-sdk

# Using yarn
yarn add @eloquentai/chat-sdk

# Using pnpm
pnpm add @eloquentai/chat-sdk
```

## 快速启动

### 反应执行

要在反应应用程序中使用 SDK,请导入 `Chat` 组件来自 SDK.

```jsx
import { Chat } from "@eloquentai/chat-sdk";

function App() {
  return (
    <Chat
      // REQUIRED - Your Eloquent AI app ID
      appId="YOUR_APP_ID"
      // OPTIONAL - You can provide a unique id that should be used to identify the user
      userId={crypto.randomUUID()}
    />
  );
}
```

别忘了在你的应用程序里 输入底片样式

```jsx
import "@eloquentai/chat-sdk/index.css";
```

### 香草执行

要在香草环境中使用 SDK, 请在 HTML 文件中列入脚本标记并呼叫 `renderChat`。 。 。 .

```html
<script src="https://unpkg.com/@eloquentai/chat-sdk"></script>

<div id="chat-container"></div>

<script>
  EloquentChatSDK.renderChat(document.getElementById("chat-container"), {
    // REQUIRED - Your Eloquent AI app ID
    appId: "YOUR_APP_ID",
    // OPTIONAL - You can provide a unique id that should be used to identify the user
    userId: crypto.randomUUID(),
  });
</script>
```

`renderChat` 返回您可以调用以删除聊天部件的卸载函数 :

```html
<script>
  const unmount = EloquentChatSDK.renderChat(
    document.getElementById("chat-container"),
    { appId: "YOUR_APP_ID" },
  );

  // Later, to remove the widget:
  unmount();
</script>
```

## 特征

-   **浮动聊天部件** ——一个发射机泡和聊天窗口,在被隔离的iframe中被制成,所以主机页面样式从不漏入出.
-   **实时消息** – 助手在WebSocket连接(AWS AppSync)上进行回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回的回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回.
-   **持续对话** ——主动对话通过本地存储自动恢复(如在页面重载上).
-   **用户识别** ——支持基于匿名设备的身份以及可选的外部用户ID和自定义用户元数据.
-   **主动/欢迎信息** ——可选信息泡可以自动出现,邀请用户开始对话.
-   **聊天收视率** ——用户可以在一次谈话被关闭或升级后进行评分.
-   **人员交接/升级** ——SDK在对话升级为人代理时会承认,并相应关闭AI聊天会话.
-   **他们** ——自定义气泡颜色和合法文本来与你的品牌相匹配.
-   **移动响应器** ——自动调整移动取景口布局.

## 配置

### `Chat` 组件道具

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `appId` | `string` | 对 | 你的口语AI应用程序ID. |
| `userId` | `string` | 没有 | 用户独有的标识符 。 如果省略,则使用匿名设备ID取而代之. |
| `userName` | `string` | 没有 | 用户的显示名 . |
| `userData` | `Record<string, string | number | boolean>` | 没有 | 任意元数据附于用户/对话(如计划,账户类型). |
| `theme` | `Partial<ThemeContextType>` | 没有 | 超音速——见 [他们](https://npmcn.com/package/%40eloquentai/chat-sdk/#readme-theming) 见下文. |
| `chatProps` | `Partial<ChatInterfaceProps>` | 没有 | 精细的UI配置——见 [聊天界面选项](https://npmcn.com/package/%40eloquentai/chat-sdk/#readme-chat-interface-options)。 。 。 . |
| `isMobile` | `boolean` | 没有 | 强制移动布局而非依赖自动取景口检测. |
| `closeButton` | `boolean` (默认 : `true`(中文(简体) ) | 没有 | 在聊天标题中显示/隐藏关闭按钮 . |
| `cleanChatButton` | `boolean` (默认 : `true`(中文(简体) ) | 没有 | 显示/隐藏"启动新聊天"按钮. |
| `initialOpen` | `boolean` (默认 : `false`(中文(简体) ) | 没有 | 默认聊天窗口是否打开 . |
| `proactiveMessageHideDelay` | `number` (默认 : `5000`(中文(简体) ) | 没有 | 在主动/受欢迎消息自动快取前的毫秒. |

### 聊天界面选项

路过 `chatProps` 道具 (英语).

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `displayWelcomeMessages` | `boolean` | 启用主动欢迎的信息泡沫 . |
| `assistantName` | `string` | 在聊天头中为助手显示的名称 . |
| `assistantLogo` | `string` | 显示助手标志的 URL . |
| `legalText` | `string` | 聊天窗口中显示的法律/免责文本. |
| `hasCopyButton` | `boolean` | 在助理信件上显示"副本"按钮. |
| `collectUserFeedback` | `boolean` | 启用助理信件的上下拇指反馈 . |
| `suggestedMessages` | `boolean` | 向用户显示推荐信件芯片 . |
| `title` | `string` | 在聊天标题中显示标题 . |
| `subtitle` | `string` | 聊天标题中显示的字幕 . |
| `onMessageClick` | `(message: MessageData) => void` | 当一个消息被点击时, 调用已启动 . |

### 他们

```jsx
<Chat
  appId="YOUR_APP_ID"
  theme={{
    userBubbleColor: "#6f34b7",
    legalText: "Powered by Eloquent AI",
  }}
/>
```

| 财产 | 说明 |
| --- | --- |
| `userBubbleColor` | 最终用户聊天泡的背景颜色. |
| `legalText` | 提供以下法律/免责条款. |

## 高级用途

### `renderChat`

程序上将聊天部件上载到任何DOM元素中——由香草/UMD构建内部使用,但也可以从ES模块中获取,用于非JSX设置:

```js
import { renderChat } from "@eloquentai/chat-sdk";

const unmount = renderChat(document.getElementById("chat-container"), {
  appId: "YOUR_APP_ID",
});
```

### `ChatInterface`

聊天窗口UI没有浮动的放出器气泡或iframe隔离,用于将聊天直接嵌入到您自己的布局(例如专用支持页面).

```jsx
import { ChatInterface } from "@eloquentai/chat-sdk";

<ChatInterface
  isOpen
  closeButton={false}
  cleanChatButton
  messages={messages}
  onSendMessage={onSendMessage}
/>;
```

### `useRealtimeSocket`

直接订阅实时对话事件流的下级钩子, 如果您需要自定义消息处理到所提供的组件之外 .

```jsx
import { useRealtimeSocket } from "@eloquentai/chat-sdk";

const { connect, disconnect, clearProcessedIds } = useRealtimeSocket({
  chatSettings,
  chatId,
  messages,
  onMessage: (response, chatId) => {
    /* handle incoming assistant message */
  },
  onCognition: (content) => {
    /* assistant is "thinking" */
  },
  onCognitionComplete: () => {},
  fetchHistory: async (chatId) => [],
});
```

## 支助

关于问题、专题请求或问题,请与口头AI小组联系.

## 常见问题

### @eloquentai/chat-sdk 是什么？

反应 SDK 用于将 Eloalent AI 的聊天功能整合到您的应用程序中\.

### 如何安装 @eloquentai/chat-sdk？

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

### @eloquentai/chat-sdk 支持 TypeScript 吗？

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

### @eloquentai/chat-sdk 支持 ESM 还是 CommonJS？

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

### @eloquentai/chat-sdk 可以商用吗？

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

### @eloquentai/chat-sdk 的下载量有多少？

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

### @eloquentai/chat-sdk 还在维护吗？

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