cue-widget-sdk

v1.0.2

Published

a month ago

Cue 助手挂件 SDK - 支持 CDN 和 ESM 引入，开箱即用

0High
0Medium
0Low

xfgong

sdk widget ai-assistant chat react component ai llm assistant research cue-widget cue

Cue Widget SDK

特性

🚀 开箱即用 - 简单配置即可集成到任何项目
📦 多格式支持 - 支持 ESM、CJS、UMD (CDN) 三种引入方式
🎨 框架无关 - 可在 React、Vue、Angular 或纯 HTML 中使用
🎯 自动挂载 - 无需手动渲染组件
⚡ 按需加载 - 动态导入，减小包体积
🔧 高度可配置 - 支持自定义主题、位置、回调等

快速开始

方式一：CDN 引入（推荐）

最简单的方式，无需构建工具，直接在 HTML 中引入：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>我的网站</title>

  <!-- 1. 引入 React (如果页面中还没有) -->
  <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>

  <!-- 2. 引入 Cue Widget SDK -->
  <script src="https://unpkg.com/cue-widget-sdk/dist/umd/cue-widget-sdk.min.js"></script>

  <!-- 引入样式 -->
  <link rel="stylesheet" href="https://unpkg.com/cue-widget-sdk/dist/styles/globals.css">
</head>
<body>
  <div id="app"></div>

  <script>
    // 3. 初始化 SDK
    const widget = CueWidgetSDK.init({
      code: 'your-auth-code',  // 必填：你的授权码
      position: 'bottom-right',               // 按钮位置
      buttonLabel: '助手',                    // 按钮文字
      modalTitle: 'AI 助手',                  // 弹窗标题
    });

    // 可选：监听事件
    widget.onOpen(() => console.log('助手已打开'));
    widget.onClose(() => console.log('助手已关闭'));
  </script>
</body>
</html>

方式二：NPM 安装（React 项目）

npm install cue-widget-sdk
# 或
pnpm add cue-widget-sdk
# 或
yarn add cue-widget-sdk

ESM 引入（推荐）

import { init, create } from 'cue-widget-sdk';
import 'cue-widget-sdk/styles';

// 方式一：使用 init (推荐)
const widget = init({
  code: 'your-app-key',
  position: 'bottom-right',
  buttonLabel: '助手',
  modalTitle: 'AI 助手',
});

// 方式二：使用 create (更简洁)
const widget = create({
  code: 'your-app-key',
});

// 控制助手
widget.open();   // 打开助手
widget.close();  // 关闭助手

// 更新配置
widget.updateConfig({
  code: 'new-app-key',
});

// 销毁实例
widget.destroy();

直接使用 React 组件

如果你在 React 项目中，也可以直接使用组件：

import { CueWidget } from 'cue-widget-sdk';

function App() {
  return (
    <CueWidget
      code="your-app-key"
      position="bottom-right"
      buttonLabel="助手"
      modalTitle="AI 助手"
    />
  );
}

API 参考

`init(config)` - 初始化 SDK

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | code | string | ✅ | - | 授权码 | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | ❌ | 'bottom-right' | 按钮位置 | | buttonLabel | string | ❌ | 'Cue' | 按钮文字 | | modalTitle | string | ❌ | 'AI 助手' | 弹窗标题 | | closeOnClickOutside | boolean | ❌ | false | 点击外部是否关闭 | | zIndex | number | ❌ | 2000 | 弹窗层级 | | primaryColor | string | ❌ | '#6366f1' | 主题色 (十六进制) | | theme | 'light' \| 'dark' | ❌ | 'light' | 主题模式 | | onOpen | () => void | ❌ | - | 打开回调 | | onClose | () => void | ❌ | - | 关闭回调 |

返回值： CueWidgetInstance

`CueWidgetInstance` - SDK 实例方法

| 方法 | 参数 | 说明 | |------|------|------| | open() | - | 打开助手 | | close() | - | 关闭助手 | | updateConfig(config) | Partial<CueWidgetConfig> | 更新配置 | | destroy() | - | 销毁实例 |

高级用法

多种初始化方式

import { init, create } from 'cue-widget-sdk';

// 完整配置
const widget1 = init({
  code: 'your-app-key',
  position: 'bottom-right',
  buttonLabel: 'AI 助手',
  modalTitle: '智能问答',
  theme: 'dark',
  primaryColor: '#4F46E5',
  onOpen: () => console.log('打开'),
  onClose: () => console.log('关闭'),
});

// 简洁配置 (使用默认值)
const widget2 = create({
  code: 'your-app-key',
});

动态更新配置

const widget = create({
  code: 'your-app-key',
  position: 'bottom-right',
});

// 切换位置
widget.updateConfig({ position: 'top-left' });

// 切换主题
widget.updateConfig({ theme: 'dark', primaryColor: '#10B981' });

// 更新 AppKey
widget.updateConfig({ code: 'new-app-key' });

事件监听

const widget = init({
  code: 'your-app-key',
  onOpen: () => {
    // 助手打开时执行
    console.log('助手已打开');
  },
  onClose: () => {
    // 助手关闭时执行
    console.log('助手已关闭');
  },
});

// 也可以通过实例方法监听
widget.onOpen(() => console.log('打开'));
widget.onClose(() => console.log('关闭'));

在 Vue 中使用

<template>
  <div id="app"></div>
</template>

<script>
import { create } from 'cue-widget-sdk';
import 'cue-widget-sdk/styles';

export default {
  mounted() {
    this.widget = create({
      code: 'your-app-key',
    });

    // 3秒后自动打开助手
    setTimeout(() => {
      this.widget.open();
    }, 3000);
  },
  beforeDestroy() {
    if (this.widget) {
      this.widget.destroy();
    }
  },
};
</script>

在 Angular 中使用

import { Component, OnInit, OnDestroy } from '@angular/core';
import { init } from 'cue-widget-sdk';

@Component({
  selector: 'app-root',
  template: `<div id="app"></div>`,
})
export class AppComponent implements OnInit, OnDestroy {
  private widget: any;

  ngOnInit() {
    this.widget = init({
      code: 'your-app-key',
    });
  }

  ngOnDestroy() {
    if (this.widget) {
      this.widget.destroy();
    }
  }
}

构建命令

# 开发模式
pnpm run dev

# 构建所有格式 (ESM, CJS, UMD)
pnpm run build

# 代码检查
pnpm run lint

# 代码格式化
pnpm run format

# 类型检查
pnpm run type-check

# 发布新版本 (需要先配置 standard-version)
pnpm run release

开发指南: 更多开发流程、发布注意事项等，请参考 DEVELOPMENT.md

项目结构

cue-widget-sdk/
├── src/
│   ├── index.tsx              # ESM/CJS 入口
│   ├── cue-widget-sdk.tsx     # UMD 入口 + SDK 主逻辑
│   ├── components/            # React 组件
│   │   └── CueWidget/          # 主组件
│   ├── api/                   # API 请求封装
│   ├── contexts/              # React Context
│   ├── hooks/                 # 自定义 Hooks
│   ├── styles/                # 全局样式
│   │   └── globals.css       # Tailwind 样式
│   └── types/                 # TypeScript 类型
├── dist/                      # 构建输出
│   ├── esm/                   # ESM 格式
│   ├── cjs/                   # CJS 格式
│   ├── umd/                   # UMD 格式 (CDN)
│   └── styles/                 # 样式文件
├── rollup.config.js           # 统一构建配置 (ESM/CJS/UMD)
├── package.json
└── tsconfig.json

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme