|
| 1 | +/** |
| 2 | + * Logger 第二参数的可选类型。 |
| 3 | + * 调用方通过 util.format 追加详情，实践中多为 catch 到的异常对象。 |
| 4 | + */ |
| 5 | +export type LoggerDetail = Error | NodeJS.ErrnoException |
| 6 | + |
| 7 | +/** 将 unknown 收窄为 LoggerDetail，供 catch 块传给 logger 使用。 */ |
| 8 | +export function toLoggerDetail(detail: unknown): LoggerDetail | undefined { |
| 9 | + return detail instanceof Error ? detail : undefined |
| 10 | +} |
| 11 | + |
| 12 | +/** 宿主注入的日志接口，与 DebugLogger（util.format）对齐。 */ |
1 | 13 | export interface Logger { |
2 | | - info: (message: string, ...args: unknown[]) => void |
3 | | - error: (message: string, ...args: unknown[]) => void |
4 | | - warn: (message: string, ...args: unknown[]) => void |
5 | | - debug: (message: string, ...args: unknown[]) => void |
6 | | - silly: (message: string, ...args: unknown[]) => void |
| 14 | + info: (message: string, detail?: LoggerDetail) => void // 信息 |
| 15 | + error: (message: string, detail?: LoggerDetail) => void // 错误 |
| 16 | + warn: (message: string, detail?: LoggerDetail) => void // 警告 |
| 17 | + debug: (message: string, detail?: LoggerDetail) => void // 调试 |
| 18 | + silly: (message: string, detail?: LoggerDetail) => void // 最细粒度调试 |
| 19 | +} |
| 20 | + |
| 21 | +/** |
| 22 | + * Bridge 连接失败时的 error_type 枚举。 |
| 23 | + * 由 bridgeClient 在 getUserId / getOAuthToken / WebSocket 创建失败时上报。 |
| 24 | + */ |
| 25 | +export type ChromeBridgeConnectionErrorType = |
| 26 | + | 'no_user_id' // 无法获取用户 UUID |
| 27 | + | 'no_oauth_token' // 无法获取 OAuth token |
| 28 | + | 'websocket_error' // WebSocket 创建或运行异常 |
| 29 | + |
| 30 | +/** 工具调用相关遥测元数据（started / completed / timeout / error）。 */ |
| 31 | +export type ChromeBridgeToolCallMetadata = { |
| 32 | + tool_name: string // MCP 工具名 |
| 33 | + tool_use_id: string // 本次调用的 UUID |
| 34 | + duration_ms?: number // 耗时（毫秒） |
| 35 | + timeout_ms?: number // 超时阈值（毫秒），仅 timeout 事件 |
| 36 | + error_message?: string // 错误摘要（截断），仅 error 事件 |
| 37 | +} |
| 38 | + |
| 39 | +/** Bridge 连接失败遥测元数据。 */ |
| 40 | +export type ChromeBridgeConnectionFailedMetadata = { |
| 41 | + duration_ms: number // 自连接开始到失败的耗时（毫秒） |
| 42 | + error_type: ChromeBridgeConnectionErrorType // 失败原因分类 |
| 43 | + reconnect_attempt: number // 当前重连尝试次数 |
7 | 44 | } |
8 | 45 |
|
| 46 | +/** Bridge 开始连接遥测元数据。 */ |
| 47 | +export type ChromeBridgeConnectionStartedMetadata = { |
| 48 | + bridge_url: string // 目标 WebSocket URL（含用户路径） |
| 49 | +} |
| 50 | + |
| 51 | +/** Bridge 断开连接遥测元数据。 */ |
| 52 | +export type ChromeBridgeDisconnectedMetadata = { |
| 53 | + close_code: number // WebSocket 关闭码 |
| 54 | + duration_since_connect_ms: number // 自连接成功到断开的时长（毫秒） |
| 55 | + reconnect_attempt: number // 即将进行的重连序号 |
| 56 | +} |
| 57 | + |
| 58 | +/** Bridge 连接成功遥测元数据。 */ |
| 59 | +export type ChromeBridgeConnectionSucceededMetadata = { |
| 60 | + duration_ms: number // 自开始到连接就绪的耗时（毫秒） |
| 61 | + status: 'paired' | 'waiting' // paired=已配对扩展；waiting=等待扩展接入 |
| 62 | +} |
| 63 | + |
| 64 | +/** Bridge 重连次数耗尽遥测元数据。 */ |
| 65 | +export type ChromeBridgeReconnectExhaustedMetadata = { |
| 66 | + total_attempts: number // 累计重连次数上限 |
| 67 | +} |
| 68 | + |
| 69 | +/** |
| 70 | + * trackEvent 回调的 metadata 联合类型。 |
| 71 | + * 各变体对应 bridgeClient 内 chrome_bridge_* 事件；null 表示无附加字段。 |
| 72 | + */ |
| 73 | +export type ChromeBridgeTrackEventMetadata = |
| 74 | + | ChromeBridgeToolCallMetadata |
| 75 | + | ChromeBridgeConnectionFailedMetadata |
| 76 | + | ChromeBridgeConnectionStartedMetadata |
| 77 | + | ChromeBridgeDisconnectedMetadata |
| 78 | + | ChromeBridgeConnectionSucceededMetadata |
| 79 | + | ChromeBridgeReconnectExhaustedMetadata |
| 80 | + | null // 无元数据（如 peer_connected / peer_disconnected） |
| 81 | + |
9 | 82 | export type PermissionMode = |
10 | 83 | | 'ask' |
11 | 84 | | 'skip_all_permission_checks' |
@@ -48,10 +121,10 @@ export interface ClaudeForChromeContext { |
48 | 121 | bridgeConfig?: BridgeConfig |
49 | 122 | /** If set, permission mode is sent to the extension immediately on bridge connection. */ |
50 | 123 | initialPermissionMode?: PermissionMode |
51 | | - /** Optional callback to track telemetry events for bridge connections */ |
52 | | - trackEvent?: <K extends string>( |
53 | | - eventName: K, |
54 | | - metadata: Record<string, unknown> | null, |
| 124 | + /** Bridge 遥测回调；eventName 为 chrome_bridge_* 事件名 */ |
| 125 | + trackEvent?: ( |
| 126 | + eventName: string, // 事件名 |
| 127 | + metadata: ChromeBridgeTrackEventMetadata, // 事件元数据 |
55 | 128 | ) => void |
56 | 129 | /** Called when user pairs with an extension via the browser pairing flow. */ |
57 | 130 | onExtensionPaired?: (deviceId: string, name: string) => void |
|
0 commit comments