npm - ibc-ai-web-sdk - Versions diffs - 2.0.2 → 2.0.4 - Mend

ibc-ai-web-sdk 2.0.2 → 2.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md CHANGED Viewed

@@ -1,607 +1,461 @@
-# IBC AI Web SDK v2.0
+# IBC AI Web SDK v2
-> **纯JavaScript实现的AI对话组件**，支持任意前端框架：Vue、React、Angular、原生HTML等
+> 纯 JavaScript 实现的 AI 智能体对话组件，基于 Web Components，支持任意前端框架。
-## ✨ 特性
+## 快速开始
-- 🚫 **零框架依赖** - 纯JavaScript实现，基于Web Components (Custom Elements + Shadow DOM)
-- 🔌 **框架无关** - 可在Vue/React/Angular/Svelte/原生HTML中无缝使用
-- 🎨 **主题可定制** - 支持亮色/暗色主题，CSS变量自定义
-- 💬 **流式响应** - 支持SSE流式输出，实时显示AI回复
-- 📱 **响应式设计** - 适配桌面端和移动端
-- ♿ **无障碍访问** - 遵循ARIA规范，支持键盘操作
-- 🎯 **轻量级** - Gzip后 < 15KB
+### CDN 引入（最简单）
-## 📦 安装
+```html
+<script src="https://unpkg.com/ibc-ai-web-sdk@2/dist/index.umd.min.js"></script>
+<script>
+  const dialog = AIWebSDK.create({
+    apiEndpoint: '/v1/app/completion',
+    appId: 'your-app-id',
+    userId: 'user-123',
+    bizType: 'chat',
+    token: 'your-auth-token'
+  });
+  dialog.open();
+</script>
+```
+### npm 安装
 ```bash
 npm install ibc-ai-web-sdk
 ```
-或直接引入CDN：
+```js
+import { createAIChatDialog } from 'ibc-ai-web-sdk';
-```html
-<script src="https://unpkg.com/ibc-ai-web-sdk@latest/dist/index.umd.min.js"></script>
+const dialog = createAIChatDialog({
+  apiEndpoint: '/v1/app/completion',
+  appId: 'your-app-id',
+  userId: 'user-123',
+  bizType: 'chat',
+  token: 'your-auth-token'
+});
+dialog.open();
 ```
-## 🚀 快速开始
+### 内嵌模式（作为页面组件嵌入）
-### 方式一：原生HTML使用（最简单）
+指定 `target` 即可将对话组件嵌入到页面的某个容器内，而非浮窗形式：
 ```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>AI Chat Demo</title>
-</head>
-<body>
-  <!-- 触发按钮 -->
-  <button onclick="openChat()">打开AI助手</button>
-  <script type="module">
-    import { createAIChatDialog } from './node_modules/ibc-ai-web-sdk/dist/index.esm.js';
-    // 或CDN方式：
-    // const dialog = AICreateChatDialog({...});
-    let chatInstance;
-    function openChat() {
-      if (!chatInstance) {
-        chatInstance = createAIChatDialog({
-          apiBaseUrl: 'https://your-api.com/ai',
-          authToken: 'your-token',
-          title: '智能客服',
-          placeholder: '请输入您的问题...',
-          theme: 'light'
-        });
-      }
-      chatInstance.open();
-    }
-    // 暴露到全局供onclick调用
-    window.openChat = openChat;
-  </script>
-</body>
-</html>
+<div id="chat-box" style="width:480px;height:680px"></div>
 ```
-### 方式二：Vue项目使用
+```js
+AIWebSDK.create({
+  target: '#chat-box',          // 挂载容器
+  apiEndpoint: '/v1/app/completion',
+  appId: 'your-app-id',
+  userId: 'user-123',
+  bizType: 'chat',
+  token: 'your-auth-token'
+});
+// 内嵌模式自动展开，无需调用 open()
+```
-#### 选项式API（Options API）
+> **npm 用户**：将 `AIWebSDK.create()` 替换为 `createAIChatDialog()` 即可。
-```vue
-<template>
-  <div>
-    <button @click="openChat">打开AI助手</button>
-    <!-- 使用组件包装器 -->
-    <AiChatWrapper
-      :visible.sync="showChat"
-      :config="chatConfig"
-      @message-send="onMessageSend"
-      @message-received="onMessageReceived"
-      @close="showChat = false"
-    />
-  </div>
-</template>
+---
-<script>
-import { installVuePlugin, AIChatDialog } from 'ibc-ai-web-sdk';
+## 配置选项
+| 参数 | 类型 | 默认值 | 必填 | 说明 |
+|------|------|--------|------|------|
+| `apiEndpoint` | string | `/v1/app/completion` | 是 | 对话接口地址 |
+| `apiBaseUrl` | string | `''` | | API 基础地址，拼接到各 endpoint 前 |
+| `appId` | string | `''` | 是 | 智能体应用 ID |
+| `userId` | string | `''` | 是 | 用户标识 |
+| `bizType` | string | `''` | 是 | 业务类型标识 |
+| `token` | string | `''` | | 认证 Token，自动添加到 Authorization 头 |
+| `title` | string | `'AI 助手'` | | 对话框标题（loadAppDetail 会自动覆盖） |
+| `welcomeText` | string | `'Hi，我是智能助手 ~'` | | 欢迎语 |
+| `welcomeDesc` | string | `'全新自动化能力上线...'` | | 欢迎描述 |
+| `theme` | string\|object | `'default'` | | 主题，见下方[主题定制](#主题定制) |
+| `suggestions` | array | 内置默认建议 | | 欢迎页建议列表 `[{ label, value }]` |
+| `timeout` | number | `60000` | | 请求超时（毫秒） |
+| `maxLength` | number | `500` | | 输入最大字符数 |
+| `enableDrag` | boolean | `true` | | 是否允许拖拽对话框 |
+| `headers` | object | `{}` | | 附加请求头 |
+| `extendInfo` | object | `{}` | | 随请求发送的扩展信息 |
+### Token 刷新
-export default {
-  data() {
+提供 `refreshTokenFn` 即可，SDK 会自动处理过期检测和刷新。
+```js
+createAIChatDialog({
+  token: 'initial-access-token',
+  tokenExpiresAt: Date.now() + 30 * 60 * 1000,  // Token 过期时间戳
+  refreshToken: 'initial-refresh-token',          // 可选
+  refreshTokenFn: async ({ token, refreshToken, userId }) => {
+    const res = await fetch('/api/auth/refresh', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token, refreshToken, userId })
+    });
+    const data = await res.json();
     return {
-      showChat: false,
-      chatConfig: {
-        apiBaseUrl: '/api/ai',
-        authToken: '',
-        title: 'AI 助手',
-        welcomeMessage: '你好！我是AI助手，有什么可以帮助您的吗？'
-      }
+      token: data.accessToken,
+      expiresAt: data.expiresAt * 1000
     };
-  },
-  mounted() {
-    // 注册Vue插件
-    installVuePlugin(this.$root.constructor); // Vue 2
-    // 或在 main.js 中全局注册：
-    // import { installVuePlugin } from 'ibc-ai-web-sdk';
-    // Vue.use(installVuePlugin);
-  },
-  methods: {
-    openChat() {
-      this.showChat = true;
-    },
-    onMessageSend(message) {
-      console.log('用户发送:', message.content);
-    },
-    onMessageReceived(message) {
-      console.log('AI回复:', message.content);
-    }
   }
-};
-</script>
+});
 ```
-#### 组合式API（Composition API）+ 直接使用Web Component
-```vue
-<template>
-  <div>
-    <button @click="handleOpen">打开AI助手</button>
-  </div>
-</template>
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `token` | string | 认证 Token |
+| `tokenExpiresAt` | number | Token 过期时间戳（毫秒） |
+| `refreshToken` | string | refresh token |
+| `refreshTokenFn` | function | 刷新函数，返回新 token 信息 |
+| `onTokenRefreshed` | function | 刷新成功回调 |
+| `onTokenExpired` | function | 刷新失败回调 |
+```
-<script setup>
-import { ref, onMounted, onUnmounted } from 'vue';
-import { createAIChatDialog } from 'ibc-ai-web-sdk';
+### 高级配置
-const chatRef = ref(null);
+```js
+createAIChatDialog({
+  // 各端点自定义
+  streamEndpoint: '/v1/app/completion/stream',
+  stopEndpoint: '/v1/app/completion/stop',
+  conversationQueryEndpoint: '/v1/app/conversation/query',
+  conversationDeleteEndpoint: '/v1/app/conversation/delete',
+  // 鉴权函数（可选）
+  authFn: async (token, userId) => {
+    // throw 或 reject 表示拒绝访问
+  },
-onMounted(() => {
-  chatRef.value = createAIChatDialog({
-    apiBaseUrl: 'https://api.example.com/ai',
-    title: '智能助手',
-    theme: 'dark',
-    width: 500,
-    height: 650,
-    // 回调事件
-    onMessageSend: (msg) => console.log('发送:', msg),
-    onMessageReceived: (msg) => console.log('收到:', msg),
-    onError: (err) => console.error('错误:', err)
-  });
-});
+  // 页脚信息
+  footerIdentity: 'UIN:123456',
+  footerDisclaimer: '推荐和回答由 AI 生成，仅供参考',
-const handleOpen = () => {
-  chatRef.value?.open();
-};
+  // 历史
+  historyDays: 30,
+  historyPageSize: 20,
-onUnmounted(() => {
-  chatRef.value?.destroy();
+  // 移动端
+  mobileMode: true  // undefined = 自动检测
 });
-</script>
 ```
-### 方式三：React项目使用
-#### 使用Hook（推荐）
-```jsx
-import React from 'react';
-import { useAIChat } from 'ibc-ai-web-sdk';
+---
-function App() {
-  const { open, close, messages, isLoading } = useAIChat({
-    apiBaseUrl: process.env.REACT_APP_AI_API_URL,
-    authToken: localStorage.getItem('token'),
-    title: 'AI 智能助手',
-    placeholder: '输入您的问题...',
-    theme: 'light',
-    // 回调
-    onMessageSend: (message) => {
-      console.log('用户发送:', message);
-    },
-    onMessageReceived: ({ content }) => {
-      console.log('AI回复:', content);
-    },
-    onError: (error) => {
-      console.error('发生错误:', error);
-    }
-  });
+## 实例方法
-  return (
-    <div className="app">
-      <h1>My App</h1>
-      <button onClick={open}>
-        {isLoading ? '对话中...' : '打开AI助手'}
-      </button>
-      {/* 显示消息历史 */}
-      <div className="message-history">
-        {messages.map((msg) => (
-          <div key={msg.id} className={`message ${msg.role}`}>
-            <strong>{msg.role === 'user' ? '我' : 'AI'}:</strong>
-            {msg.content}
-          </div>
-        ))}
-      </div>
-      <button onClick={close}>关闭</button>
-    </div>
-  );
-}
+```js
+const dialog = createAIChatDialog(config);
-export default App;
+dialog.open();           // 打开对话框
+dialog.close();          // 关闭对话框
+dialog.toggle();         // 切换显示/隐藏
+dialog.destroy();        // 销毁实例
+dialog.updateConfig({    // 动态更新配置
+  title: '新标题',
+  token: 'new-token'
+});
+dialog.clearChat();      // 清空对话，开始新会话
+dialog.stopGeneration(); // 停止当前 AI 生成
 ```
-#### 类组件方式
+---
-```jsx
-import React, { Component } from 'react';
-import { createAIChatDialog } from 'ibc-ai-web-sdk';
+## 事件与回调
-class ChatButton extends Component {
-  constructor(props) {
-    super(props);
-    this.chatRef = null;
-  }
-  componentDidMount() {
-    this.chatRef = createAIChatDialog({
-      apiBaseUrl: '/api/ai',
-      title: 'AI 助手',
-      onMessageSend: (msg) => {
-        console.log('发送:', msg);
-      },
-      onMessageReceived: (data) => {
-        console.log('收到:', data);
-        this.props.onReceive?.(data);
-      }
-    });
-  }
-  componentWillUnmount() {
-    if (this.chatRef) {
-      this.chatRef.destroy();
-    }
-  }
+支持两种方式监听，效果一样：
-  handleClick = () => {
-    if (this.chatRef) {
-      this.chatRef.open();
-    }
-  };
-  render() {
-    return (
-      <button onClick={this.handleClick}>
-        打开AI助手
-      </button>
-    );
-  }
-}
+**方式一：回调函数**
+```js
+createAIChatDialog({
+  onOpen: () => console.log('对话框打开'),
+  onClose: () => console.log('对话框关闭'),
+  onLoad: (client) => console.log('SDK 初始化完成'),
+  onMessageSend: (msg) => console.log('用户发送:', msg),
+  onMessageReceived: (data) => console.log('AI 回复:', data),
+  onError: (err) => console.error('错误:', err)
+});
+```
-export default ChatButton;
+**方式二：事件监听**
+```js
+dialog.addEventListener('open', () => {});
+dialog.addEventListener('close', () => {});
+dialog.addEventListener('init', (e) => { console.log(e.detail.config); });
+dialog.addEventListener('message-send', (e) => { console.log(e.detail); });
+dialog.addEventListener('message-received', (e) => { console.log(e.detail); });
+dialog.addEventListener('error', (e) => { console.error(e.detail); });
+dialog.addEventListener('clear', () => {});
+dialog.addEventListener('stop', () => {});
+dialog.addEventListener('loading-change', (e) => { console.log(e.detail.loading); });
 ```
-### 方式四：Angular项目使用
+---
-```typescript
-// ai-chat.service.ts
-import { Injectable, OnDestroy } from '@angular/core';
-import { createAIChatDialog, AIChatDialog } from 'ibc-ai-web-sdk';
+## 主题定制
-@Injectable({
-  providedIn: 'root'
-})
-export class AiChatService implements OnDestroy {
-  private dialog: AIChatDialog | null = null;
+### 预设主题（16 种）
-  constructor() {}
+直接传字符串名（不区分大小写）：
-  init(config?: any): void {
-    if (!this.dialog) {
-      this.dialog = createAIChatDialog({
-        apiBaseUrl: environment.aiApiUrl,
-        ...config
-      });
-    }
-  }
+```js
+createAIChatDialog({ theme: 'dark' });
+createAIChatDialog({ theme: 'ocean' });
+createAIChatDialog({ theme: 'purple' });
+```
-  open(): void {
-    this.init(); // 确保已初始化
-    this.dialog?.open();
-  }
+全部预设：`default` `dark` `fresh` `vibrant` `romantic` `purple` `ocean` `twilight` `mint` `rose` `aurora` `lavender` `coral` `jade` `starsky` `sunset`
-  close(): void {
-    this.dialog?.close();
-  }
+### 自定义主题
-  sendMessage(content: string): void {
-    if (this.dialog) {
-      // 通过DOM操作设置消息并发送
-      const textarea = this.dialog.shadowRoot?.querySelector('.ai-textarea');
-      if (textarea) {
-        // 使用内部方法发送
-        (this.dialog as any).addMessage({ role: 'user', content });
-      }
+```js
+createAIChatDialog({
+  theme: {
+    colors: {
+      primary: '#8b5cf6',
+      primaryLight: '#a78bfa',
+      primaryDark: '#7c3aed',
+      background: '#faf5ff',
+      text: '#1f2937',
+      textSecondary: '#6b7280',
+      userBubble: '#8b5cf6',
+      aiBubble: '#f3f4f6',
+      border: '#e5e7eb',
+      inputBackground: '#f9fafb',
+      inputBorder: '#d1d5db',
+      error: '#ef4444',
+      success: '#22c55e',
+      warning: '#f59e0b'
+    },
+    borderRadius: {
+      dialog: '16px',
+      bubble: '12px',
+      button: '50%',
+      input: '28px'
+    },
+    fontSize: {
+      title: '15px',
+      welcomeText: '17px',
+      message: '14px',
+      time: '11px'
     }
   }
-  ngOnDestroy(): void {
-    this.dialog?.destroy();
-  }
-}
+});
 ```
-```typescript
-// app.component.ts
-import { Component } from '@angular/core';
-import { AiChatService } from './ai-chat.service';
-@Component({
-  selector: 'app-root',
-  template: `
-    <button (click)="openChat()">打开AI助手</button>
-  `
-})
-export class AppComponent {
-  constructor(private aiChat: AiChatService) {}
-  openChat(): void {
-    this.aiChat.open();
-  }
-}
-```
+---
-### 方式五：Svelte使用
+## 框架集成示例
-```svelte
-<script>
-  import { onMount, onDestroy } from 'svelte';
-  import { createAIChatDialog } from 'ibc-ai-web-sdk';
-  let chat;
-  onMount(() => {
-    chat = createAIChatDialog({
-      apiBaseUrl: '/api/ai',
-      title: 'Svelte AI Chat',
-      onMessageSend: (msg) => {
-        console.log('发送:', msg);
-      },
-      onMessageReceived: (data) => {
-        console.log('收到:', data);
-      }
-    });
-  });
+### Vue 3 (Composition API)
+```vue
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue';
+import { createAIChatDialog } from 'ibc-ai-web-sdk';
+const chat = ref(null);
-  onDestroy(() => {
-    chat?.destroy();
+onMounted(() => {
+  chat.value = createAIChatDialog({
+    apiEndpoint: '/v1/app/completion',
+    appId: 'your-app-id',
+    userId: 'user-123',
+    bizType: 'chat',
+    token: 'your-token',
+    theme: 'ocean',
+    onMessageSend: (msg) => console.log('发送:', msg),
+    onMessageReceived: (data) => console.log('收到:', data),
+    onError: (err) => console.error('错误:', err)
   });
+});
+onUnmounted(() => chat.value?.destroy());
 </script>
-<button on:click={() => chat?.open()}>
-  打开AI助手
-</button>
+<template>
+  <button @click="chat?.open()">打开 AI 助手</button>
+</template>
 ```
-## ⚙️ 配置选项
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `apiBaseUrl` | `string` | `'/api/ai'` | API基础URL |
-| `authToken` | `string` | `''` | 认证Token |
-| `defaultParams` | `Object` | `{}` | 默认请求参数 |
-| `placeholder` | `string` | `'请输入您的问题...'` | 输入框占位符 |
-| `title` | `string` | `'AI 智能助手'` | 对话框标题 |
-| `width` | `number` | `420` | 对话框宽度(px) |
-| `height` | `number` | `600` | 对话框高度(px) |
-| `theme` | `string` | `'light'` | 主题：`light` / `dark` |
-| `showDragHandle` | `boolean` | `true` | 是否允许拖拽头部移动位置 |
-| `enableHistory` | `boolean` | `true` | 是否启用消息历史记录 |
-| `maxHistoryLength` | `number` | `50` | 最大历史消息数量 |
-| `welcomeMessage` | `string` | - | 欢迎语（空状态时显示） |
-| `errorMessage` | `string` | - | 错误提示文案 |
-| `networkErrorMessage` | `string` | - | 网络错误提示文案 |
-| `emptyMessageError` | `string` | - | 空消息错误提示文案 |
-| `streamingEnabled` | `boolean` | `true` | 是否启用流式响应(SSE) |
-| `requestTimeout` | `number` | `30000` | 请求超时时间(ms) |
-| `customStyles` | `Object` | `null` | 自定义CSS变量 |
-### 回调函数
-| 回调 | 参数 | 说明 |
-|------|------|------|
-| `onMessageSend` | `(message: Object)` | 用户发送消息时触发 |
-| `onMessageReceived` | `(data: {content, done})` | 收到AI回复时触发（流式模式下多次触发） |
-| `onError` | `(error: Error)` | 发生错误时触发 |
-| `onOpen` | - | 对话框打开时触发 |
-| `onClose` | - | 对话框关闭时触发 |
-## 🎨 主题定制
+### React
-### CSS变量覆盖
+```jsx
+import { useEffect, useRef } from 'react';
+import { createAIChatDialog } from 'ibc-ai-web-sdk';
-```javascript
-createAIChatDialog({
-  customStyles: {
-    'primary-color': '#8b5cf6',       // 主色调改为紫色
-    'primary-hover': '#7c3aed',       // 主色悬停态
-    'bg-color': '#faf5ff',            // 背景色
-    'text-color': '#1f2937',          // 文字颜色
-    'border-radius': '16px'           // 圆角大小
-  }
-});
-```
+function App() {
+  const chatRef = useRef(null);
+  useEffect(() => {
+    chatRef.current = createAIChatDialog({
+      apiEndpoint: '/v1/app/completion',
+      appId: 'your-app-id',
+      userId: 'user-123',
+      bizType: 'chat',
+      token: 'your-token',
+      onMessageReceived: (data) => console.log('回复:', data)
+    });
+    return () => chatRef.current?.destroy();
+  }, []);
-### 完整CSS变量列表
-```css
-:host {
-  --ai-primary-color: #2563eb;         /* 主色调 */
-  --ai-primary-hover: #1d4ed8;         /* 主色悬停态 */
-  --ai-bg-color: #ffffff;              /* 背景色 */
-  --ai-text-color: #1f2937;            /* 文字颜色 */
-  --ai-text-secondary: #6b7280;        /* 次要文字颜色 */
-  --ai-border-color: #e5e7eb;          /* 边框颜色 */
-  --ai-user-bg: gradient(...);         /* 用户消息背景 */
-  --ai-assistant-bg: #f3f4f6;          /* 助手消息背景 */
-  --ai-input-bg: #f9fafb;              /* 输入框背景 */
-  --ai-shadow: shadow(...);             /* 阴影效果 */
-  --ai-overlay: rgba(0,0,0,0.5);       /* 遮罩层颜色 */
-  --ai-border-radius: 12px;            /* 圆角大小 */
-  --ai-header-height: 56px;            /* 头部高度 */
+  return <button onClick={() => chatRef.current?.open()}>打开 AI 助手</button>;
 }
 ```
-## 📡 API方法
+### 原生 HTML
-```typescript
-// 创建实例
-const dialog = createAIChatDialog(config);
-// 控制显示
-dialog.open();                    // 打开对话框
-dialog.close();                   // 关闭对话框
-dialog.toggle(forceState?);       // 切换状态
-// 消息操作
-dialog.addMessage(message);       // 手动添加消息
-dialog.clearMessages();           // 清空消息历史
-dialog.sendMessage(text);         // 发送消息（程序化调用）
+```html
+<button onclick="openChat()">打开 AI 助手</button>
-// 状态控制
-dialog.setLoading(boolean);       // 设置加载状态
-dialog.updateConfig(newConfig);   // 更新配置
+<script src="https://unpkg.com/ibc-ai-web-sdk@2/dist/index.umd.min.js"></script>
+<script>
+  const dialog = AIWebSDK.create({
+    apiEndpoint: '/v1/app/completion',
+    appId: 'your-app-id',
+    userId: 'user-123',
+    bizType: 'chat',
+    token: 'your-token'
+  });
-// 生命周期
-dialog.destroy();                 // 销毁实例并清理DOM
+  function openChat() {
+    dialog.open();
+  }
+</script>
 ```
-## 🎯 事件监听
-```javascript
-const dialog = createAIChatDialog();
-// 使用addEventListener
-dialog.addEventListener('open', () => console.log('打开'));
-dialog.addEventListener('close', () => console.log('关闭'));
-dialog.addEventListener('message-send', (e) => {
-  console.log('发送的消息:', e.detail);
-});
-dialog.addEventListener('message-received', (e) => {
-  console.log('收到的回复:', e.detail);
-});
-dialog.addEventListener('error', (e) => {
-  console.error('错误:', e.detail);
-});
-// 或在配置中使用回调
-createAIChatDialog({
-  onOpen: () => {},
-  onClose: () => {},
-  onMessageSend: (msg) => {},
-  onMessageReceived: (data) => {},
-  onError: (err) => {}
-});
-```
+---
-## 🔌 服务端API要求
+## 服务端 API 规范
-SDK默认期望以下API接口：
+SDK 向后端发起以下请求，你需要实现对应的接口：
-### POST `/api/ai/chat`
+### 对话接口 `POST {apiEndpoint}`（默认 `/v1/app/completion`）
 **请求体：**
 ```json
 {
-  "message": "你好",
-  "history": [
-    { "role": "user", "content": "上一条问题" },
-    { "role": "assistant", "content": "上一条回答" }
-  ]
+  "appId": "your-app-id",
+  "prompt": "用户输入的消息",
+  "userId": "user-123",
+  "bizType": "chat",
+  "requestId": "req_1719000000000_abc123"
 }
 ```
-**普通响应：**
+携带 `conversationId` 时会继续已有会话：
 ```json
 {
-  "content": "您好！我是AI助手...",
-  "id": "msg_xxx"
+  "appId": "your-app-id",
+  "prompt": "继续聊天",
+  "userId": "user-123",
+  "bizType": "chat",
+  "requestId": "req_1719000000001_def456",
+  "conversationId": "conv_xxx"
 }
 ```
-**流式响应 (SSE)：**
-```
-data: {"content": "您好"}
-data: {"content": "！"}
-data: {"delta": "我是"}
-...
-data: [DONE]
+**普通响应（非流式）：**
+```json
+{
+  "success": true,
+  "code": 200,
+  "message": "",
+  "data": {
+    "content": "AI 的回复内容",
+    "conversationId": "conv_xxx"
+  }
+}
 ```
-**认证：**
-- Header: `Authorization: Bearer <token>`
-- 或通过配置 `authToken` 参数自动添加
+### 流式接口 `POST {streamEndpoint}`（默认 `/v1/app/completion/stream`）
-## 🏗️ 构建与开发
+请求体同上，响应为 SSE（Server-Sent Events）格式：
-```bash
-# 安装依赖
-npm install
+```
+event: [START]
-# 开发模式（监听文件变化）
-npm run dev
+event: message
+data: 您好
-# 构建
-npm run build
+event: message
+data: ，有什么可以帮您的？
-# 生产构建（压缩+去除调试代码）
-npm run build:prod
+event: [DONE]
+data: {"conversationId":"conv_xxx","tokens":{"input":10,"output":15}}
+```
-# 代码检查
-npm run lint
+**支持的 SSE 事件类型：**
-# 测试
-npm test
-```
+| event | 说明 |
+|-------|------|
+| `[START]` | 流式开始 |
+| `message` | 文本增量 |
+| `[THINKING]` | 思考/推理过程 |
+| `[TOOL_START]` / `[TOOL_RESULT]` / `[TOOL_END]` | 工具调用 |
+| `NODE_START` / `NODE_PROGRESS` / `NODE_COMPLETE` | 工作流节点 |
+| `[HITL]` | 人机交互中断 |
+| `[ERROR]` | 错误 |
+| `[DONE]` | 流式结束 |
-## 📦 输出格式
+### 应用详情 `GET /v1/app/{appId}`
-构建后会生成以下文件：
+初始化时自动调用，返回应用名称、欢迎语、建议问题：
-| 文件 | 格式 | 用途 |
-|------|------|------|
-| `dist/index.esm.js` | ES Module | modern打包工具(Vite/Webpack/Rollup) |
-| `dist/index.cjs.js` | CommonJS | Node.js/老版本打包工具 |
-| `dist/index.umd.js` | UMD | 浏览器直接引用(未压缩) |
-| `dist/index.umd.min.js` | UMD Minified | 浏览器直接引用(生产环境) |
+```json
+{
+  "success": true,
+  "code": 200,
+  "data": {
+    "name": "客服助手",
+    "description": "专业客服 AI",
+    "prologue": "你好！我可以帮你解答问题\n- 我要退货\n- 查看订单状态\n- 联系人工客服"
+  }
+}
+```
-## 🔄 从v1.x迁移
+### 其他可选接口
-如果你之前使用的是Vue版本的v1.x：
+| 接口 | 默认路径 | 用途 |
+|------|----------|------|
+| 停止生成 | `POST /v1/app/completion/stop` | 停止当前流式输出 |
+| 会话查询 | `POST /v1/app/conversation/query` | 查询历史会话列表 |
+| 会话删除 | `POST /v1/app/conversation/delete` | 删除指定会话 |
-```javascript
-// v1.x (Vue组件)
-import AIChatDialog from 'ibc-ai-web-sdk';
-// <AIChatDialog :visible.sync="visible" :config="config" />
+### 认证
-// v2.x (纯JS + Web Components)
-import { createAIChatDialog } from 'ibc-ai-web-sdk';
+所有请求自动携带 `Authorization: Bearer {token}`。提供 `refreshTokenFn` 后 Token 过期会自动刷新，无需手动处理。
-const dialog = createAIChatDialog({
-  apiBaseUrl: '/api/ai',
-  // ... 其他配置不变
-});
+---
-dialog.open();
+## 构建与开发
+```bash
+npm install
+npm run dev     # 开发模式（监听文件变化）
+npm run build   # 构建
+npm run lint    # 代码检查
+npm test        # 测试
 ```
-主要变化：
-1. **移除Vue依赖** - 不再需要Vue运行时
-2. **API更简洁** - `createAIChatDialog()` 返回实例对象
-3. **完全隔离** - Shadow DOM确保样式不会污染宿主页面
-4. **更多框架支持** - 原生支持React Hook、Angular Service等
+构建产出 `dist/`：
-## 🤝 贡献
+| 文件 | 格式 | 用途 |
+|------|------|------|
+| `index.esm.js` | ES Module | Vite/Webpack/Rollup |
+| `index.cjs.js` | CommonJS | require() |
+| `index.umd.js` | UMD | 浏览器直接引入（开发版） |
+| `index.umd.min.js` | UMD | 浏览器直接引入（生产版） |
-欢迎提交Issue和Pull Request！
+---
-## 📄 License
+## License
-MIT License
+MIT