vibe-ai-c 3.3.1 → 3.3.2

package/README.md

@@ -1,76 +1,73 @@
 # VibeAI (v3.3)
 
-VibeAI 是一个极简的、面向浏览器的多供应商 AI SDK 与 UI 管理工具。它专为希望在不引入大型框架（如 React/Vue）的情况下，快速在浏览器环境集成多模型 AI 能力的开发者设计。
+VibeAI 是一个极简、高性能、面向浏览器的多供应商 AI SDK 与 UI 管理工具。它旨在通过 **CDN 零配置集成**，为任何网页快速提供 OpenAI 兼容的 AI 能力。
 
 ## 核心特性
 
-- **零依赖 ESM**：纯 JavaScript 实现，无任何外部库依赖。
-- **增强安全性**：可选的 **AES-GCM (Web Crypto API)** 加密，使用主密码保护本地存储的 API Key。
-- **多实例绑定**：支持将多个 `<select>` 元素绑定到不同的模型实例，并独立持久化其选择状态。
-- **智能模型管理**：
-  - **上下文搜索**：针对拥有大量模型（>10个）的供应商提供实时搜索过滤。
-  - **批量操作**：支持对搜索结果进行“全选/清空”，不影响隐藏的模型。
-  - **自动排序**：模型列表按字母顺序排列。
-- **高稳定性 UI**：采用颗粒度 DOM 更新策略，在刷新列表或搜索时保持输入框焦点与滚动位置。
-- **智能路径逻辑**：自动处理 Base URL，如果请求失败会智能尝试补全 `/v1` 后缀。
+- **CDN 优先**：无需 npm 或复杂的构建工具，直接通过原生 ESM 导入。
+- **零依赖 (Zero-dependency)**：纯 JavaScript 实现，体积精简，不污染全局环境。
+- **安全性 (Web Crypto)**：支持 AES-GCM 硬件级加密存储 API Key。
+- **多实例绑定**：支持一个页面内多个对话框绑定不同供应商/模型。
+- **智能 UI 交互**：内置模型搜索、自动 `/v1` 路径补全、批量资产选择，且渲染过程不丢失输入焦点。
 
-## 快速开始
+## 快速集成 (Quick Start)
 
-### 1. 引入与初始化
-```javascript
-import { vibeAI } from './vibe-ai.js';
+由于 VibeAI 采用标准的 ESM 架构，你只需在 HTML 中使用 `<script type="module">` 即可直接从 CDN 引入：
 
-// 1. 初始化并绑定管理按钮
-await vibeAI.init({
-  setupBtnId: 'settings-btn' // 点击此按钮打开管理弹窗
-});
+### 1. 引入并初始化
+```html
+<script type="module">
+  // 推荐从 unpkg 引入最新生产版本
+  import { vibeAI } from 'https://unpkg.com/vibe-ai-c@3.3.2/vibe-ai.min.js';
+
+  // 初始化并绑定管理按钮
+  await vibeAI.init({
+    setupBtnId: 'settings-btn' 
+  });
 
-// 2. 绑定模型选择下拉框（支持多个）
-vibeAI.bindModelSelect('chat-model-selector');
+  // 绑定你的模型选择下拉框
+  vibeAI.bindModelSelect('my-selector');
+</script>
+
+<button id="settings-btn">设置 AI 供应商</button>
+<select id="my-selector"></select>
 ```
 
-### 2. 发起对话请求
+### 2. 调用对话
 ```javascript
-// 必须指定 instanceId（对应 bindModelSelect 的 ID）
 const stream = await vibeAI.chat({
-  instanceId: 'chat-model-selector',
+  instanceId: 'my-selector', // 对应绑定的 select id
   messages: [{ role: 'user', content: '你好！' }],
   stream: true
 });
 
 for await (const chunk of stream) {
-  process.stdout.write(chunk); // 逐字输出
+  console.log(chunk); // 实时流式输出
 }
 ```
 
 ## API 参考
 
 ### `vibeAI.init({ setupBtnId })`
-- 初始化 SDK。自动执行从 `v2` 到 `v3` 的配置迁移。
-- `setupBtnId`: (可选) 绑定一个 HTML 按钮用于打开管理界面。
+- **setupBtnId**: (可选) 字符串 ID。绑定后，点击该元素将自动弹出供应商配置界面。
+- **功能**: 执行存储迁移 (v2 -> v3) 并挂载全局样式。
 
 ### `vibeAI.bindModelSelect(id)`
-- 将一个 `<select>` 元素与 VibeAI 状态同步。
-- 自动填充用户在设置中勾选的模型资产。
-- 状态（用户的选择）会自动持久化。
+- **id**: HTML `<select>` 元素的 ID。
+- **功能**: 自动填充已勾选的模型资产池。当用户在设置中更改模型或供应商时，该下拉框会自动同步更新，并记忆用户的最后一次选择。
 
 ### `vibeAI.chat(payload)`
-- `payload.instanceId`: (必填) 绑定的 Select 元素 ID，用于获取当前选中的模型和供应商。
-- `payload.messages`: 标准 OpenAI 消息格式。
-- `payload.stream`: 布尔值。为 `true` 时返回 `AsyncGenerator`。
-
-### `vibeAI.openSettings()`
-- 编程方式打开供应商管理弹窗。
+- **payload.instanceId**: (必填) 绑定的 Select ID，SDK 据此识别供应商配置。
+- **payload.stream**: 布尔值。为 `true` 时返回 `AsyncGenerator`。
+- **payload.messages**: 标准 OpenAI 消息数组。
 
-## 配置规范
+## 进阶与部署
 
-- **存储方案**：使用 `vibe_ai_v3_config` 键名存储于 `localStorage`。
-- **加密模式**：开启加密后，API Key 以 `ENC:JSON_STR` 格式存储。主密码仅存在于内存会话中（SessionKey）。
-- **智能补全**：如果填写的 Base URL 请求失败，SDK 会检查是否缺少 `/v1`。例如：输入 `https://api.example.com` 失败后，会自动尝试 `https://api.example.com/v1`。
+- **生产环境建议**：始终在 CDN URL 中锁定版本号（如 `@3.3.2`）以确保生产环境稳定性。
+- **安全警告**：在非加密模式下，API Key 以明文存在 `localStorage`。建议引导用户点击设置面板顶部的“锁定”图标，通过 Web Crypto API 进行本地加密。
+- **智能路径补全**：若用户输入的 Base URL 无法连接，SDK 会自动尝试追加 `/v1`（如 `https://api.deepseek.com` -> `https://api.deepseek.com/v1`）。
 
-## UI 交互逻辑
+## 配置规范 (Storage)
 
-1. **获取模型**：点击“获取并校验资产”将连接供应商终端。
-2. **智能选择**：模型少于 10 个时默认全选；超过 10 个时需用户手动勾选常用模型。
-3. **搜索过滤**：在模型列表搜索框输入时，非匹配项会通过 CSS 隐藏，确保不破坏 DOM 树。
-4. **加密切换**：点击顶部“锁定”状态可切换明文/加密模式。
+- 存储键名：`vibe_ai_v3_config`
+- 加密前缀：`ENC:`（仅在开启加密模式时）

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "vibe-ai-c",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "一个极简的、面向浏览器的多供应商 AI SDK 与 UI 管理工具。支持 OpenAI 兼容协议。",
-  "main": "vibe-ai.js",
+  "main": "vibe-ai.min.js",
   "type": "module",
   "scripts": {
     "dev": "npx servor . demo.html 8080",