Phân giải phụ thuộc
Phân giải phụ thuộc của Aggrega & trụ cột tô-pô cấu trúc
Trong kiến trúc Aggrega, các phụ thuộc tô-pô được ánh xạ tường minh qua trụ cột lược đồ uses để giữ một payload values hoàn toàn mờ. Việc phân giải “ai nói chuyện với ai” đặt ra một thách thức cụ thể: các tô-pô ứng dụng phức tạp, nhiều nút phải được ánh xạ mà không buộc nhà phát triển viết định tuyến mạng tường minh, thứ tự thực thi cấp bộ điều phối hay các phụ thuộc hạ tầng.
1. Triết lý cốt lõi: Tại sao là uses?
Khối uses khai báo các phụ thuộc giữa các thành phần dưới dạng tô-pô thuần túy: Component A phụ thuộc vào hợp đồng công khai provides của Component B, không phải vào địa chỉ vật lý hay chi tiết kết nối của Component B. Tô-pô nằm trong uses; cấu hình nằm trong values. Sự tách biệt này cho phép trình biên dịch thấy tường minh mọi cạnh giữa các thành phần mà không phải suy ra chúng từ nội dung values.
Aggrega giải quyết điều này bằng cách nâng tô-pô thành một trụ cột lược đồ hạng nhất có tên uses.
- Lập luận proxy ngữ nghĩa: Từ khóa
usesbiểu thị ý định ngữ nghĩa L7. Nếu một tác tửusesmột cơ sở dữ liệu, điều đó vẫn đúng về mặt ngữ nghĩa ngay cả khi Platform Ops chèn các lưới proxy Wasm trong suốt vào giữa chúng. - Tính trung lập toán học: Trình biên dịch Go phân tích trực tiếp struct
usesđể vẽ đồ thị biểu diễn trung gian (IR). Nó không bao giờ cố phân tích hay truy vấn logic ứng dụng của nhà phát triển (values). - Tính nguyên tử của Feature: Trụ cột
usesáp dụng giống hệt cho Components và Features (bao gồm cả Features thông tin xác thực). Điều này cho phép một proxy sidecar (một Feature) hoặc một trình lấy thông tin xác thực tự khai báo các phụ thuộc mạng của riêng nó mà không làm rối cấu hình của Component cha.
2. Cơ chế của hợp đồng lược đồ thống nhất
Để trích xuất chỉ dẫn vận hành mà không phân tích payload ứng dụng, hệ thống dựa vào các khai báo JSON Schema 2020-12 nghiêm ngặt chi phối các cấu trúc YAML được tách biệt tường minh.
Miền 2: Lược đồ tách đôi (usesSchema & schema) Để ngăn danh mục nền tảng bị phân mảnh thành các tệp lược đồ không thể quản lý, Aggrega sử dụng một công cụ lược đồ tách đôi. usesSchema YAML gốc định nghĩa và xác thực nghiêm ngặt tô-pô, trong khi schema: (JSON Schema 2020-12 — thường được viết qua dạng viết tắt gọn) xác thực nội dung của các trụ cột values và infra và khai báo hình dạng của trụ cột provides. values mà nhà phát triển viết và infra mà người vận hành đặt được kiểm tra theo các kiểu đã khai báo; lược đồ con provides khai báo tên khóa và kiểu của hợp đồng hạ nguồn mà một Recipe tạo ra, và trình biên dịch kiểm tra rằng mọi tham chiếu inject đều nêu tên một khóa provides đã khai báo — nhưng bản thân các giá trị provides được tạo ra đi xuống hạ nguồn dưới dạng chuỗi mờ mà trình biên dịch truyền đi không diễn giải, chứ không phải các giá trị mà nó kiểm tra kiểu, vì phần lõi không diễn giải ý nghĩa của một giá trị được truyền. usesSchema là nơi một socket được khai báo, và chính việc khai báo mới cho nó một hợp đồng. Một socket do thực thể danh mục khai báo mang các ràng buộc của thực thể đó: một bộ chọn cho biết nó có thể tới những đích nào, một danh sách cho phép inject, và valueSchema / infraSchema theo từng cạnh. Bên trong usesSchema, các kiến trúc sư nền tảng dùng trường selector: — được đọc như chuỗi mà kiến trúc sư đã viết, không được sao chép vào bất kỳ lược đồ được tạo nào — và công cụ bộ chọn Go gốc đánh giá nó để thực thi an toàn kiểu giữa các nút trên các socket đã khai báo. Nó bảo đảm rằng nếu một socket yêu cầu cơ sở dữ liệu, nhà phát triển không thể cắm vào một máy chủ web.
Bộ chọn bị ràng buộc bởi ngữ pháp của nó vào thời điểm được đánh giá, tức là một lần cho mỗi cạnh được nối qua socket. Một bộ chọn mà công cụ không thể đọc thành một trong sáu dạng yêu cầu của nó — một yêu cầu rỗng do dấu phẩy thừa để lại, một khóa chứa khoảng trắng hoặc một trong các ký tự mà ngữ pháp dùng để phân biệt các dạng của nó (=, !, (, ) và dấu phẩy), hoặc một tập hợp thiếu dấu ngoặc đóng — sẽ dừng bản dựng trên cạnh đó, nêu tên yêu cầu, thay vì bị đọc thành một bộ chọn khác. Chính sự nghiêm ngặt này giữ cho việc kiểm tra trung thực: nếu đọc một cách dễ dãi, !tier=frontend, vốn được viết để loại trừ frontend, sẽ chỉ yêu cầu không có nhãn nào được đặt tên tier=frontend, và mọi đích — kể cả frontend — đều sẽ lọt qua. Cùng một ngữ pháp chi phối các bộ chọn khe đính kèm và appliesTo của một Feature; ngữ pháp bộ chọn liệt kê mọi dạng và mọi trường hợp từ chối. Một bản dựng không bao giờ đánh giá một socket không có cạnh nào được nối qua, vì vậy aggrega validate — trên toàn bộ danh mục, hoặc trên Component hay Feature khai báo socket đó — đọc bộ chọn của mọi socket đã khai báo và từ chối ngay tại đó một bộ chọn sai dạng, với cùng mã và cùng lời lẽ mà một bản dựng nối socket đó sử dụng.
Tuy nhiên, khai báo socket không phải là cách duy nhất để vẽ một cạnh. Tác giả của một Aggregate có thể nêu tên trên chính thành phần của mình một socket mà thực thể danh mục không khai báo — kể cả trên một loại thành phần hoàn toàn không khai báo usesSchema — và cạnh vẫn được dựng. Một danh mục không khai báo mục nào cho một socket là chưa lường trước kết nối đó, điều này không giống với việc cấm nó, và tô-pô của ứng dụng thuộc về nhà phát triển. Một socket như vậy được gọi là ad hoc, và cái giá của nó chính xác là những gì việc khai báo mang lại: không có mục danh mục, nên không có bộ chọn và không có hợp đồng theo cạnh, và an toàn kiểu giữa các nút không có gì để đánh giá. Những gì cạnh được phép mang không thay đổi — mọi khóa mà nó tiêm vào vẫn phải nêu tên một khóa mà provides của đích khai báo, và đích vẫn phải tồn tại. Mỗi cạnh trong đồ thị được xuất ra ghi lại nó thuộc trường hợp nào trong hai trường hợp, để bên tiêu thụ không bao giờ phải đoán; xem governance-and-compliance để biết cách người vận hành cấm hẳn các socket ad hoc.
Hai bề mặt được cố ý không mở theo cách này, vì chúng không viết tô-pô của ứng dụng. uses của một phần đính kèm Feature chỉ được nêu tên một socket mà Feature được đính kèm khai báo, và uses theo cạnh của một Release chỉ được nêu tên một socket mà thực thể danh mục của thành phần tiêu thụ khai báo trong usesSchema của nó, không bao giờ là một socket mà Aggregate viết ad hoc — người vận hành cấu hình và nối dây bên trong một kiến trúc, còn một Feature tham gia vào tô-pô mà chính thực thể danh mục của nó khai báo. Khai báo socket trong danh mục cũng vẫn là con đường tốt hơn và là điều mà danh mục thư viện chuẩn làm: một socket ad hoc là một lối thoát, không phải một mặc định mới.
Miền 1: Trải nghiệm nhà phát triển (đa hình) Nhà phát triển viết uses: ngang hàng với values: và features:. Để bảo đảm UX không ma sát, lược đồ hỗ trợ đa hình một cách tự nhiên:
- Mảng chuỗi: Dùng cho các tham chiếu thành phần logic đơn giản (ví dụ:
tools: ["search-api"]) khi định tuyến chuẩn là đủ. - Map đối tượng: Dùng khi cần các hợp đồng phân phối nghiêm ngặt (ví dụ:
databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }). - Không có ký tự đại diện: Không có dạng ký tự đại diện, điều này ngăn “phụ thuộc ma” và việc tự động đấu nối trái phép: mỗi mục nêu tên một thành phần, nên
["*"]dừng bản dựng như một đích không tồn tại — không tên thành phần nào có thể chứa*.
Miền 3: Thực tế của Ops (chuẩn hóa) Để giữ các template Go dễ đoán, trình biên dịch Go chuẩn hóa các đầu vào uses đa hình. Các mảng tham chiếu thành phần logic được chuyển thành đối tượng chuẩn trước khi được truyền vào từ điển phẳng, nghiêm ngặt được gọi là .context.uses.
3. Ví dụ từ đầu đến cuối
Hai ví dụ sau minh họa hai thuộc tính riêng biệt của trụ cột tô-pô tường minh: Ví dụ A chứng minh liệu một kết nối có được cấp phép hay không (an toàn kiểu giữa các nút), và Ví dụ B chứng minh dữ liệu kết nối được phân phối vật lý như thế nào (đa hình & chuẩn hóa).
Ví dụ A: Xác thực topo và an toàn kiểu giữa các nút
Kịch bản này lần theo cách bộ chọn trên một socket đã khai báo phát hiện rằng một tác tử AI sắp kết nối tới một cơ sở dữ liệu thiếu các nhãn tuân thủ bắt buộc, và dừng bản build. Trình biên dịch đánh giá bộ chọn nhãn mà kiến trúc sư đã viết dựa trên các nhãn của đích, dưới dạng chuỗi; nó không diễn giải ý nghĩa của một nhãn, và không có plugin chính sách nào tham gia.
1. Thư viện chuẩn (schema: hợp nhất trong danh mục) Platform Architect định nghĩa cấu trúc schema, tách logic nhận thức khỏi các đích topo một cách tự nhiên.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/enterprise-agent version: 1.0.0 labels: component.aggrega.ai/type: "worker"spec: usesSchema: datastores: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
schema: # 1. The Cognitive Intent values: system_prompt: { type: string, required: true }2. Ý định của nhà phát triển (Aggregate) Nhà phát triển tách bạch rõ ràng điều tác tử làm (values) với thứ tác tử kết nối tới (uses).
components: my_secure_vector_db: type: core/qdrant-secure:1.0.0 values: collection_name: finance_data
auditing_agent: type: core/enterprise-agent:1.0.0 values: system_prompt: "You are a financial auditing AI..." uses: datastores: finance_memory: { target: "my_secure_vector_db" }3. Thực thi của trình biên dịch và xác thực topo
- Xác thực cục bộ: Trình biên dịch Go đánh giá toàn bộ đối tượng theo JSON Schema đã được phân giải tại bước phân giải. Nó kiểm tra các nhãn danh mục bên dưới của
my_secure_vector_db. Nếu cơ sở dữ liệu thiếu nhãnrestricted, trình biên dịch sẽ dừng bản build ngay lập tức với một vi phạm an toàn kiểu. - Vẽ đồ thị: Khi xây dựng topo, trình biên dịch Go hoàn toàn bỏ qua nội dung đã được schema xác thực. Nó đọc
uses.datastores.finance_memory.targettrực tiếp từ YAML và vẽ cạnh tường minh trong đồ thị IR.
Ví dụ B: Đa hình và .context.uses đã chuẩn hóa
Kịch bản này minh họa cách trình biên dịch xử lý cả một công cụ AI hộp đen (được truyền dưới dạng mảng) lẫn một cơ sở dữ liệu quan hệ cũ (cần một map có hợp đồng inject).
1. Danh mục (miền 2): khai báo schema: Architect cho phép mảng đa hình cho các công cụ, nhưng yêu cầu đối tượng chặt chẽ cho các cơ sở dữ liệu.
spec: usesSchema: # Polymorphic Array Socket (No injection needed) tools: selector: "tool.aggrega.ai/impact=read-only"
# Strict Map Socket (Requires delivery contract) databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file"]
schema: values: system_prompt: { type: string, required: true }2. Ý định của nhà phát triển (miền 1): Aggregate Nhà phát triển dùng một mảng gọn gàng cho công cụ và một map tường minh cho cơ sở dữ liệu.
components: my-agent: type: core/python-worker:1.0.0 values: system_prompt: "You are an HR bot."
uses: # 1. Polymorphic Array: Simple logical component reference tools: - "corporate-search-api"
# 2. Strict Map: Dictating the environment variable delivery databases: hr_db: target: corporate-hr-db inject: env: - in: HR_DATABASE_URI # Local env var from: "host" # Target provides key3. Thực tế của Ops (miền 3): Recipe Trình biên dịch Go chuẩn hóa tính đa hình. Ops nhận được một từ điển .context.uses phẳng và có thể dự đoán. Họ chỉ cần lặp qua đường ống .context.inject trong các phần liên quan của template.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: generic-worker version: 1.0.0spec: capability: helm implements: core/python-worker:1.0.0 source: "./charts/internal/python-runner"
locals: primary_compute: worker-container
valuesMapping: | env: # Ops uses the pre-resolved inject map, kept apart from values and topology loops {{- range $key, $value := .context.inject.env }} - name: {{ $key }} value: "{{ $value }}" {{- end }}