API 参考

AaaS Pilot Kit 提供的完整 API 方法参考。

初始化方法

`createAaaSPilotKit(options: IOptions): IAaaSPilotKitController`

创建 AaaS Pilot Kit 控制器实例。

import {createAaaSPilotKit} from '@bdky/aaas-pilot-kit';

const controller = createAaaSPilotKit({
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // agentConfig: 若未提供自定义 agentService,此配置必填
    agentConfig: {
        token: 'xxxx',
        robotId: 'xxxx'
    }
});

实例方法（IAaaSPilotKitController）

`mount($container?: HTMLElement): Promise<void>`

🧩 挂载数字员工到指定 DOM 容器。

行为:

若传入 $container → 直接挂载
若未传 → 调用 opts.getMountContainer()
二者都没有 → 抛错 ❌

异步: 等待资源加载/容器初始化完成，同时获取 Microphone 麦克风权限。

参数:

$container - 可选，要挂载的 DOM 节点

抛出异常: 如果未传 $container 且 opts.getMountContainer 未定义

// 直接挂载到指定容器
await controller.mount(document.getElementById('avatar-container'));

// 或者不传参数，使用配置中的 getMountContainer
await controller.mount();

`getOptions(): Required<IOptions>`

📋 获取当前生效的完整配置（含默认值）。

用于调试、日志记录、动态配置比对。

返回: 合并默认值后的完整配置对象

const currentOptions = controller.getOptions();
console.log('当前配置:', currentOptions);

`playFromFullText(fullText: string): IAaaSPilotKitController`

🎬 【非流式】整段文本驱动播报 - 适合预生成回复、公告播报。

行为:

立即开始 TTS 合成 + 数字人播报
支持中途打断（若 interruptible=true）

参数:

fullText - 要播报的完整文本

返回: this（支持链式调用）

controller.playFromFullText('欢迎使用AaaS Pilot Kit数字员工服务！');

`playFromStreamText(chunk: string): IAaaSPilotKitController`

🌊 【流式】分块文本驱动播报 - 适合大模型流式输出、实时对话。

行为:

每次传入一个文本块（chunk），实时拼接并播报
支持"首句切分"策略（见 opts.minSplitLen）
支持打断（若 interruptible=true）

示例: 配合 SSE / WebSocket 流式接收 Agent 回复

参数:

chunk - 新增的文本片段

返回: this（支持链式调用）

// 模拟流式文本
controller.playFromStreamText('今天');
controller.playFromStreamText('天气');
controller.playFromStreamText('很好。');

`playWaitFor(text: string, shouldStillPlay?: () => boolean): Promise<boolean>`

⏳ 等待当前播报完成后再播报新内容（排队模式）。

用于插播"重要通知"等场景。

行为:

若正在播报 → 等待播完再播新内容
若未播报 → 立即播放
不触发打断逻辑（即使 interruptible=true）
可通过 shouldStillPlay 动态取消排队

参数:

text - 要播报的文本
shouldStillPlay - 可选，播报前检查是否仍需播放（返回 false 则取消）

返回: Promise<boolean> → true=已播放，false=被取消

const played = await controller.playWaitFor('系统通知：即将进行维护');
if (played) {
    console.log('通知已播报');
}

`mute(muted: boolean): IAaaSPilotKitController`

🔇 静音控制 - 立即生效，不影响播报队列。

行为:

muted=true → 停止音频输出（画面口型仍同步）
muted=false → 恢复音频
触发 emitter 'mute' 事件

参数:

muted - 是否静音

返回: this（支持链式调用）

// 静音
controller.mute(true);

// 取消静音
controller.mute(false);

`interrupt(reason?: string): IAaaSPilotKitController`

🛑 手动打断当前对话流程。

行为:

停止音频采集
取消 Agent 请求
中断数字人播报
触发 'interrupt' 事件

通常由用户点击"打断按钮"或语音激活触发。

参数:

reason - 可选，打断原因（用于日志/埋点）

返回: this（支持链式调用）

// 用户点击打断按钮
controller.interrupt('用户手动打断');

`dispose(): IAaaSPilotKitController`

🗑️ 销毁实例 - 释放所有资源（RTC、音频、渲染、事件监听）。

⚠️ 调用后，此实例不可再使用！需重新调用 createAaaSPilotKit 执行创建。

返回: this（支持链式调用，但之后方法调用会报错）

// 组件卸载时清理资源
controller.dispose();

`input(text: string): IAaaSPilotKitController`

💬 手动输入文本（模拟用户语音输入）→ 触发完整对话流程。

行为:

跳过 ASR，直接将文本送入 Agent
后续流程与语音输入完全一致（Agent → TTS → 播报）

适用场景: 调试、无障碍输入、聊天框集成

参数:

text - 用户输入的文本

返回: this（支持链式调用）

// 模拟用户输入
controller.input('我想了解产品功能');

`setInterruptible(interruptible: boolean): IAaaSPilotKitController`

🔄 动态切换"是否允许打断" - 可在对话中随时调整，立即生效。

参数:

interruptible - 是否允许打断

返回: this（支持链式调用）

// 重要播报时禁止打断
controller.setInterruptible(false);
controller.playFromFullText('重要通知：系统将在5分钟后维护');

// 播报完成后恢复打断功能
controller.setInterruptible(true);

`checkNeedsManualActivation(): boolean`

🚦 检测是否需要"手动激活"（如浏览器策略阻止自动播放）。

返回 true 时，必须调用 activateManually() 用户交互后才能播放音频。

常见于移动端/静音浏览器首次播放。

返回: boolean - 是否需要手动激活

if (controller.checkNeedsManualActivation()) {
    showActivationButton();
}

`activateManually(): Promise<void>`

✅ 手动激活音频上下文（解决浏览器自动播放策略限制）。

🔹 必须在用户手势事件（click/touch）中调用！

例如：用户点击"开始对话"按钮时调用。

异步: 等待数字员工形象视频流、音频流上下文恢复成功。

抛出异常: 如果不在用户手势中调用，可能激活失败

// 在用户点击事件中激活
activateButton.onclick = async () => {
    try {
        await controller.activateManually();
        hideActivationButton();
        console.log('音频已激活');
    } catch (error) {
        console.error('激活失败:', error);
    }
};

`checkAudioDevice(): Promise<void>`

🎙️ 检测麦克风设备可用性 - 执行 4 层渐进式检测（API 支持 → HTTPS → 设备枚举 → 权限 → 流获取）。

方法签名: async checkAudioDevice(): Promise<void>

返回值:

返回 Promise<void>
检测结果通过 microphone_available 事件发送

使用场景:

在用户点击"开始对话"前主动检测设备状态
在 ASR 启动失败后进行诊断
定期检查设备连接状态（例如用户插拔耳机时）

检测层级:

API 支持检测 - 浏览器是否支持 MediaDevices API
HTTPS 检测 - 是否在安全上下文（HTTPS 或 localhost）
设备枚举 - 是否能列出音频输入设备
权限检测 - 用户是否授予麦克风权限
流获取 - 是否能成功获取音频流

性能提示:

首次检测耗时 ~100-500ms（主要是 getUserMedia）
5 秒内缓存结果，重复调用 <1ms（避免频繁权限弹窗）

示例代码:

// 基础用法：监听检测结果
controller.emitter.on('microphone_available', (result) => {
  if (!result.available) {
    // 显示友好的错误提示
    alert(result.userMessage);
  } else {
    console.log('设备正常，找到', result.devices?.length, '个麦克风');
  }
});

// 执行检测
await controller.checkAudioDevice();

// 在"开始对话"前主动检测
startButton.onclick = async () => {
  // 先检测设备
  await controller.checkAudioDevice();

  // microphone_available 事件会在这里触发
  // 如果设备不可用，事件监听器会显示错误提示
};

// 监听检测结果
controller.emitter.on('microphone_available', (result) => {
  if (result.available) {
    // 设备可用，允许继续操作
    enableVoiceButton();
  } else {
    // 设备不可用，禁用语音功能
    disableVoiceButton();
    showToast(result.userMessage);
  }
});

// 高级用法：根据错误类型提供具体解决方案
controller.emitter.on('microphone_available', (result) => {
  if (!result.available) {
    switch (result.error) {
      case 'PERMISSION_DENIED':
        showPermissionGuide();
        break;
      case 'HTTPS_REQUIRED':
        showHTTPSWarning();
        break;
      case 'DEVICE_NOT_READABLE':
        showDeviceBusyWarning();
        break;
      default:
        alert(result.userMessage);
    }
  }
});

await controller.checkAudioDevice();

错误类型说明: 参见 FAQ - 错误代码表中的 3100-3105 错误码

相关事件: microphone_available - 接收检测结果

相关配置: checkAudioDeviceBeforeStart - ASR 启动前自动检测

`keepAlive(): IAaaSPilotKitController`

🕰️ 重置会话超时计时器 - "我还在用，别退出！"

行为:

重新从 0 开始计时 opts.timeoutSec
延迟触发超时事件（inactivity）

适用场景: 用户正在浏览页面、打字、填表单时调用

返回: this（支持链式调用）

// 用户有活动时保持会话
document.addEventListener('mousedown', () => {
    controller.keepAlive();
});

document.addEventListener('keydown', () => {
    controller.keepAlive();
});

链式调用示例

// 支持链式调用
controller
    .setInterruptible(false)
    .playFromFullText('欢迎使用我们的服务')
    .keepAlive();

异常处理

try {
    await controller.mount(containerElement);
    controller.playFromFullText('初始化成功');
} 
catch (e) {
    console.error('初始化失败:', e);
    // 处理错误
}

初始化方法​

createAaaSPilotKit(options: IOptions): IAaaSPilotKitController​

实例方法（IAaaSPilotKitController）​

mount($container?: HTMLElement): Promise<void>​

getOptions(): Required<IOptions>​

playFromFullText(fullText: string): IAaaSPilotKitController​

playFromStreamText(chunk: string): IAaaSPilotKitController​

playWaitFor(text: string, shouldStillPlay?: () => boolean): Promise<boolean>​

mute(muted: boolean): IAaaSPilotKitController​

interrupt(reason?: string): IAaaSPilotKitController​

dispose(): IAaaSPilotKitController​

input(text: string): IAaaSPilotKitController​

setInterruptible(interruptible: boolean): IAaaSPilotKitController​

checkNeedsManualActivation(): boolean​

activateManually(): Promise<void>​

checkAudioDevice(): Promise<void>​

keepAlive(): IAaaSPilotKitController​

链式调用示例​

异常处理​

初始化方法

`createAaaSPilotKit(options: IOptions): IAaaSPilotKitController`

实例方法（IAaaSPilotKitController）

`mount($container?: HTMLElement): Promise<void>`

`getOptions(): Required<IOptions>`

`playFromFullText(fullText: string): IAaaSPilotKitController`

`playFromStreamText(chunk: string): IAaaSPilotKitController`

`playWaitFor(text: string, shouldStillPlay?: () => boolean): Promise<boolean>`

`mute(muted: boolean): IAaaSPilotKitController`

`interrupt(reason?: string): IAaaSPilotKitController`

`dispose(): IAaaSPilotKitController`

`input(text: string): IAaaSPilotKitController`

`setInterruptible(interruptible: boolean): IAaaSPilotKitController`

`checkNeedsManualActivation(): boolean`

`activateManually(): Promise<void>`

`checkAudioDevice(): Promise<void>`

`keepAlive(): IAaaSPilotKitController`

链式调用示例

异常处理