ibc-ai-web-sdk 2.0.2 → 2.0.3

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
  1. package/README.md +334 -502
  2. package/dist/index.cjs.js +8 -2
  3. package/dist/index.cjs.js.map +1 -1
  4. package/dist/index.esm.js +8 -2
  5. package/dist/index.esm.js.map +1 -1
  6. package/dist/index.umd.js +8 -2
  7. package/dist/index.umd.js.map +1 -1
  8. package/dist/index.umd.min.js +1 -1
  9. package/package.json +1 -1
package/README.md CHANGED
@@ -1,607 +1,439 @@
1
- # IBC AI Web SDK v2.0
1
+ # IBC AI Web SDK v2
2
2
 
3
- > **纯JavaScript实现的AI对话组件**，支持任意前端框架：Vue、React、Angular、原生HTML等
3
+ > 纯 JavaScript 实现的 AI 智能体对话组件，基于 Web Components，支持任意前端框架。
4
4
 
5
- ## ✨ 特性
5
+ ## 快速开始
6
6
 
7
- - 🚫 **零框架依赖** - 纯JavaScript实现，基于Web Components (Custom Elements + Shadow DOM)
8
- - 🔌 **框架无关** - 可在Vue/React/Angular/Svelte/原生HTML中无缝使用
9
- - 🎨 **主题可定制** - 支持亮色/暗色主题，CSS变量自定义
10
- - 💬 **流式响应** - 支持SSE流式输出，实时显示AI回复
11
- - 📱 **响应式设计** - 适配桌面端和移动端
12
- - ♿ **无障碍访问** - 遵循ARIA规范，支持键盘操作
13
- - 🎯 **轻量级** - Gzip后 < 15KB
14
-
15
- ## 📦 安装
16
-
17
- ```bash
18
- npm install ibc-ai-web-sdk
19
- ```
20
-
21
- 或直接引入CDN：
7
+ ### CDN 引入（最简单）
22
8
 
23
9
  ```html
24
- <script src="https://unpkg.com/ibc-ai-web-sdk@latest/dist/index.umd.min.js"></script>
10
+ <script src="https://unpkg.com/ibc-ai-web-sdk@2/dist/index.umd.min.js"></script>
11
+ <script>
12
+ const dialog = AIWebSDK.create({
13
+ apiEndpoint: '/v1/app/completion',
14
+ appId: 'your-app-id',
15
+ userId: 'user-123',
16
+ bizType: 'chat',
17
+ token: 'your-auth-token'
18
+ });
19
+ dialog.open();
20
+ </script>
25
21
  ```
26
22
 
27
- ## 🚀 快速开始
23
+ ### npm 安装
28
24
 
29
- ### 方式一：原生HTML使用（最简单）
30
-
31
- ```html
32
- <!DOCTYPE html>
33
- <html>
34
- <head>
35
- <title>AI Chat Demo</title>
36
- </head>
37
- <body>
38
- <!-- 触发按钮 -->
39
- <button onclick="openChat()">打开AI助手</button>
40
-
41
- <script type="module">
42
- import { createAIChatDialog } from './node_modules/ibc-ai-web-sdk/dist/index.esm.js';
43
-
44
- // 或CDN方式：
45
- // const dialog = AICreateChatDialog({...});
46
-
47
- let chatInstance;
48
-
49
- function openChat() {
50
- if (!chatInstance) {
51
- chatInstance = createAIChatDialog({
52
- apiBaseUrl: 'https://your-api.com/ai',
53
- authToken: 'your-token',
54
- title: '智能客服',
55
- placeholder: '请输入您的问题...',
56
- theme: 'light'
57
- });
58
- }
59
-
60
- chatInstance.open();
61
- }
62
-
63
- // 暴露到全局供onclick调用
64
- window.openChat = openChat;
65
- </script>
66
- </body>
67
- </html>
25
+ ```bash
26
+ npm install ibc-ai-web-sdk
68
27
  ```
69
28
 
70
- ### 方式二：Vue项目使用
71
-
72
- #### 选项式API（Options API）
73
-
74
- ```vue
75
- <template>
76
- <div>
77
- <button @click="openChat">打开AI助手</button>
78
-
79
- <!-- 使用组件包装器 -->
80
- <AiChatWrapper
81
- :visible.sync="showChat"
82
- :config="chatConfig"
83
- @message-send="onMessageSend"
84
- @message-received="onMessageReceived"
85
- @close="showChat = false"
86
- />
87
- </div>
88
- </template>
29
+ ```js
30
+ import { createAIChatDialog } from 'ibc-ai-web-sdk';
89
31
 
90
- <script>
91
- import { installVuePlugin, AIChatDialog } from 'ibc-ai-web-sdk';
32
+ const dialog = createAIChatDialog({
33
+ apiEndpoint: '/v1/app/completion',
34
+ appId: 'your-app-id',
35
+ userId: 'user-123',
36
+ bizType: 'chat',
37
+ token: 'your-auth-token'
38
+ });
39
+ dialog.open();
40
+ ```
92
41
 
93
- export default {
94
- data() {
42
+ ---
43
+
44
+ ## 配置选项
45
+
46
+ | 参数 | 类型 | 默认值 | 必填 | 说明 |
47
+ |------|------|--------|------|------|
48
+ | `apiEndpoint` | string | `/v1/app/completion` | 是 | 对话接口地址 |
49
+ | `apiBaseUrl` | string | `''` | | API 基础地址，拼接到各 endpoint 前 |
50
+ | `appId` | string | `''` | 是 | 智能体应用 ID |
51
+ | `userId` | string | `''` | 是 | 用户标识 |
52
+ | `bizType` | string | `''` | 是 | 业务类型标识 |
53
+ | `token` | string | `''` | | 认证 Token，自动添加到 Authorization 头 |
54
+ | `title` | string | `'AI 助手'` | | 对话框标题（loadAppDetail 会自动覆盖） |
55
+ | `welcomeText` | string | `'Hi，我是智能助手 ~'` | | 欢迎语 |
56
+ | `welcomeDesc` | string | `'全新自动化能力上线...'` | | 欢迎描述 |
57
+ | `theme` | string\|object | `'default'` | | 主题，见下方[主题定制](#主题定制) |
58
+ | `suggestions` | array | `[]` | | 欢迎页建议列表 `[{ label, value }]`，loadAppDetail 会自动覆盖 |
59
+ | `timeout` | number | `60000` | | 请求超时（毫秒） |
60
+ | `maxLength` | number | `500` | | 输入最大字符数 |
61
+ | `enableDrag` | boolean | `true` | | 是否允许拖拽对话框 |
62
+ | `headers` | object | `{}` | | 附加请求头 |
63
+ | `extendInfo` | object | `{}` | | 随请求发送的扩展信息 |
64
+
65
+ ### Token 刷新
66
+
67
+ 提供 `refreshTokenFn` 即可，SDK 会自动处理过期检测和刷新。
68
+
69
+ ```js
70
+ createAIChatDialog({
71
+ token: 'initial-access-token',
72
+ tokenExpiresAt: Date.now() + 30 * 60 * 1000, // Token 过期时间戳
73
+ refreshToken: 'initial-refresh-token', // 可选
74
+
75
+ refreshTokenFn: async ({ token, refreshToken, userId }) => {
76
+ const res = await fetch('/api/auth/refresh', {
77
+ method: 'POST',
78
+ headers: { 'Content-Type': 'application/json' },
79
+ body: JSON.stringify({ token, refreshToken, userId })
80
+ });
81
+ const data = await res.json();
95
82
  return {
96
- showChat: false,
97
- chatConfig: {
98
- apiBaseUrl: '/api/ai',
99
- authToken: '',
100
- title: 'AI 助手',
101
- welcomeMessage: '你好！我是AI助手，有什么可以帮助您的吗？'
102
- }
83
+ token: data.accessToken,
84
+ expiresAt: data.expiresAt * 1000
103
85
  };
104
- },
105
-
106
- mounted() {
107
- // 注册Vue插件
108
- installVuePlugin(this.$root.constructor); // Vue 2
109
- // 或在 main.js 中全局注册：
110
- // import { installVuePlugin } from 'ibc-ai-web-sdk';
111
- // Vue.use(installVuePlugin);
112
- },
113
-
114
- methods: {
115
- openChat() {
116
- this.showChat = true;
117
- },
118
-
119
- onMessageSend(message) {
120
- console.log('用户发送:', message.content);
121
- },
122
-
123
- onMessageReceived(message) {
124
- console.log('AI回复:', message.content);
125
- }
126
86
  }
127
- };
128
- </script>
87
+ });
129
88
  ```
130
89
 
131
- #### 组合式API（Composition API）+ 直接使用Web Component
90
+ | 参数 | 类型 | 说明 |
91
+ |------|------|------|
92
+ | `token` | string | 认证 Token |
93
+ | `tokenExpiresAt` | number | Token 过期时间戳（毫秒） |
94
+ | `refreshToken` | string | refresh token |
95
+ | `refreshTokenFn` | function | 刷新函数，返回新 token 信息 |
96
+ | `onTokenRefreshed` | function | 刷新成功回调 |
97
+ | `onTokenExpired` | function | 刷新失败回调 |
98
+ ```
132
99
 
133
- ```vue
134
- <template>
135
- <div>
136
- <button @click="handleOpen">打开AI助手</button>
137
- </div>
138
- </template>
100
+ ### 高级配置
139
101
 
140
- <script setup>
141
- import { ref, onMounted, onUnmounted } from 'vue';
142
- import { createAIChatDialog } from 'ibc-ai-web-sdk';
143
-
144
- const chatRef = ref(null);
102
+ ```js
103
+ createAIChatDialog({
104
+ // 各端点自定义
105
+ streamEndpoint: '/v1/app/completion/stream',
106
+ stopEndpoint: '/v1/app/completion/stop',
107
+ conversationQueryEndpoint: '/v1/app/conversation/query',
108
+ conversationDeleteEndpoint: '/v1/app/conversation/delete',
109
+
110
+ // 鉴权函数（可选）
111
+ authFn: async (token, userId) => {
112
+ // throw 或 reject 表示拒绝访问
113
+ },
145
114
 
146
- onMounted(() => {
147
- chatRef.value = createAIChatDialog({
148
- apiBaseUrl: 'https://api.example.com/ai',
149
- title: '智能助手',
150
- theme: 'dark',
151
- width: 500,
152
- height: 650,
153
-
154
- // 回调事件
155
- onMessageSend: (msg) => console.log('发送:', msg),
156
- onMessageReceived: (msg) => console.log('收到:', msg),
157
- onError: (err) => console.error('错误:', err)
158
- });
159
- });
115
+ // 页脚信息
116
+ footerIdentity: 'UIN:123456',
117
+ footerDisclaimer: '推荐和回答由 AI 生成，仅供参考',
160
118
 
161
- const handleOpen = () => {
162
- chatRef.value?.open();
163
- };
119
+ // 历史
120
+ historyDays: 30,
121
+ historyPageSize: 20,
164
122
 
165
- onUnmounted(() => {
166
- chatRef.value?.destroy();
123
+ // 移动端
124
+ mobileMode: true // undefined = 自动检测
167
125
  });
168
- </script>
169
126
  ```
170
127
 
171
- ### 方式三：React项目使用
128
+ ---
172
129
 
173
- #### 使用Hook（推荐）
130
+ ## 实例方法
174
131
 
175
- ```jsx
176
- import React from 'react';
177
- import { useAIChat } from 'ibc-ai-web-sdk';
178
-
179
- function App() {
180
- const { open, close, messages, isLoading } = useAIChat({
181
- apiBaseUrl: process.env.REACT_APP_AI_API_URL,
182
- authToken: localStorage.getItem('token'),
183
- title: 'AI 智能助手',
184
- placeholder: '输入您的问题...',
185
- theme: 'light',
186
-
187
- // 回调
188
- onMessageSend: (message) => {
189
- console.log('用户发送:', message);
190
- },
191
-
192
- onMessageReceived: ({ content }) => {
193
- console.log('AI回复:', content);
194
- },
195
-
196
- onError: (error) => {
197
- console.error('发生错误:', error);
198
- }
199
- });
200
-
201
- return (
202
- <div className="app">
203
- <h1>My App</h1>
204
-
205
- <button onClick={open}>
206
- {isLoading ? '对话中...' : '打开AI助手'}
207
- </button>
208
-
209
- {/* 显示消息历史 */}
210
- <div className="message-history">
211
- {messages.map((msg) => (
212
- <div key={msg.id} className={`message ${msg.role}`}>
213
- <strong>{msg.role === 'user' ? '我' : 'AI'}:</strong>
214
- {msg.content}
215
- </div>
216
- ))}
217
- </div>
218
-
219
- <button onClick={close}>关闭</button>
220
- </div>
221
- );
222
- }
132
+ ```js
133
+ const dialog = createAIChatDialog(config);
223
134
 
224
- export default App;
135
+ dialog.open(); // 打开对话框
136
+ dialog.close(); // 关闭对话框
137
+ dialog.toggle(); // 切换显示/隐藏
138
+ dialog.destroy(); // 销毁实例
139
+ dialog.updateConfig({ // 动态更新配置
140
+ title: '新标题',
141
+ token: 'new-token'
142
+ });
143
+ dialog.clearChat(); // 清空对话，开始新会话
144
+ dialog.stopGeneration(); // 停止当前 AI 生成
225
145
  ```
226
146
 
227
- #### 类组件方式
228
-
229
- ```jsx
230
- import React, { Component } from 'react';
231
- import { createAIChatDialog } from 'ibc-ai-web-sdk';
232
-
233
- class ChatButton extends Component {
234
- constructor(props) {
235
- super(props);
236
- this.chatRef = null;
237
- }
147
+ ---
238
148
 
239
- componentDidMount() {
240
- this.chatRef = createAIChatDialog({
241
- apiBaseUrl: '/api/ai',
242
- title: 'AI 助手',
243
-
244
- onMessageSend: (msg) => {
245
- console.log('发送:', msg);
246
- },
247
-
248
- onMessageReceived: (data) => {
249
- console.log('收到:', data);
250
- this.props.onReceive?.(data);
251
- }
252
- });
253
- }
149
+ ## 事件与回调
254
150
 
255
- componentWillUnmount() {
256
- if (this.chatRef) {
257
- this.chatRef.destroy();
258
- }
259
- }
151
+ 支持两种方式监听，效果一样：
260
152
 
261
- handleClick = () => {
262
- if (this.chatRef) {
263
- this.chatRef.open();
264
- }
265
- };
266
-
267
- render() {
268
- return (
269
- <button onClick={this.handleClick}>
270
- 打开AI助手
271
- </button>
272
- );
273
- }
274
- }
153
+ **方式一：回调函数**
154
+ ```js
155
+ createAIChatDialog({
156
+ onOpen: () => console.log('对话框打开'),
157
+ onClose: () => console.log('对话框关闭'),
158
+ onLoad: (client) => console.log('SDK 初始化完成'),
159
+ onMessageSend: (msg) => console.log('用户发送:', msg),
160
+ onMessageReceived: (data) => console.log('AI 回复:', data),
161
+ onError: (err) => console.error('错误:', err)
162
+ });
163
+ ```
275
164
 
276
- export default ChatButton;
165
+ **方式二：事件监听**
166
+ ```js
167
+ dialog.addEventListener('open', () => {});
168
+ dialog.addEventListener('close', () => {});
169
+ dialog.addEventListener('init', (e) => { console.log(e.detail.config); });
170
+ dialog.addEventListener('message-send', (e) => { console.log(e.detail); });
171
+ dialog.addEventListener('message-received', (e) => { console.log(e.detail); });
172
+ dialog.addEventListener('error', (e) => { console.error(e.detail); });
173
+ dialog.addEventListener('clear', () => {});
174
+ dialog.addEventListener('stop', () => {});
175
+ dialog.addEventListener('loading-change', (e) => { console.log(e.detail.loading); });
277
176
  ```
278
177
 
279
- ### 方式四：Angular项目使用
178
+ ---
280
179
 
281
- ```typescript
282
- // ai-chat.service.ts
283
- import { Injectable, OnDestroy } from '@angular/core';
284
- import { createAIChatDialog, AIChatDialog } from 'ibc-ai-web-sdk';
180
+ ## 主题定制
285
181
 
286
- @Injectable({
287
- providedIn: 'root'
288
- })
289
- export class AiChatService implements OnDestroy {
290
- private dialog: AIChatDialog | null = null;
182
+ ### 预设主题（16 种）
291
183
 
292
- constructor() {}
184
+ 直接传字符串名（不区分大小写）：
293
185
 
294
- init(config?: any): void {
295
- if (!this.dialog) {
296
- this.dialog = createAIChatDialog({
297
- apiBaseUrl: environment.aiApiUrl,
298
- ...config
299
- });
300
- }
301
- }
186
+ ```js
187
+ createAIChatDialog({ theme: 'dark' });
188
+ createAIChatDialog({ theme: 'ocean' });
189
+ createAIChatDialog({ theme: 'purple' });
190
+ ```
302
191
 
303
- open(): void {
304
- this.init(); // 确保已初始化
305
- this.dialog?.open();
306
- }
192
+ 全部预设：`default` `dark` `fresh` `vibrant` `romantic` `purple` `ocean` `twilight` `mint` `rose` `aurora` `lavender` `coral` `jade` `starsky` `sunset`
307
193
 
308
- close(): void {
309
- this.dialog?.close();
310
- }
194
+ ### 自定义主题
311
195
 
312
- sendMessage(content: string): void {
313
- if (this.dialog) {
314
- // 通过DOM操作设置消息并发送
315
- const textarea = this.dialog.shadowRoot?.querySelector('.ai-textarea');
316
- if (textarea) {
317
- // 使用内部方法发送
318
- (this.dialog as any).addMessage({ role: 'user', content });
319
- }
196
+ ```js
197
+ createAIChatDialog({
198
+ theme: {
199
+ colors: {
200
+ primary: '#8b5cf6',
201
+ primaryLight: '#a78bfa',
202
+ primaryDark: '#7c3aed',
203
+ background: '#faf5ff',
204
+ text: '#1f2937',
205
+ textSecondary: '#6b7280',
206
+ userBubble: '#8b5cf6',
207
+ aiBubble: '#f3f4f6',
208
+ border: '#e5e7eb',
209
+ inputBackground: '#f9fafb',
210
+ inputBorder: '#d1d5db',
211
+ error: '#ef4444',
212
+ success: '#22c55e',
213
+ warning: '#f59e0b'
214
+ },
215
+ borderRadius: {
216
+ dialog: '16px',
217
+ bubble: '12px',
218
+ button: '50%',
219
+ input: '28px'
220
+ },
221
+ fontSize: {
222
+ title: '15px',
223
+ welcomeText: '17px',
224
+ message: '14px',
225
+ time: '11px'
320
226
  }
321
227
  }
322
-
323
- ngOnDestroy(): void {
324
- this.dialog?.destroy();
325
- }
326
- }
228
+ });
327
229
  ```
328
230
 
329
- ```typescript
330
- // app.component.ts
331
- import { Component } from '@angular/core';
332
- import { AiChatService } from './ai-chat.service';
333
-
334
- @Component({
335
- selector: 'app-root',
336
- template: `
337
- <button (click)="openChat()">打开AI助手</button>
338
- `
339
- })
340
- export class AppComponent {
341
- constructor(private aiChat: AiChatService) {}
342
-
343
- openChat(): void {
344
- this.aiChat.open();
345
- }
346
- }
347
- ```
231
+ ---
348
232
 
349
- ### 方式五：Svelte使用
233
+ ## 框架集成示例
350
234
 
351
- ```svelte
352
- <script>
353
- import { onMount, onDestroy } from 'svelte';
354
- import { createAIChatDialog } from 'ibc-ai-web-sdk';
355
-
356
- let chat;
357
-
358
- onMount(() => {
359
- chat = createAIChatDialog({
360
- apiBaseUrl: '/api/ai',
361
- title: 'Svelte AI Chat',
362
-
363
- onMessageSend: (msg) => {
364
- console.log('发送:', msg);
365
- },
366
-
367
- onMessageReceived: (data) => {
368
- console.log('收到:', data);
369
- }
370
- });
371
- });
235
+ ### Vue 3 (Composition API)
236
+
237
+ ```vue
238
+ <script setup>
239
+ import { ref, onMounted, onUnmounted } from 'vue';
240
+ import { createAIChatDialog } from 'ibc-ai-web-sdk';
241
+
242
+ const chat = ref(null);
372
243
 
373
- onDestroy(() => {
374
- chat?.destroy();
244
+ onMounted(() => {
245
+ chat.value = createAIChatDialog({
246
+ apiEndpoint: '/v1/app/completion',
247
+ appId: 'your-app-id',
248
+ userId: 'user-123',
249
+ bizType: 'chat',
250
+ token: 'your-token',
251
+ theme: 'ocean',
252
+ onMessageSend: (msg) => console.log('发送:', msg),
253
+ onMessageReceived: (data) => console.log('收到:', data),
254
+ onError: (err) => console.error('错误:', err)
375
255
  });
256
+ });
257
+
258
+ onUnmounted(() => chat.value?.destroy());
376
259
  </script>
377
260
 
378
- <button on:click={() => chat?.open()}>
379
- 打开AI助手
380
- </button>
261
+ <template>
262
+ <button @click="chat?.open()">打开 AI 助手</button>
263
+ </template>
381
264
  ```
382
265
 
383
- ## ⚙️ 配置选项
384
-
385
- | 参数 | 类型 | 默认值 | 说明 |
386
- |------|------|--------|------|
387
- | `apiBaseUrl` | `string` | `'/api/ai'` | API基础URL |
388
- | `authToken` | `string` | `''` | 认证Token |
389
- | `defaultParams` | `Object` | `{}` | 默认请求参数 |
390
- | `placeholder` | `string` | `'请输入您的问题...'` | 输入框占位符 |
391
- | `title` | `string` | `'AI 智能助手'` | 对话框标题 |
392
- | `width` | `number` | `420` | 对话框宽度(px) |
393
- | `height` | `number` | `600` | 对话框高度(px) |
394
- | `theme` | `string` | `'light'` | 主题：`light` / `dark` |
395
- | `showDragHandle` | `boolean` | `true` | 是否允许拖拽头部移动位置 |
396
- | `enableHistory` | `boolean` | `true` | 是否启用消息历史记录 |
397
- | `maxHistoryLength` | `number` | `50` | 最大历史消息数量 |
398
- | `welcomeMessage` | `string` | - | 欢迎语（空状态时显示） |
399
- | `errorMessage` | `string` | - | 错误提示文案 |
400
- | `networkErrorMessage` | `string` | - | 网络错误提示文案 |
401
- | `emptyMessageError` | `string` | - | 空消息错误提示文案 |
402
- | `streamingEnabled` | `boolean` | `true` | 是否启用流式响应(SSE) |
403
- | `requestTimeout` | `number` | `30000` | 请求超时时间(ms) |
404
- | `customStyles` | `Object` | `null` | 自定义CSS变量 |
405
-
406
- ### 回调函数
407
-
408
- | 回调 | 参数 | 说明 |
409
- |------|------|------|
410
- | `onMessageSend` | `(message: Object)` | 用户发送消息时触发 |
411
- | `onMessageReceived` | `(data: {content, done})` | 收到AI回复时触发（流式模式下多次触发） |
412
- | `onError` | `(error: Error)` | 发生错误时触发 |
413
- | `onOpen` | - | 对话框打开时触发 |
414
- | `onClose` | - | 对话框关闭时触发 |
266
+ ### React
415
267
 
416
- ## 🎨 主题定制
417
-
418
- ### CSS变量覆盖
268
+ ```jsx
269
+ import { useEffect, useRef } from 'react';
270
+ import { createAIChatDialog } from 'ibc-ai-web-sdk';
419
271
 
420
- ```javascript
421
- createAIChatDialog({
422
- customStyles: {
423
- 'primary-color': '#8b5cf6', // 主色调改为紫色
424
- 'primary-hover': '#7c3aed', // 主色悬停态
425
- 'bg-color': '#faf5ff', // 背景色
426
- 'text-color': '#1f2937', // 文字颜色
427
- 'border-radius': '16px' // 圆角大小
428
- }
429
- });
430
- ```
272
+ function App() {
273
+ const chatRef = useRef(null);
274
+
275
+ useEffect(() => {
276
+ chatRef.current = createAIChatDialog({
277
+ apiEndpoint: '/v1/app/completion',
278
+ appId: 'your-app-id',
279
+ userId: 'user-123',
280
+ bizType: 'chat',
281
+ token: 'your-token',
282
+ onMessageReceived: (data) => console.log('回复:', data)
283
+ });
284
+ return () => chatRef.current?.destroy();
285
+ }, []);
431
286
 
432
- ### 完整CSS变量列表
433
-
434
- ```css
435
- :host {
436
- --ai-primary-color: #2563eb; /* 主色调 */
437
- --ai-primary-hover: #1d4ed8; /* 主色悬停态 */
438
- --ai-bg-color: #ffffff; /* 背景色 */
439
- --ai-text-color: #1f2937; /* 文字颜色 */
440
- --ai-text-secondary: #6b7280; /* 次要文字颜色 */
441
- --ai-border-color: #e5e7eb; /* 边框颜色 */
442
- --ai-user-bg: gradient(...); /* 用户消息背景 */
443
- --ai-assistant-bg: #f3f4f6; /* 助手消息背景 */
444
- --ai-input-bg: #f9fafb; /* 输入框背景 */
445
- --ai-shadow: shadow(...); /* 阴影效果 */
446
- --ai-overlay: rgba(0,0,0,0.5); /* 遮罩层颜色 */
447
- --ai-border-radius: 12px; /* 圆角大小 */
448
- --ai-header-height: 56px; /* 头部高度 */
287
+ return <button onClick={() => chatRef.current?.open()}>打开 AI 助手</button>;
449
288
  }
450
289
  ```
451
290
 
452
- ## 📡 API方法
453
-
454
- ```typescript
455
- // 创建实例
456
- const dialog = createAIChatDialog(config);
457
-
458
- // 控制显示
459
- dialog.open(); // 打开对话框
460
- dialog.close(); // 关闭对话框
461
- dialog.toggle(forceState?); // 切换状态
291
+ ### 原生 HTML
462
292
 
463
- // 消息操作
464
- dialog.addMessage(message); // 手动添加消息
465
- dialog.clearMessages(); // 清空消息历史
466
- dialog.sendMessage(text); // 发送消息（程序化调用）
293
+ ```html
294
+ <button onclick="openChat()">打开 AI 助手</button>
467
295
 
468
- // 状态控制
469
- dialog.setLoading(boolean); // 设置加载状态
470
- dialog.updateConfig(newConfig); // 更新配置
296
+ <script src="https://unpkg.com/ibc-ai-web-sdk@2/dist/index.umd.min.js"></script>
297
+ <script>
298
+ const dialog = AIWebSDK.create({
299
+ apiEndpoint: '/v1/app/completion',
300
+ appId: 'your-app-id',
301
+ userId: 'user-123',
302
+ bizType: 'chat',
303
+ token: 'your-token'
304
+ });
471
305
 
472
- // 生命周期
473
- dialog.destroy(); // 销毁实例并清理DOM
306
+ function openChat() {
307
+ dialog.open();
308
+ }
309
+ </script>
474
310
  ```
475
311
 
476
- ## 🎯 事件监听
477
-
478
- ```javascript
479
- const dialog = createAIChatDialog();
480
-
481
- // 使用addEventListener
482
- dialog.addEventListener('open', () => console.log('打开'));
483
- dialog.addEventListener('close', () => console.log('关闭'));
484
- dialog.addEventListener('message-send', (e) => {
485
- console.log('发送的消息:', e.detail);
486
- });
487
- dialog.addEventListener('message-received', (e) => {
488
- console.log('收到的回复:', e.detail);
489
- });
490
- dialog.addEventListener('error', (e) => {
491
- console.error('错误:', e.detail);
492
- });
493
-
494
- // 或在配置中使用回调
495
- createAIChatDialog({
496
- onOpen: () => {},
497
- onClose: () => {},
498
- onMessageSend: (msg) => {},
499
- onMessageReceived: (data) => {},
500
- onError: (err) => {}
501
- });
502
- ```
312
+ ---
503
313
 
504
- ## 🔌 服务端API要求
314
+ ## 服务端 API 规范
505
315
 
506
- SDK默认期望以下API接口：
316
+ SDK 向后端发起以下请求，你需要实现对应的接口：
507
317
 
508
- ### POST `/api/ai/chat`
318
+ ### 对话接口 `POST {apiEndpoint}`（默认 `/v1/app/completion`）
509
319
 
510
320
  **请求体：**
511
321
  ```json
512
322
  {
513
- "message": "你好",
514
- "history": [
515
- { "role": "user", "content": "上一条问题" },
516
- { "role": "assistant", "content": "上一条回答" }
517
- ]
323
+ "appId": "your-app-id",
324
+ "prompt": "用户输入的消息",
325
+ "userId": "user-123",
326
+ "bizType": "chat",
327
+ "requestId": "req_1719000000000_abc123"
518
328
  }
519
329
  ```
520
330
 
521
- **普通响应：**
331
+ 携带 `conversationId` 时会继续已有会话：
522
332
  ```json
523
333
  {
524
- "content": "您好！我是AI助手...",
525
- "id": "msg_xxx"
334
+ "appId": "your-app-id",
335
+ "prompt": "继续聊天",
336
+ "userId": "user-123",
337
+ "bizType": "chat",
338
+ "requestId": "req_1719000000001_def456",
339
+ "conversationId": "conv_xxx"
526
340
  }
527
341
  ```
528
342
 
529
- **流式响应 (SSE)：**
530
- ```
531
- data: {"content": "您好"}
532
- data: {"content": "！"}
533
- data: {"delta": "我是"}
534
- ...
535
- data: [DONE]
343
+ **普通响应（非流式）：**
344
+ ```json
345
+ {
346
+ "success": true,
347
+ "code": 200,
348
+ "message": "",
349
+ "data": {
350
+ "content": "AI 的回复内容",
351
+ "conversationId": "conv_xxx"
352
+ }
353
+ }
536
354
  ```
537
355
 
538
- **认证：**
539
- - Header: `Authorization: Bearer <token>`
540
- - 或通过配置 `authToken` 参数自动添加
356
+ ### 流式接口 `POST {streamEndpoint}`（默认 `/v1/app/completion/stream`）
541
357
 
542
- ## 🏗️ 构建与开发
358
+ 请求体同上，响应为 SSE（Server-Sent Events）格式：
543
359
 
544
- ```bash
545
- # 安装依赖
546
- npm install
360
+ ```
361
+ event: [START]
547
362
 
548
- # 开发模式（监听文件变化）
549
- npm run dev
363
+ event: message
364
+ data: 您好
550
365
 
551
- # 构建
552
- npm run build
366
+ event: message
367
+ data: ，有什么可以帮您的？
553
368
 
554
- # 生产构建（压缩+去除调试代码）
555
- npm run build:prod
369
+ event: [DONE]
370
+ data: {"conversationId":"conv_xxx","tokens":{"input":10,"output":15}}
371
+ ```
556
372
 
557
- # 代码检查
558
- npm run lint
373
+ **支持的 SSE 事件类型：**
559
374
 
560
- # 测试
561
- npm test
562
- ```
375
+ | event | 说明 |
376
+ |-------|------|
377
+ | `[START]` | 流式开始 |
378
+ | `message` | 文本增量 |
379
+ | `[THINKING]` | 思考/推理过程 |
380
+ | `[TOOL_START]` / `[TOOL_RESULT]` / `[TOOL_END]` | 工具调用 |
381
+ | `NODE_START` / `NODE_PROGRESS` / `NODE_COMPLETE` | 工作流节点 |
382
+ | `[HITL]` | 人机交互中断 |
383
+ | `[ERROR]` | 错误 |
384
+ | `[DONE]` | 流式结束 |
563
385
 
564
- ## 📦 输出格式
386
+ ### 应用详情 `GET /v1/app/{appId}`
565
387
 
566
- 构建后会生成以下文件：
388
+ 初始化时自动调用，返回应用名称、欢迎语、建议问题：
567
389
 
568
- | 文件 | 格式 | 用途 |
569
- |------|------|------|
570
- | `dist/index.esm.js` | ES Module | modern打包工具(Vite/Webpack/Rollup) |
571
- | `dist/index.cjs.js` | CommonJS | Node.js/老版本打包工具 |
572
- | `dist/index.umd.js` | UMD | 浏览器直接引用(未压缩) |
573
- | `dist/index.umd.min.js` | UMD Minified | 浏览器直接引用(生产环境) |
390
+ ```json
391
+ {
392
+ "success": true,
393
+ "code": 200,
394
+ "data": {
395
+ "name": "客服助手",
396
+ "description": "专业客服 AI",
397
+ "prologue": "你好！我可以帮你解答问题\n- 我要退货\n- 查看订单状态\n- 联系人工客服"
398
+ }
399
+ }
400
+ ```
574
401
 
575
- ## 🔄 从v1.x迁移
402
+ ### 其他可选接口
576
403
 
577
- 如果你之前使用的是Vue版本的v1.x：
404
+ | 接口 | 默认路径 | 用途 |
405
+ |------|----------|------|
406
+ | 停止生成 | `POST /v1/app/completion/stop` | 停止当前流式输出 |
407
+ | 会话查询 | `POST /v1/app/conversation/query` | 查询历史会话列表 |
408
+ | 会话删除 | `POST /v1/app/conversation/delete` | 删除指定会话 |
578
409
 
579
- ```javascript
580
- // v1.x (Vue组件)
581
- import AIChatDialog from 'ibc-ai-web-sdk';
582
- // <AIChatDialog :visible.sync="visible" :config="config" />
410
+ ### 认证
583
411
 
584
- // v2.x (纯JS + Web Components)
585
- import { createAIChatDialog } from 'ibc-ai-web-sdk';
412
+ 所有请求自动携带 `Authorization: Bearer {token}`。提供 `refreshTokenFn` 后 Token 过期会自动刷新，无需手动处理。
586
413
 
587
- const dialog = createAIChatDialog({
588
- apiBaseUrl: '/api/ai',
589
- // ... 其他配置不变
590
- });
414
+ ---
591
415
 
592
- dialog.open();
416
+ ## 构建与开发
417
+
418
+ ```bash
419
+ npm install
420
+ npm run dev # 开发模式（监听文件变化）
421
+ npm run build # 构建
422
+ npm run lint # 代码检查
423
+ npm test # 测试
593
424
  ```
594
425
 
595
- 主要变化：
596
- 1. **移除Vue依赖** - 不再需要Vue运行时
597
- 2. **API更简洁** - `createAIChatDialog()` 返回实例对象
598
- 3. **完全隔离** - Shadow DOM确保样式不会污染宿主页面
599
- 4. **更多框架支持** - 原生支持React Hook、Angular Service等
426
+ 构建产出 `dist/`：
600
427
 
601
- ## 🤝 贡献
428
+ | 文件 | 格式 | 用途 |
429
+ |------|------|------|
430
+ | `index.esm.js` | ES Module | Vite/Webpack/Rollup |
431
+ | `index.cjs.js` | CommonJS | require() |
432
+ | `index.umd.js` | UMD | 浏览器直接引入（开发版） |
433
+ | `index.umd.min.js` | UMD | 浏览器直接引入（生产版） |
602
434
 
603
- 欢迎提交Issue和Pull Request！
435
+ ---
604
436
 
605
- ## 📄 License
437
+ ## License
606
438
 
607
- MIT License
439
+ MIT