用途
埋点规格（Instrumentation Spec）用于定义要追踪哪些分析事件、何时触发它们，以及应包含哪些属性。它充当产品与工程之间的契约，确保数据采集一致，从而支持准确度量。一份良好的埋点规格可以避免“因为当初没有追踪，所以现在无法回答这个问题”的困境。
何时使用
- 在工程实现新功能之前
- 为实验定义分析需求时
- 审计现有追踪是否存在缺口或不一致时
- 引入新的分析工具时
- 上线前确保度量已就位时
何时不使用
- 你在定义构建在事件之上的仪表盘 -> 使用 measure-dashboard-requirements
- 你需要实验专属指标与变体，而非产品级追踪 -> 使用 measure-experiment-design
- 功能本身尚未定义（没有可埋点的流程） -> 先使用 deliver-prd
- 你在分析已经收集到的数据 -> 使用 measure-experiment-results 或 measure-survey-analysis
使用方式
被要求创建埋点规格时，按以下步骤执行：
-
定义分析目标：从你需要回答的问题开始。你要度量什么？这些数据将支撑哪些决策？这可防止过度埋点，同时确保不遗漏重要内容。
-
确定要追踪的事件：列出每个应被追踪的用户动作或系统事件。遵循一致的命名约定（通常是 snake_case 的 noun_verb 或 verb_noun）。每个事件应代表一个明确且有意义的动作。
-
指定事件触发条件：针对每个事件，精确描述其触发时机。要精确：“当用户点击提交按钮时”与“当表单成功提交时”是不同的，它们代表不同的事件、不同的含义。
-
定义事件属性：列出附加到每个事件的属性。包括属性名、数据类型、描述和示例值。属性提供上下文，使事件更有用。
-
记录用户属性：确定为所有事件关联的持久用户级属性（例如订阅层级、账号创建日期）。这些属性支持在分析中进行分群。
-
处理 PII 与隐私：标记任何包含个人身份信息（PII）的属性。记录 PII 应如何处理——哈希、加密或排除。
当捕获任何模型输入、输出、检索上下文或工具调用时，应扩展本节以覆盖 trace。触发点是“捕获”，而非“创作”：无论敏感文本是用户输入的、从租户文档中检索的、携带在系统提示中的、传入或返回自工具的、从上传文件或批处理作业中读取的，还是由模型自身生成的，该节都适用。一个没有直接用户输入的功能，仍可能把客户的合同文本写入 trace 存储。
trace 不是事件：事件携带你事先选定的属性，而 trace 携带自由文本，可能包含任何内容，包括属性 schema 未能预见的数据。需要决定并记录：
- 捕获的数据类别。请具体命名（用户文本、检索文档、系统提示、工具参数与结果、文件内容、模型输出）。“trace”本身不是答案。
- 在两个边界上最小化。trace 离开进程前丢弃或脱敏了什么，以及在存储前又丢弃了什么。仅在存储层运行的脱敏器已经将原始文本发送到了网络链路上。
- 访问。谁能读取 trace，以及读取是否被记录。trace 存储通常是功能所处理的最敏感数据中治理最薄弱的副本。
- 保留与删除。保留多久、由什么删除它们，以及删除请求如何触达已被复制进评估集的 trace。
- 同意与退出。数据主体是否同意，以及当他们拒绝时功能如何处理。
- 采样。捕获比例是多少，以及该样本如何选取。均匀采样不是发现罕见故障的合适工具；如果 trace 的存在是为了诊断不良输出，则应对被标记的案例进行过采样，并明确说明。
- 创建测试清单：定义 QA 应如何验证追踪被正确实现。包括验证事件在正确时间以正确属性触发的步骤。
输出格式
使用 references/TEMPLATE.md 中的模板来组织输出。完整规格应填写模板的每个部分：Overview；Event Inventory；User Properties；PII & Privacy Considerations；Implementation Notes；以及 Testing Checklist。
质量清单
在最终确定前，请验证：
- 事件名称遵循一致的命名约定
- 每个事件都有清晰、无歧义的触发条件
- 属性包含数据类型和示例值
- PII 已被识别且处理方式已记录
- 事件与你需要回答的分析问题相对应
- 测试清单支持 QA 验证
- 如果捕获了任何模型输入、输出、检索上下文或工具调用：数据类别已命名，出口与存储两个边界上的最小化均已决定，访问与读取日志、保留与删除、同意以及采样均已决定，而非推迟
示例
完整示例见 references/EXAMPLE.md。