@aientry/chat

v0.1.0

Published

a month ago

AIEntry embeddable chat widget SDK

0High
0Medium
0Low

kevinbrother2

AIEntry Chat Widget

嵌入式聊天组件，支持两种构建模式。

构建

# 构建所有模式
pnpm build

# 或分别构建
pnpm build:sdk      # SDK 模式（CSS 打包到 JS）
pnpm build:module   # Module 模式（CSS 独立输出）

使用方式

1. SDK 模式（推荐用于嵌入到网页）

特点：

CSS 已打包到 JS 文件中
只需引入一个 JS 文件
适合通过 <script> 标签直接引入

HTML 使用：

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Chat Widget Demo</title>
</head>
<body>
  <!-- Chat widget will be mounted here -->
  <div id="chat-widget-app"></div>

  <!-- 引入 SDK（CSS 已内置） -->
  <script src="path/to/dist/sdk/chat-sdk.umd.js"></script>

  <script>
    // SDK 会自动初始化并挂载到 #chat-widget-app
    // 或者手动控制
    const widget = AientryChatSDK.initChatApp({
      kbId: 'your-kb-id',
      autoMount: true,
      mode: 'bubble',
      launcher: true
    });
  </script>
</body>
</html>

NPM 使用：

import '@aientry/chat/sdk'
// 或
import { initChatApp } from '@aientry/chat/sdk'

const widget = initChatApp({
  kbId: 'your-kb-id',
  autoMount: true
})

2. Module 模式（推荐用于 React 项目）

特点：

CSS 独立输出为 .css 文件
需要同时引入 JS 和 CSS
适合作为 npm 包在 React 项目中使用

使用方式：

// 1. 导入 CSS（必须）
import '@aientry/chat/style.css'

// 2. 导入组件
import { ChatApp } from '@aientry/chat/module'
// 或使用默认导入
import { initChatApp } from '@aientry/chat'

function App() {
  return (
    <ChatApp kbId="your-kb-id" />
  )
}

或者使用命令式 API：

import '@aientry/chat/style.css'
import { initChatApp } from '@aientry/chat'

const widget = initChatApp({
  kbId: 'your-kb-id',
  autoMount: true,
  mode: 'bubble',
  launcher: true,
  position: 'fixed',
  zIndex: 9999
})

// 控制 widget
widget.open()
widget.close()
widget.unmount()

两种模式的输出

SDK 模式输出

dist/sdk/
├── chat-sdk.es.js      # ES Module（包含 CSS）
└── chat-sdk.umd.js     # UMD（包含 CSS）

Module 模式输出

dist/module/
├── chat-sdk.es.js      # ES Module
├── chat-sdk.umd.js     # UMD
├── style.css           # 独立的 CSS 文件
└── types/                      # TypeScript 类型定义

Package.json Exports

{
  "exports": {
    ".": "./dist/module/...",           // 默认是 Module 模式
    "./sdk": "./dist/sdk/...",          // SDK 模式
    "./module": "./dist/module/..."     // Module 模式（显式）
  }
}

API

详见 TypeScript 类型定义。

主要导出：

initChatApp(options) - 初始化聊天组件
ChatApp - React 组件
createChatWidget(options) - 创建聊天组件实例
initChatSDK(config) - 配置 SDK

开发

pnpm dev          # 开发模式
pnpm dev:test     # 测试页面开发模式
pnpm preview      # 预览构建结果
pnpm lint         # 代码检查

近期更新 (2025-01-07)

组件重构

重构了聊天界面以提高可复用性和响应式体验：

新增组件:

ChatCore - 核心聊天组件（不含头部和徽章）
ResizableChatWindow - 可调整大小的聊天窗口包装器

更新组件:

ChatWindow - 现在使用 ChatCore，支持 showHeader 和 showBadge props

架构设计

核心组件

| 组件 | 职责 | |------|------| | Chat | 聊天主界面：消息列表、输入框、欢迎页 | | FloatingChat | 浮动聊天入口：管理浮窗按钮、聊天窗口、Portal 渲染 | | createChatWidget | SDK 工厂函数：创建 ChatWidgetController 实例 | | FloatButton | 浮动开关按钮 | | FloatingChatWindow | 可拖拽/调整大小的聊天窗口 | | ChatContainer | Chat 包装容器 | | FloatingChatContext | 浮动聊天状态共享（碰撞检测、视口检测） |

构建配置

vite.config.sdk.ts - SDK 构建
vite.config.module.ts - Module 构建

文档

CHORE.md - 完整的重构设计文档
docs/MCP_TESTING.md - MCP 协议测试指南
docs/PERFORMANCE_REPORT.md - 性能测试报告