编码智能体标注

标注编码智能体 trace，带 diff 渲染、终端输出和文件树导航。可从 Claude Code、Aider、SWE-Agent 等编码助手导入。

v2.4.0 新增

编码智能体——Claude Code、Aider、SWE-Agent、OpenHands 等——产生的 trace 和通用智能体的 trace 不一样。它们包含代码 diff、终端输出、文件读取、目录遍历和测试结果。评审这类 trace 需要专门的渲染方式，理解代码变更的结构，并以软件工程师熟悉的形式呈现出来。

Potato 的 CodingTraceDisplay 是专为编码智能体会话准备的显示类型。它把 unified diff 渲染成红/绿语法高亮的行，把终端输出放进深色代码块，文件读取带行号显示，并提供一个文件树侧边栏，列出智能体动过的每一个文件。标注者可以在文件之间跳转，展开或折叠过长的输出，并对单次操作或整条 trace 评分。

配置

在项目配置中启用编码 trace 显示：

yaml

instance_display:
  fields:
    - key: structured_turns
      type: coding_trace
      label: "Agent session"
      display_options:
        # Diff rendering
        diff_view: unified          # "unified" or "side_by_side"
 
        # Terminal output
        terminal_theme: dark        # "dark" or "light"
 
        # Long output
        collapse_long_outputs: true
        max_output_lines: 50        # collapse after this many lines
 
        # Step chrome
        show_file_tree: true
        show_step_numbers: true
        show_tool_badges: true
        show_reasoning: true
        compact: false

显示功能

Unified Diff 视图

编辑操作以 unified diff 渲染，带红/绿高亮。删除的行是红色背景加 - 前缀；新增的行是绿色背景加 + 前缀。上下文行显示为中性灰。文件路径和行号范围出现在每个 diff 块上方的标题栏里。

使用 diff_view: side_by_side 时，新旧两个版本并排显示在相邻的两列中，复杂改动读起来更清楚。

深色终端块

Bash 和 shell 命令渲染在深色终端块里，使用等宽字体。命令本身带 $ 提示符前缀，输出显示在下方。退出码用一个小徽标显示（0 为绿色，非 0 为红色）。过长的输出会自动折叠，并附一个「显示另外 N 行」的展开按钮。

带行号的文件读取

智能体读取文件时，内容会以带行号的浅色代码块显示。部分读取会标出行号范围（例如「312 行中的第 42-87 行」）。语法高亮根据文件扩展名判断。

文件树侧边栏

文件树侧边栏列出智能体在这条 trace 中动过的每一个文件。文件按目录分组并按字母排序。每个文件带一个图标，表示对它做过的操作：

铅笔图标表示被编辑过的文件
眼睛图标表示只读的文件
加号图标表示新建的文件
垃圾桶图标表示被删除的文件
终端图标表示被执行的脚本

点击树中的文件，主面板会滚动到涉及该文件的第一个操作。

可折叠的长输出

开启 collapse_long_outputs 后，任何超过 max_output_lines 的输出块都会折叠。摘要行显示开头和结尾的几行，并带一个「显示全部 N 行」的按钮。这样即使单次操作产生几百行输出，trace 仍然好翻。

Trace 转换器

Potato 内置四个编码智能体专用的转换器，把各种 trace 格式归一到统一的编码 trace 表示。

转换器	来源	格式
`claude_code`	Claude Code / Anthropic API	带 `tool_use` 块的 Messages API（Read、Edit、Bash、Write 工具）
`aider`	Aider	Markdown 对话日志，含 SEARCH/REPLACE 和 ORIGINAL/UPDATED 编辑块
`swe_agent_trajectory`	SWE-Agent	轨迹 JSON 文件，含 thought/action/observation 三元组
`auto`	自动识别	检查 trace 结构并自动选择最合适的转换器

转换不是一个配置项，而是在启动服务器之前跑的一步 CLI 命令：

bash

python -m potato.trace_converter \
  --input traces.json \
  --input-format claude_code \
  --output data/traces.jsonl

拿不准手上是哪种格式时，用 --auto-detect 代替 --input-format；想看全部可选格式就用 --list-formats。

Claude Code 转换器

claude_code 转换器处理来自 Anthropic Messages API 的 trace，其中工具使用表示为 tool_use 和 tool_result 内容块。它识别标准的 Claude Code 工具：

Read 工具调用变成文件读取显示
Edit 工具调用变成 unified diff
Write 工具调用变成文件创建显示
Bash 工具调用变成终端块
Glob/Grep 工具调用变成搜索结果显示

Aider 转换器

aider 转换器解析 Aider 基于 markdown 的对话格式。它提取 SEARCH/REPLACE 块（以及更早的 ORIGINAL/UPDATED 格式）并转换成 unified diff。shell 命令及其输出从标记为 bash 或 shell 的围栏代码块中提取。

SWE-Agent 轨迹转换器

swe_agent_trajectory 转换器读取 SWE-Agent 的轨迹 JSON 文件。每条轨迹记录包含一个 thought（智能体的推理）、一个 action（执行的命令）和一个 observation（命令输出）。转换器把 action 归类为文件编辑、文件读取、shell 命令和导航操作。

CLI 用法

在启动标注服务器之前先转换原始 trace：

bash

# Convert Claude Code traces
python -m potato.trace_converter \
  -i traces.json \
  -f claude_code \
  -o data/converted.jsonl
 
# Convert Aider chat logs
python -m potato.trace_converter \
  -i aider_chat_history/ \
  -f aider \
  -o data/aider_converted.jsonl
 
# Convert SWE-Agent trajectories
python -m potato.trace_converter \
  -i trajectories/ \
  -f swe_agent_trajectory \
  -o data/swe_converted.jsonl
 
# Auto-detect format
python -m potato.trace_converter \
  -i mixed_traces/ \
  -f auto \
  -o data/auto_converted.jsonl

-i 参数接受单个文件或一个目录。给的是目录时，其中所有 .json 和 .jsonl 文件都会被处理。转换器向输出文件每行写入一个 JSON 对象。

其他选项：

bash

# Filter by file extension
python -m potato.trace_converter \
  -i traces/ -f claude_code -o data/out.jsonl \
  --include "*.json"
 
# Add metadata fields from a CSV
python -m potato.trace_converter \
  -i traces/ -f claude_code -o data/out.jsonl \
  --metadata metadata.csv --join-key trace_id
 
# Validate output without writing
python -m potato.trace_converter \
  -i traces.json -f claude_code --validate

数据格式

转换之后，输出 JSONL 文件的每一行结构如下：

json

{
  "id": "trace_001",
  "task_description": "Fix the failing test in test_parser.py",
  "repository": "myproject",
  "structured_turns": [
    {
      "role": "assistant",
      "content": "I'll read the parser first to see how it handles empty input.",
      "tool_calls": [
        {
          "tool": "Read",
          "input": { "file_path": "src/parser.py" },
          "output": "def parse(input_str):\n    tokens = tokenize(input_str)\n    ..."
        }
      ]
    },
    {
      "role": "assistant",
      "content": "Empty input returns None where the test expects a ParseError.",
      "tool_calls": [
        {
          "tool": "Edit",
          "input": {
            "file_path": "src/parser.py",
            "old_string": "    if len(tokens) == 0:\n        return None",
            "new_string": "    if len(tokens) == 0:\n        raise ParseError('Empty input')"
          },
          "output": "Edited src/parser.py"
        },
        {
          "tool": "Bash",
          "input": { "command": "python -m pytest test_parser.py -v" },
          "output": "test_parser.py::test_empty_input PASSED\ntest_parser.py::test_valid_input PASSED\n\n2 passed in 0.34s"
        }
      ]
    }
  ],
  "metadata": {
    "agent": "claude_code",
    "model": "claude-sonnet-4-20250514",
    "total_tokens": 15234,
    "duration_seconds": 42
  }
}

structured_turns 数组保留操作的确切顺序。每个 turn 都有一个 type 字段（file_read、edit、terminal、file_write、search、thought）和该类型特有的字段。

配置参考

下面是一份完整配置，把编码 trace 显示和用于评估编码智能体输出的标注 schema 组合在一起：

yaml

annotation_task_name: "Coding Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/coding_traces.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
instance_display:
  fields:
    - key: structured_turns
      type: coding_trace
      label: "Agent session"
      display_options:
        diff_view: unified
        terminal_theme: dark
        collapse_long_outputs: true
        max_output_lines: 50
        show_file_tree: true
        show_step_numbers: true
        show_tool_badges: true
        show_reasoning: true
 
annotation_schemes:
  # Did the agent complete the task?
  - annotation_type: radio
    name: task_completion
    description: "Did the agent successfully complete the task?"
    labels:
      - "Fully Complete"
      - "Partially Complete"
      - "Failed"
      - "Made Things Worse"
 
  # Per-step correctness
  - annotation_type: trajectory_eval
    name: step_quality
    description: "Rate this step"
    steps_key: agentic_steps
    correctness_options:
      - "Good"
      - "Acceptable"
      - "Unnecessary"
      - "Incorrect"
 
  # Code quality rating
  - annotation_type: likert
    name: code_quality
    size: 5
    min_label: "Poor"
    max_label: "Excellent"
    description: "Rate the quality of the code changes"
    labels:
      1: "Very Poor"
      2: "Poor"
      3: "Acceptable"
      4: "Good"
      5: "Excellent"
 
  # Free-text notes
  - annotation_type: text
    name: notes
    description: "Any additional observations about the coding trace"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
export_annotation_format: "jsonl"

运行示例项目

Potato 附带了编码智能体标注的示例项目：

bash

# Clone the repository
git clone https://github.com/davidjurgens/potato.git
cd potato
 
# Run the Claude Code trace evaluation example
potato start example/coding_agent_eval/config.yaml -p 8000
 
# Run the SWE-bench evaluation example
potato start example/swe_bench_eval/config.yaml -p 8000
 
# Run the multi-agent comparison example
potato start example/coding_agent_comparison/config.yaml -p 8000

每个示例都包含样例 trace、一份完整的配置文件，以及描述标注任务的 README。

另请参阅

过程奖励标注 —— 为 PRM 训练收集逐步奖励信号
代码评审标注 —— GitHub PR 风格的代码变更内联评审
实时编码智能体观察 —— 实时观察编码智能体并与之交互
智能体标注 —— 通用的智能体 trace 标注
导出格式 —— 导出标注数据用于模型训练

有关实现详情，请参阅源文档。