Schema cấu hình workspace của Aggrega
Tài liệu tham khảo được sinh tự động. Không chỉnh sửa thủ công — hãy sinh lại từ JSON Schema đã xuất bản.
Id của schema: https://aggrega.ai/schemas/aggrega-config-v1beta1.schema.json
Tệp cấu hình theo từng workspace mà CLI aggrega sử dụng. Nằm tại .aggrega-config.yaml. Khối workspace là dấu hiệu gốc: sự hiện diện của nó đánh dấu thư mục gốc của workspace, và nó chỉ chứa các thư mục catalog. Mọi khóa khác là một thiết lập và nằm ở cấp cao nhất, thuộc các nhóm sau — nội dung được lấy từ đâu, được ghim và lưu đệm như thế nào (chọn registry, chế độ ngoại tuyến, hành vi tự động pull và ghim, vị trí và giới hạn kích thước của bộ đệm artifact và bộ đệm module đã biên dịch), nội dung được tin cậy như thế nào (ký và hành vi xác minh chữ ký), việc soạn thảo được đánh giá nghiêm ngặt đến mức nào (các mức điều chỉnh lint theo từng quy tắc, mức nghiêm ngặt với phần đã lỗi thời, và gợi ý release khi soạn thảo), những Plugins Wasm nào được gắn trên toàn workspace (governance, linter, importer, và các ràng buộc Provider-rendering theo từng target), và CLI chạy như thế nào (mức đồng thời, phục vụ, và các giới hạn loại bỏ của bộ đệm phân tích cú pháp trong daemon). Các thuộc tính bên dưới là danh sách đầy đủ và có thẩm quyền; phần tóm tắt này nêu tên các nhóm chứ không nêu tên các khóa, nên việc thêm một khóa không thể làm nó sai. Cấu trúc phẳng ở cấp cao nhất, không có lớp bao apiVersion/kind, tách biệt với nội dung catalog. Nguyên tắc tiến hóa schema: thêm một khóa mới ở cấp cao nhất là một lần tăng SemVer-MINOR (bổ sung); xóa hoặc di chuyển một khóa, hoặc thắt chặt một ràng buộc, là một thay đổi phá vỡ SemVer-MAJOR.
Kiểu cấp cao nhất: object
Thuộc tính
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
workspace | object | không | Dấu hiệu gốc của workspace. Chỉ riêng sự hiện diện của nó đã đánh dấu thư mục là gốc của workspace; nó chỉ chứa các thư mục catalog xác định gốc — thư mục của chính workspace, và bất kỳ thư mục nào một Release được cấp cho riêng nó. Mọi thiết lập không xác định gốc đều nằm ở cấp cao nhất thay vì ở đây. Viết workspace: {} để đánh dấu một gốc không có thư mục catalog vendored nào. |
default_registry | string | không | Registry OCI mặc định mà các thực thể được xuất bản lên và các phụ thuộc được phân giải từ đó khi một thực thể không nêu rõ registry: aggrega push xuất bản lên đó và aggrega pull tải về từ đó. Mặc định là hub.aggrega.ai. Hãy viết name của một mục trong registries, khi đó nó đại diện cho host của mục đó; hoặc chính host; hoặc host theo sau bởi / và một đường dẫn repository, chẳng hạn ghcr.io/acme hoặc harbor.example.com/platform. Tên được so khớp trước: một giá trị là name của một mục chính là host của mục đó, ngay cả khi nó cũng được viết giống một host, vì vậy việc xuất bản, kéo về, xác minh chữ ký và mọi thiết lập tin cậy theo từng registry đều dùng đúng host đó; một giá trị trùng tên với hai mục bị từ chối vì mơ hồ, và một tên theo sau bởi đường dẫn bị từ chối, vì một tên đại diện cho host của một mục chứ không phải cho một vị trí bên dưới nó. Mọi giá trị khác phải là một host, được viết theo cách viết mà chính sách tin cậy của nó được lưu: một tên host chữ thường có chứa dấu chấm (registry.example.com), localhost, một tên đơn theo sau bởi cổng (registry:5000), một địa chỉ IPv4, hoặc một địa chỉ IPv6 trong ngoặc vuông ([::1]), mỗi loại có thể kèm :port tùy chọn và không có scheme, thông tin xác thực, khoảng trắng hay chữ in hoa — có thể theo sau bởi một đường dẫn repository: một hoặc nhiều đoạn gồm chữ thường và chữ số nối với nhau bằng /, bên trong một đoạn có thể được phân tách bằng ., _, __ hoặc dấu gạch ngang, không có tag, digest hay / ở cuối. Đường dẫn là nơi mọi thứ được xuất bản và tải về: mọi thực thể được xuất bản qua registry mặc định đều được xuất bản dưới <host>/<path>/, và mọi thực thể được phân giải qua nó đều được tải về từ đó, nên thứ mà bên này xuất bản thì bên kia tìm thấy. Nó không bao giờ là một phần của cách một registry được tin cậy: mục registries có chính sách được áp dụng, việc đăng nhập, yêu cầu ký và các danh tính tin cậy đều được xác định chỉ bằng host. Cổng 443 trên một host được truy cập qua HTTPS là cổng mặc định của host đó, và việc viết nó ra bị từ chối, kèm theo cách viết không có cổng cần dùng; localhost và các địa chỉ loopback khác được truy cập qua HTTP thuần, nên ở đó 443 là một cổng bình thường và được giữ lại. Một giá trị rỗng không chỉ định registry mặc định nào. Giá trị được đánh giá khi cấu hình được nạp chứ không phải bởi schema này, vì mục mà một tên tham chiếu tới có thể được khai báo trong một tệp cấu hình khác: nó được đọc sau mọi tệp cấu hình và biến môi trường AGGREGA_DEFAULT_REGISTRY, và bị từ chối với cùng một thông báo bất kể nguồn nào đã đặt nó, có nêu tên tệp đó hoặc biến đó. Cờ --registry chỉ định đích xuất bản cho một lần gọi được so khớp với tên của các mục theo cùng cách; mọi giá trị khác mà nó mang có thể là một tham chiếu, và host mà tham chiếu đó chỉ định phải tuân theo cùng cách viết và là nơi bản xuất bản được đưa tới, không có đường dẫn repository. Host chỉ được đánh giá theo cách viết của nó: việc tên đó có phân giải được hay có registry nào phản hồi ở đó hay không thì không được kiểm tra. Mặc định: "hub.aggrega.ai" |
offline | boolean | không | Khi là true, bản build không liên hệ với bất kỳ registry nào; chỉ các artifact đã lưu cache và nội dung catalog vendored được tham khảo. Mặc định là false. Mặc định: false |
auto_pull | boolean | không | Khi là false (mặc định), aggrega build chỉ đọc: nó không bao giờ ghi các pin nguồn, và một lockfile theo từng release bị thiếu hoặc không đầy đủ sẽ dừng bản build một cách rõ ràng kèm một chẩn đoán yêu cầu chạy aggrega pull --release <release> trước. Khi là true, aggrega build chạy một bước pull ngay trong tiến trình trước khi build — phân giải các phụ thuộc của Release vào lockfile và cache — để bản build đầu tiên cho một Release không cần một bước pull riêng. Cùng tùy chọn cho một lần build này cũng có trên dòng lệnh dưới dạng aggrega build --auto-pull; pull vẫn là thành phần duy nhất ghi lockfile. offline: true không tắt bước pull: nó chạy trên những gì máy đã có — cache và các thư mục catalog cục bộ — mà không truy cập registry, và một tham chiếu không có ở nơi nào trong số đó sẽ dừng bản build với chính thông báo từ chối của pull nêu tên tham chiếu đó. Mặc định: false |
pin_sources_at_pull | boolean | không | Khi là false (mặc định), một lần pull không ghi pin nào bên cạnh thực thể: với một Recipe hoặc FeatureRecipe trong một thư mục catalog của workspace này mà Release build, nó dừng lại khi entity.lock bên cạnh thực thể không ghi pin cho từng đầu vào mà thực thể đọc — một source: từ xa có tọa độ được viết đầy đủ, một tệp mà một mục artifacts nhập vào, hoặc từng tệp của một source: cục bộ bên cạnh thực thể — nêu tên thực thể, từng đầu vào và loại của nó, và aggrega pin là bước ghi chúng. Pin là bước của tác giả thực thể, nên một thực thể chưa ai pin thì chưa sẵn sàng để sử dụng. Khi là true, mọi lần pull trong workspace này chạy bước đó thay thế, trên cùng các thực thể, ghi ra cùng các byte entity.lock mà aggrega pin ghi; đây là cách một workspace sử dụng các thực thể mà người khác chưa pin ghi lại pin của chúng một lần thay vì dừng lại. Một bản build tự điền lockfile của mình là một lần pull và tuân theo thiết lập này. aggrega pull --pin-sources thực hiện pin cho một lần gọi và --pin-sources=false dừng lại cho một lần gọi, bất kể thiết lập này nói gì. Một thực thể được phân giải từ cache thay vì từ một thư mục catalog không có nơi để ghi lock và không bao giờ bị pin hay bị một lần pull chặn lại. Mặc định: false |
pin_sources_at_push | boolean | không | Khi là true, mọi aggrega push trong workspace này chạy bước pin của tác giả thực thể trên thực thể mà nó xuất bản trước khi đóng gói, để entity.lock mà bước đó ghi bên cạnh thực thể trở thành một phần của nội dung được xuất bản; khi là false (mặc định), push không chạy bước pin nào và từ chối một Recipe hoặc FeatureRecipe có entity.lock không ghi mọi pin mà bước đó sẽ ghi, kèm theo tên aggrega pin. Bước này ghi bên cạnh thực thể, nên nó chỉ chạy ở nơi thực thể có vị trí ghi được, điều mà một lần push luôn có: nó xuất bản một thực thể được chỉ định bởi tài liệu của nó. aggrega push --pin-sources thực hiện pin cho một lần gọi và --pin-sources=false thì không, bất kể thiết lập này nói gì. Đây chính là bước mà aggrega pin chạy, ghi ra cùng các byte. Mặc định: false |
artifact_cache_dir | string | không | Thư mục cache artifact/nội dung cục bộ (các lần pull từ registry, OCI manifests, fixture đã biên dịch). Mặc định là .aggrega/cache. Theo quy ước nên được đưa vào gitignore. Đường dẫn được hiểu tương đối với gốc workspace, bất kể lệnh được chạy từ đâu; một giá trị tuyệt đối bị từ chối khi cấu hình được nạp, vì mọi thành phần đọc thiết lập này đều phân giải nó theo gốc đó và một đường dẫn tuyệt đối sẽ chỉ tới một vị trí mà chúng không bao giờ đến. Cache có thể nằm bên trong một thư mục catalog — mặc định là như vậy, vì thư mục catalog thường chính là gốc workspace — nhưng nó không được LÀ một thư mục catalog: quá trình quét catalog bỏ qua cache, nên một giá trị chỉ tới một thư mục catalog sẽ loại toàn bộ nội dung của thư mục đó khỏi lần quét. Một giá trị chỉ tới chính gốc workspace (., hoặc bất kỳ cách viết nào rút gọn về nó) bị từ chối khi cấu hình được nạp, chính vì lý do đó. Một giá trị chỉ tới bất kỳ thư mục catalog nào khác thì không bị từ chối: nó được nạp bình thường và sau đó lần quét không tìm thấy gì trong thư mục đó, nên việc giữ cache nằm ngoài các thư mục được liệt kê trong workspace.catalog_dirs là việc bạn phải tự kiểm tra. Khác với parse_cache, vốn giới hạn cache phân tích cú pháp trong bộ nhớ của daemon, và với compiled_module_cache, vốn giới hạn kho module đã biên dịch dùng chung cho cả máy. Mặc định: ".aggrega/cache" |
skip_signature_verification | boolean | không | Tùy chọn tắt xác minh chữ ký trên toàn cục, một cách công khai. Khi là true, việc xác minh chữ ký bị tắt trên mọi registry, kể cả mức cơ sở bắt buộc của hub. Dành cho các tình huống khẩn cấp và phát triển; nó không bao giờ diễn ra âm thầm — ở bất cứ đâu một lần pull lẽ ra đã kiểm tra chữ ký, nó đều cảnh báo rằng việc xác minh đã bị tắt trên toàn cục. Mặc định là false. Mặc định: false |
build | object | không | Các núm điều chỉnh mức nghiêm ngặt lúc build và các gợi ý khi soạn thảo. authoring_release cung cấp cho LSP một gợi ý current Release cho các chẩn đoán nội tuyến; halt_on_deprecated_severity kiểm soát cách build phản ứng khi sử dụng entity đã bị deprecated; yaml_indent đặt độ rộng thụt lề của mọi artifact YAML được render. |
plugins | object | không | Các gắn kết Wasm plugin ở cấp workspace. Mỗi socket (governance, linter, importer) nhận một mảng tham chiếu plugin; build gọi hàm đầu vào đã được tài liệu hóa của từng plugin theo hợp đồng socket của nó. Danh sách providers liên kết các capability với các plugin render provider phục vụ chúng. |
lint | object | không | Các thiết lập mức độ nghiêm ngặt theo từng quy tắc. |
parse_cache | object | không | Các giới hạn loại bỏ của parse cache trong daemon. Cả hai giới hạn áp dụng đồng thời — vòng lặp loại bỏ LRU chạy sau mỗi lần chèn vào cache và xóa các mục ít được dùng gần đây nhất cho đến khi cả số lượng mục lẫn tổng số byte đều nằm trong giới hạn. Một giá trị bằng 0 nghĩa là unbounded on that axis, hữu ích cho các tình huống CI nơi cache chỉ tồn tại trong một lần gọi. Khác với artifact_cache_dir, vốn là cache nội dung trên đĩa. |
compiled_module_cache | object | không | Giới hạn kích thước cho cache module đã biên dịch trên đĩa, kho mã máy mà trình biên dịch tái sử dụng để một Wasm plugin được biên dịch một lần cho mỗi máy thay vì một lần cho mỗi build. Cache này được chia sẻ giữa mọi workspace trên máy, vì vậy khóa này nên nằm trong file config toàn cục khi bạn muốn một giá trị duy nhất cho cả máy. Giới hạn được áp dụng một lần cho mỗi lần gọi, trước khi bất kỳ plugin nào được nạp, bằng cách xóa toàn bộ các mục theo thứ tự biên dịch cũ nhất trước cho đến khi phần còn lại vừa giới hạn — không bao giờ trong lúc một build đang biên dịch. Xóa một mục chỉ tốn một lần biên dịch lại sau đó, không gì khác, nên có thể hạ giới hạn này một cách an toàn. aggrega cache status báo cáo kích thước hiện tại của kho, và aggrega cache evict --max-size cắt giảm nó theo yêu cầu xuống giới hạn được cho trên dòng lệnh. Khác với artifact_cache_dir (nội dung registry đã pull) và với parse_cache (parse cache trong bộ nhớ của daemon). |
concurrency | object | không | Các thiết lập đồng thời cho việc điều phối yêu cầu của daemon. Daemon đọc các yêu cầu từ một luồng stdin duy nhất và chạy từng yêu cầu qua một worker pool lấy dần từ một hàng đợi yêu cầu có giới hạn; các phản hồi được phát ra theo thứ tự yêu cầu đến, bất kể thứ tự hoàn thành. |
serve | object | không | Các thiết lập hành vi của daemon (aggrega serve) cho trình biên dịch dạng dịch vụ được các tích hợp IDE sử dụng. |
mcp | object | không | Các thiết lập cho máy chủ Model Context Protocol (aggrega mcp). transport chọn cách truy cập máy chủ — qua đầu vào và đầu ra chuẩn của tiến trình, hoặc qua HTTP — và được đọc bất kể chọn cách nào. announce_tools cũng được đọc trên cả hai transport, vì việc client được cung cấp những tool nào là thuộc tính của máy chủ chứ không phải của cách client truy cập nó. Mọi khóa khác cấu hình listener mà transport HTTP khởi động và không được dùng khi máy chủ giao tiếp qua đầu vào và đầu ra chuẩn — kể cả listen, vốn chỉ được đọc ở đó để máy chủ có thể thông báo, bằng một dòng trên luồng lỗi của nó, rằng địa chỉ này không được dùng. Mỗi khóa bên dưới cho biết nó thuộc loại nào. Khác với serve, vốn cấu hình daemon backend cho trình soạn thảo. |
registries | RegistryConfig[] | không | Các thiết lập theo từng registry và chính sách tin cậy chữ ký, được định khóa theo host của registry. Một registry không được liệt kê ở đây sẽ dùng các giá trị mặc định: chữ ký có mặt thì được xác minh và chữ ký vắng mặt thì được chấp nhận, ngoại trừ hub.aggrega.ai, có mức cơ sở nhúng sẵn bắt buộc phải có chữ ký đã xác minh ngay cả khi không có mục tường minh. Một mục tường minh cho một host sẽ ghi đè mức cơ sở của host đó. Mặc định: [] |
signing | SigningConfig | không | Khối ký ở cấp cao nhất, áp dụng cho mọi registry: các URL dịch vụ keyless, một đường dẫn khóa tùy chọn cho chế độ có khóa, và lập trường tin cậy cho mọi registry (required và kinds). Một khối signing theo từng registry ghi đè các endpoint mặc định cho host đó và mang cùng lập trường required/kinds giới hạn trong host đó — một tên, một nhiệm vụ, phạm vi theo vị trí đặt. Chính sách required/kinds ở cấp cao nhất kết hợp một cách đơn điệu qua chuỗi cascade cấu hình. Bảo mật: khối này không chứa dữ liệu bí mật — token định danh OIDC không bao giờ là một trường config (nó được cung cấp lúc chạy qua flag hoặc môi trường OIDC xung quanh) và key_path là đường dẫn đến một file khóa, không bao giờ là các byte khóa viết trực tiếp. |
Không cho phép thuộc tính bổ sung.
aggrega-config.workspace
Dấu hiệu gốc của workspace. Chỉ riêng sự hiện diện của nó đã đánh dấu thư mục là gốc của workspace; nó chỉ chứa các thư mục catalog xác định gốc — thư mục của chính workspace, và bất kỳ thư mục nào một Release được cấp cho riêng nó. Mọi thiết lập không xác định gốc đều nằm ở cấp cao nhất thay vì ở đây. Viết workspace: {} để đánh dấu một gốc không có thư mục catalog vendored nào.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
catalog_dirs | string[] | không | Các thư mục catalog tùy chọn mà workspace này đọc các thực thể cục bộ từ đó, được tra cứu trước khi chuyển sang registry. Mỗi mục là một đường dẫn hệ thống tệp, được phân giải tương đối với tệp khai báo nó. Danh sách là một ngăn xếp tìm kiếm có thứ tự theo kiểu mục đầu tiên thắng: thư mục được liệt kê sớm nhất khai báo một định danh sẽ sở hữu định danh đó, và cùng định danh ấy trong một thư mục sau sẽ bị che khuất. Thư mục catalog tại gốc workspace cũng được đọc, sau mọi mục được liệt kê và chỉ khi nó tồn tại — trừ khi một mục được liệt kê đã chứa nó, trong trường hợp đó nó được đọc như một phần của mục ấy — nên việc liệt kê một thư mục sẽ bổ sung vào những gì workspace đã đọc thay vì thay thế chúng. Bỏ qua khóa này và viết nó thành một danh sách rỗng là hai khai báo khác nhau: khi bỏ qua, workspace vẫn đọc catalog; khi viết là [], nó không đọc catalog cục bộ nào cả, đó là cách một workspace cho biết nó không có catalog nào. Một Release được cấp các thư mục catalog riêng dưới releases sẽ đọc các thư mục đó thay cho danh sách này. Phạm vi gốc: các thư mục catalog cục bộ thuộc về gốc workspace này, nên chúng nằm trên dấu đánh dấu gốc thay vì ở cấp cao nhất. |
catalog_dirs_append | string[] | không | Phần bổ sung tùy chọn, chỉ nối thêm, vào danh sách catalog_dirs hiệu lực. Tại mỗi lớp ưu tiên, các mục ở đây được nối vào sau danh sách cơ sở đã phân giải, cho phép cấu hình workspace và cấu hình toàn cục kết hợp các thư mục catalog thay vì che khuất nhau. Tương tác trong cùng một lớp: khi cả catalog_dirs và catalog_dirs_append được chỉ định ở cùng một lớp, giá trị phân giải tại lớp đó là danh sách cơ sở theo sau bởi danh sách nối thêm. Mặc định: [] |
releases | map của ReleaseCatalogConfig | không | Các thư mục catalog tùy chọn riêng của một Release, dành cho workspace giữ nhiều biến thể catalog song song và build mỗi Release dựa trên một trong số đó. Mỗi khóa là một tệp Release, được viết dưới dạng đường dẫn tương đối với tệp khai báo nó; mỗi giá trị mang catalog_dirs và catalog_dirs_append với ý nghĩa như trên khối này, giới hạn trong phạm vi Release đó. Một Release được nêu tên ở đây đọc catalog_dirs riêng của nó thay cho danh sách của khối này, theo sau là catalog_dirs_append riêng của nó; một mục bỏ qua catalog_dirs giữ danh sách của khối này và thêm catalog_dirs_append của nó vào sau. Thứ tự tìm kiếm, thư mục catalog tại gốc workspace, và ý nghĩa của một danh sách rỗng giống như đối với danh sách riêng của khối này, và một Release mà map này không nêu tên sẽ đọc danh sách của khối này đúng như trước. Release đọc các thư mục này bất kể nó được build theo cách nào — tại terminal, từ trình soạn thảo thông qua aggrega serve, hoặc thông qua aggrega mcp — và một thư mục --catalog vẫn được tìm kiếm trước chúng trong một lần gọi. Một mục nêu tên một tệp không tồn tại sẽ bị từ chối khi cấu hình được nạp, kèm tên mục và tệp, để việc đổi tên một Release không thể âm thầm thay đổi catalog mà nó build dựa trên. Giữa các tệp cấu hình, mục của mỗi Release kết hợp theo cách các khóa riêng của khối này kết hợp: catalog_dirs của tệp gần hơn cho Release đó thay thế của tệp xa hơn, và catalog_dirs_append của mọi tệp cho nó được thêm vào theo thứ tự tầng. AGGREGA_CATALOG_DIRS đặt danh sách của khối này và không tác động đến mục nào ở đây. Một thao tác không liên quan đến một Release đơn lẻ nào — lint hoặc xác thực toàn bộ catalog, tra cứu một thực thể theo tên, hoặc việc trình soạn thảo liệt kê các thực thể của workspace — đọc danh sách của khối này chứ không đọc các danh sách này. |
Không cho phép thuộc tính bổ sung.
aggrega-config.build
Các núm điều chỉnh mức nghiêm ngặt lúc build và các gợi ý khi soạn thảo. authoring_release cung cấp cho LSP một gợi ý current Release cho các chẩn đoán nội tuyến; halt_on_deprecated_severity kiểm soát cách build phản ứng khi sử dụng entity đã bị deprecated; yaml_indent đặt độ rộng thụt lề của mọi artifact YAML được render.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
authoring_release | string | không | Đường dẫn tới một tệp YAML của Release mà LSP coi là ngữ cảnh current Release cho các chẩn đoán nội tuyến. Tùy chọn. |
yaml_indent | integer | không | Độ rộng thụt lề (tính bằng dấu cách) cho mọi artifact YAML được render — các tệp docker-compose, template và values của Helm chart, và các manifest Kubernetes. Mặc định là 2, độ rộng theo quy ước cho các định dạng đó. Tối thiểu: 2. Tối đa: 9. Mặc định: 2 |
halt_on_deprecated_severity | string (enum) | không | Mức độ nghiêm trọng, trong tập có thứ tự warning < error < retracted, mà tại hoặc trên mức đó một dấu ngừng hỗ trợ đã được ghi nhận sẽ dừng build. Nó chi phối cả hai nơi một dấu được ghi nhận: lockfile, cho mọi thứ mà một build tái tạo chính xác từng byte, và bản ghi tin cậy plugin bên cạnh nó, cho một plugin được gắn ở vai trò trả về phán quyết chấp nhận hoặc từ chối — một phần gắn plugins.governance tại ir-verdict hoặc render-verdict, và mọi phần gắn plugins.linter. Một nút điều chỉnh, một quy tắc, cả hai kho lưu trữ. Mặc định không được đặt, và không đặt nghĩa là không dấu đã ghi nhận nào dừng build: một dấu được ghi nhận đối với một phiên bản bạn đã ghim, nên một build đã thành công một lần sẽ tiếp tục thành công. Thông báo và phân giải là hai trục riêng biệt và không trục nào là nút điều chỉnh này. Mọi bề mặt đọc một trong hai bản ghi đều báo cáo mọi tham chiếu ngừng hỗ trợ mà nó ghim và mọi plugin tin cậy mang dấu — ở mọi mức độ nghiêm trọng — nêu tên nó, mức độ nghiêm trọng và thông điệp của nó: aggrega build, aggrega validate --release, aggrega lint --release, daemon hướng tới trình soạn thảo, và các công cụ build, describe và validate dành cho AI. Vì vậy việc nâng ngưỡng này không bao giờ làm giảm những gì bạn được thông báo. Nút điều chỉnh này chỉ chi phối build: nó dừng aggrega build (và công cụ build dành cho AI, vốn là cùng một thao tác), trong khi các bề mặt báo cáo nêu tên dấu và tiếp tục. Chỉ một dấu retracted ảnh hưởng đến việc một tham chiếu phân giải tới phiên bản nào, và nó làm vậy khi aggrega pull chọn một phiên bản, không phải lúc build. Giá trị cho phép: "warning", "error", "retracted" |
Không cho phép thuộc tính bổ sung.
aggrega-config.plugins
Các gắn kết Wasm plugin ở cấp workspace. Mỗi socket (governance, linter, importer) nhận một mảng tham chiếu plugin; build gọi hàm đầu vào đã được tài liệu hóa của từng plugin theo hợp đồng socket của nó. Danh sách providers liên kết các capability với các plugin render provider phục vụ chúng.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
governance | PluginRef[] | không | Các plugin của socket governance. Mỗi mục nêu role trong pipeline mà nó được gắn vào (annotation-transform, label-transform, ir-verdict hoặc render-verdict); role này quyết định cả những gì plugin được phép phát ra lẫn hàm entry mặc định của nó (annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). Mặc định: [] |
governance_append | PluginRef[] | không | Phần bổ sung chỉ nối thêm vào danh sách governance hiệu lực. Các mục ở đây được nối vào danh sách gốc đã phân giải tại mỗi lớp ưu tiên, cho phép cấu hình workspace và cấu hình toàn cục kết hợp các gắn kết governance thay vì che khuất nhau. Mặc định: [] |
linter | PluginRef[] | không | Các plugin của socket linter. Hàm entry mặc định: lint_rules. Các export của một plugin linter bắt buộc phải bắt đầu bằng lint_, vì vậy function: trên một trong các mục này nêu một export có tiền tố đó. Mặc định: [] |
linter_append | PluginRef[] | không | Phần bổ sung chỉ nối thêm vào danh sách linter hiệu lực. Cùng ngữ nghĩa kết hợp chứ không che khuất như governance_append. Mặc định: [] |
importer | FixedEntryPluginRef[] | không | Các plugin của socket importer. Socket gọi hàm entry import; một gắn kết không nêu tên hàm. Mặc định: [] |
importer_append | FixedEntryPluginRef[] | không | Phần bổ sung chỉ nối thêm vào danh sách importer hiệu lực. Cùng ngữ nghĩa kết hợp chứ không che khuất như governance_append. Mặc định: [] |
providers | FixedEntryPluginRef[] | không | Lựa chọn provider theo từng capability. Mỗi mục gắn một capability của provider (tên capability trần mà một Recipe gắn qua spec.capability, ví dụ helm hoặc compose) với định danh trần của plugin render provider phục vụ nó (định danh của thực thể Plugin, tức metadata.pluginType và metadata.name nối với nhau bằng dấu gạch chéo, ví dụ provider/helm), kèm một :version tùy chọn ở cuối theo cùng ba dạng như một ghim phiên bản (trần, chính xác :1.0.0, hoặc khoảng tương thích major :^1.0.0). Đây là nơi phân định và ghi đè cho một catalog liên kết, nơi có nhiều plugin provider cùng phục vụ một capability: việc gắn kết chọn plugin của nhà phát hành nào sẽ render capability đó. Khi một capability chỉ được đúng một plugin provider phục vụ thì không cần mục nào. Mỗi capability chỉ được phép có đúng một mục trên toàn bộ danh sách đã kết hợp; một capability trùng lặp sẽ dừng việc phân giải một cách rõ ràng. Việc phân giải diễn ra lúc pull: lệnh pull ghi gắn kết đã phân giải vào lockfile của từng Release, và build đọc lockfile — một thay đổi ở đây sau khi pull sẽ không được áp dụng cho tới lần pull tiếp theo, nên đầu ra của build không bị ảnh hưởng bởi nó (đầu ra tất định). Mỗi lần build và mỗi lần kiểm tra hợp lệ một Release cũng kiểm tra từng mục ở đây, dù có Recipe nào yêu cầu capability của nó hay không: một mục nêu một plugin mà build đang có nhưng không phục vụ capability của mục đó sẽ dừng, nêu những gì plugin đó phục vụ và một cách viết cách một lần sửa nếu có; một mục nêu một capability mà không có plugin, khi không plugin provider nào build đọc phục vụ capability đó, được báo dưới dạng cảnh báo thay vì dừng, vì plugin phục vụ nó có thể chỉ được một Release khác đọc; và một mục cho một capability mà một plugin phục vụ nhưng Release này không bao giờ yêu cầu là hợp lệ và không được báo gì, vì các mục được viết cho toàn bộ workspace còn một lần build chỉ dành cho một Release. Một capability chứa dấu hai chấm sẽ bị từ chối khi cấu hình được tải: spec.capability của một Recipe được đọc là capability cho tới dấu hai chấm cuối cùng và một ghim phiên bản sau đó, nên không Recipe nào có thể chạm tới một mục như vậy. Thiếu mục cho một capability được phục vụ không mơ hồ không phải là lỗi; thiếu mục cho một capability được phục vụ mơ hồ sẽ dừng lệnh pull một cách rõ ràng, liệt kê các plugin ứng viên. Sự cùng tồn tại của các phiên bản được giữ nguyên: gắn kết chọn kho plugin theo từng capability, và ghim phiên bản trong spec.capability riêng của mỗi Recipe chọn phiên bản trong kho đó, nên hai Recipes ghim các phiên bản khác nhau của cùng một provider vẫn cùng tồn tại. Mặc định: [] |
providers_append | FixedEntryPluginRef[] | không | Phần bổ sung chỉ nối thêm vào danh sách providers hiệu lực. Các mục ở đây được nối vào danh sách gốc đã phân giải tại mỗi lớp ưu tiên, cho phép cấu hình workspace và cấu hình toàn cục kết hợp các gắn kết provider thay vì che khuất nhau. Cùng ngữ nghĩa kết hợp chứ không che khuất như governance_append. Quy định mỗi capability một mục áp dụng cho danh sách đã kết hợp, nên một mục nối thêm nêu một capability đã được một lớp thấp hơn gắn sẽ dừng việc phân giải một cách rõ ràng. Mặc định: [] |
cli | CLIPluginRef[] | không | Các plugin mở rộng CLI được cài đặt thành các lệnh aggrega cấp cao nhất. Mỗi mục ghim một plugin CLI bằng tham chiếu artifact đã phân giải và ghim phiên bản của nó, cùng digest nội dung của các byte guest mà tham chiếu đó phân giải ra lúc cài đặt. Khác với bốn danh sách socket xuyên suốt, vốn có danh sách gốc bị thay thế toàn bộ qua chuỗi cấu hình, danh sách CLI được kết hợp: một plugin CLI trong cấu hình toàn cục đăng ký (các) lệnh của nó trong mọi workspace, một plugin trong cấu hình workspace chỉ đăng ký trong dự án đó, và cả hai cùng được đăng ký — nên nó không cần bản đi kèm _append. Tên lệnh và phần trợ giúp mà mỗi plugin đóng góp đến từ bản tự mô tả của chính plugin, được đọc từ bộ đệm describe trên đĩa có khóa là digest (khi bộ đệm trống thì phương án dự phòng là tải guest); danh sách chỉ mang ghim. Khi gọi lệnh, các byte đã phân giải được băm lại và so sánh với digest; nếu không khớp, lệnh dừng một cách rõ ràng và hướng dẫn ghim lại, nên một plugin có byte đã thay đổi kể từ khi được ghim không bao giờ chạy mà không bị phát hiện. Mặc định: [] |
Không cho phép thuộc tính bổ sung.
aggrega-config.lint
Các thiết lập mức độ nghiêm ngặt theo từng quy tắc.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
publishing_discipline | object | không | Các cổng kiểm soát toàn workspace cho bộ quy tắc của publishing-linter. Các cờ allow_* nới lỏng từng kiểm tra không khuyến khích riêng lẻ. Tính bất biến của artifact không cấu hình được ở đây: aggrega push luôn từ chối ghi đè một phiên bản đã phát hành, vô điều kiện. |
Không cho phép thuộc tính bổ sung.
aggrega-config.lint.publishing_discipline
Các cổng kiểm soát toàn workspace cho bộ quy tắc của publishing-linter. Các cờ allow_* nới lỏng từng kiểm tra không khuyến khích riêng lẻ. Tính bất biến của artifact không cấu hình được ở đây: aggrega push luôn từ chối ghi đè một phiên bản đã phát hành, vô điều kiện.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
allow_dynamic_refs | boolean | không | Khi là true, publishing-linter chấp nhận các cấu trúc JSON Schema $dynamicRef / $dynamicAnchor trong nội dung catalog. Mặc định là false; các cấu trúc này không được khuyến khích vì chúng làm cho việc kết hợp schema tại thời điểm biên dịch trở nên không cục bộ. Mặc định: false |
allow_id_overrides | boolean | không | Khi là true, publishing-linter chấp nhận việc ghi đè $id trên các subschema trong nội dung schema của một thực thể. Mặc định là false; việc ghi đè $id phá vỡ quy ước mỗi schema một định danh chuẩn mà cả resolver lẫn trình xác thực JSON Schema đều dựa vào. Mặc định: false |
allow_direct_x_aggrega_extensions | boolean | không | Khi là true, phép kiểm tra không khuyến khích tại thời điểm build chấp nhận các từ khóa x-aggrega-selector và x-aggrega-inject được viết trực tiếp trong nội dung schema. Mặc định là false; cách viết được khuyến nghị là usesSchema (cho các socket phụ thuộc) hoặc featuresSchema (cho các liên kết thông tin xác thực), mà trình biên dịch kết hợp thành các từ khóa đó. Mặc định: false |
allow_aggrega_ai_prefix | boolean | không | Khi là true, publishing-linter chấp nhận các khóa annotation dùng các không gian tên dành riêng aggrega.ai/ và feature.aggrega.ai/ bên ngoài ngữ cảnh chuẩn của chúng. Quy tắc tiền tố dành riêng kiểm soát metadata.annotations của thực thể catalog: tiền tố aggrega.ai/ trần là gốc của nền tảng (các khóa annotation phổ biến được miễn bất kể cờ này); tiền tố feature.aggrega.ai/ chỉ là chuẩn trên kind Feature. Mặc định là false. Người vận hành đặt cờ này khi công cụ doanh nghiệp thực sự cần dùng một tiền tố dành riêng; cờ này nới lỏng cả hai tiền tố cùng lúc. Mặc định: false |
allow_nonstandard_names | boolean | không | Khi là true, publishing-linter chấp nhận các tên thực thể catalog không tuân theo các quy ước đặt tên được tài liệu hóa của dự án. Mặc định là false; việc đặt tên nhất quán đóng vai trò quan trọng đối với resolver, việc chọn theo nhãn và sự thuận tiện cho người review. Mặc định: false |
allow_category_mismatches | boolean | không | Khi là true, publishing-linter bỏ qua quy tắc category-matches-directory. Quy ước của catalog chuẩn yêu cầu các Components trong core/false |
allow_undeclared_recipe_provides | boolean | không | Khi là true, publishing-linter bỏ qua quy tắc provides-declared-by-component. Quy tắc đó báo cáo mỗi khóa mà một Recipe công bố trong spec.provides nhưng Component được nêu bởi spec.implements của nó không khai báo trong trụ cột provides của spec.schema của nó. Hai thứ này là các bề mặt riêng biệt: những gì một Recipe công bố là giá trị mà bên tiêu thụ nhận được, còn những gì Component khai báo là hợp đồng đầu ra mà một tham chiếu inject from: được kiểm tra đối chiếu — vì vậy một khóa được công bố mà không được khai báo sẽ làm tham chiếu như vậy dừng lại. Ngoài ra, một Recipe công bố nhiều hơn những gì Component của nó khai báo vẫn được chấp nhận tại thời điểm build, đó là lý do kết quả này chỉ mang tính khuyến nghị thay vì từ chối công bố. Mặc định là false. Mặc định: false |
allow_connection_credential_mismatches | boolean | không | Khi là true, publishing-linter bỏ qua quy tắc connection-credential-matches-target-key, quy tắc mà aggrega lint --release chạy trên Release mà nó chỉ định: Release đó, Aggregate mà nó triển khai và các Components mà các instance của Aggregate đó sử dụng. Với mỗi kết nối có đích khai báo khóa mà nó yêu cầu từ các bên gọi, quy tắc so sánh những gì hai đầu tham chiếu: thông tin xác thực mà kết nối xuất trình và khóa mà đích giữ trong slot riêng của nó. Quy tắc báo cáo trường hợp hai đầu nêu các secret khác nhau, và trường hợp một khóa chỉ được khai báo ở một đầu, và nó không bao giờ trích dẫn giá trị của bên nào. Không đầu nào thấy được các phần đính kèm của đầu kia, vì vậy hai đầu chỉ khớp nhau nhờ kỷ luật khi viết — thường là một tham số cấp cho cả hai — và một bản build chấp nhận chúng dù thế nào, đó là lý do kết quả này chỉ mang tính khuyến nghị. Một workspace có hai đầu cố ý khác nhau có thể chọn không áp dụng tại đây. Mặc định là false. Mặc định: false |
Không cho phép thuộc tính bổ sung.
aggrega-config.parse_cache
Các giới hạn loại bỏ của parse cache trong daemon. Cả hai giới hạn áp dụng đồng thời — vòng lặp loại bỏ LRU chạy sau mỗi lần chèn vào cache và xóa các mục ít được dùng gần đây nhất cho đến khi cả số lượng mục lẫn tổng số byte đều nằm trong giới hạn. Một giá trị bằng 0 nghĩa là unbounded on that axis, hữu ích cho các tình huống CI nơi cache chỉ tồn tại trong một lần gọi. Khác với artifact_cache_dir, vốn là cache nội dung trên đĩa.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
max_entries | integer | không | Giới hạn số lượng kết quả phân tích được lưu trong cache. Mặc định là 1000. 0 vô hiệu hóa trục số lượng mục (không có việc loại bỏ nào được kích hoạt bởi số lượng mục). Tối thiểu: 0. Mặc định: 1000 |
max_bytes | integer | không | Giới hạn tổng kích thước, tính bằng byte, của các tài liệu mà cache lưu giữ. Mặc định là 100000000 (100 MB). 0 vô hiệu hóa trục byte (không có việc loại bỏ nào được kích hoạt bởi tổng số byte). Tối thiểu: 0. Mặc định: 100000000 |
Không cho phép thuộc tính bổ sung.
aggrega-config.compiled_module_cache
Giới hạn kích thước cho cache module đã biên dịch trên đĩa, kho mã máy mà trình biên dịch tái sử dụng để một Wasm plugin được biên dịch một lần cho mỗi máy thay vì một lần cho mỗi build. Cache này được chia sẻ giữa mọi workspace trên máy, vì vậy khóa này nên nằm trong file config toàn cục khi bạn muốn một giá trị duy nhất cho cả máy. Giới hạn được áp dụng một lần cho mỗi lần gọi, trước khi bất kỳ plugin nào được nạp, bằng cách xóa toàn bộ các mục theo thứ tự biên dịch cũ nhất trước cho đến khi phần còn lại vừa giới hạn — không bao giờ trong lúc một build đang biên dịch. Xóa một mục chỉ tốn một lần biên dịch lại sau đó, không gì khác, nên có thể hạ giới hạn này một cách an toàn. aggrega cache status báo cáo kích thước hiện tại của kho, và aggrega cache evict --max-size cắt giảm nó theo yêu cầu xuống giới hạn được cho trên dòng lệnh. Khác với artifact_cache_dir (nội dung registry đã pull) và với parse_cache (parse cache trong bộ nhớ của daemon).
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
max_bytes | integer | không | Giới hạn số byte mà cache module đã biên dịch lưu giữ trên đĩa. Mặc định là 53687091200 (50 GiB), một mức trần để ngăn tăng trưởng không giới hạn chứ không phải một ngân sách nhằm để cảm nhận được — một plugin đã biên dịch đơn lẻ đạt tới hàng trăm megabyte, nên một máy build nhiều phiên bản plugin sẽ tích lũy hàng gigabyte. Hãy đặt nó cao hơn lượng mà một bản build biên dịch: giới hạn được áp dụng trước khi bản build biên dịch bất cứ thứ gì, nên một giới hạn thấp hơn tập làm việc của chính một bản build sẽ khiến mọi bản build loại bỏ và biên dịch lại cùng các module, và kho lưu trữ không còn tiết kiệm được gì. Vì giới hạn được áp dụng trước rồi bản build mới ghi những gì nó biên dịch, kho lưu trữ có thể vượt quá giới hạn giữa các bản build; nó được cắt giảm lại khi bắt đầu bản build tiếp theo. 0 vô hiệu hóa giới hạn (kho lưu trữ tăng không giới hạn và không có gì bị xóa tự động). Vì kho lưu trữ là một thư mục mà mọi workspace dùng chung, giới hạn này không theo từng dự án ngay cả khi tệp riêng của một dự án chứa nó: giá trị được phân giải giống như mọi khóa khác, với tệp gần hơn được ưu tiên, nhưng kho lưu trữ vẫn chỉ có một kích thước. Giới hạn có hiệu lực là giới hạn từ bản build gần nhất, nên hai dự án đặt giới hạn khác nhau sẽ lần lượt có hiệu lực, và một giới hạn thấp ở dự án này sẽ loại bỏ mã máy mà dự án kia đã biên dịch. Đặt nó một lần trong tệp cấu hình toàn cục là cách để cả máy có một giá trị duy nhất. aggrega config show --origin cho biết tệp mà giá trị hiệu lực của mỗi thiết lập đến từ đó. Tối thiểu: 0. Mặc định: 53687091200 |
Không cho phép thuộc tính bổ sung.
aggrega-config.concurrency
Các thiết lập đồng thời cho việc điều phối yêu cầu của daemon. Daemon đọc các yêu cầu từ một luồng stdin duy nhất và chạy từng yêu cầu qua một worker pool lấy dần từ một hàng đợi yêu cầu có giới hạn; các phản hồi được phát ra theo thứ tự yêu cầu đến, bất kể thứ tự hoàn thành.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
pool_size | integer | không | Số worker phục vụ hàng đợi yêu cầu. Mặc định là 4, cho phép xử lý đồng thời tối đa bốn yêu cầu; đặt thành 1 để chạy các yêu cầu tuần tự theo thứ tự đến. Giá trị nhỏ hơn 1 sẽ được nâng lên 1 khi daemon khởi động. Tối thiểu: 1. Mặc định: 4 |
Không cho phép thuộc tính bổ sung.
aggrega-config.serve
Các thiết lập hành vi của daemon (aggrega serve) cho trình biên dịch dạng dịch vụ được các tích hợp IDE sử dụng.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
build_on_inspect | boolean | không | Daemon có chạy giai đoạn kết xuất artifact khi kiểm tra một đồ thị IR hay không, để các cảnh báo mà aggrega build đưa ra trong lúc kết xuất cũng xuất hiện dưới dạng vấn đề trong trình soạn thảo. Tùy chọn này không thêm bất kỳ kiểm tra nào khiến bản build dừng lại. Trong cả hai trường hợp, không có gì được ghi ra đĩa — không có artifact đã kết xuất, không có thư mục đầu ra, không có lockfile — và giai đoạn kết xuất không bao giờ thay đổi đồ thị, nên khi lần kiểm tra trả về một đồ thị thì đó vẫn là cùng một đồ thị. Mặc định là false, khớp với aggrega inspect: lệnh trên terminal không đi tới giai đoạn kết xuất khi kiểm tra một đồ thị, nên cũng không đưa ra cảnh báo nào như vậy, và một lần kiểm tra trong trình soạn thảo không đưa ra cảnh báo nào sẽ cho bạn thấy đúng những gì terminal cho thấy. Đặt true để yêu cầu trình soạn thảo hiển thị lớp bổ sung đó. Mặc định: false |
lint_on_validate | boolean | không | Daemon có chạy kiểm tra quy ước xuất bản khi xác thực một thực thể catalog hay không, để các phát hiện mà aggrega lint báo cáo về thực thể đó cũng xuất hiện dưới dạng vấn đề trong trình soạn thảo. Các phát hiện này chỉ mang tính khuyến nghị: một tài liệu có các phát hiện đó vẫn hợp lệ, và Release của nó vẫn được phân giải và kết xuất. Chỉ kiểm tra đọc nội dung cục bộ được chạy — không tham vấn registry nào, không tải gì về và không ghi gì — và nó được đánh giá trên bộ đệm mà trình soạn thảo đang giữ thay vì tệp trên đĩa, nên một tên bạn sửa sẽ ngừng bị báo cáo trước khi bạn lưu. Mặc định là false: một phiên trình soạn thảo báo cáo liệu tài liệu có đúng hay không, và không nói gì về việc một thực thể có thể xuất bản được hay không, cho đến khi bạn yêu cầu lớp thứ hai đó. Đặt true để yêu cầu nó. Độc lập với khóa này, trình soạn thảo luôn có thể yêu cầu trực tiếp kiểm tra đó, và đây cũng là cách để thực hiện việc so sánh trước khi xuất bản với phiên bản đã xuất bản trước đó. Mặc định: false |
Không cho phép thuộc tính bổ sung.
aggrega-config.mcp
Các thiết lập cho máy chủ Model Context Protocol (aggrega mcp). transport chọn cách truy cập máy chủ — qua đầu vào và đầu ra chuẩn của tiến trình, hoặc qua HTTP — và được đọc bất kể chọn cách nào. announce_tools cũng được đọc trên cả hai transport, vì việc client được cung cấp những tool nào là thuộc tính của máy chủ chứ không phải của cách client truy cập nó. Mọi khóa khác cấu hình listener mà transport HTTP khởi động và không được dùng khi máy chủ giao tiếp qua đầu vào và đầu ra chuẩn — kể cả listen, vốn chỉ được đọc ở đó để máy chủ có thể thông báo, bằng một dòng trên luồng lỗi của nó, rằng địa chỉ này không được dùng. Mỗi khóa bên dưới cho biết nó thuộc loại nào. Khác với serve, vốn cấu hình daemon backend cho trình soạn thảo.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
transport | string (enum) | không | Cách truy cập máy chủ: stdio dùng giao thức qua đầu vào và đầu ra chuẩn của tiến trình, đây là cách một client khởi chạy lệnh dưới dạng tiến trình con truy cập nó; http phục vụ qua HTTP trên địa chỉ mà listen chỉ định, và qua HTTPS khi tls chỉ định một chứng chỉ và khóa. aggrega mcp --transport stdio|http ghi đè khóa này cho một lần gọi. Mặc định là stdio, nên một workspace không bao giờ chỉ định transport sẽ được phục vụ qua đầu vào và đầu ra chuẩn bất kể khối này chứa gì khác — một listener chỉ khởi động khi http được chọn, ở đây hoặc trên dòng lệnh. Mọi giá trị khác đều bị từ chối khi cấu hình được nạp. Hãy đặt http trong cấu hình của một máy chủ mà bên gọi truy cập qua mạng, và để trống khi client tự khởi chạy máy chủ: khi chọn stdio, địa chỉ trong listen không được dùng, và máy chủ thông báo điều đó bằng một dòng trên luồng lỗi của nó. Giá trị cho phép: "stdio", "http" Mặc định: "stdio" |
listen | string | không | Địa chỉ mà listener gắn vào khi transport HTTP được chọn. Nó chỉ định nơi lắng nghe và không chọn gì cả: việc chọn transport thuộc về transport, và khi chọn stdio thì khóa này không được dùng. Chấp nhận hai dạng: host:port cho một địa chỉ TCP, và unix: theo sau là một đường dẫn hệ thống tệp cho một Unix-domain socket. aggrega mcp --listen <address> ghi đè khóa này cho một lần gọi. Mặc định là rỗng, và transport HTTP cần một địa chỉ từ nguồn này hoặc nguồn kia: nếu không có cả hai, một lần khởi chạy chọn nó sẽ bị từ chối trước khi bất cứ thứ gì được gắn. Một địa chỉ plaintext — địa chỉ được truy cập mà không có chứng chỉ và khóa trong tls — chỉ được chấp nhận trên loopback (127.0.0.1, ::1, hoặc localhost phân giải thành một trong hai địa chỉ đó) hoặc trên một Unix socket, đây là cấu hình mà máy chủ dùng khi một proxy phía trước kết thúc TLS; mọi địa chỉ khác đều bị từ chối trước khi bất cứ thứ gì được gắn, kèm theo tên mcp.tls.cert_file và mcp.tls.key_file. Hai dạng này cũng là những dạng duy nhất được chấp nhận, dù có chứng chỉ hay không, khi authorization.trusted_proxy được đặt, vì một header chỉ có thể được tin cậy như một thông tin xác thực ở nơi không ai ngoài proxy có thể đặt nó. Mặc định: "" |
tls | object | không | Chứng chỉ và khóa để kết thúc TLS bên trong tiến trình phục vụ. Đặt cả hai để phục vụ HTTPS trực tiếp từ listener mà listen chỉ định. Để trống cả hai để phục vụ plaintext, khi đó listen bị giới hạn ở loopback hoặc một Unix socket — cấu hình nên dùng khi một proxy phía trước giữ chứng chỉ. Cả hai khóa đều là đường dẫn tới tệp trên đĩa; không khóa nào chứa trực tiếp dữ liệu khóa. |
allowed_origins | string[] | không | Các origin được chấp nhận trong header Origin của một yêu cầu. Một yêu cầu có header Origin chỉ định một origin không có trong danh sách này sẽ bị từ chối với 403; một yêu cầu chỉ định một origin có trong danh sách, hoặc hoàn toàn không có header Origin, sẽ được phục vụ. Mỗi mục được so sánh chính xác với header, nên mỗi mục được viết theo cách trình duyệt gửi một origin: một scheme viết thường, ://, một host viết thường — một tên, một địa chỉ IPv4, hoặc một địa chỉ IPv6 trong dấu ngoặc vuông — và : cùng cổng khi đó không phải cổng mặc định của scheme, không có gì phía sau. Ví dụ https://app.example.com hoặc http://localhost:3000. Một mục có bất kỳ dạng nào khác sẽ không bao giờ khớp với những gì trình duyệt gửi, nên nó bị từ chối khi tệp cấu hình được nạp, kèm theo tên tệp và mục đó: mục có / ở cuối hoặc có đường dẫn (https://app.example.com/), mục không có scheme (app.example.com), và mục chứa chữ hoa hoặc dấu cách. Mặc định là rỗng, nên không origin nào được chấp nhận và chỉ bên gọi không gửi header Origin mới được phục vụ. Do đó, một client chạy trên trình duyệt cần liệt kê origin của nó ở đây; một client không phải trình duyệt không gửi header như vậy và không cần mục nào. Mỗi mục khớp với mẫu ^[a-z][a-z0-9+.-]*://(?:[a-z0-9._-]+|\[[0-9a-f:.]+\])(?::[0-9]{1,5})?$. Mặc định: [] |
limits | object | không | Các giới hạn mà listener HTTP áp dụng cho lưu lượng nó chấp nhận, để một bên gọi không thể làm cạn kiệt tiến trình phục vụ. Chúng giới hạn kích thước tối đa của một yêu cầu, số yêu cầu chạy cùng lúc, và tốc độ gửi của một bên gọi. Không giới hạn nào trong số đó có thể bị tắt. |
authorization | object | không | Những gì máy chủ này khai báo về các bearer token mà bên gọi xuất trình: máy chủ ủy quyền nào cấp chúng, địa chỉ mà máy chủ này công bố cho chính nó với tư cách tài nguyên mà token được cấp cho, tùy chọn một tệp để đọc các khóa xác minh của máy chủ đó, và tùy chọn các header mà một proxy phía trước đặt khi proxy đó xác thực token thay cho máy chủ. issuer và resource là bắt buộc bất cứ khi nào transport HTTP được chọn, và nếu thiếu chúng thì listener bị từ chối trước khi bất cứ thứ gì được gắn; một máy chủ giao tiếp qua đầu vào và đầu ra chuẩn không đọc khóa nào trong số này. Cả hai được công bố trong tài liệu metadata OAuth protected-resource mà listener phục vụ, đây là câu trả lời duy nhất mà một bên gọi HTTP nhận được mà không bị yêu cầu thông tin xác thực, vì client đọc nó để biết nơi lấy token. Khối này không chứa dữ liệu bí mật: token được bên gọi xuất trình trên yêu cầu mà nó gửi và không bao giờ là một trường cấu hình, và jwks_file chỉ định các khóa xác minh công khai chứ không phải thứ gì dùng để ký. |
deny_reach | string (enum)[] | không | Các loại phạm vi tác động mà máy chủ này không mang, bất kể token của bên gọi nói gì. Mỗi thao tác khai báo tác động của chính nó lan xa đến đâu — none cho thao tác chỉ đọc hoặc kết xuất và không để lại gì, workspace cho thao tác ghi bên trong workspace mà tiến trình này phục vụ, registry cho thao tác xuất bản, ký hoặc thu hồi, và machine cho thao tác thay đổi những gì mọi workspace trên máy chủ dùng chung — và việc chỉ định một loại ở đây sẽ rút mọi tool thuộc loại đó khỏi máy chủ này. Một tool bị rút sẽ vắng mặt trong danh sách tool và trong câu trả lời của describe-capabilities, đối với mọi bên gọi, và việc vẫn gọi nó sẽ bị từ chối kèm theo tên thiết lập này, vì không scope nào có thể cho phép nó. Mặc định là rỗng, nên máy chủ mang bất cứ thứ gì mà scope của bên gọi cho phép. Đây là giới hạn mà máy chủ tự đặt cho chính nó, bên trên giới hạn theo từng bên gọi mà scope đặt ra: một máy chủ chỉ phục vụ việc đọc sẽ chỉ định ba loại có ghi ở đây và khi đó không thể xuất bản ngay cả cho một bên gọi có token mang mọi scope. Việc chỉ định machine được chấp nhận và không thay đổi gì — không tool nào thuộc loại đó được cung cấp qua HTTP, đây là thuộc tính của transport chứ không phải một thiết lập. Được đọc khi listener khởi động: giá trị nằm ngoài bốn giá trị trên bị từ chối khi cấu hình được nạp, và việc thay đổi nó cần khởi động lại. Hoàn toàn không được đọc khi máy chủ giao tiếp qua đầu vào và đầu ra chuẩn, nơi bên gọi chính là người đã khởi chạy tiến trình. Giá trị cho phép cho mỗi mục: "none", "workspace", "registry", "machine". Mặc định: [] |
announce_tools | string[] | không | Các tool mà máy chủ này công bố, được đặt tên đúng như danh sách tool báo cáo. Bỏ khóa này thì mọi tool mà máy chủ mang đều được công bố, đây là điều mà một client tuân theo giao thức mong đợi: nó lấy toàn bộ danh sách tool và tự quyết định đưa bao nhiêu trong đó tới mô hình. Viết một danh sách thì đúng những tool đó được công bố — tool bị bỏ ra sẽ vắng mặt trong danh sách tool, vắng mặt trong câu trả lời của describe-capabilities, và bị từ chối khi được gọi theo tên, kèm theo tên thiết lập này. Viết một danh sách rỗng thì không có gì được công bố. Hãy đặt nó khi client ở đầu bên kia giới hạn số tool mà nó sẽ đăng ký — một số client áp dụng giới hạn đó trên mọi máy chủ mà chúng kết nối cùng lúc — và chỉ định các tool mà client đó cần. Nó chỉ thu hẹp những gì được công bố và không gì hơn: nó không thể nới rộng deny_reach, vốn rút hẳn một khả năng, cũng như các scope mà token của bên gọi mang. Một tool được chỉ định ở đây thuộc loại mà deny_reach rút đi vẫn nằm ngoài danh sách tool và bị từ chối khi được gọi, kèm theo tên thiết lập đó; một tool được chỉ định ở đây mà scope của bên gọi không cho phép vẫn được liệt kê, và lời gọi tới nó bị từ chối kèm theo tên scope có thể cho phép nó. Mọi tên phải là tên mà binary này mang: một tên không ứng với tool nào sẽ bị từ chối khi máy chủ khởi động, vì nếu không thì người yêu cầu một bề mặt hẹp hơn sẽ được phục vụ một bề mặt khác mà không có gì báo điều đó. Một tên thuộc họ cli-, vốn chạy một lệnh aggrega trong một tiến trình riêng, được chấp nhận trên cả hai transport và không công bố gì qua HTTP, nơi không tool nào như vậy được cung cấp cho bất kỳ bên gọi nào. Được đọc trên cả hai transport khi máy chủ khởi động, nên tập được công bố cố định trong suốt vòng đời tiến trình và việc thay đổi nó cần khởi động lại. |
health | object | không | Nơi một trình giám sát hỏi liệu tiến trình này còn sống không và đã sẵn sàng trả lời lời gọi chưa. Hai kiểm tra này được trả lời trên một địa chỉ riêng và không bao giờ trên địa chỉ mà listen chỉ định: mọi yêu cầu tới endpoint đều mang một bearer token, nên một probe được trả lời ở đó sẽ trao cho bất cứ thứ gì truy cập được endpoint một cách đọc trạng thái tiến trình không cần xác thực, cùng với một cách miễn phí để bắt nó làm việc. Endpoint trả lời /healthz và /readyz bằng cùng mã 404 mà nó trả cho mọi đường dẫn nó không phục vụ, dù có token hay không. |
Không cho phép thuộc tính bổ sung.
aggrega-config.mcp.tls
Chứng chỉ và khóa để kết thúc TLS bên trong tiến trình phục vụ. Đặt cả hai để phục vụ HTTPS trực tiếp từ listener mà listen chỉ định. Để trống cả hai để phục vụ plaintext, khi đó listen bị giới hạn ở loopback hoặc một Unix socket — cấu hình nên dùng khi một proxy phía trước giữ chứng chỉ. Cả hai khóa đều là đường dẫn tới tệp trên đĩa; không khóa nào chứa trực tiếp dữ liệu khóa.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
cert_file | string | không | Đường dẫn tới chuỗi chứng chỉ PEM mà listener xuất trình, được đọc khi tiến trình khởi động. Đặt cùng với key_file. Mặc định là rỗng, nên listener phục vụ plaintext và listen bị giới hạn ở loopback hoặc một Unix socket. Mặc định: "" |
key_file | string | không | Đường dẫn tới khóa riêng PEM cho chứng chỉ trong cert_file, được đọc khi tiến trình khởi động. Đặt cùng với nó. Là đường dẫn tới một tệp, không bao giờ là dữ liệu khóa trực tiếp. Mặc định là rỗng, nên listener phục vụ plaintext và listen bị giới hạn ở loopback hoặc một Unix socket. Mặc định: "" |
Không cho phép thuộc tính bổ sung.
aggrega-config.mcp.limits
Các giới hạn mà listener HTTP áp dụng cho lưu lượng nó chấp nhận, để một bên gọi không thể làm cạn kiệt tiến trình phục vụ. Chúng giới hạn kích thước tối đa của một yêu cầu, số yêu cầu chạy cùng lúc, và tốc độ gửi của một bên gọi. Không giới hạn nào trong số đó có thể bị tắt.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
max_body_bytes | integer | không | Kích thước body yêu cầu lớn nhất mà listener chấp nhận, tính bằng byte. Một yêu cầu có body vượt quá giá trị này bị từ chối với 413, và body không được đọc quá giới hạn. Mặc định là 4194304 (4 MiB), cao hơn nhiều so với một lời gọi tool mang cả một tài liệu soạn thảo và thấp hơn nhiều so với mức cho phép một bên gọi chiếm một phần đáng kể bộ nhớ của tiến trình. Giá trị tối thiểu là 1, nên không có giá trị nào tắt được giới hạn; hãy tăng nó khi bên gọi thực sự cần gửi tài liệu lớn hơn. Tối thiểu: 1. Mặc định: 4194304 |
max_concurrent_requests | integer | không | Số yêu cầu mà listener chạy cùng lúc. Một yêu cầu đến khi đã có ngần ấy yêu cầu đang xử lý sẽ bị từ chối với 503 thay vì được xếp hàng, để bên gọi được báo thử lại thay vì chờ sau công việc mà nó không thấy. Mặc định là 16, đủ chỗ cho vài lời gọi tool đồng thời trong khi giữ một máy nhỏ vẫn phản hồi tốt; hãy tăng nó trên máy lớn hơn. Giá trị tối thiểu là 1, nên không có giá trị nào tắt được giới hạn. Tối thiểu: 1. Mặc định: 16 |
requests_per_minute | integer | không | Số yêu cầu mà một bên gọi có thể gửi trong một phút. Giá trị được đếm theo từng bên gọi chứ không theo máy chủ — theo subject mà token của bên gọi chỉ định, hoặc theo danh tính mà một proxy tin cậy khẳng định — nên một bên gọi bận rộn không thể tiêu hết hạn mức của bên khác. Một bên gọi có thể gửi ngần ấy yêu cầu dồn một lúc; sau đó hạn mức được nạp lại đều đặn, thêm một yêu cầu sau mỗi 60 / requests_per_minute giây, và một yêu cầu đến khi đã hết hạn mức bị từ chối với 429. Mặc định là 120, tức hai yêu cầu mỗi giây liên tục: cao hơn nhiều so với lượng mà một trợ lý điều khiển workspace gửi, mà vẫn là giới hạn đối với một client bị rơi vào vòng lặp. Giá trị tối thiểu là 1, nên không có giá trị nào tắt được giới hạn. Tối thiểu: 1. Mặc định: 120 |
Không cho phép thuộc tính bổ sung.
aggrega-config.mcp.authorization
Những gì máy chủ này khai báo về các bearer token mà bên gọi xuất trình: máy chủ ủy quyền nào cấp chúng, địa chỉ mà máy chủ này công bố cho chính nó với tư cách tài nguyên mà token được cấp cho, tùy chọn một tệp để đọc các khóa xác minh của máy chủ đó, và tùy chọn các header mà một proxy phía trước đặt khi proxy đó xác thực token thay cho máy chủ. issuer và resource là bắt buộc bất cứ khi nào transport HTTP được chọn, và nếu thiếu chúng thì listener bị từ chối trước khi bất cứ thứ gì được gắn; một máy chủ giao tiếp qua đầu vào và đầu ra chuẩn không đọc khóa nào trong số này. Cả hai được công bố trong tài liệu metadata OAuth protected-resource mà listener phục vụ, đây là câu trả lời duy nhất mà một bên gọi HTTP nhận được mà không bị yêu cầu thông tin xác thực, vì client đọc nó để biết nơi lấy token. Khối này không chứa dữ liệu bí mật: token được bên gọi xuất trình trên yêu cầu mà nó gửi và không bao giờ là một trường cấu hình, và jwks_file chỉ định các khóa xác minh công khai chứ không phải thứ gì dùng để ký.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
issuer | string | không | Địa chỉ của máy chủ ủy quyền phát hành các token mà listener này chấp nhận, viết đúng như máy chủ đó tự nêu định danh issuer của mình — ví dụ https://login.example.com. Địa chỉ này được công bố trong danh sách authorization_servers của tài liệu metadata protected-resource, nhờ đó client biết nơi lấy token cho listener này. Mặc định để trống, đây không phải giá trị dùng được: listener bị từ chối trước khi bất cứ thứ gì được bind, trừ khi giá trị này chứa một địa chỉ đầy đủ, bao gồm cả scheme và host. Đây là một địa chỉ https trừ khi máy chủ ủy quyền chạy trên chính máy này: http thuần chỉ được chấp nhận cho một host loopback, chẳng hạn localhost, 127.0.0.1 hoặc ::1, và một issuer http thuần trên bất kỳ host nào khác bị từ chối trước khi bất cứ thứ gì được bind, kèm tên khóa này và yêu cầu một địa chỉ https. Điều đó đúng dù các khóa được đọc từ issuer, từ jwks_file, hay một trusted_proxy phía trước kiểm tra token, vì mọi client đều được chuyển tới issuer để lấy token. Mặc định: "" |
resource | string | không | Địa chỉ mà máy chủ này công bố cho chính nó, theo cách bên gọi truy cập tới nó — ví dụ https://mcp.example.com/mcp. Hãy viết địa chỉ mà bên gọi thực sự dùng, bao gồm cả host mà một proxy phía trước trình ra, vì đây là định danh mà client đưa cho máy chủ ủy quyền khi xin token cho máy chủ này, và nó được công bố nguyên vẹn làm trường resource của tài liệu metadata protected-resource. Nơi phục vụ tài liệu đó được suy ra từ địa chỉ này, bằng cách chèn /.well-known/oauth-protected-resource vào giữa host và path: một máy chủ công bố là https://mcp.example.com/mcp phục vụ tài liệu tại https://mcp.example.com/.well-known/oauth-protected-resource/mcp, và cả tại đường dẫn well-known đó không có gì phía sau, là nơi client tìm thứ hai. Một token chỉ được chấp nhận khi địa chỉ này nằm trong các audience mà token nêu. Mặc định để trống, đây không phải giá trị dùng được: listener bị từ chối trước khi bất cứ thứ gì được bind, trừ khi giá trị này chứa một địa chỉ đầy đủ, bao gồm cả scheme và host. Mặc định: "" |
jwks_file | string | không | Đường dẫn tới một tệp chứa JSON Web Key Set dùng để xác minh các token mà máy chủ này chấp nhận, được đọc khi tiến trình khởi động. Mặc định để trống, đây là trường hợp thông thường: các khóa được đọc từ chính máy chủ ủy quyền, bằng cách hỏi issuer nơi nó công bố chúng và tải chúng từ địa chỉ nó chỉ ra, và chúng được đọc lại một lần khi một token đến được ký bằng một định danh khóa mà tập khóa đang giữ không có. Hãy đặt giá trị này khi workspace ở chế độ offline, khi đó listener bị từ chối trước khi bất cứ thứ gì được bind nếu thiếu nó, vì một workspace offline không gửi yêu cầu mạng nào và không có cách nào khác để lấy khóa; khi đó tệp chứa các khóa duy nhất được chấp nhận, và máy chủ ủy quyền không bao giờ được liên hệ. Tệp chứa các khóa xác minh công khai và không bao giờ chứa thứ gì dùng để ký. Đường dẫn tương đối được phân giải theo thư mục của tệp cấu hình đã khai báo nó. Mặc định: "" |
trusted_proxy | object | không | Đọc danh tính bên gọi từ các header mà một proxy phía trước đặt, thay vì xác thực bearer token tại đây. Chỉ đặt giá trị này khi cả hai điều sau đều đúng: một proxy phía trước tự xác thực token, và không gì ngoài proxy đó có thể truy cập listener: khi đặt nó, listen phải là loopback hoặc một Unix socket, và mọi địa chỉ khác bị từ chối trước khi bất cứ thứ gì được bind, kèm tên cả hai thiết lập. Một header chỉ đáng tin đúng bằng mức đáng tin của tập bên gọi có thể đặt nó, và trên một địa chỉ mà mạng truy cập được thì mọi bên gọi đều có thể đặt bất kỳ header nào, nên một listener ở chế độ này trên địa chỉ như vậy sẽ cho phép mọi bên gọi tự xưng là bất kỳ ai. Khi đặt giá trị này, không token nào được đọc — không từ header Authorization, không từ bất kỳ đâu khác, và không tập khóa nào được tải — danh tính bên gọi là giá trị của principal_header, một yêu cầu không mang header đó được trả lời 401, và hai header được nêu ở đây là những header duy nhất được đọc. Bỏ qua nó, vốn là mặc định, thì máy chủ này tự xác thực bearer token. |
Không cho phép thuộc tính bổ sung.
aggrega-config.mcp.authorization.trusted_proxy
Đọc danh tính bên gọi từ các header mà một proxy phía trước đặt, thay vì xác thực bearer token tại đây. Chỉ đặt giá trị này khi cả hai điều sau đều đúng: một proxy phía trước tự xác thực token, và không gì ngoài proxy đó có thể truy cập listener: khi đặt nó, listen phải là loopback hoặc một Unix socket, và mọi địa chỉ khác bị từ chối trước khi bất cứ thứ gì được bind, kèm tên cả hai thiết lập. Một header chỉ đáng tin đúng bằng mức đáng tin của tập bên gọi có thể đặt nó, và trên một địa chỉ mà mạng truy cập được thì mọi bên gọi đều có thể đặt bất kỳ header nào, nên một listener ở chế độ này trên địa chỉ như vậy sẽ cho phép mọi bên gọi tự xưng là bất kỳ ai. Khi đặt giá trị này, không token nào được đọc — không từ header Authorization, không từ bất kỳ đâu khác, và không tập khóa nào được tải — danh tính bên gọi là giá trị của principal_header, một yêu cầu không mang header đó được trả lời 401, và hai header được nêu ở đây là những header duy nhất được đọc. Bỏ qua nó, vốn là mặc định, thì máy chủ này tự xác thực bearer token.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
principal_header | string | có | Header mà proxy phía trước đặt danh tính của bên gọi vào — ví dụ X-Forwarded-User. Nó được viết dưới dạng tên header HTTP: chữ cái, chữ số và dấu gạch nối, cùng các ký tự khác mà tên header có thể mang (!#$%&'*+.^_|~ và dấu backtick), không có khoảng trắng, dấu hai chấm hay dấu phân cách nào khác. Một tên ở bất kỳ dạng nào khác bị từ chối khi tệp cấu hình được nạp, kèm tên tệp và khóa, vì không yêu cầu nào có thể mang header như vậy. Một tên rỗng cũng bị từ chối: nó sẽ khiến máy chủ này tự kiểm tra token trong khi khối cấu hình nói rằng một proxy phía trước làm việc đó. Để tắt chế độ này, hãy bỏ trusted_proxy. Giá trị của header được lấy đúng như được viết và không so sánh với gì cả, giống như subject của một token mà máy chủ này tự xác thực được ghi lại và không so sánh với gì cả. Nó là toàn bộ thông tin xác thực trong chế độ này, nên nó bắt buộc bất cứ khi nào trusted_proxy được đặt, và một yêu cầu đến mà không có nó được trả lời 401. Mẫu: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$. |
scopes_header | string | không | Header mà proxy phía trước đặt các scope được cấp cho bên gọi vào, phân tách bằng khoảng trắng — ví dụ X-Forwarded-Scopes. Nó được viết dưới dạng tên header HTTP, cùng dạng với principal_header, hoặc để trống. Một tên ở bất kỳ dạng nào khác bị từ chối khi tệp cấu hình được nạp, kèm tên tệp và khóa, vì không yêu cầu nào có thể mang header như vậy và không bên gọi nào được cấp scope. Mặc định để trống, nghĩa là không khẳng định scope nào cho bất kỳ bên gọi nào. Dù được đặt tên là gì, không header nào ngoài header này và principal_header được đọc. Mẫu: ^[!#$%&'*+.^_`|~0-9A-Za-z-]*$. Mặc định: "" |
Không cho phép thuộc tính bổ sung.
aggrega-config.mcp.health
Nơi một trình giám sát hỏi liệu tiến trình này còn sống không và đã sẵn sàng trả lời lời gọi chưa. Hai kiểm tra này được trả lời trên một địa chỉ riêng và không bao giờ trên địa chỉ mà listen chỉ định: mọi yêu cầu tới endpoint đều mang một bearer token, nên một probe được trả lời ở đó sẽ trao cho bất cứ thứ gì truy cập được endpoint một cách đọc trạng thái tiến trình không cần xác thực, cùng với một cách miễn phí để bắt nó làm việc. Endpoint trả lời /healthz và /readyz bằng cùng mã 404 mà nó trả cho mọi đường dẫn nó không phục vụ, dù có token hay không.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
listen | string | không | Địa chỉ mà các kiểm tra liveness và readiness được trả lời trên đó, ở cùng hai dạng mà listen nhận: host:port, hoặc unix: theo sau là một đường dẫn hệ thống tệp. Mặc định để trống, nên không có listener thứ hai nào được khởi động và không kiểm tra nào được trả lời ở bất kỳ đâu. Khi đặt một địa chỉ, GET /healthz được trả lời 200 kể từ lúc tiến trình đang chạy, và GET /readyz được trả lời 503 cho đến khi workspace đã được phân giải và endpoint đã bind, rồi 200 từ đó trở đi — đây chính là sự phân biệt mà một supervisor cần, vì một tiến trình đang chạy chưa phải là một tiến trình có thể trả lời một lệnh gọi. Mọi câu trả lời là một mã trạng thái với phần thân rỗng, không yêu cầu token nào và không đọc header nào; mọi đường dẫn khác trên địa chỉ này là 404, và mọi phương thức khác trên hai đường dẫn này là 405. Khác với listen, địa chỉ này không bị giới hạn ở loopback hay Unix socket và không có địa chỉ nào bị từ chối cho nó: hãy trỏ nó vào một trong hai loại đó, vốn là mục đích của nó, và lưu ý rằng bất cứ thứ gì có thể truy cập địa chỉ bạn chọn đều có thể đọc hai câu trả lời đó. Mặc định: "" |
Không cho phép thuộc tính bổ sung.
Định nghĩa
ReleaseCatalogConfig
Các thư mục catalog riêng của một Release: cùng hai khóa mà khối workspace mang, được giới hạn phạm vi cho Release đó.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
catalog_dirs | string[] | không | Các thư mục catalog mà Release này đọc các thực thể cục bộ từ đó thay cho catalog_dirs của workspace, mỗi thư mục được phân giải tương đối với tệp khai báo nó. Cùng một ngăn xếp tìm kiếm có thứ tự, mục đầu tiên thắng, như danh sách của workspace, với thư mục catalog ở gốc workspace được đọc sau nó khi thư mục đó tồn tại và chưa có mục nào trong danh sách chứa nó. Khi bỏ qua, Release giữ danh sách của workspace; khi viết là [], nó không đọc catalog cục bộ nào cả. |
catalog_dirs_append | string[] | không | Các thư mục catalog được thêm vào sau danh sách của Release này — catalog_dirs riêng của nó nếu mục có viết, nếu không thì của workspace — mỗi thư mục được phân giải tương đối với tệp khai báo nó. Mặc định: [] |
Không cho phép thuộc tính bổ sung.
RegistryConfig
Các thiết lập và chính sách tin cậy chữ ký được giới hạn cho một máy chủ registry OCI.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
host | string | có | Máy chủ registry mà các thiết lập này áp dụng (ví dụ hub.aggrega.ai). Được so khớp với máy chủ registry của đích push/pull, nên nó được viết theo cách viết mà phép so khớp đó dùng: một tên máy chủ chữ thường có chứa dấu chấm, localhost, một tên đơn theo sau là cổng (registry:5000), một địa chỉ IPv4, hoặc một địa chỉ IPv6 trong dấu ngoặc vuông, mỗi loại có thể kèm :port — không có scheme, đường dẫn, thông tin xác thực, khoảng trắng hay chữ hoa. Cổng 443 trên một máy chủ truy cập qua HTTPS là cổng mặc định của máy chủ đó, và việc viết nó bị từ chối khi cấu hình được tải, kèm tên máy chủ cần viết không có cổng, vì một mục viết như vậy sẽ không bao giờ là mục được tìm thấy; localhost và các địa chỉ loopback khác được truy cập qua HTTP thuần, nên 443 là một cổng bình thường ở đó và được giữ lại. aggrega registry add và aggrega config init --registry đặt khóa cho mục theo máy chủ mà đối số của chúng nêu và từ chối máy chủ không được viết theo cách này. Máy chủ chỉ được đánh giá theo cách viết: việc tên có phân giải được hay có registry trả lời ở đó hay không thì không được kiểm tra. Mẫu: ^(?:(?:(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?|localhost|(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:\.(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}|\[(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:|(?:[0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}|(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}|(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}|(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}|[0-9a-f]{1,4}:(?::[0-9a-f]{1,4}){1,6}|:(?:(?::[0-9a-f]{1,4}){1,7}|:))\])(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?|[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?:(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))$. |
name | string | không | Bí danh thân thiện tùy chọn cho registry này. Máy chủ là định danh; name là bộ chọn tiện lợi phân giải thành máy chủ của mục này ở bất cứ đâu một registry được nêu tên (ví dụ --registry, hoặc default_registry). Bí danh phải là duy nhất giữa các mục. |
trusted_identities | TrustedIdentity[] | không | Tập OR các định danh ký keyless được chấp nhận cho các artifact kéo từ registry này. Một chữ ký được xác minh khi chứng chỉ của nó khớp với bất kỳ mục nào. Được dùng bởi luồng xác minh keyless. Mặc định: [] |
trusted_deprecation_identities | TrustedIdentity[] | không | Tập OR các định danh keyless được chấp nhận thêm để ký một dấu hiệu ngừng hỗ trợ hồi tố cho một artifact kéo từ registry này. Một dấu hiệu ngừng hỗ trợ được chấp nhận khi chữ ký của nó khớp với người ký artifact gốc HOẶC bất kỳ mục nào ở đây — nhờ đó chủ sở hữu registry hoặc nhóm bảo mật có thể thu hồi một artifact mà nhà phát hành gốc không còn liên lạc được, mà không cần được tin cậy để ký chính các artifact. Chỉ được dùng bởi luồng phát hiện ngừng hỗ trợ; nó không bao giờ mở rộng tập tin cậy cho chữ ký artifact. Mặc định: [] |
public_key | string | không | Khóa công khai tương thích cosign được ghim cho một registry ở chế độ có khóa, viết trực tiếp dưới dạng khối PEM: văn bản từ dòng -----BEGIN PUBLIC KEY----- (hoặc -----BEGIN RSA PUBLIC KEY-----) đến dòng -----END tương ứng, như aggrega registry add --key sao chép từ tệp khóa. Khi được đặt, các chữ ký từ registry này được xác minh ngoại tuyến với khóa này thay vì với các định danh keyless. Một giá trị không có dòng -----BEGIN … PUBLIC KEY----- bị từ chối khi tệp cấu hình được tải, kèm tên tệp và mục, và một khóa riêng tư bị dán vào đây do nhầm lẫn cũng vậy. Dòng đó có thể nằm ở bất kỳ đâu trong giá trị, vì khóa được đọc từ khối PEM mà giá trị mang và mọi văn bản trước khối đó bị bỏ qua. Ở đây chỉ dòng đó được kiểm tra: việc khối có chứa một khóa giải mã được hay không chỉ được phát hiện khi một chữ ký từ registry này được xác minh với nó. Giá trị được khai báo là nhạy cảm (x-aggrega-sensitive), nên một giá trị bị từ chối — nhất là một khóa riêng tư bị chọn nhầm — không bao giờ được trích dẫn: thông báo từ chối nêu tệp, mục và ràng buộc mà giá trị không thỏa — mẫu ở trên, hoặc kiểu string — và hiển thị <redacted> ở chỗ của giá trị. Một khóa công khai tải được sẽ được đọc và hiển thị như đã viết. Mẫu: -----BEGIN [A-Z ]*PUBLIC KEY-----. |
trusted_root | string | không | Đường dẫn tùy chọn tới một gói trust-root Sigstore được ghim cho xác minh keyless trong môi trường air-gapped. Khi được đặt, neo tin cậy keyless được tải từ tệp này mà không cần mạng; khi để trống, trust root public-good được tải về và lưu đệm. |
advisory | boolean | không | Khi là true, lỗi xác minh chữ ký cho registry này được hạ xuống thành cảnh báo thay vì dừng việc pull. Việc xác minh vẫn chạy và lỗi được báo cáo; việc pull tiếp tục. Mặc định là false. Mặc định: false |
skip_signature_verification | boolean | không | Cơ chế khẩn cấp theo từng máy chủ để bỏ qua xác minh chữ ký — cùng công tắc skip_signature_verification như công tắc toàn cục, được giới hạn theo vị trí đặt cho máy chủ này. Nó không vô hiệu hóa chính sách signing.required cấp cao nhất: một chữ ký mà tổ chức yêu cầu vẫn được xác minh trên máy chủ này bất kể công tắc này; chỉ công tắc toàn cục mới có thể tắt điều đó. Đặt công tắc này cùng với signing.required theo từng registry trên cùng máy chủ là được phép, và kết hợp chữ ký bắt buộc khi push với việc bỏ qua xác minh khi pull: skip thắng ở phía xác minh, vì lập trường bắt buộc theo từng máy chủ (khác với lập trường cấp cao nhất) không miễn nhiễm với skip theo từng máy chủ. Mặc định là false. Mặc định: false |
signing | SigningConfig | không | Khối ký của registry này: các URL dịch vụ keyless, một đường dẫn khóa tùy chọn cho chế độ có khóa, và lập trường tin cậy theo từng máy chủ. Các trường endpoint ghi đè khối signing toàn cục cho các lần push tới máy chủ này; một cờ CLI ghi đè cả hai. required và kinds lấy phạm vi từ vị trí đặt — dưới một mục registry, chúng giới hạn lập trường tin cậy duy nhất cho máy chủ này (việc phát hành một artifact chưa ký trong phạm vi bị từ chối, và việc sử dụng một artifact chưa ký cũng bị từ chối), cùng khái niệm mà khối signing cấp cao nhất mang cho mọi registry. |
Không cho phép thuộc tính bổ sung.
SigningConfig
Một khối ký: các URL dịch vụ ký không khóa, một con trỏ tùy chọn tới tệp khóa cho chế độ có khóa, và lập trường tin cậy (required và kinds). Đặt ở cấp cao nhất, khối áp dụng cho mọi registry; đặt dưới một mục registries[], khối áp dụng cho host đó — mọi trường đọc phạm vi của nó từ vị trí đặt. required là một lập trường tin cậy duy nhất bao trùm cả hai chiều (một lần push chưa ký trong phạm vi bị từ chối và một lần pull chưa ký trong phạm vi bị từ chối). Bảo mật: khối không chứa tài liệu bí mật nào — token định danh OIDC không bao giờ là một trường cấu hình (tồn tại ngắn, được cung cấp lúc chạy), và key_path là đường dẫn tới một tệp khóa, không bao giờ là các byte khóa viết trực tiếp. Điều này phản chiếu sự bất đối xứng ở phía xác minh: ở đó cho phép một public_key viết trực tiếp, nhưng phía ký chỉ mang một đường dẫn khóa. Một máy chủ aggrega mcp được truy cập qua HTTP không tham khảo key_path ở vị trí đặt nào, nên không thể ký có khóa qua một listener như vậy: một lời gọi mà nó trả lời chỉ ký bằng token định danh mà chính lời gọi đó mang theo.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
fulcio_url | string | không | URL của cơ quan cấp chứng chỉ Fulcio cho việc ký không khóa. Khi không đặt, phiên bản Fulcio công cộng được sử dụng. Giá trị được viết dưới dạng một URL https tuyệt đối: https://, một host, và tùy chọn một cổng và một đường dẫn, không có khoảng trắng — ví dụ https://fulcio.sigstore.dev. Một giá trị có dạng khác, chẳng hạn không có scheme (fulcio.example.com) hoặc bắt đầu bằng http://, bị từ chối khi tệp cấu hình được tải, kèm tên tệp và khóa. Tệp được kiểm tra trước khi bất cứ thứ gì khác được áp dụng lên trên nó, nên cùng endpoint đó khi được cung cấp bởi AGGREGA_SIGNING_FULCIO_URL, bởi cờ --fulcio-url, hoặc trong một yêu cầu phát hành từ trình soạn thảo hay trợ lý thì không bị buộc theo dạng này. Mẫu: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
rekor_url | string | không | URL của nhật ký minh bạch Rekor cho việc ký không khóa. Khi không đặt, phiên bản Rekor công cộng được sử dụng. Giá trị được viết dưới dạng một URL https tuyệt đối: https://, một host, và tùy chọn một cổng và một đường dẫn, không có khoảng trắng — ví dụ https://rekor.sigstore.dev. Một giá trị có dạng khác, chẳng hạn không có scheme (rekor.example.com) hoặc bắt đầu bằng http://, bị từ chối khi tệp cấu hình được tải, kèm tên tệp và khóa. Tệp được kiểm tra trước khi bất cứ thứ gì khác được áp dụng lên trên nó, nên cùng endpoint đó khi được cung cấp bởi AGGREGA_SIGNING_REKOR_URL, bởi cờ --rekor-url, hoặc trong một yêu cầu phát hành từ trình soạn thảo hay trợ lý thì không bị buộc theo dạng này. Mẫu: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
timestamp_url | string | không | URL của cơ quan cấp dấu thời gian RFC3161 cho việc ký không khóa. Không có giá trị mặc định: khi không đặt, không cơ quan cấp dấu thời gian nào được liên hệ, và thời gian tin cậy của một chữ ký không khóa lấy từ mục nhật ký minh bạch của nó. Giá trị được viết dưới dạng một URL https tuyệt đối: https://, một host, và tùy chọn một cổng và một đường dẫn, không có khoảng trắng — ví dụ https://tsa.example.com/api/v1/timestamp. Một giá trị có dạng khác, chẳng hạn không có scheme (tsa.example.com) hoặc bắt đầu bằng http://, bị từ chối khi tệp cấu hình được tải, kèm tên tệp và khóa. Tệp được kiểm tra trước khi bất cứ thứ gì khác được áp dụng lên trên nó, nên cùng endpoint đó khi được cung cấp bởi AGGREGA_SIGNING_TIMESTAMP_URL, bởi cờ --timestamp-url, hoặc trong một yêu cầu phát hành từ trình soạn thảo hay trợ lý thì không bị buộc theo dạng này. Mẫu: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
key_path | string | không | Đường dẫn tới một tệp PEM khóa riêng ECDSA P-256 được lưu giữ, dùng cho việc ký có khóa ngoại tuyến. Là đường dẫn tới một tệp, không bao giờ là tài liệu khóa viết trực tiếp. Khi không đặt, đường ký không khóa được sử dụng. Một máy chủ aggrega mcp được truy cập qua HTTP không bao giờ tham khảo khóa này, dù nó được đặt ở đâu — trong khối signing cấp cao nhất, trong khối của một mục registry, hay bởi AGGREGA_SIGNING_KEY_PATH: một lời gọi mà listener như vậy trả lời chỉ ký bằng token định danh mà chính lời gọi đó mang theo, hoặc bị từ chối. Một máy chủ được truy cập qua đầu vào và đầu ra chuẩn ký bằng khóa này giống như một terminal. |
required | boolean | không | Lập trường tin cậy duy nhất cho phạm vi của khối này: khi là true, việc phát hành một loại artifact trong phạm vi đòi hỏi chữ ký (một lần push chưa ký trong phạm vi bị từ chối), và việc sử dụng một artifact như vậy cũng đòi hỏi chữ ký (một lần pull chưa ký trong phạm vi bị từ chối). Phạm vi được đọc từ vị trí đặt — trên khối signing cấp cao nhất, nó bao trùm mọi registry; dưới khối signing của một mục registries[], nó bao trùm riêng host đó. Một tên, một việc, cả hai phạm vi. Chính sách cấp cao nhất được kết hợp đơn điệu qua chuỗi cấu hình phân tầng — bất kỳ tầng nào đặt nó là true đều làm nó có hiệu lực true, và không tầng nào có độ ưu tiên thấp hơn có thể tắt lại — nên không thể gỡ bỏ nó bằng một chỉnh sửa cấu hình thông thường. Mặc định là false. Mặc định: false |
kinds | string[] | không | Giới hạn required vào các loại artifact cụ thể. Để trống hoặc một mục all duy nhất nghĩa là mọi loại có thể ký; nếu không, lập trường áp dụng đúng cho các loại được liệt kê, khớp với giá trị kind: của thực thể (ví dụ Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate, Plugin). Trên khối signing cấp cao nhất, nó được kết hợp theo phép hợp qua chuỗi phân tầng — một tầng có thể mở rộng phạm vi nhưng không bao giờ thu hẹp. Phạm vi được đọc từ vị trí đặt, giống như required. Mặc định: [] |
Không cho phép thuộc tính bổ sung.
TrustedIdentity
Một định danh ký không khóa được chấp nhận: một chủ thể chứng chỉ (định danh OIDC) đi cùng với nhà phát hành OIDC đã bảo chứng cho nó.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
identity | string | không | Tên thay thế chủ thể chứng chỉ chính xác — định danh OIDC được gắn vào chứng chỉ ký tồn tại ngắn (ví dụ email của một maintainer hoặc URI của một workflow CI). |
identity_regexp | string | không | Biểu thức chính quy được so khớp với chủ thể chứng chỉ, dùng thay cho một identity chính xác (ví dụ để chấp nhận mọi workflow thuộc một tổ chức). |
issuer | string | có | URL của nhà phát hành OIDC đã cấp token định danh (ví dụ https://accounts.google.com hoặc https://token.actions.githubusercontent.com). |
Không cho phép thuộc tính bổ sung.
PluginRef
Tham chiếu tới một plugin Wasm được gắn tại một socket mà việc gắn có thể đặt tên hàm điểm vào của nó — các danh sách governance và linter. Các socket có điểm vào cố định thì dùng FixedEntryPluginRef, vốn mang đúng các trường này nhưng không có function. uri và capability cùng nhau chọn plugin: chỉ có uri là gắn trực tiếp (plugin tại định danh đó được gắn nguyên văn — cách dùng của các socket xuyên suốt, vì plugin của chúng không khai báo capability nào được phục vụ); chỉ có capability thì phân giải plugin phục vụ capability đó (tên capability trần mà một Recipe ràng buộc qua spec.capability, ví dụ helm); cả hai cùng nhau thì khử nhập nhằng — capability nêu cái cần phân giải và uri chọn plugin của nhà phát hành nào phục vụ nó, theo định danh trần của plugin đó, trong một catalog liên kết nơi có nhiều hơn một plugin phục vụ capability. function ghi đè hàm điểm vào mặc định của socket; khi bỏ qua, giá trị mặc định đã được tài liệu hóa của socket được áp dụng — trên một mục governance, giá trị mặc định đó suy ra từ role. role nêu vai trò gắn governance và chỉ được đọc trên một mục governance. with mang các đầu vào tùy chọn tại thời điểm gắn mà plugin đọc.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
uri | string | không | Định danh plugin: định danh trần của một thực thể Plugin — đường dẫn <pluginType>/<name>, ví dụ governance/redact hoặc provider/helm — một đường dẫn hệ thống tệp cục bộ, hoặc một bí danh registry. Tùy chọn: một mục có thể thay vào đó chọn plugin theo capability. Một hậu tố :version tùy chọn ghim phiên bản theo cùng ba dạng như mọi lần ghim phiên bản (trần, chính xác :1.0.0, hoặc khoảng tương thích phiên bản chính :^1.0.0). |
role | string (enum) | không | Vai trò trong pipeline mà một lần gắn governance được ràng buộc vào, chỉ được đọc trên một mục governance: annotation-transform chèn annotation vào các component đã phân giải trước khi mở rộng annotation, nên các lần chèn được ràng buộc trở thành các lần gắn Feature; label-transform tự động gắn thẻ nhãn nút của đồ thị topology khi xây dựng topology; ir-verdict đưa ra phán quyết chấp nhận/từ chối trên đồ thị IR ở bước phân tích tĩnh; render-verdict đưa ra phán quyết trên các artifact đã render ở bước render. Vai trò — chứ không phải kind mà plugin khai báo — quyết định những gì plugin có thể phát ra: đầu ra của một vai trò phán quyết chỉ có thể được đọc như một phán quyết, không bao giờ được áp dụng như một thay đổi; đầu ra của một vai trò biến đổi bị host giới hạn trong khía cạnh của nó (annotation hoặc nhãn). Nó cũng chọn hàm điểm vào mặc định (annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). Giá trị cho phép: "annotation-transform", "label-transform", "ir-verdict", "render-verdict" |
capability | string | không | Capability của provider mà mục này chọn plugin cho — tên capability trần mà một Recipe ràng buộc qua spec.capability (ví dụ helm, compose). Tùy chọn: một mục có thể thay vào đó gắn plugin trực tiếp theo uri. Các ràng buộc provider dùng trường này để chọn plugin của nhà phát hành nào phục vụ một capability trong một catalog liên kết; các socket xuyên suốt để trống trường này và gắn theo uri. |
function | string | không | Ghi đè tùy chọn cho hàm điểm vào mặc định của socket. Khi bỏ qua, giá trị mặc định đã được tài liệu hóa của socket được áp dụng (governance annotation-transform → transform_annotations, governance label-transform → mutate, governance ir-verdict → verdict_ir, governance render-verdict → verdict_render, linter → lint_rules). Phần ghi đè có thể nêu bất kỳ export nào plugin khai báo, và export được nêu phải trả về dạng đầu ra mà socket đó đọc: quá trình build dừng lại khi đầu ra đó mang một trường cấp cao nhất mà dạng này không khai báo, kèm tên export được gọi và trường không mong đợi. Phép kiểm tra đọc những tên trường cấp cao nhất nào có mặt, không đọc những tên nào vắng mặt hay những gì lồng bên dưới chúng, nên đây không phải là một phép xác thực đầy đủ đầu ra. |
with | PluginRefWith | không | Các đầu vào tùy chọn tại thời điểm gắn mà plugin đọc. Cả hai thành phần đều tùy chọn và không phụ thuộc vào socket, nên bất kỳ socket nào cũng có thể dùng lại bề mặt này. |
Không cho phép thuộc tính bổ sung.
FixedEntryPluginRef
Tham chiếu tới một plugin Wasm được gắn tại một socket có điểm vào cố định thay vì được đặt tên bởi việc gắn — danh sách importer và các ràng buộc providers. Nó mang cùng các trường như PluginRef nhưng không có function: socket importer gọi đúng một hàm điểm vào mà khế ước socket của nó nêu, còn một provider điều khiển một tập export cố định theo từng pha thay vì một điểm vào có thể chọn, nên trên cả hai danh sách đều không có điểm vào nào để function nêu tên và khóa này không được chấp nhận ở đó. uri và capability cùng nhau chọn plugin: chỉ có uri là gắn trực tiếp (plugin tại định danh đó được gắn nguyên văn — cách dùng của socket importer, vì plugin của nó không khai báo capability nào được phục vụ); chỉ có capability thì phân giải plugin phục vụ capability đó (tên capability trần mà một Recipe ràng buộc qua spec.capability, ví dụ helm); cả hai cùng nhau thì khử nhập nhằng — capability nêu cái cần phân giải và uri chọn plugin của nhà phát hành nào phục vụ nó, theo định danh trần của plugin đó, trong một catalog liên kết nơi có nhiều hơn một plugin phục vụ capability. role được chấp nhận ở đây nhưng không được đọc trên danh sách nào mà dạng này phục vụ: vai trò gắn governance mà nó nêu được đọc trên một mục governance, vốn dùng PluginRef, nên một vai trò đặt trên một trong các mục này không có tác dụng. with mang các đầu vào tùy chọn tại thời điểm gắn mà plugin đọc; một ràng buộc provider lấy cấu hình render từ Recipe thay vào đó, nên with: trên một ràng buộc như vậy bị từ chối khi tải.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
uri | string | không | Định danh plugin: định danh trần của một thực thể Plugin — đường dẫn <pluginType>/<name>, ví dụ governance/redact hoặc provider/helm — một đường dẫn hệ thống tệp cục bộ, hoặc một bí danh registry. Tùy chọn: một mục có thể thay vào đó chọn plugin theo capability. Một hậu tố :version tùy chọn ghim phiên bản theo cùng ba dạng như mọi lần ghim phiên bản (trần, chính xác :1.0.0, hoặc khoảng tương thích phiên bản chính :^1.0.0). |
role | string (enum) | không | Vai trò gắn governance. Không danh sách nào dùng dạng này đọc nó — vai trò được đọc trên một mục governance, và các mục đó dùng PluginRef — nên một vai trò đặt ở đây được chấp nhận và không có tác dụng. Các giá trị cho phép là bốn vai trò governance, và ý nghĩa của từng vai trò được mô tả trên PluginRef. Giá trị cho phép: "annotation-transform", "label-transform", "ir-verdict", "render-verdict" |
capability | string | không | Capability của provider mà mục này chọn plugin cho — tên capability trần mà một Recipe ràng buộc qua spec.capability (ví dụ helm, compose). Tùy chọn: một mục có thể thay vào đó gắn plugin trực tiếp theo uri. Các ràng buộc provider dùng trường này để chọn plugin của nhà phát hành nào phục vụ một capability trong một catalog liên kết; các socket xuyên suốt để trống trường này và gắn theo uri. |
with | PluginRefWith | không | Các đầu vào tùy chọn tại thời điểm gắn mà plugin đọc. Cả hai thành phần đều tùy chọn và không phụ thuộc vào socket, nên bất kỳ socket nào cũng có thể dùng lại bề mặt này. |
Không cho phép thuộc tính bổ sung.
CLIPluginRef
Một plugin mở rộng CLI đã được ghim, được cài đặt như một lệnh aggrega cấp cao nhất: tham chiếu artifact đã được phân giải và ghim phiên bản mà lệnh phân giải và chạy, cùng với digest nội dung của các byte guest mà tham chiếu đó phân giải tới tại thời điểm cài đặt. Cùng nhau, chúng ghim chính xác những byte mà lệnh thực thi; digest cũng là khóa của bộ đệm describe cung cấp tên và trợ giúp của lệnh mà không cần tải guest.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
uri | string | có | Tham chiếu artifact đã được phân giải và ghim phiên bản mà lệnh phân giải và chạy, ví dụ oci://hub.aggrega.ai/plugin/cli/<name>:1.2.0, được ghim khi cài đặt. |
digest | string | có | Digest nội dung của các byte .wasm của guest mà tham chiếu phân giải tới khi cài đặt, được viết dưới dạng sha256: theo sau là 64 chữ số thập lục phân viết thường của SHA-256 của các byte đó — cách viết mà aggrega plugin add cli ghi lại, và là cách viết được dùng để so sánh các byte đã phân giải. Một digest viết theo bất kỳ cách nào khác — thập lục phân trần không có tiền tố sha256:, chữ in hoa, hoặc độ dài khác — không bao giờ có thể bằng nó, nên bị từ chối khi tệp cấu hình được tải, kèm theo tên tệp và mục. Nó ghim chính xác các byte mà lệnh chạy — một lần phân giải sau đó có các byte băm ra khác sẽ dừng lệnh — và là khóa vào bộ đệm describe hiển thị trợ giúp của lệnh mà không cần tải guest. Mẫu: ^sha256:[0-9a-f]{64}$. |
Không cho phép thuộc tính bổ sung.
PluginRefWith
Các đầu vào tùy chọn tại thời điểm gắn mà plugin đọc. Cả hai thành phần đều là tùy chọn và bề mặt này mang tính tổng quát, nên bất kỳ socket nào cũng có thể tái sử dụng nó.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
sources | string[] | không | Các đường dẫn tệp định nghĩa mà host đọc tại thời điểm biên dịch và chuyển cho plugin. Mỗi mục là một đường dẫn hệ thống tệp được phân giải tương đối với thư mục của tệp cấu hình khai báo nó. |
settings | object | không | Đối tượng thiết lập dạng tự do được chuyển nguyên văn cho plugin. Host không diễn giải cấu trúc của nó; plugin định nghĩa các khóa mà nó đọc. |
Không cho phép thuộc tính bổ sung.