Beads 的 `bd metrics` 命令：匿名使用指标的状态查看、数据透明与一键开关

Beads 的bd metrics命令：匿名使用指标的状态查看、数据透明与一键开关

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

导读

bd metrics是 Beads（bd）内置的匿名使用指标管理命令，用于查看指标当前的开关状态、了解"到底收集了什么数据、发往何处"，并通过bd metrics on/off在命令行直接切换开关——无需手改配置文件、无需设置环境变量、无需重启任何进程。本文以 metrics.md 为骨架，结合 cmd/bd/metrics.go 及 internal/metrics 下的底层实现，带你完整掌握该命令的四种用法、隐私承诺的源码级印证，以及事件从本地队列到远端上报的完整数据链路。

一、命令概览：bd metrics 能做什么

bd metrics命令组共包含四个子命令，覆盖"查看状态、查看示例、开启、关闭"四个场景：

bd metrics show the current status and what is collected bd metrics on turn metrics on bd metrics off turn metrics off bd metrics example show real examples of the events bd sends

通用语法形式为：

bd metrics [flags] bd metrics example [flags] bd metrics off [flags] bd metrics on [flags]

提示：本文档（docs/cli-reference/metrics.md）由bd help --doc metrics自动生成，属于自动生成文件，内容以bd help metrics的实时输出为准。

与"一键开关"对应的设计意图

从 cmd/bd/metrics.go 的注释可以看出，该命令的设计初衷是：让用户永远不需要手改配置文件或设置环境变量来管理指标开关。bd metrics on/off直接写入用户全局配置文件，并在下一条命令生效，无需重启 shell 或守护进程。bd metrics本身也会记录一条cli_command事件（命令名称为metrics、metrics-on、metrics-off、metrics-example），与所有其他命令一样遵循相同的匿名上报规则。

二、bd metrics：查看当前状态与收集范围

不带子命令执行bd metrics，会打印三块信息：

1. 当前开关状态：Anonymous usage metrics: ON/OFF，其中状态值由"生效中的指标开关解析逻辑"（resolveMetricsEnabled）计算得出——它不仅读取配置，还会考虑环境变量覆盖。
2. 收集内容声明：明确列出收集范围——每个bd命令的名称、bd 版本、操作系统平台，并强调"绝不收集 issues、路径、远程仓库、身份信息或任何用户输入文本"。
3. 上报地址：Where it goes:后跟随当前生效的上报端点。

同时，若存在与环境变量冲突的情况，命令会在 stderr 输出提示（见下文"环境变量覆盖"一节）。

数据收集范围（源码印证）

在 internal/metrics/metrics.go 中可以看到核心常量定义：

事件模型在NewCommandEvent（internal/metrics/metrics.go）中定义：每种命令只产生一种事件cli_command，唯一的自定义属性是command（命令名）。collector 初始化时（Init）会注入distinct_id（机器派生、HMAC 保护的 ID）、app_name、app_version和平台信息。

三、bd metrics on/bd metrics off：一键开关

使用方法与输出

bd metrics on # 开启匿名使用指标 bd metrics off # 关闭匿名使用指标

开启成功后输出类似：

✓ Anonymous usage metrics are now ON. Thank you — this genuinely helps us make bd better! See what's sent with `bd metrics example`, or turn it off again with `bd metrics off`.

关闭成功后输出：

Anonymous usage metrics are now OFF. No usage data will be collected or sent. Turn them back on anytime with `bd metrics on`. Thanks for giving them a try!

底层实现：写入用户全局配置

两个子命令最终都调用setMetricsDisabled（cmd/bd/metrics.go）：

func setMetricsDisabled(disabled bool) error { val := "false" if disabled { val = "true" } return config.SetUserYamlConfig("metrics.disabled", val) }

关键点：metrics.*配置前缀会自动路由到用户全局配置（而非项目配置），因此bd metrics on/off与运行时读取的是同一个存储，不需要手改任何文件，也不依赖环境变量。对应的测试 cmd/bd/metrics_test.go 验证了：执行bd metrics off后用户配置文件包含disabled: true，执行bd metrics on后变为disabled: false。

关闭命令的特殊性：不记录退出事件

bd metrics off是唯一不发射cli_command事件的命令。原因在 cmd/bd/metrics.go 的注释中讲得很清楚：退出时配置才在下次生效，本次调用中指标仍是开启状态，若记录metrics-off事件，就会把用户刚刚拒绝的数据排入队列并在未来 flush——直接违背输出中的承诺"No usage data will be collected or sent"。因此它只写入退出偏好，不向 collector 添加任何事件。

四、bd metrics example：查看真实发送的载荷

bd metrics example的输出由两部分组成：

1. 一份代表性 JSON 载荷示例，结构为：

{ "distinct_id": "(machine-derived, HMAC-protected — not your identity)", "app_name": "beads", "app_version": "<bd version>", "platform": "<os>", "events": [ { "name": "cli_command", "attributes": [ { "key": "command", "value": "ready" } ] } ] }

载荷字段与 cmd/bd/metrics.go 中构造的examplemap 完全一致：distinct_id是机器派生且经 HMAC 保护的 ID，events中唯一的 per-event 属性是命令名。

2. 本机真实排队中的事件：命令会读取本地事件目录（~/.beads/eventsData，见DataDir），把当前缓存、等待 flush 的真实批次文件（最多展示 3 个）原样格式化打印出来。这是"最诚实的 what we send"——直接展示即将离开你机器的真实数据。如果本地没有排队事件，会提示先运行几条命令再重试。

相关实现细节：

• JSON 输出通过marshalIndentNoEscape（cmd/bd/metrics.go）生成，关闭了 Go 默认的 HTML 转义，<、>、&会原样显示。
• 测试 cmd/bd/metrics_test.go 同时断言了两件事：输出必须包含cli_command、command、platform、app_name；且不得包含Dolt engine、dolt_mode等 bd 实际并不发送的内容——防止示例夸大收集范围。

五、隐私边界的源码级印证

5.1 机器 ID：HMAC 保护 + 本地缓存

distinct_id由cachedMachineID（internal/metrics/machineid.go）提供：

• 首次计算通过eventkit.MachineID(appName)得到应用作用域内的 HMAC 值（machineid.ProtectedID），而非原始机器 ID；
• 计算结果缓存到~/.beads/machine-id文件（权限0600），后续所有调用（包括分离的 send-metrics 子进程）直接复用，避免每次调用付出约 20ms 的平台探测开销；
• 缓存读取有严格校验（validMachineID：非空、长度不超过 128、全部为可打印 ASCII、且不等于字面量invalid），损坏或异常文件会被拒绝而重新计算；
• 只有指标开启时才会计算机器 ID——关闭状态下 collector 使用惰性的"disabled"占位符，NullEmitter丢弃一切事件。

5.2 项目配置无法覆盖用户选择

在 cmd/bd/main.go 的resolveMetricsEnabled中，启用状态只从环境变量 + 用户全局配置解析，绝不读取合并后的项目/BEADS_DIR 配置。原因写得很明确：否则仓库的.beads/config.yaml（viper 最高优先级）就能替已执行bd metrics off的用户重新开启指标。端点解析resolveMetricsEndpoint（cmd/bd/main.go）同理——仓库永远无法重定向你的指标上报地址。回归测试见 cmd/bd/metrics_test.go（TestResolveMetricsIgnoresProjectConfigOverride）。

六、环境变量覆盖：BD_DISABLE_METRICS 与 DO_NOT_TRACK

指标开关的最终生效值由三层决定，优先级从高到低：

对应的命令行表现：

• bd metrics（状态查看）在环境变量与已保存配置冲突时，会在 stderr 提示：Note: BD_DISABLE_METRICS=1 is overriding your saved config (which is "on") for this shell.
• bd metrics on/off之后若存在冲突的环境变量，warnIfMetricsEnvOverride会提示：Your config preference is saved; unset BD_DISABLE_METRICS to let it take effect.

metricsEnvOverride（cmd/bd/metrics.go）的实现细节：两者同时设置时优先报告BD_DISABLE_METRICS；falsey 的DO_NOT_TRACK因不产生任何覆盖效果而不会被报告。

七、数据链路：从命令事件到远端上报

理解bd metrics背后完整的指标管线，有助于判断"数据何时真正离开机器"：

1. 采集：每条命令执行时通过metrics.NewCommandEvent(cmdName)创建cli_command事件（internal/metrics/metrics.go）。
2. 落盘：开启状态下，collector 使用eventkit.NewFileEmitter将事件批次写入~/.beads/eventsData（DataDir定义于 internal/metrics/metrics.go），而不是立即发送——这保证了即使进程崩溃事件也不丢失。
3. 命令收尾：main执行完命令后调用metrics.CloseAndFlush()（internal/metrics/metrics.go），在 500ms 预算内关闭 collector 将排队事件写盘，然后MaybeSpawnFlusher决定是否派生后台发送进程。
4. 后台发送：MaybeSpawnFlusher（internal/metrics/spawn.go）派生一个分离的bd send-metrics子进程，通过 GA4 传输层将队列 flush 到端点（internal/metrics/flusher.go）。

管线中有三个值得注意的工程细节：

• 节流：默认每 5 分钟最多派生一次发送子进程（flushInterval），通过eventsData目录内的.last-flush标记 mtime 判断（internal/metrics/spawn.go），避免每次调用都付出全量 re-exec 与 HTTPS POST 的开销。
• 队列有界：发送前PruneQueue（internal/metrics/prune.go）先清理——超过 7 天 TTL 的批次删除、存活的批次按"最老优先"裁到最多 10,000 个文件 / 64 MiB 上限；孤儿临时文件（.write-*）也被回收。清理与上限逻辑的常量定义见 internal/metrics/prune.go。
• 防递归与环境固定：子进程环境标记BD_IS_FLUSHER=1防止 flusher 再派生 flusher；同时flusherChildEnv（internal/metrics/spawn.go）会剔除父进程继承的BEADS_METRICS_ENDPOINT，并把端点固定为父进程已从"环境变量 + 用户全局配置"解析出的值——防止恶意仓库通过项目.beads/.env劫持指标上报地址。
• 退出后仍清理：即使指标已关闭，分离的子进程仍会执行队列清理（send-metrics在Enabled()检查之前先PruneQueue），确保此前开启时遗留的积压队列在退出机器上也能衰减，而不是永远滞留（见 internal/metrics/flusher.go 与 internal/metrics/spawn.go）。

八、首次运行提示：一次性的知情同意

在开启指标的状态下，bd 首次运行时会在 stderr 打印一段友好的知情提示（cmd/bd/metrics.go），说明收集内容并给出bd metrics example与bd metrics off两个指引，然后通过写用户全局配置metrics.notice_shown: true记录"已展示"，保证只出现一次。

但该提示有严格的上下文抑制机制（firstRunNoticeSuppressedByContext，cmd/bd/metrics.go），以下场景绝不输出提示，以免污染机器可读输出或破坏协议信封：

• JSON / quiet / hook-JSON 输出模式；
• git-hook 执行环境（BD_GIT_HOOK=1）；
• bd metrics命令本身及其子命令；
• hook/协议桥接类命令：hook、hooks、codex-hook、prime、send-metrics；
• version、completion、__complete及 shell 初始化类命令（bash/zsh/fish/powershell）；
• 根命令--version/-V探测；
• bd init --stealth（隐形初始化）。

这些抑制规则均有单元测试覆盖（cmd/bd/metrics_test.go），例如普通交互命令bd list应正常触发提示，而 JSON 输出、git-hook、--stealth等上下文必须抑制。

九、适用前提与注意事项

• 配置文件位置：bd metrics on/off写入的是用户全局配置文件（macOS/Linux 为~/.config/bd/config.yaml等用户级路径），与项目内.beads/config.yaml相互独立；项目配置无权覆盖用户的选择。
• 生效时机：开关在下一条命令生效；当前正在执行的命令仍按原状态运行。
• 环境变量优先：若 shell 中设置了BD_DISABLE_METRICS或 truthy 的DO_NOT_TRACK，bd metrics on不会"无效"——偏好会保存，但当前 shell 仍由环境变量决定；命令会明确提示这一情况。
• 调试与自检：想确认"到底发什么"，运行bd metrics example查看本地排队载荷；想核对解析逻辑与优先级，可阅读 cmd/bd/main.go 的resolveMetricsEnabled/resolveMetricsEndpoint/envTruthyValue。

总结

bd metrics把"匿名使用指标的知情与管控"收敛为四个可直接执行的子命令：bd metrics查状态、bd metrics example看真实载荷、bd metrics on/off一键切换。其背后的实现始终围绕两条主线：最小化收集（仅有命令名、版本、平台与 HMAC 机器 ID，单事件类型）与用户主权不可剥夺（项目配置无法覆盖用户退出选择、关闭命令本身不产生事件、环境变量覆盖会被显式提示）。结合 cmd/bd/metrics.go、internal/metrics 与 cmd/bd/metrics_test.go 中的实现与测试，你可以完整验证这套承诺在代码层面的每一处落地。

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads