坐席辅助SDK (Agent Assistant SDK)

一个用于坐席辅助功能的JavaScript SDK，支持音频协商和SSE连接功能。

功能特性

• 音频协商 API
• SSE (Server-Sent Events) 连接
• 自动认证头生成
• 模块化设计，支持多种环境
• 增强的消息和错误类型识别
• 坐席辅助弹窗功能（80vw x 80vh 弹窗，支持用户肖像、信息提取、思路导航、话术推荐和语音转文字显示）

安装

npm install @xinyao/agent-assistant-sdk
# 或
pnpm add @xinyao/agent-assistant-sdk

使用方法

ES6 模块

import AgentAssistantSDK from '@xinyao/agent-assistant-sdk';

const vm = new AgentAssistantSDK({
  // 配置项...
});

CommonJS

// 在支持ES模块的环境中（当package.json包含"type": "module"时）
import AgentAssistantSDK from '@xinyao/agent-assistant-sdk/dist/agent-assistant-sdk.js';

// 或者使用动态导入
const { default: AgentAssistantSDK } = await import('@xinyao/agent-assistant-sdk/dist/agent-assistant-sdk.js');

import AgentAssistantSDK from '@xinyao/agent-assistant-sdk';

const vm = new AgentAssistantSDK({
  url: 'https://dev.xinyaoai.com',
  app_key: 'your_app_key',
  app_secret: 'your_app_secret',
  onMessage: (message) => {
    console.log('收到消息:', message);
    switch(message.type) {
      case 'sse_message':
        console.log('SSE消息内容:', message.data);
        break;
      default:
        console.log('未知类型消息:', message);
    }
  },
  onError: (error) => {
    console.log('发生错误:', error);
    switch(error.type) {
      case 'sse_error':
        console.log('SSE连接错误:', error.error);
        break;
      case 'http_error':
        console.log('HTTP请求错误:', error.error.message, '状态码:', error.status);
        break;
      case 'connection_error':
        console.log('连接错误:', error.error.message);
        break;
      default:
        console.log('未知类型错误:', error);
    }
  },
  onOpen: () => {
    console.log('SSE连接已建立');
  },
  onAudioData: (audioData) => {
    console.log('收到音频数据:', audioData);
  }
});

CommonJS

const AgentAssistantSDK = require('@xinyao/agent-assistant-sdk');

const vm = new AgentAssistantSDK({
  // 配置项...
});

浏览器中使用

<script src="https://unpkg.com/@xinyao/agent-assistant-sdk/dist/agent-assistant-sdk.umd.js"></script>
<script>
  const vm = new AgentAssistantSDK({
    // 配置项...
  });
</script>

注意：在UMD构建中，构造函数直接导出为AgentAssistantSDK，不需要使用.default属性。

API

构造函数选项

• url: API服务器地址
• app_key: 应用密钥
• app_secret: 应用密钥
• onMessage: 服务器消息回调，现在包含type、data和timestamp字段
• onError: 错误回调，现在包含type、error和timestamp字段
• onOpen: 连接建立回调
• onAudioData: 音频数据回调
• onAudioNegotiationSuccess: 音频协商成功回调
• onConnectSSE: 连接SSE回调

消息和错误类型

onMessage 消息类型

• sse_message: 来自SSE连接的消息，包含以下字段：
  • type: 'sse_message'
  • data: 原始消息数据
  • timestamp: 时间戳

onError 错误类型

• sse_error: SSE连接错误，包含以下字段：
  • type: 'sse_error'
  • error: 错误对象
  • timestamp: 时间戳
• http_error: HTTP请求错误，包含以下字段：
  • type: 'http_error'
  • error: 错误对象
  • status: HTTP状态码
  • timestamp: 时间戳
• connection_error: 连接错误，包含以下字段：
  • type: 'connection_error'
  • error: 错误对象
  • timestamp: 时间戳

新增功能：坐席辅助弹窗

坐席辅助弹窗提供了一个可视化界面，分为左、中、右三个区域：

• 左侧区域：

  • 左上：用户肖像 - 显示用户相关信息
  • 左下：信息提取 - 显示从对话中提取的关键信息

• 中间区域：

  • 中上：思路导航 - 显示对话思路引导
  • 中下：话术推荐 - 显示推荐的话术

• 右侧区域：语音转文字 - 实时显示语音转文字的内容，区分用户和坐席

弹窗支持展开/收起功能，默认显示为80vw x 80vh大小，收起时在右下角显示一个小按钮。

createSeatAssistantPopup(container)

创建坐席辅助弹窗。

参数:

• container (HTMLElement): 弹窗容器元素

返回值:

• SeatAssistantPopup 实例

toggleSeatAssistantPopup()

切换坐席辅助弹窗的显示/隐藏状态。

handleSseMessageForPopup(data)

处理SSE消息并更新坐席辅助弹窗的显示内容。

参数:

• data (object): SSE消息数据

方法

post(endpoint, data)

通用POST请求方法，可用于向指定端点发送数据。

参数:

• endpoint (string): API端点路径
• data (object): 要发送的数据

audioNegotiation(data)

执行音频协商请求（内部使用post方法）。 现在会在 onAudioNegotiationSuccess 回调中返回带有类型的对象，包含：

• type: 'audio_negotiation_success'
• data: 协商结果数据
• timestamp: 时间戳

connectSSEWithNegotiationResult()

根据音频协商结果连接SSE。此方法需要在音频协商成功后手动调用，会使用协商结果中的sse_addr和client_id来建立SSE连接。

connectSSEWithURL(sseUrl)

使用指定URL连接SSE（辅助方法）。

参数:

• sseUrl (string): SSE连接的完整URL

参数:

• data (object):
  • app_id (string, required): 租户ID
  • audio_format (string, required): 音频格式
  • audio_sample (string, required): 音频采样率 (8k/16k)
  • user_agent (string, required): 客户端标识

connectSSE()

建立SSE连接。注意：SDK会自动在请求头中添加认证信息。

disconnectSSE()

断开SSE连接。

认证

SDK会自动在每个请求中添加认证头，格式为: Authorization: {app_key}:{timestamp}:{md5(app_secret:timestamp)}

开发

# 安装依赖
pnpm install

# 构建
pnpm run build

# 开发模式（监听文件变化）
pnpm run dev

# 运行测试
pnpm run test

项目使用 Vite 进行构建，支持多格式输出 (ESM, CJS, UDM)。

发布到npm

npm publish