fix(error): API 错误信息友好化，不再向用户暴露完整堆栈

- 新增 extractApiErrorMessage：从 RetryError/APICallError 嵌套结构中提取根因
- 优先解析 responseBody 中的原始错误消息（如"号池见底，无法注册"）
- Agent 中 logger.error 改为 logger.debug 避免堆栈打到终端
- useCommandHandler 和 headless 模式同步优化

Author: echoVic

packages/cli/src/agent/Agent.ts

@@ -86,6 +86,46 @@ import type {
 // 创建 Agent 专用 Logger
 const logger = createLogger(LogCategory.AGENT);
 
+/**
+ * 从 API 错误中提取用户友好的错误信息
+ * 处理 Vercel AI SDK 的 RetryError 和 APICallError 嵌套结构
+ */
+function extractApiErrorMessage(error: unknown): string {
+  if (!(error instanceof Error)) return '未知错误';
+
+  // Vercel AI SDK RetryError: 从嵌套的 lastError/cause 中提取根因
+  const retryError = error as Error & { lastError?: Error; reason?: string };
+  const rootError = retryError.lastError ?? error;
+
+  // APICallError: 尝试从 responseBody 解析原始错误消息
+  const apiError = rootError as Error & {
+    responseBody?: string;
+    statusCode?: number;
+  };
+
+  if (apiError.responseBody) {
+    try {
+      const body = JSON.parse(apiError.responseBody);
+      const msg = body?.error?.message;
+      if (msg) {
+        const statusHint = apiError.statusCode ? ` (HTTP ${apiError.statusCode})` : '';
+        return `${msg}${statusHint}`;
+      }
+    } catch {
+      // JSON 解析失败，fallback
+    }
+  }
+
+  // 清理 RetryError 的冗长前缀
+  const message = error.message;
+  const lastErrorMatch = message.match(/Last error:\s*(.+)$/);
+  if (lastErrorMatch) {
+    return lastErrorMatch[1];
+  }
+
+  return message;
+}
+
 /**
  * Skill 执行上下文
  * 用于跟踪当前活动的 Skill 及其工具限制
@@ -1584,12 +1624,15 @@ IMPORTANT: Execute according to the approved plan above. Follow the steps exactl
         };
       }
 
-      logger.error('Enhanced chat processing error:', error);
+      // 只在 debug 模式下打印完整堆栈，避免用户看到巨大的错误信息
+      logger.debug('Enhanced chat processing error (full):', error);
+      const friendlyMessage = extractApiErrorMessage(error);
+      logger.error(`API 调用失败: ${friendlyMessage}`);
       return {
         success: false,
         error: {
           type: 'api_error',
-          message: `处理消息时发生错误: ${error instanceof Error ? error.message : '未知错误'}`,
+          message: friendlyMessage,
           details: error,
         },
         metadata: {

packages/cli/src/commands/headless.ts

@@ -213,6 +213,34 @@ function createConfirmationHandler() {
   };
 }
 
+/**
+ * 从 API 错误中提取用户友好的错误信息
+ */
+function extractHeadlessErrorMessage(error: unknown): string {
+  if (!(error instanceof Error)) return 'Unknown error';
+
+  const retryError = error as Error & { lastError?: Error };
+  const rootError = retryError.lastError ?? error;
+  const apiError = rootError as Error & { responseBody?: string; statusCode?: number };
+
+  if (apiError.responseBody) {
+    try {
+      const body = JSON.parse(apiError.responseBody);
+      const msg = body?.error?.message;
+      if (msg) {
+        return apiError.statusCode ? `${msg} (HTTP ${apiError.statusCode})` : msg;
+      }
+    } catch {
+      // fallback
+    }
+  }
+
+  const lastErrorMatch = error.message.match(/Last error:\s*(.+)$/);
+  if (lastErrorMatch) return lastErrorMatch[1];
+
+  return error.message;
+}
+
 function resolveOutputFormat(outputFormat?: string): HeadlessOutputFormat {
   return outputFormat === 'jsonl' ? 'jsonl' : 'text';
 }
@@ -492,7 +520,7 @@ export async function runHeadless(
     if (streamState.hasOpenThinking() && outputFormat === 'text') {
       io.stderr.write('\n');
     }
-    eventWriter.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    eventWriter.error(`Error: ${extractHeadlessErrorMessage(error)}`);
     return 1;
   }
 }

packages/cli/src/ui/hooks/useCommandHandler.ts

@@ -40,6 +40,45 @@ import type { ResolvedInput } from './useInputBuffer.js';
 // 创建 UI Hook 专用 Logger
 const logger = createLogger(LogCategory.UI);
 
+/**
+ * 从 API 错误中提取用户友好的错误信息
+ * 处理 Vercel AI SDK 的 RetryError/APICallError 嵌套结构
+ */
+function extractFriendlyErrorMessage(error: unknown): string {
+  if (!(error instanceof Error)) return '未知错误';
+
+  // Vercel AI SDK RetryError: 从嵌套的 lastError 中提取根因
+  const retryError = error as Error & { lastError?: Error };
+  const rootError = retryError.lastError ?? error;
+
+  // APICallError: 尝试从 responseBody 解析原始错误消息
+  const apiError = rootError as Error & {
+    responseBody?: string;
+    statusCode?: number;
+  };
+
+  if (apiError.responseBody) {
+    try {
+      const body = JSON.parse(apiError.responseBody);
+      const msg = body?.error?.message;
+      if (msg) {
+        const statusHint = apiError.statusCode ? ` (HTTP ${apiError.statusCode})` : '';
+        return `${msg}${statusHint}`;
+      }
+    } catch {
+      // JSON 解析失败，fallback
+    }
+  }
+
+  // 清理 RetryError 的冗长前缀
+  const lastErrorMatch = error.message.match(/Last error:\s*(.+)$/);
+  if (lastErrorMatch) {
+    return lastErrorMatch[1];
+  }
+
+  return error.message;
+}
+
 /**
  * invoke_skill action 的数据类型
  */
@@ -891,15 +930,16 @@ Remember: Follow the above instructions carefully to complete the user's request
           return { success: false, error: 'aborted' };
         }
 
-        const errorMessage = error instanceof Error ? error.message : '未知错误';
+        const errorMessage = extractFriendlyErrorMessage(error);
 
         // 检测是否是图片/多模态不支持的错误
+        const rawMessage = error instanceof Error ? error.message : '';
         const isVisionNotSupportedError =
-          errorMessage.includes('can only concatenate str') ||
-          errorMessage.includes('image_url') ||
-          errorMessage.includes('multimodal') ||
-          errorMessage.includes('vision') ||
-          errorMessage.includes('does not support images');
+          rawMessage.includes('can only concatenate str') ||
+          rawMessage.includes('image_url') ||
+          rawMessage.includes('multimodal') ||
+          rawMessage.includes('vision') ||
+          rawMessage.includes('does not support images');
 
         let displayMessage = errorMessage;
         if (isVisionNotSupportedError) {