编码智能体标注

标注编码智能体 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

agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    # Diff rendering
    diff_style: unified          # "unified" or "side_by_side"
    diff_context_lines: 3        # lines of context around changes
    syntax_highlight: true       # language-aware highlighting
    show_line_numbers: true
 
    # Terminal output
    terminal_theme: dark         # "dark" or "light"
    terminal_max_lines: 80       # auto-collapse after this many lines
    show_exit_codes: true
 
    # File reads
    file_read_max_lines: 100     # auto-collapse file reads longer than this
    show_file_path: true
    show_line_range: true        # display "lines 42-87" when partial reads
 
    # File tree sidebar
    file_tree:
      enabled: true
      position: left             # "left" or "right"
      show_operation_icons: true # icons for read/edit/create/delete
      group_by_directory: true
      click_to_navigate: true    # click a file to jump to its operations
 
    # Collapsible sections
    auto_collapse_threshold: 500 # characters before auto-collapsing
    collapse_file_reads: true
    collapse_terminal_output: true

显示功能

Unified Diff 视图

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

设置 diff_style: side_by_side 时，旧版本和新版本会显示在相邻的两列中，复杂改动看起来更清楚。

深色终端块

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

带行号的文件读取

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

文件树侧边栏

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

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

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

可折叠的长输出

任何超过 auto_collapse_threshold 的输出块都会自动折叠。摘要行显示开头和结尾的几行，并带一个「显示全部 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 结构并自动选择最合适的转换器

在配置中指定转换器：

yaml

agentic:
  trace_converter: claude_code    # or aider, swe_agent_trajectory, auto

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": [
    {
      "type": "file_read",
      "tool": "Read",
      "file_path": "src/parser.py",
      "content": "def parse(input_str):\n    tokens = tokenize(input_str)\n    ...",
      "line_start": 1,
      "line_end": 45
    },
    {
      "type": "edit",
      "tool": "Edit",
      "file_path": "src/parser.py",
      "old_content": "    if len(tokens) == 0:\n        return None",
      "new_content": "    if len(tokens) == 0:\n        raise ParseError('Empty input')",
      "line_start": 12,
      "line_end": 13
    },
    {
      "type": "terminal",
      "tool": "Bash",
      "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",
      "exit_code": 0
    },
    {
      "type": "file_write",
      "tool": "Write",
      "file_path": "src/parser.py",
      "content": "...",
      "is_new_file": false
    }
  ],
  "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

task_name: "Coding Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/coding_traces.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified
    diff_context_lines: 3
    syntax_highlight: true
    show_line_numbers: true
    terminal_theme: dark
    terminal_max_lines: 80
    show_exit_codes: true
    file_read_max_lines: 100
    file_tree:
      enabled: true
      position: left
      show_operation_icons: true
      group_by_directory: true
      click_to_navigate: true
    auto_collapse_threshold: 500
 
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: per_turn_rating
    name: step_quality
    description: "Rate this step"
    target: agentic_steps
    rating_type: radio
    labels:
      - "Good"
      - "Acceptable"
      - "Unnecessary"
      - "Incorrect"
 
  # Code quality rating
  - annotation_type: likert
    name: code_quality
    description: "Rate the quality of the code changes"
    min: 1
    max: 5
    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/"
output_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 标注
导出格式 —— 导出标注数据用于模型训练

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