ai-chat-ui-kit 0.1.0 → 0.1.1

package/docs/api/components.md

@@ -1,344 +0,0 @@
-# Components 包 API 参考
-
-Components 包提供了基于 Lit 的 Web Components 封装，可直接在 HTML 中使用，也可在 React、Vue 等框架中使用。
-
-## 安装
-
-```bash
-pnpm add @ai-chat/components @ai-chat/themes
-```
-
-## 组件列表
-
-- [`<ai-chat>`](#ai-chat) - 聊天容器组件
-- [`<ai-message>`](#ai-message) - 消息组件
-- [`<ai-input>`](#ai-input) - 输入框组件
-- [`<ai-tool-call>`](#ai-tool-call) - 工具调用组件
-
-## `<ai-chat>`
-
-聊天容器组件，包含所有子组件。
-
-### 属性 (Properties)
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `theme` | `string` | `'default'` | 主题名称 (`'default'`, `'bubble'`, `'flat'`) |
-| `loading` | `boolean` | `false` | 是否显示加载状态 |
-| `placeholder` | `string` | `'输入消息...'` | 输入框占位符 |
-| `welcomeMessage` | `string` | `''` | 欢迎消息（AI 发送） |
-
-### 方法 (Methods)
-
-| 方法 | 参数 | 返回值 | 说明 |
-|------|------|--------|------|
-| `setMessageHandler` | `(handler: (message: string) => Promise<string>)` | `void` | 设置消息处理回调 |
-| `addMessage` | `(message: Message)` | `void` | 添加一条消息 |
-| `clearMessages` | - | `void` | 清除所有消息 |
-| `getMessages` | - | `Message[]` | 获取所有消息 |
-| `updateLastMessage` | `(content: string)` | `void` | 更新最后一条消息（用于流式响应） |
-| `applyTheme` | `(theme: ThemeConfig)` | `void` | 应用主题 |
-
-### 事件 (Events)
-
-| 事件名 | 事件对象 | 说明 |
-|--------|----------|------|
-| `message-sent` | `{ detail: { message: string } }` | 用户发送消息时触发 |
-| `message-received` | `{ detail: { message: string } }` | 收到 AI 回复时触发 |
-| `loading-start` | - | 开始加载时触发 |
-| `loading-end` | - | 结束加载时触发 |
-| `error` | `{ detail: { error: string } }` | 发生错误时触发 |
-
-### 插槽 (Slots)
-
-| 插槽名 | 说明 |
-|--------|------|
-| (默认) | 消息列表区域 |
-| `input` | 自定义输入框区域 |
-| `header` | 自定义头部区域 |
-
-### 使用示例
-
-```html
-<!-- 基本用法 -->
-<ai-chat></ai-chat>
-
-<!-- 设置主题 -->
-<ai-chat theme="bubble"></ai-chat>
-
-<!-- 设置欢迎消息 -->
-<ai-chat welcome-message="你好！我是 AI 助手。"></ai-chat>
-```
-
-```javascript
-// JavaScript 交互
-const chat = document.querySelector('ai-chat');
-
-// 设置消息处理回调
-chat.setMessageHandler(async (message) => {
-  // 调用您的 AI API
-  const response = await fetch('/api/chat', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ message })
-  });
-  const data = await response.json();
-  return data.reply;
-});
-
-// 添加消息
-chat.addMessage({
-  role: 'assistant',
-  content: '你好！我是 AI 助手。'
-});
-
-// 监听事件
-chat.addEventListener('message-sent', (e) => {
-  console.log('Message sent:', e.detail.message);
-});
-
-chat.addEventListener('message-received', (e) => {
-  console.log('Message received:', e.detail.message);
-});
-```
-
-### React 中使用
-
-```tsx
-import React, { useEffect, useRef } from 'react';
-import '@ai-chat/components';
-import '@ai-chat/themes/default';
-
-const ChatApp: React.FC = () => {
-  const chatRef = useRef<HTMLElement>(null);
-
-  useEffect(() => {
-    if (chatRef.current) {
-      (chatRef.current as any).setMessageHandler(async (message: string) => {
-        const response = await fetch('/api/chat', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ message })
-        });
-        const data = await response.json();
-        return data.reply;
-      });
-    }
-  }, []);
-
-  return (
-    <div style={{ height: '100vh' }}>
-      <ai-chat ref={chatRef}></ai-chat>
-    </div>
-  );
-};
-
-export default ChatApp;
-```
-
-### Vue 3 中使用
-
-```vue
-<template>
-  <div style="height: 100vh">
-    <ai-chat ref="chatRef"></ai-chat>
-  </div>
-</template>
-
-<script setup lang="ts">
-import { ref, onMounted } from 'vue';
-import '@ai-chat/components';
-import '@ai-chat/themes/default';
-
-const chatRef = ref<HTMLElement>();
-
-onMounted(() => {
-  if (chatRef.value) {
-    (chatRef.value as any).setMessageHandler(async (message: string) => {
-      const response = await fetch('/api/chat', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ message })
-      });
-      const data = await response.json();
-      return data.reply;
-    });
-  }
-});
-</script>
-```
-
-## `<ai-message>`
-
-消息组件，用于显示单条消息（通常不需要直接使用，由 `<ai-chat>` 内部管理）。
-
-### 属性
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `role` | `string` | `''` | 消息角色 (`'user'`, `'assistant'`, `'system'`) |
-| `content` | `string` | `''` | 消息内容 |
-| `timestamp` | `number` | `0` | 消息时间戳 |
-| `avatar` | `string` | `''` | 自定义头像 URL 或 emoji |
-
-### 插槽
-
-| 插槽名 | 说明 |
-|--------|------|
-| (默认) | 消息内容 |
-| `avatar` | 自定义头像 |
-
-### 使用示例
-
-```html
-<ai-message
-  role="user"
-  content="Hello!"
-  timestamp="1715600000000"
-></ai-message>
-
-<ai-message
-  role="assistant"
-  content="Hi there!"
-></ai-message>
-```
-
-## `<ai-input>`
-
-输入框组件（通常不需要直接使用，由 `<ai-chat>` 内部管理）。
-
-### 属性
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `placeholder` | `string` | `'输入消息...'` | 占位符 |
-| `value` | `string` | `''` | 输入框值 |
-| `disabled` | `boolean` | `false` | 是否禁用 |
-| `loading` | `boolean` | `false` | 是否显示加载状态 |
-
-### 事件
-
-| 事件名 | 说明 |
-|--------|------|
-| `send` | 发送消息时触发 |
-| `input` | 输入内容变化时触发 |
-| `keydown` | 按键时触发 |
-
-### 插槽
-
-| 插槽名 | 说明 |
-|--------|------|
-| `prefix` | 输入框前缀 |
-| `suffix` | 输入框后缀（默认包含发送按钮） |
-
-### 使用示例
-
-```html
-<ai-input
-  placeholder="输入消息..."
-  (send)="onSend($event.detail)"
-></ai-input>
-```
-
-## `<ai-tool-call>`
-
-工具调用组件，用于显示 AI 调用的工具（如函数调用）。
-
-### 属性
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `name` | `string` | `''` | 工具名称 |
-| `status` | `string` | `'running'` | 状态 (`'running'`, `'success'`, `'error'`) |
-| `params` | `string` | `''` | 调用参数（JSON 字符串） |
-| `result` | `string` | `''` | 调用结果 |
-
-### 插槽
-
-| 插槽名 | 说明 |
-|--------|------|
-| `icon` | 自定义图标 |
-| `content` | 自定义内容 |
-
-### 使用示例
-
-```html
-<ai-tool-call
-  name="get_weather"
-  status="running"
-  params='{"location": "Beijing"}'
-></ai-tool-call>
-
-<ai-tool-call
-  name="get_weather"
-  status="success"
-  params='{"location": "Beijing"}'
-  result='{"temperature": 25, "condition": "Sunny"}'
-></ai-tool-call>
-```
-
-## CSS 变量
-
-所有组件都使用 CSS 变量，可在全局或组件级别覆盖。
-
-### 完整 CSS 变量列表
-
-```css
-:root {
-  /* 主色 */
-  --ai-primary: #1677ff;
-  --ai-primary-hover: #4096ff;
-  --ai-primary-active: #0958d9;
-
-  /* 背景色 */
-  --ai-bg-primary: #ffffff;
-  --ai-bg-secondary: #f5f5f5;
-  --ai-bg-chat: #f0f2f5;
-
-  /* 文本色 */
-  --ai-text-primary: rgba(0, 0, 0, 0.88);
-  --ai-text-secondary: rgba(0, 0, 0, 0.65);
-
-  /* 消息气泡 */
-  --ai-message-user-bg: #1677ff;
-  --ai-message-user-text: #ffffff;
-  --ai-message-ai-bg: #ffffff;
-  --ai-message-ai-text: rgba(0, 0, 0, 0.88);
-
-  /* 输入框 */
-  --ai-input-bg: #ffffff;
-  --ai-input-border: #d9d9d9;
-  --ai-input-focus-border: #1677ff;
-
-  /* 圆角 */
-  --ai-radius-sm: 4px;
-  --ai-radius-md: 8px;
-  --ai-radius-lg: 12px;
-
-  /* 间距 */
-  --ai-spacing-xs: 4px;
-  --ai-spacing-sm: 8px;
-  --ai-spacing-md: 12px;
-  --ai-spacing-lg: 16px;
-}
-```
-
-### 覆盖示例
-
-```css
-/* 全局覆盖 */
-:root {
-  --ai-primary: #your-color;
-}
-
-/* 组件级别覆盖 */
-ai-chat {
-  --ai-primary: #your-color;
-}
-```
-
-## 下一步
-
-- [Core 包 API](./core.md)
-- [主题定制](../guide/themes.md)
-- [插件开发](../guide/plugins.md)

package/docs/api/core.md

@@ -1,349 +0,0 @@
-# Core 包 API 参考
-
-Core 包提供了 AI Chat UI Kit 的核心逻辑层，包括状态管理、API 适配器和插件系统。
-
-## 安装
-
-```bash
-pnpm add @ai-chat/core
-```
-
-## 导出
-
-```typescript
-// 主要导出
-export { createChatStore } from './store';
-export { createAPIAdapter } from './api';
-export { createPluginSystem } from './plugins';
-export { ChatStore } from './store';
-export { APIAdapter } from './api';
-export { Plugin } from './plugins';
-```
-
-## `createChatStore(config)`
-
-创建一个聊天状态管理实例。
-
-### 参数
-
-```typescript
-interface ChatStoreConfig {
-  // 初始状态（可选）
-  initialState?: {
-    messages?: Message[];
-    isLoading?: boolean;
-    error?: string | null;
-  };
-
-  // 消息处理回调（必填）
-  onMessage: (
-    message: string,
-    options?: { onChunk?: (chunk: string) => void }
-  ) => Promise<string>;
-
-  // 插件列表（可选）
-  plugins?: ChatPlugin[];
-
-  // 全局配置（可选）
-  config?: Record<string, any>;
-}
-```
-
-### 返回值
-
-```typescript
-interface ChatStore {
-  // 获取当前消息列表
-  getMessages(): Message[];
-
-  // 获取当前状态
-  getState(): ChatState;
-
-  // 发送消息
-  sendMessage(message: string): Promise<void>;
-
-  // 添加消息（不触发 AI 回复）
-  addMessage(message: Message): void;
-
-  // 更新最后一条消息（用于流式响应）
-  updateLastMessage(content: string): void;
-
-  // 清除所有消息
-  clearMessages(): void;
-
-  // 订阅状态变化
-  subscribe(listener: (state: ChatState) => void): () => void;
-
-  // 注册插件
-  registerPlugin(plugin: ChatPlugin): void;
-
-  // 启用插件
-  enablePlugin(name: string): void;
-
-  // 禁用插件
-  disablePlugin(name: string): void;
-}
-```
-
-### 示例
-
-```typescript
-import { createChatStore } from '@ai-chat/core';
-
-const chatStore = createChatStore({
-  initialState: {
-    messages: [
-      { role: 'assistant', content: '你好！我是 AI 助手。' }
-    ],
-    isLoading: false,
-    error: null,
-  },
-
-  onMessage: async (message, { onChunk }) => {
-    // 调用您的 AI API
-    const response = await fetch('/api/chat', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ message })
-    });
-
-    const data = await response.json();
-    return data.reply;
-  },
-
-  plugins: [
-    // 插件列表
-  ],
-
-  config: {
-    // 全局配置
-  },
-});
-
-// 使用 store
-chatStore.sendMessage('Hello');
-const messages = chatStore.getMessages();
-```
-
-## `createAPIAdapter(config)`
-
-创建一个 API 适配器实例（工厂函数）。
-
-### 参数
-
-```typescript
-type createAPIAdapter = (
-  config: {
-    type: 'openai' | 'claude' | 'custom';
-    apiKey?: string;
-    model?: string;
-    baseURL?: string;
-    [key: string]: any;
-  }
-) => APIAdapter;
-```
-
-### 返回值
-
-```typescript
-interface APIAdapter {
-  sendMessage(request: ChatRequest): Promise<ChatResponse>;
-  sendMessageStream?(request: ChatRequest, onChunk: (chunk: string) => void): Promise<void>;
-  getHistory?(): Promise<Message[]>;
-  clearHistory?(): Promise<void>;
-}
-```
-
-### 示例
-
-```typescript
-import { createAPIAdapter } from '@ai-chat/core';
-
-// OpenAI
-const openaiAdapter = createAPIAdapter({
-  type: 'openai',
-  apiKey: process.env.OPENAI_API_KEY,
-  model: 'gpt-4',
-});
-
-// Claude
-const claudeAdapter = createAPIAdapter({
-  type: 'claude',
-  apiKey: process.env.CLAUDE_API_KEY,
-  model: 'claude-3-opus-20240229',
-});
-
-// 自定义
-const customAdapter = createAPIAdapter({
-  type: 'custom',
-  baseURL: 'https://your-api.com',
-  token: 'your-token',
-});
-```
-
-## `createPluginSystem()`
-
-创建一个插件系统实例。
-
-### 返回值
-
-```typescript
-interface PluginSystem {
-  register(plugin: ChatPlugin): void;
-  unregister(name: string): void;
-  enable(name: string): void;
-  disable(name: string): void;
-  getPlugin(name: string): ChatPlugin | undefined;
-  getAllPlugins(): ChatPlugin[];
-}
-```
-
-### 示例
-
-```typescript
-import { createPluginSystem, ChatPlugin } from '@ai-chat/core';
-
-const pluginSystem = createPluginSystem();
-
-// 自定义插件
-class MyPlugin implements ChatPlugin {
-  name = 'my-plugin';
-
-  beforeSend(message: string): string {
-    console.log('Sending:', message);
-    return message;
-  }
-}
-
-// 注册插件
-pluginSystem.register(new MyPlugin());
-
-// 使用插件系统
-const chatStore = createChatStore({
-  // ...
-  plugins: pluginSystem.getAllPlugins(),
-});
-```
-
-## 类型定义
-
-### `Message`
-
-```typescript
-interface Message {
-  role: 'user' | 'assistant' | 'system';
-  content: string;
-  timestamp?: number;
-  metadata?: Record<string, any>;
-}
-```
-
-### `ChatState`
-
-```typescript
-interface ChatState {
-  messages: Message[];
-  isLoading: boolean;
-  error: string | null;
-}
-```
-
-### `ChatRequest`
-
-```typescript
-interface ChatRequest {
-  message: string;
-  history?: Message[];
-  model?: string;
-  temperature?: number;
-  maxTokens?: number;
-  [key: string]: any;
-}
-```
-
-### `ChatResponse`
-
-```typescript
-interface ChatResponse {
-  content: string;
-  role: 'assistant';
-  usage?: {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-  };
-  [key: string]: any;
-}
-```
-
-### `ChatPlugin`
-
-```typescript
-interface ChatPlugin {
-  name: string;
-  init?: (context: PluginContext) => void | Promise<void>;
-  beforeSend?: (message: string, context: PluginContext) => string | Promise<string>;
-  afterSend?: (message: string, context: PluginContext) => void | Promise<void>;
-  afterReceive?: (message: string, context: PluginContext) => string | Promise<string>;
-  renderUI?: (container: HTMLElement, context: PluginContext) => void;
-  destroy?: () => void | Promise<void>;
-}
-```
-
-### `PluginContext`
-
-```typescript
-interface PluginContext {
-  getMessages(): Message[];
-  addMessage(message: Message): void;
-  getConfig(): Record<string, any>;
-  setConfig(config: Record<string, any>): void;
-  emit(event: string, data?: any): void;
-  on(event: string, handler: (data: any) => void): void;
-}
-```
-
-## 使用示例
-
-### 完整示例
-
-```typescript
-import { createChatStore, createAPIAdapter } from '@ai-chat/core';
-
-// 1. 创建 API 适配器
-const adapter = createAPIAdapter({
-  type: 'openai',
-  apiKey: process.env.OPENAI_API_KEY,
-  model: 'gpt-3.5-turbo',
-});
-
-// 2. 创建 store
-const chatStore = createChatStore({
-  onMessage: async (message) => {
-    const response = await adapter.sendMessage({
-      message,
-      history: chatStore.getMessages(),
-    });
-    return response.content;
-  },
-});
-
-// 3. 订阅状态变化
-const unsubscribe = chatStore.subscribe((state) => {
-  console.log('Messages:', state.messages);
-  console.log('Loading:', state.isLoading);
-  console.log('Error:', state.error);
-});
-
-// 4. 发送消息
-await chatStore.sendMessage('Hello!');
-
-// 5. 清理
-unsubscribe();
-```
-
-## 下一步
-
-- [Components 包 API](./components.md)
-- [插件开发](../guide/plugins.md)
-- [API 适配器](../guide/api-adapters.md)