Zero CLI: các lệnh check, run, build, test, fix và explain

CLI mang lại cho bạn những gì

Tệp thực thi zero là toàn bộ bộ công cụ phát triển. Không có trình quản lý package, công cụ định dạng, linter hay trình chạy kiểm thử riêng: tất cả đều là lệnh con của zero. Nhờ vậy bề mặt luôn nhỏ gọn và dễ đoán, và đó chính là mục đích.

Danh sách ngắn các lệnh bạn sẽ dùng nhiều nhất:

Lệnh nào cũng nhận --json để xuất kết quả máy đọc được thay cho văn bản định dạng cho người đọc.

zero check

Lệnh làm việc chăm chỉ nhất. zero check chạy các bước kiểm tra tĩnh của trình biên dịch, gồm phân tích cú pháp, kiểm tra kiểu, suy luận capability và hiệu ứng, phát hiện import bị thiếu, rồi dừng trước bước sinh code. Lệnh này chạy nhanh, điều rất quan trọng vì agent và trình soạn thảo gọi nó liên tục.

zero check hello.0

Kết quả sạch (không in gì, mã thoát 0) nghĩa là tệp hợp lệ. Theo mặc định, lỗi được in ra dưới dạng văn bản cho người đọc. Thêm --json và bạn nhận được dạng có cấu trúc mà agent sử dụng:

zero check hello.0 --json

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

Cấu trúc của chẩn đoán được mô tả đầy đủ trong bài Chẩn đoán JSON. Để ý trường code ổn định: NAM003 luôn nghĩa là "unknown identifier" (định danh không xác định), bất kể phiên bản trình biên dịch.

Bạn cũng có thể trỏ check tới một thư mục package thay vì một tệp đơn lẻ:

zero check ./my-package

Lệnh này đọc zero.json, duyệt cây mã nguồn và báo cáo mọi vấn đề trên mọi target.

zero run

run biên dịch và thực thi trong một bước. Phù hợp nhất khi bạn đang thử nghiệm liên tục với một chương trình nhỏ và không cần tạo tệp thực thi trên đĩa.

zero run hello.0

Tương đương với chạy zero build rồi gọi tệp thực thi vừa tạo, chỉ khác là sản phẩm đầu ra bị bỏ đi. Stdout của chương trình được chuyển tiếp tới stdout của terminal: các lời gọi world.out.write của chương trình hiện ra trên màn hình của bạn.

Nếu chương trình cần đối số, hãy truyền chúng sau --:

zero run greet.0 -- Alice

Runtime cho chương trình truy cập các đối số đó qua chính capability World dùng cho I/O.

zero build

Khi bạn cần một sản phẩm đầu ra, hãy dùng build:

zero build hello.0

Trình biên dịch tạo ra một tệp thực thi native cạnh tệp mã nguồn (hoặc trong thư mục build của package nếu bạn đang làm việc trong một package). Bạn có thể chạy nó như mọi chương trình khác: không cần runtime riêng vì tệp thực thi Zero là độc lập.

Tệp thực thi Zero rất nhỏ. Mục tiêu thiết kế của dự án là tệp thực thi dưới 10 KB cho các chương trình đơn giản, đạt được bằng cách bỏ qua bộ công cụ LLVM và trực tiếp sinh ra các đường code gọn nhẹ.

zero test

Chạy các target kiểm thử của một package:

zero test

Các bài kiểm thử nằm cùng mã nguồn trong src/, được khai báo là target kiểm thử trong zero.json của package. Trình chạy tìm chúng, thực thi từng cái và báo đạt hay không đạt. Với --json, đầu ra có cấu trúc theo từng bài kiểm thử (tên, trạng thái, thời gian chạy, các chẩn đoán thu được) cho agent và công cụ CI.

Bài Package trong Zero trình bày cách khai báo target kiểm thử trong zero.json.

zero fix

fix dùng siêu dữ liệu sửa lỗi mà check --json tạo ra. Lệnh này có hai chế độ:

zero fix --plan --json   # show the structured plan, don't apply
zero fix                 # apply the plan in place

Một kế hoạch trông đại khái như sau (cấu trúc chỉ mang tính minh họa):

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

Ý tưởng là agent lấy kế hoạch về, quyết định có tin tưởng nó không, rồi áp dụng trực tiếp hoặc chuyển nó cho một bước suy luận cấp cao hơn. Kế hoạch là dữ liệu; agent không phải diễn giải văn bản để hành động.

zero explain

explain là phần văn bản của hệ thống chẩn đoán:

zero explain NAM003

Lệnh này in ra lời giải thích dễ đọc cho mã lỗi: ý nghĩa của nó, vì sao trình biên dịch báo nó, và các cách sửa thường gặp trông ra sao. Hữu ích khi:

• Con người đang gỡ lỗi và muốn câu trả lời dài hơn thông báo ngắn gọn.
• Agent gặp một mã chẩn đoán không có trong dữ liệu huấn luyện và muốn thêm ngữ cảnh.

Bản thân mã lỗi ổn định qua các phiên bản trình biên dịch, nên các lời giải thích đã lưu lại vẫn còn đúng.

zero new

Tạo khung cho một package mới:

zero new cli hello

Lệnh này tạo thư mục hello/ với tệp manifest zero.json và một tệp khởi đầu src/main.0. Đối số đầu tiên (ở đây là cli) chọn một mẫu, trong trường hợp này là một ứng dụng dòng lệnh thực thi được. Bài Package trong Zero giải thích chi tiết cấu trúc thư mục.

Thói quen dùng --json

Gần như lệnh nào cũng hỗ trợ --json. Nếu bạn đang xây dựng công cụ, bộ khung cho agent hay pipeline CI quanh Zero, hãy mặc định dùng dạng JSON. Dạng này:

• Ổn định. Schema có phiên bản và nhóm phát triển coi nó là một hợp đồng.
• Đầy đủ. Bạn nhận được các trường không có trong đầu ra cho người đọc (vị trí chính xác, ID kế hoạch sửa lỗi, dữ liệu đồ thị phụ thuộc).
• Dễ phân tích. Không cần dùng regex trên câu chữ tiếng Anh để lấy ra số dòng.

Với con người, hãy bỏ --json: văn bản đã định dạng mới là thứ bạn muốn thấy trong terminal.

Các lệnh hữu ích khác

Vài lệnh ít dùng hơn nhưng đáng biết:

• 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 agent muốn suy luận về các nơi gọi.
• 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. Hữu ích khi bạn quan tâm đến dung lượng tệp thực thi (một mục tiêu thiết kế của Zero).
• zero --version: in ra phiên bản bộ công cụ. Hãy ghi lại phiên bản này ở đâu đó nếu bạn làm việc theo nhóm: Zero đang ở giai đoạn trước 1.0 và các thay đổi phá vỡ tương thích vẫn xảy ra.

Tiếp theo: package trong Zero

Một tệp .0 đơn lẻ là đủ cho hello-world. Dự án thực tế dùng package với tệp manifest zero.json và thư mục src/. Bài Package trong Zero hướng dẫn cách tạo khung một package và giải thích từng trường.