Разметка кодовых агентов

Name: Potato
Author: Potato

Разметка трасс кодовых агентов с отрисовкой диффов, выводом терминала и навигацией по дереву файлов. Импорт из Claude Code, Aider, SWE-Agent и других ассистентов по коду.

Появилось в v2.4.0

Кодовые агенты — Claude Code, Aider, SWE-Agent, OpenHands и другие — выдают трассы, непохожие на трассы обычных агентов. В них диффы кода, вывод терминала, чтение файлов, обход каталогов и результаты тестов. Чтобы разбирать такие трассы, нужна специализированная отрисовка, которая понимает структуру изменений в коде и показывает их в привычном инженеру виде.

CodingTraceDisplay в Potato — отдельный тип отображения для сессий кодовых агентов. Он рисует единые диффы с красно-зелёными строками и подсветкой синтаксиса, вывод терминала тёмными блоками, чтение файлов с номерами строк и даёт боковое дерево со всеми файлами, которых агент касался. Разметчик может переходить между файлами, разворачивать и сворачивать длинный вывод и оценивать как отдельные операции, так и трассу целиком.

Конфигурация

Включите отображение трассы кодового агента в конфигурации проекта:

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

Возможности отображения

Единый вид диффа

Операции правки рисуются как единые диффы с красно-зелёной подсветкой. Удалённые строки идут на красном фоне с префиксом -, добавленные — на зелёном с префиксом +. Строки контекста показаны нейтрально-серым. Путь к файлу и диапазон строк выводятся в заголовке над каждым блоком диффа.

Если задать diff_style: side_by_side, старая и новая версии встают в соседние колонки — так проще разглядеть, что изменилось в сложных правках.

Тёмные терминальные блоки

Команды bash и shell рисуются тёмными терминальными блоками моноширинным шрифтом. Сама команда выводится с префиксом-приглашением $, а вывод — под ней. Коды возврата показаны небольшим бейджем (зелёный для 0, красный для остального). Длинный вывод автоматически сворачивается с раскрывашкой «Show N more lines».

Чтение файлов с номерами строк

Когда агент читает файл, содержимое показывается с номерами строк в светлом блоке кода. При частичном чтении выводится диапазон (например, «lines 42-87 of 312»). Подсветка синтаксиса подбирается по расширению файла.

Боковое дерево файлов

В боковом дереве видны все файлы, которых агент касался за трассу. Файлы сгруппированы по каталогам и отсортированы по алфавиту. У каждого стоит значок выполненной операции:

Карандаш — файл правился
Глаз — файл только читался
Плюс — файл создан
Корзина — файл удалён
Терминал — запускался скрипт

Клик по файлу в дереве прокручивает основную панель к первой операции с этим файлом.

Сворачивание длинного вывода

Любой блок вывода длиннее auto_collapse_threshold сворачивается автоматически. В сводной строке видны первые и последние несколько строк, а рядом — кнопка «Show all N lines». Так по трассе можно перемещаться, даже когда отдельные операции выдают сотни строк.

Конвертеры трасс

Potato поставляется с четырьмя конвертерами специально для кодовых агентов; они приводят форматы трасс к единому представлению.

Конвертер	Источник	Формат
`claude_code`	Claude Code / API Anthropic	Messages API с блоками `tool_use` (инструменты Read, Edit, Bash, Write)
`aider`	Aider	Логи чата в Markdown с блоками правок SEARCH/REPLACE и ORIGINAL/UPDATED
`swe_agent_trajectory`	SWE-Agent	Файлы траекторий в JSON с тройками «мысль/действие/наблюдение»
`auto`	Автоопределение	Осматривает структуру трассы и сам выбирает подходящий конвертер

Укажите конвертер в конфигурации:

yaml

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

Конвертер Claude Code

Конвертер claude_code обрабатывает трассы Anthropic Messages API, где работа с инструментами представлена блоками tool_use и tool_result. Он распознаёт стандартные инструменты Claude Code:

Вызовы Read становятся отображением чтения файла
Вызовы Edit становятся едиными диффами
Вызовы Write становятся отображением создания файла
Вызовы Bash становятся терминальными блоками
Вызовы Glob/Grep становятся отображением результатов поиска

Конвертер Aider

Конвертер aider разбирает формат чата Aider на основе Markdown. Он извлекает блоки SEARCH/REPLACE (и более старый формат ORIGINAL/UPDATED) и превращает их в единые диффы. Команды shell и их вывод извлекаются из блоков кода, помеченных bash или shell.

Конвертер траекторий SWE-Agent

Конвертер swe_agent_trajectory читает файлы траекторий SWE-Agent в JSON. Каждая запись содержит мысль (рассуждение агента), действие (выполненную команду) и наблюдение (вывод команды). Конвертер разносит действия по категориям: правки файлов, чтение файлов, команды shell и навигация.

Работа через CLI

Сконвертируйте сырые трассы до запуска сервера разметки:

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 сохраняет точный порядок операций. У каждой записи есть поле type (file_read, edit, terminal, file_write, search, thought) и поля, специфичные для этого типа.

Справочник по конфигурации

Вот законченная конфигурация, объединяющая отображение трассы кодового агента со схемами разметки для оценки его вывода:

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: 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
    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/"
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

К каждому примеру прилагаются образцы трасс, полный файл конфигурации и README с описанием задачи разметки.

Смотрите также

Разметка процессных вознаграждений — сбор пошаговых сигналов вознаграждения для обучения PRM
Разметка ревью кода — разбор изменений в стиле пул-реквестов GitHub
Наблюдение за живым кодовым агентом — смотреть за кодовыми агентами и вмешиваться в реальном времени
Разметка агентов — разметка трасс агентов общего назначения
Форматы экспорта — выгрузка данных разметки для обучения моделей

Детали реализации — в исходной документации.