需要人工审核 LLM 轨迹并收集结构化反馈时…

当你需要为 LLM 轨迹构建标注工具、审核轨迹或收集人工标签时，用 HTML 页面加载数据源并逐条展示、标注、保存。

适用场景

解决思路

1. 构建一个 HTML 页面，从数据源（JSON/CSV 文件）加载轨迹，一次显示一条轨迹，提供 Pass/Fail 按钮、自由文本备注字段以及 Next/Previous 导航，并将标签保存到本地文件（CSV/SQLite/JSON）。
2. 以该领域最易读的形式格式化所有数据：邮件应看起来像邮件，代码应有语法高亮，Markdown 应被渲染，表格应呈现为表格，JSON 应美化打印并可折叠。
3. 折叠重复元素：如果每条轨迹共享相同的 system prompt，将其放入 `<details>` 折叠开关中。
4. 提取并突出关键元数据：如果轨迹中包含属性名、客户端类型或 session ID 等埋藏信息，将其提取出来并以标题或徽章形式显著展示。
5. 按角色或状态进行颜色编码：使用左边框颜色区分 user 消息、assistant 消息、tool calls 和 system prompts，便于一眼识别。
6. 在视觉上分组相关元素：tool calls 及其响应应通过缩进、共享边框等方式在视觉上关联。
7. 折叠对判断无帮助的内容：冗长的 tool response JSON、中间推理步骤和调试上下文放入折叠开关后面。
8. 突出最重要的内容：让审核者主要判断的内容在视觉上占主导地位；加粗关键实体（价格、日期、名称）；使用字号和间距创建层次。
9. 展示完整轨迹：包含所有中间步骤（tool calls、检索到的上下文、推理），而不仅是最终输出；默认折叠但保持可访问。
10. 净化渲染内容：在渲染前从 LLM 输出中剥离原始 HTML；如果渲染的 Markdown 中的图片可能作为追踪像素，则禁用图片。
11. 在轨迹级别进行标注：审核者判断整条轨迹，而非单个 span。
12. 以二元 Pass/Fail 按钮作为主要操作。
13. 提供自由文本备注字段，供审核者描述出错（或正确）之处。
14. 提供 Defer 按钮用于不确定的情况。
15. 每次操作后自动保存。
16. 在通过错误分析建立失败类别之后，再添加预定义的失败模式标签（可点击复选框、下拉菜单或选择列表），让审核者除写备注外还能从已知类别中选择；但不要在初始构建时就添加这些。
17. 提供 Next/Previous 按钮和键盘方向键。
18. 显示轨迹计数器，展示位置和进度（如 "12 of 87 remaining"）。
19. 支持按 ID 跳转到特定轨迹。
20. 显示已标注与未标注轨迹的计数。
21. 实现键盘快捷键：方向键 = 导航轨迹；1 = Pass；2 = Fail；D = Defer；U = 撤销上一步操作；Cmd+S = 保存；Cmd+Enter = 保存并下一条。
22. 让应用能够接受来自任意来源（JSON/CSV 文件）的轨迹；将采样逻辑保持在应用之外，放在单独脚本中；从随机采样开始。
23. 提供参考面板：可切换的面板，在轨迹旁边显示 ground truth、预期答案或评分标准定义。
24. 提供过滤功能：按与产品相关的元数据维度（渠道、用户类型、流水线版本）过滤轨迹。
25. 提供聚类功能：按元数据或语义相似度对轨迹分组；展示每个聚类的代表性轨迹并支持下钻。
26. 遵循设计检查清单：每条轨迹使用相同的布局、控件和术语；Pass 和 Fail 按钮在视觉上明显区分（颜色、大小）；所有主要操作都有键盘快捷键；即使部分内容折叠，完整轨迹仍可访问；标签自动持久化，无需显式保存；默认在轨迹级别而非 span 级别标注；所有数据以其原生格式渲染（Markdown 渲染为 HTML、代码带高亮、JSON 美化打印、表格渲染为 HTML 表格、URL 渲染为可点击链接）。
27. 构建界面后，使用 Playwright 进行验证。
28. 进行视觉审查：加载代表性轨迹数据后对界面截图，审查每张截图的布局与间距（视觉层次是否清晰、能否立即看到重点）、可读性（所有数据是否以原生格式渲染、是否有原始 JSON 块、未渲染的 Markdown 或未样式化内容）、美观度（界面是否专业整洁、领域专家是否愿意使用）、响应式（布局在不同窗口尺寸下是否保持）。
29. 编写 Playwright 脚本执行完整标注工作流的功能测试：1. 加载应用并验证轨迹已显示；2. 对一条轨迹点击 Pass，验证标签已保存；3. 对一条轨迹点击 Fail，添加备注，验证两者均已保存；4. 点击 Defer，验证已记录；5. 使用按钮和键盘快捷键前后导航；6. 验证轨迹计数器正确更新；7. 通过重新加载页面并检查标签是否持久化来验证自动保存；8. 展开折叠部分（system prompts、tool calls）并验证内容可访问；9. 测试所有键盘快捷键是否触发正确操作。

适用边界 · 注意事项

• 尚未通过错误分析建立失败类别时，不要添加预定义的失败模式标签。
• 不要将采样逻辑放入应用内，应保持在单独脚本中。
• 不要默认进行 span 级别标注，应以轨迹级别标注为默认。