Add Telemetry

新增或调整用户可见功能时，默认要同时考虑 telemetry：我们需要知道功能是否被触达、在哪里失败、用户实际走到了哪一步，后续才能根据数据改进体验。

这份流程改写自 piglet12138/claude-code 的 telemetry dashboard skill，只保留适合 claude-zh.cn 仓库的埋点设计、接入和验证方法。

何时使用

新增安装脚本步骤、自动修复、下载源、平台分支或错误处理。
新增 wrapper、更新、登录、鉴权、支付、配置向导等用户流程。
修改已有 telemetry event、stage、schema、口径或去重方式。
需要定位某个功能“有没有用、哪里掉、为什么失败”。

文档-only 的纯内容更新通常不需要新增 telemetry，但 PR 里仍应说明“未新增 telemetry，因为没有新的用户流程或运行时行为”。

先问 5 个问题

这个功能的成功信号是什么？例如安装完成、Node 自动安装成功、登录 token 写入成功。
这个功能最可能在哪里失败？每个关键失败点是否有 stage 或 reason。
这个事件能驱动什么行动？如果数据不会影响排障、产品判断或下一次改进，就不要加。
能复用现有 dataset 吗？优先加 event 或 stage，只有业务域明显不同才新建 dataset。
是否有 PII 风险？默认禁止邮箱、用户名、token、项目路径、命令内容、自由文本错误原文出站。

现有 telemetry 面

Dataset	Binding	Endpoint	主要用途
`install_events`	`INSTALL_ANALYTICS`	`/api/install-event/{script}/{platform}/{arch}/{stage}`	安装阶段、依赖检查、下载与失败原因
`wrapper_events`	`WRAPPER_ANALYTICS`	`/api/wrapper-event/{source}/{os}/{arch}/{event}`	wrapper 首次运行和启动
`update_events`	`UPDATE_ANALYTICS`	`/api/update-event/{source}/{os}/{arch}/{event}`	自动更新检查、发现、开始、成功、失败
`cc_auth_events`	`CC_AUTH_ANALYTICS`	`/api/cc-auth-event/{platform}/{arch}/{event}`	Claude Code 登录/注册/验证码/token 安装漏斗

绑定在 wrangler.toml，接收逻辑在 functions/api/*-event/[[path]].js。新增 dataset 时必须同步加 binding 和 Function endpoint；否则优先复用上表。

不变量

零阻塞：telemetry 失败、超时或未绑定时，主流程必须继续。
零信任输入：所有 path 和 query 字段都在 Cloudflare Function 端 sanitize。
零 PII：除已有明确批准的字段外，不发送自由文本、token、邮箱、用户名、路径或完整命令。
零噪音：客户端不因为 telemetry 输出日志；失败静默吞掉。
零环境耦合：Cloudflare Analytics Engine 或 Function 不可用时，用户体验不变。
可关闭：客户端流程必须尊重 LUCKY_DISABLE_TELEMETRY=1。

设计事件

优先用现有 dataset：

安装脚本新步骤：给 install_events 增加新的 stage。
wrapper 行为：给 wrapper_events 增加 ALLOWED_EVENTS 项。
自动更新行为：给 update_events 增加 ALLOWED_EVENTS 项，必要时用 reason 和 duration_ms。
登录/鉴权行为：给 cc_auth_events 增加 ALLOWED_EVENTS 或受控枚举字段。

命名规则：

使用小写 snake case。
event 建议用 <product>_<domain>_<action>，例如 lucky_auto_update_success。
stage 建议描述流程节点或失败原因，例如 node_auto_install_start、npm_install_failed。
所有 event/stage 必须满足 ^[a-z0-9][a-z0-9_-]{0,63}$。

失败事件尽量用“一个 catchall event + reason 维度”，避免同一次失败写多条互相冲突的事件。

字段设计

blob 放枚举、版本、hash、id；double 放耗时、金额、数量；indexes[0] 通常放 event 或 stage。

设计 blob 顺序时遵守：

event 或 stage 放最前面，便于查询过滤。
platform、arch、source、channel 等切片字段靠前。
install_id、session_id、user_id 等 join key 必须稳定，且不要太靠后。
高基数字段要确认真的需要查询，否则不要收。
新增字段后必须同步注释、文档和 smoke 验证。

不要混用不同 dataset 的 blob 序号。比如 install_events.blob7 是 install_id，但其他 dataset 的 install_id 不一定在 blob7。

客户端发送规则

Shell 侧参考 public/scripts/install.sh：

[ "${LUCKY_DISABLE_TELEMETRY:-0}" = "1" ] && return 0
curl -fsS --max-time 2 "$url" >/dev/null 2>&1 || true

PowerShell 侧参考 public/scripts/install.ps1：

powershell

if ($env:LUCKY_DISABLE_TELEMETRY -eq "1") { return }
try {
  Invoke-WebRequest -Uri $url -UseBasicParsing -TimeoutSec 2 | Out-Null
} catch {}

要求：

设置 2 秒左右超时。
stdout/stderr 不污染用户终端。
网络失败、HTTP 失败、命令不存在都不影响主流程。
查询参数只传白名单字段。
能复用 install_id 时优先复用，避免每个事件生成新身份。

Function 接收规则

更新 functions/api/<scope>-event/[[path]].js 时：

将新 event/stage 加入 ALLOWED_EVENTS、ALLOWED_STAGE 或等价白名单。
新 query 字段必须有 sanitizer，枚举用 Set，自由 token 用正则，数字做范围裁剪。
非白名单输入返回 204 并静默 drop，不把错误暴露给用户流程。
成功、未绑定、写入失败都通过 x-ae-status 便于 smoke 检查。
writeDataPoint 的 blobs/doubles 顺序必须在文档里写清楚。

验证

最小验证：

npm run docs:build

Function 变更还要做端点 smoke：

curl -i "https://claude-zh.cn/api/install-event/install.sh/linux/x64/start?shell=bash&install_id=test-install-1"

本地或预览环境可用时，检查：

正向：白名单 event/stage 返回 204，响应头包含正确 echo 和 x-ae-status。
负向：非法 event/stage 返回 204，不写入 Analytics Engine。
失败隔离：endpoint 不可用或超时时，安装/运行流程仍成功。
隐私：请求里没有 token、邮箱、用户名、路径、完整命令或自由文本错误。

如果有 Analytics Engine 查询权限，再补查一条新事件是否进入对应 dataset，并确认 blob/double 顺序正确。

PR Checklist

[ ] 已说明 telemetry 决策：新增、复用、修改或明确不需要。
[ ] 新 event/stage 有可行动的问题或指标目标。
[ ] 优先复用现有 dataset；新 dataset 有明确理由。
[ ] 客户端发送路径尊重 LUCKY_DISABLE_TELEMETRY=1，失败不阻塞。
[ ] Function 端完成白名单、sanitize、writeDataPoint 和响应头。
[ ] 没有新增未批准 PII。
[ ] 文档说明了事件语义、字段顺序和验证方式。
[ ] 已做正向、负向、失败隔离 smoke，或说明无法验证的原因。

Add Telemetry ​

何时使用 ​

先问 5 个问题 ​

现有 telemetry 面 ​

不变量 ​

设计事件 ​

字段设计 ​

客户端发送规则 ​

Function 接收规则 ​

验证 ​

PR Checklist ​