@huyooo/ai-chat-core 0.2.19 → 0.2.21

package/src/events.ts

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