pangolin-lobster-widget

可嵌入任意网站的 AI 数据助手聊天窗口。基于 Shadow DOM 实现样式隔离，不影响宿主页面。

安装

pnpm add pangolin-lobster-widget
# 或
npm install pangolin-lobster-widget

快速接入

方式一：ES Module（Vue / React / Next 等现代框架）

import LobsterWidget from 'pangolin-lobster-widget';

const widget = LobsterWidget.init({
  // ===== 必填参数 =====

  // 后端 API 基础地址，所有接口请求都会发往这个地址
  apiUrl: 'https://api.pangolinfo.com',

  // 获取当前用户 JWT Token 的回调函数
  // Widget 每次调接口时都会调用此函数获取最新 token
  // 返回 null 时 Widget 会显示"请先登录"提示页
  getToken: () => localStorage.getItem('token'),

  // ===== 可选参数 =====

  // 触发按钮在页面中的位置
  // 可选: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  // 默认: 'bottom-right'
  position: 'bottom-right',

  // 主题色，影响标题栏、按钮、高亮等所有主色调
  // 支持任意 CSS 颜色值
  // 默认: '#f97316'（橙色）
  primaryColor: '#f97316',

  // 触发按钮上显示的文字
  // 默认: 'AI 助手'（中文）/ 'AI Assistant'（英文）
  triggerText: 'AI 助手',

  // 自定义触发按钮图标的图片 URL
  // 不设置则显示默认的龙虾 emoji
  triggerIcon: 'https://your-domain.com/icon.png',

  // 未登录时"去登录"按钮跳转的地址
  // 不设置则不显示登录跳转按钮
  loginUrl: '/login',

  // 页面加载后是否自动打开聊天窗口
  // 默认: false
  defaultOpen: false,

  // Widget 的 CSS z-index 层级
  // 如果和页面其他浮层冲突可以调整
  // 默认: 99999
  zIndex: 99999,

  // 界面语言
  // 可选: 'zh'（中文）| 'en'（英文）
  // 用户也可以在窗口标题栏手动切换
  // 默认: 'zh'
  locale: 'zh',

  // 微信二维码图片 URL
  // 设置后聊天区底部会显示引导条，点击展开显示二维码 + 留资表单
  // 不设置则只显示留资表单
  wechatQrUrl: 'https://your-domain.com/wechat-qr.png',
});

方式二：Script 标签（任意网页，无需构建工具）

<script src="https://unpkg.com/pangolin-lobster-widget/dist/lobster-widget.umd.js"></script>
<script>
  var widget = LobsterWidget.init({
    apiUrl: 'https://api.pangolinfo.com',
    getToken: function() {
      return localStorage.getItem('token');
    },
    position: 'bottom-right',
    primaryColor: '#f97316',
    loginUrl: '/login',
    locale: 'zh',
    wechatQrUrl: 'https://your-domain.com/wechat-qr.png',
  });
</script>

实例方法

LobsterWidget.init() 返回一个实例对象，可以用代码控制窗口：

const widget = LobsterWidget.init(config);

widget.open();     // 打开聊天窗口
widget.close();    // 关闭聊天窗口（回到触发按钮状态）
widget.destroy();  // 完全销毁 Widget，移除所有 DOM 元素

配置项一览

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|:----:|--------|------| | apiUrl | string | 是 | — | 后端 API 基础地址 | | getToken | () => string \| null \| Promise | 是 | — | 获取 JWT Token 的回调，支持同步/异步 | | position | string | 否 | 'bottom-right' | 触发按钮位置 | | primaryColor | string | 否 | '#f97316' | 主题色 | | triggerText | string | 否 | 'AI 助手' | 触发按钮文字 | | triggerIcon | string | 否 | 龙虾 emoji | 自定义按钮图标 URL | | loginUrl | string | 否 | — | 登录页跳转地址 | | defaultOpen | boolean | 否 | false | 是否默认打开窗口 | | zIndex | number | 否 | 99999 | CSS 层级 | | locale | 'zh' \| 'en' | 否 | 'zh' | 界面语言 | | wechatQrUrl | string | 否 | — | 微信二维码图片 URL |

getToken 说明

Widget 每次请求后端 API 时都会调用 getToken() 获取 JWT。不同项目存储 token 的方式不同，以下是常见写法：

// 从 localStorage 读取
getToken: () => localStorage.getItem('token')

// 从 Cookie 读取
getToken: () => getCookie('auth_token')

// 从 Vuex / Pinia 读取
getToken: () => store.state.user.token

// 从 Redux 读取
getToken: () => store.getState().auth.token

// 异步刷新 token（token 过期时自动续期）
getToken: async () => {
  if (isTokenExpired()) {
    return await refreshToken();
  }
  return localStorage.getItem('token');
}

当 getToken() 返回 null 时，Widget 会显示"请先登录"页面，引导用户去登录。

功能特性

• AI 流式对话 — 逐字输出 AI 回复，实时体验
• 多场景切换 — 竞品分析、关键词选品、评价洞察等场景 tab 切换
• 聊天历史 — 自动保存对话记录，刷新页面不丢失，支持上滑加载更多
• 用量统计 — 实时显示剩余积点，按用户独立配置上限
• 中英双语 — 支持 zh/en 切换，标题栏可手动切换
• 留资引导 — 底部常驻引导条，支持微信二维码 + 表单
• 背景信息 — 用户可填写业务背景，AI 根据背景给出更精准回答
• 样式隔离 — Shadow DOM 封装，不污染宿主页面 CSS
• 可拖拽缩放 — 窗口支持拖拽移动和右下角缩放
• 响应式布局 — 窗口较窄时自动切换为图标栏模式

开发

pnpm install    # 安装依赖
pnpm dev        # 启动开发服务器
pnpm build      # 构建产物到 dist/

技术栈

• React 18 + TypeScript
• Vite (Library Mode)
• Less
• Shadow DOM
• react-markdown