Agent Orchestrator 产品遥测(Telemetry)机制全解:数据边界、隐私设计与关闭指南

原创2026-09-22 15:49:321,724 阅读

Agent Orchestrator 产品遥测(Telemetry)机制全解:数据边界、隐私设计与关闭指南

产品遥测是 Agent Orchestrator(AO)用于理解自身使用情况与发布质量的数据管道:它收集有限的产品使用与可靠性数据,帮助团队判断哪些功能真正有用、哪些版本工作正常。本指南基于 docs/telemetry.md 展开,并结合后端遥测适配器(backend/internal/adapters/telemetry)、配置解析(backend/internal/config/config.go)与前端渲染进程代码(frontend/src/shared/telemetry.ts)的源码实现,完整说明 AO 发送什么、明确不发送什么、如何在底层限制数据,以及如何通过环境变量彻底关闭桌面端与守护进程的遥测。

产品遥测的定位与默认状态

AO 收集有限的产品使用与可靠性数据,用于学习应用哪些部分有用、发布是否按预期工作。需要明确的关键设计是:

  • 不与账户绑定:AO 不附加姓名或邮箱地址。
  • 伪匿名而非完全不可关联:由于随机安装标识符的存在,同一安装的多次事件可以在时间上被聚合统计——这使数据是"伪匿名"(pseudonymous)而非"不可关联"(unlinkable)。

从部署形态看,遥测的默认开关因构建类型而异:

构建类型 远程遥测状态
生产桌面端、移动端正式发布 启用
打包的桌面发布(其启动的 daemon) 启用
开发构建 默认关闭
直接启动的 daemon(不经过桌面端) 默认关闭

这一"开发构建默认关闭"的策略在前端源码中有直接体现。frontend/src/shared/telemetry.ts 中的 rendererTelemetryEnabled 逻辑为:只有显式设置 AO_TELEMETRY_RENDERER=on 时才强制开启,显式 off 时强制关闭,未设置时则回落到 isPackaged 判断——未打包的普通开发会话不会作为真实安装进入生产遥测项目,只有显式设置该变量才可让开发构建"故意参与"测试。

AO 发送什么:事件类别与载荷边界

AO 发送结构化事件,大致分为几大类:

  • 应用使用:启动 AO、查看界面某一粗粒度区域、开始任务或 agent 会话等。
  • 功能结果:创建项目、启动 agent、连接移动应用、安装更新是否成功。
  • GitHub 组织/账户段(owner segment):项目配置的 remote 所属的 GitHub 组织或账户,仅在"添加项目"事件中记录。只发送 owner 段,绝不发送仓库名、路径或 URL。对于个人仓库,该 owner 就是用户本人的 GitHub 用户名,因此这一特定值并非匿名;其用途是理解哪些组织和开发者从 AO 中获得最大价值,以便排定改进优先级并主动联系反馈。
  • GitHub 用户名:登录 AO GitHub 集成账户的用户名,在 session-start 事件中发送,用于识别最活跃的开发者并联系反馈。它属于产品遥测的一部分,没有独立的开关(详见下文"共享你的 GitHub 用户名")。
  • 可靠性数据:错误类型与上下文、脱敏后的崩溃消息与堆栈、HTTP 状态码、agent 等待输入等。
  • 基础环境信息:AO 版本、操作系统、发布渠道、可用的 agent 类型。
  • 随机安装标识符与单向哈希:事件需要时附带随机安装标识符,以及项目/会话标识符的哈希。
  • 移动端粗粒度使用:配对、重连、完成 onboarding、打开通知、使用核心操作。
  • 粗粒度地理位置:PostHog 根据连接 IP 在事件接收时推导出的国家(及可用的地区、城市)。AO 不解析、不发送精确坐标,也不存储 IP 本身;该功能对所有安装开启,仅用于聚合分析(了解 AO 在哪些地区被使用),不与 GitHub 用户名关联,也没有独立关闭项——关闭遥测(见下文)会一并停止它。

PostHog 处理与身份标识

AO 使用 PostHog 处理远程产品遥测。PostHog 会接收标准连接与设备元数据(连接 IP、设备类型、操作系统),而 AO 保留 PostHog 基于 IP 的位置推导能力,以便进行上述聚合地理分析。

安装标识符使 PostHog 能将同一 AO 安装的活动随时间分组;项目与会话标识符的哈希同样能在不发送明文标识符的前提下,对同一项目或会话的事件分组。两者都不与 AO 账户关联。

源码中的事件白名单与形状校验

遥测事件并非"发送一切",而是经过严格的**事件级白名单(payload allowlist)**过滤。backend/internal/adapters/telemetry/posthog.go 中的 remotePayloadAllowlist 定义了每个事件名允许携带的属性集合,例如:

  • ao.onboarding.first_project_added 仅允许 has_git_remote、kind、github_org、scm_provider;
  • ao.session.spawned 仅允许 duration_ms、harness、kind、github_actor;
  • ao.daemon.started 仅允许 agent、port;
  • ao.http.5xx 仅允许 component、duration、error_code、error_kind、fingerprint、method、operation、path、status、status_family 等字段。

该文件中 sanitizeRemotePayload(posthog.go)会丢弃一切不在白名单内的字段,sanitizeRemoteValue(posthog.go)进一步约束值类型:字符串需非空、数字需去除 NaN/Inf、非标量类型一律丢弃。

命令类属性(command、command_path)还有额外保护:isAllowedCommandValue(posthog.go)要求命令必须落在 remoteCommandTokens(如 add、agent、start、session、status 等)的封闭词表内,且 command 必须为单个 token、command_path 必须以 ao 开头;不满足条件的值会被替换为 sha256: 前缀的哈希摘要,绝不外发任意文本。每条导出的 PostHog 事件还会携带 telemetry_schema_version(当前为 2)、client(cli/desktop/mobile)等固定属性,并显式设置 $process_person_profile: false 跳过 PostHog 的人档案处理。

AO 明确不发送什么

产品遥测在设计上不包含:

  • 源代码、diff、提交、文件内容
  • Prompt、agent 对话、agent 输出、终端内容
  • Shell 命令参数、命令历史、环境变量
  • 仓库名、项目名、分支名、明文文件路径
  • API 密钥、访问令牌、密码或其他凭据
  • 姓名或邮箱地址

两个例外即上文所述的 GitHub owner 段与已认证的 GitHub 用户名,其中 owner 段仅限于所属组织或账户,绝不包含仓库、路径或 URL。除此之外,产品遥测被设计为不携带账户身份。

另外,网站 waitlist(候选名单)与产品遥测相互独立:如果你在网站上提交了邮箱地址、公司角色与社交主页,这些数据仅用于管理该 waitlist,并遵循相应的隐私政策。

AO 如何限制数据:从安装 ID 到出口链路的六道防线

文档阐述了多层次的限数措施,源码提供了每一条的具体实现:

  1. 随机安装标识符,不关联个人账户。AO 在首次运行时生成随机安装标识符,存储于 ~/.ao/data/telemetry_install_id(或在 AO_DATA_DIR 下),不与个人账户关联。后端实现见 posthog.go 的 loadOrCreateInstallID:以 ins_ 前缀 + UUID 生成,以 0o600 权限写入;前端渲染进程在 telemetry.ts 中采用完全相同的文件路径与格式,保证桌面端与 daemon 共用同一安装标识符。

  2. 项目/会话标识符单向哈希。遥测中的项目与会话标识符以 SHA-256 单向哈希(sha256String,posthog.go)形式发送为 project_id_hash、session_id_hash,既隐藏明文,又保留分组能力。

  3. 本地路径与本地 URL 脱敏。桌面端事件中检测到的绝对本地路径与本地应用 URL,在发送前会被替换为脱敏标记。

  4. 属性白名单过滤。发送到 PostHog 的 daemon 事件与移动端事件只接受固定属性集合,意外字段一律丢弃——即上文所述 remotePayloadAllowlist。

  5. 事件限流。RateLimitedSink(backend/internal/adapters/telemetry/ratelimit.go)为每个事件名设置双重上限:每分钟最多 5 条(突发上限)与每天最多 200 条(硬性日上限),防止重试风暴与错误循环造成失控;经过聚合的事件名则使用更宽松的每天 1500 条作为结构性兜底。限流只作用于远程(计费)sink,本地存储保留每一次发生。

  6. 会话录制禁用。桌面端与移动应用均禁用会话录制,AO 不会自动记录屏幕、点击或触摸。

此外还有两点值得注意的细节:

  • 聚合压缩突发量。AggregatingSink(backend/internal/adapters/telemetry/aggregate.go)把 ao.http.5xx、ao.daemon.panic、ao.cli.usage_errors 等突发型事件在每个分钟窗口内折叠为一条带 count、window_start、window_end 的汇总事件,使成本随窗口数(而非发生次数)增长,同时保留突发真实规模。汇总名单在 backend/internal/daemon/telemetry_wiring.go 中定义。

  • denylist 远程急停开关。DenylistSink(backend/internal/adapters/telemetry/denylist.go)是"遥测急停开关":通过 AO_TELEMETRY_DISABLED_EVENTS 配置的事件流会立即从远程出口链路中静默(支持 ao.renderer.* 这类前缀通配,大小写不敏感),无需等待用户安装新构建即可在线上静音某个昂贵或吵闹的事件流;本地 SQLite 仍记录一切,保证可调试。

事件出口链路(sink 装配顺序)

backend/internal/daemon/telemetry_wiring.go 中的 newTelemetrySink 展示了完整的数据管线装配顺序:

事件 → FanoutSink
        ├── LocalSQLiteSink(本地全量记录,30 天保留)
        └── DenylistSink(急停)
              └── AggregatingSink(突发折叠为每分钟 rollup)
                    └── RateLimitedSink(每分钟 5 / 每天 200)
                          └── PostHogSink(白名单过滤 + 重试导出)
  • 本地事件写入 SQLite(LocalSQLiteSink,localsqlite.go),保留期为 30 天,每小时执行一次批量清理(PruneTelemetryEventsBefore,批量上限 1000 条)。
  • PostHog 导出器(PostHogSink,posthog.go)采用 128 容量的缓冲通道、best-effort 语义:每个事件携带固定 UUID 作为 PostHog 幂等键,重试仅针对瞬时失败(连接错误、429、5xx),最多 2 次、间隔 200ms,且重试背压可被 shutdown 上下文取消。
  • 每个事件还会附带 install_age_days、active_days 与 tenure 桶(首日 d0、首周 d1_6、首月 w1_4、季度 m1_2、半年 m3_5、长期 m6_plus),由 tenure.go 的 tenureTracker 基于本地状态文件 telemetry_tenure.json 计算,把"留存"变成可下钻的属性而非 cohort 查询。

当 AO_TELEMETRY_EVENTS 未开启时,整个链路退化为 NoopSink(无操作);当 AO_TELEMETRY_REMOTE 不是 posthog 时,仅保留本地 SQLite 记录。

Agent-switch 失败上报(已分阶段、生产默认禁用)

AO 包含一条独立的、需明确同意的可靠性路径,用于异步 agent-switch 失败的异步上报。它是有意"仅失败"的设计:成功的切换、预期的校验拒绝、幂等重放、过期回调、或已被证明恢复的瞬时条件,都不会产生失败回执(receipt)、outbox 载荷或 Sentry 事件。

当未来版本启用时,合格失败事件被严格限制在一组封闭的操作字段内:事件 ID 与发生时间;有界的标题、级别、环境、平台、操作系统、release 与 channel;报告种类、子系统、分类调用点、持久化阶段、失败点、宽泛错误/故障码、执行与会话模式、源/目标 harness、目标启动模式、运行时后端、调用结果、所有权、补偿、用户影响、耗时桶,以及三态源停止/目标所有者/恢复门事实。本地 outbox 的 schema/信封版本不作为事件字段导出。合格语义与进程事件可携带有界的、已消毒的堆栈(含仓库相对文件名、行号、包与函数名);panic 事件必须带这些消毒帧,但绝不包含 panic 值。事件不包含 prompt、对话内容、终端输出、命令、provider 载荷、仓库或分支名、本地路径、运行时句柄、原生身份、switch/session/project 标识符、原始错误或 panic 值;用于判断前端失败是否仍然当前的本地标识符,在构造事件前会被剥离。

该路径的本地投递语义同样严谨:

  • 合格 daemon 事件先存入专用本地投递 outbox,再行网络投递。每条 pending/leased/delivered/discarded 载荷行有硬性的七天过期。
  • 已同意的载荷刻意与 switch 外键解耦——删除 switch 或 session 不会在 TTL 前删除该载荷。
  • 独立的无载荷回执防止同一事件被重复登记;terminal/run 回执保留七天,未解决的回执在其 switch 未解决期间可保留,解决后再保留七天。回执只含最小本地去重事实,绝不远程发送。
  • 同意开启不会回填旧的 terminal switch 历史;它可能把当前未解决恢复标记作为新事件在同意时登记,从而在不导出同意前时间戳的前提下上报仍影响用户的问题。
  • 投递为 at-least-once:若 provider 接受了事件但响应丢失,AO 可能重试同一事件 ID,产生多条 provider occurrence,由稳定指纹(fingerprint)归并为同一 issue。

必需的退出(opt-out)序列为:Electron 主进程关闭并排空其 sender → daemon 关闭并排空其投递门 → 主进程持久写入"已禁用"的同意代(consent generation)→ daemon 重读该代、镜像并清除所有 outbox 载荷 → 主进程清除本地传输缓存与 renderer 队列 → 之后 UI 才可确认变更。若 daemon 不可用或任何清理无法被证明完成,UI 会报告 cleanup_pending 而非宣称完成。无载荷回执仅保留以阻止后续重复登记;provider 可能已接受了取消前在途的请求,AO 无法召回已送达 provider 的数据。

需要明确的是:该路径当前在生产环境为禁用状态。它使用 Sentry 作为预期处理器,但 Sentry 组织的 IP 存储/擦除设置、数据驻留、保留与自动上下文设置尚未获得所需的带日期隐私批准,因此生产特性开关保持关闭,AO 不会在生产环境初始化该 agent-switch Sentry sender。Windows 上采用"失败即关闭"策略:事件同意视为禁用,且在经测试的原生写入替换实现满足策略文件持久性契约之前,启用确认会被拒绝。

共享你的 GitHub 用户名

AO 会解析其 GitHub 集成中登录的 GitHub 账户,并在 session-start 事件中包含该用户名。它以两种形式发送:

  • 事件属性 github_actor;
  • PostHog person 属性(设置在 AO 的共享安装 person 上),用于按 GitHub 用户名分组产品活动并联系活跃用户反馈。

发送条件是严格的:仅当登录账户为个人(人类)账户时发送;绝不发送组织或 bot token;若无 GitHub token 可用则什么都不发送。该 handle 属于产品遥测,没有独立开关——关闭遥测(见下文)即停止发送(承载它的 session-start 事件将不再发送)。已存储在 PostHog 的早期事件不会被追溯删除。

源码层面,github_actor 出现在 ao.session.spawned 事件的白名单中(posthog.go);PostHogSink.properties 首次携带该属性时,通过原子 CAS 只发送一次 $set person 属性(posthog.go),避免每个 spawn 事件都产生识别型计费。

关闭桌面端与 daemon 遥测

桌面端 General Settings 页包含 Event reporting 控件(针对上述分阶段的 agent-switch 可靠性路径);而现有的桌面/daemon 产品遥测路径继续由以下环境变量控制。需要在启动 AO 的环境中同时设置全部三个变量:

export AO_TELEMETRY_RENDERER=off
export AO_TELEMETRY_EVENTS=off
export AO_TELEMETRY_REMOTE=off

然后重启 AO。三个变量的作用与源码对应关系如下:

环境变量 作用 源码位置
AO_TELEMETRY_RENDERER=off 禁用桌面界面直接发送的事件(renderer 遥测) frontend/src/shared/telemetry.ts
AO_TELEMETRY_EVENTS=off 禁用 daemon 事件捕获,包括其本地副本 backend/internal/config/config.go
AO_TELEMETRY_REMOTE=off 显式禁用 daemon 向 PostHog 的导出 backend/internal/config/config.go

配置解析(backend/internal/config/config.go)还支持以下相关变量:

  • AO_TELEMETRY_METRICS:本地指标采集 off|on(默认 off);
  • AO_TELEMETRY_POSTHOG_KEY:PostHog 项目 key;
  • AO_TELEMETRY_POSTHOG_HOST:PostHog 主机(默认 https://us.i.posthog.com);
  • AO_TELEMETRY_DISABLED_EVENTS:逗号分隔的远程事件停用列表(急停开关);
  • AO_TELEMETRY_APP_VERSION:daemon 启动方(桌面 supervisor)盖印的应用版本;
  • AO_SENTRY_DSN:daemon 侧 Sentry 捕获(5xx 与 panic),与 PostHog 相互独立。

parseToggleEnv 接受 on/true/1/yes 与 off/false/0/no(大小写不敏感);parseTelemetryRemote 仅接受 off 或 posthog。值得强调的是,AO_TELEMETRY_DISABLED_EVENTS 的解析永远不会让 daemon 启动失败——不可解析或拼写错误的条目只是无效,因为急停开关的价值就在于事故发生时能立刻使用(config.go)。

需要注意的几个使用前提:

  • 变量必须到达桌面应用进程本身。例如,macOS 下从 Finder 或 Dock 启动 AO 时,shell 启动文件中的变量可能不会被继承。
  • 仅运行 daemon(不启动桌面应用)时:事件捕获与远程导出默认已关闭,除非显式开启。
  • 这些环境变量不控制移动应用。当前生产移动应用不提供应用内遥测退出选项。
  • 关闭桌面/daemon 产品遥测会停止新的收集,但不会:删除已发送到 PostHog 的事件、移除本地安装标识符、或删除已有的本地产品遥测记录。若重新开启 daemon 事件捕获,超过 30 天的本地记录自动删除会恢复执行。
  • 独立的 Event reporting 退出项遵循上述清除序列:它删除 agent-switch outbox 载荷,但保留产品恢复所需的可持久 switch/失败状态与无载荷去重回执。

隐私保留与本地数据生命周期

除远程遥测外,daemon 还可在 AO 的 SQLite 数据库中保留一份本地操作事件副本。本地遥测激活期间,AO 会周期性清除超过 30 天的记录;这些数据始终位于本机 ~/.ao 目录下,不会自动离开机器。实现上,LocalSQLiteSink 以 30 天保留期、每小时最多清理一次、每批 1000 条的方式执行(localsqlite.go)。

如果你发现本页文档存在错误,或在更广泛的数据策略、保留信息与联系方式上需要查阅,可参考项目仓库中 docs/telemetry.md 原文末尾提供的官方隐私政策入口与问题反馈途径;从工程角度看,backend/internal/adapters/telemetry 目录(含 posthog_test.go、ratelimit_test.go、aggregate_test.go、denylist_test.go、sanitize_command_test.go 等测试)与 backend/internal/daemon/telemetry_wiring_test.go 是验证上述全部行为的首选阅读与测试入口。

登录后查看全文
agent-orchestrator