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。