- 总共只有两个事件：
command_executed和command_failed - 每个事件三个属性：
command、success、version - 可通过环境变量、CLI 标志或持久同意命令退出
- Extension.js 对事件进行采样并设上限，以保持在 PostHog(开源分析) 免费额度内
Extension.js 收集什么
每次 CLI 运行最多发出以下之一。例外是监视会话（dev、start、preview）：它在启动时上报带 session: started 的 command_executed，之后若出错再上报一条 command_failed，因此一次运行可能产生两行：
失败会附加 两个属性，让失败计数可以读出原因，而不只是一个数字。
code 取自 CLI 固定的错误目录，例如 E_MANIFEST_NOT_FOUND，exit_code 是进程退出码，取值为 0 到 255 的整数。code 在发送前会与目录核对，因此 Node 的 errno、错误信息或任何不在目录中的值都会被丢弃，事件改为上报 E_INTERNAL。错误文本永远不会被发送。
当某次运行在首次启动时询问是否下载受管浏览器，该命令自身的事件会带上结果，这样”用户接受了下载”就能与”会话到此结束”区分开。browser_install 取值为 offered、accepted、declined 或 failed，browser_install_browser 是受管浏览器的名称，例如 chrome，browser_install_seconds 是下载所用的整数秒。没有单独的安装事件，计数仍然只在上面两个事件上。
create 命令会多带两个属性，让损坏的官方起步模板能出现在失败统计里：template（extension create --help 列出的起步模板名，否则不带）与 source（cli，或当 create 由文档的模板画廊发起时为 templates）。template 在发送前会与已发布的起步模板列表核对。GitHub URL、本地文件夹路径或任何不是官方名称的值都会被整个丢弃而不是截断，因此私有仓库或目录名永远不会离开你的机器。source 也以同样的方式与这两个界面核对，其他任何值都按 cli 发送。create 命令还不参与采样，因此模板使用量的统计保持准确。
附加到每个事件的公共上下文：os(darwin/linux/win32)、arch、node_major、is_ci、is_source_build，以及始终为 extension 一词的 app。仅此而已。is_source_build 是一个布尔值，只回答”这是一次 registry 安装，还是一份仓库检出”。它由安装路径的形态推算而来(CLI 之上是否存在 node_modules 形式的路径段)。路径本身从不会被读进事件、发送出去，也不会被哈希。
流量控制
有三种相互独立的控制方式，限制离开机器的数据量：- 采样： Extension.js 默认对
command_executed采样 20%。可通过EXTENSION_TELEMETRY_SAMPLE_RATE(0.0–1.0) 覆盖。失败事件不会被采样。 - 每次运行上限： 单个 CLI 进程最多 3 个事件。可通过
EXTENSION_TELEMETRY_MAX_EVENTS覆盖。 - 去抖(重复抑制)： Extension.js 会在 60 秒内丢弃相同的
(event, command, success)元组。可通过EXTENSION_TELEMETRY_DEBOUNCE_MS覆盖。
Extension.js 从不收集什么
Extension.js 的遥测契约明确排除了：- 源代码、manifest 内容、HTML 产物或
package.json内容 - 仓库名、Git remote、GitHub 组织/用户名、分支名、commit SHA 或预览 URL
- 依赖清单、权限清单或自由文本的项目标识
- 环境变量值、文件系统路径或本机 URL
- 堆栈、错误信息或自由文本的错误名
- IP 地址。PostHog 项目在接收时丢弃请求地址(
anonymize_ips)，每次载荷都发送$ip: null和$geoip_disable: true，因此也不会由此推导出位置。2026-10-06 之前发送的事件带有请求地址。
4.0 之前的版本
3.x 系列发送的是另一套模式，直到 2026-04-17 都公布在仓库的契约文件中：生命周期事件（cli_boot、cli_command_start、cli_command_finish、cli_vendor_start、cli_vendor_finish、cli_shutdown、cli_telemetry_consent）、manifest_summary（权限与内容脚本的数量）、project_profile（框架家族与包管理器）、workflow_profile（使用群组）以及 cli_build_summary（产物数量与字节数）。只有计数、布尔值和固定列表中的名称，从不包含路径、URL 或项目名。仍停留在 3.x 的安装会继续发送这些事件，而自 2026-10-07 起，PostHog 项目在接收时会丢弃所有不属于上述两个事件的事件，因此那套模式的数据不再被存储。
退出方式
按优先级顺序，有三种方式禁用遥测：$XDG_CONFIG_HOME/extensionjs/telemetry/consent(或对应平台的等价位置)。当该位置不可写时，存储位置会按顺序回退：平台缓存目录，然后是系统临时目录下的一个文件夹，最后是当前工作目录中的 ./.cache/extensionjs。
默认行为
在交互式终端中，遥测是默认开启、可退出的。在第一次没有任何上述覆盖项生效的运行中，Extension.js 会打印一行说明退出方式的提示，并写入一个enabled 同意标记，以避免重复提示。
CI 中默认关闭
在 stdout 没有连接任何东西的 CI 环境里(设置了 CI 标记且没有 TTY)，遥测默认是关闭的，并报告source: ci。已存储的 enabled 同意不会带进流水线：由真人在键盘前记录的同意，不能覆盖一条继承了同一个 home 目录的流水线，所以这个已存储的选择加入会被降到 CI 闸门之下。已存储的 disabled 是一次拒绝，而拒绝在任何地方都优先，CI 中同样如此。
如果你确实想从流水线发送遥测，请设置 EXTENSION_TELEMETRY=1。这个显式的机器级选择加入位于 CI 闸门之上。
本地审计日志
Extension.js 会把它”考虑发送”的每个事件(无论是否真的发出) 追加到同意文件旁的events.jsonl。你可以随时查看，也可以随意删除它。
审计日志的大小是有界的。达到 1 MiB 时，它会滚动成一个 events.jsonl.1 备份，覆盖此前的备份。可通过 EXTENSION_TELEMETRY_AUDIT_MAX_BYTES 覆盖这个上限。远超上限(达到 10 倍或以上) 的文件会被直接丢弃，而不是保留。如果审计写入本身失败，Extension.js 会在本次运行中禁用后续所有发送：一个无法在本地留下审计记录的事件，不会被发送出去。
最佳实践
- 当政策要求不上报遥测时，在 CI 中使用
EXTENSION_TELEMETRY_DISABLED=1。 - 把隐私回归当作产品回归来对待。
- 阅读仓库级契约文件以获取精确的事件清单。
下一步
- 在全局标志 中查看
--no-telemetry与环境变量覆盖项。 - 在build 与dev 中应用于发布与自动化工作流。
- 阅读仓库级的
docs/TELEMETRY.md契约，了解精确的事件清单。