npm package: @itzhou/chat-agent-sdk
Description: 这是一个基于 Vue 3 和 TypeScript 开发的轻量级智能客服 SDK，支持接入阿里云百炼大模型，提供流式对话体验。
Latest version: 0.1.0

# Chat Agent SDK

这是一个基于 Vue 3 和 TypeScript 开发的轻量级智能客服 SDK，支持接入阿里云百炼大模型，提供流式对话体验。

**注意：本 SDK 内置了 Vue 3 运行时，可以独立运行，兼容 Vue 2、React、Angular 或原生 HTML/JS 项目。**

## 特性

*   💬 **流式对话**：支持 SSE（Server-Sent Events）打字机效果。
*   🤖 **百炼接入**：开箱即用的阿里云百炼 API 集成。
*   🎨 **高度可定制**：支持自定义主题色、图标、标题、尺寸、字体等。
*   💅 **Markdown 支持**：内置 Markdown 渲染。
*   📦 **开箱即用**：提供 UMD 和 ESM 两种格式，支持 Script 标签直接引入或 NPM 安装。

## 安装

### 方式一：通过 NPM 安装

```bash
npm install chat-agent-sdk
```

### 方式二：通过 CDN / Script 标签引入

可以直接引入构建好的 JS 和 CSS 文件。

```html
<!-- 引入样式 -->
<link rel="stylesheet" href="https://unpkg.com/chat-agent-sdk/dist/chat-agent-sdk.css">

<!-- 引入 JS -->
<script src="https://unpkg.com/chat-agent-sdk/dist/chat-agent.umd.js"></script>
```

## 快速开始

### 1. Vue 3 项目 (推荐)

```typescript
import { initChatAgent } from 'chat-agent-sdk';
import 'chat-agent-sdk/style.css'; 

// 在组件挂载时初始化，或在全局初始化
const chat = initChatAgent({
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  ui: {
    title: '我的智能助手',
    primaryColor: '#FF5722',
    logo: 'https://example.com/logo.png'
  }
});
```

### 2. Vue 2 项目集成

虽然本 SDK 使用 Vue 3 开发，但由于它独立挂载，**完全可以在 Vue 2 项目中使用**。请勿尝试直接注册为 Vue 组件，而应将其视为一个普通的 JS 库。

```javascript
import { initChatAgent } from 'chat-agent-sdk';
import 'chat-agent-sdk/style.css';

export default {
  mounted() {
    // 初始化 SDK
    this.chatInstance = initChatAgent({
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_API_KEY'
    });
  },
  beforeDestroy() {
    // 销毁 SDK (如果需要)
    if (this.chatInstance) {
      this.chatInstance.unmount();
    }
  }
}
```

### 3. 浏览器全局变量引入 (Vue 2 / jQuery / 原生)

```html
<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="./chat-agent-sdk.css">
    <!-- 引入 Vue 2 (宿主环境) -->
    <script src="https://cdn.jsdelivr.net/npm/vue@2"></script>
</head>
<body>
    <div id="app"></div>

    <!-- 引入 SDK -->
    <script src="./chat-agent.umd.js"></script>
    
    <script>
        new Vue({
            el: '#app',
            mounted() {
                // SDK 暴露在 window.ChatAgent 下
                window.ChatAgent.init({
                    appId: 'xxx',
                    apiKey: 'xxx',
                    ui: {
                        primaryColor: '#009688',
                        width: '400px'
                    }
                });
            }
        })
    </script>
</body>
</html>
```

## 配置参数 (ChatConfig)

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `appId` | `string` | 是 | 阿里云百炼应用 ID |
| `apiKey` | `string` | 是 | 阿里云百炼 API Key (建议在服务端代理，前端通过 `apiEndpoint` 接入) |
| `apiEndpoint` | `string` | 否 | 自定义 API 端点。如果设置，将向此地址发送请求，而不是直接请求阿里云。 |
| `ui` | `ChatUIConfig` | 否 | UI 自定义配置，详见下表 |

### UI 配置 (ChatUIConfig)

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `title` | `string` | `'智能客服'` | 聊天窗口顶部的标题 |
| `logo` | `string` | `undefined` | 悬浮球图标和聊天窗口头像的 URL (若不传则使用默认 emoji) |
| `primaryColor` | `string` | `'#007bff'` | 主题色 (影响悬浮球背景、用户气泡、按钮等) |
| `width` | `string` | `'380px'` | 聊天窗口宽度 |
| `height` | `string` | `'600px'` | 聊天窗口高度 |
| `fontFamily` | `string` | `inherit` | 字体设置 |
| `zIndex` | `number` | `9999` | 悬浮球和窗口的 z-index 层级 |

## 开发与构建

```bash
# 安装依赖
npm install

# 本地开发
npm run dev

# 构建生产版本
npm run build
```

## License

MIT