PostHog 离线评测实战：基于 MCP 的 Markdown 笔记本 Agent 评测体系搭建指南

PostHog 离线评测实战：基于 MCP 的 Markdown 笔记本 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

导读

本文基于仓库内products/notebooks/plan/notebooks_mcp_evals_plan.md这份评测规划文档，系统讲解 PostHog 如何为「基于 MCP 工具创建与编辑 Markdown 笔记本」的 AI Agent 建立离线评测（offline evals）体系。你将理解：评测基建（eval harness）如何与 MCP server、Temporal、kernel 沙箱协同工作；如何设计创建型与编辑型评测用例（eval cases）；如何用「工具轨迹 → 数据库终态 → LLM 裁判」三层评分栈衡量 Agent 行为；以及如何编写 seeder 与 synthesizer 让评测数据可复现。文中的目录与代码均已按当前仓库实际实现核对，可对照阅读。

1. 评测体系的底座：独立 eval harness 与两种套件类型

PostHog 的 Agent 离线评测并不运行在 pytest 之上，而是由一个独立的评测框架承载——位于 products/posthog_ai/eval_harness/ 的 standalone harness。其运作方式是：hogli evals一次性启动共享基础设施（测试数据库、Django live server、LLM gateway、MCP server、Temporal、personhog），然后并发运行所有被选中的套件，以 Braintrust 作为评测引擎。

套件分两种类型，由模块级常量SUITE_KIND声明（见 harness/requirements.py）：

Notebook MCP 评测属于 sandboxed 类型：被测对象是「驱动真实工具、操作真实状态的 Agent」，一次性的单次调用根本无法覆盖这种行为。这也是整个评测设计的出发点。

围绕这套体系，规划文档强调了几条塑造设计的关键事实，均已在实际代码中得到印证：

• 按约定发现套件，无注册表：产品自有套件放在products/<product>/evals/（注意是复数evals/，单数products/signals/eval/是无关的 pytest 树），套件 ID 格式为<product>/<module>::<fn>，导入路径为products.<product>.evals.<module>。本评测的目录即为products/notebooks/evals/。
• 一个套件 = 一个 Braintrust experiment：experiment_name是历史键（history key），改名等于重置跨轮次对比。现有套件统一保留-cli后缀，以对齐历史上 MCP 的cli表面。
• 每个用例拥有独立组织/团队/用户：每个 case 都会从一个 master Hedgebox 团队克隆出自己的 org/team/user，用例之间永远看不到彼此的状态，预置用户名为 "Karen Smith"。
• Hedgebox 数据集在固定种子下可字节级复现：因此评测断言应检查形状和相对日期范围，绝不要断言绝对计数。
• case 字段：name、prompt、expected（按 scorer 的_name()键控）、metadata、setup（即 seeder）。seeder 的返回值会进入output["seed"]，这是 scorer 获取预置 ID 的唯一通道。
• harness 会给每个 experiment 自动添加ExitCodeZeroscorer（见 scorers/deterministic.py），套件自身不得重复声明，否则会被拒绝。
• 沙箱评测不进 CI：.github/workflows/ci-ai.yml只运行较旧的ee/hogai/eval/cipytest 树（且需要evals-readylabel），本评测按需在本地或 Modal 上运行。

想了解 harness 内部运行细节，可阅读 eval_harness/README.md 与 harness/README.md。

2. 被测表面：revamped-py-notebooks旗标下的工具集

Notebook 评测的目标表面是 MCP 中的 notebook 工具集合。在revamped-py-notebooks功能旗标开启后，注册的是以下工具（hand-written 为手写工具，generated 为从 OpenAPI schema 脚手架生成）：

工具的定义与描述可以在 products/notebooks/mcp/tools.yaml 中直接查看——例如notebooks-get被标记为feature_flag: revamped-py-notebooks，而notebooks-create采用feature_flag_behavior: disable且superseded_by: notebooks-create-markdown，说明新旧两套工具是互斥关系。

旗标关闭时，注册的是旧版工具集（notebooks-create、notebooks-retrieve、notebooks-partial-update），而所有 markdown 工具直接消失。两套工具集互斥这一点，直接影响下文 harness 的改造方式。

3. 已验证的环境阻塞点：让评测跑通的关键改造

规划文档列出了让 Notebook 评测真正可运行的五个阻塞点及其解决方案，其中大部分已经在 harness 中落地：

a. Markdown 工具通过旗标覆写到达评测 MCP server。工具过滤（tool filtering）以revamped-py-notebooks门控整个 markdown 工具集（测试见 services/mcp/tests/unit/tool-filtering.test.ts），而评测 MCP server 在FEATURE_FLAG_OVERRIDES中设置该旗标。实测代码位于 harness/services.py，其覆写字典为{"revamped-py-notebooks": True, ...}。副作用是：它同时把notebooks-create/notebooks-retrieve从评测工具列表中移除，因此若想评测旧版 notebook 工具，需要另一种杠杆（见第 9 节「开放决策」）。

b. Django 侧的门控已经满足。harness/lifecycle.py 会 patchposthoganalytics.feature_enabled使其在整个运行期间返回True，因此受旗标门控的 SQLV2 端点可以正常应答。

c. 两条 cell 运行通道，目前仅 docker 可用。

• 纯 HogQL 运行走直连通道（direct lane）：enqueue_direct_run（位于 backend/presentation/views/notebook.py）挂载在异步查询管理器上。harness 以TEST=1运行，此时 Celery 是 eager 模式，查询内联执行，不涉及沙箱。
• Python 与 DuckDB 运行调用start_sql_v2_run_workflow，需要 notebook 的 Temporal 工作流已注册、且存在 kernel 沙箱。harness 现在两者都做到了（详见 eval_harness/README.md#notebook-kernel-sandboxes）；在这项改造之前，运行会一直停留在running状态直到轮询窗口过期。
• kernel 通道仅 docker：notebook kernel 直接从SANDBOX_PROVIDER读取后端，而 modal provider 将其设为MODAL_EVALS，这不是KernelRuntime.Backend的合法值。因此python/duckdb 用例必须用--provider docker运行；纯 SQL 用例两种 provider 均可。

d. Scope 没有问题。沙箱上下文默认为"full"MCP scopes（见 custom_prompt_internals.py），其中已包含notebook:write。

e. 终态评分可行，但必须异步。Braintrust 基类的_run_eval_async会在事件循环上直接调用_run_eval_sync，因此任何在 scorer 里做同步 ORM 操作的行为都会触发 Django 的异步安全守卫。读取数据库的 scorer 应继承AsyncOnlyScorerMixin, Scorer（见 scorers/contract.py），并把数据库工作放进asyncio.to_thread。仓库中已有先例：DuplicateUniqueFlagKey（位于 products/posthog_ai/evals/experiments/scorers.py）。前提是 seeder 必须返回team_id，否则终态评分无从谈起。

4. 用例选型：用 MCP 分析数据锚定「会回归的行为」

用例选择的原则是：从工具实际行为出发，而非追求覆盖面上的面面俱到。规划文档建议在选型前先用 MCP 分析工具查看 notebook 工具的真实使用数据（query-mcp-tool-stats与query-mcp-tool-failures，或 MCP analytics UI）。规划撰写时的观测结果很有参考价值：

• notebook-edit在所有编辑工具中错误率最高，且多数失败是晦涩的internal错误——遥测中抛出的Error的表现形态，通常意味着old_markdown未找到或不唯一。这是最高价值的目标，也是唯一具有真实失败签名可复现的用例。
• notebooks-add-cell使用量尚小，评测在这里是「在大规模使用前锁定行为」，而非救火。
• 旧版notebooks-partial-update主要失败在 HTTP 409 版本冲突。

值得长期坚持的选型原则：

• 每个可合理回归的行为一个用例，而非每个工具一个用例。
• 优先选择「错误答案易检测、且在生产中代价高昂」的用例：例如覆盖（clobber）文档、丢失 cell 结果、重建已存在的 insight。
• 至少包含一个「正确行为是不调用任何工具」的用例，以及一个「工具拒绝首次尝试、Agent 必须恢复」的用例——这两类能捕捉纯成功用例漏掉的 prompt 回归。

已落地的 Suite 0：eval_notebook_cells（通道检查）

规划文档中标记为「已发布」的套件，实际实现见 products/notebooks/evals/eval_notebook_cells.py。它包含三个用例：

• python_cell_arithmetic：最便宜的 kernel 通道冒烟测试（无查询、无 dataframe、无 cell 间依赖）。若它通过而其他用例失败，说明沙箱没问题、是 Agent 的分析坏了。
• sql_cell_report：证明直连通道——要求创建名为 "Signup momentum" 的 notebook、用 SQL cell 返回最近 8 周signed_up事件的周计数，并加一段 markdown 摘要。expected中的cell_runs_completed.node_types为["hogql"]。
• python_cell_from_dataframe：端到端证明 kernel 通道——先加 SQL cell 取周计数，再加 Python cell 读取该 cell 的 dataframe 计算周环比变化。node_types为["hogql", "python"]，两条通道都覆盖。

值得注意的评分设计：CellRunsCompleted评的是NotebookNodeRun行而非对话记录，因为「已派发的运行」和「已完成的运行」在日志里看起来几乎一样——工具调用返回的要么是status: running，要么是已完成。只有 run 行才是 notebook 真正渲染内容的诚实来源。完整 scorer 实现见 products/notebooks/evals/scorers.py。

提案套件 A：eval_notebook_authoring（从分析请求创建）

提案套件 B：eval_notebook_editing（修改既有 notebook 且不破坏它）

八个 sandboxed 用例是合理的第一批规模：每个用例都是一次完整的 Agent 运行，成本线性增长，20 个用例的套件会变得难以迭代。

5. 数据生成：synthesizer 与 seeder 的分工

Hedgebox 提供事件、insights、dashboards 和 flags，但不提供 notebooks。因此编辑类和定向类用例需要 seeder 来预置数据。

规划文档建议沿用data_warehouse的 synthesizer/seeder 分工，仓库当前目录products/notebooks/evals/已按此结构落地：

products/notebooks/evals/ __init__.py constants.py # 共享字面量：标题、锚点、node id、dataframe 名 synthesizer.py # 纯确定性 markdown 文档构建器 seeders.py # 把数据安装进每个用例的团队（ORM）[已发布] scorers.py # 轨迹 + 终态 + 裁判评分器 [已发布] eval_notebook_cells.py # 两条运行通道 [已发布] eval_notebook_authoring.py eval_notebook_editing.py

• synthesizer.py：纯 Python、不依赖 Django、确定性。把 markdown 文档构建为 frozen dataclass（section 锚点、固定nodeId的 cell 标签、dataframe 名，以及用例必须找到的预置「needle」）。单元测试应放在products/notebooks/backend/test/，绝不放进evals/树内。以其中的build_churn_needle为例：默认种植 6 个账户（count=6），oldest_active_day=120、newest_active_day=70、session_stride_days=4——即账户在 120 天前注册、持续活跃到 70 天前、此后完全沉默，形成教科书式的流失形状。所有标识符（distinct_id、account_key、email、name）都携带CHURN_TOKEN = "hollowbrook"标记。
• seeders.py：接收CustomPromptSandboxContext，在用例自己的团队里创建Notebook行（内容等价于buildMarkdownNotebookContent(markdown)），对 staleness 用例还会创建NotebookNodeRun行，让notebooks-get报出真实的运行状态。
• constants.py：被 prompt、expected载荷和 scorer 共享的所有字面量（标题、锚点字符串、node ID、dataframe 名）集中存放，这是防止 prompt 与 scorer 漂移的关键机制。

Seeder 契约中容易踩坑的细节（务必遵守）：

• 同步函数：def seed_x(context) -> dict[str, Any]。harness 通过asyncio.to_thread调用它（见 base.py），永远不要把它写成 async。
• 没有每用例参数：用例特有的状态意味着要写专用的 seeder 函数，而不是给共享 seeder 加开关。
• 返回 scorer 需要的一切：包括team_id和 notebookshort_id；编辑类用例还要返回markdown_before，供 scorer 做 diff。
• seeder 抛异常 = 基础设施错误：该用例会被排除在平均值之外，破损的 seeder 永远不会被误读为 Agent 回归。

对 authoring 套件而言，seeder 是可选的：Hedgebox 已经自带了embed_saved_insight需要的 "Weekly signups" insight。但一个只返回{"team_id": ...}的最小 seeder 仍然值得写——它能解锁终态评分（seeders.py 中的seed_case_team正是如此）。

6. 三层评分栈：轨迹 → 终态 → 裁判

评分采用三层结构，确定性层作为主干，仅在问题真正属于定性判断时才动用 LLM 裁判。

第一层：工具轨迹（来自 Agent 日志）

确定性Scorer子类读取LogParser.cached(output["raw_log"], ...)（解析器见 log_parser.py）。优先复用通用评分器：RequiredToolCall、NoToolCall、LastToolCallNot、CalledTargetTool（来自 cli_mcp/scorers.py 等通用集）。notebook 特有新增：

• UsedMarkdownNotebookFlow—— 通过notebooks-create-markdown创建，而非手拼文档。
• CellsTitled—— 每个成功的 sql/pythonadd-cell都携带非空title（工具描述强制要求，PR #75471 正是因 Agent 跳过它而存在）。
• ReusedSavedInsight—— 使用带预置 short_id 的saved_insightcell，且没有重复相同查询的 SQL cell。
• RanCellsInDependencyOrder—— 对更新链，每次上游重跑都先于其依赖者的重跑。
• RecoveredFromToolRejection—— 先尝试被拒绝的形态、随后正确调用成功；是对RecoveredToCorrectTool的泛化。

第二层：终态（来自数据库）—— 本仓库的新增层

这一层才能真正捕获生产故障，也是本仓库评测体系的新增部分。异步 scorer（AsyncOnlyScorerMixin, Scorer+asyncio.to_thread）使用seed["team_id"]和seed["notebook_short_id"]从 Postgres 读回 notebook：

• NotebookIsMarkdown—— content 仍是单个ph-markdown-notebook节点，没有被覆盖成旧版富文本。
• PreservedUnrelatedContent——seed["markdown_before"]中除编辑目标外的每个锚点仍然存在，每个既有 cell 标签仍携带其nodeId、runId、resultprops。这是覆盖故障的直接反制。
• CellRunSucceeded—— 新增 cell 的NotebookNodeRun行处于DONE且 envelope 非空。用于捕获「写了一个看起来对、实际报错的 cell」。

system.notebooks也通过 HogQL 暴露markdown列，但 scorer 直接读 ORM 更简单，还能省去一次查询往返。

第三层：LLM 裁判（质量层）

JudgedScorer子类（基类见 scorers/judged.py）只需实现_prepare：

• NotebookAnswersQuestion—— 给定最终 markdown，notebook 是否真正回答了 prompt：正确的指标、正确的时间窗口、有图表、有可快速浏览的 prose。
• CellTitlesAreDescriptive—— 标题说明 cell 展示的内容，而不是「这是 SQL」。

裁判从同一次数据库读取中拿到最终 markdown，因此天然是异步的。仓库中已落地的定性裁判NotebookApproachQuality（同文件 scorers.py）展示了完整形态：从工具调用记录中读取 Agent 撰写的 cells（而非数据库），用NOTEBOOK_APPROACH_PROMPT+NOTEBOOK_APPROACH_RUBRIC六档量表（perfect → useless）让裁判按预期 approach 打分。

评分纪律

• score=None表示「此检查不适用于此用例」，会从聚合中剔除；0.0表示 Agent 做错了，且同样覆盖「裁判损坏」与「输入缺失」这类不能无声消失的路径。
• 只统计成功的工具调用（is_error=False）——Agent 被允许尝试并失败。
• 每个 scorer 只实现一个分支：_run_eval_sync与_run_eval_async二选一，绝不双实现。
• expected载荷按 scorer 名称键控，这样一份 scorer 列表就能覆盖整个套件。

7. 目录布局与套件骨架

评测树内不允许出现conftest.py或pytest导入；synthesizer 的单元测试放在products/notebooks/backend/test/。这一约定与 pytest 默认只收集test_*.py的规则天然契合——eval_*.py不会被误收集。

套件骨架（取自规划文档，与实际实现一致）：

from products.posthog_ai.eval_harness.base import SandboxedPublicEval from products.posthog_ai.eval_harness.config import SandboxedEvalCase from products.posthog_ai.eval_harness.harness.context import EvalContext async def eval_notebook_editing(ctx: EvalContext) -> None: await SandboxedPublicEval( experiment_name="sandboxed-notebooks-editing-cli", cases=[...], scorers=[...], ctx=ctx, )

默认使用SandboxedPublicEval（除非某个 prompt 或 seed 不应离开本机）；public 形态会获得 Braintrust URL 和跨运行历史。SandboxedPublicEval/SandboxedPrivateEval的实现是SandboxedEval的两个偏函数（见 base.py），前者is_public=True, no_send_logs=False，会同时向 Braintrust 与 PostHog 上报；后者反之，只写本地日志。保留-cli后缀，让命名与其余 MCP 套件对齐。

8. 上线顺序与运行命令

规划文档给出了明确的推进次序（前两步已完成落地）：

1. 在评测 MCP server 中启用revamped-py-notebooks，注册 notebook Temporal 工作流，回收 kernel 沙箱。已完成，eval_notebook_cells就是证明这条链路通畅的用例。
2. 添加eval_notebook_authoring——先用轨迹评分器覆盖判别性用例（复用 saved insight、从 component+HogQL 拒绝中恢复）。
3. 添加文档 seeder 与PreservedUnrelatedContent，然后是eval_notebook_editing。
4. 裁判最后加——它们是最嘈杂的一层，也最容易过拟合。
5. 稳定后用--trials 3运行，观察方差后再把任何分数当作基线。

常用命令（需在 flox shell 中运行）：

hogli evals --list | grep notebooks # 确认发现，import 检查模块 hogli evals eval_notebook_cells --eval python_cell_from_dataframe --provider docker hogli evals notebooks --provider docker # 整个域；docker 是因为 kernel 通道

更完整的 harness 参数可从 eval_harness/README.md 查阅，常用的包括：--eval <substr>（只跑名称含子串的用例）、--provider {docker,modal}（默认 docker）、--max-sandboxes N（并发沙箱上限，docker 默认 4）、--trials N（每用例跑 N 次）、--fail-under <fraction>（均值低于阈值则非零退出）等。

运行结束后的排查要点：读取最后一行打印的 transcript 路径，然后查看 experiment agent-log 目录下的每用例<case>.jsonl与<case>.summary.txt——光看分数无法告诉你用例为什么失败，原始 Agent 日志才是最快的定位途径。

9. 开放决策与已知边界

• Kernel 通道的 modal 支持：目前仅 docker，这使 python cell 用例并发被限制在四个沙箱左右。要解除限制，需要让 notebook kernel 认识MODAL_EVALS为 modal 后端——这是为评测而改生产代码，只有当 python 套件规模超出 docker 承载能力时才值得。
• 旧版 notebook 工具：启用旗标会隐藏它们，因此任何针对notebooks-create/notebooks-partial-update（409 冲突路径有真实错误量）的评测，需要「每套件」的旗标杠杆，而不是进程级环境变量。
• 裁判模型成本：裁判按「每个用例 × 每个 scorer」计费。八个用例配两个裁判没问题，十个裁判就太多了。

附：从规划到已落地的代码对照

规划文档写作时标注为「已发布」（shipped）的部分，在仓库中均可找到实现：

• 套件入口：products/notebooks/evals/eval_notebook_cells.py（三条用例，experiment_name="sandboxed-notebook-cells-cli"）；另一已落地的开放分析套件 products/notebooks/evals/eval_notebook_analysis.py 用seed_churn_signal预置流失账户群，并用ChurnCohortSurfaced按「笔记本 prose 中点名了预置账户的占比」打分。
• 评分器：products/notebooks/evals/scorers.py（NotebookCreated、CellRunsCompleted、ChurnCohortSurfaced、NotebookApproachQuality）。
• Seeder：products/notebooks/evals/seeders.py（seed_case_team、seed_churn_signal，含 ClickHouse 事件种植与 persons 数据库镜像）。
• 合成器：products/notebooks/evals/synthesizer.py（确定性 churn needle 构建）。
• 工具定义：products/notebooks/mcp/tools.yaml（markdown 工具集与旧工具集的旗标互斥关系）。
• 评测基建：harness 的 MCP 服务装配与 kernel 沙箱支持见 eval_harness/harness/services.py 与 eval_harness/harness/kernel_sandboxes.py。

这套评测体系的最终目的，是用可复现、可并发、可跨运行对比的方式，把「Agent 会不会用 notebook 工具、用得对不对、结果是否真的落到了数据库」变成一组可以被长期盯防的分数——在生产功能上线之前，就把回归挡在门外。

【免费下载链接】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