SDK Quickstart 首次成功时间：事件合同、可执行样例与失败分母

开发者打开 Quickstart、复制安装命令、甚至收到一次 HTTP 200，都不一定真正接通了 SDK：200 可能来自健康检查，示例也可能用了缓存响应。这里的 Time to First Success（TTFS）只在“当前 SDK 完成一项有业务语义且可由服务端证明的操作”时结束。AI onboarding 设计讨论界面引导；AI 产品 Time to Value追踪用户何时获得可信结果。TTFS 更窄，只诊断开发者集成路径，不能拿来宣称用户已经获得产品价值。

先冻结旅程，再计算耗时

每个公开 Quickstart 发布不可变的 sdk.quickstartJourney.v1。它固定 journeyVersion、文档 revision、SDK 包名与制品摘要、示例仓库 commit、API schema revision、区域及成功谓词。成功谓词必须指向受支持动作，例如“创建沙箱资源后能按 ID 读回同一资源”，不能写成含糊的 request returned 2xx。REST API 版本控制解决接口演进，这份清单进一步绑定开发者实际看到的教程与 SDK 制品。

schema: sdk.quickstartJourney.v1
journeyVersion: node-create-widget@2026-07-19
sdkArtifact: sha256:42b...
docsRevision: 81ea0d7
apiRevision: widgets.v3
successPredicate: widget.created-and-read-back
environmentClass: clean-linux-node22
observationWindow: 30m
analysisCutoff: 2026-07-26T00:00:00Z
clockAuthority: api-edge-utc-v2
maxClockSkewMs: 100

采集端发送 sdk.quickstartStep.v1，字段仅含随机 journeyId、attemptId、单调递增的 stepSeq、step、outcome、errorClass、版本元组、occurredAt 和 receivedAt。eventId 用于幂等去重；迟到事件可以补齐旅程，但不得覆盖更高 generation。W3C Trace Context 可关联安装器、SDK 和服务端 span，但 trace 标识不是用户身份，也不能塞 API key、代码内容或邮箱。Prompt 遥测治理中的采集前脱敏同样适用。

终点以服务端写出的 successReceipt 为准，包含操作 ID、谓词版本、SDK user-agent、API revision、响应摘要、业务实际被接受的 operationAcceptedAt、回执生成与汇聚的 receivedAt，并声明 clock authority 和校准误差。客户端自报只作为诊断信号。若浏览器禁用遥测但服务端收到带 journey token 的合格调用，仍可完成；反之，客户端显示绿色但服务端没有凭据，只能记为 UNCONFIRMED。token 使用短期随机值，只绑定旅程版本，不跨站追踪开发者。

分母必须包括没有成功的人

至少同时公布三个分母：看到并选择兼容 Quickstart 的 eligible_start、真正执行初始化命令的 execution_start、获得服务端凭据的 verified_success。manifest 在开始前冻结 observationWindow 与 analysisCutoff；未成功旅程的 censorAt 取“起点加 observation window”和 analysis cutoff 的较早者。TTFS 分布只覆盖成功者，会把卡死者消失掉，所以旁边必须给出 5、15、30 分钟内成功率、右删失比例和失败分类。按语言、SDK 主版本、操作系统、区域及新旧账号分层；样本不足的桶保持 INSUFFICIENT_DATA，不能并入总体后宣称改善。

时间起点取 journey 服务端签发的 eligibleStartedAt，终点取校准到同一可信时基的 operationAcceptedAt；回执 receivedAt 只决定材料水位，不能把传输延迟算进 TTFS。不同 clock domain 缺少校准、误差超过 manifest 上限或终点早于起点时标为 TIME_UNRESOLVED。迟到回执若证明业务在 censorAt 前发生，则追加 correction generation 重算后续报告，不覆盖已封存快照。重试保留同一 journeyId、新建 attemptId，既能算首次尝试成功率，也能观察修复后重试。HTTP 的状态语义遵循已绑定版本；429、401 和 422 必须分别分类，不能都压成“网络错误”。API 限流策略说明 429 的运行边界，TTFS 只负责证明它在 Quickstart 旅程中是否被正确解释。

用坏环境证明指标不会撒谎

故障套件覆盖：文档指向已撤回包版本、SDK 与 API schema 不兼容、缺少 scope、错误 base URL、DNS 失败、429 带 Retry-After、成功响应在客户端落盘前断线、事件重复与倒序、浏览器时钟快一小时、服务端 clock domain 失配、遥测端点被拦截，以及操作已及时完成但回执延迟到水位之后。系统必须把这些情况稳定映射到可行动的 errorClass；尤其不能因埋点失败就把真实成功算作失败，不能把回执延迟加进业务耗时，也不能因客户端伪造 success 就提前停表。LLM 可观测性介绍 trace、eval 与监控分层，这里只保留 Quickstart 所需的最小诊断字段。

上线门要求：清洁环境矩阵中所有受支持语言与当前主版本可执行率 100%；每个组合连续 50 次合格操作成功率不低于 98%；15 分钟内验证成功率不低于 90%；成功者 TTFS 的 p50 不高于 4 分钟、p90 不高于 12 分钟；UNKNOWN 错误低于 1%、TIME_UNRESOLVED 为 0；重复、乱序或只延迟回执时，按业务发生时刻重算的结果差异为 0；秘密对抗样本泄漏为 0。线上比较必须同时报告分母、censorAt 规则、样本量和置信区间，任何一项缺失都不准标注“更快”。

发布先让旧、新事件双发，由 shadow 聚合器对同一旅程重算七天；差异可解释后只给 5% Quickstart 会话启用新 journey alias，再逐级提升。若成功率下降超过 2 个百分点、UNCONFIRMED 超过 1% 或某语言桶无数据，立即把 alias 切回旧文档与旧 SDK 组合。新事件保留为不可变诊断证据，reader 继续双读到最长旅程窗口结束；回滚的是入口，不是篡改历史。