@bdky/aaas-pilot-kit 1.0.5 → 1.0.6

package/dist/libs/aaas-pilot-kit/src/lib/controller.d.ts

@@ -25,6 +25,15 @@ export interface IInterruptEventPayload {
 type ExtractResponseType<P> = P extends BaseAgentService<infer R, any> ? R : never;
 export interface IReplyStartEventPayload<AS extends BaseAgentService = BaseAgentService> {
     agentResponse: AgentResponse<ExtractResponseType<AS>> | null;
+    /**
+     * 数字人服务处理延迟（毫秒）
+     * 从第一次 renderStreamText 到 render_subtitle 的耗时
+     */
+    latency?: number;
+    /**
+     * 数字人服务的请求 ID，用于追踪
+     */
+    requestId: string;
 }
 export declare class AaaSPilotKitController<AS extends BaseAgentService = BaseAgentService> implements IAaaSPilotKitController<AS> {
     private readonly opts;
@@ -47,6 +56,8 @@ export declare class AaaSPilotKitController<AS extends BaseAgentService = BaseAg
     private multiModAbortControllers;
     /** playWaitFor监听listener */
     private playWaitForListener;
+    /** 记录每次 query 的开始时间，用于计算 TTFT */
+    private queryStartTime;
     private readonly weirwood;
     constructor(opts: IResolvedOptions, errorManager: ErrorManager, agentService: AS, asrService: BaseAsrService, digitalHumanService: BaseDigitalHumanService, conversationService: ConversationService);
     mount: ($container?: HTMLElement) => Promise<void>;
@@ -120,6 +131,10 @@ export declare class AaaSPilotKitController<AS extends BaseAgentService = BaseAg
     private readonly createNewAIWorkerConversation;
     private readonly handleAgentAnswerCompleted;
     private readonly handleAgentInstructionReceived;
+    /**
+     * 处理 TTFT 事件：计算总延迟并转发
+     */
+    private readonly handleTtft;
     private readonly handleAsrServiceStarted;
     /**
      * 处理asr消息

package/dist/libs/aaas-pilot-kit/src/lib/service/agent/baseAgentService.d.ts

@@ -19,6 +19,11 @@ export declare namespace NBaseAgentService {
     }
     type IHangupEventPayload = IEventWithSessionIdPayload;
     type ICompletedEventPayload = IEventWithSessionIdPayload;
+    interface ITtftEventPayload extends IEventWithSessionIdPayload {
+        firstToken: string;
+        timestamp: number;
+        totalLatency?: number;
+    }
     interface IEmitter {
         data: IDataEventPayload;
         completed: ICompletedEventPayload;
@@ -28,6 +33,7 @@ export declare namespace NBaseAgentService {
         response: IResponseEventPayload;
         quota_expired: IEventWithSessionIdPayload;
         usage_quota_reached: IEventWithSessionIdPayload;
+        ttft: ITtftEventPayload;
     }
 }
 export declare abstract class BaseAgentService<R = any, E extends NBaseAgentService.IEmitter = NBaseAgentService.IEmitter> {
@@ -49,6 +55,10 @@ export declare abstract class BaseAgentService<R = any, E extends NBaseAgentServ
      * 响应管理器,维护所有 Agent 回复
      */
     protected responseManager: ResponseManager<R>;
+    /**
+     * TTFT 标记：是否已经发出首字返回事件
+     */
+    protected hasTtftEmitted: boolean;
     constructor(request: CommonRequest, errorManager: ErrorManager, opts: IResolvedOptions);
     get sessionId(): string;
     get queryId(): string;
@@ -77,6 +87,17 @@ export declare abstract class BaseAgentService<R = any, E extends NBaseAgentServ
     protected onResponse: (response: R) => void;
     protected onUsageQuotaReached: (payload: E["usage_quota_reached"]) => void;
     protected onQuotaExpired: (payload: E["quota_expired"]) => void;
+    /**
+     * 发射 TTFT 事件（仅触发一次）
+     * 注意：totalLatency 为可选字段，由 Controller 层自动计算并填充
+     */
+    protected onTtft: (payload: Omit<E["ttft"], "totalLatency"> & {
+        totalLatency?: number;
+    }) => void;
+    /**
+     * 重置 TTFT 标记（子类在 query 开始时调用）
+     */
+    protected resetTtftFlag: () => void;
     protected _dispose: () => void;
     abstract query(text: string): Promise<any>;
     abstract dispose(): void;

package/dist/libs/aaas-pilot-kit/src/lib/service/conversation/aiWorkerConversationBean.d.ts

@@ -11,9 +11,18 @@ export declare namespace NAIWorkerConversationBean {
         content: string;
         completed: boolean;
     }
+    /**
+     * conversation_end 事件数据结构
+     * 当所有 contents 都完成渲染时触发
+     */
+    interface IConversationEndPayload extends IConversationBeanSnapshot<'aiWorker'> {
+        contents: Array<NMultimodalContent.ISnapshot<any>>;
+        timestamp: number;
+    }
     interface IEmitter extends NConversationBean.IEmitter {
         content_change: IContentChangePayload;
         queue_empty: never;
+        conversation_end: IConversationEndPayload;
         interrupt: never;
     }
 }
@@ -22,6 +31,11 @@ export declare class AIWorkerConversationBean extends ConversationBean<'aiWorker
     contents: Array<ImageContent | VideoContent | TextContent>;
     private readonly queue;
     private readonly customXmlParser;
+    /**
+     * 标记当前会话是否已接收到"结束"信号
+     * 只有在此标记为 true 且队列清空时,才触发 conversation_end 事件
+     */
+    private hasReceivedEndSignal;
     constructor(d: Partial<IConversationBeanSnapshot<'aiWorker'>>, opts: IResolvedOptions);
     get fulltext(): string;
     static create: (opts: IResolvedOptions) => AIWorkerConversationBean;
@@ -35,5 +49,10 @@ export declare class AIWorkerConversationBean extends ConversationBean<'aiWorker
     appendText: (text: string) => void;
     dispose: () => void;
     interrupt: () => void;
+    /**
+     * 标记当前会话已结束
+     * 调用此方法后,当队列清空时将触发 conversation_end 事件
+     */
+    markAsEnded: () => void;
     private readonly bindEvents;
 }

package/dist/libs/aaas-pilot-kit/src/lib/service/digital-human/BaseDigitalHumanService.d.ts

@@ -13,6 +13,11 @@ export declare namespace NAbstractDigitalHumanService {
     }
     interface IRenderSubtitleEventPayload extends IBaseEmitterPayload {
         subtitle: ISubtitle;
+        /**
+         * 从第一次 renderStreamText 到 render_subtitle 的延迟（毫秒）
+         * 仅在首次 render_subtitle 时有值
+         */
+        latency?: number;
     }
     interface IEmitter {
         disconnect_alert: IBaseEmitterPayload;
@@ -38,6 +43,10 @@ export declare abstract class BaseDigitalHumanService {
     protected _canInterrupt: boolean;
     protected ssmlHandlers: NAbstractDigitalHumanService.ISsmlHandler[];
     protected token: string;
+    /**
+     * 记录每个 requestId 的开始时间，用于计算 latency
+     */
+    protected latencyStartMap: Map<string, number>;
     constructor(opts: IOptions, request: CommonRequest, errorManager: ErrorManager);
     get isRendering(): boolean;
     get isMuted(): boolean;

package/dist/libs/aaas-pilot-kit/src/types/config.d.ts

@@ -548,6 +548,42 @@ export interface IAaaSPilotKitEmitter<AS extends BaseAgentService = BaseAgentSer
         devices?: MediaDeviceInfo[];
         permissionState?: PermissionState;
     };
+    /**
+     * ⚡【TTFT 事件】Time To First Token - 大模型首字返回事件
+     *
+     * 💡 触发时机：
+     *   - Agent SSE 返回第一个非空 answer 时立即触发
+     *   - 早于 reply_start（数字人播报开始）约 100~500ms
+     *
+     * 🎯 使用场景：
+     *   - 性能监控：统计大模型响应速度（TTFT 指标）
+     *   - 用户体验：隐藏"正在思考..."加载动画
+     *   - 埋点上报：记录首字延迟数据
+     *
+     * @payload {
+     *   sessionId: string;       // 会话 ID
+     *   queryId: string;         // 查询 ID
+     *   firstToken: string;      // 首个 token 内容（可能是字/词/句子片段）
+     *   timestamp: number;       // 首字返回时间戳（performance.now()，高精度）
+     *   totalLatency: number;    // 从 query 开始到首字的总延迟（毫秒，高精度）
+     * }
+     *
+     * ⚠️ 注意：
+     *   - timestamp 和 totalLatency 使用 performance.now() 获取，提供亚毫秒级精度
+     *   - 不受系统时间调整影响，适合性能测量
+     *
+     * @example 监听 TTFT 事件
+     * ```typescript
+     * controller.emitter.on('ttft', (payload) => {
+     *   console.log('TTFT:', payload.totalLatency.toFixed(2), 'ms');
+     *   console.log('首个 token:', payload.firstToken);
+     *   setLoading(false);  // 隐藏加载动画
+     * });
+     * ```
+     */
+    ttft: NBaseAgentService.ITtftEventPayload & {
+        totalLatency: number;
+    };
 }
 export interface IAaaSPilotKitController<AS extends BaseAgentService = BaseAgentService> {
     emitter: Emittery<IAaaSPilotKitEmitter<AS>>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bdky/aaas-pilot-kit",
-    "version": "1.0.5",
+    "version": "1.0.6",
     "license": "MIT",
     "contributors": [
         {