AutoClip 埋点体系实战指南：基于 PostHog 的匿名、可关、本地缓冲产品分析方案

• 音视频
• AI 应用
• 后端
• 前端

导读：AutoClip 是一款 AI 驱动的视频高光提取与剪辑工具，其产品侧在 ROADMAP Phase 0 就确立了"匿名、可关、本地缓冲"三大埋点设计原则。本文以 docs/ANALYTICS.md 为核心骨架，结合 frontend/src/analytics/ 下的真实实现，完整讲解 AutoClip 的指标框架、事件字典、全局属性、身份模型、隐私合规与扩展步骤。读完本文，你将掌握一套可直接复用的桌面端产品埋点方案：从事件命名规范、PostHog 初始化参数，到漏斗构建与加新事件的标准流程。

1. 技术选型与设计原则

AutoClip 的产品分析工具选用PostHog（US 区，https://us.i.posthog.com），并在 ROADMAP.md Phase 0 中确立了三条贯穿全链路的设计原则：

• 匿名：默认不采集任何 PII（个人身份信息），不采集视频内容、字幕文本、API key 明文。
• 可关：用户在设置页可以一键关闭采集（opt-out），偏好持久化到本地存储，应用重启后仍生效。
• 本地缓冲：posthog-js默认在内存中批量缓冲事件，断网或退出代理时不丢主流程事件。

这三条原则不是停留在文档层面，而是被完整落实到了 frontend/src/analytics/posthog.ts 的初始化代码中（详见第 4 节）。

2. 指标框架：从北极星到变现就绪

埋点体系的第一层是指标框架，它为整个采集体系定义了"要衡量什么"。AutoClip 按经典的增长模型分层：

从源码结构看，这一框架与事件字典一一对应：北极星指标直接锚定clips_exported事件（用户在 frontend/src/analytics/events.ts 中可看到该事件常量），而留存层则完全依赖app_opened事件，由 PostHog 平台端自动聚合出 DAU 与 D1/D7/D30 留存曲线。

3. 核心漏斗与事件字典

3.1 激活漏斗

AutoClip 的核心漏斗覆盖了从下载到回访的完整用户旅程：

下载 .dmg → app_installed → video_imported → clips_exported(★激活) → 回访(留存)

漏斗中的每一步都有对应的事件支撑，其中clips_exported被标记为激活关键事件（★）。

3.2 命名规范

事件命名遵循对象_动作的 snake_case 规范，代码层面统一收敛在 frontend/src/analytics/events.ts 中，通过AnalyticsEvent常量对象定义，避免裸字符串散落各处。未配置 key 或用户关闭埋点时，所有 capture 自动 no-op（内部已处理）。

3.3 完整事件字典

生命周期（实现于 frontend/src/analytics/lifecycle.ts）

在生命周期事件中，app_installed同时充当"装机量代理指标"。实现上有几个值得注意的细节：

• 安装判定：通过localStorage中的autoclip.analytics.installed标志位，首次启动时上报app_installed并写入标志位。
• 会话计数：autoclip.analytics.sessionCount每次启动自增，作为session_number属性上报。
• 版本更新检测：autoclip.analytics.lastVersion记录上次版本，与当前版本不一致时上报app_updated。

激活漏斗（实现于 frontend/src/services/api.ts）

实际代码调用点验证：

• 文件上传成功后在 api.ts 第 275 行 触发trackVideoImported({ source: 'upload', fileType, sizeBytes })；
• B 站 / YouTube 下载任务则在 api.ts 第 637 行 与第 644 行分别以source: 'url', fileType: 'bilibili'/'youtube'触发；
• 切片导出成功后在 api.ts 第 520 行 触发trackClipsExported，exportType通过clipId ? 'clip' : collectionId ? 'collection' : 'project'区分单切片 / 合集 / 整片三种导出粒度，clipCount当前固定为 1（单次下载语义）。

trackVideoImported与trackClipsExported的类型化签名定义在 events.ts 第 33-49 行，分别支持source / fileType / durationSec / sizeBytes与clipCount / durationSec / withSubtitles / exportType属性。

配置（触发于 SettingsPage.tsx 第 169 行）

该事件的实现体现了隐私优先的细节：trackApiKeyConfigured的签名只接收provider与hasKey布尔值，events.ts 第 59-65 行 的注释明确写着"不要传 key 明文，仅标记是否填写"。这样既能量化"配 key 率"这一变现就绪指标，又不会把敏感信息送上分析平台。

错误

错误事件的stage是一个受控枚举：import | transcribe | analyze | clip | export | other。从源码调用看，导入失败在 api.ts 第 282 行 记录stage: 'import'，导出失败在 api.ts 第 528 行 记录stage: 'export'，code取自 HTTP 状态码（error?.response?.status）。

崩溃 / 异常栈交给Sentry（Phase 0 另接），PostHog 只记业务失败。这条边界意味着：PostHog 侧关注的是"业务流程在哪一步失败、失败率多少"，而运行时崩溃的堆栈诊断归 Sentry 负责，避免两类数据互相污染。

4. 全局属性（Super Properties）

每条事件自动携带的全局属性在lifecycle.ts的trackLaunch()里注册：

app_version（TaurigetVersion()）·os·arch·app_locale

从 lifecycle.ts 第 72-88 行 的实现看，全局属性通过posthog.register()注册，注册后后续每条事件自动携带，方便按"版本 / 系统 / 架构"切片分析，典型场景是排查"某版本在某系统失败率高"。

实现细节值得一提：os与arch并非来自 Tauri 插件，而是通过navigator.userAgent正则粗略解析（lifecycle.ts 第 19-33 行），这样避免了引入需要改 Rust 侧的plugin-os依赖；getVersion()在非 Tauri 环境（如浏览器里跑 vite dev）会抛错，因此包了一层 try/catch 回退到'unknown'。getRuntimeInfo()会将这组运行环境缓存下来，供反馈等场景复用，且不依赖埋点是否开启。

5. 身份模型

• 现在：匿名设备 ID（PostHog 自动生成，localStorage持久化）。
• Phase 1 账号上线后：登录调用identifyUser(userId)、登出调用resetUser()。

frontend/src/analytics/posthog.ts 已经为账号体系备好了这两个函数：identifyUser(distinctId, properties)对应 PostHog 的identify，用于登录后把匿名设备关联到用户；resetUser()对应posthog.reset()，用于登出时重置匿名身份。与此配合的初始化参数是person_profiles: 'identified_only'，即未登录前不创建 person profile，保持匿名，登录后才通过identify关联。

6. 下载量统计（App 外）

App 内用app_installed当装机量。若有官网，可加 PostHog 网页 snippet 埋download_clicked，串成"落地页→下载→安装"全漏斗。这样获取层（下载数 / 安装数）就不再是两个孤立的数字，而是一条可分析的转化链路。

7. 隐私与合规

AutoClip 的隐私设计贯穿设置 UI 与底层实现两层：

• 设置入口：设置页 → 应用设置 →隐私与数据开关。从 SettingsPage.tsx 第 468 行 可以看到，开关通过setAnalyticsEnabled(on)切换，并用isAnalyticsEnabled()初始化状态（第 81 行）。
• 底层实现：posthog.ts 第 73-82 行 的setAnalyticsEnabled(enabled)会把偏好持久化到localStorage的autoclip.analytics.optOut键（true = 已关闭采集），然后调用posthog.opt_out_capturing()/posthog.opt_in_capturing()立即生效，重启后由opt_out_capturing_by_default: !isAnalyticsEnabled()继续遵守该偏好。
• 默认行为：默认关录屏、不采 PII、key 只记hasKey。
• 上线前提：正式上线前需配套隐私政策（《个人信息保护法》要求）。

此外，posthog.ts 第 47-65 行 的初始化参数还包含几个隐私相关的关键配置：disable_session_recording: true（隐私优先，默认不录屏，PostHog 端也需另行开启）、capture_pageview: false（HashRouter 下手动上报 pageview，由trackPageview()在路由变化时调用，见 App.tsx 第 16 行）、autocapture: true（自动捕获页面点击 / 输入，配合手动关键事件构建漏斗）。

8. 环境变量配置

埋点的开关完全由两个环境变量控制（frontend/.env.example）：

# 复制为 .env.local 并填入你的 PostHog project API key（.env.local 已被 gitignore） # 不配置时埋点自动禁用（no-op），不会发任何网络请求。 # PostHog project API key（公开 key，可打包进前端） VITE_PUBLIC_POSTHOG_KEY=phc_xxx # PostHog 实例地址：US 区填 https://us.i.posthog.com，EU 区填 https://eu.i.posthog.com VITE_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

关键行为：

• 缺省时埋点全程no-op，不发起任何网络请求，因此 dev 环境（无 key）不会污染线上数据。
• 模板见frontend/.env.example，实际配置写frontend/.env.local（已 gitignore）。
• 从 posthog.ts 第 14-17 行 看，POSTHOG_HOST未配置时会默认回退到https://us.i.posthog.com；POSTHOG_KEY未配置时，initAnalytics()直接返回，并在 dev 环境打印[analytics] 未配置 VITE_PUBLIC_POSTHOG_KEY，埋点已禁用的提示。

应用启动时，main.tsx 第 24-26 行 依次调用initAnalytics()与trackLaunch()，完成 PostHog 初始化和生命周期事件上报。

9. 应用内反馈（PostHog Surveys 扩展）

虽然 ANALYTICS 文档主线以业务指标为主，但从 frontend/src/analytics/feedback.ts 可以看到，埋点体系还延伸出一个配套能力：应用内反馈。用户不用离开应用、不用注册外部账号，就能把"哪里不对 / 想要什么"发出来，且自动带上排查所需上下文（版本 / 系统 / 架构 / LLM provider & 模型 / 失败阶段与错误）。

• 反馈以feedback_submitted事件进入 PostHog，无论有没有配置 Survey 都会发送；
• 若 PostHog 项目里存在名为AutoClip 应用内反馈（或 env 指定 id）的 Survey（API 型 / 无 UI），会同时按约定发送survey shown / survey sent / survey dismissed，结果出现在 PostHog → Surveys 的响应面板里，周报可直接读取；
• 版本 / 系统 / 架构由lifecycle.ts注册的 super properties 自动携带，此处额外显式写入，避免 Surveys 面板只看$survey_response*时丢失上下文；
• 埋点被用户关闭时，PostHog 侧不会发出，此时回退到官网飞书表单（FEEDBACK_FORM_URL）；
• collectLlmContext()会通过settingsApi.getCurrentProvider()读取当前 LLM provider / 模型 / base_url 补进反馈上下文，后端不可达时静默忽略。

10. 加新事件的完整步骤

ANALYTICS 文档给出了三步标准流程，结合源码可以进一步细化验证方式：

1. 定义事件：在 events.ts 的AnalyticsEvent加常量 + 类型化封装函数。这一步同时解决"裸字符串散落"与"载荷类型不统一"两个问题，类型化的 props 接口就是天然的事件字典。
2. 调用埋点：在调用点 import 调用，优先放 services/api.ts 这类集中层（与现有trackVideoImported/trackClipsExported/trackProcessingFailed的调用方式保持一致）。
3. 同步文档：更新本文的事件字典（即 docs/ANALYTICS.md），保证事件定义、调用位置、属性说明三者始终一致。

验证一个埋点是否生效，可以按这条链路排查：确认VITE_PUBLIC_POSTHOG_KEY已配置 → 应用启动时initAnalytics()被调用（dev 环境无 key 会打印禁用提示）→ 确认对应调用点已触发类型化函数 → 在 PostHog 后台按事件名检索并检查属性是否完整。

11. 小结

AutoClip 的埋点体系可以归纳为一条清晰的实践路径：以北极星指标（周成功出片用户数）锚定事件设计 → 用对象_动作snake_case 规范统一事件字典 → 靠全局属性（版本 / 系统 / 架构 / 语言环境）支持切片分析 → 通过 PostHog 自动聚合完成留存与漏斗分析 → 以"匿名、可关、本地缓冲"三原则兜底隐私合规。整套方案从 docs/ANALYTICS.md 的指标设计出发，完整落到 frontend/src/analytics/ 的四个模块（事件定义、生命周期、PostHog 封装、应用内反馈）与集中调用层 frontend/src/services/api.ts，对于需要给桌面端产品搭建轻量、合规、可扩展埋点体系的团队，是一份可以直接参考的落地范本。

• 音视频
• AI 应用
• 后端
• 前端