eve CLI 遥测(Telemetry)完全指南:收集内容、隐私边界与开关控制
eve CLI 遥测(Telemetry)完全指南:收集内容、隐私边界与开关控制
本文基于 eve 开源仓库中 docs/reference/telemetry.md 编写。eve 是一个构建 Agent 的开源框架(The Open Framework for Building Agents),其 CLI 默认会收集有限的匿名遥测数据,用于改进命令与开发体验。读完本文,你将完整掌握:eve CLI 究竟收集哪些信息、明确排除哪些敏感内容、如何用
EVE_TELEMETRY_DEBUG=1实时查看即将上报的数据批次、以及如何用eve telemetry disable/EVE_TELEMETRY_DISABLED=1在机器级或单命令级关闭遥测。文中还会结合 packages/eve/src/cli/telemetry 下的源码与测试,揭示标识符生成、项目 ID 哈希、偏好持久化等底层实现。
eve 为什么收集 CLI 遥测
eve CLI 会收集使用数据,目的是帮助改进其命令设计与开发体验(“to help improve its commands and development experience”)。遥测默认开启,但你可以随时关闭,且关闭不影响任何命令功能。
从源码看,eve 的 CLI 遥测是一个独立子模块,集中实现于 packages/eve/src/cli/telemetry/index.ts,由几个职责单一的文件构成:
index.ts:事件模型、启停判断、事件收集与批量上报(spawn 子进程发送);identity.ts:安装 ID、项目 ID 的生成与解析(含 Git remote 哈希逻辑);preference.ts:config.json中遥测偏好(enabled / notified)与身份信息的读写;command.ts:eve telemetry status / enable / disable三个子命令的注册与实现;flush.ts:把事件批次 POST 到 Vercel 遥测端点。
值得强调的是,CLI 遥测与“应用运行时观测”(如 OpenTelemetry)是两套不同的机制:前者是命令行工具的匿名使用统计,后者是 Agent 应用的指标、日志与追踪采集,可参考 docs/guides/instrumentation/otel.mdx。本文只讨论前者。
eve 收集哪些信息
根据官方文档,eve 会将以下信息发送给 Vercel:
- 运行环境元数据:eve 版本号、操作系统、CPU 架构、stdin 是否为终端(
stdin_is_tty)。 - 命令与结果:你运行的命令、命令结果(成功/用法错误/失败),以及适用时的 setup 或 onboarding 步骤,包括
connection-ready(连接就绪)与first-response(首次响应)的耗时。当 setup 或 onboarding 失败时,只上报一个“有界的分类”(bounded category)来描述失败发生的步骤,不会发送底层错误信息。 eve dev上下文:连接的是本地还是远程 Agent(target),UI 是交互式(TUI)还是无头模式(ui)。- 随机标识符:CLI 会话 ID、安装 ID、项目 ID,以及安装/项目标识符是“临时(ephemeral)”还是“持久(persistent)”的标记。
从源码看事件字段与白名单
在 packages/eve/src/cli/telemetry/index.ts 中,createEveCliTelemetry(version) 在创建时即固定写入四个基线事件:
| 事件 key | 含义 | 取值示例 |
|---|---|---|
version |
eve 版本号 | 1.0.0 |
platform |
操作系统平台 | linux / darwin / win32 |
arch |
CPU 架构 | x64 / arm64 |
stdin_is_tty |
stdin 是否终端 | true / false |
之后按需追加:
command:经canonicalCommand()归一化后的命令路径,如init、dev、registry:search、logs:show;outcome:success/usage_error/error;target/ui:eve dev的本地/远程目标与 TUI/无头界面;setup_flow、setup_step、setup_terminal_step、setup_terminal_result、setup_failure_code:init / extension_init / onboarding 流程中的步骤级事件;identity_kind、installation_id、project_id:flush 时追加的身份信息。
命令白名单是隐私设计的关键。canonicalCommand()(index.ts)只会从一张显式允许列表(CLI_TELEMETRY_COMMANDS,覆盖 acp、add、build、deploy、dev、eval、extension、info、init、integration、remote、registry、set、telemetry、traces 等数十个命令)中提取命令路径,任何未在列表中的命令统一记作 unknown;用户传入的参数、URL、模型名等一律不进入事件。测试 packages/eve/src/cli/telemetry/index.test.ts 验证了这一点,例如 eve set --model private/model 只记录 set,eve registry search private-query 只记录 registry:search。此外,telemetry:flush 被标记为内部命令路径(internalCliCommandPaths),永远不产生遥测。
失败分类是有界的。EveCliSetupFailureCode(index.ts)只包含 target_resolution、target_conflict、target_invalid、target_filesystem、workspace_input、scaffolding、package_manager_not_found、package_manager_start_failed、workspace_probe_failed、workspace_probe_unrecognized、dependency_installation、git_initialization、handoff、onboarding 等有限的分类码;setupFailureCode() 会把具体失败步骤映射到这些分类。测试 index.test.ts 明确断言:失败事件只含 setup_failure_code,且 error_code、error_status 之类的字段永远不会出现在事件中。
eve 不收集哪些信息
官方文档明确列出以下内容绝不上报:
- 命令参数(command arguments)
- 提示词(prompts)
- Agent 文件(agent files)
- URL
- 请求头(request headers)
- 错误消息(error messages)
- 环境变量(environment variables)
- 文件路径(file paths)
- 文件内容(file contents)
从实现角度看,这一边界的保证来自三处:
- 命令归一化白名单:如上一节所述,
canonicalCommand()只输出命令路径,绝不携带参数值(参见 index.ts 与 index.test.ts)。 - 错误信息脱敏:
trackOutcome只记录outcome枚举值;失败细节最多映射为有界分类码,底层Error对象从不序列化(index.ts)。 - 事件字段白名单式构建:所有事件都通过
event(key, value)工厂方法产生,key 全部来自代码内的固定字符串集合,不存在动态透传用户输入的通道。
项目标识符:只分组、不泄露身份
官方文档说明:项目标识符让 eve 能把来自同一项目的使用数据归组,但不会发送项目名称或位置。eve 在可用时从 Git remote 推导项目标识符,否则回退到 REPOSITORY_URL 环境变量或工作目录,并在发送前对值做变换。
源码揭示了“变换”的具体机制。在 packages/eve/src/cli/telemetry/identity.ts 中:
resolveEveTelemetryProjectId()的取值优先级为:git remote.origin.url(通过git config --local --get remote.origin.url读取,1 秒超时)→repositoryUrl参数 →REPOSITORY_URL环境变量 → 工作目录;- 无论取到哪个值,最终都经过
hashEveTelemetryProject():用projectSalt与原始值拼接后做 SHA-256 哈希,输出固定长度的十六进制摘要。
也就是说,发送到服务端的是加盐哈希而非原文,且每次安装随机生成的 projectSalt(见 preference.ts)不同,同一个项目在不同机器上会得到不同的哈希值。测试 packages/eve/src/cli/telemetry/identity.test.ts 验证了优先级顺序与“不同盐产生不同哈希”的特性。
安装 ID 与 projectSalt 均为 randomUUID() 生成的随机值,持久化在平台的用户配置目录(见下文“偏好存储位置”)。
查看遥测数据:EVE_TELEMETRY_DEBUG
官方文档提供了调试开关:设置 EVE_TELEMETRY_DEBUG=1,遥测批次会打印到 stderr 而不是发送出去:
EVE_TELEMETRY_DEBUG=1 eve info
运行后你会在 stderr 看到一行以 [eve telemetry] 开头的 JSON 数组,其中包含该次调用将要上报的全部事件对象,每个对象形如:
{"id":"<uuid>","event_time":1720000000000,"key":"command","value":"info"}
这个输出格式直接来自 index.ts 的实现:process.stderr.write([eve telemetry] ${JSON.stringify(events)}\n),随后直接 return,不再触发网络发送。结合上面的身份逻辑,你可以借此确认:自己的 Git remote、目录名在事件里只以加盐哈希形式出现,命令参数与错误信息均无踪影。
提示:
EVE_TELEMETRY_DEBUG与EVE_TELEMETRY_DISABLED是两把不同的开关——前者只是把“发送”改为“打印”,仍会走完整的收集流程(包括读取身份、生成项目 ID),适合审计;后者则直接跳过收集,适合需要彻底静默的场景。
关闭遥测:机器级、单命令级与状态查询
机器级开关
官方文档给出的三条命令:
eve telemetry disable # 在本机禁用遥测
eve telemetry status # 查看当前状态
eve telemetry enable # 重新开启
对应实现位于 packages/eve/src/cli/telemetry/command.ts:status 读取偏好并输出 Telemetry status: Enabled / Disabled;disable 调用 setEveTelemetryEnabled(false) 并提示 “No data will be collected from this machine.”;enable 则写回 true。这些命令本身也出现在 CLI 帮助中(docs/reference/cli.md)。
单命令级开关
如果只想让某一条命令不产生遥测、同时不改变已保存的偏好设置,使用环境变量:
EVE_TELEMETRY_DISABLED=1 eve dev
其判断逻辑在 index.ts 的 isEnabled() 中:NODE_ENV !== "test" 且未设置 EVE_TELEMETRY_DISABLED 且持久化偏好为 enabled 时,才会上报。测试 index.test.ts 验证了该变量与持久化偏好两重开关都会阻止 spawn 上报进程。
首次运行的告知机制
文档说明:在交互式终端上,eve 会在收集遥测之前显示一次相关信息,并将你的偏好保存在平台用户配置目录。源码中的 notify()(index.ts)满足以下条件时才打印提醒:非 test 环境、未禁用、偏好开启、尚未告知过(notified 为 false)、且 stderr 是 TTY。提醒文案为:
Attention: eve collects CLI telemetry to improve the command-line interface.
Disable it with `eve telemetry disable`, or for one command set EVE_TELEMETRY_DISABLED=1.
Learn more: https://eve.dev/docs/reference/telemetry
打印成功后调用 markEveTelemetryNotified() 写入 noticeVersion 与 notifiedAt,之后不再重复提示。注意 run.ts 中 command !== "telemetry" 才会触发 notify(packages/eve/src/cli/run.ts),即你运行 eve telemetry 系列命令时不会被遥测提醒打扰。
CI 与 Docker 环境
文档强调:在 CI 和 Docker 环境中,eve 每次调用都使用全新的内存标识符,而不是保存到磁盘。源码依据是 isEphemeralEveTelemetryEnvironment()(identity.ts):当设置了 CI 环境变量或检测到 /.dockerenv 文件存在时,判定为临时环境。此时 flush() 调用 createEveTelemetryIdentity() 生成一次性随机 ID,事件中的 identity_kind 为 ephemeral,且不会读写配置文件(测试见 index.test.ts)。
偏好与身份的存储位置
文档指出偏好保存在“平台用户配置目录”。源码 preference.ts 按平台解析出 config.json 路径:
| 平台 | 配置文件路径 | 可覆盖的环境变量 |
|---|---|---|
| Windows | %APPDATA%\eve\config.json(默认 AppData\Roaming\eve\config.json) |
APPDATA |
| macOS | ~/Library/Preferences/eve/config.json |
无 |
| Linux | ~/.config/eve/config.json |
XDG_CONFIG_HOME(仅接受绝对路径,相对路径会被忽略,见测试 preference.test.ts) |
config.json 中的 telemetry 段 schema 如下(preference.ts):
{
"telemetry": {
"enabled": true,
"installationId": "<uuid>",
"projectSalt": "<uuid>",
"noticeVersion": 1,
"notifiedAt": "2026-10-13T00:00:00.000Z"
}
}
enabled:默认true(未配置或文件缺失时按开启处理,测试 preference.test.ts 验证);installationId、projectSalt:随机生成的持久身份,首次使用时创建并写入;noticeVersion、notifiedAt:首启告知的记录,用于判断是否已提示。
写入采用原子方式:先写临时文件(config.json.<pid>.<timestamp>.tmp,权限 0o600)再 rename 替换,避免写一半损坏配置(preference.ts)。持久化失败不会影响命令本身的执行。
上报机制:异步、静默、绝不阻塞命令
虽然用户日常不需要关心发送细节,但理解上报机制有助于确认“遥测不影响你的命令”。flush()(index.ts)的流程如下:
- 检查
isEnabled(),关闭或事件为空则直接返回; - 按环境决定使用临时身份或持久身份,并追加
identity_kind、installation_id、project_id与全部 setup 事件; - 若设置了
EVE_TELEMETRY_DEBUG,把批次打印到 stderr 后返回(不发送); - 否则
spawn一个 detached(分离)子进程:用当前 Node 可执行文件重新执行eve telemetry flush <payload>,并显式设置EVE_TELEMETRY_DISABLED=1防止子进程再次收集,子进程stdio: "ignore"、unref()脱离父进程生命周期——父命令立即结束,发送在后台完成; - 子进程(flush.ts)将事件批次 POST 到默认端点
https://telemetry.vercel.com/api/eve-cli/v1/events(可通过EVE_TELEMETRY_ENDPOINT环境变量覆盖),带client-id: eve-cli、x-eve-cli-topic-id: generic、x-eve-cli-session-id请求头,1 秒超时; - 所有发送路径都被 try/catch 包裹,任何网络失败、spawn 失败都不会影响命令输出或退出码(测试 index.test.ts 验证了这一点,包括“身份初始化失败直接跳过上报”的情形)。
整体调用时机见 packages/eve/src/cli/run.ts:每次 CLI 调用在解析参数后 trackCommand,结束后在 finally 中 flush(),确保无论成功、用法错误还是异常,事件都在进程退出前进入上报队列。
隐私与合规小结
把文档承诺与源码实现对照,可以得到一张简洁的“承诺-实现”对照表:
| 文档承诺 | 源码实现证据 |
|---|---|
| 只收集版本、平台、架构、TTY、命令、结果、dev 上下文、随机 ID | index.ts 固定基线事件 + 白名单命令 |
| 失败只上报有界分类,不发送底层错误 | EveCliSetupFailureCode 枚举 + index.test.ts |
| 不收集参数、提示词、文件、URL、环境变量、错误消息等 | canonicalCommand() 白名单、event() 固定 key 工厂、测试断言 |
| 项目 ID 不泄露名称与位置 | SHA-256 加盐哈希,identity.ts |
| CI/Docker 使用一次性内存标识符 | isEphemeralEveTelemetryEnvironment(),identity.ts |
| 遥测不影响命令执行 | detached 子进程 + try/catch 全包裹,flush.ts |
整体上,eve CLI 遥测的设计取向是“默认开启、透明可审计、边界严格”:通过 EVE_TELEMETRY_DEBUG=1 你可以随时查看实际发送的数据;通过 eve telemetry disable 或 EVE_TELEMETRY_DISABLED=1 你可以随时停止收集。相关的命令参考可继续查阅 docs/reference/cli.md,更宏观的隐私与合规讨论可参考 docs/responsible-use.md。