@huyooo/ai-chat-core 0.2.19 → 0.2.20

package/dist/events.d.ts

@@ -0,0 +1,452 @@
+/**
+ * AI Chat 事件系统
+ *
+ * 模块化的事件类型定义，用于 Agent 与前端之间的通信。
+ *
+ * 设计原则：
+ * 1. 每种事件类型有明确的数据结构
+ * 2. 事件分组便于管理和扩展
+ * 3. 类型安全，避免 unknown
+ * 4. 统一的时间追踪（开始/结束/耗时）
+ */
+/**
+ * 搜索结果项（统一契约）
+ * 无论搜索来源是厂商原生（ARK annotation）还是 Tavily 工具，协议/编排层都会归一为此结构，
+ * 前端只需依赖 title/url/snippet 即可。
+ */
+interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/** 工具调用状态 */
+type ToolCallStatus = 'pending' | 'running' | 'success' | 'error';
+/** 工具调用信息（用于前端状态管理） */
+interface ToolCallInfo {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    status: ToolCallStatus;
+    result?: string;
+    error?: string;
+    startedAt?: number;
+    duration?: number;
+}
+/** Token 使用统计 */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /** 思考 token 数（如果有） */
+    reasoningTokens?: number;
+    /** 缓存命中 token 数（如果有） */
+    cachedTokens?: number;
+}
+/** 错误类别 - 参考 AI SDK 设计 */
+type ErrorCategory = 'api' | 'rate_limit' | 'validation' | 'tool' | 'timeout' | 'abort' | 'parse' | 'unknown';
+/** 错误详情 - 结构化错误信息 */
+interface ErrorDetails {
+    /** 错误分类 */
+    category: ErrorCategory;
+    /** 人类可读的错误信息 */
+    message: string;
+    /** 错误代码（如 'RATE_LIMIT', 'NETWORK_ERROR'） */
+    code?: string;
+    /** HTTP 状态码（如果适用） */
+    statusCode?: number;
+    /** HTTP 状态文本 */
+    statusText?: string;
+    /** 是否可重试 */
+    retryable?: boolean;
+    /** 重试等待时间（秒） */
+    retryAfter?: number;
+    /** 原始错误信息（用于调试） */
+    cause?: string;
+    /** 错误发生的上下文（如模型名、工具名） */
+    context?: string;
+}
+/** 思考开始事件 */
+interface ThinkingStartEvent {
+    type: 'thinking_start';
+    data: {
+        /** 开始时间戳（毫秒） */
+        startedAt: number;
+    };
+}
+/** 思考内容增量事件 */
+interface ThinkingDeltaEvent {
+    type: 'thinking_delta';
+    data: {
+        /** 增量内容 */
+        content: string;
+    };
+}
+/** 思考结束事件 */
+interface ThinkingEndEvent {
+    type: 'thinking_end';
+    data: {
+        /** 结束时间戳（毫秒） */
+        endedAt: number;
+        /** 思考耗时（毫秒） */
+        duration: number;
+    };
+}
+/** 思考相关事件联合类型 */
+type ThinkingEvent = ThinkingStartEvent | ThinkingDeltaEvent | ThinkingEndEvent;
+/** 搜索开始事件 */
+interface SearchStartEvent {
+    type: 'search_start';
+    data: {
+        /** 搜索查询词 */
+        query: string;
+        /** 开始时间戳（毫秒） */
+        startedAt: number;
+    };
+}
+/** 搜索结果事件（成功完成） */
+interface SearchResultEvent {
+    type: 'search_result';
+    data: {
+        /** 搜索结果列表 */
+        results: SearchResult[];
+        /** 结束时间戳（毫秒） */
+        endedAt: number;
+        /** 搜索耗时（毫秒） */
+        duration: number;
+    };
+}
+/** 搜索结束事件（失败或取消） */
+interface SearchEndEvent {
+    type: 'search_end';
+    data: {
+        /** 是否成功 */
+        success: boolean;
+        /** 错误信息（失败时） */
+        error?: string;
+        /** 结束时间戳（毫秒） */
+        endedAt: number;
+        /** 搜索耗时（毫秒） */
+        duration: number;
+    };
+}
+/** 搜索相关事件联合类型 */
+type SearchEvent = SearchStartEvent | SearchResultEvent | SearchEndEvent;
+/** 工具调用开始事件 */
+interface ToolCallStartEvent {
+    type: 'tool_call_start';
+    data: {
+        /** 工具调用 ID */
+        id: string;
+        /** 工具名称 */
+        name: string;
+        /** 工具参数 */
+        args: Record<string, unknown>;
+        /** 开始时间戳（毫秒） */
+        startedAt: number;
+    };
+}
+/** 副作用定义（从 types.ts 复制，避免循环依赖） */
+interface SideEffect {
+    type: string;
+    success: boolean;
+    data?: unknown;
+    message?: string;
+}
+/** 工具调用结果事件 */
+interface ToolCallResultEvent {
+    type: 'tool_call_result';
+    data: {
+        /** 工具调用 ID */
+        id: string;
+        /** 工具名称 */
+        name: string;
+        /** 执行结果 */
+        result: string;
+        /** 是否成功 */
+        success: boolean;
+        /** 错误信息（失败时） */
+        error?: string;
+        /** 结束时间戳（毫秒） */
+        endedAt: number;
+        /** 执行耗时（毫秒） */
+        duration: number;
+        /**
+         * 工具副作用
+         * 前端可根据此字段处理通知、刷新文件列表等
+         */
+        sideEffects?: SideEffect[];
+        /**
+         * 结果类型（用于前端渲染）
+         *
+         * 当工具定义了 resultType 且执行成功时，前端会根据此类型生成对应的 ContentPart
+         * 例如：resultType: 'weather' 会生成 { type: 'weather', ...result }
+         */
+        resultType?: string;
+    };
+}
+/** 工具输出增量事件（用于 stdout/stderr 流式展示） */
+interface ToolCallOutputEvent {
+    type: 'tool_call_output';
+    data: {
+        /** 工具调用 ID */
+        id: string;
+        /** 工具名称 */
+        name: string;
+        /** 输出流类型 */
+        stream: 'stdout' | 'stderr';
+        /** 输出增量内容 */
+        chunk: string;
+        /** 时间戳 */
+        at: number;
+    };
+}
+/** 工具执行批准请求事件（manual 模式） */
+interface ToolApprovalRequestEvent {
+    type: 'tool_approval_request';
+    data: {
+        /** 工具调用 ID */
+        id: string;
+        /** 工具名称 */
+        name: string;
+        /** 工具参数 */
+        args: Record<string, unknown>;
+        /** 请求时间戳 */
+        requestedAt: number;
+    };
+}
+/**
+ * 客户端工具调用请求事件（透传模式）
+ *
+ * 用于用户自定义工具：
+ * - AI 返回 tool_call
+ * - 服务端不执行，透传给客户端
+ * - 客户端执行后，发新请求继续对话
+ */
+interface ToolCallRequestEvent {
+    type: 'tool_call_request';
+    data: {
+        /** 工具调用 ID */
+        id: string;
+        /** 工具名称 */
+        name: string;
+        /** 工具参数 */
+        args: Record<string, unknown>;
+        /** 请求时间戳 */
+        requestedAt: number;
+    };
+}
+/** 工具相关事件联合类型 */
+type ToolEvent = ToolCallStartEvent | ToolCallResultEvent | ToolApprovalRequestEvent | ToolCallOutputEvent | ToolCallRequestEvent;
+/** 文本增量事件 */
+interface TextDeltaEvent {
+    type: 'text_delta';
+    data: {
+        /** 增量文本 */
+        content: string;
+    };
+}
+/** 文本相关事件联合类型 */
+type TextEvent = TextDeltaEvent;
+/** 计划步骤状态 */
+type PlanStepStatus = 'pending' | 'in_progress' | 'done' | 'failed';
+/** 计划步骤 */
+interface PlanStep {
+    /** 步骤 ID（模型生成，如 "1", "scan", "move-images"） */
+    id: string;
+    /** 步骤描述 */
+    title: string;
+    /** 步骤状态 */
+    status: PlanStepStatus;
+}
+/** 完成事件 */
+interface DoneEvent {
+    type: 'done';
+    data: {
+        /** 完整的最终文本 */
+        text: string;
+        /** Token 使用统计 */
+        usage?: TokenUsage;
+        /** 总耗时（毫秒） */
+        duration?: number;
+    };
+}
+/** 错误事件 - 结构化错误信息 */
+interface ErrorEvent {
+    type: 'error';
+    data: ErrorDetails;
+}
+/** 中止事件 - 用户主动取消 */
+interface AbortEvent {
+    type: 'abort';
+    data: {
+        /** 中止原因 */
+        reason?: string;
+        /** 中止时间戳 */
+        abortedAt: number;
+    };
+}
+/** 状态相关事件联合类型 */
+type StatusEvent = DoneEvent | ErrorEvent | AbortEvent;
+/** 步骤开始事件 */
+interface StepStartEvent {
+    type: 'step_start';
+    data: {
+        /** 步骤编号（从 1 开始） */
+        stepNumber: number;
+        /** 步骤描述（可选） */
+        description?: string;
+        /** 开始时间戳 */
+        startedAt: number;
+    };
+}
+/** 步骤结束事件 */
+interface StepEndEvent {
+    type: 'step_end';
+    data: {
+        /** 步骤编号 */
+        stepNumber: number;
+        /** 结束时间戳 */
+        endedAt: number;
+        /** 耗时（毫秒） */
+        duration: number;
+    };
+}
+/** 步骤相关事件联合类型 */
+type StepEvent = StepStartEvent | StepEndEvent;
+/**
+ * Agent 当前阶段：前端根据此字段直接渲染 loading 状态，不需要「猜」。
+ *
+ * - thinking：模型正在思考（初始请求 / 工具执行完后等待下一轮）→ 显示「正在思考...」
+ * - null：有可见活动（思考/搜索/工具/文字流），不需要额外 loading
+ */
+type AgentPhase = 'thinking' | null;
+/** Agent 状态事件（前端用于渲染 loading 提示） */
+interface AgentStatusEvent {
+    type: 'agent_status';
+    data: {
+        /** 当前阶段 */
+        phase: AgentPhase;
+    };
+}
+/** 创建 agent_status 事件 */
+declare function createAgentStatus(phase: AgentPhase): AgentStatusEvent;
+/** 所有事件类型 */
+type ChatEvent = ThinkingEvent | SearchEvent | ToolEvent | TextEvent | StatusEvent | StepEvent | AgentStatusEvent;
+/** 事件类型字符串 */
+type ChatEventType = ChatEvent['type'];
+/** 所有合法事件类型（用于契约测试：Orchestrator/适配器产出必须在此集合内） */
+declare const CHAT_EVENT_TYPES: readonly ChatEventType[];
+/**
+ * 创建思考开始事件
+ */
+declare function createThinkingStart(): ThinkingStartEvent;
+/**
+ * 创建思考增量事件
+ */
+declare function createThinkingDelta(content: string): ThinkingDeltaEvent;
+/**
+ * 创建思考结束事件
+ */
+declare function createThinkingEnd(startedAt: number): ThinkingEndEvent;
+/**
+ * 创建搜索开始事件
+ */
+declare function createSearchStart(query: string): SearchStartEvent;
+/**
+ * 创建搜索结果事件（成功）
+ */
+declare function createSearchResult(results: SearchResult[], startedAt: number): SearchResultEvent;
+/**
+ * 创建搜索结束事件（失败或取消）
+ */
+declare function createSearchEnd(success: boolean, startedAt: number, error?: string): SearchEndEvent;
+/**
+ * 创建工具调用开始事件
+ */
+declare function createToolCallStart(id: string, name: string, args: Record<string, unknown>): ToolCallStartEvent;
+/**
+ * 创建工具调用结果事件
+ */
+declare function createToolCallResult(id: string, name: string, result: string, success: boolean, startedAt: number, error?: string, sideEffects?: SideEffect[], resultType?: string): ToolCallResultEvent;
+/**
+ * 创建工具输出增量事件
+ */
+declare function createToolCallOutput(id: string, name: string, stream: 'stdout' | 'stderr', chunk: string): ToolCallOutputEvent;
+/**
+ * 创建客户端工具调用请求事件（透传模式）
+ *
+ * 用于用户自定义工具，服务端不执行，透传给客户端
+ */
+declare function createToolCallRequest(id: string, name: string, args: Record<string, unknown>): ToolCallRequestEvent;
+/**
+ * 创建文本增量事件
+ */
+declare function createTextDelta(content: string): TextDeltaEvent;
+/**
+ * 创建完成事件
+ */
+declare function createDone(text: string, usage?: TokenUsage, duration?: number): DoneEvent;
+/**
+ * 创建错误事件（完整版）
+ */
+declare function createError(details: ErrorDetails): ErrorEvent;
+/**
+ * 创建 API 错误事件
+ */
+declare function createApiError(message: string, options?: {
+    code?: string;
+    statusCode?: number;
+    statusText?: string;
+    retryable?: boolean;
+    retryAfter?: number;
+    cause?: string;
+    context?: string;
+}): ErrorEvent;
+/**
+ * 创建速率限制错误事件
+ */
+declare function createRateLimitError(message: string, retryAfter?: number, context?: string): ErrorEvent;
+/**
+ * 创建工具错误事件
+ */
+declare function createToolError(message: string, toolName: string, cause?: string): ErrorEvent;
+/**
+ * 创建超时错误事件
+ */
+declare function createTimeoutError(message: string, context?: string): ErrorEvent;
+/**
+ * 创建解析错误事件
+ */
+declare function createParseError(message: string, cause?: string): ErrorEvent;
+/**
+ * 创建中止事件
+ */
+declare function createAbort(reason?: string): AbortEvent;
+/**
+ * 创建步骤开始事件
+ */
+declare function createStepStart(stepNumber: number, description?: string): StepStartEvent;
+/**
+ * 创建步骤结束事件
+ */
+declare function createStepEnd(stepNumber: number, startedAt: number): StepEndEvent;
+/** 检查是否为思考事件 */
+declare function isThinkingEvent(event: ChatEvent): event is ThinkingEvent;
+/** 检查是否为搜索事件 */
+declare function isSearchEvent(event: ChatEvent): event is SearchEvent;
+/** 检查是否为工具事件 */
+declare function isToolEvent(event: ChatEvent): event is ToolEvent;
+/** 检查是否为文本事件 */
+declare function isTextEvent(event: ChatEvent): event is TextEvent;
+/** 检查是否为状态事件 */
+declare function isStatusEvent(event: ChatEvent): event is StatusEvent;
+/** 检查是否为错误事件 */
+declare function isErrorEvent(event: ChatEvent): event is ErrorEvent;
+/** 检查是否为中止事件 */
+declare function isAbortEvent(event: ChatEvent): event is AbortEvent;
+/** 检查是否为步骤事件 */
+declare function isStepEvent(event: ChatEvent): event is StepEvent;
+/** 检查错误是否可重试 */
+declare function isRetryableError(event: ChatEvent): boolean;
+
+export { type AbortEvent, type AgentPhase, type AgentStatusEvent, CHAT_EVENT_TYPES, type ChatEvent, type ChatEventType, type DoneEvent, type ErrorCategory, type ErrorDetails, type ErrorEvent, type PlanStep, type PlanStepStatus, type SearchEndEvent, type SearchEvent, type SearchResult, type SearchResultEvent, type SearchStartEvent, type SideEffect, type StatusEvent, type StepEndEvent, type StepEvent, type StepStartEvent, type TextDeltaEvent, type TextEvent, type ThinkingDeltaEvent, type ThinkingEndEvent, type ThinkingEvent, type ThinkingStartEvent, type TokenUsage, type ToolApprovalRequestEvent, type ToolCallInfo, type ToolCallOutputEvent, type ToolCallRequestEvent, type ToolCallResultEvent, type ToolCallStartEvent, type ToolCallStatus, type ToolEvent, createAbort, createAgentStatus, createApiError, createDone, createError, createParseError, createRateLimitError, createSearchEnd, createSearchResult, createSearchStart, createStepEnd, createStepStart, createTextDelta, createThinkingDelta, createThinkingEnd, createThinkingStart, createTimeoutError, createToolCallOutput, createToolCallRequest, createToolCallResult, createToolCallStart, createToolError, isAbortEvent, isErrorEvent, isRetryableError, isSearchEvent, isStatusEvent, isStepEvent, isTextEvent, isThinkingEvent, isToolEvent };

package/dist/events.js

@@ -0,0 +1 @@
+function t(t){return{type:"agent_status",data:{phase:t}}}var e=["thinking_start","thinking_delta","thinking_end","search_start","search_result","search_end","tool_call_start","tool_call_result","tool_call_output","tool_approval_request","tool_call_request","text_delta","done","error","abort","step_start","step_end","agent_status"];function n(){return{type:"thinking_start",data:{startedAt:Date.now()}}}function r(t){return{type:"thinking_delta",data:{content:t}}}function a(t){const e=Date.now();return{type:"thinking_end",data:{endedAt:e,duration:e-t}}}function o(t){return{type:"search_start",data:{query:t,startedAt:Date.now()}}}function u(t,e){const n=Date.now();return{type:"search_result",data:{results:t,endedAt:n,duration:n-e}}}function s(t,e,n){const r=Date.now();return{type:"search_end",data:{success:t,error:n,endedAt:r,duration:r-e}}}function c(t,e,n){return{type:"tool_call_start",data:{id:t,name:e,args:n,startedAt:Date.now()}}}function i(t,e,n,r,a,o,u,s){const c=Date.now();return{type:"tool_call_result",data:{id:t,name:e,result:n,success:r,error:o,endedAt:c,duration:c-a,sideEffects:u,resultType:s}}}function d(t,e,n,r){return{type:"tool_call_output",data:{id:t,name:e,stream:n,chunk:r,at:Date.now()}}}function _(t,e,n){return{type:"tool_call_request",data:{id:t,name:e,args:n,requestedAt:Date.now()}}}function l(t){return{type:"text_delta",data:{content:t}}}function p(t,e,n){return{type:"done",data:{text:t,usage:e,duration:n}}}function y(t){return{type:"error",data:t}}function f(t,e={}){return y({category:"api",message:t,...e})}function g(t,e,n){return y({category:"rate_limit",message:t,code:"RATE_LIMIT",statusCode:429,retryable:!0,retryAfter:e,context:n})}function h(t,e,n){return y({category:"tool",message:t,code:"TOOL_ERROR",context:e,cause:n,retryable:!1})}function m(t,e){return y({category:"timeout",message:t,code:"TIMEOUT",retryable:!0,context:e})}function A(t,e){return y({category:"parse",message:t,code:"PARSE_ERROR",cause:e,retryable:!1})}function b(t){return{type:"abort",data:{reason:t,abortedAt:Date.now()}}}function w(t,e){return{type:"step_start",data:{stepNumber:t,description:e,startedAt:Date.now()}}}function D(t,e){const n=Date.now();return{type:"step_end",data:{stepNumber:t,endedAt:n,duration:n-e}}}function k(t){return t.type.startsWith("thinking_")}function x(t){return t.type.startsWith("search_")}function R(t){return t.type.startsWith("tool_")}function E(t){return"text_delta"===t.type}function T(t){return"done"===t.type||"error"===t.type||"abort"===t.type}function q(t){return"error"===t.type}function O(t){return"abort"===t.type}function W(t){return t.type.startsWith("step_")}function I(t){return"error"===t.type&&!0===t.data.retryable}export{e as CHAT_EVENT_TYPES,b as createAbort,t as createAgentStatus,f as createApiError,p as createDone,y as createError,A as createParseError,g as createRateLimitError,s as createSearchEnd,u as createSearchResult,o as createSearchStart,D as createStepEnd,w as createStepStart,l as createTextDelta,r as createThinkingDelta,a as createThinkingEnd,n as createThinkingStart,m as createTimeoutError,d as createToolCallOutput,_ as createToolCallRequest,i as createToolCallResult,c as createToolCallStart,h as createToolError,O as isAbortEvent,q as isErrorEvent,I as isRetryableError,x as isSearchEvent,T as isStatusEvent,W as isStepEvent,E as isTextEvent,k as isThinkingEvent,R as isToolEvent};