PostHog Desktop 的 Agent-server 影子观察器agent-shadowGo 实现的只读健康观测与启动基线采集方案【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog导读本文基于 PostHog 仓库中 products/desktop/packages/agent-shadow/README.md 展开深入解析 agent-shadow 这一用 Go 编写、以只读方式旁路观测 agent-server 启动过程的小型进程。它通过轮询 agent-server 的/health接口在会话就绪或请求超时时输出一条 JSON 记录用于将「影子环境观测到的启动耗时」与「生产环境 agent-server 上报的启动耗时」配对对比从而为会话启动性能的回归分析提供可量化的基线数据。读完本文你将掌握 agent-shadow 的完整命令行参数、输出 JSON 契约、底层观测逻辑以及它与 TypeScript 侧AgentBootTracker的对应关系可直接在真实任务运行中复现和扩展这一观测方案。一、agent-shadow 是什么一个只读的影子观测进程在 PostHog Desktop 的 agent 运行时体系中agent-serverTypeScript 实现的会话服务进程见 products/desktop/packages/agent/src/server/agent-server.ts负责承载任务运行task run、建立会话、调用模型等核心职责。agent-shadow 则是与之配套的一个Go 进程它像影子一样“贴”在生产 agent-server 旁边运行但不做任何业务动作。根据原文档的明确表述agent-shadow 具备以下约束这也是理解它设计意图的关键它是只读read-only的观察者它不接受流量does not accept traffic它不启动会话does not start sessions它不修改仓库does not change repositories它不调用模型does not call models它不清理进程does not clean up processes。也就是说agent-shadow 的唯一职责是轮询生产 agent-server 暴露的健康检查端点观察会话从启动到就绪ready的全过程耗时并输出一条结构化 JSON 记录。这条记录会被上游的编排逻辑如任务运行管理器用来评估“在当前环境下启动一个 agent 会话需要多长时间”与生产侧的启动数据做对照。二、运行方式与全部命令行参数原文档给出了最直接的运行命令go run . --boot-id $POSTHOG_TASK_RUN_ID --health-url http://127.0.0.1:8080/health其中$POSTHOG_TASK_RUN_ID是任务运行task run的唯一标识符它同时出现在 agent-server 侧的引导信息与 agent-shadow 的观测结果中用来把“影子观测”和“生产观测”在时间维度上配对该环境变量在仓库内也被 agent-server 用于任务运行相关的 API 调用参见 agent-server.ts 中$POSTHOG_TASK_RUN_ID的使用。http://127.0.0.1:8080/health是 agent-server 在本机监听并暴露的健康检查地址。从 main.go 的flag定义可以确认agent-shadow 共支持四个命令行参数全部带有默认值只有--boot-id是必填项参数默认值说明--boot-id空字符串任务运行标识符用于把生产与影子两路观测配对为空时程序打印--boot-id is required并以退出码 2 终止--health-urlhttp://127.0.0.1:8080/health生产 agent-server 的健康检查 URL--poll-interval100ms健康观测的轮询间隔必须是正数否则以退出码 2 终止--timeout5m单次观测的最大持续时间超时后按failed结果输出注意--poll-interval的校验逻辑if cfg.PollInterval 0直接报错退出这是为了避免空转的紧密轮询打爆健康端点。此外命令是go run .意味着 agent-shadow 是一个独立的 Go module——go.mod 声明了module github.com/PostHog/posthog/products/desktop/packages/agent-shadow与go 1.23标准库之外无任何第三方依赖因此可以直接运行或交叉编译成单一二进制部署。退出码约定运行结束后agent-shadow 会依据观测结果设置进程退出码main.go观测结果为ready退出码为 0观测结果为failed超时或契约版本不支持等退出码为 1参数校验失败缺--boot-id、非正--poll-interval退出码为 2JSON 编码失败退出码为 1。这一约定让上游编排方可以不解析 JSON 就快速判断“本次影子观测是否成功”非常适合作为 CI 或任务运行脚本中的一个健康检查环节。三、输出的 JSON 契约agent-shadow 在观测结束会话就绪或超时时向stdout写入恰好一条JSON 记录对应源码中的shadowResult结构体main.go。字段如下字段类型含义contractVersionint契约版本当前恒为1用于兼容未来字段演进bootIdstring与--boot-id相同的任务运行标识符outcomestringready或failed二选一observedReadyMsint从影子进程启动到观测到会话就绪或失败所经过的毫秒数productionReadyMsint生产 agent-server 上报的启动总耗时boot.totalMsphasesMsmap各启动阶段耗时仅ready结果且经过白名单过滤后输出failed结果省略failureClassstring失败分类仅failed结果输出取值见下文成功结果示例结合 main_test.go 中TestObserveReadyContract的断言一条典型的ready记录形如{ contractVersion: 1, bootId: run-1, outcome: ready, observedReadyMs: 1200, productionReadyMs: 1200, phasesMs: { acp_initialize: 300 } }失败结果示例当 5 分钟超时仍未观测到就绪时输出{ contractVersion: 1, bootId: run-1, outcome: failed, observedReadyMs: 300000, failureClass: timeout }failureClass目前有两种取值timeout观测窗口内会话未就绪或健康端点持续不可达与unsupported_contract健康端点返回的boot.contractVersion不是 1说明影子观测器与生产 agent-server 的契约不匹配此时立即放弃观测。四、观测核心逻辑轮询、三重条件判断与阶段白名单observe函数main.go是整个进程的心脏其工作流程可以概括为四个要点1. 定时轮询而非被动等待进程启动时记录startedAt创建间隔为--poll-interval默认 100ms的 ticker然后进入一个循环每次先读取一次健康端点再用select同时等待「上下文到期」或「下一个轮询节拍」。这样即便健康端点短暂不可用也会在超时窗口内不断重试而不是一次性失败。2. 就绪判定是三重条件的与运算一次健康响应被判定为“会话就绪”必须同时满足main.gohealth.HasSession health.Readiness ready health.Boot.BootID cfg.BootIDHasSessionagent-server 已创建活动会话Readiness ready引导状态为就绪Boot.BootID cfg.BootID健康响应中的引导 ID 必须与本次任务运行的 ID 完全一致。第三重判断尤为关键——它防止影子观测器“误认”同一台机器上其它并发任务运行的会话为己方会话是保证观测结果与任务一一对应的核心机制。3. 契约版本校验一旦就绪条件满足立即检查health.Boot.ContractVersion ! 1不匹配则返回failed且FailureClass为unsupported_contract避免把新老版本之间的字段差异误当成真实性能数据。4. 阶段耗时白名单allowlist就绪后影子观测器并不会原样转发生产侧的所有phasesMs而是经过allowlistedPhasesmain.go过滤只保留以下五个阶段且只保留非负值阶段名含义依据 boot-phases.ts 中的AGENT_BOOT_PHASEScontext_fetch拉取任务上下文acp_initialize初始化 Agent Client Protocol 连接repository_ready仓库准备就绪session_dependencies会话依赖安装/准备session_create会话创建白名单之外的生产侧阶段例如测试中构造的secret_phase不会出现在影子输出中这既控制了对比记录的数据体积也避免了不必要地暴露生产内部的敏感或噪声指标——测试TestObserveReadyContract正是为此断言“non-allowlisted phase leaked into comparison record”会直接测试失败。五、与 TypeScript 侧 AgentBootTracker 的对应关系agent-shadow 并非凭空定义一套观测契约而是与 agent-server 内的引导追踪器严格对应。在 boot-phases.ts 中AGENT_BOOT_CONTRACT_VERSION 1与影子侧硬编码的ContractVersion: 1一一对应AGENT_BOOT_PHASES定义了与上述白名单完全一致的五个阶段名AgentBootTracker.snapshot()产出的AgentBootSnapshot含contractVersion、bootId、state、totalMs、phasesMs正是影子观测器解析的healthResponse.boot字段的源头markReady()在会话初始化成功时被调用并把状态置为ready调用点位于 agent-server.ts初始化异常时则调用markFailed()。而在 agent-server 的 HTTP 层agent-server.tsGET /health处理器直接以this.bootTracker.snapshot()作为boot字段返回同时给出hasSession、readiness等顶层字段——这正是影子观测器读到的healthResponse的真实生产来源。因此agent-shadow 的「观测基线」本质上是用独立的 Go 进程在系统层面重新测量一遍生产会话的启动耗时observedReadyMs与生产自报的productionReadyMsboot.totalMs做交叉验证。当两者出现系统性偏差时即可推断出进程内计时与进程外真实时间之间存在偏移从而定位计时口径问题或调度延迟。六、测试如何保证观测器行为正确main_test.go 用三个用例覆盖了影子观测器最关键的三个行为面可视为该组件的契约测试TestObserveReadyContract模拟健康端点返回hasSession: true, readiness: ready, bootId: run-1验证结果为ready、ProductionMS正确取到totalMs并确认非白名单阶段secret_phase被剔除TestObserveIgnoresMismatchedBoot健康端点返回bootId: another-run与观测目标不匹配验证即使响应本身是就绪的影子观测器也会继续轮询直至超时最终得到failureClass: timeoutTestObserveTimesOutWithoutCopyingErrors健康请求直接返回context.DeadlineExceeded验证观测器不会被底层错误打断而是保持「超时即失败」的稳定语义。测试通过自实现的roundTripFunc类型把http.Client替换为内存中的函数无需启动真实 agent-server既快又确定。这三个用例共同回答了一个问题无论健康端点如何异常影子观测器最终只会输出两种结果ready / failed且就绪判定绝不会张冠李戴。七、在任务运行体系中的定位与使用建议结合前文可见agent-shadow 是 PostHog Desktop 会话启动质量观测链路中的一个轻量探针。它的典型使用场景是在任务运行被编排启动时并行拉起 agent-shadow 进程并传入$POSTHOG_TASK_RUN_ID随后采集其 stdout 上的单条 JSON 作为该次运行的启动基线。由于它只读、无副作用可以安全地与生产 agent-server 共存于同一台机器、同一个命名空间。实操时需要注意几点确保--boot-id与 agent-server 的引导 ID 一致生产侧由$POSTHOG_TASK_RUN_ID注入否则观测结果永远是timeout默认--poll-interval100ms适合多数场景若健康端点负载敏感可适当调大间隔以降低轮询开销默认--timeout5m覆盖了绝大多数会话启动场景若网络环境较差可结合自身预期合理调整对输出 JSON 的处理应同时参考退出码exit 0表示readyexit 1表示failedexit 2表示参数错误无需解析内容即可快速分流。总结agent-shadow 用不到 160 行的 Go 代码main.go实现了一个职责极其纯粹的只读观测器轮询健康端点、三重条件判定就绪、契约版本校验、阶段白名单过滤最终输出单条可配对的 JSON 基线记录。它与 TypeScript 侧的AgentBootTrackerboot-phases.ts共享同一套契约版本1与五个引导阶段并通过 main_test.go 固化了行为边界。对于需要评估或优化 agent 会话启动性能的工程场景这套「进程外影子观测 生产自报」的双轨计量思路可以直接借鉴——它把主观的“启动快慢”变成了可交叉验证、可追溯的单条结构化数据。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考