콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

Aggrega Core (Plugin) 스키마

자동 생성된 레퍼런스입니다. 직접 편집하지 말고 게시된 JSON Schema에서 다시 생성하십시오.

스키마 ID: https://aggrega.ai/schemas/plugin-v1beta1.schema.json

Wasm 플러그인: OCI 레지스트리에 게시되고 metadata.pluginType(플러그인이 구현하는 소켓)과 접두사 없는 metadata.name으로 식별되는 WebAssembly 모듈로, 대상으로 하는 ABI 버전, 선택적인 서명 포인터, 선택적인 런타임 블록을 선언합니다. 엔티티와 그 .wasm은 metadata.version으로 태그가 지정된 하나의 OCI 매니페스트로 게시됩니다. 엔티티 YAML은 매니페스트의 config blob이 되고, .wasm은 인라인 레이어가 되며, 서명은 한 번만 이루어집니다. 식별자는 metadata.pluginType/metadata.name 좌표와 엔티티의 metadata.version입니다. .wasm 위치는 이 좌표와 구성된 레지스트리로부터 도출되며, 확인된 콘텐츠 다이제스트는 엔티티가 아니라 lockfile에 저장됩니다. lockfile은 다이제스트를 기록하고, 레지스트리별 신뢰 정책은 pull 시점에 아티팩트의 서명을 검증합니다. 컴파일러는 플러그인의 동작을 해석하지 않습니다. 컴파일러는 참조를 라우팅하고, WebAssembly 런타임이 바이트를 실행합니다.

Plugin 엔티티 작성에 관한 설명은 Plugin 작성 레퍼런스를 참조하십시오. 이 페이지는 해당 레퍼런스가 설명하는 구조적 스키마를 문서화합니다.

최상위 타입: object

속성

속성타입필수설명
apiVersionconst “aggrega.ai/v1beta1”예상수: "aggrega.ai/v1beta1"
kindconst “Plugin”예상수: "Plugin"
metadataobject예
specobject예플러그인이 대상으로 하는 ABI 버전, 선택적 서명 포인터, 선택적 runtime 블록입니다. 플러그인의 .wasm 위치는 플러그인의 식별자, 즉 metadata.pluginType(소켓)과 접두사 없는 metadata.name, 그리고 구성된 레지스트리에서 도출되며 spec에 담기지 않습니다.

추가 속성은 허용되지 않습니다.

plugin.metadata

속성타입필수설명
namestring예최소 1자 이상이어야 합니다.
versionstring예Plugin 엔티티의 엄격한 시맨틱 버저닝 버전입니다(예: 1.0.0). 패턴: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$.
pluginTypestring (enum)예이 플러그인이 구현하는 소켓 타입입니다. 플러그인은 런타임이 인식하는 플러그인 타입 분류에서 정확히 하나의 소켓 타입을 구현합니다: provider(IR 노드를 provider 고유 아티팩트로 렌더링), linter(작성된 콘텐츠를 검사하고 진단을 발생), pipeline-step(FeatureRecipe 또는 Recipe의 pipeline:에 있는 단계로, 렌더링된 문서 집합에 패치를 적용), governance(빌드 파이프라인 거버넌스 역할을 수행합니다. 토폴로지 구성 시 노드 레이블을 변환하거나, 정적 분석 시 IR 그래프에 대해 또는 렌더링 시 렌더링된 아티팩트에 대해 승인/거부 판정을 내립니다. 무엇을 내보낼 수 있는지는 종류가 아니라 연결된 역할이 정합니다), cli(운영자가 명령줄에서 호출하는 런타임 aggrega <cmd> 하위 명령을 제공합니다. 컴파일 타임 렌더 및 파이프라인 소켓과 구별되는 런타임 소켓입니다), parser(외부 소스 텍스트를 정규 구조 트리로 변환하여 소비자가 자체 언어 파서 없이 트리를 읽게 하며, 처리하는 형식을 parse:<format> 기능으로 알립니다), importer(외부 인프라 또는 에이전트 정의 소스를 Aggrega 작성 파일 초안으로 변환하며, 처리하는 형식을 import:<format> 기능으로 알립니다). 허용 값: "provider", "linter", "pipeline-step", "governance", "cli", "parser", "importer"
descriptionstring아니요이 엔티티가 무엇이며 무엇을 위한 것인지를, 사용 여부를 결정하려는 사람을 위해 작성합니다. 대상을 지칭하는 문장으로 시작한 뒤, 독자가 이를 선택하고 올바르게 사용하는 데 필요한 내용, 즉 이를 실행하는 빌드에 무엇을 기대하는지와 동작 방식에서 예상하기 어려운 점을 덧붙입니다. 보통 짧은 문단 하나 정도의 분량입니다.
maintainersobject[]아니요이 엔티티를 소유하는 메인테이너 목록입니다.
licensestring아니요이 엔티티가 기술하는 소프트웨어의 라이선스를 나타내는 SPDX 식별자로, MIT 또는 AGPL-3.0 등이 있습니다. 이 파일의 조건이 아니라 해당 소프트웨어의 조건을 기록합니다.
repositorystring아니요소스 파일이 있는 Git 저장소의 URL입니다.
homestring아니요이 엔티티의 홈페이지, 위키 또는 문서의 URL입니다.
keywordsstring[]아니요UI에서 쉽게 찾을 수 있도록 하는 설명 키워드 목록입니다.

추가 속성은 허용되지 않습니다.

plugin.metadata.maintainers[]
속성타입필수설명
namestring예
emailstring아니요
urlstring아니요

추가 속성은 허용되지 않습니다.

plugin.spec

플러그인이 대상으로 하는 ABI 버전, 선택적 서명 포인터, 선택적 runtime 블록입니다. 플러그인의 .wasm 위치는 플러그인의 식별자, 즉 metadata.pluginType(소켓)과 접두사 없는 metadata.name, 그리고 구성된 레지스트리에서 도출되며 spec에 담기지 않습니다.

속성타입필수설명
abiVersionstring (enum)예플러그인이 대상으로 하는 호스트/게스트 ABI 버전입니다. 허용되는 값은 v1beta1 하나뿐이며, 이 컴파일러가 더 이상 지원하지 않는 ABI 버전을 선언하는 Plugin은 거부되고, 플러그인을 다시 빌드할 대상 버전이 안내됩니다. 허용 값: "v1beta1"
signatureobject아니요플러그인에 첨부된 서명을 가리키는 선택적 설명용 포인터입니다. 이 블록은 문서 용도일 뿐입니다. 카탈로그 독자를 위해 서명의 위치와 생성 방식을 기록할 뿐, 그 자체로 플러그인을 차단하거나 허용하지 않습니다. 실제 검사는 pull 시 적용되는 레지스트리별 신뢰 정책입니다. 서명은 OCI referrer로 가져와 레지스트리의 신뢰된 ID 또는 고정된 키로 검증한 뒤 lockfile에 검증된 사실로 기록됩니다. 서명을 요구하는 레지스트리는 필요한 서명이 없거나 신뢰할 수 없거나 유효하지 않으면 pull을 중단합니다.
runtimeobject아니요호스트가 플러그인을 로드하고 실행할 때 적용하는 선택적 실행 제약입니다. 아웃바운드 네트워크 접근은 작성 필드가 아닙니다. 플러그인은 빌드 시점에 네트워크에 접근하지 않으므로(AOT 경계) 여기에 작성할 호스트 허용 목록 필드는 없습니다.
exportsobject[]아니요이 플러그인이 제공하는 export로, 각각 선언된 기능을 가집니다. export는 호스트가 디스패치하는 하나의 이름 있는 진입점이며(예: render_node, lint_naming, step), export별 기능 블록은 그 export가 하는 일에 대한 작성자의 주장으로, 호스트가 publish 시와 로드 시 플러그인의 자체 보고와 대조합니다. 항목은 작성 순서를 유지합니다. 생략하면 작성된 export 표면이 없음을 선언합니다.
commandsobject[]아니요기계가 관리하므로 작성하지 마십시오. 플러그인의 자체 보고로부터 aggrega plugin sync(또는 aggrega plugin gen-catalog)가 기록합니다. CLI 플러그인이 제공하는 최상위 aggrega <command> 동사는 플러그인의 자체 보고에서 읽어 자체 보고에 선언된 순서대로 여기에 기록되므로, CLI 플러그인이 설치하는 명령 표면을 플러그인을 로드하지 않고 엔터티에서 읽을 수 있습니다. CLI가 아닌 플러그인은 명령을 제공하지 않으며 빈 목록을 기록합니다. 호스트는 정확히 이 집합을 설치합니다. 기록된 집합이 플러그인의 자체 보고와 다르면 로드 시 중단되며, publish는 바이너리와 맞지 않는 집합을 거부하고 작성자에게 다시 기록하도록 안내합니다.
providerobject아니요pluginType: provider 플러그인을 위한 provider 소켓 블록입니다. 제공하는 기능, aggrega.ai/v1beta1 Workload 종류를 변환하는 방식, 읽는 플랫폼 고유 어노테이션, 렌더 동작 계약을 담습니다. provider 렌더링 플러그인에만 있으며 다른 모든 플러그인 타입에는 없습니다.
pipelineStepobject아니요pluginType: pipeline-step 플러그인을 위한 pipeline-step 블록으로, 해당 단계와 호환되는 provider 기능을 담습니다. pipeline-step 플러그인에만 있으며 다른 모든 플러그인 타입에는 없습니다.
parserobject아니요pluginType: parser 플러그인을 위한 parser 블록으로, 정규 구조 트리로 변환하는 소스 형식을 담습니다. parser 플러그인에만 있으며 다른 모든 플러그인 타입에는 없습니다.
importerobject아니요pluginType: importer 플러그인을 위한 importer 블록으로, Aggrega 작성 파일 초안으로 변환하는 외부 소스 형식과 해당 형식의 소스를 식별하는 시그니처를 담습니다. importer 플러그인에만 있으며 다른 모든 플러그인 타입에는 없습니다.

추가 속성은 허용되지 않습니다.

plugin.spec.signature

플러그인에 첨부된 서명을 가리키는 선택적 설명용 포인터입니다. 이 블록은 문서 용도일 뿐입니다. 카탈로그 독자를 위해 서명의 위치와 생성 방식을 기록할 뿐, 그 자체로 플러그인을 차단하거나 허용하지 않습니다. 실제 검사는 pull 시 적용되는 레지스트리별 신뢰 정책입니다. 서명은 OCI referrer로 가져와 레지스트리의 신뢰된 ID 또는 고정된 키로 검증한 뒤 lockfile에 검증된 사실로 기록됩니다. 서명을 요구하는 레지스트리는 필요한 서명이 없거나 신뢰할 수 없거나 유효하지 않으면 pull을 중단합니다.

속성타입필수설명
typeconst “sigstore-cosign”예서명 방식입니다. 지원되는 방식은 sigstore-cosign입니다. 상수: "sigstore-cosign"
signatureRefstring아니요첨부된 서명 번들의 OCI referrer 참조로, 문서화와 검색을 위한 것입니다. 서명을 여기에 고정하지 않고 pull 시 referrer 열거로 찾는 경우에는 생략합니다.
publicKeyRefstring아니요키 기반 서명의 경우 서명 생성에 사용된 공개 키를 가리키는 포인터입니다. 생략하면 레지스트리의 신뢰된 ID로 검증되는 키리스(OIDC ID) 서명임을 나타냅니다.

추가 속성은 허용되지 않습니다.

plugin.spec.runtime

호스트가 플러그인을 로드하고 실행할 때 적용하는 선택적 실행 제약입니다. 아웃바운드 네트워크 접근은 작성 필드가 아닙니다. 플러그인은 빌드 시점에 네트워크에 접근하지 않으므로(AOT 경계) 여기에 작성할 호스트 허용 목록 필드는 없습니다.

속성타입필수설명
maxMemoryPagesinteger아니요플러그인의 선형 메모리를 Wasm 페이지 단위(페이지당 64 KiB)로 제한합니다. 0이거나 없으면 플랫폼 기본 상한이 적용되므로 로드가 무제한이 되는 일은 없습니다. 더 많은 메모리가 필요한 연결은 이 값을 올립니다. 최솟값: 0.
timeoutMsinteger아니요한 번의 호출 동안 플러그인 자체 코드가 실행될 수 있는 시간을 밀리초 단위로 제한하며, 플러그인이 호출하는 호스트 함수 내부에서 소요된 시간은 포함하지 않습니다. Linux에서는 프로세서 시간으로 측정하므로 바쁜 머신에서 프로세서를 기다리는 시간은 포함되지 않으며, 다른 시스템에서는 경과 시간으로 측정합니다. 새로 로드된 플러그인에 대한 첫 호출에는 플러그인 자체의 시작 시간도 포함됩니다. 0이거나 없으면 플랫폼 기본 상한이 적용되므로 호출이 취소 불가능해지는 일은 없습니다. 더 오래 실행되는 연결은 이 값을 올립니다. 최솟값: 0.
hostFunctionsstring[]아니요기계가 관리하므로 직접 작성하지 마십시오. 플러그인이 가져오는 호스트 함수로, aggrega plugin sync(또는 aggrega plugin gen-catalog)가 .wasm 가져오기 섹션에서 읽어 정규 형식(정렬되고 중복이 제거된 형식)으로 여기에 기록합니다. 게시 시 바이너리에서 다시 도출하여 기록이 다른 엔터티를 거부하며, 풀 시 다시 도출하여 재검증합니다. 호스트는 정확히 이 도출된 집합을 등록하고, 모든 항목을 관리되는 허용 목록과 대조하여 검증합니다.
configKVstring 맵아니요런타임이 시작 시 플러그인에 전달하는 Plugin별 구성으로, 문자열 대 문자열 키/값 쌍으로 지정합니다. 항목은 작성자가 지정한 순서를 유지하므로 출력되는 레코드는 실행할 때마다 바이트 단위로 동일합니다. 지정하지 않으면 런타임의 기본 빈 구성이 적용됩니다.

추가 속성은 허용되지 않습니다.

plugin.spec.exports[]
속성타입필수설명
namestring예내보내기의 ABI 이름으로, 호스트가 디스패치하는 이름입니다(예: render_node, lint_naming, step). 최소 1자 이상이어야 합니다.
operatesstring (enum)아니요이 내보내기가 수행하는 파이프라인 작업입니다: patch(기존에 렌더링된 문서를 수정) 또는 emit(새 문서를 추가). 없으면 작업에 대한 주장이 없습니다. 허용되는 값: "patch", "emit"
scopestring (enum)아니요이 내보내기가 작업하는 문서 루트입니다: own(노드 자신의 렌더링된 문서) 또는 host(컴포넌트 범위 FeatureRecipe가 연결된 컴포넌트의 문서). 없으면 범위에 대한 주장이 없습니다. 허용되는 값: "own", "host"
selectorstring아니요내보내기가 작용하는 대상에 대한 자유 형식의 사람이 읽을 수 있는 설명입니다(예: workloads carrying a pod template). 카탈로그 독자를 위한 문서이며, 컴파일러는 이를 해석하지 않습니다.

추가 속성은 허용되지 않습니다.

plugin.spec.commands[]
속성타입필수설명
namestring예호스트가 등록하는 명령 동사입니다. 운영자가 호출하는 aggrega <name> 토큰이며, 호스트가 호출 시 플러그인에 전달하는 판별자이기도 하므로 여러 명령을 지원하는 단일 플러그인이 어떤 명령이 호출되었는지에 따라 분기할 수 있습니다. 최소 1자 이상이어야 합니다.
descriptionstring아니요명령 목록과 도움말 출력에 표시되는 명령의 한 줄 짧은 도움말 텍스트입니다. 문서 용도일 뿐이며, 호스트는 이에 따라 동작하지 않습니다.
flagsobject[]아니요선언된 순서대로 나열된 명령의 플래그입니다. 각 항목은 호스트가 명령에 등록하는 플래그 하나를 제공하므로, aggrega help 는 이를 핵심 명령의 플래그처럼 렌더링합니다. 플래그가 없는 명령은 이를 비워 둡니다. 한 명령 안에서 각 플래그 이름과 각 단축 이름은 한 번만 나타나야 하며, 어느 것도 모든 aggrega 명령이 이미 가진 플래그(--help, -h 및 전역 플래그)를 재사용할 수 없습니다. 호스트는 플러그인의 명령을 추가할 때 이를 검사하며, 선언이 검사에 실패한 플러그인은 경고와 함께 추가되지 않습니다.

추가 속성은 허용되지 않습니다.

plugin.spec.commands[].flags[]
속성타입필수설명
namestring예플래그의 긴 이름으로, 운영자가 명령줄에서 전달하는 —name 토큰입니다. 선언된 모든 플래그는 이 이름을 지정해야 합니다. 최소 1자 이상이어야 합니다.
shorthandstring아니요플래그의 선택적 짧은 별칭으로, 운영자가 긴 이름 대신 전달할 수 있는 -x 형식이며 단일 ASCII 문자 또는 숫자입니다. 없으면 플래그에 짧은 별칭이 없습니다. 패턴: ^[A-Za-z0-9]$.
descriptionstring아니요명령의 도움말 출력에 표시되는 플래그의 한 줄 도움말 텍스트입니다. 선택적인 문서이며, 호스트는 이를 검증하지도 이에 따라 동작하지도 않습니다.
typestring (enum)아니요플래그의 값 타입(string, bool 또는 int)이며, 도움말이 이 플래그를 어떤 종류의 플래그로 렌더링할지를 정합니다. 없으면 문자열 플래그로 렌더링합니다. 허용되는 값: "string", "bool", "int"
defaultstring아니요운영자가 플래그를 전달하지 않을 때의 기본값으로, 문자열로 표현합니다. bool 또는 int 플래그의 경우 해당 타입의 값입니다. 생략하면 플래그가 기본값을 선언하지 않습니다.

추가 속성은 허용되지 않습니다.

plugin.spec.provider

pluginType: provider 플러그인을 위한 provider 소켓 블록입니다. 제공하는 기능, aggrega.ai/v1beta1 Workload 종류를 변환하는 방식, 읽는 플랫폼 고유 어노테이션, 렌더 동작 계약을 담습니다. provider 렌더링 플러그인에만 있으며 다른 모든 플러그인 타입에는 없습니다.

속성타입필수설명
capabilitiesstring[]아니요aggrega plugin gen-catalog가 플러그인 .wasm의 자체 보고로부터 기록하므로, 이 목록의 출처는 플러그인입니다. 작성자는 게시 전에 목록을 좁혀 이 엔터티가 제공하지 않아야 할 항목을 제거할 수 있지만, 자체 보고에 없는 항목은 추가할 수 없습니다. 게시와, --plugin으로 플러그인의 .wasm을 지정한 aggrega validate는 자체 보고에 없는 capability를 지정한 목록을 거부합니다. 게시는 작성된 그대로 엔터티를 보내며 이 목록을 다시 쓰지 않고, 자체 보고에는 있지만 목록에서 빠진 각 capability를 알립니다. 이 provider가 제공하는 capability, 즉 helm 또는 compose 같은 capability 이름으로, provider는 해당 capability의 출력 형태를 렌더링합니다. provider는 capability의 출력 형태를 공유하는 아티팩트 전반에서 범용적이지만 모든 capability에 걸쳐 범용적인 것은 아니므로, 이 목록은 희망 사항이 아니라 명시적이고 테스트된 호환성 주장입니다. 항목은 작성자가 작성한 순서를 유지합니다. Recipe가 요청한 provider 대상은 그 대상을 목록에 포함하는 provider 플러그인으로 해석됩니다. 둘 이상의 provider 플러그인이 나열한 대상은 워크스페이스 구성의 plugins.providers 선택이 사용할 플러그인을 지정하지 않는 한 모호한 것으로 간주되어 중단됩니다. 목록이 비어 있거나 없으면 capability 주장을 선언하지 않으므로 플러그인은 어떤 대상도 제공하지 않습니다.
workloadSchemastring아니요이 provider가 aggrega.ai/v1beta1 Workload kind를 provider 고유 매니페스트로 변환하는 방법을 문서화하는 JSON Schema 2020-12입니다. 이 필드가 있으면 provider는 workload: 블록을 선언하는 Recipes(합성 모드)를 지원합니다. provider는 이 스키마를 문서/계약으로 참고하여 Workload를 provider 고유 매니페스트로 변환합니다. workload: Recipe의 지원 여부는 이 필드의 존재가 아니라 바인딩된 provider의 합성 capability로 결정됩니다. 합성할 수 없는 provider에 바인딩된 합성 모드 Recipe는 렌더링 시점에 명시적으로 중단됩니다. 표준 라이브러리 카탈로그는 합성하는 provider에 문서화된 계약으로서 workloadSchema를 선언하며, 그 capability와 동기화된 상태로 유지합니다. 이 필드는 문서화된 계약입니다. 본문은 올바른 형식인지 확인하기 위해 로드 시 JSON Schema 2020-12로 컴파일되며, 그 밖에는 아무것도 이를 읽지 않습니다.
wellKnownAnnotationsobject[]아니요provider의 지원 주장입니다. 이 provider가 읽는 플랫폼 고유의 잘 알려진 어노테이션 키(aggrega.ai/ 네임스페이스)를, 각각 읽히는 범위 및 키가 없을 때 적용되는 동작과 함께 나열합니다. provider가 실제로 읽는 키만 선언하십시오. 게시되는 지원 매트릭스는 이 선언에서 렌더링되므로, 여기에 나열된 키는 작성자가 해당 키가 지정하는 범위에서 렌더링 출력을 바꿀 것으로 기대할 수 있는 키입니다. 컴파일러는 이 선언을 두 가지 방식으로 읽습니다. provider 자신의 contract.inputKinds가 주장하지 않는 입력 종류를 지정하는 scope는 같은 엔터티의 인접한 주장과 모순되며, 빌드는 해당 키와 모순을 지명하며 중단됩니다. 또한 aggrega.ai/ 어노테이션이 이 provider를 통해 렌더에 도달했는데 해당 렌더가 선언하는 어떤 입력 종류에서도 이를 포함하는 항목이 없으면 빌드는 경고합니다. 이 필드는 예약된 aggrega.ai/ 접두사 아래의 값 바인딩을 규율하는 규칙과는 별개입니다. 없으면 지원 주장을 선언하지 않으며, 이 provider에 대해서는 그러한 경고가 발생하지 않습니다. 이러한 키를 하나도 읽지 않는 provider는 이 목록 대신 readsNoWellKnownAnnotations를 선언합니다. 항목은 순서 있는 목록이며 작성자가 작성한 순서를 유지합니다.
readsNoWellKnownAnnotations상수 true아니요이 provider가 aggrega.ai/ 네임스페이스의 플랫폼 고유 어노테이션 키, 즉 그렇지 않았다면 wellKnownAnnotations가 나열했을 키를 하나도 읽지 않음을 선언합니다. 이는 어떤 키도 포함하지 않는 지원 주장이며, 이 필드와 wellKnownAnnotations를 모두 생략하는 것이 침묵인 것과 달리 명시적인 진술입니다. 이 경우 빌드는 이 provider를 통해 렌더에 도달하는 모든 aggrega.ai/ 어노테이션에 대해 키, provider, 그리고 해당 렌더가 선언하는 입력 종류를 지명하며 경고합니다. 값은 여전히 변경 없이 통과하며 빌드는 중단되지 않습니다. true만 작성할 수 있으므로, 필드를 생략하는 것이 여전히 아무것도 말하지 않는 유일한 방법입니다. wellKnownAnnotations와 함께 작성할 수 없습니다. 키 중 일부를 읽는 provider는 대신 해당 키를 그곳에 나열합니다. 상수: true
contractobject아니요provider가 스스로 선언한 렌더링 동작 계약입니다. 렌더링하는 입력 종류, 디스패치 그룹의 노드별 출력을 조립하는 방식과 그 출력이 위치하는 디렉터리, 가져온 아티팩트 파일에 적용하는 템플릿 구분자 쌍, 로드된 인스턴스 하나가 모든 경계 통과를 처리할 수 있는지, 경계 간 엣지를 연결하는지, omit 항목을 준수하는지, Recipe가 자신의 경계 공유 출력에 기여하는 파일을 받아들이는지, 그리고 해당 생태계가 소스 옆에 절대 함께 배포하지 않는 파일을 다룹니다. 이는 provider 플러그인의 자체 보고를 게시 시점에 기록한 것이며, 호스트는 게시 시와 로드 시에 이를 그 자체 보고와 교차 검증합니다. 없으면 렌더링 동작 계약을 선언하지 않으며, 교차 검증은 export별 주장만 비교합니다.

추가 속성은 허용되지 않습니다.

plugin.spec.provider.wellKnownAnnotations[]
속성타입필수설명
keystring예provider가 읽는 플랫폼 고유의 잘 알려진 어노테이션 키입니다(예: aggrega.ai/namespace). 플랫폼 예약 aggrega.ai/ 어노테이션 네임스페이스, 즉 provider가 읽는 플랫폼 지시어 아래에 위치합니다. 패턴: ^aggrega\.ai/.+.
purposestring예어노테이션이 제어하는 대상, 즉 어노테이션이 있을 때 영향을 미치는 렌더링 동작입니다.
defaultBehaviorstring아니요이 어노테이션이 없을 때 provider가 적용하는 동작입니다.
scopestring (enum)[]아니요이 provider가 키를 읽는 위치입니다. 처음 세 값은 Recipe 입력 종류이며 키가 읽히는 렌더링 경로를 지정합니다. sourced는 벤더링된 파일 집합, synthesized는 provider가 구체화하는 Workload, artifactsStandalone는 출력 전체가 가져온 아티팩트 문서인 노드입니다. 이들 각각은 이 provider의 contract.inputKinds가 주장하는 입력 종류여야 하며, 주장하지 않는 종류를 지정하면 빌드가 중단됩니다. boundary는 노드별이 아니라 경계마다 한 번 해석되는 키, 즉 조립된 아티팩트의 이름이나 경계 간 참조가 형성되는 배치 컨텍스트를 위한 값입니다. 여기서는 입력 종류가 의미 있는 축이 아니므로 contract.inputKinds와 대조하지 않습니다. 둘 이상의 경로에서 읽히는 키는 해당 경로를 모두 나열합니다. 없으면 경로별 주장을 하지 않습니다. 아무것도 검사되지 않으며, 키는 provider가 어딘가에서 그 키를 읽는다는 것만 나타냅니다. 항목이 1개 이상 있어야 합니다. 같은 항목이 두 번 나타날 수 없습니다. 각 항목의 허용 값: "sourced", "synthesized", "artifactsStandalone", "boundary".

추가 속성은 허용되지 않습니다.

plugin.spec.provider.contract

provider가 스스로 선언한 렌더링 동작 계약입니다. 렌더링하는 입력 종류, 디스패치 그룹의 노드별 출력을 조립하는 방식과 그 출력이 위치하는 디렉터리, 가져온 아티팩트 파일에 적용하는 템플릿 구분자 쌍, 로드된 인스턴스 하나가 모든 경계 통과를 처리할 수 있는지, 경계 간 엣지를 연결하는지, omit 항목을 준수하는지, Recipe가 자신의 경계 공유 출력에 기여하는 파일을 받아들이는지, 그리고 해당 생태계가 소스 옆에 절대 함께 배포하지 않는 파일을 다룹니다. 이는 provider 플러그인의 자체 보고를 게시 시점에 기록한 것이며, 호스트는 게시 시와 로드 시에 이를 그 자체 보고와 교차 검증합니다. 없으면 렌더링 동작 계약을 선언하지 않으며, 교차 검증은 export별 주장만 비교합니다.

속성타입필수설명
inputKindsobject아니요이 플러그인이 렌더링하는 세 가지 Recipe 입력 종류: 소싱된 파일 집합, 합성된 워크로드, 아티팩트만으로 이루어진 독립 노드입니다. 각 필드는 서로 독립적인 주장입니다.
boundaryAssemblystring (enum)아니요플러그인이 디스패치 그룹의 노드별 렌더링 출력을 결합하는 방식입니다. none은 각 노드의 출력을 디스패치 경로에 직접 씁니다. merge는 노드별 조각을 하나의 문서로 합칩니다. nest는 각 노드의 출력을 상위 구조 안의 고유한 위치 아래에 배치합니다. 없으면 조립에 관한 주장을 하지 않습니다. 허용되는 값: "none", "merge", "nest"
artifactDelimitersobject아니요플러그인이 가져온 아티팩트 파일에 적용하는 Go 템플릿 구분자 쌍입니다. 없으면 기본 {{/}} 쌍을 의미합니다. 대상 구문이 이 쌍과 충돌하는 플러그인은 여기에 대체 쌍을 선언합니다.
assemblyNameAnnotationobject아니요해석된 값이 플러그인이 디스패치 그룹에서 조립하는 아티팩트의 이름이 되는 경계 어노테이션입니다. 그룹에 기여하는 경계들을 하나의 이름 있는 조립물로 합치는 플러그인은 자신이 읽는 어노테이션 키와, 기여하는 모든 경계가 해당 어노테이션의 해석된 값에 일치해야 하는지 여부를 선언합니다. 없으면 플러그인은 디스패치 경로만으로 조립물의 이름을 정합니다.
reusableInstance불리언아니요교차마다 새 인스턴스를 사용하는 대신, 로드된 하나의 플러그인 인스턴스가 빌드의 모든 render, assemble, validate 교차를 처리할 수 있는지 여부입니다. 플러그인이 교차 간에 상태를 유지하지 않을 때만, 즉 교차별 입력의 순수 함수일 때만 true로 선언하므로, 단일 인스턴스는 재사용되든 새로 로드되든 바이트 단위로 동일한 출력을 생성합니다. 없으면(false) 교차마다 새 인스턴스를 로드하여, 구조상 상태를 갖는 플러그인을 격리합니다.
crossBoundaryLinking불리언아니요플러그인이 짝을 이루는 link_publish/link_resolve export 계약을 통해 provider 고유의 상호 참조 연결을 내보내어, 경계를 넘는 uses 에지(소비하는 쪽과 소비되는 쪽이 서로 다른 디스패치 그룹으로 조립되는 uses 에지)를 연결하는지 여부입니다. 플러그인이 둘 다 export할 때만 true로 선언하며, export 쌍과 일치하지 않는 주장은 로드 시 중단됩니다. 없으면(false) 경계 간 연결을 선언하지 않으므로, 호스트는 플러그인에 link 교차를 전달하지 않습니다.
omits불리언아니요provider가 omit 항목(노드의 출력에서 제외할 렌더링 단위를 지정하는 항목)을 따르는지 여부입니다. 따르는 provider는 항목과 일치하는 모든 단위를 렌더링 결과에서 제외하고, 각 항목이 일치한 단위 수를 보고합니다. 이는 provider의 자체 보고가 하는 omits 주장을 게시 시점에 기록한 것이며, 그 보고와 다른 값은 로드 시 중단됩니다. 없으면(false) 그러한 지원을 선언하지 않습니다.
boundaryArtifacts불리언아니요provider가 렌더링하는 경계의 공유 출력에 Recipe가 Recipe의 spec.boundary.artifacts 아래에서 기여하는 파일을 수용하는지 여부입니다. 컴파일러는 그러한 각 파일을 경계의 조립된 출력이 있는 디렉터리에 한 번 쓰며, provider의 대상은 이를 해당 출력의 일부로 취급합니다. 이는 provider의 자체 보고가 하는 boundary_artifacts 주장을 게시 시점에 기록한 것이며, 그 보고와 다른 값은 로드 시 중단됩니다. 없으면(false) 그러한 지원을 선언하지 않으며, 이 provider에 대해 해당 블록을 선언한 Recipe는 렌더링이 시작되기 전에 거부됩니다.
nestSegmentstring아니요boundaryAssembly가 nest인 provider에서, 이 provider의 대상이 각 기여자의 하위 디렉터리를 배치하는 디렉터리입니다. 예를 들어 차트 상위 구조에는 charts, 루트 모듈에는 modules입니다. 컴파일러는 이 디렉터리, 기여자의 이름, 각 파일의 고유 경로를 결합합니다. 중첩하는 provider에 대해서만 읽습니다. 없으면 각 기여자의 하위 디렉터리를 경계의 고유 디렉터리에 직접 배치합니다. 값은 하나의 디렉터리를 지정하며 경로는 지정하지 않습니다.
sourceIgnoreobject아니요이 provider의 생태계가 렌더링하는 소스 옆에 절대 함께 배포하지 않는 파일로, gitignore 구문의 무시 규칙으로 표현됩니다. 이는 자체 보고가 선언하는 source_ignore 규칙을 게시 시점에 기록한 것입니다. 작성자가 이 provider가 제공하는 capability를 가진 Recipe 또는 FeatureRecipe를 고정하면, 이 규칙은 작성자 자신의 .aggregaignore와 결합되어 이 플러그인의 이름과 함께 엔터티 옆의 entity.lock에 기록되며, 이후 엔터티 로컬 소스의 모든 게시, 비교, 렌더링은 기록된 규칙을 적용합니다. 있으면 자체 보고가 선언하는 것과 같아야 하며, 보고가 다른 플러그인은 로드 시 거부됩니다. 없으면 주장을 하지 않으며 비교하지 않습니다.

추가 속성은 허용되지 않습니다.

plugin.spec.provider.contract.inputKinds

이 플러그인이 렌더링하는 세 가지 Recipe 입력 종류: 소싱된 파일 집합, 합성된 워크로드, 아티팩트만으로 이루어진 독립 노드입니다. 각 필드는 서로 독립적인 주장입니다.

속성타입필수설명
sourced불리언아니요가져온 파일 집합(차트, 모듈, compose 파일)을 렌더링합니다.
synthesized불리언아니요합성된 워크로드를 provider 고유 아티팩트로 렌더링합니다.
artifactsStandalone불리언아니요독립형 아티팩트 전용 노드, 즉 가져온 아티팩트 문서를 담고 source나 워크로드는 없는 노드를 렌더링합니다.

추가 속성은 허용되지 않습니다.

plugin.spec.provider.contract.artifactDelimiters

플러그인이 가져온 아티팩트 파일에 적용하는 Go 템플릿 구분자 쌍입니다. 없으면 기본 {{/}} 쌍을 의미합니다. 대상 구문이 이 쌍과 충돌하는 플러그인은 여기에 대체 쌍을 선언합니다.

속성타입필수설명
leftstring예여는 구분자입니다.
rightstring예닫는 구분자입니다.

추가 속성은 허용되지 않습니다.

plugin.spec.provider.contract.assemblyNameAnnotation

해석된 값이 플러그인이 디스패치 그룹에서 조립하는 아티팩트의 이름이 되는 경계 어노테이션입니다. 그룹에 기여하는 경계들을 하나의 이름 있는 조립물로 합치는 플러그인은 자신이 읽는 어노테이션 키와, 기여하는 모든 경계가 해당 어노테이션의 해석된 값에 일치해야 하는지 여부를 선언합니다. 없으면 플러그인은 디스패치 경로만으로 조립물의 이름을 정합니다.

속성타입필수설명
annotationstring예플러그인이 조립된 아티팩트의 이름을 읽어 오는 경계 어노테이션 키입니다.
requireUnique불리언아니요하나의 디스패치 그룹에 기여하는 모든 경계가 어노테이션의 확인된 값에 일치해야 하는지 여부입니다. true이면 기여 경계들이 어노테이션을 서로 다른 값으로 확인하는 그룹은 빌드를 중단시키고, false이면 플러그인은 처음 확인된 값을 받아들입니다.

추가 속성은 허용되지 않습니다.

plugin.spec.provider.contract.sourceIgnore

이 provider의 생태계가 렌더링하는 소스 옆에 절대 함께 배포하지 않는 파일로, gitignore 구문의 무시 규칙으로 표현됩니다. 이는 자체 보고가 선언하는 source_ignore 규칙을 게시 시점에 기록한 것입니다. 작성자가 이 provider가 제공하는 capability를 가진 Recipe 또는 FeatureRecipe를 고정하면, 이 규칙은 작성자 자신의 .aggregaignore와 결합되어 이 플러그인의 이름과 함께 엔터티 옆의 entity.lock에 기록되며, 이후 엔터티 로컬 소스의 모든 게시, 비교, 렌더링은 기록된 규칙을 적용합니다. 있으면 자체 보고가 선언하는 것과 같아야 하며, 보고가 다른 플러그인은 로드 시 거부됩니다. 없으면 주장을 하지 않으며 비교하지 않습니다.

속성타입필수설명
patternsstring[]아니요생태계 자체의 무시 패턴으로, 각각 로컬 소스 디렉터리의 루트를 기준으로 하며 적용되는 순서대로 나열됩니다.
filesstring[]아니요생태계가 소스 안에서 따르는 무시 파일의 이름입니다(차트의 경우 .helmignore). 그러한 각 파일의 줄은 추가 패턴이며, 그 파일을 담은 디렉터리를 기준으로 합니다.

추가 속성은 허용되지 않습니다.

plugin.spec.pipelineStep

pluginType: pipeline-step 플러그인을 위한 pipeline-step 블록으로, 해당 단계와 호환되는 provider 기능을 담습니다. pipeline-step 플러그인에만 있으며 다른 모든 플러그인 타입에는 없습니다.

속성타입필수설명
capabilitiesstring[]아니요aggrega plugin gen-catalog가 플러그인 .wasm의 자체 보고에서 기록하므로, 이 목록의 출처는 플러그인입니다. 작성자는 게시 전에 이 목록을 좁혀 이 엔티티가 제공하지 않아야 할 항목을 제거할 수 있지만, 자체 보고에 없는 항목은 추가할 수 없습니다. 게시와, --plugin으로 플러그인 .wasm을 전달한 aggrega validate는 자체 보고에 없는 capability를 나열한 목록을 거부합니다. 게시는 엔티티를 작성된 그대로 보내며 이 목록을 다시 쓰지 않고, 자체 보고에는 있지만 목록에서 빠진 각 capability를 알립니다. 이 플러그인의 파이프라인 단계와 호환되는 provider capability로, 단계가 렌더링 출력을 변환하는 방법을 아는 helm이나 compose 같은 provider capability 이름입니다. 단계는 한 번에 하나의 provider 출력 형태를 대상으로 작성되므로, 이 목록은 희망 사항이 아니라 명시적이고 검증된 호환성 주장입니다. 항목은 작성자의 순서를 유지합니다. 이는 해당 주장을 카탈로그에서 읽을 수 있도록 기록한 것입니다. 빌드는 단계가 스코프에 관여할 때 플러그인에서 같은 주장을 읽으며, 해당 스코프의 문서를 렌더링하는 provider가 그 안에 없으면 중단됩니다. 목록이 비어 있거나 없으면 호환성 주장을 선언하지 않으므로, 어떤 스코프도 해당 단계를 허용하지 않습니다.

추가 속성은 허용되지 않습니다.

plugin.spec.parser

pluginType: parser 플러그인을 위한 parser 블록으로, 정규 구조 트리로 변환하는 소스 형식을 담습니다. parser 플러그인에만 있으며 다른 모든 플러그인 타입에는 없습니다.

속성타입필수설명
capabilitiesstring[]아니요aggrega plugin gen-catalog가 플러그인 .wasm의 자체 보고에서 기록하므로, 이 목록의 출처는 플러그인입니다. 작성자는 게시 전에 이 목록을 좁혀 이 엔티티가 제공하지 않아야 할 항목을 제거할 수 있지만, 자체 보고에 없는 항목은 추가할 수 없습니다. 게시와, --plugin으로 플러그인 .wasm을 전달한 aggrega validate는 자체 보고에 없는 capability를 나열한 목록을 거부합니다. 게시는 엔티티를 작성된 그대로 보내며 이 목록을 다시 쓰지 않고, 자체 보고에는 있지만 목록에서 빠진 각 capability를 알립니다. 이 파서가 정규 구조 트리로 변환하는 소스 형식으로, 각각 parse:<format> 형태로 씁니다(예: parse:yaml). 접두사는 항목의 일부이므로, 여러 형식을 알리는 플러그인은 형식마다 하나의 항목을 나열합니다. 항목은 작성자의 순서를 유지합니다. 요청된 형식은 목록에 일치하는 항목이 있는 파서로 해석됩니다. 어떤 파서도 알리지 않는 형식은 빌드를 중단시키며, 둘 이상의 파서 플러그인이 알리는 형식은 모호한 것으로 중단됩니다. 목록이 비어 있거나 없으면 형식 주장을 선언하지 않으므로, 플러그인은 아무것도 파싱하지 않습니다.

추가 속성은 허용되지 않습니다.

plugin.spec.importer

pluginType: importer 플러그인을 위한 importer 블록으로, Aggrega 작성 파일 초안으로 변환하는 외부 소스 형식과 해당 형식의 소스를 식별하는 시그니처를 담습니다. importer 플러그인에만 있으며 다른 모든 플러그인 타입에는 없습니다.

속성타입필수설명
capabilitiesstring[]아니요aggrega plugin gen-catalog가 플러그인 .wasm의 자체 보고에서 기록하므로, 이 목록의 출처는 플러그인입니다. 작성자는 게시 전에 이 목록을 좁혀 이 엔티티가 제공하지 않아야 할 항목을 제거할 수 있지만, 자체 보고에 없는 항목은 추가할 수 없습니다. 게시와, --plugin으로 플러그인 .wasm을 전달한 aggrega validate는 자체 보고에 없는 capability를 나열한 목록을 거부합니다. 게시는 엔티티를 작성된 그대로 보내며 이 목록을 다시 쓰지 않고, 자체 보고에는 있지만 목록에서 빠진 각 capability를 알립니다. 이 importer가 Aggrega 작성 파일 초안으로 변환하는 외부 소스 형식이며, 각각 import:<format> 형태로 씁니다(예: import:terraform). 접두사는 항목의 일부이므로 여러 형식을 알리는 플러그인은 형식마다 항목을 하나씩 나열합니다. 항목은 작성자가 쓴 순서를 유지합니다. 요청된 import 형식은 목록에 일치하는 항목이 있는 importer로 해석됩니다. 어떤 importer도 알리지 않는 형식은 import를 중단시키고, 둘 이상의 importer 플러그인이 알리는 형식은 워크스페이스 구성의 plugins.importer 항목이 그중 하나를 지정하지 않는 한 모호함으로 중단되며, 지정된 경우 그 플러그인이 실행됩니다. 비어 있거나 없는 목록은 형식 주장을 선언하지 않으므로 플러그인은 아무것도 가져오지 않습니다.
detectobject[]아니요기계가 소유하므로 직접 작성하지 마십시오. 엔티티가 플러그인의 .wasm 자체 보고로부터 생성될 때 도출되어, 자체 보고가 선언한 순서대로 여기에 기록됩니다. import가 형식을 지정하지 않을 때 이 importer의 형식에 해당하는 소스를 인식하는 시그니처입니다. aggrega import는 워크스페이스의 카탈로그가 보유한 모든 importer(모든 버전 포함)와 컴파일러의 코어 importer의 시그니처를 읽고, 어떤 형식이 무엇인지 알지 못한 채 이를 소스와 대조하며, 시그니처가 일치하는 단 하나의 importer의 형식으로 소스를 읽습니다. 어떤 시그니처와도 일치하지 않는 소스는 형식을 요청하며 거부되고, 둘 이상의 형식의 시그니처와 일치하는 소스는 그 형식들을 명시하며 거부됩니다. 소스를 인식한 importer는 그 소스를 자신이 알리는 모든 형식으로 인식하므로, 둘 이상의 형식을 알리는 importer의 일치는 모두 모호함으로 거부됩니다. 이 목록이 있으면 플러그인의 자체 보고가 선언하는 내용과 항목별로, 순서까지 같아야 하며, 보고가 다른 플러그인은 로드와 게시에서 이 필드를 명시하며 거부됩니다. 없으면 아무것도 주장하지 않고 비교되지 않으며, 이 경우 importer의 형식은 이름을 지정해야만 사용할 수 있습니다.

추가 속성은 허용되지 않습니다.

plugin.spec.importer.detect[]
속성타입필수설명
syntaxstring예소스를 파싱할 구문 형식으로(예: json 또는 yaml), parser 플러그인이 parse:<syntax>로 알리는 형식입니다. 소스는 워크스페이스의 카탈로그가 해당 구문에 대해 제공하는 parser로 파싱되며, 카탈로그가 parser를 제공하지 않는 구문이면 컴파일러에 포함된 parser로 파싱됩니다. 그 구문을 지정하는 시그니처가 몇 개이든 파싱은 최대 한 번이며, 그 구문으로 파싱되지 않는 소스는 그 구문을 지정하는 어떤 시그니처와도 일치하지 않습니다. 어느 쪽도 parser를 제공하지 않는 구문은 해당 parser의 부재를 명시하며 인식을 중단시킵니다. 최소 1자 이상입니다.
filesstring[]아니요시그니처가 적용되는 파일 이름 패턴으로, 구분자를 슬래시로 읽은 소스 이름의 끝부분과 대조됩니다. 세그먼트가 하나인 패턴은 파일 자체의 이름과, 슬래시로 구분된 여러 세그먼트의 패턴은 경로의 마지막 같은 수의 세그먼트와 대조되므로, .vscode/mcp.json은 .vscode라는 디렉터리에 있는 mcp.json이라는 파일과 일치합니다. 세그먼트 안에서 *는 임의 길이의 문자열, ?는 한 문자, [...]는 클래스에 속한 한 문자와 일치합니다. 패턴 중 하나라도 일치하면 시그니처가 적용됩니다. 없거나 비어 있으면 이름과 관계없이 단일 파일인 소스에 적용되고, 디렉터리의 파일에는 적용되지 않습니다. importer 시그니처의 패턴은 aggrega import가 디렉터리의 어떤 파일을 그 importer에 넘길지도 결정합니다.
matchobject[]아니요파싱된 트리가 선언된 순서대로 모두 충족해야 하는 술어입니다. 없거나 비어 있으면 해당 구문으로 파싱되는 것 외에 트리에 아무것도 요구하지 않습니다.

추가 속성은 허용되지 않습니다.

plugin.spec.importer.detect[].match[]
속성타입필수설명
pathstring예술어가 트리에서 살펴보는 위치로, 트리의 최상위부터 점으로 이은 키로 씁니다. data.nodes는 최상위 data 객체의 nodes 멤버를 가리킵니다. 0 이상의 정수로 쓴 세그먼트는 0부터 세어 배열의 해당 위치를 선택하므로, nodes.0.type은 첫 번째 노드의 type을 가리킵니다. 그 밖의 모든 세그먼트는 객체의 멤버를 선택합니다. 최소 1자 이상입니다.
isstring (enum)예경로가 도달해야 하는 대상입니다. present는 null을 포함해 어떤 종류의 값에든 도달하면 성립하고, absent는 아무것에도 도달하지 않으면 성립하며, object, array, string, number, boolean은 각각 그 종류의 값에 도달하면 성립합니다. 허용되는 값: "present", "absent", "object", "array", "string", "number", "boolean"
equalsstring아니요경로가 도달한 값이 정확히 같아야 하는 문자열입니다. 문자열이 아닌 값은 결코 같지 않습니다. 하나의 술어에는 equals와 prefix 중 최대 하나만 선언합니다. 최소 1자 이상입니다.
prefixstring아니요경로가 도달한 값이 시작해야 하는 문자열입니다. 문자열이 아닌 값은 결코 이 문자열로 시작하지 않습니다. 하나의 술어에는 equals와 prefix 중 최대 하나만 선언합니다. 최소 1자 이상입니다.

추가 속성은 허용되지 않습니다.