Skip to Content

Đọc lỗi check

Mỗi dòng lỗi của check có lớp, mã luật, file và dòng; trang này giải thích các lỗi hay gặp và cách đưa agent ra khỏi vòng sửa lặp.

Phần lớn thời gian agent tự đọc và tự sửa. Bạn đọc kết quả khi deploy bị từ chối, hoặc khi agent sửa một lỗi tới lần thứ ba mà vẫn còn.

Cấu trúc một dòng

- [gate:code.invalid-api-method] app/orders/page.tsx:31 api.orders.stats() is not in the generated client … │ │ │ │ └ thông báo, luôn kèm cách sửa │ │ │ └ dòng │ │ └ file │ └ mã luật └ lớp: syntax · gate · contract · types
  • Errors chặn deploy. Warnings không chặn, nhưng chỉ ra chỗ app sẽ chậm, xấu hoặc khó bảo trì.
  • Thông báo viết bằng tiếng Anh vì người đọc chính là agent. Mã luật tra ở Quy tắc check.

Lỗi hay gặp

  • syntax: thiếu ngoặc, JSX chưa đóng. Sửa lỗi này trước, vì khi còn lỗi cú pháp phần lớn luật khác tạm dừng.
  • code.invalid-api-method: trang gọi api.<tài nguyên>.<hàm>() không có trong client. Thông báo liệt kê các hàm hợp lệ. Hoặc gọi đúng tên, hoặc viết handler còn thiếu.
  • contract “FE calls … but no matching BE route”: trang gọi một đường dẫn chưa có handler. Thêm file handler đúng đường dẫn.
  • code.antd-v6-no-visible-prop: visible trên Modal, Drawer của antd v6 bị bỏ qua, lớp phủ không bao giờ mở. Đổi thành open.
  • code.no-css-import, code.no-tailwind-import, code.no-mui: agent dùng thứ ngoài stack. Bảo agent dùng antd và class Tailwind trong className.
  • code.backend-package-not-allowed: package server không có trong danh sách cho phép. Thông báo liệt kê package được phép; thường manh/* đã có sẵn việc đó.
  • access.unknown-role: access nêu một vai không có trong app/auth.ts. Sửa tên vai hoặc thêm vai vào roles.
  • code.no-async-transaction: db.transaction(async …). Kiểm hết rồi mới ghi, hoặc dùng callback đồng bộ.
  • types: lỗi TypeScript từ check({ typecheck: true }) hay khi deploy. Thường là handler trả kiểu khác với thứ trang dùng, hoặc thiếu import.

Khi agent sửa vòng vòng

Dấu hiệu: cùng một mã luật quay lại sau hai, ba lần ghi file, hoặc agent sửa một lỗi thì sinh lỗi khác ở chỗ cũ.

  1. Dán nguyên dòng lỗi cho agent và nói ý muốn bằng lời: “Trang này cần tổng đơn theo tháng. Viết handler app/orders/stats/get.ts, đừng gọi hàm khác.”
  2. Bảo agent đọc lại phần tài liệu liên quan qua framework_docs trước khi sửa tiếp.
  3. Lỗi nằm ở thứ agent viết từ đầu sai hướng (một thư viện ngoài stack, một cấu trúc file khác): bảo agent quay lại checkpoint gần nhất rồi làm lại phần đó.

Deploy bị từ chối

Deploy chạy đủ bốn lớp. Còn lỗi thì manh.run từ chối, trả danh sách lỗi, và app đang chạy giữ nguyên.

  • Lỗi ở ba lớp đầu không bỏ qua được. Phải sửa.
  • Chỉ lỗi kiểu mới bỏ qua được, bằng deploy({ force: true, reason }). Chỉ đồng ý khi bạn đã thử app trên bản chạy thử và thấy chạy đúng; ghi lý do thật vào reason.
  • Một cây file đã từng deploy thành công luôn deploy lại được, dù sau đó có thêm luật mới.

Kiểm thử sau deploy báo hỏng

Deploy xong, manh.run chạy bộ kiểm thử của app trên một bản sao có database riêng và trả kết quả trong tests. Bộ kiểm thử lấy từ spec/acceptance.json. App chưa có file này thì manh.run tự sinh vài phép thử cơ bản: mỗi vai mở được trang chủ, các màn hình khác mở được, mọi danh sách trả 200 hoặc 403 chứ không trả 500.

Một phép thử hỏng nghĩa là app chưa làm đúng điều nghiệp vụ cần. Bảo agent sửa app rồi deploy lại, đừng sửa phép thử cho qua.

Cần biết

  • Cảnh báo code.missing-frontend lúc đang làm phần dữ liệu và API là bình thường.
  • Cảnh báo hint.* chỉ ra tính năng có sẵn mà code đang tự viết lại (thông báo lỗi, giờ Việt Nam, xuất Excel). Bảo agent dùng tính năng có sẵn.

Bước tiếp theo

Cập nhật