Bài 4 — Đăng nhận xét lên đúng dòng và tổng hợp review

Agent đã có danh sách nhận xét JSON. Giờ phải đưa chúng lên PR sao cho hữu ích: đúng dòng, gom thành một review, và có tóm tắt để reviewer nắm nhanh. Đăng sai chỗ hoặc spam từng comment lẻ sẽ làm dev bực và bỏ qua agent.

1. Hiểu tọa độ dòng trong diff

API review comment của GitHub yêu cầu trỏ vào vị trí trong diff, không phải số dòng file gốc. Cách chắc chắn nhất là dùng inline comment theo line + side trên review API:

POST /repos/{owner}/{repo}/pulls/{number}/reviews
{
  "event": "COMMENT",
  "body": "Agent review: 1 high, 2 medium. Xem chi tiết inline.",
  "comments": [
    {
      "path": "src/pay.py",
      "line": 42,
      "side": "RIGHT",
      "body": "**[HIGH][bug]** balance tính nhưng không kiểm tra.\n

`side: RIGHT` = phiên bản mới. Dùng khối ` 

2. Gom một review thay vì nhiều comment lẻ

Đăng một review chứa nhiều inline comment (như trên) thay vì gọi API từng comment. Lợi ích: một thông báo duy nhất cho dev, dễ theo dõi, ít rate-limit.

3. Xử lý dòng không nằm trong diff

Nếu agent muốn nói về file/dòng không xuất hiện trong diff, GitHub sẽ từ chối inline comment đó. Giải pháp: gom các nhận xét "ngoài diff" vào phần summary ở đầu review.

Các bước triển khai

• Ánh xạ mỗi nhận xét → {path, line, side, body}.
• Lọc bỏ nhận xét trỏ vào dòng không có trong diff (đưa vào summary).
• Định dạng body có nhãn [SEVERITY][category] + suggestion block.
• Tạo một review với event: COMMENT (giai đoạn đầu; xem Bài 7 về block).
• Nếu chạy lại trên cùng PR, dọn review cũ của agent hoặc chỉ comment phần thay đổi để tránh trùng lặp.

Khung tư duy: mỗi nhận xét cần "3W"

• Where — đúng file + dòng.
• What — vấn đề gì, mức nào (severity).
• Way out — cách sửa (suggestion), càng cụ thể càng tốt.

Ví dụ định dạng body dễ đọc

**[MEDIUM][test]** Nhánh lỗi mới chưa có test.
Hàm `charge` giờ raise `InsufficientFunds` nhưng không có test cho case này.
Gợi ý: thêm test khi balance < amount.

Sai lầm thường gặp

• Spam từng comment một. 12 comment riêng lẻ = 12 thông báo; dev sẽ tắt agent. Gom một review.
• Trỏ sai dòng vì nhầm tọa độ diff. Luôn dùng line theo side: RIGHT cho code mới; test kỹ trên PR nhiều hunk.
• Lặp lại review mỗi lần push. Mỗi synchronize lại đăng full review cũ gây nhiễu; hãy dedupe hoặc resolve comment đã sửa.
• Bỏ qua khối suggestion. Không dùng suggestion block là bỏ lỡ nút Apply — thứ khiến agent thực sự tiết kiệm thời gian.
• Không giới hạn số nhận xét. 40 comment trên một PR gây quá tải; cắt còn N nhận xét ưu tiên cao nhất và tóm tắt phần còn lại.

Ví dụ: sắp xếp và cắt nhận xét trước khi đăng

ORDER = {"high": 0, "medium": 1, "low": 2}
comments.sort(key=lambda c: (ORDER[c["severity"]], -c["confidence"]))
top = comments[:MAX_INLINE]          # vd 10 nhận xét inline
rest = comments[MAX_INLINE:]         # phần còn lại đưa vào summary
body = f"Agent review: {n_high} high, {n_med} medium."
if rest:
    body += f" (+{len(rest)} nhận xét mức thấp gộp trong tóm tắt.)"

Ưu tiên high trước, rồi confidence giảm dần. Cách này đảm bảo thứ quan trọng nhất luôn hiển thị, còn nhiễu mức thấp không lấn át.

Xử lý chạy lại trên cùng PR

Mỗi lần dev push, sự kiện synchronize kích hoạt agent lần nữa. Nếu đăng lại full review, PR sẽ ngập comment trùng. Hai chiến lược:

• Dedupe: trước khi đăng, lấy các review comment cũ do agent tạo, bỏ những nhận xét trùng (cùng path+line+message).
• Resolve: với comment mà dòng liên quan đã thay đổi/được sửa, đánh dấu resolved thay vì để treo.