Chuyển tới nội dung chính

Xử lý rework và xung đột merge

Trang này hướng dẫn từ chối task bằng Request Changes đúng cách, xử lý xung đột merge và rollback Wiki khi cần. Đọc khi bạn đã quen Review View và diff chưa đạt hoặc merge báo conflict.

Đối tượng: approver khi diff chưa đạt hoặc merge bị conflict. Điều kiện: đã quen Review View. Role kỹ thuật: Request Changes cần admin + human thật, giống Approve.

Rework và conflict nhìn một mạch​

Request Changes — vòng rework (tối đa 3 chu kỳ)​

  1. Trong Review Panel bấm Request Changes → ReworkModal.
  2. Viết ghi chú cụ thể — đây là toàn bộ thông tin agent nhận được:
Ghi chú tốt vs ghi chú tệ
  • Tệ: "Sửa lại đi".
  • Tốt: "Bổ sung try-catch retry 3 lần với backoff khi VNPay timeout, thêm unit test cho nhánh timeout".
  1. Server ghi task_runs loại rework, bơm ghi chú vào .board/history.md (mục ## Rework Attempt #<số> (ngày-giờ) kèm Kind + Note), chuyển task về in-progress trên cùng worktree và branch cũ (không rẽ nhánh mới).
  2. Agent sửa xong → quay lại review cho vòng duyệt tiếp. Tra cứu chuỗi verdict: GET /api/tasks/:id/reviews; task_runs có run_index tăng dần với kind='rework'.

Qua API (runId trả về để đối chiếu audit; blockingFindings tùy chọn):

curl -X POST http://<host>/api/tasks/<taskId>/rework \
  -H 'Content-Type: application/json' \
  -d '{"note": "Bổ sung try-catch retry 3 lần với backoff khi VNPay timeout, thêm unit test cho nhánh timeout"}'
{ "success": true, "task": { "id": "<taskId>", "columnId": "in-progress" }, "runId": "…" }
Quá 3 chu kỳ vẫn bị từ chối?

Hệ thống khoá tự chạy lại, task chuyển needs-human để người can thiệp tay. Lần rework thứ 4 trả đúng 400 {"error": "Task has exceeded maximum rework attempts (3). Escalated to human engineer.", "reviewState": "needs-human"}. Lúc này làm tay trong worktree, commit, rồi approve lại trên UI.

Xung đột merge — auto-rework đúng 1 lần​

Bối cảnh: hai task song song sửa cùng file; task A merge trước; khi approve task B, git báo conflict.

  1. Bảo vệ repo gốc trước tiên: merge fail → git merge --abort ngay (repo gốc luôn sạch, lock được nhả). Task sang merge-conflict, API trả 409 có cấu trúc (không phải 500):
{ "error": "<thông-báo-git>", "conflict": true, "reviewState": "merge-conflict" }
  1. Dò xung đột cách ly: trong task.worktreePath, merge thử baseBranch (rơi về main) vào nhánh task, lấy danh sách file conflict (git diff --name-only --diff-filter=U), rồi abort — không chiếm lock repo gốc nên không chặn task khác.
  2. Auto-rework đúng 1 lần: ghi hướng dẫn vào .board/history.md, gọi lại rework với kind='auto_conflict_resolution' trên cùng worktree (ghi chú liệt kê đúng file conflict).
  3. Agent gỡ xong → merge lần 2 → done. Agent thất bại, hoặc đây đã là lần auto-conflict thứ 2 (Auto merge conflict resolution already attempted) → needs-human, giao cho người.
Task không dùng worktree (useWorktree=false)?

Dừng ngay ở needs-human, không auto-rework — không có nơi cách ly để thử. Xử lý tay:

docker exec -it agentjira_server sh -c 'cd <worktreePath> && git status'

Gỡ conflict, commit, rồi approve lại trên UI.

Rollback Wiki & nhánh tri thức​

  1. Rollback trang Wiki (POST /api/wiki/pages/:slug/revisions/:version/rollback?projectId=…): cần Board admin và human thật (cùng cổng wiki:approve với duyệt draft) — rollback tạo version mới, không ghi đè lịch sử. Thiếu projectId → 400 projectId is required to roll back a wiki page; version sai → 400 version must be a positive integer.
  2. Member/agent gọi rollback → 403 ngay tại cổng Board (thiếu admin hoặc không phải human).
  3. Vượt qua cổng Board nhưng Arkon từ chối quyền → 502 kèm detail (Failed to roll back page: …): đó là cổng Arkon, liên hệ owner Space / sysadmin kiểm tra department và token.
  4. Merge / close nhánh Wiki (POST /api/wiki/branches/:id/merge · .../close) cũng cần admin + human — merge là duyệt mọi draft trong nhánh trong 1 transaction (thiếu projectId → 400 projectId is required to act on a wiki branch; nhánh của Space khác → 403 Branch does not belong to this Space; kẹt conflict giữa đường → 409 Merge blocked by a conflict: …, giữ nguyên để bạn xử lý).
curl -X POST 'http://<host>/api/wiki/pages/<slug>/revisions/2/rollback?projectId=<spaceId>'
curl -X POST 'http://<host>/api/wiki/branches/<branchId>/merge?projectId=<spaceId>' \
  -H 'Content-Type: application/json' -d '{"note": "Đã đọc hết draft trong nhánh"}'

Gặp lỗi? Xem Xử lý sự cố.

Đi tiếp: Duyệt & approve · Pentest Human Gate · Xử lý sự cố.

Cập nhật lần cuối vào