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

Beads 的bd metrics命令匿名使用指标的状态查看、数据透明与一键开关【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读bd metrics是 Beadsbd内置的匿名使用指标管理命令用于查看指标当前的开关状态、了解到底收集了什么数据、发往何处并通过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会打印三块信息当前开关状态Anonymous usage metrics: ON/OFF其中状态值由生效中的指标开关解析逻辑resolveMetricsEnabled计算得出——它不仅读取配置还会考虑环境变量覆盖。收集内容声明明确列出收集范围——每个bd命令的名称、bd 版本、操作系统平台并强调绝不收集 issues、路径、远程仓库、身份信息或任何用户输入文本。上报地址Where it goes:后跟随当前生效的上报端点。同时若存在与环境变量冲突的情况命令会在 stderr 输出提示见下文环境变量覆盖一节。数据收集范围源码印证在 internal/metrics/metrics.go 中可以看到核心常量定义常量值含义AppNamebeads事件中的应用名DefaultEndpointhttps://gastownhall-eventsapi.com/mp/collect默认上报端点EnvDisableMetricsBD_DISABLE_METRICS指标总开关环境变量EnvDoNotTrackDO_NOT_TRACK跨工具标准的禁用别名EnvDisableEventFlushBD_DISABLE_EVENT_FLUSH禁用后台 flush 进程事件模型在NewCommandEventinternal/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 whats 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!底层实现写入用户全局配置两个子命令最终都调用setMetricsDisabledcmd/bd/metrics.gofunc 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的输出由两部分组成一份代表性 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 保护的 IDevents中唯一的 per-event 属性是命令名。本机真实排队中的事件命令会读取本地事件目录~/.beads/eventsData见DataDir把当前缓存、等待 flush 的真实批次文件最多展示 3 个原样格式化打印出来。这是最诚实的 what we send——直接展示即将离开你机器的真实数据。如果本地没有排队事件会提示先运行几条命令再重试。相关实现细节JSON 输出通过marshalIndentNoEscapecmd/bd/metrics.go生成关闭了 Go 默认的 HTML 转义、、会原样显示。测试 cmd/bd/metrics_test.go 同时断言了两件事输出必须包含cli_command、command、platform、app_name且不得包含Dolt engine、dolt_mode等 bd 实际并不发送的内容——防止示例夸大收集范围。五、隐私边界的源码级印证5.1 机器 IDHMAC 保护 本地缓存distinct_id由cachedMachineIDinternal/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.yamlviper 最高优先级就能替已执行bd metrics off的用户重新开启指标。端点解析resolveMetricsEndpointcmd/bd/main.go同理——仓库永远无法重定向你的指标上报地址。回归测试见 cmd/bd/metrics_test.goTestResolveMetricsIgnoresProjectConfigOverride。六、环境变量覆盖BD_DISABLE_METRICS 与 DO_NOT_TRACK指标开关的最终生效值由三层决定优先级从高到低优先级来源说明1BD_DISABLE_METRICS双向覆盖任意非空值0/false视为不禁用都直接决定开关即使已保存bd metrics off也可通过BD_DISABLE_METRICS0临时重新启用2DO_NOT_TRACK仅禁用方向truthy 值1/true等关闭指标0/false/空值则穿透到已保存的配置绝不会把已退出的用户重新开启回归测试 cmd/bd/metrics_test.go3用户全局配置metrics.disabled即bd metrics on/off写入的字段对应的命令行表现bd metrics状态查看在环境变量与已保存配置冲突时会在 stderr 提示Note: BD_DISABLE_METRICS1 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.metricsEnvOverridecmd/bd/metrics.go的实现细节两者同时设置时优先报告BD_DISABLE_METRICSfalsey 的DO_NOT_TRACK因不产生任何覆盖效果而不会被报告。七、数据链路从命令事件到远端上报理解bd metrics背后完整的指标管线有助于判断数据何时真正离开机器采集每条命令执行时通过metrics.NewCommandEvent(cmdName)创建cli_command事件internal/metrics/metrics.go。落盘开启状态下collector 使用eventkit.NewFileEmitter将事件批次写入~/.beads/eventsDataDataDir定义于 internal/metrics/metrics.go而不是立即发送——这保证了即使进程崩溃事件也不丢失。命令收尾main执行完命令后调用metrics.CloseAndFlush()internal/metrics/metrics.go在 500ms 预算内关闭 collector 将排队事件写盘然后MaybeSpawnFlusher决定是否派生后台发送进程。后台发送MaybeSpawnFlusherinternal/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 的开销。队列有界发送前PruneQueueinternal/metrics/prune.go先清理——超过 7 天 TTL 的批次删除、存活的批次按最老优先裁到最多 10,000 个文件 / 64 MiB 上限孤儿临时文件.write-*也被回收。清理与上限逻辑的常量定义见 internal/metrics/prune.go。防递归与环境固定子进程环境标记BD_IS_FLUSHER1防止 flusher 再派生 flusher同时flusherChildEnvinternal/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记录已展示保证只出现一次。但该提示有严格的上下文抑制机制firstRunNoticeSuppressedByContextcmd/bd/metrics.go以下场景绝不输出提示以免污染机器可读输出或破坏协议信封JSON / quiet / hook-JSON 输出模式git-hook 执行环境BD_GIT_HOOK1bd metrics命令本身及其子命令hook/协议桥接类命令hook、hooks、codex-hook、prime、send-metricsversion、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_TRACKbd 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考