aggrega explain
코드가 가리키는 중단 조건 설명
개요
aggrega explain <code>설명
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.동작
중단된 빌드는 실패의 원인이 되는 범주와 해당 조건의 짧은 코드(문자 E와 네 자리 숫자)를 대괄호로 묶은 머리말로 출력합니다:
[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...aggrega explain E0209는 그 코드를 코드가 가리키는 조건과 작성 측 수정 방법의 단계별 안내로 바꿔 줍니다:
aggrega explain E0209응답은 조건의 두 식별자와 해당 진단이 시작하는 고정 문장으로 시작하며, 이어서 조건의 원인과 수정할 내용을 설명하는 항목을 그대로 보여 줍니다. 이는 fatal-halts.md에 게시된 것과 같은 항목입니다.
전달할 코드
조건의 두 코드 중 어느 것이든 받아들입니다. 두 코드는 각각 다른 경로로 전달되기 때문입니다.
짧은 코드는 터미널에 표시되는 코드이며, 출력된 내용만 가지고 있을 때 사용합니다. 번호는 한 번 부여된 뒤 고정되므로, 1년 전에 보고서에 붙여 넣은 짧은 코드도 그때와 같은 조건을 가리킵니다.
설명형 코드는 구조화된 진단이 별도 필드로 담고 있는 하이픈으로 연결된 코드이며, 프로그램이 분기 기준으로 사용합니다. 조건을 단어로 나타내고 접두사가 없으므로, 컴파일러의 구조가 바뀌어도 고정된 채로 유지됩니다. 이 코드를 가지고 있다면 대신 이 코드를 전달하십시오. 위의 조건은 recipe-values-mapping-requires-source로 등록되어 있습니다:
aggrega explain recipe-values-mapping-requires-source조건의 두 코드는 같은 조건을 가리키므로 어느 표기로든 동일한 응답을 얻습니다. 짧은 코드는 화면에서 읽고 다시 입력하는 값이므로 대소문자를 구분하지 않고 일치시킵니다.
sentinels.md에서 조건이 갖는 세 가지 식별자와 각각을 언제 사용하는지 설명합니다.
응답의 출처
이 바이너리가 선언하는 모든 조건은 바이너리에서 응답합니다. 조건의 두 코드와 진단이 시작하는 문장은 컴파일러 안에 선언되어 있으므로, 이 부분에는 네트워크, 캐시, 설정이 필요하지 않습니다.
이 바이너리가 선언하지 않는 코드는 게시된 참조 문서에서 조회합니다. 플러그인은 컴파일러가 선언하는 조건을 선택하여 중단을 보고하므로, 다른 곳에서 선언되는 조건은 없습니다. 게시된 참조 문서인 sentinels.md는 제품이 선언하는 모든 조건을 나열하며, 실행 중인 바이너리와 다른 버전용으로 게시되었을 수 있습니다. 따라서 더 새롭거나 오래된 릴리스로 작성된 보고서에서 인용한 코드도 그곳에서 해석될 수 있습니다.
단계별 안내 역시 게시된 문서이며, fatal-halts.md에서 읽어 옵니다. 두 페이지 모두 문서 번들에서 가져오며, 이 번들은 모든 Aggrega 프로젝트가 공유하는 캐시에 머신당 한 번, 레지스트리와 버전마다 하나의 사본으로 보관됩니다. aggrega cache를 참고하십시오. 읽는 번들은 실행 중인 aggrega 버전용으로 게시된 번들입니다. 해당 버전용으로 게시된 번들이 없으면 이전 버전용으로 게시된 번들 중 가장 최신 번들을 읽습니다. 이는 aggrega scaffold --example이 하는 것과 같은 선택이므로, 두 명령이 서로 다른 문서를 읽는 일은 없습니다. 이전 버전의 참조 문서에 없는 코드는 그 이후에 선언된 조건을 가리킬 수 있으므로, 아무것도 가리키지 않는 코드가 아니라 판별할 수 없는 코드로 거부되며, 거부 메시지는 어느 버전의 참조 문서를 읽었는지 알려 줍니다. 번들을 가져올 레지스트리(워크스페이스의 기본 레지스트리)는 워크스페이스가 결정하며, 머신에 이미 있는 사본을 읽어도 되는지도 워크스페이스가 결정합니다. 페이지를 제공하기 전에, 사본 옆에 보관된 서명을 해당 레지스트리에 대한 워크스페이스 자체의 서명 검사로 다시 검증합니다. 이는 번들을 가져올 때 적용되는 것과 같은 검사입니다. 이 검사는 오프라인에서도 실행됩니다. 검사가 키나 신뢰 루트를 고정하는 경우 그것만 읽고, 공식 허브의 기본 제공 검사처럼 둘 다 고정하지 않는 경우에는 공개 Sigstore 신뢰 루트를 기준으로 검증합니다. 오프라인 워크스페이스는 이 신뢰 루트를 가져올 수 없으므로, 오프라인에서는 이 머신에서 이전에 온라인으로 가져올 때 홈 디렉터리의 .sigstore 아래에 남겨 둔 신뢰 루트로 검증하며 아무것도 가져오지 않습니다. 머신에 사본이 없거나 검사를 통과하는 사본이 없으면, 명령은 해당 검사에 따라 사본을 한 번 받아 오고 이후에는 캐시에서 읽습니다. 같은 사본이 aggrega mcp를 통해 어시스턴트가 읽는 문서와 aggrega serve를 통해 편집기가 보여 주는 설명에도 사용됩니다.
다음 세 가지 응답은 각각 요구하는 조치가 다르므로 알아 둘 만합니다.
아직 항목이 없는 조건. 코드와 문장은 보고되며, 중단 조건 페이지에 해당 조건의 단계별 안내가 없다는 메모가 표시됩니다. 모든 조건은 여전히 sentinels.md에 나열되어 있습니다.
사용할 수 있는 문서가 없음. 컴파일러가 선언하는 조건이라면 코드와 문장은 여전히 보고되며, 읽을 수 없었던 번들과 버전을 알려 주는 메모가 표시됩니다. 이 바이너리가 선언하지 않는 코드라면 응답할 근거가 남아 있지 않으므로 코드가 거부되며, 거부 메시지는 참조 문서를 읽을 수 없었다고 알려 줍니다. 참조 문서 없이는 다른 버전의 코드를 오타와 구별할 수 없기 때문이며, 코드를 수정하거나 문서를 확보하는 두 가지 해결책을 모두 열어 둡니다. 일반적인 원인은 오프라인으로 고정된 워크스페이스이거나 레지스트리에 한 번도 연결된 적이 없는 워크스페이스입니다. 머신에 있는 사본을 워크스페이스의 서명 검사가 허용하지 않는 경우, 예를 들어 다른 프로젝트가 더 느슨한 설정으로 가져온 사본이거나, 검사가 기준으로 삼는 공개 신뢰 루트를 이 머신이 한 번도 가져온 적이 없어 오프라인 워크스페이스가 검사할 수 없는 사본이라면, 메모는 사본이 없는 것이 아니라 거부되었다는 사실과 그 이유를 알려 줍니다. 사용 중인 버전용으로 게시된 번들이 없고 그보다 이전의 최신 번들이 이 버전의 aggrega가 더 이상 읽지 않는 형식인 경우(예: 자체 문서가 게시되기 전에 실행하는 릴리스 후보), 메모는 두 가지를 한 문장으로 알려 줍니다:
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폐기된 번호. 한때 조건을 가리켰지만 더 이상 가리키지 않는 번호는 존재한 적 없는 코드가 아니라 폐기된 번호로, 과거에 가리키던 내용과 함께 응답됩니다. 또한 다른 조건으로 응답되는 일은 없습니다. 폐기된 번호는 다시 부여되지 않기 때문입니다.
예시
실패한 빌드에서 바로 가져온 코드 설명:
aggrega build --release release.yaml || aggrega explain E0209프로그램이 일치시킨 코드 설명:
aggrega explain plugin-value-not-representable어시스턴트에서 얻는 같은 응답
aggrega mcp로 연결된 AI 어시스턴트는 explain-error 도구를 통해 이와 같은 설명에 접근합니다. 코드만 전달하지 말고 진단 텍스트를 전달하십시오. 어시스턴트는 빌드가 출력한 내용을 가지고 있습니다. 그 텍스트가 짧은 코드로 시작하면, 응답에는 조건, 진단이 시작하는 문장, 작성 측 수정 방법에 대한 게시된 단계별 안내가 위의 응답과 같은 방식으로 구성되어 담깁니다. 또한 설명형 코드도 담기므로 어시스턴트는 메시지 문구 대신 이 코드를 기준으로 분기할 수 있으며, 조건이 게시된 주소도 함께 담깁니다.
앞의 섹션에서 단계별 안내가 없는 경우에 대해 설명한 내용은 여기에도 모두 적용됩니다. 페이지에 항목이 없는 조건이든, 문서를 읽을 수 없는 워크스페이스든, 조건은 응답되며 어느 경우였는지 알려 주는 메모가 함께 표시됩니다. 폐기된 번호 역시 여기서도 과거에 가리키던 내용과 함께 폐기된 번호로 응답되므로, 오래된 진단을 전달받은 어시스턴트는 다른 내용을 다루는 페이지로 안내되는 대신 그 번호가 더 이상 사용되지 않는다는 것을 알게 됩니다. 어시스턴트 경로는 세션이 열릴 때 문서를 한 번 가져오므로, 설명은 이미 캐시된 내용을 읽습니다.
데몬은 진단이 아닌 코드를 기준으로 편집기에 같은 질문의 응답을 제공합니다. 이 세 가지는 우연히 일치하는 세 개의 응답이 아니라, 하나의 설명을 세 가지 방식으로 표현한 것입니다.