a2a-ai-chat-sdk

AI Chat SDK

一个功能完善的AI聊天SDK，支持Vue 3，提供开箱即用的聊天组件和灵活的API。

✨ 核心特性

🎯 真正的开箱即用

• ✅ 零配置启动 - 导入即用，无需实现任何功能
• ✅ 完整UI组件 - 原版样式100%还原
• ✅ 自动初始化 - 自动获取所有必要信息
• ✅ 智能管理 - 自动管理session、智能体、用户信息

🚀 完整功能

• ⚡ 打字机效果 - 模拟真实的逐字打印
• 🧠 深度思考 - 支持深度思考模式
• 🌐 联网搜索 - 支持实时网络搜索
• 📝 会话管理 - 创建、加载、删除会话
• 🔄 重新生成 - 支持重新生成AI回答
• ⏸️ 停止对话 - 可随时停止生成
• 💾 历史记录 - 自动保存对话历史
• 📎 文件上传 - 支持文件上传功能
• 🤖 智能体切换 - 支持多智能体切换
• 📋 一键复制 - 支持复制消息内容

📦 安装

方式一：一键安装（推荐）

最简单的方式，一次性安装 SDK 和所有必需依赖：

npm install a2a-ai-chat-sdk vue@^3.2.41 element-plus@^2.6.0 pinia@^2.1.7 vue-router@^4.6.3 axios@^1.6.7 js-cookie@^3.0.5 @microsoft/fetch-event-source@^2.0.1 vant@3.6.6 markdown-it@^14.0.0 markdown-it-katex@^2.0.3 marked@^11.0.0 highlight.js@^11.9.0 dompurify@^3.0.11 event-source-polyfill@^1.0.31

使用 yarn：

yarn add a2a-ai-chat-sdk vue@^3.2.41 element-plus@^2.6.0 pinia@^2.1.7 vue-router@^4.6.3 axios@^1.6.7 js-cookie@^3.0.5 @microsoft/fetch-event-source@^2.0.1 vant@3.6.6 markdown-it@^14.0.0 markdown-it-katex@^2.0.3 marked@^11.0.0 highlight.js@^11.9.0 dompurify@^3.0.11 event-source-polyfill@^1.0.31

使用 pnpm：

pnpm add a2a-ai-chat-sdk vue@^3.2.41 element-plus@^2.6.0 pinia@^2.1.7 vue-router@^4.6.3 axios@^1.6.7 js-cookie@^3.0.5 @microsoft/fetch-event-source@^2.0.1 vant@3.6.6 markdown-it@^14.0.0 markdown-it-katex@^2.0.3 marked@^11.0.0 highlight.js@^11.9.0 dompurify@^3.0.11 event-source-polyfill@^1.0.31

方式二：分步安装

如果项目已安装部分依赖，可以分步安装：

步骤 1：安装 SDK

npm install a2a-ai-chat-sdk

步骤 2：安装核心框架依赖

npm install vue@^3.2.41 element-plus@^2.6.0 pinia@^2.1.7 vue-router@^4.6.3

步骤 3：安装工具库依赖

npm install axios@^1.6.7 js-cookie@^3.0.5 @microsoft/fetch-event-source@^2.0.1

步骤 4：安装 UI 组件库依赖

npm install vant@3.6.6

步骤 5：安装 Markdown 和代码高亮依赖

npm install markdown-it@^14.0.0 markdown-it-katex@^2.0.3 marked@^11.0.0 highlight.js@^11.9.0

步骤 6：安装其他功能依赖

npm install dompurify@^3.0.11 event-source-polyfill@^1.0.31

方式三：分类安装（按功能模块）

如果只需要部分功能，可以按需安装：

仅核心功能（最小安装）

npm install a2a-ai-chat-sdk vue@^3.2.41 element-plus@^2.6.0 pinia@^2.1.7 axios@^1.6.7 js-cookie@^3.0.5 @microsoft/fetch-event-source@^2.0.1

包含移动端 UI

npm install a2a-ai-chat-sdk vue@^3.2.41 element-plus@^2.6.0 pinia@^2.1.7 vue-router@^4.6.3 axios@^1.6.7 js-cookie@^3.0.5 @microsoft/fetch-event-source@^2.0.1 vant@3.6.6

包含 Markdown 支持

npm install a2a-ai-chat-sdk vue@^3.2.41 element-plus@^2.6.0 pinia@^2.1.7 vue-router@^4.6.3 axios@^1.6.7 js-cookie@^3.0.5 @microsoft/fetch-event-source@^2.0.1 markdown-it@^14.0.0 markdown-it-katex@^2.0.3 marked@^11.0.0 highlight.js@^11.9.0 dompurify@^3.0.11

📋 完整依赖列表

SDK 使用 peer dependencies 模式，以下为完整的依赖列表：

⚠️ 安装注意事项

1. 版本要求：请确保安装的依赖版本符合上表要求，版本不匹配可能导致功能异常
2. 已安装依赖：如果项目中已安装部分依赖，npm 会自动检测并使用现有版本（如果版本兼容）
3. 版本兼容：部分依赖允许使用较新版本（如 marked@^17.0.0），但建议使用推荐版本以确保最佳兼容性
4. 包管理器：支持 npm、yarn、pnpm，选择你项目使用的包管理器即可

🎨 配置

1. 引入样式文件

// 引入 Element Plus 样式
import 'element-plus/dist/index.css'

// 引入 Vant 样式
import 'vant/lib/index.css'

// 引入 SDK 样式
import 'a2a-ai-chat-sdk/dist/style.css'

2. 初始化 Vue 应用

import { createApp } from 'vue'
import { createPinia } from 'pinia'
import ElementPlus from 'element-plus'
import Vant from 'vant'

const app = createApp(App)
app.use(createPinia())
app.use(ElementPlus)
app.use(Vant)
app.mount('#app')

🚀 快速开始

方式一：使用ChatBox组件（推荐）

<template>
  <div class="app">
    <!-- 外部自定义按钮 -->
    <div class="controls">
      <button @click="handleStop">停止</button>
      <button @click="handleRegenerate">重新生成</button>
      <button @click="handleNewChat">新对话</button>
    </div>

    <!-- SDK提供的聊天框（原版样式） -->
    <ChatBox :chat-instance="chatSDK" />
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { AIChat, ChatBox } from 'ai-chat-sdk';

const chatSDK = ref(null);

onMounted(async () => {
  // 创建SDK实例
  chatSDK.value = new AIChat({
    api: { baseURL: '/api' }
  });
  
  // 自动初始化（获取所有必要信息）
  await chatSDK.value.initialize();
});

// 所有功能SDK已实现，直接调用即可
async function handleStop() {
  await chatSDK.value.stopChat();
}

async function handleRegenerate() {
  await chatSDK.value.regenerateAnswer();
}

async function handleNewChat() {
  await chatSDK.value.createNewSession(); // 会自动刷新智能体列表
}
</script>

🎯 核心方法

初始化

// 自动获取：用户信息、clientToken、智能体列表、文件上传限制
const result = await chatSDK.initialize();

发送消息

await chatSDK.sendMessage({
  userInput: '你好',
  thinkDeep: true,           // 开启深度思考
  webBasedSearch: false,     // 关闭联网搜索
});

对话控制

// 停止当前对话
await chatSDK.stopChat();

// 重新生成回答（自动使用原始参数）
await chatSDK.regenerateAnswer();

// 新建对话（自动刷新智能体列表）
await chatSDK.createNewSession();

会话管理

// 获取会话列表
const sessions = await chatSDK.getSessionList();

// 加载历史会话（自动设置sessionId和消息列表）
await chatSDK.loadHistorySession(sessionId);

// 删除会话
await chatSDK.deleteSession(sessionId);

智能体管理

// 获取智能体列表
const agents = chatSDK.getAgentList();

// 获取当前智能体
const currentAgent = chatSDK.getCurrentAgent();

// 切换智能体（自动更新apikey和清空对话）
await chatSDK.switchAgent(agentId);

其他功能

// 复制消息
await chatSDK.copyMessage(content);

// 获取用户信息
const userInfo = chatSDK.getUserInfo();

// 获取上传限制
const uploadLimit = chatSDK.getUploadLimit();

// 上传文件
const result = await chatSDK.uploadFile(file);

// 消息反馈
await chatSDK.feedbackMessage({
  message_id: 'xxx',
  feedback_type: 'like'
});

📡 事件监听

// 监听消息更新
chatSDK.on('message', (data) => {
  console.log('消息更新:', data.message);
});

// 监听完成事件
chatSDK.on('complete', (data) => {
  console.log('对话完成');
});

// 监听新建会话
chatSDK.on('new-session', (data) => {
  console.log('新建会话:', data);
});

// 监听会话加载
chatSDK.on('session-loaded', (data) => {
  console.log('会话已加载:', data.sessionId);
});

// 监听智能体切换
chatSDK.on('agent-switched', (data) => {
  console.log('智能体已切换:', data.agentId);
});

// 监听复制成功
chatSDK.on('copy-success', (data) => {
  console.log('复制成功');
});

// 取消监听
chatSDK.off('message', listenerFn);

⚙️ 配置选项

const chatSDK = new AIChat({
  api: {
    baseURL: '/api',              // API基础URL
    a2aURL: '/api',               // A2A API URL
    timeout: 180000,              // 请求超时(ms)
  },
  auth: {
    apiKey: 'xxx',                // API密钥（可选，SDK会自动从Cookie读取）
    authToken: 'xxx',             // 认证Token（可选）
    clientToken: 'xxx',           // 客户端Token（可选）
  },
  defaults: {
    thinkDeep: false,             // 默认深度思考
    webBasedSearch: false,        // 默认联网搜索
    typingEffect: true,           // 打字机效果
    typingSpeed: 20,              // 打字速度(ms/字符)
  }
});

💡 完整示例

查看 test-project 目录获取完整的使用示例：

• App-custom-buttons.vue - 自定义按钮版本（推荐）
• App-with-component.vue - 完全内置UI版本

🎨 组件说明

ChatBox组件

• 包含：消息列表 + 输入框
• 样式：完全还原原版UI
• 特点：开箱即用，无需自己写样式

Props

Events

🔐 认证说明

SDK支持两种认证方式：

1. 自动从Cookie读取（推荐）

SDK会自动读取以下Cookie：

• authToken - 认证Token
• apikey - API密钥
• client_token - 客户端Token

const chatSDK = new AIChat({
  api: { baseURL: '/api' }
  // 不需要配置auth，SDK会自动读取Cookie
});

2. 手动配置

const chatSDK = new AIChat({
  api: { baseURL: '/api' },
  auth: {
    apiKey: 'your-api-key',
    authToken: 'your-auth-token'
  }
});

🆚 与原版对比

📚 文档

• SDK使用指南.md - 完整的API文档
• SDK完整功能清单.md - 功能详细说明
• test-project/README.md - 测试项目说明

🧪 本地开发

# 安装依赖
npm install

# 启动测试项目
cd test-project
npm install
npm run dev

📝 构建发布

# 构建SDK
npm run build:lib

# 发布到npm
npm publish

💡 核心优势

真正的零实现

用户完全不需要：

• ❌ 自己调用API
• ❌ 管理状态
• ❌ 处理SSE
• ❌ 保存参数
• ❌ 实现业务逻辑
• ❌ 写样式

所有功能SDK内部完成

• ✅ 自动初始化
• ✅ 自动刷新智能体列表
• ✅ 自动保存重发参数
• ✅ 自动管理session
• ✅ 自动处理事件

📄 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！