Name: Potato
Author: Potato

Как оценивать работу кодового агента

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

Обычный текстовый интерфейс разметки не умеет отрисовать единый дифф, отформатировать вывод терминала или справиться с вложенной структурой трассы агента. Поэтому лаборатории пишут собственные интерфейсы оценки, повторяют одну и ту же работу и получают датасеты, которые между собой не стыкуются.

Теперь Potato работает с разметкой кодовых агентов напрямую: компоненты отрисовки сделаны под трассы, схемы разметки — под такую оценку, а экспорт идёт прямо в обучение. Полный справочник — в документации по разметке кодовых агентов и в более общем руководстве по оценке агентов.

CodingTraceDisplay: просмотрщик трасс

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

Интерфейс разметки кодового агента:

Coding agent trace display showing diff rendering and file tree The CodingTraceDisplay renders code diffs, terminal output, and file reads with proper formatting

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

Правки кода рисуются едиными диффами с красно-зелёной подсветкой удалённых и добавленных строк. В диффе есть номера строк, заголовки с путями к файлам и строки контекста вокруг изменений, так что читается он как пул-реквест на GitHub.

yaml

# The diff rendering is automatic when your trace data includes tool_use
# steps with file edit operations. No special config is needed.
coding_agent:
  display:
    diff_style: "unified"         # "unified" or "split" side-by-side
    context_lines: 3              # Lines of context around changes
    syntax_highlighting: true     # Language-aware highlighting
    collapse_large_diffs: true    # Auto-collapse diffs > 100 lines
    large_diff_threshold: 100

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

Команды bash и их вывод рисуются тёмными терминальными блоками моноширинным шрифтом, с поддержкой цветов ANSI и прокруткой для длинных результатов. В блоке видны выполненная команда, рабочий каталог и код возврата.

yaml

coding_agent:
  display:
    terminal_theme: "dark"        # "dark" or "light"
    max_terminal_height: 400      # pixels, scrollable beyond this
    show_exit_codes: true
    show_working_directory: true
    ansi_colors: true             # Render ANSI escape sequences

Блоки кода с номерами строк

Операции чтения файлов показываются блоками кода с подсветкой синтаксиса и номерами строк. Если агент прочитал конкретный диапазон строк, показываются только они, с сохранением исходных номеров, чтобы можно было свериться с файлом.

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

Сворачиваемая боковая панель показывает все файлы, затронутые за траекторию, в виде дерева. У каждого файла значок, показывающий, был ли он создан, изменён, прочитан или удалён. Клик по файлу прокручивает трассу к его первому появлению.

yaml

coding_agent:
  display:
    file_tree:
      enabled: true
      position: "left"            # "left" or "right"
      show_change_icons: true     # Icons for created/modified/deleted
      group_by: "directory"       # "directory" or "chronological"

Сворачиваемый вывод

Длинный вывод любого типа шага можно свернуть, чтобы трасса оставалась читаемой. Разметчик разворачивает отдельные шаги по мере надобности или пользуется кнопками «Expand All» и «Collapse All». Блоки размышлений агента по умолчанию свёрнуты, но доступны для разбора.

yaml

coding_agent:
  display:
    collapsible:
      auto_collapse_thinking: true
      auto_collapse_long_output: true
      long_output_threshold: 50   # lines
      default_expanded_types:     # These step types start expanded
        - "file_edit"
        - "bash_command"

Схема модели вознаграждения процесса (PRM)

Модели вознаграждения процесса раздают заслуги по шагам, а не оценивают только итоговый результат. Potato поддерживает два режима разметки PRM, рассчитанные на разный баланс между скоростью и подробностью.

Режим первой ошибки

В режиме первой ошибки разметчик пролистывает траекторию и кликает по первому шагу, где агент свернул не туда. Все шаги до него автоматически помечаются верными, а все после (включая сам этот шаг) — неверными. Размечать так намного быстрее: разметчик указывает одну точку вместо того, чтобы оценивать каждый шаг.

yaml

annotation_schemes:
  - annotation_type: process_reward
    name: prm_first_error
    mode: "first_error"
    description: "Click the first step where the agent makes an error"

Пошаговый режим

В пошаговом режиме каждый шаг получает независимую оценку. Обучающие данные выходят подробнее, но на трассу уходит больше времени. Разметчик отмечает каждый шаг как верный, неверный или частично верный.

yaml

annotation_schemes:
  - annotation_type: process_reward
    name: prm_per_step
    mode: "per_step"

Схема ревью кода

Схема ревью кода приносит в трассы агентов разметку в стиле пул-реквестов GitHub. Разметчик оставляет комментарии к конкретным строкам внутри диффов, оценивает отдельные файлы и выносит общий вердикт.

Code review annotation with inline diff comments Annotators can click diff lines to add inline comments, rate files, and give approve/reject verdicts

yaml

annotation_schemes:
  - annotation_type: code_review
    name: agent_review
    comment_categories:
      enabled: true
      categories:                 # Optional categorization for comments
        - "Bug"
        - "Style"
        - "Logic Error"
        - "Unnecessary Change"
        - "Missing Error Handling"
    file_rating_dimensions:
      enabled: true
      scale: [1, 2, 3, 4, 5]
      labels: ["Poor", "Below Average", "Acceptable", "Good", "Excellent"]
    verdict_options:
      enabled: true
      options:
        - value: "approve"
          text: "Approve"
          description: "Changes are correct and complete"
        - value: "request_changes"
          text: "Request Changes"
          description: "Changes need fixes before merging"
        - value: "comment"
          text: "Comment"
          description: "General feedback, no strong opinion"

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

В Potato встроены конвертеры для трёх форматов кодовых агентов плюс автоопределение для смешанных каталогов. Каждый конвертер приводит свой формат к внутреннему структурному представлению трассы.

Claude Code (Anthropic Messages API)

Трассы Claude Code используют формат Anthropic Messages API с блоками tool_use и tool_result. Конвертер извлекает из вызовов инструментов правки файлов, команды bash и чтение файлов и сохраняет текст рассуждений ассистента.

bash

# Convert Claude Code traces to Potato format
potato convert-traces \
  --format claude_code \
  --input ./claude_traces/ \
  --output ./potato_data/traces.jsonl

Aider (чат в Markdown с блоками правок)

Aider выдаёт логи чата в Markdown с блоками правок SEARCH/REPLACE. Конвертер разбирает их, восстанавливая правки файлов, и извлекает команды shell из блоков кода.

bash

# Convert Aider chat logs
potato convert-traces \
  --format aider \
  --input ./aider_logs/ \
  --output ./potato_data/traces.jsonl

SWE-Agent (мысль/действие/наблюдение)

SWE-Agent работает в цикле «мысль/действие/наблюдение». Конвертер сопоставляет действия с подходящими типами шагов (правка, bash, чтение) и сохраняет цепочку рассуждений агента сворачиваемыми блоками размышлений.

bash

# Convert SWE-Agent trajectories
potato convert-traces \
  --format swe_agent \
  --input ./swe_agent_trajectories/ \
  --output ./potato_data/traces.jsonl

Автоопределение

Если у вас трассы от разных агентов, Potato может определить формат каждого файла по его структуре:

bash

# Auto-detect format for mixed trace directories
potato convert-traces \
  --format auto \
  --input ./mixed_traces/ \
  --output ./potato_data/traces.jsonl

Экспорт для обучающих конвейеров

Размеченные трассы выгружаются в форматах, готовых для обучения моделей.

Формат PRM

Пошаговые метки вознаграждения для обучения моделей вознаграждения процесса:

python

# Exported PRM format (one line per trace)
{
  "trace_id": "trace_001",
  "steps": [
    {"step_idx": 0, "content": "Read file src/main.py", "label": "correct"},
    {"step_idx": 1, "content": "Edit src/main.py: fix import", "label": "correct"},
    {"step_idx": 2, "content": "Run tests", "label": "correct"},
    {"step_idx": 3, "content": "Edit src/utils.py: wrong fix", "label": "incorrect"},
    {"step_idx": 4, "content": "Run tests again", "label": "incorrect"}
  ],
  "first_error_step": 3
}

Пары предпочтений DPO/RLHF

В сочетании с разметкой попарных сравнений Potato формирует пары предпочтений, пригодные для Direct Preference Optimization или обучения по RLHF:

python

# Exported preference pair format
{
  "prompt": "Fix the failing test in src/test_utils.py",
  "chosen": {"trace_id": "trace_001", "steps": [...]},
  "rejected": {"trace_id": "trace_002", "steps": [...]},
  "preference_strength": 0.85
}

Результаты, совместимые с SWE-bench

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

bash

# Export to SWE-bench format
potato export \
  --format swe_bench \
  --project ./my_project/ \
  --output ./swe_bench_results.json

Быстрый старт

Четыре шага от пустого каталога до работающего сервера разметки.

Установка

bash

pip install potato-annotation[coding-agents]

Сконвертируйте свои трассы

bash

# Convert traces from your coding agent
potato convert-traces \
  --format auto \
  --input ./my_agent_traces/ \
  --output ./data/traces.jsonl

Создайте конфигурацию

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

yaml

# config.yaml
project_name: "Coding Agent Evaluation"
port: 8000
 
data:
  source: "local"
  input_path: "./data/traces.jsonl"
  data_format: "coding_trace"
 
coding_agent:
  display:
    diff_style: "unified"
    context_lines: 3
    syntax_highlighting: true
    collapse_large_diffs: true
    terminal_theme: "dark"
    max_terminal_height: 400
    show_exit_codes: true
    file_tree:
      enabled: true
      position: "left"
      show_change_icons: true
    collapsible:
      auto_collapse_thinking: true
      auto_collapse_long_output: true
 
annotation_schemes:
  - annotation_type: process_reward
    name: prm_evaluation
    mode: "first_error"
    description: "Click the first step where the agent makes a mistake"
 
  - annotation_type: code_review
    name: code_quality
    comment_categories:
      enabled: true
      categories: ["Bug", "Logic Error", "Style", "Missing Error Handling"]
    file_rating_dimensions:
      enabled: true
      scale: [1, 2, 3, 4, 5]
    verdict_options:
      enabled: true
      options:
        - value: "approve"
          text: "Approve"
        - value: "request_changes"
          text: "Request Changes"
        - value: "comment"
          text: "Comment"
 
  - annotation_type: text
    name: overall_notes
    description: "Additional Notes"
    placeholder: "Any other observations about this trace..."
output:
  path: "./output/"
  format: "jsonl"
  export_formats:
    - "prm"
    - "swe_bench"
 
quality_control:
  inter_annotator_agreement: true
  overlap_percentage: 20
  minimum_time_per_instance: 30  # seconds
 
annotators:
  - username: "annotator1"
  - username: "annotator2"

Запустите сервер

bash

potato start config.yaml -p 8000

Откройте в браузере http://localhost:8000, войдите и начинайте размечать. Вам доступны и отрисовка диффов, и вывод терминала, и разметка процессных вознаграждений, описанные выше.

Что дальше

Это первый выпуск, и планов у нас больше. В списке: поддержка новых форматов агентов, лучшая визуализация рефакторингов по нескольким файлам и более тесная связка с обучающими фреймворками вроде OpenRLHF и TRL.

Если вы напишете новый конвертер трасс, схему или формат экспорта, мы будем рады вкладу. А если ваша команда оценивает кодовых агентов и упирается во что-то, чего эта связка не покрывает, заведите issue в нашем репозитории на GitHub.