npm package: @kingsoft-ai/chat
Description: AI聊天组件库 - 面向大模型对话场景的业务组件库
Latest version: 0.1.10

# @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，支持主题切换

**示例：**

```tsx
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` | - | 自定义样式 |

## 🚀 快速开始

### 安装

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

### 基础使用

```tsx
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>
  )
}
```

### 主题定制

```tsx
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，可以这样做：

```tsx
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 作为测试框架。

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

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

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

# 打开 Vitest UI
pnpm test:ui
```

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

## 🔨 开发

### 构建

```bash
# 构建组件库
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组件：

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

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

### 2. Token驱动

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

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

### 3. 可组合性

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

```tsx
<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](https://www.conventionalcommits.org/)：

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