Khả năng mở rộng
Khả năng mở rộng của hệ sinh thái và rào chắn bảo vệ của trình biên dịch
1. Giao diện WebAssembly (Wasm) phổ quát
Để bảo đảm tính đối xứng kiến trúc trên toàn hệ sinh thái, Aggrega sử dụng một hợp đồng thực thi được chuẩn hóa, áp dụng thống nhất cho mọi socket Wasm trong pipeline của trình biên dịch.
Giao diện YAML để gọi bất kỳ plugin nào dựa trên hai từ khóa được chọn có chủ đích: function và with.
function: Aggrega nhúng một runtime Wasm (bộ công cụ Extism trên nền engine Wazero), thực thi Wasm trực tiếp trong bộ nhớ, nên không có tiến trình hệ điều hành nào được khởi chạy.functionnêu tên export mà host Go gọi: một hàm được export tường minh của module Wasm.with: các đầu vào riêng của plugin, tách biệt khỏivaluescủa nhà phát triển và khỏiparametersmà một Release đáp ứng. Từ khóa này theo quy ước của GitHub Actions (with:); khi một plugin khai báo JSON Schema cho các đầu vào của nó, host sẽ xác thực chúng theo schema đó trước khi thực thi.
Các loại Plugins Wasm: Giao diện function và with phổ quát này hỗ trợ mọi socket có thể lập trình trong trình biên dịch:
| Loại Plugin | Nơi chạy | Mục đích | Đầu ra mong đợi |
|---|---|---|---|
Provider (provider) | Render (tạo sinh) | Chuyển IR cuối cùng trong bộ nhớ thành các tệp vật lý dạng chuỗi cho một định dạng đích (Helm, Terraform, Compose). | Một mảng các tệp dạng chuỗi. |
Bước pipeline của FeatureRecipe (pipeline-step) | Pipeline plugin của một Recipe hoặc FeatureRecipe | Các bước tuần tự lấy secret hoặc chèn sidecar vào các AST cơ sở. | patches RFC 6902 trên tập tài liệu được đánh khóa, cùng với side_effects (phát ra một tài liệu hoặc tệp mới), diagnostics và outputs mà một bước sau có thể đọc. Đầu vào của bước mang tập tài liệu được đánh khóa đó và đầu vào with đã được render của bước. |
Quản trị (governance) | Trước khi mở rộng annotation, xây dựng topology, phân tích tĩnh hoặc giai đoạn render | Đảm nhận các vai trò quản trị của pipeline build. Trước khi mở rộng annotation, nó chèn annotation vào các thành phần đã phân giải; khi xây dựng topology, nó tự động gắn nhãn tuân thủ hoặc nhãn môi trường cho các nút (người vận hành chọn bật từng vai trò). Khi phân tích tĩnh hoặc ở giai đoạn render, nó đóng vai trò Loud Guardrail: đánh giá các cạnh, đường dẫn và nhãn của đồ thị — hoặc các artifact đã render — dựa trên các ranh giới bảo mật. Chính vai trò mà nó được gắn vào, chứ không phải loại của nó, quyết định những gì nó có thể phát ra. | Trước khi mở rộng annotation, các lần chèn annotation. Khi xây dựng topology, một mảng JSONPatch nhắm tới metadata.labels. Khi phân tích tĩnh hoặc ở giai đoạn render, các phán quyết ở mức độ halt, warn hoặc info (một chính sách Rego thu thập chúng dưới deny, warn và audit); một halt sẽ dừng bản build. |
Linter (linter) | Ngoài luồng build | Các kiểm tra FinOps hoặc vệ sinh tùy chọn (ví dụ: ước tính chi phí đám mây từ .infra) và kỷ luật tại thời điểm phát hành. | Chuỗi cảnh báo hoặc dừng nghiêm trọng. |
Phần mở rộng CLI (cli) | Runtime (aggrega <command>) | Một lệnh cấp cao nhất cắm vào là dùng được, do một plugin đã ký và chạy trong sandbox cung cấp, không cần mã Go riêng cho từng lệnh trong host. | Đầu ra chuẩn và lỗi chuẩn được truyền trực tiếp, cùng với mã thoát của guest. |
Parser (parser) | Theo yêu cầu, ở bất cứ nơi nào một định dạng bên ngoài được đọc | Chuyển văn bản nguồn bên ngoài (HCL, TOML, YAML, JSON, JSON có chú thích) thành một cây JSON chuẩn. | tree cùng với diagnostics, và spans nguồn tùy chọn. |
Importer (importer) | Theo yêu cầu, bên ngoài mọi bản build (aggrega import, trình soạn thảo và công cụ import của trợ lý) | Chuyển một nguồn hạ tầng hoặc định nghĩa agent bên ngoài (Langflow, Flowise, n8n, một cấu hình MCP, một ứng dụng Compose, một ứng dụng Dify, các agent được khai báo của một dự án CrewAI, cấu hình của một ứng dụng LangGraph, các cấu hình agent của một ứng dụng Google ADK, một agent khai báo của Agent Framework) thành các tệp soạn thảo Aggrega dạng bản nháp, đồng thời công bố các định dạng mà nó xử lý dưới dạng capability import:<format>. | Các thực thể Aggregate / Component / Release dạng bản nháp, hoặc các tham chiếu tới các Components trong catalog mà nó tái sử dụng, các quyết định ánh xạ đằng sau chúng, các chẩn đoán và các tệp scaffold cần ghi. |
Runtime host: một sandbox từ chối capability. Aggrega nhúng host Wasm dưới dạng bộ công cụ Extism chạy trên nền engine Wazero; tệp nhị phân host vẫn là Go thuần, không phụ thuộc vào toolchain gốc nào, vì vậy aggrega biên dịch chéo một cách gọn gàng. Mọi socket đều chạy sau một tường lửa thuần khiết AOT: host từ chối cấp cho plugin bất kỳ capability truy cập runtime nào — không mạng, không hệ thống tệp, không đồng hồ thực, không môi trường, không I/O chuẩn — nên một lời gọi định dùng một capability như vậy sẽ thất bại, và một plugin import từ một bề mặt host mà host không cung cấp sẽ bị từ chối khi tải. Một plugin không thể truy cập mạng hay đọc đồng hồ thì không thể phá vỡ sự bảo đảm ahead-of-time của trình biên dịch rằng cùng một đầu vào sẽ tạo ra cùng một đầu ra. Các runtime ngôn ngữ cần một vài import khởi động vô hại sẽ chạy với một cấu hình của các import đó vốn từ chối capability: host cố định đồng hồ có thể quan sát, cung cấp entropy thực, loại bỏ I/O chuẩn, và không cấp quyền truy cập hệ thống tệp, đối số hay môi trường — vì vậy một plugin không thể tới được bất kỳ capability nào của host thay đổi giữa các bản build. Entropy được cố ý để ở dạng thực thay vì cố định: cố định nó sẽ làm ổn định seed hash nội bộ và thứ tự lặp map của runtime ngôn ngữ guest, và do đó che giấu một plugin có đầu ra tự thân không tái tạo được thay vì để điều đó lộ ra dưới dạng đầu ra khác nhau. Một plugin có kết quả phụ thuộc vào entropy là một vấn đề tính tất định ở cấp soạn thảo, và cấu hình này được xây dựng để làm lộ ra vấn đề đó thay vì che giấu nó.
Phát triển dựa trên host: PDK. Tác giả plugin không tự viết tay ABI bộ nhớ Wasm. Aggrega cung cấp một Plugin Development Kit bằng ba ngôn ngữ — Go, Rust và TypeScript — là các lớp bọc mỏng trình bày đầu vào và đầu ra có kiểu của từng socket để tác giả viết các hàm thông thường. Giao diện function / with ở trên là thứ mà một Aggregate hoặc FeatureRecipe dùng để gọi một plugin; PDK là nền tảng mà tác giả plugin xây dựng dựa trên.
Mỗi socket chạy ở đâu. Mọi socket đều chạy qua cùng một host: publishing linter trong aggrega lint; các vai trò quản trị, các provider render và các bước pipeline của Recipe và FeatureRecipe trong aggrega build; các parser ở bất cứ nơi nào một định dạng ngoại lai được đọc; các importer trong aggrega import; và các plugin CLI dưới dạng lệnh cấp cao nhất. Xem Trạng thái của ngôn ngữ để biết mức độ sẵn sàng của từng socket.
Plugin nào được ghim, và plugin nào do môi trường của bạn chọn. Aggrega phân chia plugin theo việc chúng có thay đổi đầu ra mà bạn phát hành hay không. Các plugin định hình đầu ra — các provider kết xuất, các plugin quản trị được gắn ở vai trò biến đổi (label-transform, annotation-transform), và các bước pipeline của FeatureRecipe và Recipe — được ghim trong lockfile của bản phát hành khi bạn chạy aggrega pull, và được tái tạo giống hệt từng byte khi chạy aggrega build và aggrega serve chỉ từ lockfile đó. Có hai loại không được ghim, vì mỗi lần build đều đọc chúng từ cùng một nơi: một provider kết xuất được phục vụ từ bên trong tệp nhị phân của trình biên dịch, và một provider hoặc bước pipeline có thực thể Plugin được viết trong một trong các thư mục catalog của chính bạn. Để thay đổi plugin định hình đầu ra nào được áp dụng, bạn pull lại; thay đổi cấu hình workspace sau một lần pull không làm dịch chuyển đầu ra của build cho đến lần pull tiếp theo. Các plugin cổng kiểm soát — policy và lint — đánh giá một build mà không thay đổi các byte của nó, vì vậy chúng được lưu vào bộ nhớ đệm khi pull (để build vẫn có thể chạy chúng khi ngoại tuyến; plugin mà tệp nhị phân của trình biên dịch mang theo, hoặc plugin được viết trong thư mục catalog của chính bạn, thì được đọc từ đó) nhưng không được ghim: cổng nào chạy là do môi trường của bạn chọn tại thời điểm build, nên việc chia thành nới lỏng ở dev / nghiêm ngặt ở CI là một lựa chọn cấu hình thông thường chứ không phải một lần pull lại, và việc chuyển đổi cổng không bao giờ thay đổi đầu ra mà một build đạt yêu cầu tạo ra. Các Plugins chỉ tác động lên đầu vào soạn thảo, chẳng hạn như trình nhập và phần mở rộng CLI, không định hình đầu ra build nào và không được ghim cũng không thuộc tập được lưu đệm của build.
2. Pipeline Plugin của FeatureRecipe
Các FeatureRecipes gắn các ý định vận hành trừu tượng (như gắn một proxy bảo mật hoặc chèn một sidecar) với các pipeline plugin WebAssembly (Wasm) có phiên bản. Ops khai báo những gì một Feature cần tại một đích provider cụ thể; trình biên dịch thực thi pipeline đã khai báo trên đồ thị IR phẳng.
Việc gắn kết này mang lại ba hệ quả cho hệ sinh thái:
- Tách rời quá trình phát triển. Bộ từ vựng hạ tầng phát triển thông qua các plugin Wasm bên ngoài mà không cần một bản phát hành lõi của trình biên dịch Aggrega. Các provider mới, sidecar mới và tích hợp bảo mật mới được phát hành dưới dạng các tệp nhị phân Wasm độc lập dựa trên ABI Wasm ổn định.
- Phiên bản ngữ nghĩa. Các FeatureRecipes tham chiếu plugin Wasm theo phiên bản — chính xác (
:1.0.0) hoặc một khoảng dấu mũ (:^1.0.0, phiên bản cao nhất tương thích với nó). Với khoảng dấu mũ, Ops khóa một phiên bản chính trong khi vẫn nhận các bản phát hành phụ và bản vá của nó mỗi khi lockfile được phân giải lại bằngaggrega pull --upgrade. - Chuyển giao độ phức tạp. Việc sinh CRD đặc thù của nhà cung cấp hoặc kết xuất phức tạp (đối tượng policy đặc thù của nhà cung cấp, tài nguyên định tuyến gốc của provider) nằm trong các plugin Wasm thuần túy hoạt động trên đồ thị IR phẳng, thay vì phải đi xuyên qua các khai báo schema hoặc logic template bên trong định nghĩa thành phần.
Xâu chuỗi pipeline — tách biệt trách nhiệm giữa các plugin. Một pipeline FeatureRecipe có thể xâu chuỗi nhiều plugin Wasm theo tuần tự, mỗi plugin nhận cùng một ngữ cảnh nút IR từ trình biên dịch. Mẫu chuẩn phân chia trách nhiệm sao cho một plugin đơn lẻ không mang đồng thời cả ý định ngữ nghĩa của một tính năng lẫn cơ chế vật lý chặn bắt lưu lượng của một môi trường đích cụ thể.
Một chuỗi hai plugin chuẩn mực trông như sau:
- Một plugin cấu hình phát ra các quy tắc ngữ nghĩa cho tính năng (quy tắc policy bảo mật, mẫu kiểm toán, ngưỡng giới hạn tốc độ). Nó hiểu ý định của tính năng; nó không hiểu kết cấu chặn bắt lưu lượng của môi trường đích.
- Một plugin định tuyến phát ra cấu hình mesh vật lý mang các quy tắc đó (CRD của gateway, bản vá chèn sidecar, quy tắc tường lửa). Nó hiểu kết cấu của môi trường đích; nó không hiểu ý định ngữ nghĩa của tính năng.
Cả hai plugin lần lượt nhận cùng một ngữ cảnh nút IR từ trình biên dịch, nên chúng kết hợp gọn gàng mà không ràng buộc trực tiếp với nhau. Trình biên dịch điều phối pipeline; các plugin mang tri thức miền.
3. Chặn bắt lưu lượng: đích HTTPRoute
Mô hình khả năng mở rộng của Aggrega nhắm đến chuẩn HTTPRoute của Kubernetes Gateway API làm tạo phẩm dùng chung giữa các provider cho việc chặn bắt lưu lượng ở cấp mesh. Thư viện chuẩn phát ra các đối tượng HTTPRoute thông qua Feature core/http-route, mà FeatureRecipe helm của nó render một route cho mỗi thành phần được gắn; các môi trường đích sử dụng Gateway API sẽ dịch HTTPRoute sang kết cấu gốc của chúng.
4. Quyền tự chủ của Plugin: phân giải nhãn
Khi các plugin Wasm sinh tài nguyên vật lý từ đồ thị IR, các SRE cần truy ngược một Pod Kubernetes đang chạy hoặc một tài nguyên đám mây về ý định ngữ nghĩa của nhà phát triển trong Aggregate. Mô hình khả năng mở rộng của Aggrega đặt việc chuyển dịch đó hoàn toàn trong quyền kiểm soát của tác giả plugin Wasm.
Trình biên dịch chuyển toàn bộ từ điển labels của đồ thị IR vào sandbox Wasm mà không diễn giải. Từ đó, tác giả plugin — Platform Ops — quyết định logic ánh xạ: chuyển nguyên văn mọi nhãn, lọc theo các tiền tố miền cụ thể (*.aggrega.ai/*), hoặc ánh xạ trực tiếp nhãn đồ thị sang các lược đồ gắn thẻ gốc của provider (dịch một nhãn IR thành tags của AWS, annotations của Kubernetes, hoặc một cơ chế siêu dữ liệu đặc thù của đám mây). Trình biên dịch không áp đặt hạn chế nào về cách gắn thẻ cho các tạo phẩm được sinh ra.
Quyền tự chủ này giữ trí tuệ đặc thù miền — nhãn nào quan trọng cho khả năng quan sát, nhãn nào ánh xạ sang các quy ước gắn thẻ gốc, nhãn nào là nội bộ của nền tảng — bên trong lớp plugin Wasm, nơi hệ sinh thái phát triển độc lập với nhịp phát hành của trình biên dịch Go.
5. Phần mở rộng CLI: lệnh thời gian chạy
Các socket ở trên chạy bên trong một build — trình biên dịch gọi chúng khi phân tích cú pháp, biến đổi, xác thực và kết xuất một Aggregate. Socket phần mở rộng CLI khác về bản chất: nó chạy tại terminal, bên ngoài mọi build, khi người vận hành gõ aggrega <command>. Đây là cách chính bề mặt lệnh của aggrega phát triển mà không cần bản phát hành lõi.
Phần mở rộng CLI là gì. Phần mở rộng CLI là một aggrega <command> dùng ngay được đóng góp bởi một plugin Wasm đã ký và chạy trong sandbox. Nó áp dụng cùng cách tiếp cận drop-in, với logic thuộc về guest, như socket kết xuất: logic miền nằm hoàn toàn trong guest, và host Go không đóng góp mã riêng cho từng lệnh. Việc thêm một lệnh cấp cao nhất mới chỉ cần ba thứ — một tệp nhị phân .wasm, một thực thể Plugin khai báo pluginType: cli (xem Plugin), và một lệnh aggrega plugin add cli tường minh. Host phát hiện lệnh từ phần tự mô tả của plugin đã cài đặt; không có lệnh nào được biên dịch vào tệp nhị phân.
Vì sao socket thời gian chạy làm được điều mà socket build không làm được. Vì các socket thời gian biên dịch chạy trong khi build, chúng không có khả năng truy cập và mang tính tất định: Aggrega là trình biên dịch ahead-of-time, và cùng một đầu vào phải luôn tạo ra cùng một đầu ra (xem Các bất biến kiến trúc). Do đó, một plugin kết xuất hoặc policy không thể truy cập mạng, đọc đồng hồ, hay truyền luồng ra terminal — bất cứ thứ gì thay đổi giữa các lần chạy đều sẽ phá vỡ đảm bảo đó. Phần mở rộng CLI chạy sau và bên ngoài ranh giới đó, được điều khiển bởi một người tại dấu nhắc lệnh thay vì bởi pipeline tất định. Chính vì vậy mà một plugin CLI được phép truyền luồng đầu ra chuẩn và lỗi chuẩn trong khi chạy và trả về mã thoát của tiến trình: không có tạo phẩm build nào có độ ổn định từng byte bị những tác động đó đe dọa.
Cài đặt, chạy và khám phá. aggrega plugin add cli <query> tìm trong registry đã cấu hình một plugin cli phù hợp, xác minh nó theo chính sách tin cậy của registry, và cài đặt nó thành một lệnh cấp cao nhất — trước tiên in ra các khả năng mà plugin khai báo, để người vận hành xác nhận chính xác lệnh được phép làm gì trước khi nó được cài đặt. Sau khi cài đặt, aggrega <command> chạy nó như mọi lệnh tích hợp sẵn. Một plugin CLI khai báo các lệnh và cờ của chúng trong phần tự mô tả describe(), và host hiển thị cờ của từng lệnh trong aggrega help <command> giống hệt như với lệnh tích hợp sẵn, nhờ đó người vận hành khám phá các --flags của một lệnh đã cài đặt theo cùng một cách. Để tìm các lệnh có thể cài đặt và nội dung catalog, aggrega search truy vấn chỉ mục cục bộ của các registry đã cấu hình — --kind plugin --plugin-type cli thu hẹp kết quả về các plugin CLI có thể cài đặt, và một lần tìm kiếm không lọc sẽ bao gồm các thực thể catalog; aggrega plugin list hiển thị những gì đã được cài đặt. Các cờ và dạng đầu ra của từng lệnh được trình bày trên các trang tham chiếu đó.
Mô hình khả năng. Một phần mở rộng CLI bắt đầu từ một mức cơ sở cố định mà mọi lệnh đều nhận được mà không cần khai báo và không cần hỏi xác nhận:
| Khả năng cơ sở | Được cấp |
|---|---|
| Đối số dòng lệnh đầu vào | Luôn luôn |
| Đầu ra chuẩn và lỗi chuẩn được truyền luồng | Luôn luôn |
| Mã thoát của tiến trình đầu ra | Luôn luôn |
Mọi thứ vượt quá mức cơ sở đều tắt theo mặc định. Một plugin cần nhiều hơn sẽ khai báo tường minh từng khả năng bổ sung, và host chỉ cấp khả năng đó sau khi hiển thị nó lúc cài đặt để người vận hành xác nhận. Một lớp khả năng được thêm vượt quá mức cơ sở — truy cập môi trường, hệ thống tệp hoặc mạng, nhập liệu tương tác — được cấp sau cùng một cổng khai báo và xác nhận, nên một lệnh không bao giờ có thể âm thầm có được phạm vi tiếp cận mà người vận hành chưa phê duyệt.
Lệnh tích hợp sẵn luôn được ưu tiên. Một plugin đã cài đặt không bao giờ có thể che khuất một lệnh tích hợp sẵn. Một cơ chế bảo vệ tên dành riêng dựa trên denylist bảo vệ các lệnh tích hợp sẵn và một tập tên dành riêng cho lệnh tích hợp sẵn, và một xung đột sẽ bị từ chối khi cài đặt thay vì được phép ghi đè hành vi lõi. Bề mặt lệnh mà người vận hành dựa vào vẫn ổn định, bất kể những gì được cài đặt bên trên.
6. Plugins trình phân tích cú pháp: đọc định dạng ngoại
Trình biên dịch thường xuyên cần đọc văn bản được viết ở một định dạng mà nó không tạo ra — một module Terraform bằng HCL, một tệp cấu hình bằng TOML, một manifest bằng YAML hoặc JSON. Socket trình phân tích cú pháp cung cấp khả năng đọc đó mà không cần dạy lõi trình biên dịch bất kỳ định dạng cụ thể nào. Một trình phân tích cú pháp là một plugin phi trạng thái biến văn bản nguồn ngoại thành một cây JSON có cấu trúc: đưa cho nó các byte của một tệp HCL và nó trả về cùng nội dung dưới dạng một đối tượng JSON mà phần còn lại của pipeline đã biết cách duyệt. Bất kỳ phần nào của trình biên dịch cần đọc một định dạng mà nó không phân tích nguyên bản sẽ yêu cầu một cây đã phân tích và làm việc từ đó.
Định dạng là một khả năng, không phải một tính năng của trình biên dịch. Một trình phân tích cú pháp công bố các định dạng mà nó xử lý dưới dạng khả năng — parse:hcl, parse:toml, v.v. — và host phân giải trình phân tích cú pháp theo định dạng được yêu cầu, chạy nó, rồi trả lại cây. Đây chính là mô hình drop-in, dựa trên khả năng được công bố, mà các provider kết xuất và plugin CLI áp dụng: lõi trình biên dịch không giữ danh sách định dạng tích hợp nào, nên thêm một định dạng là phát hành một plugin phân tích cú pháp mới, không bao giờ là một bản phát hành lõi. Các trình phân tích cú pháp cho HCL, TOML, YAML, JSON và JSON có chú thích được đóng gói trong tệp nhị phân như một bộ khởi đầu; doanh nghiệp cần định dạng khác sẽ phát hành một plugin phân tích cú pháp công bố định dạng đó.
Việc chọn định dạng mang tính khai báo, không bao giờ đoán. Host không bao giờ kiểm tra nội dung của một tệp để quyết định tệp đó là gì. Nó chọn định dạng thông qua các tín hiệu được khai báo theo một thứ tự ưu tiên cố định. Một provider kết xuất có thể khai báo định dạng của từng tệp mà nó phát ra, và host ưu tiên tuyệt đối định dạng do bên sản xuất khai báo đó — provider đã ghi các byte là bên có thẩm quyền về cách đọc chúng. Với tệp mà bên sản xuất không gắn thẻ, một bảng ánh xạ phần mở rộng tệp cố định là phương án dự phòng — .tf chọn HCL, .toml chọn TOML, .yaml chọn YAML, .json chọn JSON. Việc chọn theo định dạng đã khai báo hoặc phần mở rộng cố định giữ cho việc phân tích cú pháp tất định và dễ hiểu: cùng một đầu vào luôn được định tuyến tới cùng một trình phân tích cú pháp, và người vận hành có thể biết trình phân tích cú pháp nào sẽ chạy mà không cần biết các byte bên trong tệp. Việc dò nội dung sẽ khiến lựa chọn phụ thuộc vào payload, và Aggrega không làm điều đó.
Trình phân tích cú pháp hoàn toàn mang tính cú pháp. Đầu ra là một cây JSON cùng các chẩn đoán, và tùy chọn là vị trí nguồn mà mỗi nút xuất phát. Trình phân tích cú pháp không mang ý nghĩa Aggrega nào — nó báo cáo những gì văn bản nói về mặt cấu trúc, không gì về ý nghĩa của nó như một Component, một Recipe, hay bất kỳ thực thể nào khác. Việc biến một cây đã phân tích thành các thực thể Aggrega là một mối quan tâm riêng nằm ở nơi khác; nhiệm vụ duy nhất của trình phân tích cú pháp là dịch trung thực từ cú pháp sang JSON. Hướng đọc là một chiều theo cùng tinh thần đó: trình phân tích cú pháp đọc một định dạng thành cây, nó không ghi ngược lại thành định dạng.
Một bên tiêu thụ: policy trên HCL của Terraform. Một policy ở giai đoạn kết xuất cần kiểm tra Terraform mà một build tạo ra không tự học HCL. Host phân tích tạo phẩm HCL thông qua socket trình phân tích cú pháp và trao cho plugin policy cây JSON mà nó vốn đã đọc, nhờ đó policy suy luận trên dữ liệu có cấu trúc theo đúng dạng mà mọi socket khác nhận được. Các trình đọc định dạng ngoại mới kết hợp theo cùng cách — yêu cầu host cung cấp cây, rồi làm việc với JSON — nhờ đó khả năng hiểu định dạng của trình biên dịch tăng lên bằng cách thêm plugin phân tích cú pháp thay vì mở rộng lõi.
7. Plugins trình nhập: soạn bản nháp tệp soạn thảo từ nguồn ngoại
Một nhóm hiếm khi bắt đầu từ trang giấy trắng. Kiến trúc agent của nhóm thường đã tồn tại ở đâu đó — một flow Langflow hoặc Flowise, một workflow n8n, một ứng dụng Dify, các máy chủ MCP mà một client được cấu hình, một ứng dụng Compose, các agent mà cấu hình của một framework khai báo. Socket trình nhập biến nguồn ngoại đó thành một khởi đầu thực sự cho việc soạn thảo Aggrega: nó đọc nguồn và tạo bản nháp đầu tiên của các thực thể Aggregate và Component, và từ một cấu hình MCP, một ứng dụng Compose hoặc cấu hình được khai báo của một framework là một bản nháp Release, để tác giả xem xét và hoàn thiện, nhờ đó nhóm mang những gì đã có sang Aggrega thay vì viết lại bằng tay. Trình nhập ánh xạ ý nghĩa — nó đọc một nút nguồn là gì và đề xuất thực thể Aggrega đại diện cho nút đó, hoặc để nút đó lại bên trong flow mà nền tảng được soạn nháp mang theo; trình biên dịch chuyển tiếp các thực thể được phát ra một cách không minh bạch, đúng như cách nó vẫn không phụ thuộc vào những gì bất kỳ plugin nào tạo ra.
Định dạng là một khả năng, không phải một tính năng của trình biên dịch. Một trình nhập công bố các định dạng mà nó xử lý dưới dạng khả năng — import:langflow, import:flowise, import:n8n, import:mcp, import:compose, import:dify, import:crewai, import:langgraph, import:google-adk, import:agent-framework, v.v. — và host phân giải trình nhập theo định dạng được yêu cầu, chạy nó, rồi nhận lại các thực thể mà nó đã soạn nháp. Đây chính là mô hình drop-in, dựa trên khả năng được công bố, mà socket trình phân tích cú pháp áp dụng với parse:<format>: lõi trình biên dịch không giữ danh sách định dạng có thể nhập tích hợp nào, nên hỗ trợ một định dạng mới là phát hành một plugin trình nhập công bố định dạng đó, không bao giờ là một bản phát hành lõi.
Trình nhập đọc thông qua socket trình phân tích cú pháp; nó không phân tích lại. Trình nhập cần dạng có cấu trúc của nguồn, nhưng không triển khai lại việc đọc một định dạng mà hệ sinh thái đã phân tích được. Khi cần cây, nó yêu cầu host chạy trình phân tích cú pháp tương ứng — trình mà catalog của workspace phục vụ cho cú pháp của nguồn, hoặc, nơi catalog không phục vụ trình nào, trình mà chính trình biên dịch mang theo — thông qua cùng khả năng phân tích cú pháp do host làm trung gian mà phần còn lại của pipeline sử dụng, và làm việc từ cây JSON được trả về. Việc đọc (từ cú pháp sang cây) vẫn là việc của trình phân tích cú pháp; việc ánh xạ (từ cây sang thực thể Aggrega) là việc của trình nhập. Hai socket kết hợp mà không trùng lặp nhau: trình nhập bổ sung trí tuệ ánh xạ cho một nguồn và dựa vào trình phân tích cú pháp sẵn có cho phần byte.
Định dạng được nhận diện từ những gì trình nhập của nó khai báo, không bao giờ đoán. Một lần nhập có thể nêu thẳng định dạng nguồn của nó. Nếu không, định dạng được nhận diện từ các chữ ký mà mỗi trình nhập khai báo trong phần tự mô tả và được thực thể Plugin của nó ghi lại: cú pháp mà nguồn được đọc, các tên tệp mà một chữ ký áp dụng, và các đường dẫn mà cây đã phân tích phải hoặc không được chứa. Host không tự biết định dạng nào. Nó phân tích nguồn thông qua trình phân tích cú pháp mà catalog của workspace phục vụ cho mỗi cú pháp mà một chữ ký nêu tên — hoặc trình của trình biên dịch nơi catalog không phục vụ trình nào — đánh giá các vị từ đã khai báo trên cây được trả về, và đọc nguồn theo định dạng của trình nhập duy nhất có chữ ký khớp. Các chữ ký được khai báo thay thế vai trò mà bảng ánh xạ phần mở rộng tệp cố định đảm nhận cho socket trình phân tích cú pháp, vì các định dạng mà một lần nhập đọc có thể dùng chung phần mở rộng — một bản xuất Langflow, một bản xuất Flowise và một workflow n8n đều là tệp JSON. Một nguồn không khớp chữ ký nào sẽ bị từ chối, kèm yêu cầu cung cấp định dạng và nêu tên các định dạng mà các trình nhập công bố — hoặc, với một thư mục, kèm yêu cầu cung cấp riêng một trong các tệp của nó hoặc một định dạng có trình nhập khai báo mẫu tệp, và chỉ nêu tên các định dạng đó; một nguồn khớp chữ ký của nhiều hơn một định dạng sẽ bị từ chối, kèm tên các định dạng đó. Việc nhận diện không đọc gì ngoài nguồn và không truy cập mạng, nên nhận diện một định dạng mới là một khai báo do trình nhập mới mang theo, không bao giờ là một thay đổi đối với host. Các quy tắc viết chữ ký nằm trong Socket trình nhập.
Thư mục được đọc thông qua các tệp mà trình nhập của nó khai báo. Một nguồn là một tệp hoặc một thư mục. Một tệp được trao nguyên vẹn cho trình nhập. Một thư mục được đọc thành các nguồn có tên — chính xác những tệp trong đó mà các mẫu tệp trong chữ ký của trình nhập chọn, mỗi tệp được đặt tên theo đường dẫn bên trong thư mục, theo thứ tự đã sắp xếp — và không tệp nào khác của thư mục được mở; một liên kết dẫn việc đọc ra ngoài thư mục sẽ bị từ chối trước khi bất cứ thứ gì được đọc. Một trình nhập không khai báo mẫu tệp nào sẽ đọc một tệp và từ chối thư mục, và một thư mục không chứa tệp nào mà các mẫu của trình nhập chọn cũng bị từ chối. Các trình nhập Langflow, Flowise, n8n, Dify và Agent Framework của trình biên dịch không khai báo mẫu nào, nên mỗi trình đọc một tệp flow, workflow hoặc ứng dụng đã xuất, hoặc một agent khai báo; trình nhập MCP của nó khai báo tên tệp của các cấu hình client MCP mà nó đọc, nên thư mục của một dự án được đọc thông qua các cấu hình mà nó chứa; trình nhập Compose của nó khai báo các tên tệp mà Compose đọc theo mặc định, nên thư mục của một dự án được đọc thông qua tệp Compose của nó và tệp override mà Compose hợp nhất lên trên; và trình nhập CrewAI của nó khai báo các tên tệp mà một dự án CrewAI dùng để khai báo agent và tác vụ, nên thư mục của một dự án được đọc thông qua các khai báo đó và chương trình của nó không bao giờ được đọc; và trình nhập LangGraph của nó khai báo langgraph.json, nên thư mục của một ứng dụng chỉ được đọc thông qua cấu hình của nó, mã và các tệp môi trường không bao giờ được đọc, một tệp môi trường mà cấu hình nêu tên chỉ đến được trình nhập khi with.sources trong phần gắn kết của nó trao tệp đó, và khi ấy chỉ để lấy tên các biến; và trình nhập Google ADK của nó khai báo root_agent.yaml, nên thư mục của một ứng dụng chỉ được đọc thông qua cấu hình agent gốc của nó, các cấu hình mà các agent con nêu tên chỉ đến được trình nhập khi with.sources trong phần gắn kết của nó trao chúng, và cả mã lẫn tệp môi trường của nó đều không bao giờ được đọc.
Việc ánh xạ mang tính tất định, có điểm tin cậy và được cân nhắc dựa trên catalog của chính bạn. Host trao cho trình nhập một khung nhìn về các Components mà catalog của chính workspace chứa — catalog mà trình nhập được chọn từ đó — các thư mục catalog của workspace, hoặc, khi workspace không nêu tên thư mục nào, ảnh chụp catalog mà registry mặc định của nó công bố — các Components của một catalog doanh nghiệp y như của thư viện chuẩn. Khung nhìn chứa tên, phiên bản và nhãn của mỗi Component, tên các khóa mà values và provides của nó khai báo, và bộ chọn của các socket của nó, và không bao giờ chứa một giá trị, một giá trị mặc định hay một bí mật; không có gì được tải về để tạo nó ngoài ảnh chụp đó, và thứ tự của nó cố định, nên một catalog cho ra một khung nhìn. Một trình nhập được xây dựng trên gói importer của PDK Go — trong đó có các trình nhập Langflow, Flowise, n8n và Compose của chính trình biên dịch — cân nhắc từng nút trong nguồn dựa trên các Components đó và không gì khác, với một mô hình tin cậy tất định không dùng mô hình AI, và ghi lại quyết định — các ứng viên đã cân nhắc, mức khớp đã gán, và lựa chọn đã đưa ra — dưới dạng các gợi ý có thể xem xét mà tác giả có thể đọc và sửa đổi. Một Component mà catalog có thêm sẽ là ứng viên ở lần nhập tiếp theo, mà không cần xây dựng lại trình nhập nào. Mặc định chỉ là gợi ý: lần nhập đề xuất, và tác giả quyết định. Một kết quả khớp có độ tin cậy cao có thể được ghi thành tham chiếu tới một thành phần catalog có sẵn thay vì một phần thân mới soạn nháp, nhưng chỉ khi người vận hành chủ động bật — luôn dưới dạng một đề xuất tường minh, có thể đảo ngược mà tác giả quyết định, không bao giờ là một lần viết lại âm thầm. Vì việc chấm điểm không dùng mô hình nào và không tra cứu lúc chạy, cùng một nguồn được chấm điểm dựa trên cùng một catalog luôn cho ra cùng các gợi ý.
Một flow được soạn nháp thành nền tảng chạy nó. Một flow Langflow, một chatflow Flowise và một workflow n8n chạy trên một nền tảng, và theo mặc định một lần nhập soạn nháp nền tảng đó thay vì các nút của flow: một instance của Component nền tảng trong thư viện chuẩn — core/ai-agent/langflow, core/ai-agent/flowise hoặc core/ai-agent/n8n — mang flow như khi được xuất trong giá trị flow_definition của nó, mà nền tảng nạp khi triển khai. Mỗi phần của flow mà một socket của nền tảng tiếp nhận — trên các nền tảng của thư viện chuẩn, là một mô hình, một máy chủ MCP hoặc một công cụ khác được truy cập qua HTTP, và một vector store — trở thành một Component riêng, được tham chiếu hoặc soạn nháp tùy theo quyết định ánh xạ, và được nối vào socket đó dưới uses của nền tảng. Như vậy mỗi lời gọi mà flow thực hiện tới một mô hình, một công cụ hoặc một store là một kết nối mà Aggregate khai báo: một plugin quản trị đánh giá đồ thị sẽ thấy nó như thấy mọi cạnh khác, và allowlist egress của thư viện chuẩn, mà thiết lập attach_egress_allowlist gắn vào nền tảng, chỉ cho phép nền tảng kết nối tới những gì các kết nối của nó vươn tới, các pod của chính nó và DNS của cụm. Khi định dạng cho phép, bản nháp ghi vào flow được mang theo những gì khiến flow vươn tới từng phần thông qua kết nối của nó. Mọi nút khác — một agent, một chain, một trigger — ở lại bên trong flow được mang theo và không trở thành Component nào, với quyết định của nó ghi lại các ứng viên mà nó đã được cân nhắc. Một ứng dụng Dify được soạn nháp theo cùng cách, theo hình thức mà cả một bản cài đặt có: một mục của bản cài đặt Dify mà thư viện chuẩn lắp ráp, core/dify, mang ứng dụng trong tham số app_definition của nó, với bản cài đặt tự nối các kết nối của nó. Thiết lập layout trong phần gắn kết của trình nhập chọn bản nháp: platform, mặc định, hoặc nodes, soạn nháp mỗi nút của nguồn thành một Component riêng, mỗi cạnh của flow thành một kết nối uses, và không mang flow nào. Nền tảng mang flow trình bày những nút nào trở thành các phần và mỗi nút được nối ở đâu.
Một framework code-first được đọc thông qua cấu hình được khai báo, không bao giờ thông qua chương trình của nó. CrewAI, LangGraph, Google ADK và Agent Framework giữ hành vi của một ứng dụng trong chương trình của nó và khai báo các agent, đồ thị và mô hình của nó trong cấu hình đặt bên cạnh. Các trình nhập của chúng chỉ đọc các khai báo đó — các tệp agent và tác vụ của một dự án CrewAI, langgraph.json của một ứng dụng LangGraph, các cấu hình agent của một ứng dụng Google ADK, một agent khai báo của Agent Framework — và soạn nháp agent của thư viện chuẩn dành cho framework đó quanh một chương trình mà chúng không bao giờ mở, được nối với những gì các khai báo nêu tên: mô hình mà một agent yêu cầu, khi socket model của agent chấp nhận nó, và kho dữ liệu nơi một checkpointer LangGraph lưu trạng thái. Một máy chủ MCP mà một agent Agent Framework nêu tên do nhà cung cấp mô hình truy cập, dưới dạng một công cụ được lưu trữ, nên bản nháp nêu tên nó trong các chú thích và không nối gì với nó. Chương trình chạy trong image mà Release nêu tên. Những gì chỉ chương trình nói — logic của một tác vụ, một công cụ mà mã của nó định nghĩa, một agent mà mã của nó xây dựng — được nêu tên trong các chú thích và quyết định của bản nháp và không trở thành Component nào; việc đưa chúng vào các tệp soạn thảo là công việc của tác giả, bằng tay hoặc với một trợ lý AI soạn thảo thay mặt tác giả thông qua aggrega mcp, công cụ đọc tài liệu tham chiếu, tạo khung và xác thực các thực thể.
Những gì một nguồn nêu về cách các phần của nó chạy sẽ nằm trong một bản nháp Release. Các đầu vào vận hành là thứ Release cung cấp, nên các trình nhập MCP, Compose, CrewAI, LangGraph, Google ADK và Agent Framework soạn nháp một Release bên cạnh Aggregate, được spec.aggregate của nó nêu tên: Release mang những gì nguồn nêu — dòng lệnh hoặc địa chỉ của một máy chủ, image và cổng của một máy chủ chung, endpoint của một mô hình — và, trong các chú thích phía trên mỗi mục, những gì nguồn nêu mà không khóa nào của Component được soạn nháp tiếp nhận, chẳng hạn các volume của một dịch vụ hoặc môi trường của một cấu hình. Những gì không nguồn nào nêu — image chạy chương trình của một framework, thông tin xác thực mà một kết nối xuất trình, metadata.environment và spec.manifest của Release — được nêu tên trong một chú thích tại vị trí của nó, để người vận hành cung cấp, và build dừng lại, nêu tên mục nào trong image, môi trường và manifest vẫn chưa được thiết lập. Một bản nháp nền tảng không ghi Release nào: chú thích phía trên instance của nền tảng nêu tên những gì Release cung cấp — các đầu vào riêng của nền tảng, chẳng hạn image mà nó chạy hoặc tài khoản chủ sở hữu của nó, địa chỉ của mỗi máy chủ MCP được nối, và thông tin xác thực mà mỗi kết nối xuất trình.
Một giá trị thông tin xác thực mà nguồn chứa được giữ nguyên như đã viết trừ khi có yêu cầu xóa nó. Một trình nhập xác định mọi giá trị trong nguồn có thể chứa thông tin xác thực, mỗi giá trị thuộc một lớp: những gì định dạng đánh dấu là thông tin xác thực, một thành phần trong cấu hình của một máy chủ MCP, hoặc một đầu vào mà định dạng đánh dấu không phải thông tin xác thực nhưng vẫn có thể chứa thông tin xác thực, chẳng hạn các header của một yêu cầu. Theo mặc định không giá trị nào bị ghi rỗng: mỗi giá trị có nội dung được giữ nguyên như đã viết — trong flow hoặc ứng dụng mà nền tảng mang theo, hoặc trong bản nháp Release — và được nêu tên trong một cảnh báo credential-carried theo vị trí của nó — nút, máy chủ, dịch vụ hoặc agent của nó, và trường của nó — không bao giờ theo giá trị của nó, cùng với giá trị thiết lập sẽ ghi rỗng nó. Thiết lập empty_credentials bật việc xóa, mỗi lần một lớp: marked ghi rỗng những gì định dạng đánh dấu là thông tin xác thực và mọi thành phần trong cấu hình của một máy chủ MCP, và all thêm cả các đầu vào được đánh dấu không phải thông tin xác thực, mỗi giá trị bị ghi rỗng được báo cáo bằng credential-emptied. Những gì bản nháp ghi để một flow vươn tới kết nối của nó là phần nối dây, được ghi bất kể thiết lập nói gì, và một kết nối trong bản nháp không mang thông tin xác thực nào: Release gắn thông tin xác thực mà mỗi kết nối xuất trình. Một tệp mà nguồn chỉ trỏ tới, chẳng hạn một tệp môi trường, chỉ được đọc để lấy tên các biến, nếu có được đọc, và một bản nháp được tạo theo từng nút không đọc giá trị nào. Những gì nằm ngoài các vị trí mà trình nhập xác định — mã của một thành phần tùy chỉnh, một prompt — là phần tác giả cần xem xét trước khi chia sẻ bản nháp, như Các giá trị thông tin xác thực mà flow chứa trình bày.
Lệnh, trình soạn thảo và trợ lý chạy cùng một lần nhập. aggrega import <file or directory> chạy một lần nhập từ terminal; trình soạn thảo chạy cùng thao tác đó qua yêu cầu aggrega/import của phiên làm việc, và trợ lý AI qua công cụ import được cung cấp bởi aggrega mcp. Cả ba chọn importer theo cùng một cách, trong số các importer mà danh mục của workspace chứa và các importer lõi của trình biên dịch: importer mà một liên kết plugins.importer chỉ định, khi nó chỉ định một importer có quảng bá định dạng đó, và nếu không thì là phiên bản cao nhất của importer duy nhất quảng bá định dạng đó — các importer mang hai tên khác nhau cho cùng một định dạng mà không có cái nào được liên kết sẽ dừng lần nhập và nêu tên cả hai, như Importer nào biến một nguồn thành bản nháp trình bày. Cả ba báo cáo các quyết định ánh xạ bên cạnh bản nháp. Lệnh in ra standard error một dòng cho mỗi node được ánh xạ, nêu tên Component hoặc bản nháp được chọn cho node đó, việc nó được tham chiếu hay được tạo bản nháp, cấp độ khớp và, khi importer đã cân nhắc một ứng viên, điểm của ứng viên tốt nhất; trình soạn thảo hiển thị cùng các dòng đó, còn kết quả phiên của trình soạn thảo và câu trả lời của trợ lý mang đầy đủ từng quyết định. Nhờ vậy, tác giả thấy được lần nhập đã phỏng đoán ở đâu, trên bất kỳ bề mặt nào đã chạy nó, mà không cần mở bản nháp. --format chỉ định rõ định dạng nguồn — ví dụ langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk hoặc agent-framework — thay cho việc tự nhận diện. Lệnh đặt các thực thể và mọi tệp scaffold mà lần nhập tạo ra bên dưới thư mục gốc của workspace, hoặc bên dưới thư mục mà --output-dir chỉ định; --dry-run làm mọi việc lệnh làm ngoại trừ ghi, trả về các tệp đã tạo bản nháp dưới dạng nội dung và nêu tên tệp mà mỗi nội dung dành cho, để tác giả có thể xem lại scaffold trước khi commit bất cứ thứ gì vào cây làm việc.
Các trình nhập lõi. Các trình nhập lõi mà trình biên dịch phát hành đọc các định dạng sau, mỗi định dạng một trình nhập:
- Langflow — một flow được xuất từ Langflow, soạn nháp thành nền tảng Langflow của thư viện chuẩn mang flow đó, với mỗi phần của nó mà một socket tiếp nhận được nối vào socket đó.
- Flowise — một chatflow hoặc agentflow được xuất từ Flowise, soạn nháp thành nền tảng Flowise của thư viện chuẩn mang nó, với mỗi phần của nó mà một socket tiếp nhận được nối vào socket đó.
- n8n — một workflow được xuất từ n8n, soạn nháp thành nền tảng n8n của thư viện chuẩn mang nó, với mỗi phần của nó mà một socket tiếp nhận được nối vào socket đó.
- Dify — một ứng dụng được xuất từ Dify, soạn nháp thành bản cài đặt Dify mà thư viện chuẩn lắp ráp và mang ứng dụng đó, với các mô hình, công cụ và cơ sở tri thức mà nó nêu tên được báo cáo là đã cấu hình bên trong Dify.
- MCP — cấu hình của một client MCP hoặc mô tả máy chủ của một registry MCP, với mỗi máy chủ được soạn nháp thành một instance của công cụ MCP trong thư viện chuẩn, kèm một
Releasemang dòng lệnh, địa chỉ hoặc image của mỗi máy chủ. - Compose — một định dạng hạ tầng, với mỗi dịch vụ của một ứng dụng Compose được soạn nháp thành Component catalog khớp với image của nó — thông qua một bảng mà trình nhập mang theo, được sinh từ các Recipes và Components Compose của catalog chuẩn khi trình nhập được xây dựng — hoặc thành một máy chủ chung chạy image của nó, kèm một
Releasemang image và cổng của mỗi máy chủ chung và, trong các chú thích, các cổng, volume và môi trường mà mỗi dịch vụ khai báo. - CrewAI — các agent mà một dự án CrewAI khai báo trong các tệp cấu hình của nó, mỗi agent được soạn nháp thành agent CrewAI của thư viện chuẩn mang vai trò, mục tiêu và tiểu sử của nó và được nối với mô hình mà nó nêu tên, với các tác vụ và công cụ của dự án được báo cáo là thuộc về chương trình của nó, bản thân chương trình không bao giờ được đọc, kèm một
Releaseđể người vận hành tự nêu tên image chạy nó. - LangGraph — các đồ thị mà cấu hình của một ứng dụng LangGraph khai báo, mỗi đồ thị được soạn nháp thành agent LangGraph của thư viện chuẩn mang đường dẫn import của đồ thị và được nối với kho dữ liệu nơi checkpointer của nó lưu trạng thái, kèm một
Releasenêu, trong một chú thích, môi trường mà cấu hình khai báo, và mã của các đồ thị không bao giờ được đọc. - Google ADK — các cây agent mà các cấu hình agent của một ứng dụng Google ADK khai báo, mỗi cây được soạn nháp thành agent ADK của thư viện chuẩn được nối với mô hình mà nó nêu tên khi ADK gửi các yêu cầu của mô hình đó đến Gemini API, còn một mô hình được truy cập theo bất kỳ cách nào khác — chẳng hạn qua một chuỗi mô hình LiteLLM — được nêu tên trong một chú thích và kết nối của nó được để lại cho tác giả, kèm một
Releaseđể người vận hành tự nêu tên image chạy ứng dụng, và mã của ứng dụng không bao giờ được đọc. - Agent Framework — một agent khai báo của Agent Framework, được soạn nháp thành agent Agent Framework của thư viện chuẩn được nối với mô hình OpenAI mà nó nêu tên, mỗi máy chủ MCP mà nó nêu tên được ghi trong các chú thích vì nhà cung cấp của mô hình truy cập máy chủ đó như một công cụ được lưu trữ, kèm một
Releasemang endpoint của mô hình và, trong một chú thích, địa chỉ của mỗi máy chủ, và mã của ứng dụng không bao giờ được đọc.
Chúng là các plugin trình nhập như mọi plugin khác — trí tuệ ánh xạ đặc thù định dạng nằm trong chúng, không nằm trong lõi — được xây dựng từ mã nguồn của trình biên dịch và được công bố cùng mỗi bản phát hành của trình biên dịch theo phiên bản của bản phát hành đó. Không trình nào được biên dịch vào tệp nhị phân: tệp nhị phân mang thực thể Plugin của từng trình và digest của module duy nhất mà nó chấp nhận, nên mỗi trình phục vụ định dạng của mình trong mọi workspace mà không cần mục catalog nào. Lần nhập đầu tiên cần một trình nhập mà máy chưa có sẽ tải nó từ registry mặc định của workspace, ràng buộc nó với digest đó, xác minh nó như cách một lần pull xác minh một plugin mà nó tải về — chữ ký của nó theo chính sách tin cậy của registry đó, và các hàm host mà nó sử dụng — rồi lưu nó trong bộ nhớ đệm nội dung của workspace; mọi lần nhập sau đó đều đọc nó từ đó, không cần truy cập mạng cho nó. Một lần nhập không ghim trình nhập nào: không có gì khác được ghi cho nó — không có mục lockfile và không có bản ghi plugin tin cậy nào — và không lần pull nào lưu đệm nó cũng như không build nào đọc nó. Một module không vượt qua xác minh sẽ bị từ chối, và không có gì được giữ lại. Khi không thể tải module — workspace đang ngoại tuyến, không truy cập được registry của nó, hoặc registry không chứa nó — lần nhập dừng lại, nêu tên trình nhập, phiên bản của nó và những gì đưa module của nó lên máy. Lựa chọn vẫn thuộc về workspace: một trình nhập mà catalog của nó chứa dưới một tên khác cho một trong các định dạng này sẽ chạy ở nơi một phần gắn kết plugins.importer nêu tên nó, và một trình nhập có cùng tên và cùng phiên bản với một trình nhập lõi sẽ chạy thay cho trình nhập lõi đó.
Khởi tạo và phát triển một danh mục
Một danh mục không cần được xây dựng từ con số không. Phần lớn công việc khởi tạo Recipes và plugin cho một môi trường mới là dựng khung (scaffolding) và tái sử dụng, thay vì tự tay viết từng tệp nhị phân.
Nhập một nguồn bên ngoài thành bản nháp tệp authoring. aggrega import <file or directory> đọc một nguồn định nghĩa agent dạng khai báo — một flow Langflow hoặc Flowise, một workflow n8n, hoặc cấu hình của một client MCP hay mô tả máy chủ trong một registry MCP —, một ứng dụng Compose, một ứng dụng Dify, các agent mà một dự án CrewAI khai báo, các đồ thị mà cấu hình của một ứng dụng LangGraph khai báo, các agent mà cấu hình agent của một ứng dụng Google ADK khai báo, hoặc một agent khai báo của Agent Framework, rồi dựng bản nháp đầu tiên của YAML Aggregate và Component, và từ một nguồn MCP, Compose, CrewAI, LangGraph, Google ADK hoặc Agent Framework thì thêm một bản nháp Release, để tác giả xem lại và hoàn thiện, nhờ đó một nhóm tiếp tục với những gì đã có thay vì tự tay viết lại. Với mỗi node của một flow, và mỗi dịch vụ của một ứng dụng Compose, lệnh chấm điểm các Components trong danh mục riêng của workspace — danh mục doanh nghiệp cũng như thư viện chuẩn — bằng một mô hình độ tin cậy tất định, không dùng mô hình, và ghi lại quyết định — các ứng viên đã cân nhắc, cấp độ đã gán và lựa chọn đã đưa ra — dưới dạng gợi ý có thể xem xét, mà lệnh, trình soạn thảo và trợ lý đều báo cáo; một kết quả khớp có độ tin cậy cao có thể được ghi thành tham chiếu danh mục khi người vận hành bật tùy chọn này, luôn ở dạng gợi ý tường minh, có thể đảo ngược và do tác giả phê duyệt, chứ không phải một lần viết lại âm thầm. Mỗi Component mà một danh mục có thêm là một ứng viên mà lần nhập tiếp theo cân nhắc. Trí tuệ ánh xạ riêng cho từng định dạng nằm trong một plugin importer: các importer Langflow, Flowise, n8n, MCP, Compose, Dify, CrewAI, LangGraph, Google ADK và Agent Framework của trình biên dịch phục vụ các định dạng đó trong mọi workspace, được tải về và xác minh ở lần dùng đầu tiên, và một danh mục thêm một định dạng bằng cách chứa một plugin importer quảng bá định dạng đó. Một nguồn dạng thư mục được đọc qua các mẫu tệp mà importer của nó khai báo; các importer Langflow, Flowise, n8n, Dify và Agent Framework không khai báo mẫu nào, và mỗi importer đọc một tệp đã xuất hoặc một agent khai báo, trong khi importer MCP đọc các cấu hình client mà một thư mục chứa, importer Compose đọc các tệp Compose của thư mục, được hợp nhất theo cách Compose hợp nhất chúng, importer CrewAI đọc các khai báo của một dự án, không bao giờ đọc chương trình của nó, importer LangGraph đọc cấu hình của một ứng dụng, không bao giờ đọc mã hay tệp môi trường — tên trong tệp đó chỉ được đọc khi liên kết của importer trao tệp cho nó —, và importer Google ADK đọc cấu hình agent gốc của một ứng dụng, không bao giờ đọc mã hay tệp môi trường, còn cấu hình của các sub-agent được đọc khi liên kết của nó trao chúng — một cấu hình mà ADK nêu là thử nghiệm, có các agent mặc định dùng một mô hình Gemini và kết nối tới mô hình của các nhà cung cấp khác theo tên thông qua các lớp riêng của ADK, hoặc thông qua một chuỗi mô hình LiteLLM.
Phần lớn công việc với plugin là template, không phải mã biên dịch. Một phần lớn các tính năng chỉ chèn một sidecar tĩnh, một biến môi trường hoặc một label — một JSONPatch đơn giản không có logic điều kiện. Một plugin patcher có thể cấu hình, được viết một lần để nhận một template JSONPatch dạng khai báo làm đầu vào with, có thể bao quát trường hợp phổ biến đó mà không cần một tệp nhị phân biên dịch riêng cho mỗi tính năng: tác giả viết một template, và với nhiều đích kiểu CRD, chỉ riêng một template valuesMapping (thường tham chiếu các đoạn dùng chung trong một mục MappingLibrary) là đủ. Các plugin PDK viết riêng dành cho phần còn lại thực sự có điều kiện.
Tham khảo các công cụ đã thành danh. Khi viết logic plugin mới, tác giả có thể tham khảo các hình dạng đầu ra được ghi chép công khai của các công cụ mã nguồn mở đã thành danh — cấu trúc của các CRD, patch hoặc template mà các công cụ đó được biết là tạo ra — làm tham chiếu cho hình dạng đích mà một plugin mới phải tạo ra, đồng thời tôn trọng giấy phép của từng dự án. Các webhook chèn sidecar, thư viện construct cấp cao hơn, trình tạo CRD cho operator và danh mục trait hoặc composition đều công bố những cấu trúc đầu ra tương ứng sát với những gì một FeatureRecipe hoặc plugin tương đương cần tạo ra. Mục tiêu là khớp với một hợp đồng đầu ra được hiểu rõ, không phải sao chép phần triển khai của bất kỳ dự án nào.