Name: Potato
Author: Potato

給編碼智慧體的工作打分

編碼智慧體（如 Claude Code、Aider 和 SWE-Agent）進步得很快，現在人們需要給它們的工作打分。一次執行就是一條很長的軌跡：程式碼修改、終端命令、檔案讀取和推理步驟串在一起。要訓練出更好的智慧體，你需要人對這些執行給出反饋，而多數團隊手上的標註工具從來不是為這類資料設計的。

純文本的標註介面無法渲染統一差異（unified diff），無法格式化終端輸出，也應付不了智慧體軌跡的巢狀結構。於是各個實驗室自己寫評測介面，重複同樣的工作，最後得到一批互不相通的資料集。

Potato 現在直接支援編碼智慧體標註，配有為軌跡構建的渲染元件、面向這類評測的標註方案，以及可直接進入訓練流程的匯出格式。完整功能參考見編碼智慧體標註文件，以及更宏觀的智慧體評測指南。

CodingTraceDisplay：軌跡檢視器

標註體驗的主體都通過 CodingTraceDisplay 元件呈現。它會按每種步驟類型選擇合適的視覺化方式，逐步渲染智慧體的軌跡。

編碼智慧體標註介面：

展示差異渲染與檔案樹的編碼智慧體軌跡檢視 CodingTraceDisplay 會以恰當的格式渲染程式碼差異、終端輸出和檔案讀取

統一差異檢視

程式碼修改會渲染成統一差異，刪除行標紅、新增行標綠。差異檢視包含行號、檔案路徑標題和改動周圍的上下文行，讀起來就像一個 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"

可摺疊的輸出

任何步驟類型的長輸出都可以摺疊，以保持軌跡的可讀性。標註者可以按需展開單個步驟，也可以使用"全部展開"／"全部摺疊"控制元件。智慧體的思考／推理塊預設摺疊，但隨時可以展開檢視。

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 拉取請求式的評審帶到智慧體軌跡上。標註者可以在差異中的特定行上留下行內評論、給單個檔案打分，並給出總體結論。

帶行內差異評論的程式碼審查標註標註者可以點選差異行新增行內評論、給檔案打分，並給出通過／打回的結論

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 內建了三種編碼智慧體格式的轉換器，並支援對混合目錄的自動識別。每個轉換器都會把對應格式歸一化成 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 會生成適用於直接偏好最佳化（DPO）或 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 等訓練框架更緊密的整合。

如果你寫了新的軌跡轉換器、方案或匯出格式，我們非常歡迎貢獻。如果你的團隊正在評測編碼智慧體，並遇到了這套配置覆蓋不到的場景，歡迎在我們的 GitHub 倉庫提 issue。