Fix type (#1242)

* 完善所有用到的type对象，并添加中文注释

* 补充遗失的type

* 修复claude-for-chrome-mcp中的type和interface类型缺失

* 完善注释

packages/@ant/claude-for-chrome-mcp/src/bridgeClient.ts

@@ -9,6 +9,7 @@ import { SocketConnectionError } from './mcpSocketClient.js'
 import {
   localPlatformLabel,
   type BridgePermissionRequest,
+  toLoggerDetail,
   type ChromeExtensionInfo,
   type ClaudeForChromeContext,
   type PermissionMode,
@@ -578,7 +579,7 @@ export class BridgeClient implements SocketClient {
       const durationMs = Date.now() - this.connectionStartTime
       logger.error(
         `[${serverName}] Failed to create WebSocket after ${durationMs}ms:`,
-        error,
+        toLoggerDetail(error),
       )
       trackEvent?.('chrome_bridge_connection_failed', {
         duration_ms: durationMs,
@@ -618,7 +619,10 @@ export class BridgeClient implements SocketClient {
         )
         this.handleMessage(message)
       } catch (error) {
-        logger.error(`[${serverName}] Failed to parse bridge message:`, error)
+        logger.error(
+          `[${serverName}] Failed to parse bridge message:`,
+          toLoggerDetail(error),
+        )
       }
     })
 
@@ -862,7 +866,10 @@ export class BridgeClient implements SocketClient {
       const allowed = await pending.onPermissionRequest(request)
       this.sendPermissionResponse(requestId, allowed)
     } catch (error) {
-      logger.error(`[${serverName}] Error handling permission request:`, error)
+      logger.error(
+        `[${serverName}] Error handling permission request:`,
+        toLoggerDetail(error),
+      )
       this.sendPermissionResponse(requestId, false)
     }
   }

packages/@ant/claude-for-chrome-mcp/src/index.ts

@@ -8,8 +8,11 @@ export { localPlatformLabel } from './types.js'
 export type {
   BridgeConfig,
   ChromeExtensionInfo,
+  ChromeBridgeTrackEventMetadata,
   ClaudeForChromeContext,
   Logger,
+  LoggerDetail,
   PermissionMode,
   SocketClient,
 } from './types.js'
+export { toLoggerDetail } from './types.js'

packages/@ant/claude-for-chrome-mcp/src/mcpSocketClient.ts

@@ -9,6 +9,7 @@ import type {
   PermissionMode,
   PermissionOverrides,
 } from './types.js'
+import { toLoggerDetail } from './types.js'
 
 export class SocketConnectionError extends Error {
   constructor(message: string) {
@@ -87,7 +88,10 @@ class McpSocketClient {
       await this.validateSocketSecurity(socketPath)
     } catch (error) {
       this.connecting = false
-      logger.info(`[${serverName}] Security validation failed:`, error)
+      logger.info(
+        `[${serverName}] Security validation failed:`,
+        toLoggerDetail(error),
+      )
       // Don't retry on security failures (wrong perms/owner) - those won't
       // self-resolve. Only the error handler retries on transient errors.
       return
@@ -145,14 +149,20 @@ class McpSocketClient {
             logger.info(`[${serverName}] Received unknown message: ${message}`)
           }
         } catch (error) {
-          logger.info(`[${serverName}] Failed to parse message:`, error)
+          logger.info(
+            `[${serverName}] Failed to parse message:`,
+            toLoggerDetail(error),
+          )
         }
       }
     })
 
     this.socket.on('error', (error: Error & { code?: string }) => {
       clearTimeout(connectTimeout)
-      logger.info(`[${serverName}] Socket error (code: ${error.code}):`, error)
+      logger.info(
+        `[${serverName}] Socket error (code: ${error.code}):`,
+        toLoggerDetail(error),
+      )
       this.connected = false
       this.connecting = false
 

packages/@ant/claude-for-chrome-mcp/src/toolCalls.ts

@@ -7,6 +7,7 @@ import type {
   PermissionOverrides,
   SocketClient,
 } from './types.js'
+import { toLoggerDetail } from './types.js'
 
 export const handleToolCall = async (
   context: ClaudeForChromeContext,
@@ -44,7 +45,10 @@ export const handleToolCall = async (
 
     return handleToolCallDisconnected(context)
   } catch (error) {
-    context.logger.info(`[${context.serverName}] Error calling tool:`, error)
+    context.logger.info(
+      `[${context.serverName}] Error calling tool:`,
+      toLoggerDetail(error),
+    )
 
     if (error instanceof SocketConnectionError) {
       return handleToolCallDisconnected(context)
@@ -165,8 +169,7 @@ async function handleToolCallConnected(
 
   // Fallback for unexpected result format
   context.logger.warn(
-    `[${context.serverName}] Unexpected result format from socket bridge`,
-    response,
+    `[${context.serverName}] Unexpected result format from socket bridge: ${JSON.stringify(response)}`,
   )
 
   return {

packages/@ant/claude-for-chrome-mcp/src/types.ts

@@ -1,11 +1,84 @@
-export interface Logger {
-  info: (message: string, ...args: unknown[]) => void
-  error: (message: string, ...args: unknown[]) => void
-  warn: (message: string, ...args: unknown[]) => void
-  debug: (message: string, ...args: unknown[]) => void
-  silly: (message: string, ...args: unknown[]) => void
+/**
+ * Logger 第二参数的可选类型。
+ * 调用方通过 util.format 追加详情，实践中多为 catch 到的异常对象。
+ */
+export type LoggerDetail = Error | NodeJS.ErrnoException
+
+/** 将 unknown 收窄为 LoggerDetail，供 catch 块传给 logger 使用。 */
+export function toLoggerDetail(detail: unknown): LoggerDetail | undefined {
+  return detail instanceof Error ? detail : undefined
 }
 
+/** 宿主注入的日志接口，与 DebugLogger（util.format）对齐。 */
+export interface Logger {
+  info: (message: string, detail?: LoggerDetail) => void // 信息
+  error: (message: string, detail?: LoggerDetail) => void // 错误
+  warn: (message: string, detail?: LoggerDetail) => void // 警告
+  debug: (message: string, detail?: LoggerDetail) => void // 调试
+  silly: (message: string, detail?: LoggerDetail) => void // 最细粒度调试
+}
+
+/**
+ * Bridge 连接失败时的 error_type 枚举。
+ * 由 bridgeClient 在 getUserId / getOAuthToken / WebSocket 创建失败时上报。
+ */
+export type ChromeBridgeConnectionErrorType =
+  | 'no_user_id' // 无法获取用户 UUID
+  | 'no_oauth_token' // 无法获取 OAuth token
+  | 'websocket_error' // WebSocket 创建或运行异常
+
+/** 工具调用相关遥测元数据（started / completed / timeout / error）。 */
+export type ChromeBridgeToolCallMetadata = {
+  tool_name: string // MCP 工具名
+  tool_use_id: string // 本次调用的 UUID
+  duration_ms?: number // 耗时（毫秒）
+  timeout_ms?: number // 超时阈值（毫秒），仅 timeout 事件
+  error_message?: string // 错误摘要（截断），仅 error 事件
+}
+
+/** Bridge 连接失败遥测元数据。 */
+export type ChromeBridgeConnectionFailedMetadata = {
+  duration_ms: number // 自连接开始到失败的耗时（毫秒）
+  error_type: ChromeBridgeConnectionErrorType // 失败原因分类
+  reconnect_attempt: number // 当前重连尝试次数
+}
+
+/** Bridge 开始连接遥测元数据。 */
+export type ChromeBridgeConnectionStartedMetadata = {
+  bridge_url: string // 目标 WebSocket URL（含用户路径）
+}
+
+/** Bridge 断开连接遥测元数据。 */
+export type ChromeBridgeDisconnectedMetadata = {
+  close_code: number // WebSocket 关闭码
+  duration_since_connect_ms: number // 自连接成功到断开的时长（毫秒）
+  reconnect_attempt: number // 即将进行的重连序号
+}
+
+/** Bridge 连接成功遥测元数据。 */
+export type ChromeBridgeConnectionSucceededMetadata = {
+  duration_ms: number // 自开始到连接就绪的耗时（毫秒）
+  status: 'paired' | 'waiting' // paired=已配对扩展；waiting=等待扩展接入
+}
+
+/** Bridge 重连次数耗尽遥测元数据。 */
+export type ChromeBridgeReconnectExhaustedMetadata = {
+  total_attempts: number // 累计重连次数上限
+}
+
+/**
+ * trackEvent 回调的 metadata 联合类型。
+ * 各变体对应 bridgeClient 内 chrome_bridge_* 事件；null 表示无附加字段。
+ */
+export type ChromeBridgeTrackEventMetadata =
+  | ChromeBridgeToolCallMetadata
+  | ChromeBridgeConnectionFailedMetadata
+  | ChromeBridgeConnectionStartedMetadata
+  | ChromeBridgeDisconnectedMetadata
+  | ChromeBridgeConnectionSucceededMetadata
+  | ChromeBridgeReconnectExhaustedMetadata
+  | null // 无元数据（如 peer_connected / peer_disconnected）
+
 export type PermissionMode =
   | 'ask'
   | 'skip_all_permission_checks'
@@ -48,10 +121,10 @@ export interface ClaudeForChromeContext {
   bridgeConfig?: BridgeConfig
   /** If set, permission mode is sent to the extension immediately on bridge connection. */
   initialPermissionMode?: PermissionMode
-  /** Optional callback to track telemetry events for bridge connections */
-  trackEvent?: <K extends string>(
-    eventName: K,
-    metadata: Record<string, unknown> | null,
+  /** Bridge 遥测回调；eventName 为 chrome_bridge_* 事件名 */
+  trackEvent?: (
+    eventName: string, // 事件名
+    metadata: ChromeBridgeTrackEventMetadata, // 事件元数据
   ) => void
   /** Called when user pairs with an extension via the browser pairing flow. */
   onExtensionPaired?: (deviceId: string, name: string) => void