Nhập
aggrega import đọc một dự án được viết ở định dạng khác — một luồng xuất từ Langflow, cấu hình của một máy khách MCP, một tệp Compose và các định dạng khác được liệt kê bên dưới — rồi ghi ra các tệp Aggrega từ đó: một Aggregate, một Release và, với đích mà --target chỉ định, một Manifest. Gộp lại, chúng tạo thành một không gian làm việc xác thực và dựng được đúng như khi được viết, sau khi một vài giá trị mà không nguồn nào có thể chứa được trả lời: quá trình nhập hỏi từng giá trị đó một lần và lưu câu trả lời trong một tệp câu trả lời. Lệnh này không triển khai gì cả và không truy cập bất kỳ cụm hay tài khoản đám mây nào. Các bản nháp là những tệp thông thường trong không gian làm việc của bạn, và việc xử lý chúng tiếp theo ra sao là tùy bạn.
- LangGraph
- CrewAI
- n8n
- Dify
- Langflow
- Flowise
- Google ADK
- Microsoft Agent Framework
- MCP client configurations
- Compose
aggrega importcác tệp Aggrega bản nháp
để bạn xem xét và chỉnh sửa
Dự án hiện có của bạn đi vào, các tệp Aggrega bản nháp đi ra. Không có gì được triển khai; bạn xem xét các bản nháp trước.
Bạn nhận được gì
- Dự án của bạn đến với Aggrega mà không phải viết lại bằng tay. Aggregate, Release và Manifest được soạn nháp là cùng loại tệp mà bạn tự viết. Chúng dựng được đúng như khi được viết cho đích mà quá trình nhập chỉ định, và mọi chính sách quản trị mà không gian làm việc của bạn gắn vào đều đánh giá bản dựng đó như mọi bản dựng khác.
- Những gì nguồn nêu ra được chuyển sang. Một nút hoặc dịch vụ mà danh mục có kết quả khớp mạnh sẽ tham chiếu đến Component đó của danh mục, với các giá trị mà nguồn gán cho nó, chẳng hạn mô hình mà một luồng chỉ định. Một nền tảng mà nguồn chạy trên đó được soạn nháp với image mà các Recipes của danh mục dành cho nền tảng đó chạy. Một bí mật được soạn nháp dưới dạng tham chiếu đến nơi nó xuất phát, không bao giờ dưới dạng giá trị của nó.
- Bạn chỉ được hỏi những gì không nguồn nào có thể chứa, một lần. Các câu trả lời được lưu trong một tệp câu trả lời bên cạnh nguồn, nên lần nhập tiếp theo của cùng nguồn đó không hỏi gì cả.
- Các bản nháp là của bạn. Chúng là YAML thông thường trong không gian làm việc của bạn, không để lại thứ gì mà bản dựng phụ thuộc vào. Hãy chỉnh sửa, đổi tên, commit chúng.
- Bản nháp có thể theo kịp nguồn của nó.
aggrega import --synccập nhật các bản nháp của một lần nhập trước đó theo nguồn đã thay đổi, chỉ thay đổi những gì quá trình nhập đã ghi. Khi nguồn thay đổi một phần bạn đã chỉnh sửa, lệnh sẽ dừng lại và nêu tên phần đó thay vì ghi đè lên chỉnh sửa của bạn.
Những gì nó không làm
Một lần nhập soạn nháp những gì nguồn nêu ra và những gì danh mục của bạn xác định, và hỏi phần còn lại. Mỗi bản nháp cho biết, trong một chú thích bên cạnh giá trị, giá trị mà nó soạn nháp đến từ đâu.
- Không đoán những gì nguồn của bạn không thể nêu ra. Không nguồn nào chỉ định môi trường mà một Release được triển khai đến, nên Release được soạn nháp chỉ định
development, kèm một chú thích cho biết đó là giá trị mặc định cần thay đổi. Một giá trị mà danh mục yêu cầu và không nguồn nào chứa — email của tài khoản chủ sở hữu, image của một ứng dụng được dựng từ mã của chính bạn, tên của một Secret Kubernetes — được soạn nháp ở dạng trống và được hỏi, như Cách một lần nhập chạy bên dưới mô tả. - Không đọc mã. Chương trình riêng của một luồng hay một dự án không được đọc: chương trình của một crew CrewAI, mã đồ thị của một ứng dụng LangGraph, mã nguồn của một thành phần Langflow ngoài việc mang nó bên trong luồng.
- Không phán xét ý nghĩa của một giá trị. Mỗi nút hoặc dịch vụ được so sánh với các Components trong danh mục của không gian làm việc của bạn — tên, phân loại, nhãn của chúng và tên các giá trị chúng khai báo. Một kết quả khớp ở bậc cao được tham chiếu trong bản nháp; một kết quả yếu hơn được ghi dưới dạng chú thích nêu tên Component và điểm số của nó, để bạn chọn.
- Không thay đổi phiên bản mà một nền tảng chạy để theo nguồn. Image của một nền tảng được soạn nháp ở phiên bản mà các Recipes của danh mục dành cho nền tảng đó được biết là chạy được, và khi nguồn chỉ định một phiên bản khác, một chú thích bên cạnh image sẽ nêu phiên bản đó.
- Không thay bạn chuyển thông tin xác thực ra khỏi nguồn. Một giá trị có thể mang khóa — một giá trị môi trường, một header, dòng lệnh của một máy chủ MCP — theo mặc định được mang vào bản nháp đúng như đã viết, và quá trình nhập nêu tên từng giá trị trong một cảnh báo
credential-carried, không bao giờ bằng giá trị của nó. Thiết lậpempty_credentialscủa trình nhập sẽ ghi chúng ở dạng rỗng thay vào đó (Thiết lập). Hãy đọc các cảnh báo trước khi chia sẻ một bản nháp. - Không triển khai hay chạy bất cứ thứ gì. Nó đọc nguồn và danh mục của bạn, rồi ghi tệp. Dựng các bản nháp, và chạy những gì bản dựng ghi ra, là những bước riêng do bạn thực hiện.
Cách một lần nhập diễn ra
Bạn có thể chạy một lần nhập bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn chạy giúp bạn.
-
Bắt đầu từ một không gian làm việc. Một lần nhập ghi các bản nháp vào bên dưới thư mục gốc của không gian làm việc nơi nó chạy — thư mục chứa một
.aggrega-config.yamlcó khóaworkspace— hoặc bên dưới thư mục mà--output-dirchỉ định. Nó không bao giờ ghi đè lên một Aggregate đã có ở đó. -
Danh mục dùng để so sánh. Quá trình nhập chấm điểm nguồn của bạn so với các Components trong danh mục của không gian làm việc, và không gì khác. Khi không gian làm việc không chỉ định thư mục danh mục riêng, đó là danh mục thư viện chuẩn, được đọc từ registry mặc định của không gian làm việc: mỗi lần phát hành danh mục đều phát hành một bản chụp nhanh đã ký của toàn bộ danh mục, và lần nhập đầu tiên tải bản chụp nhanh đó, xác minh chữ ký của nó, giữ nó trong bộ nhớ đệm nội dung của không gian làm việc và nêu nó bằng digest của nó trong bản ghi mà lần nhập ghi cạnh các bản nháp, nên một lần nhập sau của cùng các bản nháp đó đọc cùng danh mục mà không cần hỏi lại registry. So với danh mục đó, một dịch vụ PostgreSQL được khớp với
core/datastore/postgres, và--targetsoạn nháp một Manifest từ các Recipes của danh mục. Khi không có danh mục, quá trình nhập không có gì để khớp, và--targetbị từ chối, vì không có Recipe nào gắn với đích.Một không gian làm việc có chỉ định các thư mục danh mục riêng thì thay vào đó nhập so với các thư mục đó, và không tải bản chụp nhanh nào: các thư mục mà
workspace.catalog_dirsliệt kê, một thư mụccatalogở gốc không gian làm việc, hoặc các thư mục màAGGREGA_CATALOG_DIRSchỉ định. Các tệp riêng của danh mục thư viện chuẩn là thư mụcaggrega-catalogcủa kho lưu trữaggrega-hub, https://github.com/aggrega-ai/aggrega-hub, dành cho không gian làm việc muốn có chúng dưới dạng thư mục.--upgradetải bản chụp nhanh mới nhất mà registry phát hành và từ đó trở đi nhập so với nó; với--offline, một lần nhập lẽ ra phải tải một bản chụp nhanh sẽ dừng lại và nêu lệnh cần chạy. -
Chạy lệnh nhập. Chỉ định tệp hoặc thư mục:
Terminal window aggrega import compose.yaml --target composeĐịnh dạng được nhận diện từ tên và nội dung của tệp;
--formatchỉ định nó khi không nhận diện được.--targetchỉ định một năng lực của nhà cung cấp, chẳng hạncomposehoặchelm, và soạn nháp một Manifest ánh xạ mỗi kiểu thành phần và kiểu tính năng mà các bản nháp cần tới Recipe của năng lực đó mà danh mục của bạn cung cấp cho nó: cái duy nhất hiện có, hoặc, trong số nhiều cái, cái được đặt tên theo kiểu đó. Release được soạn nháp nêu tên Manifest đó, và nội dung các bản nháp mang theo phụ thuộc vào đích: trêncompose, một bí mật là một tham chiếu biến mà Docker Compose điền từ shell của bạn; trênhelm, đó là tên của một Kubernetes Secret. Trên luồng lỗi chuẩn, quá trình nhập nêu tên định dạng nó đã đọc, từng cảnh báo, và một dòng cho mỗi nút nó đã ánh xạ; trên đầu ra chuẩn, nó liệt kê các tệp đã ghi. -
Trả lời những gì không nguồn nào chứa. Một giá trị mà danh mục yêu cầu nhưng không nguồn nào có thể chứa — email của tài khoản chủ sở hữu, image của một ứng dụng được dựng từ mã của chính bạn, tên của một Kubernetes Secret — chỉ cần trả lời một lần. Quá trình nhập đọc câu trả lời từ
import-answers.yamlbên cạnh nguồn, hoặc từ tệp mà--answerschỉ định; tại một terminal, nó hỏi từng giá trị còn thiếu, mỗi lần một câu hỏi, và ghi câu trả lời của bạn vào tệp đó. Một bí mật được trả lời bằng nguồn gốc của nó — một biến hoặc tên của một Secret — không bao giờ bằng giá trị của nó. Ở nơi không thể hỏi gì — trong tích hợp liên tục, qua một pipe, từ trợ lý hoặc trình soạn thảo — quá trình nhập ghi tệp câu trả lời với khóa của từng giá trị còn thiếu và một câu trả lời trống, liệt kê chúng và thoát với trạng thái 1; hãy điền chúng và chạy lại quá trình nhập. Một tệp câu trả lời phục vụ mọi đích: một câu trả lời mà các bản nháp cho một đích không cần được giữ trong tệp và không được dùng. Tệp câu trả lời của quá trình nhập mô tả đầy đủ tệp này. -
Quá trình nhập kéo những gì bản dựng cần. Khi không còn thiếu gì, quá trình nhập kéo các phụ thuộc của Release đã soạn nháp, như
aggrega pulllàm, và ghirelease.lockbên cạnh nó. Với--offline, nó không kéo gì và nêu lệnhaggrega pullcần chạy. -
Xác thực và dựng. Trong thư mục chứa các bản nháp:
Terminal window aggrega validate --release release.yamlaggrega build --release release.yamlKhi cả hai đều thông qua, bản dựng đã ghi các tệp của đích vào
dist/. Một lời từ chối nêu rõ cần thay đổi gì và ở đâu, trong tài liệu mà bạn thay đổi. -
Chạy những gì bản dựng đã ghi ra. Một bản dựng cho Docker Compose ghi ra
dist/compose/docker-compose.yaml, và tệp này không đặt tên dự án Compose nào, vì vậy hãy đặt tên bằng-p:Terminal window docker compose -p <name> -f dist/compose/docker-compose.yaml up -dNếu không có
-p, Docker Compose đặt tên dự án theo thư mục chứa tệp,compose, nên hai không gian làm việc được khởi động theo cách đó sẽ dùng chung một dự án. Các dịch vụ nằm trên một mạng duy nhất, được Docker Compose đặt tên theo dự án,<name>_compose. Một dịch vụ mà bản build không công bố cổng nào được truy cập từ bên trong mạng đó, bằngdocker compose -p <name> -f dist/compose/docker-compose.yaml exec <service> …, hoặc từ một container mà bạn khởi động trên mạng đó bằngdocker run --network <name>_compose …. Các phần “Chạy thử” và “Kiểm thử” của một bài hướng dẫn từng bước trình bày các lệnh cho bản build của chính nó.Một lần chạy trả lời được mà không cần khóa OpenAI khi mô hình
core/ai-model/openaicủa nó trỏ tới một mô hình nhỏ do Ollama phục vụ trong cùng dự án, với ba thay đổi trong các tệp đã soạn nháp, một bản dựng với--auto-pull, cờ kéo những gì thành phần được thêm vào cần, và một lệnh sau khi stack chạy:- trong Aggregate, thêm một thành phần không nối với gì:
local-model, kiểucore/ai-model/ollama, vớimodel: qwen2.5:0.5btrongvaluescủa nó; - trong Manifest, Recipe Compose của nó:
core/ai-model/ollama: compose/ollama; - trong Release,
local-model: {}, vàendpointcủa mô hình OpenAI, dướiinfracủa nó, được đặt thành địa chỉ tương thích OpenAI của máy chủ đó,http://local-model:11434/v1; - sau khi stack chạy, mô hình đã kéo về được sao chép dưới tên mô hình mà mô hình OpenAI của bản build chỉ định,
<model>, chẳng hạngpt-4o-minihoặcgpt-4.1:docker compose -p <name> -f dist/compose/docker-compose.yaml exec local-model ollama cp qwen2.5:0.5b <model>.
Khi đó
OPENAI_API_KEYcó thể chứa bất kỳ giá trị không rỗng nào của riêng bạn: máy chủ cục bộ không kiểm tra giá trị nào. Một workflow n8n đọc địa chỉ và khóa của mô hình từ thông tin xác thực mà node mô hình của nó chọn, chứ không từ địa chỉ màendpointcung cấp, vì vậy hãy cấp cho thông tin xác thực đó cả địa chỉ của máy chủ, dưới dạng mộturlbên cạnhapiKeytrongdatacủa nó. Máy chủ Ollama màcore/ai-model/ollamachạy theo mặc định phục vụ Responses API của OpenAI cũng như Chat Completions, vì vậy một agent khai báo của Agent Framework có chỉ địnhapiType: Responseskết nối tới nó đúng như đã viết.Một bản build cho Kubernetes, tức target
helm, ghi ra các manifest thuần thay vì một chart, như nhà cung cấp helm mô tả: dướidist/helm/, hoặc, với các thành phần mà một Release đặt vào một boundary, dướidist/boundaries/<boundary>/helm/, một số nằm trong thư mục riêng bên dưới. Các tệp không chỉ định namespace, như các tệp của bản build MCP và Dify, sẽ đi vào namespace mà ngữ cảnhkubectlcủa bạn chỉ định, hoặc vàodefaultnếu ngữ cảnh không chỉ định namespace nào; hãy tạo trước ở đó các Secrets mà chúng đọc, rồi áp dụng thư mục:Terminal window kubectl apply -R -f dist/helm/-Rbao gồm cả các tệp trong những thư mục đó. Một ServiceClusterIP, loại mà các bản build MCP và Dify gán cho các máy chủ chúng chạy, chỉ có thể truy cập từ bên trong cluster: để truy cập một Service như vậy từ máy của bạn, hãy chuyển tiếp một cổng cục bộ tới nó bằngkubectl port-forward svc/<service> <local port>:<port>, lệnh này chạy cho đến khi bạn dừng nó. - trong Aggregate, thêm một thành phần không nối với gì:
Bên cạnh các bản nháp, quá trình nhập ghi .aggrega-import.json, bản ghi về những gì nó đã ghi. Hãy giữ tệp này chừng nào bạn còn định chạy aggrega import --sync, lệnh đọc nó để phân biệt chỉnh sửa của bạn với nội dung do chính quá trình nhập ghi. Hãy giữ cả tệp câu trả lời: nó không chứa bí mật nào, nên có thể nằm trong hệ thống quản lý phiên bản bên cạnh nguồn, và mọi lần nhập sau của nguồn đó đều đọc nó.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega có thể làm điều tương tự: dán prompt này vào nó.
Chỉ sử dụng các công cụ của Aggrega và không tự tạo thư mục nào. Gọi công cụ `import` với `source` được đặt thành `compose.yaml` và `target` được đặt thành `compose`: công cụ này ghi các bản nháp vào thư mục Workspace. Nếu nó cho biết vẫn còn thiếu giá trị, hãy cho tôi biết từng giá trị và đó là gì, rồi chờ trong khi tôi ghi câu trả lời bên cạnh các khóa tương ứng trong tệp câu trả lời mà nó chỉ ra; sau đó gọi lại công cụ `import` theo cùng cách. Tiếp theo, gọi công cụ `validate` với `release` được đặt thành `release.yaml`, và công cụ `build` với `release` được đặt thành `release.yaml` và `write` được đặt thành true. Cho tôi biết bản build đã ghi những tệp nào; chúng nằm dưới `dist/` trong thư mục Workspace.Mở trong VS Code
Khi đã cài đặt tiện ích mở rộng Aggrega cho Visual Studio Code, hãy mở trong VS Code không gian làm việc nơi lần nhập đã chạy — thư mục chứa .aggrega-config.yaml của nó: các bản nháp nằm trong đó, ở thư mục gốc hoặc trong thư mục mà --output-dir chỉ định. Khi không gian làm việc chứa một Release, trình soạn thảo sẽ chọn nó cho bạn; khi chứa nhiều hơn, Aggrega: Select Release… chọn Release mà trình soạn thảo làm việc. Trình soạn thảo kiểm tra các bản nháp theo Release đã chọn trong khi bạn chỉnh sửa, đánh dấu những gì nó tìm thấy trong tệp và trong bảng Problems. Aggrega: Show topology graph, trong Command Palette, vẽ các thành phần của Release đã chọn và các kết nối giữa chúng. Aggrega: Build, Aggrega: Preview build và Aggrega: Pull tác động lên cùng Release đó, và mỗi lệnh cũng là một nút trên bảng Commands của khung nhìn Aggrega trong thanh hoạt động; Build ghi các tệp của nó vào dist/ của không gian làm việc. Sử dụng Aggrega trong Visual Studio Code trình bày phần còn lại.
Các trình nhập đến từ đâu
Mỗi định dạng được đọc bởi một plugin trình nhập. Các trình nhập lõi của trình biên dịch, mỗi trình nhập cho một định dạng trong bảng bên dưới, được phát hành cùng mọi bản phát hành của trình biên dịch và phục vụ định dạng của chúng trong mọi không gian làm việc, mà không cần mục nào trong danh mục của bạn. Lần nhập đầu tiên cần đến một trình nhập sẽ tải nó từ registry mặc định của không gian làm việc, ở chính phiên bản của trình biên dịch, xác minh nó và lưu nó trong bộ nhớ đệm nội dung của không gian làm việc, nên mọi lần nhập sau đều đọc nó từ đó mà không cần truy cập mạng để lấy nó. Khi hoàn toàn không thể tải mô-đun — chẳng hạn khi không gian làm việc đang ngoại tuyến — quá trình nhập dừng lại và nêu hai cách để đưa nó vào máy. Trình nhập lõi mô tả đầy đủ từng trình nhập, cùng các thiết lập mà một trình nhập nhận được thông qua một mục plugins.importer.
Các định dạng
| Định dạng | Những gì nó đọc | Hướng dẫn từng bước |
|---|---|---|
| Compose | một tệp Compose và tệp ghi đè của nó, hoặc một thư mục chứa chúng | Nhập một dự án Compose |
| Cấu hình máy khách MCP | .mcp.json, claude_desktop_config.json, .vscode/mcp.json, .cursor/mcp.json, hoặc một server.json của registry MCP | Nhập cấu hình máy khách MCP |
| Langflow | một flow được xuất từ Langflow, dưới dạng JSON | Nhập một luồng Langflow |
| Flowise | một chatflow hoặc một agentflow được xuất từ Flowise, dưới dạng JSON | Nhập một chatflow Flowise |
| n8n | một workflow được xuất từ n8n, dưới dạng JSON | Nhập một workflow n8n |
| Dify | một ứng dụng được xuất từ Dify theo DSL của nó, dưới dạng YAML | Nhập một ứng dụng Dify |
| CrewAI | các khai báo agent và tác vụ của một dự án CrewAI | Nhập một dự án CrewAI |
| LangGraph | langgraph.json của một ứng dụng LangGraph | Nhập một ứng dụng LangGraph |
| Google ADK | các tệp Agent Config của một ứng dụng xây dựng trên Google ADK, bắt đầu từ root_agent.yaml | Nhập một agent Google ADK |
| Microsoft Agent Framework | một agent khai báo, một tài liệu YAML thuộc loại Prompt | Nhập một agent khai báo của Microsoft Agent Framework |
aggrega import là tài liệu tham khảo đầy đủ của lệnh: mọi cờ, cách một nguồn được nhận diện, những gì --sync thay đổi và những gì nó từ chối. Tệp câu trả lời của quá trình nhập mô tả tệp câu trả lời: nó nằm ở đâu, chứa gì và cách trả lời cho một bí mật.