langchat-widget 1.0.0

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 +222 -0
  2. package/dist/favicon.ico +0 -0
  3. package/dist/index.d.ts +635 -0
  4. package/dist/langchat-widget.css +1 -0
  5. package/dist/langchat-widget.es.js +23422 -0
  6. package/dist/langchat-widget.es.js.map +1 -0
  7. package/dist/langchat-widget.umd.js +51 -0
  8. package/dist/langchat-widget.umd.js.map +1 -0
  9. package/package.json +81 -0
package/README.md ADDED
@@ -0,0 +1,222 @@
1
+ ## LangChat Widget 文档（Mintlify 风格）
2
+
3
+ 欢迎使用 LangChat Widget —— 一个即插即用的 Web 聊天组件，基于 Vue 3 + TypeScript 构建，支持以 NPM 包形式集成到 Vue 工程，也支持在纯 HTML 页面通过 UMD 方式直接引入使用。
4
+
5
+ ### 安装
6
+
7
+ ```bash
8
+ pnpm add @langchat-widget
9
+ # 或者
10
+ npm install @langchat-widget
11
+ ```
12
+
13
+ <Tip>
14
+ 建议在现代项目中优先使用 ESM 安装与引入（如 Vite、Nuxt、Vue CLI 新版本）。
15
+ </Tip>
16
+
17
+ ### 快速开始（Vue 工程）
18
+
19
+ 以下示例展示在 Vue 3 项目中如何初始化和使用组件。建议在业务初始化逻辑中创建实例。
20
+
21
+ ```ts
22
+ // main.ts 或任意业务入口文件
23
+ import { LangChatBot } from '@langchat-widget';
24
+ import '@langchat-widget/dist/langchat-widget.css';
25
+
26
+ const widget = new LangChatBot({
27
+ apiKey: 'YOUR_API_KEY',
28
+ baseUrl: 'https://api.siliconflow.cn/v1',
29
+ modelName: 'Qwen/Qwen2.5-72B-Instruct',
30
+ header: { title: 'LangChat' },
31
+ autoOpen: false,
32
+ position: 'bottom-right',
33
+ enableStreaming: true,
34
+ enableHistory: true,
35
+ });
36
+
37
+ // 可选：监听事件
38
+ widget.on('open', () => console.log('widget opened'));
39
+ widget.on('close', () => console.log('widget closed'));
40
+ ```
41
+
42
+ 在需要时可以通过以下方法控制：
43
+
44
+ ```ts
45
+ widget.open();
46
+ widget.close();
47
+ widget.toggle();
48
+ widget.updateConfig({ theme: { mode: 'dark' } });
49
+ ```
50
+
51
+ <Warning>
52
+ 请勿在生产环境将真实 `apiKey` 暴露在浏览器源码中。推荐通过服务端代理或安全的 KV/Edge Config 注入方式下发临时令牌。
53
+ </Warning>
54
+
55
+ ### 纯 HTML 使用（UMD）
56
+
57
+ 无需构建工具，直接在 HTML 中引入 UMD 与 CSS 文件并创建实例。
58
+
59
+ ```html
60
+ <!doctype html>
61
+ <html>
62
+ <head>
63
+ <meta charset="utf-8" />
64
+ <meta name="viewport" content="width=device-width,initial-scale=1" />
65
+ <!-- 引入样式 -->
66
+ <link rel="stylesheet" href="./dist/langchat-widget.css" />
67
+ </head>
68
+ <body>
69
+ <!-- 容器可选；若不提供将自动创建并挂载到 body -->
70
+ <div id="langchat-widget-container"></div>
71
+
72
+ <!-- 引入 UMD 文件 -->
73
+ <script src="./dist/langchat-widget.umd.js"></script>
74
+ <script>
75
+ // UMD 导出对象为 LangChatWidget，主类为 LangChatBot
76
+ const { LangChatBot } = window.LangChatWidget;
77
+
78
+ const widget = new LangChatBot({
79
+ apiKey: 'YOUR_API_KEY',
80
+ baseUrl: 'https://api.siliconflow.cn/v1',
81
+ modelName: 'Qwen/Qwen2.5-72B-Instruct',
82
+ header: { title: 'LangChat Widget' },
83
+ position: 'bottom-right',
84
+ enableStreaming: true,
85
+ });
86
+
87
+ widget.on('open', () => console.log('opened'));
88
+ </script>
89
+ </body>
90
+ </html>
91
+ ```
92
+
93
+ 项目内已提供演示文件：`apps/widget/examples/basic-usage.html`。
94
+
95
+ <Tip>
96
+ UMD 模式无需打包工具，适合静态站点或简单嵌入场景；框架工程推荐使用 ESM 安装，以获得更好的 Tree-Shaking 与类型支持。
97
+ </Tip>
98
+
99
+ ### 配置项（Config）
100
+
101
+ 以下为常用配置项（更多字段以包内类型为准）：
102
+
103
+ | 键 | 类型 | 必填 | 默认值 | 说明 |
104
+ | --- | --- | --- | --- | --- |
105
+ | apiKey | string | 是 | - | 模型访问密钥（请勿直曝）。 |
106
+ | baseUrl | string | 否 | SDK 默认 | 模型服务地址，如 `https://api.siliconflow.cn/v1`。 |
107
+ | modelName | string | 是 | - | 模型名称，如 `Qwen/Qwen2.5-72B-Instruct`。 |
108
+ | organization | string | 否 | - | 组织标识。 |
109
+ | header | `{ title: string }` | 否 | `{ title: 'LangChat' }` | 头部标题配置。 |
110
+ | avatars | `{ ai: string|URL; user: string|URL; size?: number }` | 否 | `{ size: 32 }` | 头像与尺寸。 |
111
+ | theme | `{ mode?: 'light'|'dark'; primaryColor?; backgroundColor?; textColor?; borderRadius?; shadow?; customCSS? }` | 否 | 见源码默认 | 主题与样式。 |
112
+ | messages | `{ showAudioButton?; aiBackgroundColor?; userBackgroundColor?; userTextColor?; maxHeight? }` | 否 | 见源码默认 | 消息区样式与行为。 |
113
+ | copyright | `{ text: string; link?: string }` | 否 | `Powered by LangChat Widget` | 版权信息。 |
114
+ | welcome | `{ enabled?: boolean; title?: string }` | 否 | 启用且含默认标题 | 欢迎语配置。 |
115
+ | questions | `Array<{ id: string; text: string; value: string }>` | 否 | `[]` | 预置问题。 |
116
+ | backendAPI | `{ getWelcomeMessage?; getSuggestedQuestions? }` | 否 | - | 后端接口扩展，用于欢迎语与智能问题。 |
117
+ | position | `'bottom-right'|'bottom-left'|'top-right'|'top-left'` | 否 | `bottom-right` | 浮动位置。 |
118
+ | zIndex | number | 否 | `9999` | 层级。 |
119
+ | autoOpen | boolean | 否 | `false` | 初始化后是否自动打开。 |
120
+ | enableMarkdown | boolean | 否 | `true` | 开启 Markdown 渲染。 |
121
+ | enableHistory | boolean | 否 | `true` | 本地历史持久化。 |
122
+ | maxHistoryItems | number | 否 | `50` | 历史最大条数。 |
123
+ | enableStreaming | boolean | 否 | `true` | 开启流式输出。 |
124
+ | enableAutoSuggestions | boolean | 否 | `false` | 自动推荐问题（需 `backendAPI.getSuggestedQuestions`）。 |
125
+
126
+ <Note>
127
+ 校验规则（节选）：缺失 `apiKey` 会报错；`baseUrl` 会进行格式校验；`maxHistoryItems` 必须大于 0。
128
+ </Note>
129
+
130
+ ### 方法（API）
131
+
132
+ | 方法 | 签名 | 说明 |
133
+ | --- | --- | --- |
134
+ | open | `open(): void` | 打开聊天窗口 |
135
+ | close | `close(): void` | 关闭聊天窗口 |
136
+ | toggle | `toggle(): void` | 切换开合 |
137
+ | sendMessage | `sendMessage(content: string): Promise<void>` | 发送用户消息，并触发流式回复 |
138
+ | clearHistory | `clearHistory(): void` | 清空本地历史记录 |
139
+ | isOpen | `isOpen(): boolean` | 是否处于打开状态 |
140
+ | isLoading | `isLoading(): boolean` | 是否处于加载状态 |
141
+ | updateConfig | `updateConfig(partial: Partial<LangChatConfig>): void` | 运行时更新配置 |
142
+ | getConfig | `getConfig(): LangChatConfig` | 获取当前配置快照 |
143
+ | getHistory | `getHistory(): ChatMessage[]` | 获取当前消息历史 |
144
+ | on | `on(event: LangChatEvent, cb: Function): void` | 监听组件事件 |
145
+ | off | `off(event: LangChatEvent, cb: Function): void` | 取消事件监听 |
146
+
147
+ ### 事件（Events）
148
+
149
+ | 事件名 | 触发时机 | 回调参数 |
150
+ | --- | --- | --- |
151
+ | init | 初始化完成 | - |
152
+ | open / close | 窗口打开/关闭时 | - |
153
+ | message-sent | 用户消息已发送 | `ChatMessage` |
154
+ | message-received | AI 消息接收完成 | `ChatMessage` |
155
+ | streaming-update | 流式更新增量 | `{ messageId: string; content: string }` |
156
+ | config-updated | 配置已更新 | `Required<LangChatConfig>` |
157
+ | questions-updated | 建议问题更新 | `QuestionItem[]` |
158
+ | error | 捕获到错误 | `Error` |
159
+
160
+ ### Vue 进阶示例
161
+
162
+ 下面演示在任意组件中发送消息与监听事件：
163
+
164
+ ```ts
165
+ import { onMounted, onBeforeUnmount } from 'vue';
166
+ import { LangChatBot } from '@langchat-widget';
167
+ import '@langchat-widget/dist/langchat-widget.css';
168
+
169
+ let widget: LangChatBot | null = null;
170
+
171
+ onMounted(() => {
172
+ widget = new LangChatBot({
173
+ apiKey: 'YOUR_API_KEY',
174
+ baseUrl: 'https://api.siliconflow.cn/v1',
175
+ modelName: 'Qwen/Qwen2.5-72B-Instruct',
176
+ header: { title: 'Support Assistant' },
177
+ enableStreaming: true,
178
+ });
179
+
180
+ widget.on('message-received', (msg) => {
181
+ console.log('assistant replied:', msg.content);
182
+ });
183
+ });
184
+
185
+ onBeforeUnmount(() => {
186
+ widget?.destroy();
187
+ widget = null;
188
+ });
189
+ ```
190
+
191
+ ### 常见问题（FAQ）
192
+
193
+ 1) 浏览器报错 “process is not defined”
194
+ - 使用本组件打包的 UMD/ES 版本已对浏览器环境做了兼容处理；若你自行二次打包，请确保为 `process.env` 添加 polyfill。
195
+
196
+ 2) 报错 “OpenAI client not initialized”
197
+ - 确认已设置 `apiKey`，并在创建实例时传入。
198
+
199
+ 3) 无法获取建议问题
200
+ - 若未传入 `questions` 静态数组，需要提供 `backendAPI.getSuggestedQuestions` 方法，或关闭 `enableAutoSuggestions`。
201
+
202
+ 4) Markdown 样式无效
203
+ - 确认已引入 `@langchat-widget/dist/langchat-widget.css` 样式文件。
204
+
205
+ <Tip>
206
+ 若在 SSR 框架中（如 Nuxt）使用，请仅在客户端生命周期创建 `LangChatBot` 实例，以避免服务端渲染期间访问 `window` 导致报错。
207
+ </Tip>
208
+
209
+ ### 版本与打包
210
+
211
+ - 输出文件：
212
+ - `dist/langchat-widget.css`
213
+ - `dist/langchat-widget.es.js`
214
+ - `dist/langchat-widget.umd.js`
215
+ - UMD 全局对象：`window.LangChatWidget`，主类：`LangChatBot`
216
+ - 建议通过 ESM 方式在现代框架中引入，通过 UMD 方式在纯 HTML 使用
217
+
218
+ ### 许可
219
+
220
+ MIT
221
+
222
+
package/dist/favicon.ico ADDED
Binary file