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.

Trạng thái của ngôn ngữ

Trang này là tài liệu tham chiếu chính thức cho biết những bề mặt nào của Aggrega có thể dùng được hiện nay, những bề mặt nào đã được mô tả trong tài liệu nhưng trình biên dịch chưa xử lý, và những bề mặt nào được lên kế hoạch cho một phiên bản tương lai. Trang này bổ sung cho các chương theo từng lĩnh vực bằng cách trình bày trạng thái sẵn sàng trên toàn bộ ngôn ngữ tại một nơi duy nhất.

Hai nhóm người đọc tra cứu trang này. Người mới viết lần đầu xem trang này trước khi viết dựa trên một bề mặt chưa quen thuộc, để xác nhận rằng bề mặt đó hiện đã tạo ra đầu ra được kết xuất. Người tìm tham chiếu xem trang này khi một bề mặt họ đang dùng hoạt động không như mong đợi — ví dụ, khi YAML hợp lệ nhưng không có đầu ra nào được tạo ra, trang này là nơi đầu tiên để tra cứu trạng thái của bề mặt đó. Người đọc quay lại cũng tra cứu trang này để xác định những bề mặt đã chuyển giữa các nhãn trạng thái kể từ lần đọc trước. Các chương theo từng lĩnh vực và các tài liệu tham chiếu thực thể mô tả bề mặt được thiết kế để hoạt động như thế nào; trang này mô tả liệu nó đã hoạt động hay chưa.

Phân loại trạng thái

Mỗi bề mặt ngôn ngữ trên trang này mang một trong bốn nhãn trạng thái:

  • available. Schema chấp nhận bề mặt; trình biên dịch tiêu thụ nó; hành vi khớp với hợp đồng đã được tài liệu hóa. Tác giả dùng một bề mặt available nhận được đúng hợp đồng đã được tài liệu hóa.

  • accepted but inert. Schema chấp nhận bề mặt — việc viết theo nó vượt qua kiểm tra hợp lệ — nhưng trình biên dịch chưa xử lý nó. Viết một bề mặt accepted but inert tạo ra một bản build hợp lệ về cú pháp nhưng không có hiệu ứng render nào cho bề mặt đó; trình biên dịch có thể phát ra cảnh báo nêu tên bề mặt không hoạt động (mẫu được khuyến nghị), hoặc một số bề mặt hiện tại lặng lẽ bị bỏ qua mà không cảnh báo. Các mục theo từng phần bên dưới nêu rõ hành vi cụ thể.

  • accepted but blocked. Schema chấp nhận bề mặt — việc viết theo nó vượt qua kiểm tra hợp lệ — nhưng trình biên dịch dừng bản build thay vì render nó. Viết theo một bề mặt accepted but blocked sẽ thất bại khi render với một lỗi tường minh nêu rõ bạn nên viết gì thay thế. Việc chặn có thể là vĩnh viễn, khi những gì được viết là một sự mơ hồ mà trình biên dịch sẽ không giải quyết thay bạn, vì chọn một cách hiểu cho bạn có thể phát hành thứ bạn không yêu cầu; hoặc nó chỉ tồn tại cho đến khi hành vi đằng sau bề mặt được phát hành. Điều nhãn này cam kết là như nhau trong cả hai trường hợp: schema chấp nhận nó, bản build từ chối nó, và lỗi cho bạn biết cách sửa.

  • planned. Bề mặt được tài liệu hóa theo thiết kế nhưng cả schema lẫn trình biên dịch đều chưa chấp nhận nó. Viết theo một bề mặt planned sẽ thất bại ở bước kiểm tra schema. Trang này nêu các mục đã lên kế hoạch để tác giả có thể lập kế hoạch xoay quanh sự vắng mặt của chúng thay vì phát hiện khoảng trống khi build.

Các nhãn trạng thái được đánh giá dựa trên trình biên dịch hiện tại. Các bề mặt đang được phát triển tích cực có thể chuyển đổi giữa các nhãn; các mục theo từng phần mô tả kế hoạch chuyển đổi khi đã biết.

Các loại đầu vào của Recipe

Một Recipe kết hợp đầu ra của nó từ ba loại đầu vào — sourced, synthesized và artifacts — được mô tả trong 16-recipe-input-composition.md. Trạng thái theo từng loại đầu vào:

  • source: + valuesMapping: (sourced) — available. Trình biên dịch phân giải URI source:, đánh giá template valuesMapping (nội tuyến, $import: từ file, hoặc $import: từ thư viện), và chuyển kết quả cho provider đích để kết xuất. Được sử dụng bởi các provider helm, helm-chart, compose, terraform và cloudformation.

  • workload: (synthesized) — available. Recipe khai báo workload: hoặc nội tuyến (block scalar chứa YAML của Workload) hoặc qua $import: (đường dẫn file). Trình biên dịch phân tích Workload đã qua template, xác thực nó theo schema Workload được nhúng, và chuyển tới bộ tổng hợp workload của provider đích. Được sử dụng bởi các provider helm và compose. Provider helm-chart chuyển hướng tác giả một cách tường minh sang provider helm cho các manifest K8s được tổng hợp. Một Recipe khai báo workload: với một provider không triển khai tổng hợp workload sẽ dừng khi kết xuất với lỗi CATALOG_ERROR.

  • artifacts: (artifacts) — khả dụng. Trường này là một map gồm các mục có tên; mỗi mục được viết inline hoặc được nạp qua $import: theo từng mục. Các mục được đánh giá sau khi Workload đã được phân tích cú pháp và source đã được phân giải, nên toàn bộ ngữ cảnh template — bao gồm .workload và .source — đều khả dụng với chúng. Với các tài liệu có metadata, thông tin nguồn gốc được hợp nhất vào metadata.labels và metadata.annotations của chúng: các khóa không an toàn về bộ ký tự — recipe-uri, boundary-path, sync-wave — được đặt vào annotations, đúng cách phân chia mà các provider helm áp dụng. Các mục được xuất thành các tệp riêng biệt bên cạnh đầu ra được render từ source hoặc được tổng hợp từ workload của Recipe. Provider dispatch — provider helm dạng phẳng xuất các tệp độc lập trong một thư mục mang tên thành phần đã khai báo chúng, nằm trong thư mục đầu ra của boundary, vì khóa chỉ đặt tên cho tệp và không cho biết thành phần nào đã viết ra nó; provider compose chuyển các tệp xuất của nó qua bộ hợp nhất ở cuối Release; provider helm-chart đánh giá mọi mục với dấu phân cách Aggrega [[ ]] để cú pháp {{ }} của Helm trong cùng tệp được giữ nguyên cho lần render phía sau, rồi đặt từng mục theo dạng đã viết của nó — một mục được nạp bằng $import: được đặt tại boundaries/<bp>/charts/<nodeID>/templates/<authored-key> (các tệp của một bundle được lồng bên dưới khóa đó), bên cạnh các template riêng của chart lấy từ source, còn một mục có nội dung inline được đặt tại boundaries/<bp>/charts/<nodeID>/<authored-key>, tức thư mục gốc của chart, nơi các template riêng của chart đọc nó qua .Files.Get / .Files.Glob; provider terraform ghi nguyên văn từng mục vào thư mục riêng của thành phần dưới cây modules/ của boundary; provider cloudformation hợp nhất từng mục, một đoạn stack, vào stack duy nhất được lắp ráp cho thư mục đầu ra đó. Các xung đột tên tệp giữa các nguồn gốc loại đầu vào (đầu ra được render từ source, được tổng hợp từ workload, hoặc được xuất từ artifact) được bộ phát hiện xung đột chéo nguồn gốc phát hiện tại thời điểm render và tạo ra một CATALOG_ERROR nêu tên mọi bên đóng góp.

Xem entities/recipe.md về bề mặt viết Recipe và các quy tắc kết hợp loại đầu vào; errors/fatal-halts.md về các quy tắc hình dạng của Recipe; và phần Providers bên dưới về ma trận theo từng provider.

Ngôn ngữ ánh xạ

Recipes (và FeatureRecipes) gắn với một trường ánh xạ duy nhất để chuyển ngữ cảnh Aggrega thành từ điển giá trị mà provider bên dưới sử dụng. Trường valuesMapping: hỗ trợ ba chế độ soạn thảo, được phân luồng theo hình dạng nội dung:

  • valuesMapping: — Chế độ 1-3 đã có. Chế độ 1: Go template nội tuyến (block scalar). Chế độ 2: $import: tệp (một map chỉ chứa $import: với đường dẫn tệp cục bộ). Chế độ 3: $import: thư viện (một map chỉ chứa $import: với tham chiếu định danh dạng tên trần tới một mục MappingLibrary, <Library>#/mappings/<entry>, tùy chọn kèm mức sàn :<version>). Trình biên dịch phân luồng theo hình dạng nội dung — block scalar sang Chế độ 1, $import: với đường dẫn tệp sang Chế độ 2, $import: với tham chiếu thư viện dạng tên trần sang Chế độ 3. Cả ba đều đánh giá Go template đã được phân giải dựa trên ngữ cảnh template của Recipe trong quá trình ánh xạ giá trị (thư viện trợ giúp Sprig được đăng ký sẵn); Chế độ 3 phân giải mục dựa trên catalog cục bộ cùng mọi thư viện được ghim trong lockfile, và tham chiếu có chứa host sẽ bị từ chối. Xem mục “Trường valuesMapping — ba chế độ soạn thảo” trong entities/recipe.md để biết cơ chế phân luồng và các ví dụ minh họa.

Xem entities/recipe.md để biết bề mặt soạn thảo Recipe và thiết kế ngôn ngữ ánh xạ, và entities/mappinglibrary.md để biết thực thể thư viện hỗ trợ Chế độ 3.

Cú pháp inject

Khối inject: có một cú pháp duy nhất ở mọi vị trí — trong inject riêng của một component, trong một kết nối uses, và trong một gắn kết.

  • Một danh sách mục cho mỗi cơ chế ([{in: ..., from: ...}], [{in: ..., value: ...}]) — đã có. Mỗi cơ chế phân phối là một danh sách; mỗi mục nêu định danh cục bộ của nó (tên biến môi trường, đường dẫn tệp, cờ đối số) bằng in: và mang đúng một trong hai: from: (tham chiếu khóa provides) hoặc value: (chuỗi literal). Một cơ chế được viết dưới dạng map thay vì danh sách, hoặc một mục mang cả hai từ khóa, sẽ dừng quá trình build tại phong bì tài liệu của Aggregate và nêu đường dẫn.

  • value: chỉ trong inject riêng của một component. Một literal thuộc về inject riêng của component, nơi phân phối nó. Trên một kết nối uses, value: sẽ dừng quá trình build, như An inject: entry on a connection carries a literal (Một mục trên kết nối mang một literal) mô tả, và trong inject riêng của một gắn kết, nó cũng dừng quá trình build, như An inject: entry on an attached Feature carries a literal (Một mục trên một Feature được gắn kết mang một literal) mô tả: cả hai chỉ phân phối các khóa mà một thực thể khác công bố, được đặt tên bằng from:.

Xem vocabulary/topology-triad.md để biết đặc tả đầy đủ của Injection Contract, bao gồm ngữ nghĩa ngữ cảnh hai trạng thái, các quy tắc xung đột khóa và các ví dụ minh họa.

Template engine

Template engine Go của Aggrega đánh giá các template của Recipe và FeatureRecipe dựa trên ngữ cảnh template tại giai đoạn theo từng vị trí mà Template Expansion Matrix mô tả. Thư viện helper Sprig được đăng ký sẵn cùng với các helper riêng của Aggrega trên mọi bề mặt mà renderer đánh giá, với một ngoại lệ: việc phân giải một tọa độ source: có cấu trúc chỉ đăng ký các helper của Aggrega — optional và capitalizedWords có sẵn ở đó còn các hàm của Sprig thì không, nên một lời gọi Sprig trong trường source:, hoặc trong một mục locals: trên một entity mang source: có cấu trúc, sẽ dừng ngay tại thời điểm phân tích cú pháp. Xem errors/fatal-halts.md, nơi dành cho bề mặt đó một mục riêng. Việc đánh giá, phân tích cú pháp và tích hợp Sprig hiện đã có sẵn.

Hành vi khi thiếu khóa — được chấp nhận trên các value template; nghiêm ngặt missingkey=error trên các path template, trên các assertion và trên một tọa độ source:. Các value template được đánh giá với tùy chọn missingkey=zero của Go, nên một template tham chiếu đến khóa chưa được gán (ví dụ: .values.unset_field) không gây lỗi và phép đọc không render ra gì. Các cách viết quen thuộc trong catalog như {{ .values.optional_field | default "fallback" }} vẫn hoạt động theo chính sách này, vì một giá trị chưa được đặt được coi là rỗng đối với default. Các path template (directory: / subDirectory: trên các ranh giới Release) được đánh giá với missingkey=error dựa trên một danh sách cho phép đóng — các lỗi đường dẫn âm thầm tạo ra cấu trúc hệ thống tệp hỏng mà người vận hành chỉ phát hiện sau khi build, và tính nghiêm ngặt giúp bắt lỗi sớm hơn. Hai bề mặt khác cũng áp dụng chính sách nghiêm ngặt này, vì cùng lý do: một kết quả render rỗng ở đó sẽ tạo ra một phán quyết sai hoặc một pin sai thay vì một trường mà tác giả có thể đọc lại. Đó là một mục assertions: trên một Component, Feature, Recipe hoặc FeatureRecipe, và các trường dùng template của một khối source: có cấu trúc trên một Recipe hoặc FeatureRecipe. errors/fatal-halts.md trình bày chính sách của từng bề mặt một và đưa ra các dạng nhận biết sự hiện diện hoạt động được theo chính sách nghiêm ngặt.

Giá trị dự phòng nhận biết sự hiện diện qua optional. Khi tác giả Recipe cần phân biệt “khóa vắng mặt” với “khóa có mặt với giá trị không / rỗng / false” — sự phân biệt mà default của Sprig không làm được — renderer cung cấp helper optional: {{ optional .infra "replicas" 1 }} trả về infra.replicas do tác giả viết (kể cả một giá trị 0 được viết) khi có mặt, và chỉ dùng 1 khi khóa vắng mặt. Xem templates/sprig-functions.md để biết đầy đủ ngữ nghĩa.

Gộp tên qua capitalizedWords. Khi một đích chỉ chấp nhận chữ cái và chữ số trong các tên mà nó dùng để định danh tài nguyên, {{ capitalizedWords .context.instance_id }} đọc id thành các từ được phân tách bởi bất kỳ ký tự nào ngoài bảng chữ cái đó và viết hoa chữ cái đầu của mỗi từ, nên payments-db cho ra PaymentsDb. Phép gộp loại bỏ mọi dấu phân tách, nên hai id chỉ khác nhau ở dấu câu sẽ cho ra cùng một tên; một bản build sắp tạo ra hai tài nguyên dưới cùng một tên sẽ dừng lại và nêu tên cả hai id. Xem templates/sprig-functions.md để biết đầy đủ ngữ nghĩa.

Thực thi hợp đồng tham số tại tầng khai báo. Các tham số bắt buộc mà Release không cung cấp sẽ tạo ra lỗi rõ ràng tại tầng hợp đồng tham số, thứ đầu tiên mà quá trình phân giải kiểm tra, kèm nguồn gốc file:line nêu tên tham số và hợp đồng. Các vi phạm kiểu / ràng buộc cũng được báo theo cùng cách. Đây là cơ chế thực thi thực chất đối với khóa bị thiếu: kiểu được kiểm tra tại nơi thể hiện ý định của nhà phát triển (khai báo parameters: của Aggregate), chứ không phải ở thời điểm đánh giá template phía sau. Xem entities/aggregate.md §“Typed parameter contracts”.

Một ngữ pháp khai báo duy nhất cho parameters: của Aggregate. Mỗi vị trí tham số được viết dưới dạng một đối tượng hợp đồng có kiểu (key: { type: <type>, default: <value>, ... }). Cách viết tắt dạng scalar trần (key: <value>) bị từ chối tại phong bì tài liệu của Aggregate, với một lỗi nêu tên tham số và cho biết lẽ ra phải là một đối tượng. Bộ từ vựng hợp đồng có kiểu làm cho ngữ nghĩa của type:, required: và các ràng buộc trở nên rõ ràng tại tầng khai báo; việc đáp ứng của Release vẫn tiếp tục dùng các giá trị scalar theo kiểu đã khai báo của hợp đồng.

Xem templates/expansion-matrix.md để biết ma trận đánh giá theo từng vị trí template và 05-templates.md để xem tổng quan về templating.

Các giai đoạn của pipeline biên dịch

Pipeline biên dịch của Aggrega được mô tả trong ../architecture/10-compilation-pipeline.md. Trạng thái theo từng giai đoạn:

  • Phân giải, xây dựng topology, hoàn thiện đồ thị, phân tích tĩnh và kết xuất — đã có.
  • Inject mapping (chặn trước khi kết xuất bằng injectMapping) và mọi giai đoạn con của kết xuất cơ sở — công bố locals, ánh xạ values, tổng hợp workload, đánh giá artifact, kết xuất của provider, kết xuất feature, và sinh tài nguyên FeatureRecipe cho thông tin xác thực — đã có.
  • Pipeline plugin (thực thi Wasm qua pipeline:) — đã có. Một Recipe hoặc FeatureRecipe khai báo các bước pipeline: không rỗng sẽ có từng bước được thực thi theo thứ tự khai báo: trình biên dịch gọi plugin Wasm mà bước đó nêu tên trên đầu ra đã kết xuất, áp dụng các thao tác JSON Patch được trả về lên các tài liệu được chỉ định, và phát ra các tác dụng phụ của bước. Một bước có điều kiện when: kết xuất ra giá trị falsy sẽ bị bỏ qua như một bước chuyển tiếp, giữ nguyên tập tài liệu. Các tác giả muốn thực hiện các thay đổi kiểu JSONPatch (chèn sidecar Envoy, VolumeMount cho secret, v.v.) có thể đạt được chúng thông qua cơ chế này.

Providers

Thư viện chuẩn của Aggrega cung cấp năm provider kết xuất — helm, helm-chart, compose, terraform và cloudformation. Trạng thái theo từng provider:

  • helm — đã có. Cả chế độ có nguồn (kết xuất Helm chart qua Helm SDK) lẫn chế độ tổng hợp (Workload → một đối tượng controller được chọn theo form của Workload — Deployment, StatefulSet, DaemonSet, Job hoặc CronJob — cùng với Services và PVCs) đều đã được cung cấp.
  • helm-chart — đã có. Chế độ có nguồn (kết hợp umbrella chart) đã được cung cấp. Loại đầu vào tổng hợp không áp dụng cho provider này; tác giả cần tổng hợp manifest K8s sử dụng provider helm với workload:.
  • compose — đã có. Cả chế độ có nguồn (lớp phủ phân đoạn compose) lẫn chế độ tổng hợp (Workload → service compose + volumes + networks) đều đã được cung cấp. Đầu ra docker-compose.yaml theo từng ranh giới được lắp ráp thông qua bộ kết hợp ở cấp Release.
  • terraform — đã có. Cả chế độ có nguồn lẫn artifact đều đã được cung cấp; mỗi boundary nhận một cấu hình gốc, aggrega.modules.tf, khai báo mọi component dưới dạng một khối module có các tệp nằm trong thư mục riêng của nó dưới modules/. Loại đầu vào tổng hợp không áp dụng cho provider này.
  • cloudformation — đã có. Cả chế độ có nguồn lẫn artifact (các đoạn stack) đều đã được cung cấp; mọi component render vào cùng một thư mục đầu ra được lắp ráp thành một template stack, xuất ra dưới dạng JSON thuần. Loại đầu vào tổng hợp không áp dụng cho provider này.

Việc render Provider được đảm nhận bởi một Plugin có pluginType: provider; xem entities/plugin.md để biết bề mặt soạn thảo Plugin render provider và 06-providers.md để xem các trang tham chiếu cho từng provider.

Mở rộng dựa trên annotation

Manifests mang một phần binding features.annotations: ánh xạ các khóa annotation tới các kiểu Feature, cùng với một bảng định tuyến nhóm theo trụ cột (maps.infra / maps.values) chỉ rõ những thuộc tính schema Feature nào mà mỗi binding có thể điền. Được mô tả trong entities/manifest.md và providers/well-known-annotations.md; vị trí trong pipeline tại ../architecture/10-compilation-pipeline.md; cơ chế lúc tải catalog và lúc inspect tại ../architecture/13-catalog-and-registry.md §“Annotation-driven Feature expansion”.

  • Các binding features.annotations của Manifest — đã có. Giai đoạn con mở rộng annotation của bước phân giải đã được phát hành đầy đủ từ đầu đến cuối. Nó duyệt các ranh giới Release (từ ngoài vào trong) và các hệ thống con Aggregate (từ ngoài vào trong), tính tập annotation hiệu lực cho từng component thông qua cascade + override với cơ chế opt-out bằng null cho toàn bộ giá trị và cho từng khóa con, phân tích mỗi giá trị annotation thành một scalar, một map có cấu trúc hoặc một null tường minh, định tuyến theo từng khóa con qua khai báo maps của binding với việc kiểm soát phía so với trụ cột (phía Aggregate kích hoạt maps.values; phía Release kích hoạt maps.infra), xác thực kiểu của từng lá theo spec.schema của Feature đích, và chèn các gắn kết Feature tổng hợp mà đồ thị IR đánh dấu bằng origin: annotation. Việc kết hợp giữa hai phía được hợp nhất theo từng trụ cột, từng trường tại thời điểm xây dựng IR, với giá trị tường minh thắng theo từng trường; aggrega inspect hiển thị dấu ngoặc nguồn gốc cho từng lá. Việc xác thực đích binding lúc tải catalog, lint chồng lấn trụ cột schema và lint chồng lấn bản đồ binding kiểm soát lộ trình này. Tiền tố aggrega.ai/ trần bị từ chối khi tải Manifest nếu được dùng làm khóa binding — tiền tố đó được dành riêng cho các annotation gốc của nền tảng; các binding dùng feature.aggrega.ai/ hoặc một tên miền tùy chỉnh.

Khớp phiên bản

Các Recipes và FeatureRecipes khai báo giao diện Component hoặc Feature mà chúng triển khai thông qua từ khóa implements:. implements: không bao giờ chọn một Recipe: ánh xạ của Manifest mới làm việc đó, và một instance có kiểu không được ánh xạ nào bao phủ sẽ dừng với một lỗi liệt kê các Recipes có implements: có thể triển khai kiểu đó làm ứng viên. Điều mà implements: chi phối là phép kiểm tra rằng Recipe của mỗi mục ánh xạ trong Manifest triển khai kiểu được ánh xạ, hoặc một kiểu cơ sở mà kiểu đó extends. Kiểu được ánh xạ là khóa của mục và, với một khóa components.type, cũng là kiểu của mỗi instance component mà khóa đó chạm tới ở một phiên bản khóa không nêu — mọi instance mà nó chạm tới, với một khóa được viết không kèm phiên bản — tại phiên bản mà quá trình build biên dịch instance đó: phiên bản mà instance nêu, hoặc, với một instance không nêu phiên bản nào, phiên bản cao nhất của Component đó mà catalog có. Trạng thái theo từng dạng:

  • Chính xác (core/api-server:1.0.0) — đã có. Kiểu được ánh xạ phải là đúng phiên bản đó.
  • Phạm vi tương thích major (core/api-server:^1.0.0) — đã có. Dạng dấu mũ là một ràng buộc SemVer (>=1.0.0, <2.0.0 trong ví dụ này); phiên bản của kiểu được ánh xạ phải thỏa mãn nó.
  • Không phiên bản (core/api-server) — đã có. Bất kỳ phiên bản nào của kiểu đều thỏa mãn nó.

Một mục ánh xạ mà implements: của Recipe không khớp với kiểu được ánh xạ cũng như bất kỳ kiểu cơ sở nào của nó sẽ dừng quá trình build với một OPS_ERROR nêu tên mục đó, Recipe và giá trị implements: của nó. Một instance component mà một khóa chạm tới ở một phiên bản khác, có phiên bản không được implements: của Recipe thỏa mãn, sẽ dừng quá trình build với cùng OPS_ERROR đó, nêu tên instance, kiểu của nó — và, với một instance không nêu phiên bản, phiên bản mà nó được biên dịch — khóa, Recipe và giá trị implements: của nó. Dạng dấu mũ là bề mặt soạn thảo chuẩn cho việc khớp tương thích major.

Xem vocabulary/inheritance-and-interface.md về bề mặt thiết kế implements: và entities/manifest.md về cấu trúc tầng ánh xạ theo từng Manifest.

Phong bì metadata

Các phong bì của thực thể catalog mang metadata.labels, metadata.annotations và (trên Release) metadata.environment. Trạng thái theo từng bề mặt:

Khả dụng của metadata.labels và metadata.annotations — trên bảy loại. Các phong bì thực thể mang các trường này là Component (labels bắt buộc, với khóa bắt buộc component.aggrega.ai/type, annotations tùy chọn), Feature (cả hai tùy chọn), bốn loại thư viện SchemaLibrary, MappingLibrary, WorkloadLibrary và ArtifactLibrary (cả hai tùy chọn), và Aggregate (chỉ labels, tùy chọn). Các thực thể còn lại — Recipe, FeatureRecipe, Manifest, Release, Plugin — không chấp nhận metadata.labels hay metadata.annotations ở cấp phong bì.

metadata.environment trên Release — bắt buộc. Schema của Release liệt kê environment là một trường metadata bắt buộc; quá trình build đóng dấu giá trị của nó lên đầu ra đã render dưới dạng label aggrega.ai/environment. Xem entities/release.md để biết năm trường hợp sử dụng thực tế của phần Environment Metadata (phân bổ chi phí OTel/FinOps, lọc trace/log OTel, nhắm mục tiêu operator Kubernetes, phân biệt production đa vùng, xác định phạm vi tuân thủ).

Xem 02-naming-conventions.md để biết nguyên tắc viết hoa tên trường áp dụng cho các khóa metadata, và các trang tham chiếu của từng thực thể để biết hình dạng phong bì mà mỗi thực thể hiện chấp nhận.

Các lệnh CLI

CLI của Aggrega đăng ký pipeline build cùng các lệnh introspection. Trạng thái theo từng lệnh:

  • aggrega build — đã có. Đọc một tệp Release, phân giải Aggregate + Manifest, chạy pipeline biên dịch, ghi các artifact đã render vào các thư mục đầu ra của boundary. Khi có lockfile, lệnh kiểm tra các phụ thuộc theo lockfile đó; khi không có, lệnh dừng và yêu cầu chạy pull, hoặc tạo lockfile trước nếu --auto-pull hoặc auto_pull yêu cầu.
  • aggrega inspect — đã có. Kiểm tra một thực thể catalog, một tệp thực thể, một thực thể đã xuất bản trong registry, hoặc một Release, và báo cáo hình dạng đã phân giải của nó. Xem cli/aggrega-inspect.md.
  • aggrega pull — đã có. Phân giải mọi phụ thuộc của một Release và ghi một lockfile cho từng Release, ghim mọi thực thể catalog và artifact nguồn vào một phiên bản và content digest, và mọi đầu vào bên ngoài mà quá trình render của Release yêu cầu vào một content digest; lưu nội dung đã tải vào bộ đệm tại .aggrega/cache. --verify kiểm tra một lockfile hiện có so với trạng thái hiện tại. Xem cli/aggrega-pull.md.
  • aggrega push — đã có. Xuất bản một thực thể catalog lên registry OCI; aggrega push --list-kinds báo cáo các kind mà lệnh chấp nhận. Xem cli/aggrega-push.md.
  • aggrega lint — đã có. Chạy các quy tắc kỷ luật xuất bản ở mức nghiêm trọng warn trên toàn bộ catalog, bao đóng phụ thuộc của một Release, hoặc một thực thể; trên một thực thể, --pre-publish thêm một bước kiểm tra tăng phiên bản so với phiên bản hiện đang xuất bản của thực thể, và sự không khớp sẽ làm dừng. Các quy tắc được cung cấp dưới dạng một Wasm plugin tùy chọn bật. Xem cli/aggrega-lint.md.
  • aggrega serve — đã có. Một daemon trình biên dịch dạng dịch vụ chạy lâu dài, giao tiếp JSON-RPC 2.0 qua stdin/stdout, dùng cho tích hợp với trình soạn thảo và IDE. Xem cli/aggrega-serve.md để biết các phương thức mà nó phục vụ.
  • aggrega version — đã có. In phiên bản CLI; -o json xuất một đối tượng phiên bản mà máy đọc được.
  • aggrega validate — đã có. Kiểm tra tính đúng đắn trên toàn bộ catalog, một Release, hoặc một thực thể đơn lẻ, báo cáo các chẩn đoán mà không render artifact.
  • aggrega search — đã có. Tìm kiếm các thực thể đã xuất bản trong chỉ mục cục bộ của các registry đã cấu hình; chỉ mục được xây dựng và làm mới bởi aggrega registry update.
  • aggrega registry — đã có. Quản lý các registry và chính sách tin cậy chữ ký của chúng; registry add ghi nhận một registry, và registry update xây dựng chỉ mục cục bộ mà aggrega search truy vấn.
  • aggrega push-artifact — đã có. Xuất bản một artifact dữ liệu độc lập (chẳng hạn một gói tài liệu) lên registry OCI, bên cạnh lệnh push dùng để xuất bản thực thể.
  • aggrega sign — đã có. Ký một hoặc nhiều artifact đã xuất bản và đính kèm chữ ký của chúng.
  • aggrega deprecate — đã có. Đính kèm một dấu đánh dấu ngừng hỗ trợ đã ký vào một artifact đã xuất bản.
  • aggrega login và aggrega logout — đã có. Xác thực với một registry OCI và lưu thông tin xác thực, hoặc xóa một thông tin xác thực đã lưu.
  • aggrega auth — đã có. Quản lý danh tính ký cục bộ dùng để ký artifact.
  • aggrega config — đã có. Kiểm tra và quản lý cấu hình workspace; các lệnh con hiển thị cấu hình hợp nhất có hiệu lực và nguồn gốc của từng thiết lập, khởi tạo một cấu hình làm việc với một registry và chính sách tin cậy chữ ký của nó, và cố định cấu hình quan trọng cho build đang có hiệu lực vào workspace để workspace build giống hệt nhau mà không phụ thuộc vào cấu hình toàn cục của máy.
  • aggrega get-schema — đã có. In JSON Schema cho một kind thực thể hoặc kind hợp đồng.
  • aggrega plugin — đã có. Kiểm tra các Wasm plugin mà CLI có thể phân giải; các lệnh con liệt kê chúng, thêm và xóa các plugin đã cấu hình, đồng bộ các bản ghi do máy quản lý của một plugin, và tạo một chế độ xem catalog của chúng.
  • aggrega cache — đã có. Kiểm tra và bảo trì các bộ đệm trên đĩa; các lệnh con báo cáo trạng thái, cắt tỉa, loại bỏ và xóa sạch.
  • aggrega mcp — đã có. Chạy một máy chủ Model Context Protocol qua stdio, hoặc qua HTTPS cho một client trên máy khác, cung cấp khả năng introspection của trình biên dịch cho các tích hợp trợ lý AI.
  • aggrega completion — đã có. Tạo script tự động hoàn thành shell cho CLI.
  • Các lệnh con mở rộng CLI — đã có. Một Wasm plugin được xuất bản dưới dạng guest pluginType: cli được phân giải và đăng ký làm một lệnh con của aggrega, nhờ đó một phần mở rộng đã cài đặt chạy dưới dạng aggrega <extension> bên cạnh các lệnh tích hợp sẵn.
  • aggrega import — đã có. Chuyển một nguồn định nghĩa agent khai báo từ bên ngoài (Langflow, Flowise, n8n) thành các tệp soạn thảo Aggregate và Component dạng nháp, với một quyết định tái sử dụng catalog tất định có chấm điểm độ tin cậy được ghi lại cho từng node. Ánh xạ đặc thù theo định dạng được cung cấp bởi một plugin importer mà workspace phân giải cho định dạng nguồn — một plugin mà catalog của workspace chứa, hoặc một trong các importer Langflow, Flowise và n8n của trình biên dịch, được build và xuất bản cùng mỗi bản phát hành trình biên dịch. Tệp nhị phân mang các thực thể Plugin của chúng nhưng không mang module của chúng, nên chúng phục vụ định dạng của mình trong mọi workspace: lần import đầu tiên cần đến một importer mà máy chưa có sẽ tải nó từ registry mặc định của workspace, xác minh nó và giữ nó trong bộ đệm nội dung cho mọi lần import sau. Một nguồn được phân tích qua parser mà catalog của workspace cung cấp cho cú pháp của nó, hoặc, khi catalog không cung cấp parser nào, qua parser mà trình biên dịch mang theo, nên một workspace có catalog không chứa parser nào vẫn import được qua một trong hai.
  • aggrega scaffold — đã có. Soạn một tài liệu khởi đầu cho bất kỳ loại thực thể nào từ schema của loại đó — mọi trường mà nó yêu cầu, với một placeholder ở nơi cần giá trị — và ghi nó ra đầu ra chuẩn; với --example, ghi một trong các ví dụ có thể chạy của tài liệu, được đọc từ gói tài liệu đã ký, vào một thư mục mới.
  • aggrega explain — đã có. Giải thích điều kiện dừng mà một mã ngắn (chẳng hạn E0007) hoặc một mã mô tả chỉ ra.
  • aggrega edit-document — đã có. Áp dụng một chỉnh sửa có cấu trúc, có giới hạn vào một tài liệu — thêm một component, gắn một Feature, nối một kết nối hoặc đặt một giá trị — giữ nguyên mọi byte mà nó không chạm tới.
  • aggrega pin — đã có. Ghi lại, trong entity.lock bên cạnh một Recipe hoặc FeatureRecipe, ghim nội dung cho mọi đầu vào mà thực thể đọc từ bên ngoài tài liệu của chính nó.
  • aggrega skills — đã có. Cài đặt skill Aggrega vào một trợ lý AI.

Xem 07-cli.md để biết tổng quan về CLI và chỉ mục Language Reference để xem mọi trang tham chiếu theo từng lệnh.

Trình soạn thảo và các frontend khác

Mọi frontend đều hiển thị những gì tệp nhị phân aggrega đã biên dịch; không frontend nào mang trình biên dịch riêng. Trạng thái theo từng bề mặt:

  • Hợp đồng đồ thị IR — đã có. Lược đồ đồ thị IR, hợp đồng mà mọi frontend dựa vào để đọc đồ thị, được phát hành như một phần của bản phân phối lược đồ Aggrega; xem tài liệu tham chiếu lược đồ IR.
  • Đọc đồ thị từ một lệnh — đã có. aggrega build chấp nhận --ir-graph, và aggrega inspect khi được cho một Release cũng như aggrega validate --release cũng vậy; cờ này ghi đồ thị mà lần chạy đó đã phân giải ra stdout dưới dạng JSON, bên cạnh mọi thứ lệnh vốn đã tạo ra. Một phiên daemon đọc cùng đồ thị đó tại aggrega/irGraph, và các công cụ cli-inspect, cli-build và cli-validate của máy chủ MCP nhận nó làm đối số ir_graph.
  • Đồ thị cấu trúc liên kết trong Visual Studio Code — đã có. Tiện ích mở rộng Aggrega cho Visual Studio Code vẽ đồ thị IR của Release đã chọn thành một đồ thị tương tác và gắn Features từ đó, yêu cầu daemon aggrega serve cho cả hai việc.
  • Chế độ truyền luồng CLI không giao diện — đã lên kế hoạch. Chế độ không giao diện xuất đồ thị IR dưới dạng JSON phân tách bằng dòng mới ra stdout để frontend sử dụng khi cấu trúc liên kết thay đổi. Những gì được phát hành hiện nay là một tài liệu cho mỗi lần gọi thay vì một luồng: không lệnh nào xuất một chuỗi đồ thị trên cùng một stdout khi cấu trúc liên kết thay đổi.

Xem ../architecture/15-editors-assistants-and-frontends.md để biết cách trình soạn thảo, trợ lý và daemon tiếp cận trình biên dịch.

Các hướng thiết kế

Phân loại trạng thái ở trên phân loại trạng thái của từng bề mặt trong toàn bộ ngôn ngữ; phần này ghi lại trạng thái của các hướng thiết kế rộng hơn được mô tả trong các chương kiến trúc.

Tuân thủ trên toàn hệ thống không phải là một hướng dự kiến: việc khai báo một quy tắc quản trị một lần để nó ràng buộc mọi bản build trong workspace đã có sẵn ngày nay thông qua socket quản trị. Một plugin được gắn tại khóa plugins.governance của cấu hình workspace sẽ đánh giá mọi bản build trong workspace đó — một vai trò phán quyết từ chối một đồ thị hoặc một artifact đã render vi phạm quy tắc, một vai trò biến đổi cung cấp metadata dẫn xuất mà nhà phát triển không bao giờ phải gõ. Xem ../architecture/11-governance-and-compliance.md.

  • Tương đương giao diện và tự động triển khai — đã có. Một Recipe được viết cho một Component cơ sở phục vụ mọi Component mở rộng nó, ở bất kỳ độ sâu nào của chuỗi, mà Architect không cần tạo một Recipe trùng lặp. Component mở rộng viết schema: inherited, nên nó không thêm vào values / infra / provides khóa gốc nào mà Recipe của cơ sở không thể sử dụng; một Component khai báo extends cùng với schema riêng của nó sẽ bị từ chối tại phong bì tài liệu của nó. Manifest vẫn ánh xạ kiểu mở rộng bằng một mục riêng, và phép kiểm tra ánh xạ chấp nhận nó khi implements của Recipe được ánh xạ nêu tên kiểu đó hoặc bất kỳ kiểu cơ sở nào mà nó mở rộng. Được mô tả trong ../architecture/02-ecosystem-philosophy.md.
  • Ghost Infrastructure Tracker — đã có. Một cơ chế bảo vệ ở giai đoạn render phát ra cảnh báo khi một khóa do tác giả khai báo đến được một nút mà không template nào do Recipe được liên kết khai báo đọc nó, nhờ vậy một giá trị do tác giả khai báo và bị template âm thầm bỏ qua sẽ được nêu tên thay vì bị mất. Đây là nửa thuộc giai đoạn render của cùng một thiết kế khớp hình dạng. Xem errors/warnings.md.

Các chương kiến trúc mô tả các bề mặt thiết kế; trang này theo dõi trạng thái triển khai.