eve CLI 遥测(Telemetry)完全指南:收集内容、隐私边界与开关控制

原创2026-10-13 13:39:171,632 阅读
文章标签:人工智能AI AgentAgent 框架工具调用后端MCP ClientsAI 评测可观测性

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:

  1. 运行环境元数据:eve 版本号、操作系统、CPU 架构、stdin 是否为终端(stdin_is_tty)。
  2. 命令与结果:你运行的命令、命令结果(成功/用法错误/失败),以及适用时的 setup 或 onboarding 步骤,包括 connection-ready(连接就绪)与 first-response(首次响应)的耗时。当 setup 或 onboarding 失败时,只上报一个“有界的分类”(bounded category)来描述失败发生的步骤,不会发送底层错误信息。
  3. eve dev 上下文:连接的是本地还是远程 Agent(target),UI 是交互式(TUI)还是无头模式(ui)。
  4. 随机标识符: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)

从实现角度看,这一边界的保证来自三处:

  1. 命令归一化白名单:如上一节所述,canonicalCommand() 只输出命令路径,绝不携带参数值(参见 index.ts 与 index.test.ts)。
  2. 错误信息脱敏:trackOutcome 只记录 outcome 枚举值;失败细节最多映射为有界分类码,底层 Error 对象从不序列化(index.ts)。
  3. 事件字段白名单式构建:所有事件都通过 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)的流程如下:

  1. 检查 isEnabled(),关闭或事件为空则直接返回;
  2. 按环境决定使用临时身份或持久身份,并追加 identity_kind、installation_id、project_id 与全部 setup 事件;
  3. 若设置了 EVE_TELEMETRY_DEBUG,把批次打印到 stderr 后返回(不发送);
  4. 否则 spawn 一个 detached(分离)子进程:用当前 Node 可执行文件重新执行 eve telemetry flush <payload>,并显式设置 EVE_TELEMETRY_DISABLED=1 防止子进程再次收集,子进程 stdio: "ignore"、unref() 脱离父进程生命周期——父命令立即结束,发送在后台完成;
  5. 子进程(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 秒超时;
  6. 所有发送路径都被 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。

登录后查看全文
eve