@huyooo/ai-chat-core 0.2.40 → 0.2.42

package/src/events.ts

@@ -62,46 +62,13 @@ export type ErrorCategory =
   | 'parse'         // 解析错误（JSON、响应格式）
   | 'unknown';      // 未知错误
 
-/**
- * 工具执行错误结构化（可抛出的 Error 携带）
- * 用于工具 throw 后由 bridge 透传，前端展示 suggestion、重试按钮等
- */
-export interface ToolErrorShape {
-  message: string;
-  code?: string;
-  retryable?: boolean;
-  suggestion?: string;
-}
+// 工具错误类型从 types 统一定义，此处重导出
+import type { ToolError } from './types';
+export type { ToolError as ToolErrorShape };
+export { isToolError as isThrowableToolError } from './types';
 
-/** 判断错误是否携带 toolError 结构 */
-export function isThrowableToolError(e: unknown): e is Error & { toolError: ToolErrorShape } {
-  return (
-    e instanceof Error &&
-    e !== null &&
-    typeof (e as Error & { toolError?: unknown }).toolError === 'object' &&
-    (e as Error & { toolError: Record<string, unknown> }).toolError !== null &&
-    typeof ((e as Error & { toolError: Record<string, unknown> }).toolError as Record<string, unknown>).message === 'string'
-  );
-}
-
-/**
- * 创建可抛出的结构化工具错误
- * 工具 throw 后 bridge 检测 toolError 并透传给前端
- */
-export function createThrowableToolError(
-  message: string,
-  opts?: { code?: string; retryable?: boolean; suggestion?: string }
-): Error & { toolError: ToolErrorShape } {
-  const toolError: ToolErrorShape = {
-    message,
-    code: opts?.code,
-    retryable: opts?.retryable,
-    suggestion: opts?.suggestion,
-  };
-  const err = new Error(message) as Error & { toolError: ToolErrorShape };
-  Object.defineProperty(err, 'toolError', { value: toolError, enumerable: true });
-  return err;
-}
+/** 内部使用的 ToolErrorShape 别名 */
+type ToolErrorShape = ToolError;
 
 /** 错误详情 - 结构化错误信息 */
 export interface ErrorDetails {
@@ -220,14 +187,6 @@ export interface ToolCallStartEvent {
   };
 }
 
-/** 副作用定义（从 types.ts 复制，避免循环依赖） */
-export interface SideEffect {
-  type: string;
-  success: boolean;
-  data?: unknown;
-  message?: string;
-}
-
 /** 工具调用结果事件 */
 export interface ToolCallResultEvent {
   type: 'tool_call_result';
@@ -236,31 +195,28 @@ export interface ToolCallResultEvent {
     id: string;
     /** 工具名称 */
     name: string;
-    /** 执行结果 */
+    /** 执行结果（JSON 字符串） */
     result: string;
     /** 是否成功 */
     success: boolean;
     /** 错误信息（失败时） */
-    error?: string;
+    error?: ToolErrorShape;
     /** 结束时间戳（毫秒） */
     endedAt: number;
     /** 执行耗时（毫秒） */
     duration: number;
-    /** 
-     * 工具副作用
-     * 前端可根据此字段处理通知、刷新文件列表等
-     */
-    sideEffects?: SideEffect[];
-    /**
-     * 结果类型（用于前端渲染）
-     * 
-     * 当工具定义了 resultType 且执行成功时，前端会根据此类型生成对应的 ContentPart
-     * 例如：resultType: 'weather' 会生成 { type: 'weather', ...result }
-     */
-    resultType?: string;
+    /** 工具 UI 声明（成功时） */
+    ui?: ToolUIShape;
   };
 }
 
+/** ToolUI 形状（对应 types.ts 中的 ToolUI，避免循环依赖） */
+export interface ToolUIShape {
+  type: 'render' | 'action';
+  name: string;
+  props?: Record<string, unknown>;
+}
+
 /** 工具输出增量事件（用于 stdout/stderr 流式展示） */
 export interface ToolCallOutputEvent {
   type: 'tool_call_output';
@@ -413,6 +369,43 @@ export interface StepEndEvent {
 /** 步骤相关事件联合类型 */
 export type StepEvent = StepStartEvent | StepEndEvent;
 
+// ==================== 上下文压缩事件 ====================
+
+/** 上下文压缩开始事件 */
+export interface CompactStartEvent {
+  type: 'compact_start';
+  data: {
+    /** 压缩前估算 token 数 */
+    estimatedTokens: number;
+    /** 可用 prompt token 预算 */
+    budget: number;
+    /** 开始时间戳 */
+    startedAt: number;
+  };
+}
+
+/** 上下文压缩完成事件 */
+export interface CompactEndEvent {
+  type: 'compact_end';
+  data: {
+    /** 是否成功 */
+    success: boolean;
+    /** 压缩后估算 token 数 */
+    compressedTokens: number;
+    /** 压缩前消息数 */
+    originalMessageCount: number;
+    /** 压缩后消息数 */
+    compressedMessageCount: number;
+    /** 结束时间戳 */
+    endedAt: number;
+    /** 耗时（毫秒） */
+    duration: number;
+  };
+}
+
+/** 上下文压缩相关事件联合类型 */
+export type CompactEvent = CompactStartEvent | CompactEndEvent;
+
 // ==================== Agent 状态事件 ====================
 
 /**
@@ -447,6 +440,7 @@ export type ChatEvent =
   | TextEvent
   | StatusEvent
   | StepEvent
+  | CompactEvent
   | AgentStatusEvent;
 
 /** 事件类型字符串 */
@@ -460,6 +454,7 @@ export const CHAT_EVENT_TYPES: readonly ChatEventType[] = [
   'text_delta',
   'done', 'error', 'abort',
   'step_start', 'step_end',
+  'compact_start', 'compact_end',
   'agent_status',
 ] as const;
 
@@ -567,9 +562,8 @@ export function createToolCallResult(
   result: string,
   success: boolean,
   startedAt: number,
-  error?: string,
-  sideEffects?: SideEffect[],
-  resultType?: string
+  error?: ToolErrorShape,
+  ui?: ToolUIShape
 ): ToolCallResultEvent {
   const endedAt = Date.now();
   return {
@@ -582,8 +576,7 @@ export function createToolCallResult(
       error,
       endedAt,
       duration: endedAt - startedAt,
-      sideEffects,
-      resultType
+      ui
     }
   };
 }
@@ -789,6 +782,40 @@ export function createStepEnd(stepNumber: number, startedAt: number): StepEndEve
   };
 }
 
+/**
+ * 创建上下文压缩开始事件
+ */
+export function createCompactStart(estimatedTokens: number, budget: number): CompactStartEvent {
+  return {
+    type: 'compact_start',
+    data: { estimatedTokens, budget, startedAt: Date.now() },
+  };
+}
+
+/**
+ * 创建上下文压缩完成事件
+ */
+export function createCompactEnd(
+  success: boolean,
+  compressedTokens: number,
+  originalMessageCount: number,
+  compressedMessageCount: number,
+  startedAt: number,
+): CompactEndEvent {
+  const endedAt = Date.now();
+  return {
+    type: 'compact_end',
+    data: {
+      success,
+      compressedTokens,
+      originalMessageCount,
+      compressedMessageCount,
+      endedAt,
+      duration: endedAt - startedAt,
+    },
+  };
+}
+
 // ==================== 类型守卫 ====================
 
 /** 检查是否为思考事件 */
@@ -831,6 +858,11 @@ export function isStepEvent(event: ChatEvent): event is StepEvent {
   return event.type.startsWith('step_');
 }
 
+/** 检查是否为上下文压缩事件 */
+export function isCompactEvent(event: ChatEvent): event is CompactEvent {
+  return event.type.startsWith('compact_');
+}
+
 /** 检查错误是否可重试 */
 export function isRetryableError(event: ChatEvent): boolean {
   if (event.type !== 'error') return false;

package/src/index.ts

@@ -138,9 +138,12 @@ export type {
   // 工具接口
   Tool,
   ToolContext,
-  ToolResult,
-  // 副作用类型
-  SideEffect,
+  ToolUI,
+  RenderType,
+  ActionType,
+  ExecResult,
+  ToolError,
+  ToolErrorCode,
   // 工具插件（Vite 风格）
   ToolPlugin,
   ToolConfigItem,
@@ -156,6 +159,11 @@ export {
   resolveTools,
   tool,
   tools,
+  // 工具错误
+  throwToolError,
+  rethrowToolError,
+  isToolError,
+  getArg,
 } from './types';
 
 // 常量
@@ -172,9 +180,10 @@ export type {
   ErrorCategory,
   ErrorDetails,
   ToolErrorShape,
+  ToolUIShape,
 } from './events';
 
-export { createThrowableToolError, isThrowableToolError } from './events';
+export { isThrowableToolError } from './events';
 
 // 思考事件
 export type {
@@ -208,7 +217,7 @@ export type {
   TextEvent
 } from './events';
 
-// 计划类型（update_plan 工具通过 resultType:'plan' 渲染，无专用事件）
+// 计划类型（update_plan 工具通过 ui: { type: 'render', name: 'plan' } 渲染，无专用事件）
 export type {
   PlanStep,
   PlanStepStatus,

package/src/internal/web-search.ts

@@ -22,7 +22,6 @@ export function createWebSearchTool(tavilyApiKey: string): Tool {
       },
       required: ['query'],
     },
-    resultType: 'search_results',
     execute: async (args, ctx) => {
       const query = typeof args.query === 'string' ? args.query : '';
       const maxResults = typeof args.max_results === 'number' && Number.isFinite(args.max_results)
@@ -30,10 +29,10 @@ export function createWebSearchTool(tavilyApiKey: string): Tool {
         : 5;
 
       if (!query.trim()) {
-        return JSON.stringify({ query: '', results: [], error: '缺少 query' });
+        return { query: '', results: [], error: '缺少 query' };
       }
       if (!tavilyApiKey) {
-        return JSON.stringify({ query, results: [], error: '缺少 Tavily API Key' });
+        return { query, results: [], error: '缺少 Tavily API Key' };
       }
 
       const resp = await fetch('https://api.tavily.com/search', {
@@ -54,7 +53,7 @@ export function createWebSearchTool(tavilyApiKey: string): Tool {
 
       if (!resp.ok) {
         const t = await resp.text().catch(() => '');
-        return JSON.stringify({ query, results: [], error: `Tavily /search 错误: ${resp.status} ${t}`.trim() });
+        return { query, results: [], error: `Tavily /search 错误: ${resp.status} ${t}`.trim() };
       }
 
       const data: unknown = await resp.json().catch(() => null);
@@ -71,7 +70,7 @@ export function createWebSearchTool(tavilyApiKey: string): Tool {
         results.push({ title, url, snippet });
       }
 
-      return JSON.stringify({ query, results });
+      return { query, results };
     },
   };
 }

package/src/mcp/client-manager.ts

@@ -181,7 +181,8 @@ export class McpClientManager {
           }
         }
 
-        return texts.join('\n') || JSON.stringify(result.content);
+        const text = texts.join('\n') || JSON.stringify(result.content);
+        return { text };
       },
     };
   }

package/src/providers/context-compressor.ts

@@ -1,16 +1,11 @@
 /**
  * Context 压缩模块
- * 
- * 当消息历史过长时自动压缩，避免超出模型 context window。
- * 
- * 策略参考 Claude Code（92% context window 触发摘要）和
- * OpenAI Codex（auto_compact_limit 触发压缩）。
- * 
- * 压缩算法：
- * 1. 保留 system prompt
- * 2. 保留第一条 user 消息（任务描述）
- * 3. 将中间的 assistant/tool 交互压缩为一条摘要
- * 4. 保留最近 N 条消息（工作上下文）
+ *
+ * 当 prompt token 估算接近模型 context window 时，让当前模型自己总结对话历史，
+ * 然后用 summary + 最近几条消息继续对话。
+ *
+ * 参考 Claude Code / Cursor 的做法：
+ * 不机械截断，而是让 AI 生成高质量摘要，保留关键决策和上下文。
  */
 
 import type { StandardMessage } from './types';
@@ -18,69 +13,86 @@ import { DebugLogger } from '../utils';
 
 const logger = DebugLogger.module('ContextCompressor');
 
+// ==================== Token 估算 ====================
+
+const CHARS_PER_TOKEN = 3.2;
+const MESSAGE_OVERHEAD_TOKENS = 4;
+
+function estimateStringTokens(s: string): number {
+  if (!s) return 0;
+  return Math.ceil(s.length / CHARS_PER_TOKEN);
+}
+
+export function estimateMessageTokens(msg: StandardMessage): number {
+  let tokens = MESSAGE_OVERHEAD_TOKENS;
+  tokens += estimateStringTokens(msg.content);
+
+  if (msg.toolCalls) {
+    for (const tc of msg.toolCalls) {
+      tokens += estimateStringTokens(tc.name);
+      tokens += estimateStringTokens(tc.arguments);
+      tokens += 10;
+    }
+  }
+
+  if (msg.images) {
+    tokens += msg.images.length * 85;
+  }
+
+  return tokens;
+}
+
+export function estimateTotalTokens(messages: StandardMessage[]): number {
+  let total = 3;
+  for (const msg of messages) {
+    total += estimateMessageTokens(msg);
+  }
+  return total;
+}
+
 // ==================== 配置 ====================
 
-/** 压缩配置 */
 export interface CompactConfig {
-  /**
-   * 字符数阈值，超过此值触发压缩
-   * 
-   * 使用字符数而非 token 数（粗略估计：1 token ≈ 3-4 中文字符 / 4 英文字符）。
-   * 80K 字符 ≈ 20K-27K tokens，约为最小 context window (128K tokens) 的 15-20%。
-   * 
-   * @default 80_000
-   */
-  charThreshold?: number;
-
-  /**
-   * 压缩后保留的最近消息数
-   * 
-   * 保留最近的消息对（assistant + tool），确保模型有足够上下文继续工作。
-   * 
-   * @default 10
-   */
+  contextWindowTokens: number;
+  maxOutputTokens: number;
+  /** 触发压缩的使用率，默认 0.80 */
+  compactThresholdRatio?: number;
+  /** 压缩后保留的最近消息数，默认 6 */
   keepRecentMessages?: number;
 }
 
-const DEFAULT_CHAR_THRESHOLD = 80_000;
-const DEFAULT_KEEP_RECENT = 10;
+const DEFAULT_THRESHOLD_RATIO = 0.80;
+const DEFAULT_KEEP_RECENT = 6;
 
 // ==================== 核心函数 ====================
 
+/** 计算可用 prompt token 预算 */
+export function getPromptBudget(config: CompactConfig): number {
+  const ratio = config.compactThresholdRatio ?? DEFAULT_THRESHOLD_RATIO;
+  return Math.floor(config.contextWindowTokens * ratio) - config.maxOutputTokens;
+}
+
+/** 检测是否需要压缩 */
+export function needsCompaction(messages: StandardMessage[], config: CompactConfig): boolean {
+  return estimateTotalTokens(messages) > getPromptBudget(config);
+}
+
 /**
- * 压缩消息历史
- * 
- * 当消息总字符数超过阈值时，保留首尾、压缩中间部分。
- * 
- * @param messages - 消息数组（会被原地修改）
- * @param config - 压缩配置（可选）
- * @returns 是否执行了压缩
+ * 构建发给 AI 的总结请求
+ *
+ * 返回一组消息，发给当前模型让它总结对话历史。
+ * 总结完成后调用 applySummary 组装新的消息列表。
  */
-export function compactMessages(messages: StandardMessage[], config?: CompactConfig): boolean {
-  const charThreshold = config?.charThreshold ?? DEFAULT_CHAR_THRESHOLD;
-  const keepRecent = config?.keepRecentMessages ?? DEFAULT_KEEP_RECENT;
-
-  // 计算总字符数
-  const totalChars = messages.reduce((sum, m) => sum + (m.content?.length ?? 0), 0);
-  
-  if (totalChars < charThreshold) {
-    return false;
-  }
-  
-  logger.info(`Context 压缩触发: ${totalChars} 字符, ${messages.length} 条消息`);
-  
-  // ---- 找到各段边界 ----
-  // [0..systemEnd):       system prompt（可能没有）
-  // [systemEnd..firstUserEnd): 第一条 user 消息
-  // [firstUserEnd..recentStart): 中间的 assistant/tool 交互（压缩目标）
-  // [recentStart..end):   最近 N 条消息（保留）
-  
+export function buildSummarizeRequest(
+  messages: StandardMessage[],
+  config: CompactConfig,
+): { summarizeMessages: StandardMessage[]; keepMessages: StandardMessage[] } {
+  const keepRecent = config.keepRecentMessages ?? DEFAULT_KEEP_RECENT;
+
+  // 找边界
   let systemEnd = 0;
-  if (messages[0]?.role === 'system') {
-    systemEnd = 1;
-  }
-  
-  // 找到第一条 user 消息
+  if (messages[0]?.role === 'system') systemEnd = 1;
+
   let firstUserEnd = systemEnd;
   for (let i = systemEnd; i < messages.length; i++) {
     if (messages[i].role === 'user') {
@@ -88,62 +100,118 @@ export function compactMessages(messages: StandardMessage[], config?: CompactCon
       break;
     }
   }
-  
+
+  // 要保留的最近消息
   const recentStart = Math.max(firstUserEnd, messages.length - keepRecent);
-  
-  // 中间部分太短，不值得压缩
-  if (recentStart - firstUserEnd < 4) {
-    return false;
-  }
-  
-  // ---- 生成摘要 ----
+  const keepMessages = messages.slice(recentStart);
+
+  // 要被总结的中间历史
   const middleMessages = messages.slice(firstUserEnd, recentStart);
-  const summary = buildSummary(middleMessages);
-  
-  // ---- 组装压缩后的消息 ----
-  const compressed: StandardMessage[] = [
-    ...messages.slice(0, firstUserEnd),   // system + first user
-    { role: 'system', content: summary }, // 压缩摘要
-    ...messages.slice(recentStart),       // 最近 N 条
+
+  if (middleMessages.length < 2) {
+    // 中间太短，没什么可总结的
+    return { summarizeMessages: [], keepMessages: messages.slice(systemEnd) };
+  }
+
+  const estimatedTokens = estimateTotalTokens(messages);
+  const budget = getPromptBudget(config);
+  logger.info(`准备 AI 总结: ~${estimatedTokens} tokens > budget ${budget}, 总结 ${middleMessages.length} 条中间消息, 保留最近 ${keepMessages.length} 条`);
+
+  // 构建总结请求：把中间历史交给模型
+  const summarizeMessages: StandardMessage[] = [
+    {
+      role: 'system',
+      content: SUMMARIZE_SYSTEM_PROMPT,
+    },
+    {
+      role: 'user',
+      content: formatMessagesForSummary(middleMessages),
+    },
   ];
-  
-  const compressedChars = compressed.reduce((s, m) => s + (m.content?.length ?? 0), 0);
-  logger.info(`Context 压缩完成: ${messages.length} → ${compressed.length} 条消息, ${totalChars} → ${compressedChars} 字符`);
-  
-  // 原地替换
-  messages.length = 0;
-  messages.push(...compressed);
-  
-  return true;
-}
 
-// ==================== 内部函数 ====================
+  return { summarizeMessages, keepMessages };
+}
 
 /**
- * 从中间消息中构建压缩摘要
+ * 用 AI 返回的摘要组装新的消息列表
  */
-function buildSummary(middleMessages: StandardMessage[]): string {
-  const toolCallNames: string[] = [];
-  let textPreview = '';
-  
-  for (const msg of middleMessages) {
-    if (msg.role === 'assistant' && msg.toolCalls) {
-      for (const tc of msg.toolCalls) {
-        toolCallNames.push(tc.name);
-      }
+export function applySummary(
+  originalMessages: StandardMessage[],
+  summary: string,
+  keepMessages: StandardMessage[],
+): StandardMessage[] {
+  // 取原始的 system prompt
+  const systemPrompt = originalMessages[0]?.role === 'system' ? originalMessages[0] : null;
+
+  // 取第一条 user 消息
+  const startIdx = systemPrompt ? 1 : 0;
+  let firstUser: StandardMessage | null = null;
+  for (let i = startIdx; i < originalMessages.length; i++) {
+    if (originalMessages[i].role === 'user') {
+      firstUser = originalMessages[i];
+      break;
     }
-    if (msg.role === 'assistant' && msg.content) {
-      textPreview += msg.content.slice(0, 200) + '\n';
+  }
+
+  const result: StandardMessage[] = [];
+  if (systemPrompt) result.push(systemPrompt);
+  if (firstUser) result.push(firstUser);
+
+  // 插入 AI 生成的摘要
+  result.push({
+    role: 'system',
+    content: `[对话历史摘要]\n${summary}`,
+  });
+
+  // 拼上最近保留的消息
+  result.push(...keepMessages);
+
+  const tokens = estimateTotalTokens(result);
+  logger.info(`AI 总结应用完成: ${originalMessages.length} → ${result.length} 条消息, ~${tokens} tokens`);
+
+  return result;
+}
+
+// ==================== 内部 ====================
+
+const SUMMARIZE_SYSTEM_PROMPT = `你是一个对话历史压缩助手。请总结以下对话历史，保留所有关键信息：
+
+要求：
+1. 保留所有文件修改记录（哪些文件被创建/修改/删除了，具体改了什么）
+2. 保留所有关键决策和结论
+3. 保留错误信息和解决方案
+4. 保留用户的明确要求和偏好
+5. 用简洁的条目列表格式输出
+6. 不要遗漏任何可能影响后续工作的信息
+
+直接输出摘要，不要开头说"以下是摘要"之类的话。`;
+
+/** 把消息列表格式化为可读文本，供总结用 */
+function formatMessagesForSummary(messages: StandardMessage[]): string {
+  const parts: string[] = [];
+
+  for (const msg of messages) {
+    const role = msg.role === 'assistant' ? 'AI' : msg.role === 'user' ? '用户' : '工具';
+
+    if (msg.role === 'assistant' && msg.toolCalls && msg.toolCalls.length > 0) {
+      const calls = msg.toolCalls.map(tc => {
+        const argsPreview = tc.arguments.length > 200
+          ? tc.arguments.slice(0, 200) + '...'
+          : tc.arguments;
+        return `  调用 ${tc.name}(${argsPreview})`;
+      }).join('\n');
+      const text = msg.content ? `${msg.content}\n${calls}` : calls;
+      parts.push(`[${role}]\n${text}`);
+    } else if (msg.role === 'tool') {
+      // tool result 保留前 1000 字符（总结模型能看到足够信息）
+      const content = msg.content.length > 1000
+        ? msg.content.slice(0, 1000) + `... (共 ${msg.content.length} 字符)`
+        : msg.content;
+      parts.push(`[${role}: ${msg.toolName ?? 'unknown'}]\n${content}`);
+    } else if (msg.content) {
+      parts.push(`[${role}]\n${msg.content}`);
     }
   }
-  
-  return [
-    `[上下文压缩] 以下是之前 ${middleMessages.length} 条消息的摘要：`,
-    toolCallNames.length > 0
-      ? `- 执行了 ${toolCallNames.length} 次工具调用: ${[...new Set(toolCallNames)].join(', ')}`
-      : '',
-    textPreview
-      ? `- AI 回复摘要: ${textPreview.slice(0, 500)}`
-      : '',
-  ].filter(Boolean).join('\n');
+
+  return parts.join('\n\n---\n\n');
 }