Annotazione di coding agent

Annota le tracce dei coding agent con rendering dei diff, output del terminale e navigazione nell'albero dei file. Importa da Claude Code, Aider, SWE-Agent e altri assistenti di programmazione.

Novità della v2.4.0

I coding agent -- Claude Code, Aider, SWE-Agent, OpenHands e altri -- producono tracce diverse da quelle degli agenti generici. Contengono diff del codice, output del terminale, letture di file, esplorazioni di directory e risultati dei test. Rivederle richiede un rendering specializzato, che capisca la struttura delle modifiche al codice e la presenti in un formato familiare a chi sviluppa software.

Il CodingTraceDisplay di Potato è un tipo di display dedicato alle sessioni dei coding agent. Mostra i diff unificati con righe rosse e verdi e syntax highlighting, l'output del terminale in blocchi scuri, le letture dei file con i numeri di riga, e offre una barra laterale con l'albero dei file che elenca ogni file toccato dall'agente. Gli annotatori possono spostarsi tra i file, espandere o richiudere gli output lunghi e valutare le singole operazioni o la traccia nel suo insieme.

Configurazione

Abilita il display delle tracce di coding nella configurazione del progetto:

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

Funzionalità di visualizzazione

Vista a diff unificato

Le operazioni di modifica vengono mostrate come diff unificati con evidenziazione rossa e verde. Le righe rimosse compaiono su sfondo rosso con il prefisso -; quelle aggiunte compaiono su sfondo verde con il prefisso +. Le righe di contesto restano in grigio neutro. Il percorso del file e l'intervallo di righe compaiono in una barra di intestazione sopra ogni blocco di diff.

Con diff_style: side_by_side la versione vecchia e quella nuova compaiono in colonne affiancate, il che rende più facile vedere che cosa è cambiato nelle modifiche complesse.

Blocchi di terminale scuri

I comandi bash e shell vengono mostrati in blocchi di terminale scuri con font monospaziato. Il comando stesso compare preceduto dal prompt $, e sotto compare l'output. I codici di uscita sono indicati da un piccolo badge (verde per 0, rosso per valori diversi da zero). Gli output lunghi vengono richiusi in automatico, con un espansore «Show N more lines».

Letture di file con numeri di riga

Quando l'agente legge un file, il contenuto viene mostrato con i numeri di riga in un blocco di codice chiaro. Le letture parziali indicano l'intervallo di righe (per esempio «lines 42-87 of 312»). Il syntax highlighting viene applicato in base all'estensione del file.

Barra laterale con l'albero dei file

La barra laterale con l'albero dei file mostra ogni file toccato dall'agente durante la traccia. I file sono raggruppati per directory e ordinati alfabeticamente. Ogni file ha un'icona che indica le operazioni eseguite:

Icona a matita per i file modificati
Icona a occhio per i file solo letti
Icona con il più per i file appena creati
Icona a cestino per i file eliminati
Icona di terminale per gli script eseguiti

Cliccando su un file nell'albero, il pannello principale scorre fino alla prima operazione che lo riguarda.

Output lunghi richiudibili

Ogni blocco di output che supera auto_collapse_threshold viene richiuso in automatico. Una riga di riepilogo mostra le prime e le ultime righe, con un pulsante «Show all N lines». Così la traccia resta navigabile anche quando una singola operazione produce centinaia di righe di output.

Convertitori di tracce

Potato include quattro convertitori specifici per i coding agent, che normalizzano i formati delle tracce nella rappresentazione unificata delle tracce di coding.

Convertitore	Origine	Formato
`claude_code`	Claude Code / API di Anthropic	Messages API con blocchi `tool_use` (strumenti Read, Edit, Bash, Write)
`aider`	Aider	Log di chat in markdown con blocchi di modifica SEARCH/REPLACE e ORIGINAL/UPDATED
`swe_agent_trajectory`	SWE-Agent	File JSON di traiettoria con triple thought/action/observation
`auto`	Rilevamento automatico	Esamina la struttura della traccia e sceglie da solo il convertitore migliore

Indica il convertitore nella configurazione:

yaml

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

Convertitore Claude Code

Il convertitore claude_code gestisce le tracce della Messages API di Anthropic, dove l'uso degli strumenti è rappresentato da blocchi di contenuto tool_use e tool_result. Riconosce gli strumenti standard di Claude Code:

Le chiamate allo strumento Read diventano visualizzazioni di lettura file
Le chiamate allo strumento Edit diventano diff unificati
Le chiamate allo strumento Write diventano visualizzazioni di creazione file
Le chiamate allo strumento Bash diventano blocchi di terminale
Le chiamate agli strumenti Glob/Grep diventano visualizzazioni di risultati di ricerca

Convertitore Aider

Il convertitore aider legge il formato di chat basato su markdown di Aider. Estrae i blocchi SEARCH/REPLACE (e il vecchio formato ORIGINAL/UPDATED) e li converte in diff unificati. I comandi shell e il loro output vengono estratti dai blocchi di codice marcati come bash o shell.

Convertitore delle traiettorie SWE-Agent

Il convertitore swe_agent_trajectory legge i file JSON di traiettoria di SWE-Agent. Ogni voce della traiettoria contiene un thought (il ragionamento dell'agente), un'action (il comando eseguito) e un'observation (l'output del comando). Il convertitore classifica le azioni in modifiche a file, letture di file, comandi shell e operazioni di navigazione.

Uso da riga di comando

Converti le tracce grezze prima di avviare il server di annotazione:

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

Il flag -i accetta un singolo file o una directory. Se gli passi una directory, vengono elaborati tutti i file .json e .jsonl. Il convertitore scrive un oggetto JSON per riga nel file di output.

Altre opzioni:

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

Formato dei dati

Dopo la conversione, ogni riga del file JSONL di output ha questa struttura:

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
  }
}

L'array structured_turns conserva l'ordine esatto delle operazioni. Ogni turno ha un campo type (file_read, edit, terminal, file_write, search, thought) e campi specifici per quel tipo.

Riferimento di configurazione

Ecco una configurazione completa che unisce il display delle tracce di coding e gli schemi di annotazione per valutare l'output di un coding agent:

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"

Eseguire i progetti di esempio

Potato include progetti di esempio per l'annotazione dei coding agent:

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

Ogni esempio comprende tracce di prova, un file di configurazione completo e un README che descrive il compito di annotazione.

Vedi anche

Annotazione di process reward -- raccogli segnali di reward passo per passo per addestrare un PRM
Annotazione di code review -- revisione inline in stile pull request di GitHub per le modifiche al codice
Osservazione dal vivo di un coding agent -- guarda i coding agent e interagisci con loro in tempo reale
Annotazione agentica -- annotazione generica di tracce di agenti
Formati di esportazione -- esporta i dati di annotazione per l'addestramento dei modelli

Per i dettagli implementativi, vedi la documentazione sorgente.