ai-chat-embed 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhoumingle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,302 @@
+# ai-chat-embed(AI助手组件)
+
+将 AI-Chat 聊天组件球嵌入任意网站，**只需一行 `<script>`，无需依赖任何框架、无需构建工具**。
+
+## 跨框架接入（核心特性）
+
+`ai-chat-embed` 的核心目标就是 **跨框架、跨技术栈**：
+
+- React / Next.js / Vue / Angular / Svelte
+- 原生 HTML / 传统多页（JSP、PHP、Rails 模板）
+- jQuery、低代码平台、自定义脚本区块
+
+你无需把业务项目改造成 Vue3，只要页面能插入 `<script>` 即可接入。
+
+> 本包基于 [ai-suspended-ball-chat](https://www.npmjs.com/package/ai-suspended-ball-chat) 封装，将其能力扩展到任意前端技术栈。
+
+![Snipaste_2025-08-31_19-48-18.png](https://luckycola.com.cn/public/imgs/luckycola_Imghub_forever_8sbgSs4M17686524429047868.jpeg)
+
+**《组件落地场景体验1-AI简历助手》**: [点击直达案例1🔗](https://luckycola.com.cn/public/resume/?t=123456789#/resume)
+
+**《组件落地场景体验2-AI编程助手》**: [点击直达案例2🔗](https://luckycola.com.cn/public/dist/onlineCodeEditor.html?t=123456789#/editor)
+
+> **🔔 温馨提示:** 如果您觉得阅读文档困难,也可以选择咨询*在线AI助手*: [🤖点击直达咨询→](https://luckycola.com.cn/public/dist/aiAgent.html?openChat=1&t=123456789#/)
+
+---
+
+## ✨ 特性
+
+- 🚀 **即插即用**：只需 `<script>` + `AIChatEmbed.init()` 即可挂载
+- 🧩 **跨框架接入**：React / Vue / Angular / jQuery / 原生 HTML 通用
+- 🪄 **双模式渲染**：支持 `ball` 悬浮球模式与 `panel` 内嵌面板模式
+- 🔁 **实例化调用**：`const chat = await init()` 后可 `sendMessage / update / destroy`
+- 📡 **加载生命周期回调**：支持 `onEmbedLoading / onEmbedReady / onEmbedError`
+- 🧱 **资源自动加载**：自动拉取 Vue、lodash、组件 UMD（支持自定义 CDN 地址）
+- 🧠 **能力透传**：原组件方法可通过实例动态透传，减少封装层跟随升级成本
+
+> 说明：本包重点解决“跨技术栈嵌入与生命周期管理”，具体 AI 业务能力（流式、语音、图片上传、历史记录等）由底层 `ai-suspended-ball-chat` 提供并透传。
+
+---
+
+## 一、两种模式
+
+### 悬浮球模式（默认）
+
+页面右侧出现可拖拽的悬浮球，点击弹出聊天面板，适合全站挂载。
+
+```html
+<script src="https://unpkg.com/ai-chat-embed/dist/ai-chat-embed.min.js"></script>
+<script>
+  AIChatEmbed.init({
+    url: "https://your-api-endpoint.com/chat",
+    appName: "my-app",
+    domainName: "user123",
+    enableStreaming: true
+  });
+  // mode 默认为 "ball"，可省略
+</script>
+```
+
+### 面板模式
+
+ChatPanel 内嵌在指定容器中，适合嵌入页面某个固定区域（如侧边栏、弹窗内）。
+
+```html
+<div id="my-chat-area" style="width:400px;height:600px;"></div>
+
+<script src="https://unpkg.com/ai-chat-embed/dist/ai-chat-embed.min.js"></script>
+<script>
+  AIChatEmbed.init({
+    mode: "panel",
+    mountTo: "#my-chat-area",
+    url: "https://your-api-endpoint.com/chat",
+    appName: "my-app",
+    domainName: "user123",
+    enableStreaming: true,
+    showCloseButton: false
+  });
+</script>
+```
+
+## 二、多技术栈接入示例
+
+### React（useEffect）
+
+```jsx
+import { useEffect } from "react";
+
+export default function Page() {
+  useEffect(() => {
+    let chat;
+    const boot = async () => {
+      chat = await window.AIChatEmbed.init({
+        url: "https://your-api-endpoint.com/chat",
+        appName: "react-app",
+        domainName: "react-user",
+        mode: "ball"
+      });
+    };
+    boot();
+
+    return () => {
+      chat?.destroy();
+    };
+  }, []);
+
+  return <div>My React Page</div>;
+}
+```
+
+> 前提：页面已通过 `<script src=\"https://unpkg.com/ai-chat-embed/dist/ai-chat-embed.min.js\"></script>` 加载 SDK。
+
+### 原生 HTML
+
+```html
+<script src="https://unpkg.com/ai-chat-embed/dist/ai-chat-embed.min.js"></script>
+<script>
+  (async function () {
+    const chat = await AIChatEmbed.init({
+      url: "https://your-api-endpoint.com/chat",
+      appName: "native-page",
+      domainName: "user-001",
+      mode: "ball"
+    });
+    // 主动发一条欢迎消息
+    chat.sendMessage("你好，介绍一下你的能力");
+  })();
+</script>
+```
+
+### jQuery 页面
+
+```html
+<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
+<script src="https://unpkg.com/ai-chat-embed/dist/ai-chat-embed.min.js"></script>
+<script>
+  $(async function () {
+    const chat = await AIChatEmbed.init({
+      url: "https://your-api-endpoint.com/chat",
+      appName: "jquery-app",
+      domainName: "jquery-user",
+      mode: "panel",
+      mountTo: "#chat-container"
+    });
+
+    $("#send-btn").on("click", function () {
+      chat.sendMessage($("#msg").val());
+    });
+  });
+</script>
+```
+
+### Vue 2 (Options API)
+
+```vue
+<template>
+  <div>My Vue 2 Page</div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      chat: null
+    };
+  },
+  async mounted() {
+    this.chat = await window.AIChatEmbed.init({
+      url: "https://your-api-endpoint.com/chat",
+      appName: "vue2-app",
+      domainName: "vue2-user",
+      mode: "ball"
+    });
+  },
+  beforeDestroy() {
+    this.chat?.destroy();
+  }
+};
+</script>
+```
+
+> 前提：页面已通过 `<script src="https://unpkg.com/ai-chat-embed/dist/ai-chat-embed.min.js"></script>` 加载 SDK。
+
+
+## 三、API
+
+### `AIChatEmbed.init(options)`
+
+初始化并挂载组件，返回 Promise。同一页面重复调用不会重复挂载。
+
+```js
+const chat = await AIChatEmbed.init({
+  url: "https://your-api-endpoint.com/chat",
+  appName: "my-app",
+  domainName: "user123",
+  enableStreaming: true,
+  callbacks: {
+    onUserMessage: (msg) => console.log("用户发送:", msg),
+    onAssistantMessage: (msg) => console.log("AI 回复:", msg),
+    onError: (err) => console.error("出错:", err)
+  }
+});
+```
+
+可选：你可以在 `init` 传入封装层生命周期回调，处理首次 CDN 资源加载时的业务 loading：
+
+```js
+const chat = await AIChatEmbed.init({
+  // ...你的业务配置
+  onEmbedLoading: (loading, meta) => {
+    // loading=true 开始加载外部资源，false 结束
+    // meta: { mode, containerId }
+  },
+  onEmbedReady: (meta) => {
+    // 首次挂载完成后触发（含 elapsedMs）
+  },
+  onEmbedError: (error, meta) => {
+    // 资源加载失败或初始化失败时触发
+  }
+});
+```
+
+### `chat.update(options)`
+
+通过实例动态更新组件配置（如切换标题、接口地址等），无需重新挂载。
+
+```js
+chat.update({ title: "新的助手名称" });
+```
+
+### 主动调用能力（关键入口）
+
+初始化返回的实例可直接调用：
+
+```js
+const chat = await AIChatEmbed.init({ /* ... */ });
+chat.sendMessage("你好，帮我总结今日工作");
+chat.getChatState();
+chat.stopRequest();
+chat.clearHistory();
+```
+
+实例也支持通用调用和动态方法透传（便于对齐底层组件升级）：
+
+```js
+chat.invoke("sendMessage", "你好");
+// 如果底层组件存在 someNewMethod，会自动透传
+chat.someNewMethod?.("arg1");
+```
+
+### `chat.destroy()`
+
+通过实例卸载并移除组件，彻底清理 DOM。
+
+```js
+chat.destroy();
+```
+
+## 四、配置说明
+
+以下参数由本包提供，用于控制资源加载和挂载行为：
+
+| 参数 | 类型 | 默认值 | 说明 |
+| ------ | ------ | -------- | ------ |
+| `mode` | `"ball"` \| `"panel"` | `"ball"` | 悬浮球模式或内嵌面板模式 |
+| `mountTo` | string \| HTMLElement | `"body"` | 挂载目标，支持 CSS 选择器或元素引用 |
+| `containerId` | string | `"ai-chat-embed-root"` / `"ai-chat-panel-root"` | 挂载容器的 `id`，ball/panel 模式各有默认值 |
+| `vueUrl` | string | unpkg Vue3 CDN | 自定义 Vue3 全局构建地址 |
+| `lodashUrl` | string | unpkg lodash CDN | 自定义 lodash 全局构建地址（需包含 `_.cloneDeep`） |
+| `chatLibUrl` | string | unpkg 原组件 UMD 地址 | 自定义原组件 UMD 加载地址,可以按需按选择版本,默认‘正式版’ |
+| `onEmbedLoading` | function | - | 封装层资源加载状态回调：`(loading, meta)` |
+| `onEmbedReady` | function | - | 封装层初始化完成回调：`(meta)` |
+| `onEmbedError` | function | - | 封装层初始化失败回调：`(error, meta)` |
+
+> 其余所有配置（`url`、`appName`、`domainName`、`title`、`callbacks`、`enableStreaming` 等）会直接透传给底层 `SuspendedBallChat` 组件。完整配置参考原包文档：[ai-suspended-ball-chat](https://www.npmjs.com/package/ai-suspended-ball-chat)
+
+## 五、适用场景
+
+- 营销页、活动页快速集成 AI 客服
+- React / Angular / Svelte 等非 Vue 项目
+- 传统 JSP、PHP 等多页应用
+- 低代码平台的自定义 HTML 区块
+
+## 六、高级扩展能力支持
+- 如需支持 Mermaid 渲染，请在页面中提前引入：`https://unpkg.com/mermaid@11.10.1/dist/mermaid.min.js`
+- 如需支持 ECharts 渲染，请在页面中提前引入：`https://unpkg.com/echarts@5.0.0/dist/echarts.min.js`
+
+## 七、chatLibUrl版本
+- 正式版本: https://unpkg.com/ai-suspended-ball-chat@latest/dist/suspended-ball-chat.umd.js
+- alpha版本: https://unpkg.com/ai-suspended-ball-chat@0.3.61-alpha.1/dist/suspended-ball-chat.umd.js
+- beta版本: https://unpkg.com/ai-suspended-ball-chat@0.3.61-beta.1/dist/suspended-ball-chat.umd.js
+
+### Q: 不同版本功能上是否有差异?
+
+A: 是的,当前有三个版本: 正式版、beta版本、alpha版本。他们的差异如下:
+
+- **正式版**: 稳定版,功能最新且齐全,但此版本不支持“**独立协议的深度思考模式**”,但是你可以通过后端将“思考内容”用`<details><summary >`包裹间接实现这个功能.
+  
+- **beta版本**: 这是一个差异版本,对齐正式版90%的功能,支持“**独立协议的深度思考模式**”,但是此版本不支持“渲染自定义组件”等功能。
+  
+- **alpha版本**: 这是一个实验版本, 对齐正式版100%的功能, 唯一的差异是此版本已经将“对话列表虚拟化”了以提升性能,此版本和主版本一样不支持“**独立协议的深度思考模式**”, 可能存在一些未知Bug,谨慎使用.
+
+**总结: 根据您的需求选择需要的版本, 无特殊需求建议使用正式版。**

package/dist/ai-chat-embed.min.js

@@ -0,0 +1 @@
+var AIChatEmbed=(()=>{var A=Object.defineProperty;var D=Object.getOwnPropertyDescriptor;var R=Object.getOwnPropertyNames;var $=Object.prototype.hasOwnProperty;var F=(e,t)=>{for(var o in t)A(e,o,{get:t[o],enumerable:!0})},T=(e,t,o,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of R(t))!$.call(e,r)&&r!==o&&A(e,r,{get:()=>t[r],enumerable:!(n=D(t,r))||n.enumerable});return e};var _=e=>T(A({},"__esModule",{value:!0}),e);var Q={};F(Q,{default:()=>J,init:()=>V});var v={vueUrl:"https://unpkg.com/vue@3/dist/vue.global.prod.js",lodashUrl:"https://unpkg.com/lodash@4.17.21/lodash.min.js",chatLibUrl:"https://unpkg.com/ai-suspended-ball-chat/dist/suspended-ball-chat.umd.js",mode:"ball",mountTo:"body",containerId:"ai-chat-embed-root"},u={},f=null,l=new Map,y=new Map;function h(e,...t){if(typeof e=="function")try{e(...t)}catch{}}function H(){if(typeof window>"u"||typeof document>"u")throw new Error("AIChatEmbed can only run in browser environments.")}function S(e,t){if(typeof t=="function"&&t())return Promise.resolve();if(l.has(e))return l.get(e);let o=document.querySelector(`script[data-ai-chat-embed-src="${e}"]`);if(o){let r=o.getAttribute("data-ai-chat-embed-loaded"),d=o.getAttribute("data-ai-chat-embed-error");if(r==="1"){let a=Promise.resolve();return l.set(e,a),a}if(d==="1")o.remove();else{let a=new Promise((E,c)=>{o.addEventListener("load",()=>E(),{once:!0}),o.addEventListener("error",()=>{o.setAttribute("data-ai-chat-embed-error","1"),c(new Error(`Failed loading script: ${e}`))},{once:!0})});return a.catch(()=>{l.delete(e)}),l.set(e,a),a}}let n=new Promise((r,d)=>{let a=document.createElement("script");a.src=e,a.async=!0,a.setAttribute("data-ai-chat-embed-src",e),a.onload=()=>{a.setAttribute("data-ai-chat-embed-loaded","1"),r()},a.onerror=()=>{a.setAttribute("data-ai-chat-embed-error","1"),d(new Error(`Failed loading script: ${e}`))},document.head.appendChild(a)});return n.catch(()=>{l.delete(e)}),l.set(e,n),n}function I(e){let t=[window.SuspendedBallChat,window.suspendedBallChat,window.AISuspendedBallChat,window.aiSuspendedBallChat,window.AiSuspendedBallChat,window.AI_SUSPENDED_BALL_CHAT,window["ai-suspended-ball-chat"]];for(let o of t)if(o&&o.SuspendedBallChat)return o;for(let o of e){let n=window[o];if(n&&typeof n=="object"&&n.SuspendedBallChat)return n}return null}function K(){window.Vue&&(typeof window.Vue.component!="function"&&(window.Vue.component=function(){return this}),typeof window.Vue.extend!="function"&&(window.Vue.extend=function(t){return function(n){return{...t,props:n}}}),typeof window.Vue.set!="function"&&(window.Vue.set=function(t,o,n){return t[o]=n,n}),typeof window.Vue.delete!="function"&&(window.Vue.delete=function(t,o){delete t[o]}))}async function q(e){return f||(f=(async()=>{await S(e.vueUrl,()=>!!(window.Vue&&window.Vue.createApp)),await S(e.lodashUrl,()=>!!(window._&&typeof window._.cloneDeep=="function")),K();let t=new Set(Object.keys(window));await S(e.chatLibUrl,()=>!!I([]));let o=Object.keys(window).filter(d=>!t.has(d)),n=window.Vue;if(!n||!n.createApp||!n.h||!n.reactive||!n.ref)throw new Error("Vue 3 runtime not found after loading script.");let r=I(o)||I([]);if(!r||!r.SuspendedBallChat)throw new Error("Cannot find SuspendedBallChat export from ai-suspended-ball-chat.");if(!r.ChatPanel)throw new Error("Cannot find ChatPanel export from ai-suspended-ball-chat.");return{vue:n,chatLib:r}})().catch(t=>{throw f=null,t}),f)}function N(e){if(!e||e==="body")return document.body;if(typeof e=="string"){let t=document.querySelector(e);if(!t)throw new Error(`mountTo selector not found: ${e}`);return t}if(e instanceof HTMLElement)return e;throw new Error("mountTo must be a CSS selector, HTMLElement, or 'body'.")}function z(e){let t=N(e.mountTo),o=e.containerId,n=document.getElementById(o),r=!1;return n?n.parentNode||t.appendChild(n):(n=document.createElement("div"),n.id=o,t.appendChild(n),r=!0),{container:n,createdContainer:r}}function B(e){let t={...e};return delete t.vueUrl,delete t.lodashUrl,delete t.chatLibUrl,delete t.mode,delete t.mountTo,delete t.containerId,delete t.onEmbedLoading,delete t.onEmbedReady,delete t.onEmbedError,t}async function V(e={}){H();let t=e.mode||v.mode;if(t!=="ball"&&t!=="panel")throw new Error(`Invalid mode "${t}". Use "ball" or "panel".`);let o=t==="panel"?"ai-chat-panel-root":v.containerId,n={...v,containerId:o,...e,mode:t},r=n.containerId,d={mode:t,containerId:n.containerId};if(u[r])return h(e.onEmbedReady,d),u[r].publicApi;if(y.has(r))return y.get(r);let a=(async()=>{let E=Date.now();h(e.onEmbedLoading,!0,d);try{let k=function(i,...s){let p=g.value;if(!p||typeof p[i]!="function")throw new Error(`Method "${i}" is unavailable before component ready.`);return p[i](...s)},{vue:c,chatLib:m}=await q(n),{container:w,createdContainer:P}=z(n),C=c.reactive(B(e)),g=c.ref(null),x=t==="panel"?m.ChatPanel:m.SuspendedBallChat,b=c.createApp({name:"AIChatEmbedRoot",render(){return c.h(x,{...C,ref:g})}});typeof m.install=="function"&&b.use(m),b.mount(w);let M={update(i={}){if(!u[r])throw new Error("Instance already destroyed.");Object.assign(C,B(i))},destroy(){u[r]&&(b.unmount(),P&&w.parentNode&&w.parentNode.removeChild(w),delete u[r],Object.keys(u).length===0&&(f=null,l.clear()))},invoke(i,...s){return k(i,...s)}},L=new Proxy(M,{get(i,s,p){if(Reflect.has(i,s))return Reflect.get(i,s,p);if(typeof s=="string"&&!["then","catch","finally"].includes(s))return(...j)=>i.invoke(s,...j)}});return u[r]={app:b,componentProps:C,componentRef:g,container:w,createdContainer:P,publicApi:L},h(e.onEmbedReady,{...d,elapsedMs:Date.now()-E}),L}catch(c){throw h(e.onEmbedError,c,d),c}finally{h(e.onEmbedLoading,!1,d),y.delete(r)}})();return y.set(r,a),a}var G={init:V},U=G;typeof window<"u"&&(window.AIChatEmbed=U);var J=U;return _(Q);})();

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "ai-chat-embed",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Framework-agnostic embed wrapper for ai-suspended-ball-chat",
+  "main": "dist/ai-chat-embed.min.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "default": "./dist/ai-chat-embed.min.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "dev": "concurrently -k \"npm:build:watch\" \"npm:serve\" \"npm:mock\"",
+    "dev:web": "concurrently -k \"npm:build:watch\" \"npm:serve\"",
+    "serve": "serve . -l 5173",
+    "mock": "node mock/server.js",
+    "build": "esbuild src/ai-chat-embed.js --bundle --format=iife --global-name=AIChatEmbed --minify --outfile=dist/ai-chat-embed.min.js",
+    "build:dev": "esbuild src/ai-chat-embed.js --bundle --format=iife --global-name=AIChatEmbed --sourcemap --outfile=dist/ai-chat-embed.js",
+    "build:watch": "esbuild src/ai-chat-embed.js --bundle --format=iife --global-name=AIChatEmbed --sourcemap --outfile=dist/ai-chat-embed.js --watch",
+    "test": "vitest run --environment jsdom",
+    "test:watch": "vitest --environment jsdom",
+    "test:coverage": "vitest run --environment jsdom --coverage",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "concurrently": "^9.2.1",
+    "cors": "^2.8.5",
+    "jsdom": "^24.1.3",
+    "express": "^4.21.2",
+    "rimraf": "^6.0.1",
+    "serve": "^14.2.5",
+    "esbuild": "^0.27.0",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "ai",
+    "chat",
+    "embed",
+    "widget",
+    "vue3",
+    "react",
+    "angular",
+    "jquery",
+    "jsp",
+    "php",
+    "html",
+    "css",
+    "javascript",
+    "typescript",
+    "framework-agnostic",
+    "mermaid",
+    "echarts"
+  ],
+  "license": "MIT",
+  "author": "ai-chat-embed team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mingle98/ai-chat-embed.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mingle98/ai-chat-embed/issues"
+  },
+  "homepage": "https://github.com/mingle98/ai-chat-embed#readme"
+}