skycity-ai-sdk

SkyCity AI 聊天 SDK

一个功能完整、高度可定制的 AI 聊天 SDK，基于 Vue 3 + Vite 构建，提供仿 DeepSeek 风格的现代化聊天界面。支持多种 AI 模型、实时流式响应、语音交互、文件上传等丰富功能。

✨ 核心特性

🎨 界面与交互

• 现代化 UI 设计 - 仿 DeepSeek 的精美界面，支持明暗主题无缝切换
• 响应式布局 - 完美适配桌面端、平板和移动端设备
• 流畅动画 - 打字机效果、加载动画、过渡效果
• 可定制主题 - 支持自定义颜色、字体、圆角等样式配置

💬 聊天功能

• 多会话管理 - 创建、切换、删除、重命名聊天会话
• 智能面具系统 - 预设角色模板，快速切换对话场景
• 消息操作 - 编辑、删除、复制、重新生成消息
• 实时流式响应 - SSE 流式传输，支持打字机效果展示
• 深度思考模式 - 显示 AI 推理过程，提升交互透明度

🤖 AI 能力

• 多模型支持 - 支持 GPT、Claude、DeepSeek 等多种 AI 模型
• 联网搜索 - 实时获取最新信息，增强回答准确性
• 提示词优化 - 内置提示词优化功能，提升对话质量
• 上下文管理 - 智能管理对话上下文，保持连贯性

🎙️ 语音交互

• 语音录制 - 支持实时语音输入，自动转换为文本
• 音频可视化 - 实时波形显示，增强交互体验
• 静音检测 - 智能检测语音输入，避免无效录制
• 跨平台兼容 - 支持主流浏览器的语音 API

� 文件处理

• 图片上传 - 支持拖拽上传、粘贴上传多种方式
• 文件预览 - 内置图片预览功能，支持缩放查看
• 多格式支持 - 支持 JPG、PNG、GIF、WebP 等常见格式
• 云存储集成 - 可配置阿里云 OSS 等云存储服务

📊 数据管理

• 本地存储 - IndexedDB 存储聊天记录，支持离线访问
• 数据导出 - 支持 TXT、Markdown、JSON、图片等多种导出格式
• 缓存优化 - 智能缓存策略，提升加载性能
• 数据清理 - 自动清理过期数据，优化存储空间

🛠️ 技术架构

核心技术栈

• 前端框架: Vue 3 (Composition API)
• 构建工具: Vite 4.x
• 样式预处理: Less + CSS Variables
• HTTP 客户端: Axios
• 实时通信: Server-Sent Events (SSE)
• Markdown 渲染: Marked + Highlight.js
• 数据存储: IndexedDB
• 语音处理: Web Audio API

架构设计

• 组件化架构 - 高度模块化的组件设计，易于维护和扩展
• Hooks 模式 - 基于 Composition API 的 Hooks 设计，逻辑复用性强
• 插件系统 - 支持 Vue 插件方式集成，配置灵活
• 主题系统 - 完整的主题管理系统，支持动态切换
• 移动端优化 - 专门的移动端适配和性能优化

🚀 快速开始

安装

npm install skycity-ai-sdk
# 或
yarn add skycity-ai-sdk
# 或
pnpm add skycity-ai-sdk

基本使用

完整聊天组件（推荐）

<template>
  <SkyCityAIChat
    :base-url="config.baseUrl"
    :authorization="config.authorization"
    :upload-image="handleImageUpload"
    :selected-model="config.defaultModel"
    :theme-config="themeConfig"
    :ui-config="uiConfig"
    @error="handleError"
  />
</template>

<script setup>
import { SkyCityAIChat } from 'skycity-ai-sdk'
import 'skycity-ai-sdk/style.css'

// 基础配置
const config = {
  baseUrl: 'https://your-api-server.com',
  authorization: 'your-auth-token',
  defaultModel: 'gpt-4o-mini'
}

// 图片上传处理函数
const handleImageUpload = async (file, callbacks) => {
  try {
    callbacks.onProgress?.(0)

    // 这里实现你的图片上传逻辑
    const formData = new FormData()
    formData.append('file', file)

    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData
    })

    const result = await response.json()
    callbacks.onProgress?.(100)
    callbacks.onFinish?.(result.url)

    return result.url
  } catch (error) {
    callbacks.onError?.(error)
    throw error
  }
}

// 主题配置（可选）
const themeConfig = {
  primary: '#3b82f6',
  borderRadius: { medium: '12px' }
}

// UI 配置（可选）
const uiConfig = {
  components: {
    Button: 'el-button', // 使用 Element Plus
    Input: 'el-input'
  }
}

// 错误处理
const handleError = (error) => {
  console.error('AI Chat Error:', error)
}
</script>

轻量级聊天组件

<template>
  <SkyCityMinimalChat
    :base-url="baseUrl"
    :authorization="authorization"
    :title="'AI 助手'"
    :visible="true"
    :preset-questions="presetQuestions"
    @open="handleOpen"
    @close="handleClose"
  />
</template>

<script setup>
import { SkyCityMinimalChat } from 'skycity-ai-sdk'
import 'skycity-ai-sdk/style.css'

const baseUrl = 'https://your-api-server.com'
const authorization = 'your-auth-token'

const presetQuestions = [
  '帮我写一份工作总结',
  '解释一下 Vue 3 的新特性',
  '推荐一些学习资源'
]

const handleOpen = () => console.log('Chat opened')
const handleClose = () => console.log('Chat closed')
</script>

Vue 插件方式

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import { SkyCityAIPlugin } from 'skycity-ai-sdk'
import 'skycity-ai-sdk/style.css'

const app = createApp(App)

// 注册插件
app.use(SkyCityAIPlugin, {
  // 全局配置
  theme: {
    primary: '#3b82f6'
  },
  ui: {
    components: {
      Button: 'el-button',
      Input: 'el-input'
    }
  }
})

app.mount('#app')

配置参数

SkyCityAIChat 组件参数

SkyCityMinimalChat 组件参数

🎯 事件监听

SDK 提供了强大的事件系统，允许外部应用监听聊天过程中的各种事件。

基础用法

import { SkyCityAI } from 'skycity-ai-sdk'

// 监听用户发送消息事件
const unsubscribe = SkyCityAI.onMessageSent((data) => {
  console.log('用户发送了消息:', data.message.content)
  console.log('会话ID:', data.conversationId)
  console.log('是否包含图片:', data.hasImage)
  console.log('是否包含文件:', data.hasFile)
})

// 取消监听
unsubscribe()

支持的事件类型

消息相关事件

// 用户发送消息
SkyCityAI.onMessageSent((data) => {
  // data: { message, conversationId, timestamp, hasImage, hasFile }
})

// AI 回复消息
SkyCityAI.onMessageReceived((data) => {
  // data: { message, conversationId, timestamp }
})

// 消息被编辑
SkyCityAI.onMessageEdited((data) => {
  // data: { message, oldContent, newContent, conversationId, timestamp }
})

// 消息被删除
SkyCityAI.onMessageDeleted((data) => {
  // data: { messageId, conversationId, timestamp }
})

会话相关事件

// 创建新会话
SkyCityAI.onConversationCreated((data) => {
  // data: { conversationId, title, timestamp }
})

文件相关事件

// 文件上传完成
SkyCityAI.onFileUploaded((data) => {
  // data: { fileUrl, fileName, fileType, timestamp }
})

错误事件

// 监听错误
SkyCityAI.onError((data) => {
  // data: { error, context, timestamp }
})

高级用法

使用事件常量

import { SkyCityAI, EVENT_TYPES } from 'skycity-ai-sdk'

// 使用事件常量
SkyCityAI.on(EVENT_TYPES.MESSAGE_SENT, (data) => {
  console.log('消息发送事件:', data)
})

// 获取所有事件类型
console.log(SkyCityAI.events)

批量管理监听器

// 清除所有监听器
SkyCityAI.clearAllListeners()

// 手动取消特定监听器
const callback = (data) => console.log(data)
SkyCityAI.on('message:sent', callback)
SkyCityAI.off('message:sent', callback)

一次性监听

import { globalEventManager, EVENT_TYPES } from 'skycity-ai-sdk'

// 只监听一次
globalEventManager.once(EVENT_TYPES.MESSAGE_SENT, (data) => {
  console.log('这只会执行一次')
})

实际应用场景

用户行为统计

import { SkyCityAI } from 'skycity-ai-sdk'

// 统计用户消息数量
let messageCount = 0
SkyCityAI.onMessageSent(() => {
  messageCount++
  console.log(`用户已发送 ${messageCount} 条消息`)
})

// 统计会话数量
let conversationCount = 0
SkyCityAI.onConversationCreated(() => {
  conversationCount++
  console.log(`用户已创建 ${conversationCount} 个会话`)
})

自动保存聊天记录

SkyCityAI.onMessageSent((data) => {
  // 保存用户消息到数据库
  saveMessageToDatabase({
    type: 'user',
    content: data.message.content,
    conversationId: data.conversationId,
    timestamp: data.timestamp
  })
})

SkyCityAI.onMessageReceived((data) => {
  // 保存AI回复到数据库
  saveMessageToDatabase({
    type: 'assistant',
    content: data.message.content,
    conversationId: data.conversationId,
    timestamp: data.timestamp
  })
})

实时通知

SkyCityAI.onMessageReceived((data) => {
  // 显示桌面通知
  if (Notification.permission === 'granted') {
    new Notification('AI助手回复', {
      body: data.message.content.substring(0, 50) + '...',
      icon: '/ai-icon.png'
    })
  }
})

TypeScript 支持

SDK 提供完整的 TypeScript 类型支持：

import { SkyCityAI, MessageSentEventData } from 'skycity-ai-sdk'

SkyCityAI.onMessageSent((data: MessageSentEventData) => {
  console.log(data.message.content) // 类型安全
})

📋 API 接口

聊天接口

POST /chat/completions

发送聊天消息，支持 SSE 流式响应。

请求参数：

{
  "maskId": 0, // 面具ID（角色模板）
  "message": "你好，请介绍一下自己", // 用户消息内容
  "messageId": 1234567890, // 消息唯一ID（时间戳）
  "model": "gpt-4o-mini", // AI模型名称
  "reasonEnabled": false, // 是否启用深度思考
  "searchEnabled": false, // 是否启用联网搜索
  "preQuestion": "", // 预设问题（首次对话）
  "continueFrom": {
    // 续写配置（可选）
    "maskId": 0,
    "msgUid": "previous-msg-id",
    "cnvoId": "conversation-id"
  }
}

请求头：

Authorization: your-auth-token
Content-Type: application/json
Accept-Language: zh-CN

响应格式（SSE 流式）：

data:{"t":"c","v":"AI回复的文本内容"}
data:{"t":"r","v":"深度思考的推理过程"}
data:{"t":"end","v":""}

响应类型说明：

• t: "c" - 主要回复内容
• t: "r" - 深度思考内容
• t: "end" - 响应结束标志

模型列表接口

GET /chat/models

获取可用的 AI 模型列表。

响应格式：

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "modelCode": ["gpt-4o-mini"],
        "provider": ["OpenAI"],
        "description": {
          "name": "GPT-4o Mini",
          "desc": "快速响应的轻量级模型"
        },
        "abilities": [
          "text", // 文本对话
          "vision", // 图像理解
          "search", // 联网搜索
          "reason" // 深度思考
        ]
      }
    ]
  }
}

提示词优化接口

POST /chat/prompts/optimize

优化用户输入的提示词，提升对话质量。

请求参数：

{
  "prompt": "写一篇文章",
  "task": "step-by-step",
  "tip": ""
}

响应格式：

{
  "code": 0,
  "msg": "success",
  "data": {
    "optimizedPrompt": "请帮我写一篇关于[主题]的文章，要求：1. 结构清晰 2. 逻辑严谨 3. 内容丰富"
  }
}

📁 项目结构

src/
├── components/                 # 组件目录
│   ├── TianzhiAIChat.vue      # 主聊天组件（完整版）
│   ├── MinimalChat.vue        # 轻量级聊天组件
│   ├── MaskModal.vue          # 面具选择弹窗
│   ├── ChatHeader.vue         # 聊天头部组件
│   ├── ChatInputArea.vue      # 输入区域组件
│   ├── MessageList.vue        # 消息列表组件
│   ├── Sidebar.vue            # 侧边栏组件
│   ├── MarkdownRenderer.vue   # Markdown渲染组件
│   ├── ImagePreviewModal.vue  # 图片预览弹窗
│   ├── SettingsDialog.vue     # 设置对话框
│   └── ...                    # 其他UI组件
├── hooks/                     # Composition API Hooks
│   ├── useChatState.js        # 聊天状态管理
│   ├── useMessageManager.js   # 消息管理
│   ├── useVoiceFeature.js     # 语音功能
│   ├── useFileUpload.js       # 文件上传
│   ├── useThemeManager.js     # 主题管理
│   ├── useModelManager.js     # 模型管理
│   ├── useUIInteraction.js    # UI交互
│   ├── useMobileOptimization.js # 移动端优化
│   └── ...                    # 其他功能Hooks
├── services/                  # 服务层
│   └── api.js                 # API服务封装
├── utils/                     # 工具函数
│   ├── index.js              # 通用工具函数
│   ├── theme.js              # 主题相关工具
│   ├── mobile.js             # 移动端工具
│   ├── file.js               # 文件处理工具
│   ├── indexedDB.js          # 数据库操作
│   ├── sse.js                # SSE处理工具
│   └── chat.js               # 聊天相关工具
├── styles/                   # 样式文件
│   ├── variables.less        # Less变量定义
│   └── mobile.less           # 移动端样式
├── assets/                   # 静态资源
│   └── images/               # 图片资源
├── lib.js                    # 库入口文件
├── main.js                   # 开发入口文件
└── style.css                 # 全局样式

🎯 功能详解

会话管理系统

• 多会话支持 - 同时管理多个独立的聊天会话
• 会话持久化 - 基于 IndexedDB 的本地存储，支持离线访问
• 智能面具系统 - 预设角色模板，快速切换对话场景
• 会话操作 - 创建、删除、重命名、导出会话
• 自动标题生成 - 根据对话内容自动生成会话标题

消息处理系统

• 富文本支持 - Markdown 渲染、代码高亮、数学公式
• 消息操作 - 编辑、删除、复制、重新生成消息
• 流式渲染 - 实时显示 AI 回复，支持打字机效果
• 深度思考 - 展示 AI 推理过程，可折叠显示
• 消息分页 - 大量消息的分页加载，优化性能

语音交互系统

• 实时录音 - 支持连续语音输入，自动转换为文本
• 音频可视化 - 实时波形显示，增强交互体验
• 智能检测 - 自动检测语音开始和结束
• 跨平台兼容 - 支持主流浏览器的 Web Audio API
• 静音处理 - 智能过滤无效录音

文件上传系统

• 多种上传方式 - 拖拽、点击、粘贴上传
• 实时预览 - 上传前预览，支持图片缩放查看
• 进度显示 - 上传进度实时反馈
• 格式验证 - 支持多种图片格式验证
• 云存储集成 - 可配置各种云存储服务

主题系统

• 动态切换 - 明暗主题无缝切换
• 自定义配置 - 支持颜色、字体、圆角等自定义
• CSS 变量 - 基于 CSS 变量的主题系统
• 响应式适配 - 主题在不同设备上的适配
• 持久化存储 - 主题偏好本地存储

移动端优化

• 响应式布局 - 完美适配各种屏幕尺寸
• 触摸优化 - 针对触摸操作的交互优化
• 键盘适配 - 虚拟键盘弹出时的界面适配
• 性能优化 - 移动端性能优化策略
• 手势支持 - 滑动、长按等手势操作

开发说明

添加新功能

1. 在 src/components/ 目录下创建新组件
2. 在 src/stores/ 目录下添加状态管理
3. 在 src/services/ 目录下添加 API 服务
4. 在 src/utils/ 目录下添加工具函数

样式规范

• 使用 CSS 变量管理主题色彩
• 支持明暗主题切换
• 响应式设计，支持移动端
• 使用 Flexbox 和 Grid 布局

代码规范

• 使用 Vue 3 Composition API
• 使用 TypeScript 类型注解（可选）
• 遵循 ESLint 规则
• 组件命名使用 PascalCase

构建说明

本项目支持两种构建模式，分别用于不同的使用场景：

构建命令

1. build 命令

npm run build

• 用途: 构建完整的应用，包含开发模式的初始化逻辑
• 入口文件: src/main.js
• 特点:
  • 包含应用初始化代码 (createApp(App) 和 app.mount('#app'))
  • 主要用于开发环境或完整应用部署
  • 输出文件名: tianzhi-ai-sdk.js
  • 外部化依赖: vue, vue-router

2. build:lib 命令

npm run build:lib

• 用途: 构建纯库文件，供其他项目作为依赖使用
• 入口文件: src/lib.js
• 特点:
  • 提供 Vue 插件形式的导出 (TianzhiAIPlugin)
  • 支持多种模块格式: es、umd、cjs
  • 输出多个文件: tianzhi-ai-sdk.es.js、tianzhi-ai-sdk.umd.js、tianzhi-ai-sdk.cjs.js
  • 外部化依赖: vue、highlight.js
  • 包含 CSS 文件: tianzhi-ai-sdk.css

构建模式对比

推荐使用场景

• 使用 build:lib: 构建供其他项目使用的 SDK 库
• 使用 build: 构建完整的演示应用或开发环境

部署说明

构建 SDK

# 构建库文件（推荐）
npm run build:lib

# 或构建完整应用
npm run build

构建后的文件位于 dist/ 目录。

集成到其他项目

1. 将构建后的文件复制到目标项目
2. 引入组件并传入必要的配置参数
3. 确保目标项目支持 Vue 3

许可证

MIT License

贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

联系方式

如有问题或建议，请提交 Issue 或联系开发团队。

发布指南

快速发布

# 发布补丁版本 (1.2.0 -> 1.2.1)
npm run publish:patch

# 发布次要版本 (1.2.0 -> 1.3.0)
npm run publish:minor

# 发布主要版本 (1.2.0 -> 2.0.0)
npm run publish:major

使用发布脚本

Linux/Mac

# 给脚本执行权限
chmod +x scripts/publish.sh

# 发布补丁版本
./scripts/publish.sh patch

# 发布次要版本
./scripts/publish.sh minor

# 发布主要版本
./scripts/publish.sh major

# 查看帮助
./scripts/publish.sh help

Windows

# 发布补丁版本
scripts\publish.bat patch

# 发布次要版本
scripts\publish.bat minor

# 发布主要版本
scripts\publish.bat major

发布前检查

# 检查发布配置
npm run check-publish

# 构建项目
npm run build

# 检查 npm 登录状态
npm whoami

发布流程

发布脚本会自动执行以下步骤：

1. ✅ 检查项目目录和配置文件
2. ✅ 验证 npm 登录状态
3. ✅ 检查 git 状态（如有未提交更改会提示）
4. ✅ 验证包名可用性
5. ✅ 构建项目 (npm run build)
6. ✅ 更新版本号 (patch/minor/major)
7. ✅ 执行 dry-run 测试
8. ✅ 发布到 npm
9. ✅ 验证发布结果
10. ✅ 创建 git 标签（如果存在 git 仓库）

版本说明

• patch: 补丁版本，修复 bug (1.2.0 -> 1.2.1)
• minor: 次要版本，新增功能 (1.2.0 -> 1.3.0)
• major: 主要版本，破坏性更新 (1.2.0 -> 2.0.0)

注意事项

1. 发布前请确保已登录 npm: npm login
2. 建议先提交代码到 git 仓库
3. 发布前可以运行 npm run check-publish 检查配置
4. 如果发布失败，检查包名是否被占用或版本号是否已存在