AI 产品埋点设计：要记录模型前后的关键事件

// ❌ 坏做法：只记一个长度，无法区分「写了一半」和「精心构造」
posthog.capture('ai_generate_clicked', {
  input_length: prompt.length,
})
 
// ✅ 好做法：记录输入的多个质量维度
posthog.capture('ai_input_submitted', {
  input_length: prompt.length,
  // 输入中是否包含具体指令（而非空泛描述）
  has_specific_instruction: /请|帮我|生成|修改|翻译|总结/.test(prompt),
  // 是否附带了参考材料（如上传文件、选中上下文）
  has_context_attachment: attachments.length > 0,
  // 上下文来源类型：手动输入、模板填充、从文档选中、历史记录
  context_source: determineContextSource(inputMeta),
  // 输入语言（多语言产品必备）
  input_language: detectLanguage(prompt),
  // 历史重试次数——区分首次使用和反复重试
  retry_count: currentRetryCount,
})

// ❌ 坏做法：只记录「成功/失败」，丢失了关键的状态信息
posthog.capture('ai_generation_complete', {
  status: response.ok ? 'success' : 'error',
})
 
// ✅ 好做法：记录输出的多维状态
posthog.capture('ai_output_received', {
  // 模型版本——同一个功能可能同时跑 A/B 两个模型
  model_id: response.model,
  // 实际返回模型（提供商可能路由到不同版本）
  response_model: response.actualModel,
  // 完成原因：正常结束、触发长度限制、工具调用、内容过滤
  finish_reason: response.finishReason,
  // 输出 token 数
  output_tokens: response.usage.outputTokens,
  // 输入 token 数
  input_tokens: response.usage.inputTokens,
  // 首字延迟（用户感知速度的关键指标）
  time_to_first_token_ms: ttft,
  // 端到端延迟
  total_latency_ms: totalLatency,
  // 输出结构类型：纯文本、Markdown、JSON、代码块
  output_format: classifyOutputFormat(response.content),
  // 是否触发了内容安全策略
  content_policy_triggered: response.finishReason === 'content_filter',
})

// ❌ 坏做法：只有显式反馈，而大部分用户不会主动点赞/点踩
posthog.capture('ai_feedback', {
  type: 'thumbs_up', // 收集到的反馈量极少，无法代表整体
})
 
// ✅ 好做法：显式 + 隐式双通道
// 显式反馈
posthog.capture('ai_explicit_feedback', {
  feedback_type: 'thumbs_up' | 'thumbs_down' | 'rating',
  rating_value: rating, // 1-5 分
  feedback_text: optionalComment,
  trace_id: currentTraceId,
})
 
// 隐式反馈——这才是大多数用户真实态度的体现
posthog.capture('ai_implicit_feedback', {
  // 用户是否在输出基础上做了编辑
  edited: outputText !== finalText,
  // 编辑距离——衡量改动幅度
  edit_distance: levenshteinDistance(outputText, finalText),
  // 编辑比例——改了几个字 vs 全部重写
  edit_ratio: levenshteinDistance(outputText, finalText) / outputText.length,
  // 用户是否直接复制使用
  copied_to_clipboard: wasCopied,
  // 从输出到下次操作的时间——太短可能意味着直接放弃
  time_to_next_action_ms: timeToNextAction,
  // 用户是否在同一会话内重试
  retried_in_session: hasRetry,
})

// ❌ 坏做法：所有失败都归为一个笼统的 error 事件
posthog.capture('ai_error', {
  error_message: error.message,
})
 
// ✅ 好做法：按失败类型分类，附带诊断信息
posthog.capture('ai_failure', {
  // 失败分类——这是后续做失败归因分析的核心维度
  failure_type: classifyFailure(error),
  // 具体错误码或类别
  error_code: error.code,
  // 失败发生在哪个阶段：输入处理、模型调用、输出解析、工具调用
  failure_stage: 'model_call' | 'output_parse' | 'tool_call' | 'input_process',
  // 模型版本——某些失败可能只在特定模型上出现
  model_id: requestModel,
  // 是否可重试
  is_retryable: isRetryableError(error),
  // 重试次数
  retry_count: attemptCount,
  // 用户是否触发了降级方案（如切换到更小的模型）
  fallback_triggered: usedFallback,
  // trace_id 用于关联追踪数据
  trace_id: currentTraceId,
})

// ✅ 采纳事件——记录的是「用户真正使用了输出」
posthog.capture('ai_output_adopted', {
  // 采纳方式：直接插入、合并后插入、替换已有内容
  adoption_type: 'direct_insert' | 'merged_insert' | 'replace',
  // 从输出到采纳的时间——太长可能意味着用户犹豫过
  time_to_adoption_ms: timeToAdoption,
  // 采纳时输出被修改的比例
  modification_ratio: modificationRatio,
  // 采纳发生在第几次重试之后
  adoption_after_retry: retryCount,
  // 关联的 trace_id
  trace_id: currentTraceId,
})

// ✅ 成本事件——每次模型调用都附带成本信息
posthog.capture('ai_cost_recorded', {
  // 功能模块——成本要能聚合到功能级别
  feature: 'document_summarizer',
  // 模型
  model_id: 'gpt-4o',
  // Token 消耗
  input_tokens: inputTokens,
  output_tokens: outputTokens,
  // 估算成本（单位：美分）
  cost_cents: calculateCost(inputTokens, outputTokens, 'gpt-4o'),
  // 用户 ID——用于计算单用户成本
  user_id: userId,
  // 是否为重试产生的额外成本
  is_retry_cost: retryCount > 0,
  // trace_id
  trace_id: currentTraceId,
})

// ❌ 坏做法：手动在每个 API 调用处写埋点，容易遗漏且不统一
async function summarize(text: string) {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: text }],
  })
  // 每次都要记得写这些……
  posthog.capture('ai_call', { tokens: response.usage.total_tokens })
  posthog.capture('ai_cost', { cost: calculateCost(response.usage) })
  return response.choices[0].message.content
}
 
// ✅ 好做法：用 SDK 包装自动处理，业务代码保持干净
import { wrapOpenAI } from 'your-otel-wrapper'
 
const instrumentedOpenAI = wrapOpenAI(openai, {
  posthog,
  // 自动追踪每次调用，记录 token、延迟、模型、完成原因
  autoTrace: true,
  // 成本计算规则
  costTable: COST_TABLE,
  // 不记录原文内容（隐私保护）
  captureContent: false,
})
 
async function summarize(text: string) {
  const response = await instrumentedOpenAI.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: text }],
  })
  // 追踪、成本、延迟——全自动
  return response.choices[0].message.content
}

// ❌ 坏做法：把用户输入原文存到分析事件里
posthog.capture('ai_input', {
  prompt_text: userPrompt, // 可能包含姓名、电话、地址等 PII
})
 
// ✅ 好做法：记录结构化元数据，不存原文
posthog.capture('ai_input', {
  input_length: userPrompt.length,
  // 内容类别（用于分析哪类输入最多）
  content_category: classifyContent(userPrompt),
  // 输入文本的哈希（用于去重和统计唯一输入数）
  input_hash: await sha256(userPrompt),
  // 是否包含可能的敏感信息
  contains_pii_hint: piiDetector.quickScan(userPrompt),
})