Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Viết tệp Aggrega

Soạn thảo trong Aggrega là một vòng lặp ngắn và có thể lặp lại. Dù bạn đang viết thực thể nào — Aggregate của nhà phát triển, Component của kiến trúc sư, Recipe của bộ phận vận hành hay Release của người vận hành — năm bước giống nhau sẽ đưa bạn từ một tệp trống đến một tệp đã được kiểm tra hợp lệ:

  1. Chọn thực thể mà vai trò của bạn phụ trách.
  2. Tìm hiểu cấu trúc của nó từ JSON Schema và trang tham chiếu.
  3. Bắt đầu từ một bộ khung thay vì một tệp trống.
  4. Điền các trường mà vai trò của bạn phụ trách, để phần còn lại cho những người phụ trách chúng.
  5. Kiểm tra hợp lệ, rồi biên dịch.

Trang này đi qua vòng lặp một lần, cho cả người soạn thảo thủ công lẫn trợ lý AI soạn thảo thông qua máy chủ Model Context Protocol. Hai con đường là cùng một vòng lặp trên cùng các nguồn tham chiếu. Cả hai đều cần tệp nhị phân aggrega: Cài đặt tệp nhị phân cài đặt nó bằng một lệnh.

1. Chọn thực thể mà vai trò của bạn phụ trách

Aggrega tách việc soạn thảo thành bốn vai trò cộng tác — ý định của nhà phát triển, danh mục nền tảng, công thức hạ tầng và việc nối dây triển khai. Mỗi vai trò thường phụ trách một tập loại thực thể cụ thể. Nếu bạn đã biết vai trò của mình, hãy chuyển thẳng đến thực thể bạn cần; nếu chưa, hãy đọc Personas để biết bốn vai trò và Thực thể theo vai trò để xem bản đồ đầy đủ từ loại đến vai trò.

Sự phân tách này là hướng dẫn, không phải quy tắc do trình biên dịch áp đặt. Một tác giả làm việc một mình có thể tự do đảm nhận mọi vai trò và viết tất cả các thực thể trong một lần; trình biên dịch chấp nhận bất kỳ cách soạn thảo nào vượt qua kiểm tra hợp lệ theo schema. Các vai trò tồn tại để giữ cho trách nhiệm rõ ràng, không phải để giới hạn những gì bạn được phép viết.

2. Tìm hiểu cấu trúc của nó

Mỗi loại thực thể có một JSON Schema chuẩn và một trang tham chiếu mô tả từng trường. Hãy đọc cả hai trước khi viết:

  • Schema là cấu trúc chính xác: các trường bắt buộc, các giá trị được phép và cách lồng nhau. Từ dòng lệnh, aggrega get-schema <kind> in ra schema; aggrega get-schema --list liệt kê mọi loại bạn có thể yêu cầu. Trợ lý đọc cùng các byte đó từ tài nguyên schema://<kind>. Xem tài liệu tham chiếu aggrega get-schema.
  • Trang tham chiếu giải thích mỗi trường có nghĩa là gì và các trường liên quan với nhau như thế nào. Các trang thực thể nằm trong language-reference/entities/ — ví dụ component hoặc aggregate. Trợ lý đọc cùng trang đó từ tài nguyên langref://entities/<kind>.

Schema cho bạn biết điều gì hợp lệ về mặt cấu trúc; tài liệu tham chiếu cho bạn biết điều gì là hợp lý. Hãy đọc schema để tránh bị từ chối khi kiểm tra hợp lệ, và đọc tài liệu tham chiếu để soạn ra thứ làm đúng điều bạn muốn.

3. Bắt đầu từ một bộ khung

Bắt đầu từ một bộ khung nhanh hơn và ít lỗi hơn so với một tệp trống. Trợ lý kết nối với máy chủ MCP gọi công cụ scaffold với một loại và một tên để nhận một điểm khởi đầu tối thiểu chứa mọi trường mà loại đó yêu cầu, với một chỗ giữ chỗ ở bất cứ nơi nào giá trị vẫn còn thiếu. Khi soạn thảo thủ công, aggrega scaffold <kind> <name> in cùng điểm khởi đầu đó ra đầu ra chuẩn, nên hãy chuyển hướng nó vào một tệp; hoặc sao chép ví dụ hoàn chỉnh gần nhất và rút gọn nó còn những gì bạn cần.

Dù bằng cách nào, bộ khung cũng đã chứa sẵn các trường cấp cao nhất bắt buộc (apiVersion, kind, metadata.name) ở đúng dạng, nên bạn dành sự chú ý cho các trường mà vai trò của bạn phụ trách thay vì cho mã mẫu lặp lại.

4. Điền các trường mà vai trò của bạn phụ trách

Chỉ điền các trụ cột mà vai trò của bạn chịu trách nhiệm, và để các trụ cột khác cho những người phụ trách chúng. Nhà phát triển cung cấp ý định ứng dụng và các giá trị; kiến trúc sư khai báo hợp đồng — các giá trị nhà phát triển có thể cung cấp, các đầu ra mà một thành phần cung cấp, các socket mà nó để lộ; bộ phận vận hành ánh xạ hợp đồng đó lên một provider cụ thể mà không thay đổi bề mặt hướng tới nhà phát triển; người vận hành nối dây việc triển khai. Thực thể theo vai trò chỉ rõ trụ cột nào thuộc vai trò nào cho mọi loại.

Giữ mỗi giá trị trong trụ cột do người phụ trách nó kiểm soát là điều cho phép cùng một ý định của nhà phát triển nhắm tới các hạ tầng khác nhau ở các môi trường khác nhau mà tệp của nhà phát triển không thay đổi. Đó chính là lý do bề mặt soạn thảo được chia tách.

Giữ phần mô tả trong vài đoạn ngắn. metadata.description của một thực thể là đoạn văn người đọc gặp trước khi chọn nó: nó được công bố cùng thực thể như phần mô tả có thể tìm kiếm, và aggrega search đối chiếu truy vấn với nó. Hãy viết nó cho khoảnh khắc đó, thành các đoạn ngắn — trong một khối gập description: >, một dòng trống bắt đầu đoạn mới — nói rõ thực thể là gì, người đọc dùng nó như thế nào, nó được hiện thực hóa ở đâu và nó không làm gì. Một giới hạn mà người đọc phải biết trước khi chọn thực thể cũng thuộc về đó, được nêu ngắn gọn. Mọi thứ khác — vì sao một giá trị mặc định lại như vậy, một thiết lập hoạt động thế nào trên một đích, một giá trị có nghĩa gì trong mỗi cách hiện thực hóa — được đặt trong chú thích YAML bên cạnh trường hoặc khối mà nó giải thích, nơi người làm việc với trường đó sẽ đọc. Không có gì trong trình biên dịch giới hạn độ dài của phần mô tả hay hành động dựa trên nội dung của nó, nên việc giữ nó ngắn gọn là vì người đọc.

5. Kiểm tra hợp lệ, rồi biên dịch

Hãy kiểm tra tệp trước khi dựa vào nó:

  • Trợ lý gọi công cụ validate, công cụ này báo cáo trực tiếp các lỗi schema và lỗi tham chiếu để trợ lý có thể sửa bản nháp trước khi trả lại.
  • Khi làm thủ công, aggrega validate <file> kiểm tra một tệp Component, Feature, Recipe, FeatureRecipe, Workload hoặc Plugin, và aggrega validate --release <release> kiểm tra mọi thứ mà một Release chạm tới, bao gồm cả Aggregate và Manifest của nó. aggrega lint chạy các quy tắc về kỷ luật xuất bản trên một thực thể danh mục, và aggrega inspect phân giải và hiển thị những gì trình biên dịch thấy. Khi toàn bộ topology đã sẵn sàng, aggrega pull --release <release> phân giải các phụ thuộc của nó và ghi lockfile, rồi aggrega build --release <release> biên dịch Release thành các tạo phẩm theo từng ranh giới — một bản build thất bại sẽ nêu chính xác điều cần sửa.

Kiểm tra hợp lệ sớm rẻ hơn một bản build thất bại muộn. Soạn thảo, kiểm tra hợp lệ, sửa, và chỉ sau đó mới biên dịch.

Soạn thảo với trợ lý AI

Lệnh aggrega mcp chạy một máy chủ Model Context Protocol, biến bất kỳ client nào hỗ trợ MCP thành một trợ lý soạn thảo hiểu Aggrega. Sau khi kết nối, trợ lý có thể:

  • Đảm nhận một vai trò thông qua các prompt soạn thảo tích hợp sẵn — mỗi persona một prompt (nhà phát triển, kiến trúc sư, vận hành) cùng một mẫu chuyên biệt cho từng thực thể. Mỗi prompt định khung vai trò và hướng trợ lý tới schema, trang tham chiếu và hướng dẫn này, để các gợi ý của nó nằm trong các trụ cột mà vai trò đó phụ trách.
  • Đọc tài liệu tham chiếu thông qua các tài nguyên: schema://<kind> cho JSON Schema của một loại, langref://<path> cho bất kỳ trang tham chiếu nào, và authoring://<topic> cho hướng dẫn này.
  • Thao tác trên workspace của bạn thông qua các công cụ: scaffold để khởi tạo một bộ khung đúng, validate để kiểm tra một bản nháp, describe để xem xét một thực thể danh mục, và get-schema để lấy schema theo loại.

Mọi thứ trợ lý đọc đều được phục vụ từ máy của bạn: các schema được tích hợp trong tệp nhị phân, còn các trang hướng dẫn và tham chiếu đến từ gói tài liệu được lưu trong bộ nhớ đệm của máy bạn, mà máy chủ tải về từ registry khi khởi động và không tìm thấy bản sao nào ở đó. Đọc một trang, tạo khung và kiểm tra hợp lệ đều không truy cập mạng; khi không tải được gói, các schema vẫn được phục vụ còn các trang thì không. Để kết nối một client, hãy làm theo Kết nối máy chủ MCP; Những gì trợ lý của bạn có thể làm với Aggrega trình bày phần còn lại của những gì trợ lý truy cập được. Về chính lệnh này, xem tài liệu tham chiếu aggrega mcp.

Tiếp theo nên đọc gì