التعليق التوضيحي لمراجعة الأكواد

جديد في الإصدار v2.4.0

يتطلب تقييم تغييرات الكود التي ينتجها وكلاء البرمجة أكثر من حكم ثنائي بالنجاح أو الفشل. فالباحثون وفرق الهندسة يحتاجون إلى تقدير جودة الكود على مستويات دقة متعددة: قد تحتوي أسطر بعينها على أخطاء أو مخالفات أسلوبية، وقد تكون ملفات كاملة معدَّلة تعديلاً صحيحاً أو غير ضرورية أصلاً، وقد تحل مجموعة التغييرات المشكلة لكنها تُدخل ديناً تقنياً. وهذا هو سير العمل نفسه الذي يتبعه مراجعو الأكواد البشر عند مراجعة pull requests على GitHub.

يأتي وضع التعليق التوضيحي لمراجعة الأكواد في Potato بتجربة مراجعة الـ pull request من GitHub إلى تقييم الوكلاء. يرى المعلّقون diffs موحّدة لكل ملف عدّله الوكيل. ويمكنهم النقر على أي سطر في الـ diff لترك تعليق مضمّن مع وسم فئة. ويحصل كل ملف على تقييم للصحة وآخر للجودة. ثم يصدر المعلّق حكماً نهائياً: قبول، أو طلب تعديلات، أو تعليق فقط. ويُلتقط هذا كله في بيانات تعليق توضيحي منظمة جاهزة لتدريب نماذج جودة الكود.

التعليقات المضمّنة

ينقر المعلّقون على أي سطر في الـ diff ليفتحوا نموذج تعليق مضمّن. لكل تعليق فئة، ودرجة خطورة، ومحتوى نصي حر. ويظهر التعليق مربوطاً بالسطر المعني، تماماً كتعليقات مراجعة الـ pull request على GitHub.

فئات التعليقات

تغطي فئات التعليقات الافتراضية أشيع أنواع ملاحظات مراجعة الأكواد:

التهيئة

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 مفعّلاً، يمكن للمعلّقين كتابة بديل مقترح لكتلة الكود التي يعلّقون عليها. وهذا يحاكي ميزة suggestion في GitHub. يظهر الاقتراح في كتلة كود تحت التعليق، ويمكن استخدامه في تدريب نماذج إصلاح الكود.

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

التقييمات على مستوى الملف

يحصل كل ملف عدّله الوكيل على تقييمين مستقلين: الصحة وجودة الكود.

التهيئة

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

صيغة المخرجات

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

الحكم الكلي

بعد مراجعة كل الملفات وترك التعليقات المضمّنة، يصدر المعلّق حكماً كلياً على مجموعة التغييرات بأكملها.

التهيئة

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

مرجع التهيئة

إليك تهيئة كاملة لمهمة تعليق توضيحي لمراجعة الأكواد:

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: تعرض اللوحة الرئيسية diffs موحّدة لكل ملف. يمرّ المعلّقون على الـ diffs ويقرأون كل تغيير.

4. إضافة تعليقات مضمّنة: النقر على رقم سطر يفتح نموذج تعليق. يختار المعلّق فئة (خلل، اقتراح، إلخ)، ويختار درجة خطورة اختيارياً، ويكتب تعليقه، ويضيف اقتراح كود إن شاء.

5. تقييمات الملفات: بعد مراجعة diff كل ملف، يقيّمه المعلّق على الصحة (1-5) وعلى جودة الكود (1-5) عبر أدوات التقييم أسفل diff كل ملف.

6. الحكم الكلي: في الأسفل، يختار المعلّق حكماً (قبول أو طلب تعديلات أو تعليق فقط) ويكتب ملخصاً لمراجعته.

7. الإرسال: ينقر المعلّق على Submit لحفظ كل التعليقات المضمّنة وتقييمات الملفات والحكم في سجل تعليق واحد.

صيغة البيانات

المخرجات الكاملة لتعليق توضيحي واحد لمراجعة أكواد:

{
  "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 }
  }
}

التصدير

يمكن تصدير تعليقات مراجعة الأكواد بصيغ عدة:

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

صيغة code_review_comments مفيدة بوجه خاص لتدريب نماذج تولّد تعليقات مراجعة الأكواد أو تتنبأ بموضع مشكلات الكود وفئتها.

انظر أيضاً

• التعليق التوضيحي لوكيل البرمجة -- عرض تتبعات وكلاء البرمجة مع تصيير الـ diff وشجرة الملفات
• تعليق مكافأة العملية -- إشارات مكافأة لكل خطوة لتدريب PRM
• مراقبة وكيل البرمجة المباشر -- مراقبة وكلاء البرمجة والتفاعل معهم في الوقت الفعلي
• التعليق التوضيحي للوكلاء -- التعليق على تتبعات الوكلاء لأغراض عامة
• صيغ التصدير -- كل صيغ التصدير المدعومة

للاطلاع على تفاصيل التنفيذ، راجع الوثائق المصدرية.