PostHog 公共仓库评测用例数据编写规范：从属性清单出发，杜绝真实对话泄露-平芜编程栈

PostHog 公共仓库评测用例数据编写规范：从属性清单出发，杜绝真实对话泄露

【免费下载链接】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 仓库中 ee/hogai/eval/CLAUDE.md 为核心，系统讲解 AI 评测（evals）中"自带内联数据（inline case data）"的编写纪律。适用场景是 Max AI 助手等支持类功能评测：当用例数据由人手编写并提交进公共开源仓库时，如何在保证用例真实感的前提下，彻底避免真实对话、凭据与用户信息进入公开可见的代码。读完你将掌握一套可落地的属性清单写作流程、脱敏边界与出处自查方法，并了解仓库中对应的评测执行与源码佐证。

两种评测用例数据：种子项目 vs 内联数据

PostHog 的 AI 评测用例数据来源有两种，它们对"是否允许携带真实信息"有截然不同的处理方式：

种子项目（seeded Hedgebox）数据：绝大多数 CI 评测运行在预先造好的 Hedgebox 演示项目上，对应demo_org_team_userfixture（见 ci/conftest.py）。这类数据本身是合成数据（synthetic），天然不涉及真实用户隐私。
内联数据（inline case data）：部分评测不依赖团队数据，而是把对话记录直接传给EvalCase(input=...)。典型例子是 ci/eval_ticket_summary.py，它评测的是"提示词（prompt）"而非"对某个团队的查询"，因此直接把整段客服对话塞进用例里。

本指南讨论的正是第二种。正如 ee/hogai/eval/CLAUDE.md 开篇所警告的：

"When you write case data by hand, you are the only thing standing between a real conversation and a public repository."

即：当手工编写用例数据时，你就是真实对话与公共仓库之间唯一的防线。这份文档的整篇纪律，都是围绕这一句话展开的。

核心方法论：从属性清单写作，而不是从源材料改写

为什么不能"照着真实对话改一改"

对于客服类功能的评测，最理想的情况是手头恰好有一段真实对话。但文档明确禁止"把它编辑成形"（Do not edit it into shape），理由是：

"Adapting real material and writing a fresh case are indistinguishable once you are partway through, and the result reads as synthetic while carrying somebody's actual words."

改写一旦开始，就很难停在"只是借用灵感"的边界上；成品看起来是合成的，但里面却混着某个真实用户的原话。因此，正确顺序不是"改写"，而是下面这条三步流程：

三步流程

读真实材料，只提炼"属性"（properties）：只记录用例必须覆盖的特性点，例如：
- 某个可引用片段内的拼写错误（misspelling）；
- 同一个词出现两种拼写，从而可以检验"拼接引用"是否被抓出；
- 对话中途话题切换（mid-conversation topic change）；
- 对话记录里残留的早期总结（earlier summary sitting in the transcript）；
- 非英文文本；
- 只有一条裸命令、没有任何可总结内容的对话。
关掉真实材料（Close the real material）。
依据属性清单编写用例。

文档强调：属性清单本身就是第一步的交付物。如果跳过"写下来"这一步，最终结果就会变成 paraphrase（转述），而不是真正新鲜的用例。

一切可识别信息都必须虚构

硬性规则

用例中的主机名、邮箱、人名、公司名、ID、Cookie 和 Token，必须全部是编造的，而不是真实信息的"匿名化版本"（anonymized versions）。具体要求：

使用保留域名：example.com、example.org（见 RFC 2606）；
使用明显是假的 Token 值。

为什么匿名化不够

因为客户会把凭据粘贴进支持聊天里。一段真实的 Cookie、或真实认证 Token 的碎片，哪怕已过期、已截断、单独无法使用，也不应该出现在公共仓库里。

这一点可以直接在仓库源码中得到印证：在 ci/eval_ticket_summary.py 的最后一个用例里，虚构的 curl 请求携带了_ga=GA1.1.0000000000.0000000000与app-auth-token=base64-ZmFrZS1ldmFsLXRva2VuLXZhbHVlLWRvLW5vdC11c2U——注意这个 base64 串解出来正是 "fake-eval-token-value-do-not-use"，一个刻意到一眼可辨的假 Token。这正是文档规则在真实用例中的落地：不仅要用假值，还要假得让人无法误用。

出处声明：没有做过属性清单流程，就不要写 "Written fresh"

提交信息中的出处声明是一项事实主张

在 commit message 中写 "Written fresh"（全新编写）是一项事实主张（factual claim），评审者会依赖它。只有在确实执行了上面的属性清单流程之后，才允许这样写。

40 字符自查阈值

如果不确定某个用例是否已经滑向源材料，应当主动核查而不是直接断言：

"any shared run of roughly 40 characters or more means derived, not fresh."

即：用例与真实材料之间只要存在约 40 个字符或更长的连续公共片段，就应当认定为"派生（derived）"而非"全新（fresh）"。

lint-staged 的机械提醒机制

仓库提供了一个自动化提醒：.github/scripts/check-fixture-provenance.sh（实际存在于仓库 .github/scripts/check-fixture-provenance.sh）。当一次提交新增一批"对话形态"的用例数据时，lint-staged 会触发一个警告。该脚本有两个关键设计：

只警告、永不阻断（warning only, never blocks）：脚本注释明确说明，"这段文本是否源自真实对话"无法机械判定，它的职责只是让评审者去看 diff；
按文件计数、阈值为 2：脚本对每个文件单独统计命中数，命中content|message|body|text|prompt等承载散文内容的关键字且字符串长度 ≥ 25 字符才计一次，达到 2 次才告警。其校准数据表明：对最近 60 个涉及 eval/fixture 路径的提交、共 265 个匹配文件中，只有 3 个有命中，而触发该脚本构建的那次事件单文件得分 34——这说明阈值设置得足够保守，正常小改动不会误报。

仓库源码佐证：内联用例在评测中如何被消费

EvalCase 与评测执行底座

内联用例通过 base.py 中的BaseMaxEval执行。该实现有几个与本文主题直接相关的点：

MaxPublicEval（公开评测）与MaxPrivateEval（私有评测）是BaseMaxEval的两个偏函数变体；
公开评测会以max-ai-{experiment_name}为项目名向 Braintrust 上报（init_logger），并关闭no_send_logs，以便结果与基线对比；
_filter_data支持--eval <子串>的 pytest 参数按用例名过滤；
超时设置：普通模式 8 分钟，EVAL_MODE=offline时放宽到 1 小时。

ticket_summary 评测如何体现文档纪律

ci/eval_ticket_summary.py 是文档点名的内联用例范例。它由三部分构成，恰好覆盖了文档强调的三种能力：

评测目标函数call_summarizer：用MaxChatAnthropic调用claude-sonnet-5，把SUPPORT_SUMMARIZER_SYSTEM_PROMPT与渲染后的 transcript 喂给模型，让模型产出一份客服工单摘要；
两个打分器：
- TicketSummaryQuality（LLM 评判）：检查摘要是否只使用规定的小节标签（**Reported issue:**、**Details provided:**、**Checked by the customer:**）、是否以客户原话开头、是否只记录客户所述而非 PostHog AI 的行为、是否第三人称、是否逐行列出等；
- QuoteFidelity（算法评分，ScorerWithPartial）：计算"单个客户消息中被摘要逐字引用的引用片段占比"。它直接复用 transcript.py 的customer_turns、quoted_spans、unverifiable_quotes，从而能机械地验证：摘要中的每一处引号内容，是否都能在同一条客户消息中找到完整出处——这正是文档中"一个词两种拼写以便抓出拼接引用"属性的自动化实现。
11 个内联 EvalCase：每条expected都是对"该测什么属性"的精确描述。

从用例反推文档属性清单的落地形态

逐条对照 ci/eval_ticket_summary.py 的用例与 ee/hogai/eval/CLAUDE.md 的属性清单，可以看到每条纪律都有对应用例：

拼写错误必须原样保留：第二个用例的mistakenly, mistakinly and allready，第九个用例要求occured不得被"纠正"成occurred；
同词两种拼写以抓拼接引用：第二个用例明确要求mistakinly与allready"must survive exactly wherever quoted, and no quote may mix words from their two separate messages"；
对话中途话题切换：第四个用例要求"仅保留国旗错误这一话题"，开头的 Data management 提问"不是问题，不应出现"；
早期总结混在对话里：第七个用例的对话中间夹了一段PostHog AI Support Ticket Summary，expected 明确指出那是 PostHog AI 自己的输出，"不得当作客户所说"；
非英文文本：第九个用例整段为西班牙语支持对话；
裸命令：多个用例以孤零零的/ticket结束，测试摘要器是否不会为它虚构内容；
PostHog AI 的推测不得升格为事实：第六个用例的 expected 强调"不得断言这是 automations 的 bug，因为只有 PostHog AI 推测过"；
客户粘贴的凭据类内容用假值：最后一个用例使用example.com域名与上面分析过的假 Token。

这些用例文件位于公共仓库中、会被任何人阅读，因此它们本身就是"属性清单流程 + 全虚构标识 + 可机械校验"三原则最直接的示例。

结语：三条可立即执行的红线

写作顺序不可颠倒：先提炼属性清单，关掉源材料，再写用例；跳过清单就是转述。
识别信息全部虚构：域名用 RFC 2606 保留域名，Token/Cookie 用一眼可辨的假值，真实凭据的任何碎片都不允许进入公共仓库。
出处声明要诚实：没做属性清单流程就不写 "Written fresh"；出现约 40 字符连续公共片段即视为派生；提交大批对话形态用例时，留意 .github/scripts/check-fixture-provenance.sh 的 lint-staged 警告，并主动复核 diff。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考