error-discovery

错误发现技能

你正在进行一场交互式错误分析会话。用户有一个包含大模型输出或轨迹的数据集（JSONL、CSV、JSON 等），希望通过查看样本来发现失败模式。

此技能仅用于交互式会话。

此技能分为两部分：

• 本文件涵盖阶段 1 至 4。你将读取数据、设计界面、构建界面并选择样本。
• review-loop.md 涵盖阶段 5。你将运行交互式审查会话。

首先阅读本文件，完成所有准备工作。应用运行后，人类开始审查时，请遵循 review-loop.md。

进度更新

每个阶段都需要时间，尤其是构建界面时。请在每一步告知用户你正在做什么。开始一个阶段前，说明你接下来要做什么以及原因。步骤完成后，说明你做了什么以及接下来会做什么。例如：“正在阅读 10 条样本记录，以了解数据结构”“正在构建包含文章、地图和进度三个视图的 HTML 应用”“正在根据 5 个特征进行聚类，以选择多样化样本”。不要长时间不作回应。

阶段 1：了解领域和数据

在构建任何内容之前，先彻底研究数据集。

1a：读取并清点数据

加载文件。检查分布中的 5 到 10 条记录。对于每条记录，确定：

• 所有字段、字段类型及其含义
• 人类需要判断的主要内容字段
• 作为元数据的字段（有助于理解背景，但不是被判断的内容）
• 不同记录之间会变化的字段和保持不变的字段

1b：识别内容结构

数据可能有多种形式。判断适用以下哪种模式：

• 单个文本字段，例如文章、摘要、邮件、作文、翻译
• 输入／输出对，例如提示词 + 补全内容、问题 + 答案、指令 + 结果
• 多轮轨迹，例如包含不同角色消息的序列（system、human、assistant、工具调用、工具结果、思考／推理块）。这在 Agent 轨迹、聊天机器人日志和 Agent 工作流中很常见。
• 代码，例如源文件、补丁、差异内容，可包含或不包含周边上下文
• 结构化输出，例如 JSON、函数调用、提取的实体、分类结果
• 复合内容，例如任务描述 + Agent 轨迹 + 最终输出

对于多轮轨迹，尤其要确定：

• 存在哪些角色或作者（system、user、assistant、tool、thinking 等）
• 是否有工具调用／工具结果对
• 是否有思考／推理块
• 各轮的逻辑分组方式，例如一个“步骤” = 思考 + 工具调用 + 工具结果

1c：识别变化维度

考虑不同数据点之间以及单个数据点内部有哪些差异。你将使用这些维度来决定视觉设计。

数据点之间（记录间变化）：

• 元数据，例如主题、模型、难度、来源、标签、任务类型
• 结构特征，例如长度、轮数、工具调用次数
• 结果，例如成功／失败、分数

单个数据点内部（单条记录的各部分之间变化）：

• 每个片段的作者／角色（人类 vs Agent vs 系统 vs 工具）
• 每个片段的内容类型（自然语言 vs 代码 vs JSON vs 思考）
• 每个片段的重要性／相关性（模板化系统提示词 vs 实际回复）

1d：思考“糟糕”意味着什么

思考此领域中几种可能的失败类别。预计人类会在审查过程中发现其中大多数类别。

阶段 2：设计视觉编码

编写任何代码之前，先设计每个变化维度如何映射到视觉属性。运用格式塔原理和信息可视化基础原则。

适用的核心格式塔原则

• 相似性（颜色、形状）。观看者会将具有相同视觉属性的事物视为相关。将此用于类别维度。为不同的消息角色使用不同的颜色，并为不同的标签使用不同的徽章颜色。
• 接近性（间距）。观看者会将彼此靠近的事物视为一组。将此用于逻辑单元。将对话中同一步骤的轮次放得更近，并用更大的间距分隔不同步骤。
• 共同区域（容器、背景）。观看者会将处于同一边界内的事物视为一组。将此用于多部分内容，例如，让工具调用及其结果共用一个容器。
• 图形与背景（不透明度、对比度）。重要内容应具有高对比度（图形）。不那么重要的内容应退至背景。将此用于强调。以较低的不透明度显示模板化内容。

视觉编码规则

将每个变化维度映射到且仅映射到一个视觉通道。不同事物不要使用相同通道。

色相。将其用于区分最重要的类别维度。

• 对于多轮轨迹，使用颜色表示消息角色。每种角色（人类、助手、系统、工具、思考）都使用一种独特且饱和度充足的色相。选择 3 到 5 种易于区分的色相。
• 对于单条内容，使用颜色表示标签或来源类别。
• 不要使用色相表示定量数据。

不透明度／饱和度。用于表示人类是否需要仔细阅读此内容。

• 仅降低人类确实无需阅读的内容的不透明度，例如各条记录中完全相同的重复模板化内容、冗长的工具架构、自动生成的标头。请自问：“如果删掉这些内容，人类会遗漏什么吗？”
• 不要按角色淡化内容。系统消息、工具结果和思考区块都可能包含实际错误。无论内容由哪个角色生成，都只淡化冗余或机械性的特定内容。
• 常规内容保持完全不透明。

间距。用于表示层级结构。

• 逻辑组内的项目之间使用紧凑间距（4 至 8px），例如 Agent 轨迹中同一步骤内连续的消息。
• 逻辑组之间使用中等间距（16 至 24px），例如步骤之间。
• 主要章节之间使用较大间距（32 至 48px）。

字体排版。用于表示内容类型。

• 自然语言散文：比例字体，常规字号。
• 代码：等宽字体，字号略小。
• 元数据：小号、淡化、紧凑。
• 思考／推理：使用斜体或独特的字体样式，以标示“内部”内容。

边框／容器。用于归组相关部分。

• 将工具调用及其工具结果放在同一个带有浅色边框的容器中。
• 使用清晰的分隔线分隔输入／输出对，或将它们并排放置。

结构异常标记。仅显示在标头中，不要放在行内。

• 预先计算关键结构特征（长度、标题数、段落数等）在数据集层面的平均值。
• 对每条记录，标记明显偏离统计分布的维度（例如，位于前／后 10%）。
• 在标头中将其显示为小巧紧凑的徽章，例如“6 个标题（多于 89%）”或“比 95% 的内容短”。
• 保持简洁。大多数记录应没有标记，或只有一个标记。不要标注行内内容。

第 3 阶段：构建审阅界面

架构

• Python HTTP 服务器（标准库 http.server，无依赖项）：
  • GET / 提供 HTML 应用
  • GET /api/samples 返回当前样本集
  • POST /api/samples 允许 Agent 推送新样本
  • GET /api/annotations 返回当前批注
  • POST /api/annotations 允许应用在每次更改时保存批注
  • GET /api/graph 返回所有记录的 2D 投影，用于聚类地图
  • GET /api/patterns 返回 Agent 当前的故障模式分类体系
  • POST /api/patterns 允许 Agent 推送更新后的分类体系
  • GET /api/suggestions 返回 Agent 建议的批注
  • POST /api/suggestions 允许 Agent 推送建议
• 存储在磁盘 error_discovery_data/ 目录中的文件：
  • samples.json、annotations.json、graph.json、patterns.json、suggestions.json
• HTML 应用会在每次添加批注时自动保存到服务器。它会轮询新样本和建议。

HTML 应用结构

三个视图，可从顶部栏切换：

1. 文章／内容视图。主要审阅界面，供人工阅读和添加批注。
2. 地图视图。所有记录的 2D 散点图（PCA 或 UMAP 投影）。显示聚类、哪些项目在样本中，以及哪些项目已添加批注。审阅者可以点击样本节点，转到其内容视图。
3. 进度视图。包含两个部分：
   • 故障模式：以树图展示 Agent 迄今分类的模式。每个区块代表一种故障模式，大小按批注数量决定。每个区块内列出备注。审阅者可以点击备注，转到内容视图中的对应批注。
   • 待审阅的 Agent 建议：以列表形式展示待处理建议，并附复选框。每行显示故障模式、引文和来源记录。审阅者可以点击文本，跳转到文章中的对应位置。顶部提供“全选”复选框，以及“接受所选”和“忽略所选”按钮。审阅者可以全选，取消勾选少数不同意的建议，然后一键接受其余建议。

内容视图设计。应用第 2 阶段的视觉编码：

• 页眉：标题 + 标签 + 主题。保持简洁。仅当记录确实是离群项时，才添加结构性离群标记（来自第 2 阶段）。

• 正文：根据内容类型使用合适的呈现方式显示主要内容。

  对于多轮轨迹（Agent 日志、对话、聊天）：

  • 将每条消息／每一轮显示为一个区块。所有区块左对齐，但按角色使用不同颜色的左边框或背景色调。
  • 在每个区块顶部显示角色标签（字号较小、加粗），例如“系统”“用户”“助手”“工具调用”“工具结果”“思考”。
  • 为每个角色分配不同色相，并在所有记录中保持一致。默认情况下，所有角色均以完全不透明度显示。
  • 以明显不同的样式呈现思考／推理区块（例如，使用较浅的背景、斜体或略微缩进），以表明这是内部独白，同时确保内容清晰易读。
  • 突出显示工具调用的函数名称。将参数放入可折叠的格式化 JSON 中。
  • 如果工具结果较长，默认将其折叠，并显示一行摘要。
  • 仅对在多条记录中完全相同的内容降低不透明度，例如每条轨迹中逐字重复的相同系统提示词。如果系统消息有所不同，则保持完全可见。
  • 将相关轮次分组：将思考区块及其生成的工具调用和工具结果在视觉上归为一组，采用紧凑间距和共用容器。

  对于单段文本内容（文章、摘要等）：

  • 将 Markdown 渲染为格式化 HTML（使用 marked.js 或类似工具）。
  • 纯文本按段落分隔显示。

  对于代码／差异：

  • 使用语法高亮（通过 CDN 使用 highlight.js 或 Prism）。
  • 用绿色背景显示新增内容，用红色背景显示删除内容。
  • 显示行号。

  对于输入／输出对：

  • 将两者上下排列，并用清晰的分隔线区分；如果两者都较短，也可以并排放置。
  • 为每个部分添加标签。

• 行内批注：审阅者选中文本后，会出现一个带文本输入框的浮动弹窗；按 Enter 键即可保存，并高亮显示所选文本。弹窗出现且输入框获得焦点时，浏览器会清除原生文本选区。为避免这种情况，在输入框获得焦点之前，先将选中的范围包裹在临时高亮 span 中（例如，使用 class "pending-highlight" 和可见的背景色）。保存批注、取消操作或点击弹窗外部将其关闭时，移除临时高亮。这样，审阅者始终能看到正在批注的文本。

• 边栏批注：批注和建议必须显示在右侧边栏列中，并与对应的高亮文本垂直对齐。使用两列布局：左侧为文章正文（flex: 1，max-width ~720px），右侧为边栏批注列（width ~240px）。每条边栏批注都在边栏列内设置为 position: absolute，其 top 偏移量根据高亮元素相对于边栏容器的位置计算（对高亮元素和边栏容器都使用 getBoundingClientRect，然后计算两者的差值——不要加上 scrollTop，否则会重复计算滚动偏移量）。批注之间留出最小间距，避免重叠。加入悬停联动：悬停在边栏批注上时为其对应的高亮添加轮廓，悬停在高亮上时为其对应的边栏批注添加轮廓。每条边栏批注显示引用文本、审阅者的批注以及编辑/删除按钮（悬停时显示）。不要将悬停提示作为显示批注内容的主要方式——边栏批注取代悬停提示。

• Agent 建议：在行内高亮（虚线边框、柔和色调）和边栏批注（不同颜色的左边框、「Agent 建议」标签）上都要与人工批注明显区分。边栏批注显示接受/忽略按钮（始终可见，不受悬停控制）。审阅者可以接受建议（将其转为批注）或忽略建议。

• 不要添加质量标签、下拉菜单或结构化表单。只使用自由文本批注。

• 每次更改时自动保存到服务器。保留一份 localStorage 备份。

• 定期轮询新样本和建议。出现新内容时显示横幅或提示消息。

地图视图：

• 使用 PCA/UMAP 投影显示所有记录的二维散点图。
• 按聚类着色（与凸包颜色一致），不要按标签着色。
• 使用形状区分类别，例如用圆形表示 AI，用方形表示人工。
• 使用较大的节点显示样本项目，并添加深色边框。
• 使用独特颜色（例如橙色）显示已添加批注的项目。
• 使用不显眼的背景形状绘制聚类凸包或边界。
• 悬停时，显示包含标题、元数据和批注数的提示。
• 点击时（仅限样本节点），跳转到该项目的内容视图。

第 4 阶段：聚类并选择初始样本

1. 提取适合内容类型的特征（维度参见第 1c 阶段）。
2. 使用 KMeans 或类似方法，对归一化后的特征进行聚类。目标为 6 到 10 个聚类。
3. 构建初始样本（对于数据集超过 50 条的情况，选取 15 到 25 条）：
   • 聚类代表项（约 60% 到 70%）：选取最接近各质心的 1 到 2 条，并混合不同类别/标签。
   • 随机样本（约 30% 到 40%）：从整个数据集中随机选取，不受聚类限制。聚类可能无法捕捉到所有重要维度，因此随机抽样有助于覆盖遗漏的内容。
   • 移除重复项。
4. 优先考虑多样性。目标是发现失败模式，而非估算其常见程度。

第 5 阶段：运行交互式审阅循环

应用运行后，人工开始审阅时，请遵循 review-loop.md 中的说明开展持续的交互会话，包括如何监控新增批注。

如果会话在人工审阅开始前结束（例如运行 codex exec 或 claude -p 这样的非交互式任务），请构建并进行冒烟测试，然后停止服务器，并提供稍后启动服务器的命令；绝不要声称审阅循环已经运行，或声称仍有任何内容在运行。