編碼智慧體標註

Name: Potato
Author: Potato

標註編碼智慧體 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: 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

每個示例都包含樣例 trace、一份完整的配置檔案，以及描述標註任務的 README。

另請參閱

過程獎勵標註 —— 為 PRM 訓練收集逐步獎勵訊號
程式碼評審標註 —— GitHub PR 風格的程式碼變更內聯評審
即時編碼智慧體觀察 —— 即時觀察編碼智慧體並與之互動
智慧體標註 —— 通用的智慧體 trace 標註
匯出格式 —— 匯出標註資料用於模型訓練

有關實現詳情，請參閱源文件。