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” 功能。建議會以程式碼塊的形式出現在評論下方，可用於訓練程式碼修復模型。

yaml
# In inline comment output:
{
  "file": "src/parser.py",
  "line_start": 42,
  "line_end": 44,
  "category": "bug",
  "severity": "critical",
  "comment": "Off-by-one error: range should be inclusive of end",
  "suggestion": "for i in range(start, end + 1):\n    process(tokens[i])"
}

檔案級評分

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

配置

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
task_name: "Coding Agent Code Review"
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: 5
    syntax_highlight: true
    show_line_numbers: true
    terminal_theme: dark
    file_tree:
      enabled: true
      position: left
      show_operation_icons: true
      click_to_navigate: 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/"
output_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
{
  "id": "trace_042",
  "annotator": "reviewer_01",
  "timestamp": "2025-01-15T14:30:00Z",
  "annotations": {
    "inline_comments": [
      {
        "file": "src/parser.py",
        "line_start": 42,
        "line_end": 42,
        "category": "bug",
        "severity": "critical",
        "comment": "This will throw IndexError when tokens list is empty",
        "suggestion": "if tokens:\n    return tokens[0]\nreturn None"
      },
      {
        "file": "src/parser.py",
        "line_start": 15,
        "line_end": 15,
        "category": "style",
        "severity": "nit",
        "comment": "Variable name 'x' is not descriptive"
      },
      {
        "file": "tests/test_parser.py",
        "line_start": 28,
        "line_end": 30,
        "category": "praise",
        "comment": "Good edge case coverage for empty input"
      }
    ],
    "file_ratings": {
      "src/parser.py": { "correctness": 3, "quality": 2 },
      "tests/test_parser.py": { "correctness": 5, "quality": 4 }
    },
    "verdict": {
      "decision": "request_changes",
      "summary": "The core fix is on the right track but has an edge case bug with empty input. The test coverage is good. Fix the IndexError and clean up variable naming."
    }
  }
}

匯出

程式碼評審標註可以匯出為多種格式：

bash
# Export as structured code review JSON
python -m potato.export \
  -i output/ \
  -f code_review \
  -o results/reviews.jsonl
 
# Export inline comments only (for training code comment models)
python -m potato.export \
  -i output/ \
  -f code_review_comments \
  -o results/comments.jsonl
 
# Export file ratings as a CSV (for analysis)
python -m potato.export \
  -i output/ \
  -f code_review_file_ratings \
  -o results/file_ratings.csv
 
# Export verdict distribution summary
python -m potato.export \
  -i output/ \
  -f code_review_verdicts \
  -o results/verdicts.json

code_review_comments 格式尤其適合訓練那些生成程式碼評審評論、或者預測程式碼問題位置與類別的模型。

另請參閱

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