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.

Bề mặt xuất bản

Mọi tệp YAML danh mục của Aggrega đều mang một tập trường siêu dữ liệu thống nhất mô tả thực thể cho việc phân phối danh mục: ai bảo trì nó, nó được phát hành theo giấy phép nào, mã nguồn của nó nằm ở đâu, những từ khóa nào giúp tìm thấy nó. Cùng nhau, các trường này tạo thành bề mặt xuất bản — bộ từ vựng siêu dữ liệu mà các nhà xuất bản danh mục và các công cụ sử dụng dựa vào, khác với cơ chế metadata.labels / metadata.annotations ở phía nội dung được mô tả tại labels-and-annotations.md.

Trang này mô tả các trường của bề mặt xuất bản, danh mục các trường mô tả trong toàn bộ kho tài liệu (mô tả cấp envelope, cấp instance và cấp trường), mục đích sử dụng dự kiến và bên sử dụng đã được xác minh của trường maintainer, cùng các điểm bất đối xứng về trường bắt buộc theo từng thực thể (mỗi thực thể hiện yêu cầu những trường nào và các điểm bất đối xứng nào là có chủ ý).

Các trường của bề mặt xuất bản

Các trường sau xuất hiện trên mọi thực thể thuộc Domain 2 (Component, Feature) và Domain 3 (Recipe, FeatureRecipe, Plugin), cũng như trên Aggregate khi là một mô-đun tái sử dụng. Chúng cũng xuất hiện trên Manifest và Release, với ngữ nghĩa thu hẹp (ghi nhận thuộc về workspace thay vì xuất bản lên catalog).

TrườngLoạiMục đíchBên sử dụng
descriptionstringTóm tắt dễ đọc về thực thểThẻ hover trong trình soạn thảo (aggrega serve); công cụ describe mà trợ lý gọi (aggrega mcp); một annotation có thể tìm kiếm trên artifact đã xuất bản (aggrega push); aggrega inspect
maintainersmảng các đối tượngAi sở hữu thực thể (tên, email, url)catalog_metadata theo từng nút trong IR, trên các nút Component
licensestringTuân thủ pháp lý (thường là mã định danh SPDX)catalog_metadata theo từng nút trong IR, trên các nút Component
repositorystring (URL)Kho Git chứa mã nguồncatalog_metadata theo từng nút trong IR, trên các nút Component — không có gì khác đọc nó
homestring (URL)URL tài liệu / wikicatalog_metadata theo từng nút trong IR, trên các nút Component — không có gì khác đọc nó
keywordsmảng các chuỗiThẻ phục vụ khám phácatalog_metadata theo từng nút trong IR, trên các nút Component — không có chỉ mục tìm kiếm nào sử dụng chúng

Cả sáu trường đều không bắt buộc trên mọi thực thể có chúng. Một tác giả catalog bỏ qua toàn bộ nhóm trường vẫn tạo ra một YAML hợp lệ — bề mặt xuất bản dành cho các thực thể dự định phân phối qua catalog; các thực thể dùng nội bộ có thể bỏ qua mà không gây hậu quả gì.

Cột Bên sử dụng liệt kê đầy đủ những gì hiện được phát hành, và có hai hệ quả của nó đáng nói rõ, vì chúng thay đổi điều gì đáng để viết:

  • description là trường duy nhất có nhiều hơn một bên đọc. aggrega serve hiển thị nó trong thẻ hover cho Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest và bốn loại thư viện (SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) — không cho Plugin hay Release. Công cụ describe mà aggrega mcp cung cấp trả về nó cho thực thể thuộc bất kỳ loại nào. aggrega push gắn nó lên artifact đã xuất bản dưới dạng annotation có thể tìm kiếm. aggrega inspect in nó bên dưới phần tiêu đề của thực thể cho mọi loại, và không in trường nào khác của bề mặt xuất bản.
  • repository, home và keywords được kiểm tra hợp lệ và được mang theo, nhưng không có gì đọc chúng ngoài IR. Không có bề mặt liệt kê, trang catalog hay chỉ mục tìm kiếm nào sử dụng chúng. Việc viết chúng ghi lại nguồn gốc đi kèm thực thể và có thể đọc được từ đầu ra IR và từ một chính sách quản trị; nó không làm cho thực thể có thể được tìm thấy ở bất kỳ đâu.

Ngừng hỗ trợ (deprecation) không phải là một trường của bề mặt xuất bản. Một thực thể bị đánh dấu ngừng hỗ trợ bằng cách ghi một dấu đánh dấu cho nó trong registry sau khi xuất bản — một dấu đánh dấu có chữ ký mang mức độ nghiêm trọng (warning, error hoặc retracted), lý do và phương án thay thế, được xác minh khi pull. Mọi bề mặt đọc lockfile khi đó đều báo cáo nó; build.halt_on_deprecated_severity chỉ quyết định liệu nó có dừng cả bản build hay không. Dấu đánh dấu không bao giờ được viết trong chính YAML của thực thể, và lý do mang tính cấu trúc: một artifact đã xuất bản là bất biến, nên một cờ được đóng băng vào đó lúc xuất bản không bao giờ có thể thể hiện một quyết định đưa ra sau này. Thông báo ngừng hỗ trợ mà aggrega inspect in ra cho một thực thể catalog đến từ dấu đánh dấu, cho mọi loại mà nó phân giải theo tên.

Việc IR sử dụng — catalog_metadata theo từng nút

Trình biên dịch mang các trường của bề mặt xuất bản từ mỗi Component vào khối catalog_metadata của nút đó, hiển thị trong đồ thị IR mà một lần chạy trả về (aggrega inspect <release> --ir-graph). Khối này chứa maintainers, license, repository, home và keywords — năm trường mà IR mang theo; description không nằm trong số đó. Công cụ xây dựng dựa trên hợp đồng đồ thị IR đọc metadata từ đó thay vì đọc lại YAML của catalog.

Chỉ các nút Component. Khối được điền bằng cách tra loại component của nút trong catalog như một Component, nên bề mặt xuất bản của một Feature, Recipe, FeatureRecipe hay Plugin không bao giờ đến được IR — các thực thể đó mang các trường và các trường được kiểm tra hợp lệ, nhưng không có nút IR nào được tạo ra từ chúng.

catalog_metadata bị loại bỏ hoàn toàn khỏi JSON của IR khi mọi trường bề mặt xuất bản trên Component nguồn đều rỗng hoặc bằng không: khối bị bỏ qua thay vì được xuất ra với các giá trị rỗng. Do đó cùng một đầu vào cho ra cùng một đầu ra gọn, giúp diff của IR ổn định giữa các lần chạy.

Một chính sách quản trị có thể đọc khối này. Một plugin gắn dưới plugins.governance với vai trò ir-verdict nhận toàn bộ đồ thị IR, từng nút một, bao gồm catalog_metadata của mỗi nút Component — nên một chính sách có thể chấp nhận hoặc từ chối một bản build dựa trên license, repository, home, keywords hoặc maintainers của một nút. Khả năng truy cập đó chỉ có ở socket quản trị: plugin kết xuất của một provider nhận một phép chiếu giới hạn theo từng nút không bao gồm catalog_metadata, nên các plugin kết xuất không thể đọc các trường này.

Ba loại mô tả

Trường description xuất hiện thống nhất trên envelope, nhưng kho tài liệu còn chứa các chuỗi kiểu mô tả bên trong các khai báo schema (mô tả theo từng trường) và bên trong phần thân của pillar (mô tả theo từng instance). Ba loại mô tả riêng biệt cùng tồn tại; bảng dưới đây phân biệt chúng.

LoạiVị tríNgười soạnMục đích
Mô tả envelopemetadata.description trên mọi entityNgười xuất bản catalogTóm tắt về toàn bộ entity, hiển thị trên thẻ hover của trình soạn thảo và được đóng dấu lên artifact đã xuất bản
Mô tả instanceTrường description bên cạnh một khai báo theo từng instance (ví dụ: featuresSchema.<slot>.description, usesSchema.<socket>.description)Tác giả schemaMô tả theo từng slot / socket / port, dành cho tác giả của các entity sử dụng khi đọc khai báo
Mô tả trườngChú thích description: của JSON Schema 2020-12 bên trong nội dung schema: / featuresSchema: / usesSchema: (dạng rút gọn hoặc YAML JSON Schema đầy đủ)Tác giả schemaTài liệu theo từng trường đi kèm với schema

Ba loại này dùng chung từ “description” nhưng nằm ở các cấp độ khác nhau về cấu trúc. Mô tả envelope áp dụng cho toàn bộ entity; mô tả instance áp dụng cho một khai báo bên trong một slot của schema; mô tả trường áp dụng cho một giá trị cụ thể bên trong một schema có kiểu. Khi viết một Component, tác giả:

  • Đặt metadata.description một lần cho chính entity Component.
  • Đặt featuresSchema.admin_password.description một lần cho mỗi slot thông tin xác thực mà Component khai báo.
  • Đặt các chú thích description: theo từng trường bên trong khối schema: — ở dạng rút gọn (port: { type: integer, description: "..." }) hoặc ở YAML JSON Schema đầy đủ — để ghi tài liệu cho từng trường cho bất kỳ ai đọc schema của Component.

Ba loại này không kế thừa lẫn nhau và không xung đột, và mỗi loại đến một bề mặt khác nhau — hoặc không đến bề mặt nào:

  • Mô tả envelope — thẻ hover của trình soạn thảo, các chú thích có thể tìm kiếm của artifact đã xuất bản, và aggrega inspect, theo cột Consumer ở trên.
  • Mô tả trường — xuất hiện nguyên văn trong đoạn trích schema mà thẻ hover của một Component hoặc một Feature hiển thị. Đoạn trích chỉ bao gồm spec.schema và bị cắt chỉ còn các dòng đầu, nên một mô tả nằm sâu hơn trong khối — hoặc nằm bên trong featuresSchema: hay usesSchema: — sẽ không xuất hiện ở đó.
  • Mô tả instance — được khai báo và mang theo cùng entity; không có bề mặt nào được phát hành tự hiển thị nó. aggrega inspect liệt kê các socket và feature slot của một Component mà không kèm mô tả của chúng.

Mục đích của trường maintainer

Trường maintainers chứa một mảng các đối tượng, mỗi đối tượng có name, email và url. Mục đích và bên tiêu thụ đã được xác minh:

Mục đích (mang tính thông tin + nguồn gốc trong IR). Trường này mang tính thông tin cho việc xuất bản catalog: mục đích kiến trúc là “ai chịu trách nhiệm cho thực thể catalog này” — một tín hiệu về quyền sở hữu đi kèm với thực thể. Không có bề mặt nào trình bày nó như một danh sách liên hệ, và không có kiểm tra tích hợp sẵn nào so sánh nó với bất cứ thứ gì.

Bên tiêu thụ đã được xác minh (catalog_metadata theo từng nút). Trình biên dịch đưa metadata.maintainers của mỗi Component vào catalog_metadata.maintainers của nút tương ứng trong IR, hiển thị trong đồ thị mà aggrega inspect <release> --ir-graph trả về khi Component nguồn có khai báo trường này. Đó là bên đọc duy nhất của trường này. Một chính sách quản trị được gắn dưới plugins.governance với vai trò ir-verdict sẽ thấy nó ở đó, nên một quy tắc về quyền sở hữu — mọi thực thể nêu tên ít nhất một maintainer, tên miền của maintainer khớp với một tập được phê duyệt — có thể được biểu đạt dựa trên IR thay vì dựa trên YAML của catalog. Không có quy tắc nào như vậy được cung cấp sẵn; socket là nơi đặt một quy tắc như thế.

Trình biên dịch không áp đặt hay xác thực nội dung maintainer ngoài cấu trúc của JSON Schema (name là bắt buộc; email và url là tùy chọn, cả hai đều là chuỗi). Việc các maintainer được liệt kê có thực sự sở hữu thực thể hay không, email của họ có liên lạc được hay không, một commit trong kho mã có được ký bởi một trong số họ hay không — đây là các vấn đề quản trị catalog, và không có kiểm tra nào được cung cấp sẵn đánh giá bất kỳ vấn đề nào trong số đó. Chúng thuộc về một chính sách quản trị do người vận hành gắn vào, không thuộc về trình biên dịch.

Sự bất đối xứng của các trường bắt buộc

Các loại thực thể của Aggrega có tập trường bắt buộc hơi khác nhau trong JSON Schema của chúng. Phần lớn sự bất đối xứng là có chủ đích và phản ánh vai trò của thực thể.

Các trường bắt buộc theo từng thực thể (không tính apiVersion / kind / metadata.name / metadata.version, vốn được mọi thực thể yêu cầu như nhau):

Thực thểCác trường bắt buộc bổ sungLý do
Componentmetadata.labels.component.aggrega.ai/typeYêu cầu nhãn này đóng vai trò thiết yếu cho việc khớp selector: các chú thích usesSchema x-aggrega-selector: lọc các Components đích theo nhãn này; nếu thiếu nhãn, Component bị từ chối khi được nạp
Feature—Không có yêu cầu nhãn dành riêng; các Features được nhận diện bằng tên + nhà phát hành
Recipespec.capability, spec.implementsCapability kiểm soát việc điều phối provider; implements kiểm soát việc gắn kết Component
FeatureRecipespec.capability, spec.implementsGiống Recipe
Pluginmetadata.pluginType, spec.abiVersionLoại socket mà plugin triển khai (thuộc khối định địa chỉ, cung cấp phân đoạn <pluginType> của tọa độ dẫn xuất plugin/<pluginType>/<name>) và phiên bản ABI mà nó nhắm tới; vị trí .wasm được dẫn xuất từ định danh đó chứ không do tác giả viết; một plugin kết xuất provider (pluginType: provider) còn mang thêm hợp đồng dịch của nó trong spec.provider
Aggregate—Một Aggregate không khai báo components, subsystems hay aggregates nào vẫn được nạp và build, và không kết xuất gì cả
Manifestspec.mappingsCác tầng ánh xạ là mục đích duy nhất của Manifest
Releasespec.aggregate, spec.manifest (một Release khai báo extends không ghi aggregate và có thể bỏ qua manifest); metadata.environmentHai trường đầu gắn quá trình build với một Aggregate + Manifest cụ thể; environment được đóng dấu lên đầu ra đã kết xuất dưới dạng nhãn aggrega.ai/environment

Yêu cầu nhãn của Component đóng vai trò thiết yếu

Nhãn component.aggrega.ai/type là nhãn duy nhất mà Aggrega yêu cầu trên bất kỳ thực thể nào. Yêu cầu này tồn tại vì cơ chế usesSchema của thư viện chuẩn lọc các ứng viên đích thông qua các chú thích x-aggrega-selector: mang chuỗi selector như "component.aggrega.ai/type=database" — selector tra cứu nhãn của đích để xác định loại có khớp với các loại mà socket chấp nhận hay không. Schema của Component thực thi điều này: một Component bỏ qua nhãn này sẽ bị từ chối khi được nạp (E0215), kèm tên khóa bị thiếu.

Do đó, yêu cầu này không phải là mối quan tâm của bề mặt xuất bản (nhãn không dùng để khám phá trong catalog) mà là mối quan tâm về topology: mọi Component đều mang nhãn này, kể cả các Components dùng nội bộ không nhắm tới việc phân phối qua catalog.

metadata.environment của Release là bắt buộc

Schema của Release yêu cầu metadata.environment, một chuỗi mà bản build đóng dấu lên đầu ra đã kết xuất dưới dạng nhãn aggrega.ai/environment.

Các bất đối xứng khác

Các bất đối xứng còn lại (trường bắt buộc của Recipe so với Component, yêu cầu mappings của Manifest) phản ánh vai trò của từng thực thể. Tác giả muốn có một hợp đồng trường bắt buộc đồng nhất trên mọi loại thực thể sẽ không tìm thấy điều đó; các bất đối xứng là có chủ đích theo thiết kế dựa trên vai trò.

Tham chiếu chéo

  • labels-and-annotations.md — cơ chế siêu dữ liệu phía nội dung, bổ sung cho bề mặt xuất bản.
  • entities/component.md — yêu cầu metadata.labels.component.aggrega.ai/type của Component và các khai báo schema / usesSchema / featuresSchema.
  • entities/release.md — trường metadata.environment của Release và yêu cầu bắt buộc của nó.
  • 10-status.md — trạng thái của envelope metadata.
  • architecture/02-ecosystem-philosophy.md — Phân vùng API nghiêm ngặt và cách định hình thiết kế Bộ siêu dữ liệu doanh nghiệp.
  • architecture/13-catalog-and-registry.md §“Lockfile pinning and artifact immutability” + §“Catalog entity name-shape enforcement” — những gì quy tắc bất biến từ chối tại thời điểm xuất bản, và nơi kiểm tra dạng tên theo từng loại thực thể: plugin kỷ luật xuất bản báo cáo chúng ở mức khuyến nghị khi tác giả chạy aggrega lint, còn cả việc build lẫn việc xuất bản đều không kiểm tra chúng.
  • architecture/11-governance-and-compliance.md §“Inheritance and publishing discipline” — những quy tắc quản trị nào thuộc về plugin kỷ luật xuất bản, và những quy tắc nào được cơ chế kế thừa của một Component mở rộng giải quyết ngay từ cấu trúc.