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.

Trình soạn thảo, trợ lý và các frontend khác

Aggrega được dùng từ nhiều nơi: terminal, tiện ích mở rộng Visual Studio Code, trợ lý AI được kết nối qua Model Context Protocol (MCP), và bất kỳ chương trình nào điều khiển tệp nhị phân aggrega. Không frontend nào trong số này mang theo trình biên dịch riêng. Mỗi frontend chạy tệp nhị phân aggrega, hoặc kết nối tới một tệp nhị phân đang chạy, và gửi yêu cầu tới nó, nên việc phân tích YAML, phân giải danh mục và xây dựng đồ thị diễn ra ở một nơi, và những gì frontend hiển thị chính là những gì tệp nhị phân đó đã biên dịch. Frontend không triển khai lại bất kỳ phần nào trong số đó, nên không có bản sao thứ hai để lệch khỏi bản đầu tiên.

Chương này mô tả hợp đồng mà các frontend đó dùng chung, và những gì mỗi frontend yêu cầu từ tệp nhị phân.

Đồ thị IR là hợp đồng công khai

Biên dịch một Release, cùng với Aggregate và Manifest mà nó chỉ định, tạo ra một đồ thị biểu diễn trung gian (IR): mọi node, cùng với thành phần mà nó khởi tạo, phiên bản mà thành phần đó được phân giải thành, ranh giới và hệ thống con nơi nó nằm, và tệp đã khai báo nó; mọi kết nối giữa các node; các Features được gắn vào từng node; và các giá trị được ánh xạ lên chúng, kèm theo nguồn gốc của từng giá trị. Đây là ảnh chụp những gì trình biên dịch sắp render thành các artifact.

Hình dạng của đồ thị được công bố dưới dạng một JSON Schema, https://aggrega.ai/schemas/ir-v1beta1.schema.json, và tài liệu tham khảo schema IR mô tả mọi trường. Frontend đọc đồ thị theo schema đó, chứ không theo cấu trúc nội bộ của trình biên dịch, nên schema là nơi duy nhất hình dạng thay đổi, và một frontend viết bằng bất kỳ ngôn ngữ nào cũng theo dõi nó theo cùng một cách.

Các giá trị mà tác giả khai báo là nhạy cảm sẽ bị ẩn khỏi đồ thị ở bất cứ nơi nào đồ thị được trao đi. Frontend cần chúng ở dạng rõ thì yêu cầu chúng một cách tường minh, và bất cứ thứ gì câu trả lời sau đó đi tới đều mang chúng ở dạng rõ.

Ba cách yêu cầu đồ thị

Cùng một đồ thị có sẵn trên mọi bề mặt, và mỗi câu trả lời là một tài liệu đồ thị hoàn chỉnh:

  • Từ dòng lệnh. aggrega build, aggrega inspect khi được cung cấp một Release, và aggrega validate --release đều chấp nhận --ir-graph, cờ này ghi đồ thị mà lần chạy đó đã tính ra vào đầu ra chuẩn dưới dạng JSON, bên cạnh mọi thứ lệnh vốn đã tạo ra. --unredacted đi kèm sẽ in ra các giá trị nhạy cảm. Xem aggrega inspect.
  • Từ daemon. Một yêu cầu aggrega/irGraph gửi tới aggrega serve, chỉ định Release bằng đường dẫn tương đối so với thư mục gốc của workspace, được trả lời bằng cùng tài liệu đó dưới graph; unredacted: true yêu cầu các giá trị nhạy cảm. Xem aggrega serve.
  • Từ trợ lý AI. Các công cụ cli-inspect, cli-build và cli-validate của máy chủ MCP nhận cờ của lệnh làm đối số ir_graph. Xem aggrega mcp.

Mỗi câu trả lời mô tả Release ở trạng thái tại thời điểm câu hỏi được đặt ra. Frontend theo dõi các chỉnh sửa sẽ hỏi lại: tiện ích mở rộng Visual Studio Code vẽ lại đồ thị mỗi khi một tài liệu được lưu.

Tiện ích mở rộng Visual Studio Code

Tiện ích mở rộng Aggrega cho Visual Studio Code khởi động aggrega serve và giữ nó chạy cho workspace. Mọi câu trả lời mà tiện ích hiển thị đều đến từ tệp nhị phân aggrega: phần lớn từ daemon đó — trong đó có chẩn đoán khi bạn chỉnh sửa, hover, tự động hoàn thành, đi tới định nghĩa, tìm tham chiếu, build và xem trước build — và phần còn lại từ việc chạy các lệnh riêng của tệp nhị phân.

Đồ thị cấu trúc liên kết của tiện ích chính là đồ thị IR. Tiện ích gửi aggrega/irGraph cho Release được chọn và vẽ câu trả lời: ranh giới và hệ thống con dưới dạng các container lồng nhau, thành phần dưới dạng node, kết nối dưới dạng cạnh, và, trên một node hoặc kết nối được chọn, các Features được gắn vào nó. Trình biên dịch gửi cấu trúc liên kết và không bao giờ gửi tọa độ; bố cục được tính trong trình soạn thảo. Việc gắn một Feature từ đồ thị cũng đi ngược qua daemon: trình biên dịch chỉ ra tài liệu và vị trí bên trong nó nơi phần gắn thuộc về, và tiện ích ghi nó vào đó. Xem đồ thị cấu trúc liên kết để biết chế độ xem hiển thị và làm gì.

Máy chủ MCP

aggrega mcp chạy tệp nhị phân như một máy chủ Model Context Protocol, nên trợ lý AI khám phá các thao tác của Aggrega và gọi chúng thay vì đọc đầu ra của lệnh. Qua đầu vào và đầu ra chuẩn, nó giao tiếp bằng JSON-RPC 2.0 phân tách bằng ký tự xuống dòng, đó là cách một client khởi động nó như một tiến trình con tiếp cận nó; qua HTTP, nó phục vụ một endpoint, /mcp, cho các bên gọi trên máy khác. Các công cụ của nó là các thao tác của trình biên dịch — đọc schema, mô tả workspace, xác thực, build, soạn nháp và chỉnh sửa tài liệu — và mỗi lời gọi được trả lời bởi chính tệp nhị phân mà dòng lệnh chạy.

Kết nối máy chủ MCP trình bày cách kết nối từng client, và Trợ lý của bạn có thể làm gì với Aggrega trình bày những gì các công cụ cung cấp.

Daemon aggrega serve

aggrega serve chạy trình biên dịch như một tiến trình chạy dài hạn cho các trình soạn thảo. Nó giữ các tài liệu đã phân tích, danh mục đã phân giải và các chẩn đoán qua các yêu cầu, nên trình soạn thảo có thể hỏi nhiều câu hỏi nhỏ mà không phải trả chi phí tải toàn bộ danh mục mỗi lần.

Giao thức là JSON-RPC 2.0 qua đầu vào và đầu ra chuẩn, mỗi thông điệp được đặt trước bởi một header Content-Length, với các phương thức nằm trong namespace aggrega/. Đây không phải là Language Server Protocol, vì nó mang các thao tác mà giao thức đó không có chỗ cho, chẳng hạn như yêu cầu đồ thị IR; một tiện ích mở rộng trình soạn thảo chuyển đổi giữa các yêu cầu của trình soạn thảo và các phương thức này, đồng thời tái sử dụng các dạng vị trí, phạm vi và địa điểm của giao thức đó khi phù hợp. Một phiên mở bằng aggrega/initialize, phương thức này báo cáo workspace và phiên bản của tệp nhị phân đang trả lời; daemon đẩy chẩn đoán bằng aggrega/publishDiagnostics; và thông báo aggrega/shutdown kết thúc phiên một cách gọn gàng.

Mọi phần thân thông điệp được công bố dưới dạng một schema, https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json, được mô tả trong tài liệu tham khảo định dạng wire; tiện ích mở rộng Visual Studio Code lấy các kiểu thông điệp từ đó. Một trình soạn thảo khác tích hợp bằng cách dùng cùng giao thức. Tài liệu tham khảo aggrega serve mô tả từng phương thức, những gì nó đọc và ghi, và các lỗi nó phát sinh.