# AaaS Pilot Kit

>  🤖 开箱即用的数字员工基础套件: 无缝串联 AI Agent、ASR 与数字人渲染服务，全链路可观测、关键点位可追踪， 打造真正流畅自然的数字员工体验。

原生 JavaScript SDK，无任何框架依赖，可在任何前端项目中使用。提供完整的 TypeScript 类型支持。

## 📚 文档与资源

- 📖 **完整文档**: [aaas-pilot-kit-docs.cloud.baidu.com](https://aaas-pilot-kit-docs.cloud.baidu.com)
- 🔗 **API 参考**: 详细的 API 文档和配置选项
- 💡 **示例代码**: 更多使用场景和集成案例
- 📝 **更新日志**: 查看版本更新和变更记录

## 📦 安装

```bash
# npm
npm install @bdky/aaas-pilot-kit

# yarn
yarn add @bdky/aaas-pilot-kit

# pnpm
pnpm add @bdky/aaas-pilot-kit
```

## 🚀 快速开始

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

// 初始化 SDK
const controller = createAaaSPilotKit({
    figureId: '209337',                    // 数字人 ID
    ttsPer: 'LITE_audiobook_female_1',     // 语音音色
    agentConfig: {
        token: 'your-token',               // Agent Token
        robotId: 'your-robot-id'           // 机器人 ID
    }
});

// 监听就绪事件
controller.emitter.on('ready', () => {
    console.log('SDK 已就绪');
    controller.playFromFullText('您好，我是智能助手，有什么可以帮您？');
});

// 监听对话消息
controller.emitter.on('conversation_add', (conversation) => {
    console.log('新消息:', conversation.text);
});

// 挂载到 DOM
await controller.mount(document.getElementById('container'));
```

## 📖 核心 API

### 初始化配置

```typescript
interface IOptions {
    figureId: string;           // 数字人 ID
    ttsPer: string;            // TTS 音色
    agentConfig?: {
        token?: string;        // Agent Token
        robotId?: string;      // 机器人 ID
    };
    agentService?: typeof CustomAgentService; // 自定义 Agent
    // ... 更多配置选项
}

// ⚠️ 未提供 agentService 时，需配置 agentConfig（token 或 robotId）。
// ✅ 已提供 agentService 时，可省略 agentConfig，由自定义服务接管对话流程。
```

### 控制器方法

```typescript
// 挂载到 DOM
await controller.mount(element: HTMLElement);

// 文本输入（触发对话）
controller.input(text: string);

// 播放文本（TTS）
controller.playFromFullText(text: string);

// 检查是否需要手动激活
controller.checkNeedsManualActivation(): boolean;

// 手动激活（处理浏览器自动播放限制）
controller.activateManually(): void;

// 销毁实例
controller.dispose(): void;
```

### 事件监听

```typescript
// SDK 就绪
controller.emitter.on('ready', () => {});

// 新对话消息
controller.emitter.on('conversation_add', (conversation) => {});

// 错误事件
controller.emitter.on('error', (error) => {});

// ASR 识别结果
controller.emitter.on('asr_result', (result) => {});
```

## 💡 最佳实践

### 1. 等待 Ready 事件

在执行任何操作前，务必等待 `ready` 事件：

```typescript
controller.emitter.on('ready', () => {
    // ✅ 在这里安全地开始交互
    controller.input('开始对话');
});
```

### 2. 处理浏览器自动播放限制

某些浏览器（尤其是移动端）会限制自动播放，需要手动激活：

```typescript
let isReady = false;

controller.emitter.on('ready', () => {
    isReady = true;
});

// 在用户交互（如点击）后激活
button.addEventListener('click', () => {
    if (isReady && controller.checkNeedsManualActivation()) {
        controller.activateManually();
    }
});
```

> ⚠️ **iOS 微信环境**: 必须在用户交互后调用 `activateManually()` 才能正常播放音频和渲染数字人。

### 3. 错误处理

建议监听错误事件并进行适当处理：

```typescript
controller.emitter.on('error', (error) => {
    console.error('SDK 错误:', error);
    // 上报错误、显示提示等
});
```

### 4. 资源清理

组件销毁时务必清理资源：

```typescript
// 原生 JS
window.addEventListener('beforeunload', () => {
    controller.dispose();
});

// React
useEffect(() => {
    return () => {
        controller.dispose();
    };
}, []);

// Vue
onUnmount(() => {
    controller.dispose();
});
```

## 🔧 TypeScript 支持

SDK 提供完整的 TypeScript 类型定义：

```typescript
import type {
    IAaaSPilotKitController,
    IAaaSPilotKitEmitter,
    IOptions,
    IConversation
} from '@bdky/aaas-pilot-kit';

// 类型安全的配置
const options: IOptions = {
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    agentConfig: {
        token: 'your-token'
    }
};

// 类型化的事件回调
controller.emitter.on('conversation_add', (conversation: IConversation) => {
    console.log(conversation.id, conversation.text, conversation.type);
});
```

## 📦 相关包

- **React 版本**: [@bdky/aaas-pilot-kit-react](https://npmjs.com/package/@bdky/aaas-pilot-kit-react) - React Hooks 封装
- **Vue3 版本**: [@bdky/aaas-pilot-kit-vue3](https://npmjs.com/package/@bdky/aaas-pilot-kit-vue3) - Vue3 Composition API 封装


## ❓ 帮助与支持

遇到问题或有建议？欢迎通过以下方式联系我们：

- 📧 [发送邮件至维护团队](https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/faq#%E6%9B%B4%E5%A4%9A%E5%B8%AE%E5%8A%A9)
- 📖 查看[常见问题文档](https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/faq)


<p align="center">
  Made with ❤️ by 百度智能云客悦 Ky-FE Team
</p>
