完善注释

Author: xiaoFjun-eng

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

@@ -1,65 +1,83 @@
-/** Optional util.format detail; call sites pass caught exceptions. */
+/**
+ * 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
+  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'
-  | 'no_oauth_token'
-  | 'websocket_error'
+  | 'no_user_id' // 无法获取用户 UUID
+  | 'no_oauth_token' // 无法获取 OAuth token
+  | 'websocket_error' // WebSocket 创建或运行异常
 
-/** Metadata shapes emitted by bridgeClient trackEvent calls. */
+/** 工具调用相关遥测元数据（started / completed / timeout / error）。 */
 export type ChromeBridgeToolCallMetadata = {
-  tool_name: string
-  tool_use_id: string
-  duration_ms?: number
-  timeout_ms?: number
-  error_message?: string
+  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
+  duration_ms: number // 自连接开始到失败的耗时（毫秒）
+  error_type: ChromeBridgeConnectionErrorType // 失败原因分类
+  reconnect_attempt: number // 当前重连尝试次数
 }
 
+/** Bridge 开始连接遥测元数据。 */
 export type ChromeBridgeConnectionStartedMetadata = {
-  bridge_url: string
+  bridge_url: string // 目标 WebSocket URL（含用户路径）
 }
 
+/** Bridge 断开连接遥测元数据。 */
 export type ChromeBridgeDisconnectedMetadata = {
-  close_code: number
-  duration_since_connect_ms: number
-  reconnect_attempt: number
+  close_code: number // WebSocket 关闭码
+  duration_since_connect_ms: number // 自连接成功到断开的时长（毫秒）
+  reconnect_attempt: number // 即将进行的重连序号
 }
 
+/** Bridge 连接成功遥测元数据。 */
 export type ChromeBridgeConnectionSucceededMetadata = {
-  duration_ms: number
-  status: 'paired' | 'waiting'
+  duration_ms: number // 自开始到连接就绪的耗时（毫秒）
+  status: 'paired' | 'waiting' // paired=已配对扩展；waiting=等待扩展接入
 }
 
+/** Bridge 重连次数耗尽遥测元数据。 */
 export type ChromeBridgeReconnectExhaustedMetadata = {
-  total_attempts: number
+  total_attempts: number // 累计重连次数上限
 }
 
+/**
+ * trackEvent 回调的 metadata 联合类型。
+ * 各变体对应 bridgeClient 内 chrome_bridge_* 事件；null 表示无附加字段。
+ */
 export type ChromeBridgeTrackEventMetadata =
   | ChromeBridgeToolCallMetadata
   | ChromeBridgeConnectionFailedMetadata
   | ChromeBridgeConnectionStartedMetadata
   | ChromeBridgeDisconnectedMetadata
   | ChromeBridgeConnectionSucceededMetadata
   | ChromeBridgeReconnectExhaustedMetadata
-  | null
+  | null // 无元数据（如 peer_connected / peer_disconnected）
 
 export type PermissionMode =
   | 'ask'
@@ -103,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 */
+  /** Bridge 遥测回调；eventName 为 chrome_bridge_* 事件名 */
   trackEvent?: (
-    eventName: string,
-    metadata: ChromeBridgeTrackEventMetadata,
+    eventName: string, // 事件名
+    metadata: ChromeBridgeTrackEventMetadata, // 事件元数据
   ) => void
   /** Called when user pairs with an extension via the browser pairing flow. */
   onExtensionPaired?: (deviceId: string, name: string) => void

packages/@ant/computer-use-mcp/src/types.ts

@@ -8,19 +8,24 @@ import type {
  *  cross-respawn `scaleCoord` survival. */
 export type ScreenshotDims = Omit<ScreenshotResult, 'base64'>
 
-/** Shape mirrors claude-for-chrome-mcp/src/types.ts Logger */
+/**
+ * Logger 第二参数的可选类型（与 claude-for-chrome-mcp 对齐）。
+ * 实践中多为 catch 到的 Error。
+ */
 export type LoggerDetail = Error | NodeJS.ErrnoException
 
+/** 将 unknown 收窄为 LoggerDetail，供 catch 块传给 logger 使用。 */
 export function toLoggerDetail(detail: unknown): LoggerDetail | undefined {
   return detail instanceof Error ? detail : undefined
 }
 
+/** 宿主注入的日志接口（与 claude-for-chrome-mcp/src/types.ts 对齐）。 */
 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
+  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 // 最细粒度调试
 }
 
 /**

packages/@ant/ink/src/core/dom.ts

@@ -46,10 +46,9 @@ export type DOMElement = {
   dirty: boolean
   // Set by the reconciler's hideInstance/unhideInstance; survives style updates.
   isHidden?: boolean
-  // Event handlers set by the reconciler for the capture/bubble dispatcher.
-  // Stored separately from attributes so handler identity changes don't
-  // mark dirty and defeat the blit optimization.
-  _eventHandlers?: Partial<EventHandlerProps>
+  // 协调器写入的事件处理器（捕获/冒泡分发用）。
+  // 与 attributes 分离，避免 handler 引用变化触发 dirty 破坏 blit 优化。
+  _eventHandlers?: Partial<EventHandlerProps> // 见 event-handlers.ts EventHandlerProps
 
   // Scroll state for overflow: 'scroll' boxes. scrollTop is the number of
   // rows the content is scrolled down by. scrollHeight/scrollViewportHeight

packages/@ant/ink/src/core/events/terminal-event.ts

@@ -103,7 +103,8 @@ export class TerminalEvent extends Event {
 
 import type { EventHandlerProps } from './event-handlers.js'
 
+/** 终端事件系统的目标节点（DOM 树节点或根节点）。 */
 export type EventTarget = {
-  parentNode: EventTarget | undefined
-  _eventHandlers?: Partial<EventHandlerProps>
+  parentNode: EventTarget | undefined // 父节点，根节点为 undefined
+  _eventHandlers?: Partial<EventHandlerProps> // 事件处理器，与 dom.ts DOMElement 同构
 }