@bdky/aaas-pilot-kit 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/README.md +222 -0
  2. package/dist/http.cjs.js +2 -0
  3. package/dist/http.cjs.js.LICENSE.txt +1 -0
  4. package/dist/http.esm.js +2 -0
  5. package/dist/http.esm.js.LICENSE.txt +1 -0
  6. package/dist/http.umd.js +2 -0
  7. package/dist/http.umd.js.LICENSE.txt +1 -0
  8. package/dist/index.cjs.js +44 -0
  9. package/dist/index.cjs.js.LICENSE.txt +45 -0
  10. package/dist/index.esm.js +44 -0
  11. package/dist/index.esm.js.LICENSE.txt +45 -0
  12. package/dist/index.umd.js +44 -0
  13. package/dist/index.umd.js.LICENSE.txt +45 -0
  14. package/dist/ky-aaas-pilot-kit.umd.js +44 -0
  15. package/dist/ky-aaas-pilot-kit.umd.js.LICENSE.txt +45 -0
  16. package/dist/libs/aaas-pilot-kit/src/http.d.ts +4 -0
  17. package/dist/libs/aaas-pilot-kit/src/index.d.ts +5 -0
  18. package/dist/libs/aaas-pilot-kit/src/lib/DI/types.d.ts +12 -0
  19. package/dist/libs/aaas-pilot-kit/src/lib/aaas-pilot-kit.d.ts +5 -0
  20. package/dist/libs/aaas-pilot-kit/src/lib/api/request.d.ts +9 -0
  21. package/dist/libs/aaas-pilot-kit/src/lib/constants/env.d.ts +1 -0
  22. package/dist/libs/aaas-pilot-kit/src/lib/controller.d.ts +107 -0
  23. package/dist/libs/aaas-pilot-kit/src/lib/error/BaseError.d.ts +12 -0
  24. package/dist/libs/aaas-pilot-kit/src/lib/error/ErrorEmitter.d.ts +54 -0
  25. package/dist/libs/aaas-pilot-kit/src/lib/error/ErrorHandler.d.ts +17 -0
  26. package/dist/libs/aaas-pilot-kit/src/lib/error/ErrorManager.d.ts +34 -0
  27. package/dist/libs/aaas-pilot-kit/src/lib/error/codes.d.ts +57 -0
  28. package/dist/libs/aaas-pilot-kit/src/lib/error/index.d.ts +16 -0
  29. package/dist/libs/aaas-pilot-kit/src/lib/error/monitoring/MonitoringError.d.ts +46 -0
  30. package/dist/libs/aaas-pilot-kit/src/lib/error/reporters/ConsoleReporter.d.ts +4 -0
  31. package/dist/libs/aaas-pilot-kit/src/lib/error/reporters/HttpReporter.d.ts +16 -0
  32. package/dist/libs/aaas-pilot-kit/src/lib/error/reporters/index.d.ts +2 -0
  33. package/dist/libs/aaas-pilot-kit/src/lib/error/services/AgentError.d.ts +17 -0
  34. package/dist/libs/aaas-pilot-kit/src/lib/error/services/AsrError.d.ts +23 -0
  35. package/dist/libs/aaas-pilot-kit/src/lib/error/services/ConversationError.d.ts +23 -0
  36. package/dist/libs/aaas-pilot-kit/src/lib/error/services/DigitalHumanError.d.ts +32 -0
  37. package/dist/libs/aaas-pilot-kit/src/lib/error/services/index.d.ts +4 -0
  38. package/dist/libs/aaas-pilot-kit/src/lib/error/types.d.ts +41 -0
  39. package/dist/libs/aaas-pilot-kit/src/lib/error/utils/ErrorUtils.d.ts +7 -0
  40. package/dist/libs/aaas-pilot-kit/src/lib/service/agent/aiobAgentService.d.ts +69 -0
  41. package/dist/libs/aaas-pilot-kit/src/lib/service/agent/baseAgentService.d.ts +65 -0
  42. package/dist/libs/aaas-pilot-kit/src/lib/service/agent/cspAgentService.d.ts +90 -0
  43. package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/aiWorkerConversationBean.d.ts +39 -0
  44. package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/clientConversationBean.d.ts +25 -0
  45. package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/content/ImageContent.d.ts +25 -0
  46. package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/content/MultimodalContent.d.ts +42 -0
  47. package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/content/TextContent.d.ts +41 -0
  48. package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/content/VideoContent.d.ts +26 -0
  49. package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/content/index.d.ts +8 -0
  50. package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/conversationBean.d.ts +25 -0
  51. package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/conversationService.d.ts +36 -0
  52. package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/index.d.ts +4 -0
  53. package/dist/libs/aaas-pilot-kit/src/lib/service/digital-human/BaseDigitalHumanService.d.ts +62 -0
  54. package/dist/libs/aaas-pilot-kit/src/lib/service/digital-human/CloudDigitalHumanService.d.ts +102 -0
  55. package/dist/libs/aaas-pilot-kit/src/lib/service/digital-human/PictureClientDigitalHumanService.d.ts +85 -0
  56. package/dist/libs/aaas-pilot-kit/src/lib/service/digital-human/interface.d.ts +100 -0
  57. package/dist/libs/aaas-pilot-kit/src/lib/service/rtc-asr/asr/baseAsrService.d.ts +82 -0
  58. package/dist/libs/aaas-pilot-kit/src/lib/service/rtc-asr/asr/brtcAsrService.d.ts +38 -0
  59. package/dist/libs/aaas-pilot-kit/src/lib/service/rtc-asr/signal/base.d.ts +19 -0
  60. package/dist/libs/aaas-pilot-kit/src/lib/service/rtc-asr/signal/brtc.d.ts +69 -0
  61. package/dist/libs/aaas-pilot-kit/src/lib/utils/applyTextReplacements.d.ts +15 -0
  62. package/dist/libs/aaas-pilot-kit/src/lib/utils/customXmlParser.d.ts +46 -0
  63. package/dist/libs/aaas-pilot-kit/src/lib/utils/isEmptyObject.d.ts +14 -0
  64. package/dist/libs/aaas-pilot-kit/src/lib/utils/isPlainObject.d.ts +13 -0
  65. package/dist/libs/aaas-pilot-kit/src/lib/utils/noop.d.ts +1 -0
  66. package/dist/libs/aaas-pilot-kit/src/lib/utils/sleep.d.ts +1 -0
  67. package/dist/libs/aaas-pilot-kit/src/lib/utils/toQueryString.d.ts +1 -0
  68. package/dist/libs/aaas-pilot-kit/src/lib/utils/ua.d.ts +3 -0
  69. package/dist/libs/aaas-pilot-kit/src/samples/react/Route/index.d.ts +3 -0
  70. package/dist/libs/aaas-pilot-kit/src/samples/react/conversation.d.ts +2 -0
  71. package/dist/libs/aaas-pilot-kit/src/samples/react/index.d.ts +1 -0
  72. package/dist/libs/aaas-pilot-kit/src/test-setup.d.ts +1 -0
  73. package/dist/libs/aaas-pilot-kit/src/types/agent.d.ts +8 -0
  74. package/dist/libs/aaas-pilot-kit/src/types/common.d.ts +5 -0
  75. package/dist/libs/aaas-pilot-kit/src/types/config.d.ts +552 -0
  76. package/package.json +64 -0
@@ -0,0 +1,552 @@
1
+ import type { Newable } from 'inversify';
2
+ import type { AgentConfig } from './agent';
3
+ import type { Env } from './common';
4
+ import { BaseAgentService, NBaseAgentService } from '../lib/service/agent/baseAgentService';
5
+ import type { ReplacementRule } from '../lib/utils/applyTextReplacements';
6
+ import { NPictureClientDigitalHumanService } from '../lib/service/digital-human/PictureClientDigitalHumanService';
7
+ import Emittery from 'emittery';
8
+ import { AnyConversation, type IConversationBeanSnapshot } from '../lib/service/conversation';
9
+ import type { IErrorEventPayload } from '../lib/error';
10
+ import { NAbstractDigitalHumanService } from '../lib/service/digital-human/BaseDigitalHumanService';
11
+ import { IAsrMessageEventPayload, IBusyEventPayload, IInterruptEventPayload } from '../lib/controller';
12
+ import { NDigitalHumanService } from '../lib/service/digital-human/CloudDigitalHumanService';
13
+ type TFormatter = (input: string) => string;
14
+ export interface IOptions<AS extends BaseAgentService = BaseAgentService> {
15
+ /**
16
+ * 🆔【必填】数字员工形象 ID —— 从平台获取的唯一形象资源标识
17
+ * 示例:"209337", "209342"
18
+ * 选型:https://cloud.baidu.com/doc/AI_DH/s/2lyzilgsg 可到此网址申请
19
+ */
20
+ figureId: string;
21
+ /**
22
+ * 🎙️【必填】数字员工音色 ID —— 对应 TTS 引擎的发音人标识
23
+ * 示例:"LITE_audiobook_female_1", "LITE_badao_shaoye"
24
+ * 选型:https://cloud.baidu.com/doc/AI_DH/s/Slywt3fxy 可到此网址申请
25
+ */
26
+ ttsPer: string;
27
+ /**
28
+ * 🔑【必填】数字员工鉴权 Token
29
+ * 用于调用数字员工服务的身份认证凭证
30
+ * 📌 获取方式:联系平台管理员或通过 API 申请
31
+ */
32
+ token: string;
33
+ /**
34
+ * 📊【选填】TTS 音频采样率(Hz),影响音质与带宽
35
+ * ✅ 推荐值:
36
+ * - 16000(16k,默认,平衡音质与性能)
37
+ * - 24000(24k,高保真场景)
38
+ * - 8000(8k,低带宽/嵌入式设备)
39
+ */
40
+ ttsSample?: number;
41
+ /**
42
+ * 🖥️【选填】渲染模式:云端推流 or 本地2D渲染
43
+ * - 'cloud'(默认)→ 高保真动态形象,需网络 + RTC 支持(推荐)
44
+ * - 'client' → 本地静态图+口型动画 2D 渲染,低资源消耗,离线可用
45
+ */
46
+ rendererMode?: 'cloud' | 'client';
47
+ /**
48
+ * 🖼️【选填】仅 rendererMode='client' 时生效 —— 配置本地渲染参数
49
+ * 包含形象资源路径、口型映射、TTS 驱动参数等
50
+ */
51
+ clientRendererConfig?: {
52
+ common: NPictureClientDigitalHumanService.IPictureClientProps;
53
+ tts: NPictureClientDigitalHumanService.ITtsConfig;
54
+ };
55
+ /**
56
+ * ⏱️【选填】会话全局超时时间(单位:秒)
57
+ * 超时后自动结束对话,释放资源
58
+ * ✅ 默认:60秒
59
+ */
60
+ timeoutSec?: number;
61
+ /**
62
+ * ⏰【选填】超时前提醒(单位:秒)
63
+ * 例:设为 10 → 超时前10秒播报“即将结束对话”
64
+ * ✅ 默认:10秒
65
+ */
66
+ disconnectAlertSec?: number;
67
+ /**
68
+ * 📐【选填】数字员工形象分辨率宽度(像素)
69
+ * 🔧 要求:
70
+ * - 必须为偶数
71
+ * - 最小 400,最大不超过 1920
72
+ * - 与 height 组合不能超过 1080x1920 或 1920x1080
73
+ * ⚠️ 过高分辨率可能导致性能下降
74
+ */
75
+ figureResolutionWidth?: number;
76
+ /**
77
+ * 📐【选填】数字员工形象分辨率高度(像素)
78
+ * 🔧 要求同 width
79
+ */
80
+ figureResolutionHeight?: number;
81
+ /**
82
+ * 🗣️【选填】播报语速(字/秒)
83
+ * ✅ 默认:6 字/秒(标准播音语速)
84
+ * 🎯 调整建议:
85
+ * - 教学/老人场景 → 4~5
86
+ * - 快节奏客服 → 7~8
87
+ */
88
+ speechSpeed?: number;
89
+ /**
90
+ *【选填】“打字机效果”中文字间隔(毫秒)
91
+ * 控制字幕逐字出现的动画节奏
92
+ * ✅ 默认:163(流畅自然),计算公式:1000ms/163 每秒输出约6个字
93
+ */
94
+ typeDelay?: number;
95
+ /**
96
+ * ⌨️【选填】英文字符打字机间隔(毫秒)
97
+ * ✅ 默认:45,如需英文更快/更慢可单独配置
98
+ */
99
+ enTypeDelay?: number;
100
+ /**
101
+ * TODO 大模型 API 相关配置 (现在区分外呼和客服,后续应该统一参数,不应该走 XOR 逻辑)
102
+ */
103
+ agentConfig: AgentConfig;
104
+ /**
105
+ * 📦【选填】挂载容器获取函数 —— 返回你要挂载数字员工形象的 DOM 节点
106
+ * 💡 若不传,需确保在调用 mount($container?: HTMLElement): Promise<void> 时传入,同时确保容器 DOM 已存在
107
+ */
108
+ getMountContainer?: () => HTMLElement;
109
+ /**
110
+ *【选填】是否允许用户打断当前播报(语音/手动输入均可触发)
111
+ * ✅ 默认:true(推荐开启,提升交互体验)
112
+ */
113
+ interruptible?: boolean;
114
+ /**
115
+ * 🎬【选填】开场白话术 —— 初始化后自动播报
116
+ * 示例:"您好,我是您的数字员工小悦,有什么可以帮您?"
117
+ */
118
+ prologue?: string;
119
+ /**
120
+ * 📏【选填】数字员工形象 X 轴缩放比例(默认 1.0)
121
+ * >1 放大,<1 缩小
122
+ */
123
+ scaleX?: number;
124
+ /**
125
+ * 📏【选填】数字员工形象 Y 轴缩放比例(默认 1.0)
126
+ */
127
+ scaleY?: number;
128
+ /**
129
+ * ↔️【选填】数字员工人物形象 x 方向 translate 像素值(正右负左)
130
+ */
131
+ translateX?: number;
132
+ /**
133
+ * ↕️【选填】数字员工人物形象 y 方向 translate 像素值(正下负上)
134
+ */
135
+ translateY?: number;
136
+ /**
137
+ * 🧩【选填】像素级位置与裁剪控制 —— 用于精准布局数字员工形象在最终画面中的显示区域
138
+ *
139
+ * 🔧 工作流程:
140
+ * 1️⃣ 先根据 `crop` 从原始人像底板中裁剪出“数字员工形象主体矩形区域”
141
+ * 2️⃣ 再根据 `location` 将裁剪后的区域缩放+定位到最终视频画布中
142
+ *
143
+ * 💡 适用场景:
144
+ * - 将数字员工形象嵌入到固定尺寸的“对话框”或“产品卡片”中
145
+ * - 对齐 UI 设计稿的像素级定位需求
146
+ * - 屏蔽背景干扰,只展示数字员工形象上半身/面部特写
147
+ *
148
+ * 📐 参数结构:
149
+ * {
150
+ * // 裁剪区域(基于原始底板)
151
+ * crop: { x: number, y: number, width: number, height: number }
152
+ * // 最终定位+缩放(基于输出画布)
153
+ * location: { x: number, y: number, width: number, height: number }
154
+ * }
155
+ *
156
+ * ⚠️ 注意:
157
+ * - 所有值均为**像素单位**,不支持百分比
158
+ * - `crop` 区域超出原始底板 → 自动 clamp 边界
159
+ * - `location` 超出画布 → 数字员工形象部分或全部不可见
160
+ * - 与 `scaleX/Y`、`translateX/Y` 不冲突,会叠加计算(先裁剪定位 → 再缩放平移)
161
+ *
162
+ * @example —— 居中显示数字员工形象上半身(原始底板 1920x1080,输出画布 800x600)
163
+ * {
164
+ * // 裁剪上半身
165
+ * crop: { x: 600, y: 0, width: 720, height: 540 },
166
+ * // 缩放后定位到左上区域
167
+ * location: { x: 40, y: 20, width: 720, height: 540 }
168
+ * }
169
+ */
170
+ position?: NDigitalHumanService.IPosition;
171
+ /**
172
+ * ✂️【选填】首句流式切分粒度(字数)
173
+ * “先攒够 N 个字,遇到标点就开播”,避免逐字卡顿
174
+ * ✅ 默认:5 → “今天天气不错。” → 攒到“不错。”开始播
175
+ */
176
+ minSplitLen?: number;
177
+ /**
178
+ * ⚡【选填】TTS 模型版本
179
+ * - undefined → 标准版(稳定,低延迟)
180
+ * - '02-turbo' → 加速版(响应更快,适合实时对话)
181
+ */
182
+ ttsModel?: '02-turbo' | undefined;
183
+ /**
184
+ * ASR 语音端点检测(VAD)的静音超时时长(单位:毫秒)
185
+ * —— 用于判断用户“说完一句话”的停顿阈值。
186
+ *
187
+ * 🎯 通俗理解:你停顿多久,系统就认为你说完了,开始识别。
188
+ * - 值越大 → 越“耐心”,适合语速慢/爱思考的用户;
189
+ * - 值越小 → 越“灵敏”,适合语速快/想快速响应的场景。
190
+ *
191
+ * ✅ 推荐值:
192
+ * - 默认 600ms(适合大多数对话场景)
193
+ * - 快速问答可设 300~400ms
194
+ * - 慢速/英文教学场景可设 800~1000ms
195
+ *
196
+ * ⚠️ 注意:过小可能导致话没说完就被打断,过大会让用户觉得“反应迟钝”。
197
+ */
198
+ asrVad?: number;
199
+ /**
200
+ * 🌐【选填】运行环境
201
+ * - 'development' → 开发调试(日志全开)
202
+ * - 'sandbox' → 沙箱测试(模拟生产)
203
+ * - 'production' → 生产环境(默认,性能最优)
204
+ */
205
+ env?: Env;
206
+ /**
207
+ * 🐞【选填】开启 Debug 模式 → 输出全链路日志(ASR/Agent/TTS/渲染)
208
+ * 开发调试时建议开启,生产环境需关闭
209
+ */
210
+ enableDebugMode?: boolean;
211
+ /**
212
+ * 🧩【选填】语音识别热词纠正规则(正则替换)
213
+ * 用于纠正 ASR 识别不准的专有名词、品牌词等
214
+ * 示例:
215
+ * { pattern: /客悦\s*one/gi, replacement: '客悦·ONE' }
216
+ * { pattern: /A I/g, replacement: 'AI' }
217
+ */
218
+ hotWordReplacementRules?: ReplacementRule[];
219
+ /**
220
+ * 语音文本输入格式处理
221
+ */
222
+ speechFormatters?: TFormatter[];
223
+ /**
224
+ * 消息内容格式处理
225
+ */
226
+ conversationFormatters?: TFormatter[];
227
+ /**
228
+ * 🧠【选填】自定义 Agent 服务类(需继承 BaseAgentService)
229
+ * 用于实现私有 Agent 流式 Api 协议对接,这个绑定后 agentConfig 配置将不可用
230
+ */
231
+ agentService?: Newable<AS>;
232
+ /**
233
+ * ⏸️【选填】长时间无交互提示语
234
+ * 用户沉默超时后,数字员工主动播报提醒
235
+ * 示例:"您还在吗?我可以继续为您服务~"
236
+ */
237
+ inactivityPrompt?: string;
238
+ /**
239
+ * 🟢【选填】是否自动开启绿幕抠像(仅 rendererMode='cloud' 时有效)
240
+ * ✅ 默认:true → 自动去除背景,融合进您的页面
241
+ * ❌ 设为 false → 保留原始背景(适合已有透明通道的素材)
242
+ */
243
+ autoChromaKey?: boolean;
244
+ }
245
+ export interface IAaaSPilotKitEmitter {
246
+ /**
247
+ * 🔇【状态事件】静音状态变更
248
+ * —— 当调用 .mute(true/false) 时触发
249
+ *
250
+ * 💡 适用场景:同步 UI 静音按钮状态
251
+ *
252
+ * @payload boolean - true=已静音,false=取消静音
253
+ */
254
+ mute: boolean;
255
+ /**
256
+ * 🚀【一次性】数字员工初始化完成,可安全调用其他 API
257
+ * —— 在数字员工形象加载完成、ASR初始化完成后触发
258
+ *
259
+ * 💡 最佳实践:在 'ready' 后再调用 playXXX / input 等方法,避免竞态
260
+ *
261
+ * @payload never - 无参数
262
+ */
263
+ ready: never;
264
+ /**
265
+ * 💬【高频】新增对话消息(用户 or AI)
266
+ * —— 每当有新对话内容产生时触发(ASR识别结果 / Agent回复)
267
+ *
268
+ * 💡 适用场景:聊天记录展示、日志记录、数据分析
269
+ *
270
+ * @payload AnyConversation - 包含角色(client/aiWorker)、内容、时间戳等
271
+ * @see IConversationBean
272
+ */
273
+ conversation_add: AnyConversation;
274
+ /**
275
+ * 📝【高频】当前对话片段状态更新(流式播报中)
276
+ * —— 用于实时更新“正在输入…”动画或打字机效果
277
+ *
278
+ * 💡 适用场景:UI 实时渲染流式回复、进度提示
279
+ *
280
+ * @payload { text: string; type: 'client'|'aiWorker'; id: string; completed: boolean }
281
+ * - completed=true 表示该片段播报结束(气泡完成渲染)
282
+ */
283
+ conversation_change: IConversationBeanSnapshot<'client' | 'aiWorker'> & {
284
+ completed: boolean;
285
+ };
286
+ /**
287
+ * ❌【必须监听】系统发生错误 —— 覆盖 ASR / Agent / TTS / 网络 / 渲染等全链路异常
288
+ *
289
+ * 🚨 生产环境务必监听并处理!建议上报监控系统 + 用户友好提示
290
+ *
291
+ * @payload IErrorEventPayload
292
+ * - code: 错误唯一标识,如 'ASR_TIMEOUT'、'AGENT_UNAUTHORIZED'
293
+ * - message: 人类可读错误描述,可用于日志或用户提示
294
+ * - stack?: 错误堆栈(开发环境建议保留,生产可选上报)
295
+ * - actionRequired: 用户或开发者需采取的操作,如 “请检查麦克风权限”、“稍后重试”
296
+ * - severity: 'low' | 'medium' | 'high' | 'critical' —— 用于告警分级
297
+ * - metadata: 错误上下文(时间、会话ID、用户ID、服务模块等,便于追踪)
298
+ * - originalError?: 原始 Error 对象(内部调试用,生产环境可忽略)
299
+ *
300
+ * 🎯 响应建议:
301
+ * - low/medium → 记录日志 + 局部提示
302
+ * - high/critical → 中断流程 + 弹窗提示 + 上报运维
303
+ */
304
+ error: IErrorEventPayload;
305
+ /**
306
+ * 🎙️ ASR 音频采集开始(用户开始说话)
307
+ * —— 通常在 VAD 检测到语音活动后触发
308
+ *
309
+ * 💡 适用场景:显示“正在听…”动画、启动打断检测
310
+ *
311
+ * @payload never - 无参数
312
+ */
313
+ asr_start: never;
314
+ /**
315
+ * 🎙️【高频流式】ASR 实时识别结果(逐句/逐词推送)
316
+ * —— 用户说话过程中持续触发,用于实现实时字幕、语音预览、热词高亮等
317
+ *
318
+ * 💡 触发时机:
319
+ * - 每当语音识别引擎输出一个“中间片段”或“最终句子”时触发
320
+ * - 由 VAD(语音活动检测)和语义断句策略共同驱动
321
+ *
322
+ * 🎯 使用场景:
323
+ * - 实时显示“用户正在说:xxx...”
324
+ * - 热词替换/敏感词标记(配合 opts.hotWordReplacementRules)
325
+ * - 打断检测(当 completed=false 但停顿过长,可预判打断)
326
+ *
327
+ * @payload IAsrMessageEventPayload
328
+ * - text: 当前识别出的文本片段(可能不完整)
329
+ * - completed: true=本句识别结束(可送入 Agent),false=仍在说话(中间结果)
330
+ * - id: 本条语音片段唯一标识(可用于去重或追踪)
331
+ * - sessionId: 当前会话 ID(用于多路对话隔离)
332
+ *
333
+ * ⚠️ 注意:
334
+ * - 中间结果(completed=false)可能被后续结果覆盖,勿直接用于业务逻辑
335
+ * - 只有 completed=true 的文本才应提交给 Agent 或记录到对话历史
336
+ *
337
+ * @example 中间识别:
338
+ * { text: "今天天气", completed: false, id: "asr_1", sessionId: "sess_abc" }
339
+ *
340
+ * @example 最终识别:
341
+ * { text: "今天天气真不错", completed: true, id: "asr_1", sessionId: "sess_abc" }
342
+ */
343
+ asr_message: IAsrMessageEventPayload;
344
+ instruction_received: NBaseAgentService.IInstructionReceivedEventPayload;
345
+ /**
346
+ * 🎬【高频】数字员工开始播报某段文本
347
+ * —— 每次开始播放一个句子/片段时触发
348
+ *
349
+ * 💡 适用场景:同步播报字幕、埋点统计播报内容
350
+ *
351
+ * @payload { text: string; sessionId: string; timestamp: number }
352
+ */
353
+ render_start: NAbstractDigitalHumanService.IEmitter['render_subtitle'] & NBaseAgentService.IEventWithSessionIdPayload;
354
+ /**
355
+ * ⏸️【低频】用户长时间无交互(触发 opts.inactivityPrompt)
356
+ * —— 在配置的不活跃时间后触发,数字人将播报提醒语
357
+ *
358
+ * 💡 适用场景:挽留用户、自动结束会话前提示
359
+ *
360
+ * @payload { requestId: string; }
361
+ */
362
+ inactivity: NAbstractDigitalHumanService.IEmitter['disconnect_alert'];
363
+ /**
364
+ * 🚧【低频】系统繁忙(资源达到上限)
365
+ * —— 数字人并发路数 / Agent QPS / RTC 带宽超限
366
+ *
367
+ * ⚠️ 需引导用户“稍后再试”或“联系客服”
368
+ */
369
+ busy: IBusyEventPayload;
370
+ /**
371
+ * 🛑 对话被打断(用户主动 or 系统触发)
372
+ * —— 调用 .interrupt() 或语音打断时触发
373
+ *
374
+ * 💡 适用场景:停止动画、清除输入框、重置状态
375
+ *
376
+ * @payload IInterruptEventPayload {
377
+ * requestId?: string;
378
+ * queryId?: string;
379
+ * sessionId?: string;
380
+ * }
381
+ */
382
+ interrupt: IInterruptEventPayload;
383
+ /**
384
+ * 🖼️【状态同步】数字员工渲染/播报状态变更 —— 实时反映是否“正在说话中”
385
+ *
386
+ * 💡 核心用途:
387
+ * - 控制 UI:显示“正在播报…”加载态、禁用发送按钮
388
+ * - 体验优化:避免用户在播报中途误操作导致体验割裂
389
+ * - ...
390
+ *
391
+ * @payload boolean
392
+ * - true → 数字人**正在渲染口型 + 播放语音**(播报中)
393
+ * - false → **播报完成,空闲可交互**(此时可安全输入或执行后续动作)
394
+ *
395
+ * ⚠️ 注意:
396
+ * - 此状态仅反映“数字员工是否在播报”,不反映 ASR 或 Agent 是否在工作
397
+ */
398
+ is_rendering_change: boolean;
399
+ }
400
+ export interface IAaaSPilotKitController {
401
+ emitter: Emittery<IAaaSPilotKitEmitter>;
402
+ /**
403
+ * 🧩 挂载数字员工到指定 DOM 容器
404
+ *
405
+ * 🔹 行为:
406
+ * - 若传入 $container → 直接挂载
407
+ * - 若未传 → 调用 opts.getMountContainer()
408
+ * - 二者都没有 → 抛错 ❌
409
+ *
410
+ * ⏳ 异步:等待资源加载/容器初始化完成,同时获取 Microphone 麦克风权限(在这步获取的原因是,前置预判有无权限,无权限则退出,有权限的话可以直接开启对话,节省时间)
411
+ *
412
+ * @param $container - 可选,要挂载的 DOM 节点
413
+ * @throws {Error} 如果未传 $container 且 opts.getMountContainer 未定义
414
+ */
415
+ mount($container?: HTMLElement): Promise<void>;
416
+ /**
417
+ * 📋 获取当前生效的完整配置(含默认值)
418
+ * —— 用于调试、日志记录、动态配置比对
419
+ *
420
+ * @returns 合并默认值后的完整配置对象
421
+ */
422
+ getOptions(): Required<IOptions>;
423
+ /**
424
+ * 🎬【非流式】整段文本驱动播报 —— 适合预生成回复、公告播报
425
+ *
426
+ * 🔹 行为:
427
+ * - 立即开始 TTS 合成 + 数字人播报
428
+ * - 支持中途打断(若 interruptible=true)
429
+ *
430
+ * @param fullText - 要播报的完整文本
431
+ * @returns this(支持链式调用)
432
+ */
433
+ playFromFullText(fullText: string): IAaaSPilotKitController;
434
+ /**
435
+ * 🌊【流式】分块文本驱动播报 —— 适合大模型流式输出、实时对话
436
+ *
437
+ * 🔹 行为:
438
+ * - 每次传入一个文本块(chunk),实时拼接并播报
439
+ * - 支持“首句切分”策略(见 opts.minSplitLen)
440
+ * - 支持打断(若 interruptible=true)
441
+ *
442
+ * 💡 示例:配合 SSE / WebSocket 流式接收 Agent 回复
443
+ *
444
+ * @param chunk - 新增的文本片段
445
+ * @returns this(支持链式调用)
446
+ */
447
+ playFromStreamText(chunk: string): IAaaSPilotKitController;
448
+ /**
449
+ * ⏳ 等待当前播报完成后再播报新内容(排队模式)
450
+ * —— 用于插播“重要通知”等场景
451
+ *
452
+ * 🔹 行为:
453
+ * - 若正在播报 → 等待播完再播新内容
454
+ * - 若未播报 → 立即播放
455
+ * - 不触发打断逻辑(即使 interruptible=true)
456
+ * - 可通过 shouldStillPlay 动态取消排队
457
+ *
458
+ * @param text - 要播报的文本
459
+ * @param shouldStillPlay - 可选,播报前检查是否仍需播放(返回 false 则取消)
460
+ * @returns Promise<boolean> → true=已播放,false=被取消
461
+ */
462
+ playWaitFor(text: string, shouldStillPlay?: () => boolean): Promise<boolean>;
463
+ /**
464
+ * 🔇 静音控制 —— 立即生效,不影响播报队列
465
+ *
466
+ * 🔹 行为:
467
+ * - muted=true → 停止音频输出(画面口型仍同步)
468
+ * - muted=false → 恢复音频
469
+ * - 触发 emitter 'mute' 事件
470
+ *
471
+ * @param muted - 是否静音
472
+ * @returns this(支持链式调用)
473
+ */
474
+ mute(muted: boolean): IAaaSPilotKitController;
475
+ /**
476
+ * 🛑 手动打断当前对话流程
477
+ *
478
+ * 🔹 行为:
479
+ * - 停止音频采集
480
+ * - 取消 Agent 请求
481
+ * - 中断数字人播报
482
+ * - 触发 'interrupt' 事件
483
+ *
484
+ * 💡 通常由用户点击“打断按钮”或语音激活触发
485
+ *
486
+ * @param reason - 可选,打断原因(用于日志/埋点)
487
+ * @returns this(支持链式调用)
488
+ */
489
+ interrupt(reason?: string): IAaaSPilotKitController;
490
+ /**
491
+ * 🗑️ 销毁实例 —— 释放所有资源(RTC、音频、渲染、事件监听)
492
+ *
493
+ * ⚠️ 调用后,此实例不可再使用!需重新调用 createAaaSPilotKit 执行创建
494
+ *
495
+ * @returns this(支持链式调用,但之后方法调用会报错)
496
+ */
497
+ dispose(): IAaaSPilotKitController;
498
+ /**
499
+ * 💬 手动输入文本(模拟用户语音输入)→ 触发完整对话流程
500
+ *
501
+ * 🔹 行为:
502
+ * - 跳过 ASR,直接将文本送入 Agent
503
+ * - 后续流程与语音输入完全一致(Agent → TTS → 播报)
504
+ *
505
+ * 💡 适用场景:调试、无障碍输入、聊天框集成
506
+ *
507
+ * @param text - 用户输入的文本
508
+ * @returns this(支持链式调用)
509
+ */
510
+ input(text: string): IAaaSPilotKitController;
511
+ /**
512
+ * 🔄 动态切换“是否允许打断”
513
+ * —— 可在对话中随时调整,立即生效
514
+ *
515
+ * @param interruptible - 是否允许打断
516
+ * @returns this(支持链式调用)
517
+ */
518
+ setInterruptible(interruptible: boolean): IAaaSPilotKitController;
519
+ /**
520
+ * 🚦 检测是否需要“手动激活”(如浏览器策略阻止自动播放)
521
+ *
522
+ * 🔹 返回 true 时,必须调用 activateManually() 用户交互后才能播放音频
523
+ * —— 常见于移动端/静音浏览器首次播放
524
+ *
525
+ * @returns boolean - 是否需要手动激活
526
+ */
527
+ checkNeedsManualActivation(): boolean;
528
+ /**
529
+ * ✅ 手动激活音频上下文(解决浏览器自动播放策略限制)
530
+ *
531
+ * 🔹 必须在用户手势事件(click/touch)中调用!
532
+ * —— 例如:用户点击“开始对话”按钮时调用
533
+ *
534
+ * ⏳ 异步:等待数字员工形象视频流、音频流上下文恢复成功
535
+ *
536
+ * @throws {Error} 如果不在用户手势中调用,可能激活失败
537
+ */
538
+ activateManually(): Promise<void>;
539
+ /**
540
+ * 🕰️ 重置会话超时计时器 —— “我还在用,别退出!”
541
+ *
542
+ * 🔹 行为:
543
+ * - 重新从 0 开始计时 opts.timeoutSec
544
+ * - 延迟触发超时事件(inactivity)
545
+ *
546
+ * 💡 适用场景:用户正在浏览页面、打字、填表单时调用
547
+ *
548
+ * @returns this(支持链式调用)
549
+ */
550
+ keepAlive(): IAaaSPilotKitController;
551
+ }
552
+ export {};
package/package.json ADDED
@@ -0,0 +1,64 @@
1
+ {
2
+ "name": "@bdky/aaas-pilot-kit",
3
+ "version": "1.0.2",
4
+ "license": "MIT",
5
+ "contributors": [
6
+ {
7
+ "name": "zhangwenxi",
8
+ "email": "zhangwenxi@baidu.com"
9
+ }
10
+ ],
11
+ "main": "./dist/index.cjs.js",
12
+ "module": "./dist/index.esm.js",
13
+ "browser": "./dist/ky-aaas-pilot-kit.umd.js",
14
+ "typings": "./dist/libs/aaas-pilot-kit/src/index.d.ts",
15
+ "exports": {
16
+ ".": {
17
+ "types": "./dist/libs/aaas-pilot-kit/src/index.d.ts",
18
+ "import": "./dist/index.esm.js",
19
+ "require": "./dist/index.cjs.js"
20
+ },
21
+ "./http": {
22
+ "types": "./dist/libs/aaas-pilot-kit/src/http.d.ts",
23
+ "import": "./dist/http.esm.js",
24
+ "require": "./dist/http.cjs.js"
25
+ }
26
+ },
27
+ "files": [
28
+ "dist"
29
+ ],
30
+ "publishConfig": {
31
+ "access": "public",
32
+ "registry": "https://registry.npmjs.org"
33
+ },
34
+ "scripts": {
35
+ "build": "npx rslib build",
36
+ "dev": "npx rsbuild dev --open",
37
+ "analyze": "RSDOCTOR=true npx rslib build"
38
+ },
39
+ "dependencies": {
40
+ "@bddh/starling-dh-picture-client": "^1.0.52",
41
+ "@bddh/starling-dhiframe": "^2.1.9",
42
+ "@types/ua-parser-js": "^0.7.39",
43
+ "abort-signal-polyfill": "^1.0.0",
44
+ "core-js": "^3.44.0",
45
+ "emittery": "^1.2.0",
46
+ "fast-xml-parser": "^5.2.5",
47
+ "inversify": "^7.5.2",
48
+ "ky": "^1.8.1",
49
+ "p-defer": "^4.0.1",
50
+ "p-queue": "^8.1.0",
51
+ "reflect-metadata": "^0.2.2",
52
+ "type-fest": "^4.41.0",
53
+ "typewriter-effect": "^2.22.0",
54
+ "ua-parser-js": "^1.0.40",
55
+ "uuid": "^13.0.0",
56
+ "webrtc-adapter": "^9.0.3"
57
+ },
58
+ "devDependencies": {
59
+ "@types/react": "^19",
60
+ "@types/react-dom": "^19",
61
+ "react": "^19.1.0",
62
+ "react-dom": "^19.1.0"
63
+ }
64
+ }