mcpField
B
build-review-interface

build-review-interface

github.com/ai-evals-course测试与质量1.6k1.0k 次安装5 周前更新
代码仓库

关于 build-review-interface

用于构建自定义标注界面的技能，指导开发者制作逐条展示运行跟踪并收集 Pass/Fail、备注和延后标记的 HTML 页面。它还涵盖导航、自动保存、可读性呈现及 Playwright 测试。

主要功能

  1. 01从 JSON 或 CSV 加载跟踪
  2. 02逐条展示并收集 Pass/Fail 标记
  3. 03添加备注与延后标记
  4. 04键盘导航并显示标注进度
  5. 05自动保存标签
  6. 06使用 Playwright 验证界面

适用场景

  1. 01为模型运行跟踪搭建人工审核界面
  2. 02让评审者标注通过、失败及原因
  3. 03按元数据筛选或聚类跟踪
  4. 04检查标注流程和保存行为

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ai-evals-course/evals-skills --skill build-review-interface

安装后在 Claude Code 中输入/build-review-interface确认已加载。

附带文件agents/openai.yaml

详细介绍

构建自定义标注界面

概述

构建一个 HTML 页面，从数据源（JSON/CSV 文件）加载轨迹，一次显示一条轨迹，并提供通过/失败按钮、自由文本备注字段以及下一条/上一条导航。将标签保存到本地文件（CSV/SQLite/JSON）。然后根据以下指南针对具体领域进行定制。

数据展示

以最便于理解的形式呈现数据，使其符合具体领域的惯例。电子邮件应显示为电子邮件的样式。代码应进行语法高亮。Markdown 应渲染出来。表格应显示为表格。JSON 应进行美化排版并可折叠。

  • 折叠重复内容。 如果每条轨迹都包含相同的系统提示词，就将其放在 <details> 切换区域中。
  • 提取并突出显示关键元数据。 如果轨迹包含埋在数据中的属性名称、客户端类型或会话 ID，就将其提取出来，作为醒目的标题或徽标显示。
  • 按角色或状态着色。 使用左侧边框颜色区分用户消息、助手消息、工具调用和系统提示词，让人一眼就能辨认。
  • 以视觉方式组合相关元素。 工具调用及其响应应在视觉上关联起来（通过缩进或共用边框）。
  • 折叠无助于判断的内容。 冗长的工具响应 JSON、中间推理步骤和调试上下文应放在切换区域中。
  • 突出重要内容。 让评审者需要判断的主要内容在视觉上更醒目。将关键实体（价格、日期、名称）加粗。使用字号和间距建立层次。
  • 显示完整轨迹。 包含所有中间步骤（工具调用、检索到的上下文、推理），而不只是最终输出。默认折叠这些内容，但应确保可以访问。
  • 清理渲染内容。 渲染前移除大模型输出中的原始 HTML。如果渲染的 Markdown 中的图片可能是跟踪像素，则应禁用图片。

反馈收集

在轨迹级别进行标注。评审者判断的是整条轨迹，而不是单个片段。

  • 将二元通过/失败按钮设为主要操作。
  • 提供自由文本备注字段，供评审者描述出了什么问题（或做得好的地方）。
  • 为不确定的情况提供暂缓按钮。
  • 每次操作后自动保存。

通过错误分析确定失败类别后，可以稍后添加预定义的失败模式标签，并以可点击复选框、下拉菜单或选项列表的形式呈现，让评审者除了填写备注外，还可以从已知类别中选择。但初始构建时不要添加这些内容。

导航与状态

  • 提供下一条/上一条按钮和键盘方向键导航。
  • 显示轨迹计数器，显示当前位置和进度（“剩余 87 条中的第 12 条”）。
  • 可按 ID 跳转到指定轨迹。
  • 显示已标注与未标注轨迹的数量。

键盘快捷键

Arrow keys = Navigate traces
1 = Pass              2 = Fail
D = Defer             U = Undo last action
Cmd+S = Save          Cmd+Enter = Save and next

选择要加载的轨迹

构建应用，使其能够从任何来源加载轨迹（JSON/CSV 文件）。将抽样逻辑放在应用之外的独立脚本中。先从随机抽样开始。

其他功能

参考面板： 可切换的面板，用于在轨迹旁显示真实标签、预期答案或评分标准定义。

筛选： 按与产品相关的元数据维度筛选轨迹（渠道、用户类型、流水线版本）。

聚类： 按元数据或语义相似度对轨迹分组。显示每个集群的代表性轨迹，并支持深入查看。

设计检查清单

  • 每条轨迹都使用相同的布局、控件和术语
  • 通过和失败按钮在视觉上有所区分（颜色、大小）
  • 所有主要操作都支持键盘快捷键
  • 即使各部分已折叠，也能访问完整轨迹
  • 标签自动持久化，无需显式保存
  • 默认在轨迹级别进行标注（而非片段级别）
  • 所有数据都以其原生格式呈现（Markdown 渲染为 HTML，代码进行语法高亮，JSON 美化排版，表格渲染为 HTML 表格，URL 显示为可点击链接）

测试

构建界面后，使用 Playwright 对其进行验证。

视觉审查： 加载具有代表性的跟踪数据后，截取界面截图。检查每张截图，确认以下方面：

  • 布局和间距：视觉层次是否清晰？是否能立即看出重点？
  • 可读性：所有数据是否都以原生格式呈现？是否存在原始 JSON 块、未渲染的 Markdown 或未设置样式的内容？
  • 美观度：界面是否专业、简洁？领域专家会使用它吗？
  • 响应性：不同窗口尺寸下，布局是否都能正常显示？

功能测试： 编写一个 Playwright 脚本，完成完整的标注工作流：

  1. 加载应用并确认跟踪记录已显示
  2. 点击某条跟踪记录上的 Pass，确认标签已保存
  3. 点击某条跟踪记录上的 Fail，添加备注，并确认二者均已保存
  4. 点击 Defer，确认该操作已记录
  5. 使用按钮和键盘快捷键向前和向后导航
  6. 确认跟踪记录计数器更新正确
  7. 重新加载页面，检查标签是否保留，以确认自动保存生效
  8. 展开折叠的部分（系统提示词、工具调用），并确认其内容可访问
  9. 测试所有键盘快捷键是否都能触发正确操作

评论

支持 Markdown