@kingsoft-ai/chat

面向大模型对话场景的 AI 聊天组件库，基于 React 和 Emotion 构建，使用三层 Design Token 体系。

📦 组件库定位

@kingsoft-ai/chat 是一个业务组件库，专注于 AI 对话场景的高级组件：

• ✅ 业务组件：针对 AI 聊天场景的复杂组件（欢迎组件、消息组件、对话列表等）
• ❌ 原子组件：基础UI组件如 Button、Checkbox 等请使用 @kingsoft-ai/design

与 @kingsoft-ai/design 的区别

| 特性 | @kingsoft-ai/design | @kingsoft-ai/chat | |------|-------------|-----------| | 定位 | 原子组件库 | 业务组件库 | | 组件示例 | Button、Checkbox、Radio、Input | Welcome、Message、ChatInput、Conversation | | 使用场景 | 通用UI场景 | AI对话场景 | | Token层级 | 基础三层Token | 扩展聊天场景Token |

🎨 设计Token体系

本组件库遵循三层 Design Token 架构，并在此基础上扩展了聊天场景的特定Token：

@kingsoft-ai/theme (基础层)
    ↓
@kingsoft-ai/chat/styles/theme (扩展层)
    ├── chat.semantic (聊天场景语义Token)
    └── chat.components (聊天组件Token)

Token文件结构

src/
├── styles/
│   └── theme.ts          # 第二层(语义)和第三层(组件)Token

📚 组件列表

Welcome 欢迎组件

用于AI对话开始时的欢迎界面，展示助手信息和功能介绍。

特性：

• 支持左对齐和居中两种布局
• 可自定义头像（emoji、图标或图片）
• 灵活的标题和描述配置
• 完全基于Design Token，支持主题切换

示例：

import { Welcome } from '@kingsoft-ai/chat'
import { CustomThemeProvider } from '@kingsoft-ai/theme'
import { lightChatTheme } from '@kingsoft-ai/chat/styles'

function App() {
  return (
    <CustomThemeProvider theme={lightChatTheme}>
      <Welcome
        title="你好，我是超级助手Emily"
        description="我能够快速总结预警数据、回答HSE专业知识问题、为您体验平台特色功能提供引导。"
        avatar="👋"
        layout="left"
      />
    </CustomThemeProvider>
  )
}

Props:

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | title | string | "你好，我是超级助手Emily" | 欢迎标题 | | description | string | - | 欢迎描述 | | avatar | React.ReactNode | "👋" | 头像内容 | | avatarSize | 'default' \| 'large' | 'default' | 头像尺寸 | | layout | 'left' \| 'center' | 'left' | 布局方式 | | className | string | - | 自定义类名 | | style | React.CSSProperties | - | 自定义样式 |

🚀 快速开始

安装

pnpm add @kingsoft-ai/chat @kingsoft-ai/theme

基础使用

import { Welcome } from '@kingsoft-ai/chat'
import { CustomThemeProvider } from '@kingsoft-ai/theme'
import { lightChatTheme } from '@kai/chat/styles'

function ChatApp() {
  return (
    <CustomThemeProvider theme={lightChatTheme}>
      <Welcome />
    </CustomThemeProvider>
  )
}

主题定制

import { lightChatTheme, darkChatTheme } from '@kai/chat/styles'
import { CustomThemeProvider } from '@kingsoft-ai/theme'

function App() {
  const [isDark, setIsDark] = useState(false)
  
  return (
    <CustomThemeProvider theme={isDark ? darkChatTheme : lightChatTheme}>
      {/* 你的应用 */}
    </CustomThemeProvider>
  )
}

自定义Token

如需扩展或覆盖Token，可以这样做：

import { lightChatTheme } from '@kai/chat/styles'

const customTheme = {
  ...lightChatTheme,
  chat: {
    ...lightChatTheme.chat,
    components: {
      ...lightChatTheme.chat.components,
      welcome: {
        ...lightChatTheme.chat.components.welcome,
        title: {
          ...lightChatTheme.chat.components.welcome.title,
          color: '#FF0000', // 自定义标题颜色
        },
      },
    },
  },
}

🧪 测试

本包使用 Vitest + Testing Library 作为测试框架。

# 交互式测试（watch 模式）
pnpm test

# 一次性运行所有测试
pnpm test:run

# 生成覆盖率报告
pnpm test:coverage

# 打开 Vitest UI
pnpm test:ui

测试文件位于 src/<component>/__tests__/*.test.tsx。

🔨 开发

构建

# 构建组件库
pnpm build:lib

# 清理并重新构建
pnpm prepare:lib

# 仅清理构建产物
pnpm clean

本地开发

1. 克隆仓库
2. 安装依赖：pnpm install
3. 构建 theme 包：cd packages/theme && pnpm build:lib
4. 回到 chat 包：cd ../chat-components
5. 运行测试：pnpm test

📋 依赖要求

Peer Dependencies

• React >= 18
• @emotion/react >= 11
• @emotion/styled >= 11
• @kingsoft-ai/theme (workspace)

为什么这些是 peer dependencies？

• 灵活性：允许项目使用自己的React版本
• 避免重复：防止多个React实例导致的问题
• 包大小：减少最终打包体积

🎯 设计原则

1. 场景专注

专注于AI对话场景，不做通用UI组件：

// ✅ 正确 - 聊天场景组件
<Welcome />
<ChatMessage />
<ConversationList />

// ❌ 错误 - 通用组件应使用 @kai/design
<Button />
<Input />
<Checkbox />

2. Token驱动

所有样式通过Design Token定义，确保：

• 主题切换无缝
• 设计一致性
• 易于维护

3. 可组合性

组件设计遵循组合原则，支持灵活搭配：

<ChatContainer>
  <Welcome />
  <MessageList>
    <Message />
    <Message />
  </MessageList>
  <ChatInput />
</ChatContainer>

🗺️ Roadmap

• [ ] Message - 消息组件（用户/助手消息）
• [ ] MessageList - 消息列表组件
• [ ] ChatInput - 聊天输入组件
• [ ] TypingIndicator - 输入中指示器
• [ ] QuickReply - 快捷回复组件
• [ ] ConversationList - 对话列表组件
• [ ] AvatarGroup - 头像组组件
• [ ] CodeBlock - 代码块组件（for AI回复）
• [ ] ThinkingBubble - 思考气泡组件

📄 许可证

MIT License

🤝 贡献指南

1. 创建功能分支：git checkout -b feature/your-feature
2. 提交改动：git commit -m 'feat: add some feature'
3. 推送分支：git push origin feature/your-feature
4. 提交 Pull Request

Commit 规范

遵循 Conventional Commits：

• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• style: 代码格式（不影响功能）
• refactor: 重构
• test: 测试相关
• chore: 构建/工具链相关