Chẩn đoán JSON trong Zero: lỗi biên dịch có cấu trúc cho agent

Tính năng nổi bật nhất

Tính năng đặc trưng nhất của Zero không phải là một phần cú pháp. Đó là cách trình biên dịch giao tiếp với bất kỳ ai, hay bất kỳ thứ gì, đang đọc đầu ra của nó.

Chạy một chương trình bị lỗi qua zero check --json và bạn nhận được một luồng dữ liệu mà agent có thể đọc trực tiếp:

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

Đó là một khối nhỏ nhưng chứa nhiều thông tin. Cùng mổ xẻ từng trường và các lựa chọn thiết kế phía sau.

Cấu tạo của một chẩn đoán

Một chẩn đoán là một đối tượng có cấu trúc mô tả một vấn đề trong mã nguồn. Các trường chuẩn:

• code: một định danh ổn định (ví dụ NAM003). Luôn mang cùng một nghĩa, bất kể phiên bản trình biên dịch.
• message: mô tả dễ đọc cho con người. Cách diễn đạt có thể đổi giữa các phiên bản; ý nghĩa được cố định bởi code, không phải bởi thông báo.
• line (và các trường vị trí khác): nơi xảy ra vấn đề.
• repair: metadata có cấu trúc tùy chọn, mô tả một bản sửa mà trình biên dịch cho rằng sẽ giải quyết được chẩn đoán. Hình dạng của trường này cũng được ghi trong tài liệu và ổn định.

Cấu trúc cấp cao nhất gồm một boolean ok cho toàn bộ lần chạy và một mảng diagnostics; kể cả khi lần chạy thành công, mảng đó vẫn có thể chứa cảnh báo hoặc ghi chú.

Mã lỗi ổn định

Cam kết về code là phần dễ khiến bạn bất ngờ nhất. NAM003 hôm nay nghĩa là "định danh không xác định". NAM003 tháng sau và năm sau cũng sẽ nghĩa là "định danh không xác định". Agent (và con người) có thể dựa vào điều đó.

Điều này quan trọng vì các mô hình ngôn ngữ và công cụ có xu hướng lưu đệm hoặc ghi nhớ những gì chúng đã thấy. Nếu ý nghĩa của NAM003 thay đổi sau mỗi bản phát hành, mọi lần tra cứu đã lưu đệm sẽ không còn an toàn. Cố định mã giúp giữ:

• Dữ liệu huấn luyện của agent còn đúng qua các phiên bản.
• Tài liệu có thể tra cứu theo mã.
• Các pipeline công cụ ổn định.

message dành cho con người có thể thoải mái thay đổi khi nhóm phát triển cải thiện cách diễn đạt. code mới là định danh gánh vác mọi thứ.

Metadata sửa lỗi

Trường repair, khi có mặt, cho bên sử dụng biết loại bản sửa mà trình biên dịch cho rằng sẽ hiệu quả:

{
    "code": "NAM003",
    "message": "unknown identifier",
    "line": 3,
    "repair": { "id": "declare-missing-symbol" }
}

declare-missing-symbol ở đây là loại sửa lỗi, tức ý định ở mức cao. Để lấy các chỉnh sửa cụ thể, gọi zero fix --plan --json. Lệnh đó trả về một kế hoạch gồm đường dẫn tệp, các vùng byte cần sửa và văn bản mới:

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

(Tên trường và hình dạng chính xác có thể khác trong phiên bản bộ công cụ của bạn; nguyên tắc là "dữ liệu có cấu trúc, không phải văn xuôi".)

Agent đọc kế hoạch có vài lựa chọn:

1. Áp dụng các chỉnh sửa nguyên trạng.
2. Áp dụng các chỉnh sửa có điều chỉnh.
3. Từ chối kế hoạch và tìm cách sửa khác.

Trong mọi trường hợp, agent đang làm việc với dữ liệu có cấu trúc thay vì cố hiểu một gợi ý bằng tiếng Anh. Đó là khác biệt giữa kế hoạch sửa lỗi và những gợi ý kiểu "có phải ý bạn là ...?" trong một trình biên dịch thông thường.

Agent thực sự dùng điều này thế nào

Một vòng lặp đầu cuối đơn giản hóa mà agent có thể chạy:

1. Sinh hoặc sửa một tệp Zero.
2. Chạy zero check --json trên tệp đó.
3. Nếu kết quả là { "ok": true, ... }, chuyển sang việc tiếp theo.
4. Nếu không, với mỗi chẩn đoán:
   • Tra code để hiểu điều gì sai (bằng zero explain hoặc một bảng tra cục bộ).
   • Nếu có repair được đề xuất và trông an toàn, gọi zero fix --plan --json để lấy các chỉnh sửa.
   • Áp dụng (hoặc mô phỏng) các chỉnh sửa.
5. Quay lại bước 2.

So với việc làm việc dựa trên một thông báo văn xuôi: agent phải phân tích tiếng Anh, trích ra số dòng có khả năng đúng, đoán loại bản sửa và suy ra chính xác văn bản cần chèn hoặc thay thế. Bước nào cũng mơ hồ. Con đường JSON thay mỗi bước bằng một lần tra cứu theo một schema đã được ghi trong tài liệu.

Không chỉ có lỗi: đồ thị và kích thước

--json không chỉ dành cho chẩn đoán. Các lệnh khác cũng cung cấp dữ liệu có cấu trúc theo cùng cách:

• zero graph --json: xuất đồ thị phụ thuộc của một package dưới dạng dữ liệu có cấu trúc. Hữu ích để hiểu cái gì phụ thuộc vào cái gì, và cho các agent muốn suy luận về các chỗ gọi trước khi chạm vào chúng.
• zero size --json: báo cáo kích thước trên đĩa của các sản phẩm biên dịch, chia theo target. Đây là cùng dữ liệu con người thấy trong zero size, chỉ là có thể phân tích được.

Những cấu trúc này là một phần của thiết kế: bất cứ khi nào trình biên dịch có dữ liệu hữu ích, dữ liệu đó đều có sẵn dưới dạng JSON để công cụ dùng mà không cần cào màn hình.

Schema trông như thế nào

Tên trường và hình dạng chính xác được ghi trong repository của Zero và sẽ còn thay đổi khi dự án vẫn ở giai đoạn trước 1.0. Các nhóm thông tin bạn có thể mong đợi:

• Metadata của lần chạy: ok, version, thời gian.
• Chẩn đoán: code, message, vị trí (tệp/dòng/cột/vùng byte), mức độ (lỗi/cảnh báo/ghi chú), repair tùy chọn.
• Kế hoạch sửa lỗi: khi được lấy về, là danh sách chỉnh sửa có cấu trúc.

Nếu bạn xây dựng công cụ dựa trên bề mặt này, cách an toàn là đọc các trường bạn đã biết, bỏ qua các trường lạ một cách nhẹ nhàng, và dựa vào code cho các quyết định về hành vi.

Đi nhanh từ đầu đến cuối

Giả sử mã nguồn của bạn dùng một định danh chưa được khai báo:

pub fun main(world: World) -> Void raises {
    check world.out.write(answer())   // 'answer' is not defined anywhere
}

Chạy zero check --json cho ra kết quả kiểu như:

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier 'answer'",
            "line": 2,
            "column": 27,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

zero fix --plan --json trả về chỉnh sửa:

{
    "diagnostic": { "code": "NAM003", "line": 2 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

zero fix (không có --plan) áp dụng chỉnh sửa trực tiếp vào tệp, sau đó zero check trả về ok: true. Mỗi bước là một giao dịch riêng lẻ, có thể kiểm tra được.

Vì sao điều này quan trọng không chỉ với agent

Cùng những tính chất đó, đầu ra có cấu trúc, mã ổn định, kế hoạch sửa lỗi, cũng giúp dễ dàng hơn cho:

• Editor và IDE. Dấu gạch chân và gợi ý sửa nhanh hoạt động dựa trên ID của repair thay vì văn bản đã phân tích.
• Pipeline CI. Các lỗi được ghi log kèm code để dễ grep và dựng dashboard.
• Công cụ code-mod. Sửa hàng loạt nhắm vào một mã, không phải một regex trên thông báo.

Hệ thống được thiết kế với agent làm trọng tâm, nhưng các công cụ dành cho con người cũng nhận được cùng lợi ích.

Tiếp theo: thiết kế agent-first

Hệ thống chẩn đoán là ví dụ cụ thể nhất cho triết lý agent-first của Zero. Tài liệu tiếp theo, thiết kế agent-first, lùi lại để nhìn các nguyên tắc nền tảng: bề mặt nhỏ, công cụ tất định, hiệu ứng tường minh, và cách mỗi nguyên tắc chứng minh giá trị của mình.