遥测与用户画像

// services/analytics/index.ts

// 公共 API — 所有模块通过此函数上报事件
export function logEvent(
  eventName: string,
  eventProperties?: Record<string, unknown>,
  analyticsMetadata?: AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
): void

// 异步版本 — 支持需要 await 的元数据收集
export async function logEventAsync(
  eventName: string,
  eventProperties?: Record<string, unknown>,
  analyticsMetadata?: AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
): Promise<void>

// 类型标记：强制开发者显式验证字符串不含代码/文件路径
type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS = {
  [key: string]: string | boolean | number | null
}

// PII 标记：标记字段发送至特权 BigQuery 列
type AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED = {
  _PROTO_EMAIL?: string
  _PROTO_SKILL_NAME?: string
  _PROTO_PLUGIN_NAME?: string
  _PROTO_MARKETPLACE_NAME?: string
}

// Sink 未附加时 → 缓存到 eventQueue
// Sink 附加后 → 排空队列 + 后续事件直接分发
const eventQueue: QueuedEvent[] = []

// services/analytics/datadog.ts

const DATADOG_ENDPOINT = 'https://http-intake.logs.us5.datadoghq.com/api/v2/logs'
const DATADOG_CLIENT_TOKEN = 'pubbbf48e6d78dae54bceaa4acf463299bf' // 硬编码

// 批量配置
const FLUSH_INTERVAL_MS = 15_000   // 15 秒刷新
const MAX_BATCH_SIZE = 100         // 最大批次 100 条

// 白名单机制 — 仅发送以下事件
const DATADOG_ALLOWED_EVENTS = new Set([
  'chrome_bridge_*',          // Chrome 桥接
  'tengu_api_error',          // API 错误
  'tengu_init',               // 初始化
  'tengu_tool_use_success',   // 工具成功
  'tengu_tool_use_error',     // 工具失败
  'tengu_started',            // 启动
  // ... 共约 64 种
])

// 用户隐私桶 — SHA-256 哈希后取模
function getUserBucket(userId: string): number {
  const hash = createHash('sha256').update(userId).digest('hex')
  return parseInt(hash.slice(0, 8), 16) % 30
}

// 仅第一方提供商（排除 Bedrock/Vertex/Foundry）
if (!isFirstPartyProvider()) return  // 跳过第三方

// services/analytics/firstPartyEventLogger.ts

// 基于 OpenTelemetry LoggerProvider 构建
const provider = new LoggerProvider({
  resource: new Resource({
    'service.name': 'claude-code',
    'service.version': VERSION,
  }),
})
provider.addLogRecordProcessor(
  new BatchLogRecordProcessor(exporter, {
    scheduledDelayMillis: 5000,    // 5 秒刷新
    maxExportBatchSize: 512,       // 最大批次 512
    maxQueueSize: 2048,            // 队列上限 2048
  })
)

// 每个事件的结构
interface ClaudeCodeInternalEvent {
  event_id: string           // UUID
  core_metadata: {
    model: string            // 模型名称
    session_id: string       // 会话 ID
    user_type: string        // ant | external
    beta_features: string[]  // 启用的 beta 特性
    entrypoint: string       // cli | sdk | unknown
    interaction_mode: string // 交互模式
    client_type: string      // 客户端类型
    agent_id?: string        // Agent 标识
    agent_type?: string      // teammate | subagent | standalone
    team_name?: string       // 团队名
    subscription_type?: string  // max | pro | enterprise | team
  }
  user_metadata: {
    device_id: string        // 设备 ID
    session_id: string       // 会话 ID
    email?: string           // 用户邮箱（PII）
    app_version: string      // 应用版本
    platform: string         // 平台
    organization_uuid?: string
    account_uuid?: string
  }
  event_metadata: Record<string, unknown>  // 事件特有属性
}

// services/analytics/firstPartyEventLoggingExporter.ts

// 失败事件写入磁盘缓存
const FAILED_EVENTS_DIR = '~/.claude/telemetry/'
const FAILED_EVENTS_FILE = '1p_failed_events.*.json'

// 指数退避重试
const MAX_RETRIES = 8
const BASE_DELAY_MS = 1000  // 1s, 2s, 4s, 8s, 16s, 32s, 64s, 128s

async function exportWithRetry(events: LogRecord[]): Promise<void> {
  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
    try {
      await this.sendBatch(events)
      return
    } catch (error) {
      if (attempt === MAX_RETRIES - 1) {
        // 最终失败 → 写入磁盘缓存
        await this.persistFailedEvents(events)
        return
      }
      await this.delay(BASE_DELAY_MS * Math.pow(2, attempt))
    }
  }
}

// 支持动态配置（通过 GrowthBook）
// - 批次大小、延迟、端点 URL、采样率均可远程调整

// services/analytics/growthbook.ts

const gb = new GrowthBook({
  apiHost: 'https://api.anthropic.com/',
  remoteEval: true,     // 远程评估模式
  attributes: {         // 用户属性 — 实验分组依据
    id: userId,
    sessionId: sessionId,
    deviceID: deviceId,
    platform: platform,
    apiBaseUrlHost: apiHost,
    organizationUUID: orgUuid,
    accountUUID: accountUuid,
    userType: userType,              // ant | external
    subscriptionType: subscription,  // max | pro | enterprise | team
    rateLimitTier: tier,
    firstTokenTime: firstTokenTime,
    email: email,
    appVersion: version,
    github: {                         // CI 环境上下文
      eventName: ghEventName,
      repository: ghRepo,
      runnerEnvironment: ghRunner,
    },
  },
})

// 特性缓存到磁盘（~/.claude.json → cachedGrowthBookFeatures）
// 外部用户: 6 小时刷新
// Anth 内部: 20 分钟刷新

// 关键 Feature Gates
// tengu_log_datadog_events    — Datadog 管道总开关
// tengu_frond_boric           — 管道级熔断（datadog | firstParty）
// tengu_anti_distill_fake_tool_injection — 假工具注入开关
// tengu_thinking_redaction    — 思维链脱敏开关
// tengu_event_sampling_config — 事件采样率动态配置

// services/analytics/metadata.ts

interface EventMetadata {
  // 环境上下文 (EnvContext)
  env: {
    platform: string           // darwin | linux | win32
    arch: string               // x64 | arm64
    nodeVersion: string        // Node.js 版本
    terminal: string           // 终端类型
    packageManagers: string[]  // 检测到的包管理器
    runtimes: string[]         // Bun | Node
    isCi: boolean              // 是否 CI 环境
    version: string            // CC 版本
    buildTime: string          // 构建时间
    deploymentEnvironment: string
    wslVersion?: string        // WSL 版本
    linuxDistro?: string       // Linux 发行版
    vcs?: string               // git | none
    githubActions?: {          // GitHub Actions 元数据
      eventName: string
      repository: string
      actor: string
      ref: string
      runnerOS: string
    }
    remoteEnvironmentType?: string  // 远程环境类型
    containerId?: string            // 容器 ID
  }

  // 进程指标 (ProcessMetrics)
  process: {
    uptime: number             // 进程运行时间
    rss: number                // 常驻内存集
    heapTotal: number          // 堆总量
    heapUsed: number           // 堆使用量
    external: number           // 外部内存
    arrayBuffers: number       // ArrayBuffer 内存
    constrainedMemory?: number // 内存限制
    cpuUsage: number           // CPU 使用率(%)
  }

  // Agent 标识
  agentId?: string             // 当前 Agent ID
  parentSessionId?: string     // 父会话 ID
  agentType?: string           // teammate | subagent | standalone
  teamName?: string            // 团队名称
}

// 工具名称清洗 — MCP 工具名统一归一化
// 原始: "mcp__plugin_ecc_playwright__browser_click"
// 清洗后: "mcp_tool"（防止泄漏自定义插件名）
// 但存在白名单豁免：特定已知 MCP 工具保留原始名称

// 文件扩展名提取 — 从 Bash 命令中提取
// "sed -i 's/foo/bar/' config.yaml" → ".yaml"
// "python3 train.py && python3 eval.py" → ".py,.py"

// services/analytics/index.ts

// PII 字段用 _PROTO_ 前缀标记
interface PIIFields {
  _PROTO_EMAIL?: string         // 用户邮箱
  _PROTO_SKILL_NAME?: string    // Skill 名称
  _PROTO_PLUGIN_NAME?: string   // 插件名称
  _PROTO_MARKETPLACE_NAME?: string  // 市场名称
}

// Datadog 管道发送前：stripProtoFields() 剥离所有 _PROTO_* 字段
// 1P 管道发送前：保留 _PROTO_* 字段，写入 BigQuery 特权列
// 这确保 PII 数据只在内部数据仓库中可见，不会泄漏到 Datadog

// utils/privacyLevel.ts

type PrivacyLevel = 'default' | 'no-telemetry' | 'essential-traffic'

// default:       正常收集所有遥测数据
// no-telemetry:  禁用分析事件，保留必要 API 调用
// essential-traffic: 仅保留认证和 API 请求

// 控制方式：
// DISABLE_TELEMETRY=1 → no-telemetry
// CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 → essential-traffic

// 配置入口：
// commands/privacy-settings/privacy-settings.tsx
// → "Help improve Claude" (Grove) 开关
// → 记录 tengu_grove_policy_toggled 事件

// services/api/metricsOptOut.ts

// 查询组织是否启用了指标记录
// GET https://api.anthropic.com/api/claude_code/organizations/metrics_enabled
// 响应: { enabled: boolean }

// 缓存策略：
// - 磁盘缓存: 24 小时
// - 内存缓存: 1 小时
// → 避免每次启动都查询 API