Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

aggrega explain

Giải thích điều kiện dừng mà một mã chỉ định

Cú pháp

aggrega explain <code>

Mô tả

Explain the halting condition a code names.
A halting diagnostic opens with the category the failure is attributable to and the condition's short code — the letter E and four digits, as in [CATALOG_ERROR E0209]. That short code is the one to pass here; it is fixed once a condition is published, so a code quoted out of an old report still names the same condition.
aggrega explain E0209
The descriptive code is accepted too — the hyphenated one naming the condition in words, which a structured diagnostic carries as a field of its own. A condition's two codes name the same condition and reach different readers, so either is a code you may be holding, and the condition above is registered under recipe-values-mapping-requires-source:
aggrega explain recipe-values-mapping-requires-source
Every condition is declared inside this binary, so the identifiers and the sentence are reported without a network or a cache. The published reference supplies the walk-through of the authoring fix for every condition, and nothing else is resolved against it. It is read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version — kept in the cache every project on this machine shares, acquired on first use when that cache holds no copy this workspace's signature check admits. Where it cannot be acquired, the condition is still reported and the reason the walk-through is missing is stated.
A number that named a condition and no longer does is reported as retired, with what it named, so a code quoted from an old report is never answered with a different condition.

Chức năng

Một bản build bị dừng sẽ in ra một phần đầu trong ngoặc vuông, nêu tên danh mục mà lỗi được quy về và mã ngắn của điều kiện — chữ E và bốn chữ số:

[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...

aggrega explain E0209 chuyển mã đó thành điều kiện mà nó chỉ định và phần hướng dẫn từng bước cách sửa khi soạn thảo:

Terminal window
aggrega explain E0209

Câu trả lời mở đầu bằng cả hai định danh của điều kiện và câu cố định mà các chẩn đoán của nó bắt đầu, sau đó tái hiện mục giải thích nguyên nhân gây ra điều kiện và những gì cần thay đổi — chính là mục được công bố trong fatal-halts.md.

Mã cần truyền vào

Lệnh chấp nhận bất kỳ mã nào trong hai mã của điều kiện, vì mỗi mã đến với bạn qua một bề mặt khác nhau.

Mã ngắn là mã mà terminal hiển thị cho bạn, và là mã nên dùng khi tất cả những gì bạn có là đầu ra được in. Một số chỉ được cấp một lần rồi cố định, nên một mã ngắn bạn dán vào báo cáo từ một năm trước vẫn chỉ định đúng điều kiện mà nó chỉ định khi đó.

Mã mô tả là mã có dấu gạch nối mà một chẩn đoán có cấu trúc mang dưới dạng một trường riêng, và là mã mà chương trình dùng để rẽ nhánh. Nó gọi tên điều kiện bằng lời và không mang tiền tố, nên vẫn cố định ngay cả khi trình biên dịch được tổ chức lại xung quanh nó. Nếu đó là mã bạn đang có, hãy truyền mã đó — điều kiện ở trên được đăng ký dưới recipe-values-mapping-requires-source:

Terminal window
aggrega explain recipe-values-mapping-requires-source

Hai mã của một điều kiện chỉ định cùng một điều kiện, nên cả hai cách viết đều cho câu trả lời giống hệt nhau. Mã ngắn được so khớp không phân biệt chữ hoa chữ thường, vì đó là giá trị bạn đọc trên màn hình rồi gõ lại.

sentinels.md giải thích ba định danh mà một điều kiện mang và khi nào nên dùng từng định danh.

Câu trả lời đến từ đâu

Mọi điều kiện mà tệp nhị phân này khai báo đều được trả lời từ tệp nhị phân. Hai mã của nó và câu mà các chẩn đoán của nó mở đầu được khai báo bên trong trình biên dịch, nên phần đó không cần mạng, không cần bộ nhớ đệm và không cần cấu hình.

Một mã mà tệp nhị phân này không khai báo sẽ được tra cứu trong tài liệu tham khảo đã xuất bản. Một plugin báo cáo việc dừng bằng cách chọn một điều kiện mà trình biên dịch khai báo, nên không có điều kiện nào được khai báo ở nơi khác. Tài liệu tham khảo đã xuất bản, sentinels.md, liệt kê mọi điều kiện mà sản phẩm khai báo, và nó có thể đã được xuất bản cho một phiên bản khác với tệp nhị phân bạn đang chạy — nên một mã được trích từ báo cáo tạo bằng một bản phát hành mới hơn hoặc cũ hơn vẫn có thể được phân giải ở đó.

Phần hướng dẫn từng bước cũng là tài liệu đã công bố, được đọc từ fatal-halts.md. Cả hai trang đều đến từ gói tài liệu, được lưu một lần trên mỗi máy trong bộ nhớ đệm mà mọi dự án Aggrega dùng chung, mỗi registry và phiên bản một bản — xem aggrega cache. Gói được đọc là gói đã công bố cho phiên bản aggrega bạn đang chạy; nếu không có gói nào được công bố cho phiên bản đó, thì đó là gói mới nhất được công bố cho một bản phát hành trước — cùng lựa chọn mà aggrega scaffold --example đưa ra, nên hai lệnh này không bao giờ đọc tài liệu khác nhau. Một mã không có trong tài liệu tham khảo của một bản phát hành trước có thể chỉ một điều kiện được khai báo sau đó, nên nó bị từ chối như một mã không xác định được chứ không phải như một mã không chỉ điều kiện nào, và lời từ chối cho biết tài liệu tham khảo của phiên bản nào đã được đọc. Workspace của bạn quyết định gói đến từ registry nào, tức registry mặc định của nó, và liệu một bản đã có trên máy có được phép đọc hay không: trước khi một trang được phục vụ, các chữ ký lưu bên cạnh bản sao được xác minh lại theo cơ chế kiểm tra chữ ký riêng của workspace cho registry đó, chính là cơ chế kiểm tra mà một lần tải gói phải tuân theo. Việc kiểm tra này cũng chạy khi ngoại tuyến. Nếu nó ghim một khóa hoặc một gốc tin cậy, nó chỉ đọc những thứ đó; nếu nó không ghim cái nào, như cơ chế kiểm tra tích hợp sẵn của hub chính thức, nó xác minh dựa trên gốc tin cậy công khai của Sigstore, thứ mà một workspace ngoại tuyến không thể tải về — nên khi ngoại tuyến, nó xác minh dựa trên gốc tin cậy mà một lần tải trực tuyến trước đó trên máy này đã để lại trong .sigstore ở thư mục home của bạn, và không tải gì cả. Khi máy không có bản sao nào, hoặc không có bản nào được cơ chế kiểm tra của bạn chấp nhận, lệnh sẽ lấy một bản theo cơ chế kiểm tra đó, một lần, và sau đó đọc từ bộ nhớ đệm. Cùng bản sao đó phục vụ tài liệu mà trợ lý đọc qua aggrega mcp và các giải thích mà trình soạn thảo hiển thị qua aggrega serve.

Có ba kiểu câu trả lời đáng để nhận biết, vì mỗi kiểu yêu cầu bạn một việc khác nhau.

Một điều kiện chưa có mục. Các mã và câu vẫn được báo cáo, kèm một ghi chú cho biết trang điều kiện dừng chưa có hướng dẫn từng bước cho điều kiện đó. Mọi điều kiện vẫn được liệt kê trong sentinels.md.

Không có tài liệu. Với một điều kiện mà trình biên dịch khai báo, các mã và câu vẫn được báo cáo, kèm một ghi chú nêu tên gói và phiên bản không đọc được. Với một mã mà tệp nhị phân này không khai báo thì không còn gì để trả lời, nên mã bị từ chối — và lời từ chối cho biết không đọc được tài liệu tham khảo, vì thiếu nó thì một mã từ phiên bản khác không thể phân biệt được với lỗi gõ, và để ngỏ cả hai cách khắc phục: sửa mã, hoặc lấy tài liệu. Nguyên nhân thường gặp là một workspace được ghim ở chế độ ngoại tuyến, hoặc một workspace chưa từng kết nối tới registry của nó. Khi máy có một bản sao mà cơ chế kiểm tra chữ ký của workspace không chấp nhận — một bản mà dự án khác đã tải theo thiết lập lỏng hơn, hoặc một bản mà workspace ngoại tuyến không thể kiểm tra vì máy này chưa từng tải gốc tin cậy công khai mà cơ chế kiểm tra của nó dựa vào — ghi chú sẽ cho biết bản sao đã bị từ chối chứ không phải bị thiếu, và lý do. Khi không có gói nào được công bố cho phiên bản của bạn và gói mới nhất trước đó ở định dạng mà phiên bản aggrega này không còn đọc được — chẳng hạn một bản ứng viên phát hành được chạy trước khi tài liệu của chính nó được công bố — ghi chú nêu cả hai điều trong một câu:

hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the walk-through is not shown here; every condition, including the ones a provider declares, is published at aggrega-docs/language-reference/errors/sentinels.md, and the walk-through of each authoring fix at aggrega-docs/language-reference/errors/fatal-halts.md

Một số đã ngừng sử dụng. Một số từng chỉ định một điều kiện nhưng nay không còn được trả lời là đã ngừng sử dụng, kèm điều nó từng chỉ định, thay vì như một mã chưa từng tồn tại — và nó không bao giờ được trả lời bằng một điều kiện khác, vì một số đã ngừng sử dụng sẽ không được cấp lại.

Ví dụ

Giải thích một mã lấy trực tiếp từ một bản build thất bại:

Terminal window
aggrega build --release release.yaml || aggrega explain E0209

Giải thích một mã mà chương trình đã so khớp:

Terminal window
aggrega explain plugin-value-not-representable

Cùng câu trả lời từ một trợ lý

Một trợ lý AI được kết nối qua aggrega mcp truy cập cùng phần giải thích này qua công cụ explain-error. Hãy đưa cho nó văn bản chẩn đoán thay vì chỉ một mã đơn lẻ — trợ lý nắm giữ những gì bản build đã in ra — và khi văn bản đó mở đầu bằng một mã ngắn, câu trả lời mang điều kiện, câu mà các chẩn đoán của nó mở đầu, và phần hướng dẫn từng bước đã công bố về cách sửa khi soạn thảo, được ghép theo cùng cách như câu trả lời ở trên. Nó cũng mang mã mô tả, để trợ lý có thể rẽ nhánh dựa trên mã đó thay vì dựa trên câu chữ của thông báo, và địa chỉ nơi điều kiện được công bố.

Mọi điều các phần trên nói về việc thiếu hướng dẫn từng bước cũng đúng ở đó: một điều kiện mà trang không có mục nào, và một workspace không đọc được tài liệu, đều khiến điều kiện được trả lời kèm một ghi chú cho biết đó là trường hợp nào. Một số đã ngừng sử dụng cũng được trả lời là đã ngừng sử dụng ở đó, kèm điều nó từng chỉ định, để một trợ lý nhận được chẩn đoán cũ biết rằng số đó không còn được dùng thay vì bị dẫn tới một trang về thứ khác. Bề mặt trợ lý lấy tài liệu một lần khi phiên mở ra, nên mỗi lần giải thích đều đọc những gì đã có sẵn trong bộ nhớ đệm.

Daemon trả lời cùng câu hỏi đó cho trình soạn thảo, dựa trên một mã thay vì một chẩn đoán. Cả ba là một phần giải thích duy nhất trong ba cách thể hiện, chứ không phải ba câu trả lời tình cờ trùng khớp.