# @rayvision/ai-chat 中文文档

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

版本：0\.0\.2
npm 元数据更新时间：2026-11-02T06:11:05.232Z
中文译文更新时间：2026-11-02T07:06:00.878Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：805 kB，40 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2026-10-22T08:25:17.787Z
- 最新版本发布：2026-11-02T06:11:05.019Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

共享Renderbus AI聊天UI包

## 安装

```sh
npm install @rayvision/ai-chat
```

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

## README

# @rayvision/ai-chat

Renderbus AI Chat React 组件，提供流式问答、Markdown、引用、建议问题、附件上传、会话恢复和中英文界面。

## 安装

```bash
npm install @rayvision/ai-chat
```

需要 React 和 React DOM 18 或更高版本。

## 快速开始

```tsx
import { useRef, useState } from 'react'
import { AIChat, createAIChatController, createCustomerV1ChatAdapter } from '@rayvision/ai-chat'

export function App(): JSX.Element {
  const [container, setContainer] = useState<HTMLDivElement | null>(null)
  const controller = useRef(
    createAIChatController({
      adapter: createCustomerV1ChatAdapter(),
    }),
  ).current

  return (
    <>
      <div ref={setContainer} />
      <AIChat container={container} controller={controller} language='zh' theme='light' />
    </>
  )
}
```

`AIChat` 会把界面挂载到 `container` 的 Shadow DOM 中，并自动注入组件样式。`container` 为 `null` 时组件不会渲染。

对于 Vue 等非 React 宿主，可以直接使用 `mountAIChat`：

```ts
import { mountAIChat } from '@rayvision/ai-chat'

const chat = mountAIChat(document.querySelector('#ai-chat')!, {
  language: 'zh',
  launcher: false,
})

chat.controller.toggle(true)
// 页面卸载时调用
chat.destroy()
```

该 API 会在包内部创建 React root、controller 和 Shadow DOM，宿主只需要提供一个 DOM 容器。

## Gateway 适配器

默认适配器请求同源地址 `/api/ai-assistant/v1`，使用浏览器 Cookie 携带会话信息：

```tsx
const adapter = createCustomerV1ChatAdapter({
  baseUrl: '/api/ai-assistant/v1',
  module: 'tasks',
  knowledgeScope: 'public',
})

const controller = createAIChatController({ adapter })
```

选项：

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `baseUrl` | `string` | Gateway v1 基础地址，默认 `/api/ai-assistant/v1` |
| `module` | `string` | 建议问题和请求使用的业务模块 |
| `knowledgeScope` | `'public'` | 知识库范围 |

宿主应用需要保证 `baseUrl` 可访问，并按服务端要求配置 Cookie、跨域和代理。

## 组件配置

```tsx
<AIChat container={container} controller={controller} language='en' theme='dark' launcher={false} />
```

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `container` | `HTMLElement | null` | 无 | Shadow DOM 的宿主节点 |
| `controller` | `AIChatController` | 必填 | 管理会话、消息和请求 |
| `language` | `'zh' | 'en'` | `'zh'` | 界面语言 |
| `theme` | `'light' | 'dark'` | `'light'` | 初始主题 |
| `launcher` | `boolean | AIChatLauncherProps` | `true` | 是否显示悬浮打开按钮 |
| `adapter` | `ChatAdapter` | controller 的适配器 | 替换请求实现 |

通过 `launcher` 对象可以设置按钮属性：

```tsx
<AIChat
  container={container}
  controller={controller}
  launcher={{
    disabled: false,
    className: 'my-ai-chat-launcher',
  }}
/>
```

## 控制器

```tsx
const controller = createAIChatController({
  defaultOpen: false,
})

await controller.initialize()
controller.toggle(true)
controller.setLanguage('zh')
controller.setDraft('如何提交渲染任务？')
controller.send()
controller.cancel()
controller.clear()
```

常用方法：

-   `initialize()`：加载建议问题和附件配置。
-   `toggle(show?)`：打开或关闭聊天面板。
-   `setDraft(draft)`、`send()`：设置并发送文本问题。
-   `addFiles(files)`、`removeAttachment(id)`：管理附件。
-   `restoreConversation(conversationId, limit?)`：恢复历史会话。
-   `cancel()`：取消当前流式请求。
-   `destroy()`：释放控制器资源。

## 自定义适配器

如果后端不是 Gateway v1，可以实现 `ChatAdapter` 并注入控制器：

```tsx
import type { ChatAdapter } from '@rayvision/ai-chat'

const adapter: ChatAdapter = {
  send(input, handlers) {
    // 调用业务接口，并通过 handlers.onDelta / onComplete / onError
    // 把流式结果通知给组件。
    return {
      cancel() {
        // 取消请求
      },
    }
  },
}

const controller = createAIChatController({ adapter })
```

`send` 至少需要实现 `onDelta`、`onComplete` 和 `onError` 对应的调用逻辑。附件、建议问题、历史会话和引用详情为可选能力。

## 导出内容

主要导出包括：

-   组件：`AIChat`
-   工具：`mountAIChat`、`createAIChatController`、`createCustomerV1ChatAdapter`
-   类型：`AIChatProps`、`AIChatController`、`ChatAdapter`、`ChatMessage`、`Citation`、`Attachment`

## 浏览器要求

组件使用 `fetch`、`AbortController`、`Shadow DOM` 和 `File` API。请在支持这些 Web API 的现代浏览器中使用。

## 常见问题

### @rayvision/ai-chat 是什么？

共享Renderbus AI聊天UI包

### 如何安装 @rayvision/ai-chat？

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

### @rayvision/ai-chat 支持 TypeScript 吗？

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

### @rayvision/ai-chat 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @rayvision/ai-chat 可以商用吗？

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

### @rayvision/ai-chat 还在维护吗？

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