Skip to content

程式碼評審標註

用 GitHub PR 風格的內聯 diff 評論、檔案級正確性評分，以及通過或打回的結論，評審 AI 編碼智慧體的輸出，衡量程式碼品質。

v2.4.0 新增

評估 AI 編碼智慧體產出的程式碼改動，光靠一個通過/失敗的判斷遠遠不夠。研究者和工程團隊需要在多個粒度上衡量程式碼品質：某一行可能藏著 bug 或風格問題，某個檔案可能改對了也可能根本不該改，而整套改動可能解決了問題卻留下了技術債。這正是人類評審在 GitHub 上看 pull request 時走的流程。

Potato 的程式碼評審標註模式把 GitHub PR 評審的體驗帶進了智慧體評估。標註者能看到智慧體改動過的每個檔案的 unified diff。他們可以點選任意 diff 行，留下帶分類標籤的內聯評論。每個檔案都會得到一個正確性和品質評分。標註者最後給出結論：approve、request changes 或 comment only。全部內容都被記錄為結構化的標註資料，可直接用於訓練程式碼品質模型。

內聯評論

標註者點選 diff 中的任意一行，開啟內聯評論表單。每條評論包含一個分類、一個嚴重程度和自由文本內容。評論會錨定在具體的那一行上，和 GitHub PR 評審評論一樣。

評論分類

預設的評論分類覆蓋了最常見的程式碼評審反饋類型：

分類說明
bug功能性 bug —— 程式碼無法正確工作
logic邏輯錯誤 —— 語法沒問題，但做法本身有缺陷
security安全漏洞或不安全的做法
performance效能問題 —— 多餘的計算、記憶體洩漏等
style風格問題 —— 命名、格式、是否地道
suggestion有更好的替代做法
question需要澄清 —— 評審者拿不準這裡的意圖
praise正面反饋 —— 智慧體做得好的地方

配置

yaml
annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Click any diff line to add an inline comment"
 
    # Categories offered on each inline comment
    comment_categories:
      - bug
      - logic
      - security
      - performance
      - style
      - suggestion
      - question

建議的程式碼改動

啟用 allow_suggestions 後，標註者可以為自己正在評論的程式碼塊寫一段替換建議，對應 GitHub 的 “suggestion” 功能。建議會以程式碼塊的形式出現在評論下方，可用於訓練程式碼修復模型。

json
{
  "category": "bug",
  "file": "src/parser.py",
  "line": 42,
  "text": "Off-by-one error: range should be inclusive of end"
}

檔案級評分

智慧體改動過的每個檔案都會得到兩項彼此獨立的評分：正確性和程式碼品質。

配置

yaml
annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Rate each modified file"
 
    # One 1-5 rating per dimension, per file touched by the diff
    file_rating_dimensions:
      - correctness
      - quality

輸出格式

json
{
  "file_ratings": {
    "src/parser.py": {
      "correctness": 4,
      "quality": 3
    },
    "tests/test_parser.py": {
      "correctness": 5,
      "quality": 4
    },
    "src/utils.py": {
      "correctness": 2,
      "quality": 2
    }
  }
}

總體結論

看完所有檔案、留下內聯評論之後，標註者為整套改動給出一個總體結論。

配置

yaml
annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Give an overall verdict on the code changes"
 
    verdict_options:
      - approve
      - request_changes
      - comment_only

配置參考

一個程式碼評審標註任務的完整配置：

yaml
annotation_task_name: "Coding Agent Code Review"
task_dir: "."
 
data_files:
  - "data/coding_traces.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
instance_display:
  fields:
    - key: structured_turns
      type: coding_trace
      label: "Agent changes"
      display_options:
        diff_view: unified
        terminal_theme: dark
        collapse_long_outputs: true
        max_output_lines: 50
        show_file_tree: true
        show_step_numbers: true
        show_reasoning: true
 
annotation_schemes:
  # Inline comments, file ratings and the overall verdict are all one scheme
  - annotation_type: code_review
    name: review
    description: "Review the agent's code changes"
    comment_categories:
      - bug
      - logic
      - security
      - performance
      - style
      - suggestion
      - question
      - praise
    file_rating_dimensions:
      - correctness
      - quality
    verdict_options:
      - approve
      - request_changes
      - comment_only
 
  # A free-text summary is a separate scheme
  - annotation_type: text
    name: summary
    description: "Summarize your review"
    rows: 4
 
output_annotation_dir: "output/"
export_annotation_format: "jsonl"

標註流程

標註者在完成一個程式碼評審標註任務時，看到和要做的是這些：

  1. 任務概覽：任務描述顯示在最上方，說明智慧體被要求做什麼（比如“修復 test_parser.py 中失敗的測試”）。

  2. 檔案樹導航：左側欄列出智慧體動過的所有檔案，並用顏色區分：綠色是新增檔案，黃色是修改的檔案，紅色是刪除的檔案。

  3. 審閱 diff：主面板按檔案顯示 unified diff。標註者逐段翻看，讀每一處改動。

  4. 新增內聯評論：點選行號會開啟評論表單。標註者選擇一個分類（bug、建議等），可選地選擇嚴重程度，寫下評論，也可以附上一段程式碼建議。

  5. 檔案評分：看完某個檔案的 diff 之後，標註者用該檔案 diff 下方的評分元件，從正確性（1-5）和程式碼品質（1-5）兩方面打分。

  6. 總體結論：在頁面底部，標註者選擇一個結論（通過、要求修改，或只留評論），並寫一段評審總結。

  7. 提交：標註者點選 “Submit”，把全部內聯評論、檔案評分和結論作為一條標註記錄儲存。

資料格式

一次程式碼評審標註的完整輸出：

json
{
  "instance_id": "trace_042",
  "annotator": "reviewer_01",
  "verdict": "request_changes",
  "comments": [
    {
      "category": "bug",
      "file": "src/parser.py",
      "line": 42,
      "text": "This will throw IndexError when tokens list is empty"
    },
    {
      "category": "style",
      "file": "src/parser.py",
      "line": 15,
      "text": "Variable name 'x' is not descriptive"
    },
    {
      "category": "praise",
      "file": "tests/test_parser.py",
      "line": 28,
      "text": "Good edge case coverage for empty input"
    }
  ],
  "file_ratings": {
    "src/parser.py": { "correctness": 3, "quality": 2 },
    "tests/test_parser.py": { "correctness": 5, "quality": 4 }
  }
}

匯出

程式碼評審標註通過 coding_eval 匯出器產出。它接受的是配置檔案而不是輸出目錄，並寫入你指定的目錄：

bash
python -m potato.export \
  -c config.yaml \
  -f coding_eval \
  -o results/ \
  --option types=code_review

types 決定寫出哪些內容，可取 prm、preference、swebench 和 code_review，預設四種全寫。去掉 --option 就能在評審之外一併拿到其餘幾種。如果某個請求的類型在這項研究裡沒有資料，匯出器會明說，而不是寫出一個空檔案。

程式碼評審的輸出裡帶著每條內聯評論及其檔案、行號、分類和嚴重程度，還有逐檔案的評分和每次評審的結論，所以評論級的訓練資料和評分分析都來自同一個檔案。

另請參閱

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