@rayvision/ai-chat

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

安装

npm install @rayvision/ai-chat

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

快速开始

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：

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 携带会话信息：

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

const controller = createAIChatController({ adapter })

选项：

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

组件配置

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

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

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

控制器

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 并注入控制器：

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 的现代浏览器中使用。