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.

aggrega serve

aggrega serve chạy Aggrega dưới dạng một daemon trình biên dịch như một dịch vụ hoạt động lâu dài, phục vụ việc tích hợp với IDE. Daemon giao tiếp bằng JSON-RPC 2.0 qua stdin/stdout và giữ trạng thái của bộ phân giải catalog, bộ nhớ đệm phân tích cú pháp và chẩn đoán xuyên suốt các yêu cầu, nhờ đó các thao tác trong trình soạn thảo nhận được phản hồi dưới một giây thay vì phải chịu toàn bộ chi phí nạp catalog ở mỗi lần gõ phím.

Daemon thường được một tiện ích mở rộng của trình soạn thảo khởi chạy như một tiến trình con, chứ không được chạy thủ công. Một tiện ích mở rộng VS Code là client tham chiếu; các trình soạn thảo khác có thể tích hợp bằng cách dùng cùng giao thức này.

Giao thức

Giao thức truyền là JSON-RPC 2.0 với khung Content-Length, thuộc không gian tên phương thức aggrega/. Nó cố ý không phải là Language Server Protocol — Aggrega có các thao tác miền (truy vấn đồ thị IR, tín hiệu vô hiệu hóa bộ nhớ đệm) mà LSP không có gì tương đương. Một tiện ích mở rộng của trình soạn thảo chuyển đổi giữa các yêu cầu LSP của trình soạn thảo và các phương thức aggrega/* này; các giá trị vị trí, phạm vi và địa điểm theo dạng LSP được dùng lại ở những chỗ phù hợp.

Hai phương thức giữ tên chuẩn $/ của giao thức thay vì được đổi tên vào không gian tên aggrega/, vì cả hai đều là vấn đề của tầng truyền tải, không mang ý nghĩa nào của Aggrega, và một client đã nói giao thức này xử lý chúng mà không cần thêm gì: $/cancelRequest, dừng một yêu cầu mà client không còn cần câu trả lời, và $/progress, là cách daemon báo cáo một thao tác dài trong khi nó chạy. Cả hai được mô tả bên dưới.

🔴 Mọi yêu cầu bên dưới đều mang workspaceRoot, đường dẫn tuyệt đối của workspace mà nó tác động, và điều này không được nhắc lại ở từng phương thức. Ba yêu cầu không mang nó, vì đối tượng của chúng không phải là một workspace: aggrega/initialize, aggrega/getSchema và aggrega/scaffoldEntity — ngoại trừ việc aggrega/scaffoldEntity khi ghi hoặc liệt kê một ví dụ chạy được thì có nêu tên một workspace. Xem Mọi yêu cầu đều nêu tên workspace mà nó liên quan để biết một yêu cầu không nêu workspace nào sẽ nhận được gì, và Khai báo workspace mà bạn muốn được đẩy chẩn đoán để biết các chẩn đoán được đẩy đi đâu.

Cấu trúc từng trường được công bố dưới dạng một schema, và tài liệu tham khảo cấu trúc truyền là nơi để đọc chúng. Trang đó nêu đối tượng tham số của mọi phương thức, mọi kết quả và mọi payload thông báo — mỗi trường với kiểu của nó, có bắt buộc hay không, và nó mang gì — cùng với ba thuộc tính áp dụng cho toàn bộ bề mặt chứ không theo từng phương thức: hai trường mà mọi yêu cầu chấp nhận ngoài các trường do chính phương thức của nó khai báo, là workspaceRoot ở trên và workDoneToken của Theo dõi một thao tác dài; một đối tượng params mang một khóa mà phương thức của nó không chấp nhận sẽ bị từ chối, với tập được chấp nhận được nêu trong lời từ chối; và nơi một tập hợp vắng mặt đến đường truyền dưới dạng null thay vì dạng rỗng. Trang đó được sinh ra từ schema ấy, nên nó thay đổi khi hợp đồng thay đổi.

Trang này mang giao thức, trang kia mang cấu trúc, và chúng được thiết kế để đọc cùng nhau. Ở đây: khung truyền, mục đích của từng phương thức, phạm vi của nó, những gì nó ghi, những lời từ chối nó đưa ra và lý do, các mã lỗi và cách xử lý từng mã. Ở kia: những gì cần đặt lên đường truyền, từng khóa một. Vì vậy danh sách bên dưới nêu tên từng phương thức và nói việc gọi nó có nghĩa là gì, còn danh sách trường cho yêu cầu bạn đang soạn nằm trong tài liệu tham khảo bên cạnh.

Các yêu cầu:

  • aggrega/initialize — bắt tay. Thương lượng mã hóa vị trí (máy chủ ưu tiên UTF-8, sau đó UTF-16, rồi UTF-32, và mặc định là UTF-16), nhận workspace bạn khai báo cho các chẩn đoán được đẩy, và báo cáo thư mục gốc của workspace đó, lớp cấu hình mà các thiết lập của nó được phân giải từ đó, và dấu hiệu đã phân giải nó. Câu trả lời cũng mang version, phiên bản của tệp nhị phân đang trả lời: cùng giá trị mà aggrega version báo cáo cho tệp nhị phân đó. Nó mô tả tiến trình đang chạy, nên khi tệp mà daemon được khởi động từ đó đã bị thay thế — chẳng hạn một lần build lại vào cùng đường dẫn — version vẫn nêu daemon đang chạy trong khi hỏi tệp sẽ nêu bản thay thế của nó; hãy đọc nó ở đây khi câu hỏi là bạn đang nói chuyện với phiên bản nào. workspaceRoot là tùy chọn và nó khai báo một workspace chứ không tác động lên một workspace — xem Khai báo workspace mà bạn muốn được đẩy chẩn đoán. Gửi capabilities.window.workDoneProgress: true để cho biết client của bạn có thể xử lý các thông báo tiến độ; capabilities.workDoneProgress của câu trả lời lặp lại điều đó, và trường này vắng mặt đối với một client không khai báo gì. Xem Theo dõi một thao tác dài.
  • aggrega/validate — xác thực nội dung của một tệp; trả về các chẩn đoán. release là một đường dẫn tương đối so với thư mục gốc của workspace, nêu Release để xác thực theo — cùng giá trị mà aggrega/irGraph nhận, và cùng giá trị mà aggrega build --release nhận khi chạy từ thư mục gốc. Nó là tùy chọn, và nó chọn phạm vi của câu trả lời: nêu một Release thì các kiểm tra cần đến một Release sẽ chạy theo nó — một thực thể catalog được kiểm tra như một thực thể đơn lẻ theo các điều kiện của Release đó, và mọi tài liệu khác được kiểm tra theo bao đóng phụ thuộc của Release đó; bỏ qua nó thì câu trả lời bao gồm những gì tài liệu có thể bị ràng buộc khi đứng riêng, và mang checked để cho biết điều đó. Một giá trị có mặt nhưng sai dạng sẽ bị từ chối trong cả hai trường hợp — một đường dẫn tuyệt đối, hoặc một đường dẫn phân giải ra ngoài thư mục gốc của workspace, sẽ bị từ chối thay vì được phân giải. Xem Xác thực trực tiếp.
  • aggrega/diagnostics — trả về các phát hiện được lưu giữ cho một tệp. Nếu một lần xác thực của chính tệp đó đang chạy khi yêu cầu đến, câu trả lời sẽ chờ nó và báo cáo những gì nó tìm thấy, nên câu trả lời không bao giờ là một kết luận “không có vấn đề” cho một tệp mà daemon đang dở tay tìm lỗi. Xem Yêu cầu chẩn đoán trong khi một lần xác thực đang chạy.
  • aggrega/hover — nội dung hover cho thực thể tại một vị trí. release là tùy chọn và trả lời theo các điều kiện của Release đó — xem Trả lời theo các điều kiện của một Release.
  • aggrega/completion — các ứng viên hoàn thành tại một vị trí. Ở nơi con trỏ nêu tên một thực thể theo loại — type của một component, type của một phần gắn Feature, một giá trị extends:, implements: của một Recipe hoặc FeatureRecipe — các ứng viên là tên thuộc loại đó mà chính các tài liệu trong workspace của bạn khai báo và, với một Component hoặc một Feature, cả các tên mà catalog_dirs đã cấu hình của bạn khai báo, mỗi tên được đưa ra một lần và theo thứ tự tên. Do đó một workspace lấy các Components và Features từ một catalog sẽ được đưa ra chúng, chứ không chỉ những gì nó tự soạn. Các Recipes và FeatureRecipes, được đưa ra tại giá trị của một ánh xạ Manifest, đến từ chính các tài liệu của workspace. Một thực thể chỉ có trong bộ nhớ đệm artifact hoặc một registry sẽ không được đưa ra: việc trả lời một yêu cầu hoàn thành không bao giờ tải về. release là tùy chọn và trả lời theo các điều kiện của Release đó — xem Trả lời theo các điều kiện của một Release.
  • aggrega/resolve — phân giải thực thể được tham chiếu tại một vị trí (đi tới định nghĩa). release là tùy chọn và trả lời theo các điều kiện của Release đó — xem Trả lời theo các điều kiện của một Release.
  • aggrega/findReferences / aggrega/findImplementations. Mỗi phương thức nhận một release tùy chọn và trả lời theo các điều kiện của Release đó — xem Trả lời theo các điều kiện của một Release.
  • aggrega/irGraph — đồ thị IR đã biên dịch của một Release, dùng cho việc trình soạn thảo tự kiểm tra. release là một đường dẫn tương đối so với thư mục gốc của workspace, chỉ định một Release nằm trong đó — cùng giá trị mà aggrega build --release nhận khi chạy từ thư mục gốc. Mọi dạng khác đều bị từ chối bằng lỗi invalid-params tiêu chuẩn, nêu rõ nên gửi gì thay vào đó: một đường dẫn tuyệt đối, một đường dẫn phân giải ra ngoài thư mục gốc của workspace — dù nó leo ra ngoài theo cách viết hay dẫn ra ngoài qua một liên kết, tới tệp hoặc tới một thư mục trên đường đi — và một giá trị rỗng đều bị từ chối thay vì được phân giải, nên một yêu cầu không bao giờ báo cáo về một tệp mà workspace không chứa. Một Release mà cấu hình workspace của bạn chỉ định, dưới dạng build.authoring_release hoặc một khóa của workspace.releases, là Release mà workspace chứa dù tệp của nó nằm ở đâu, nên một liên kết bên trong workspace dẫn tới nó được chấp nhận, đúng như aggrega/releaseCandidates liệt kê nó. Một thư mục catalog mà Release đọc nhưng không thể duyệt — chẳng hạn một thư mục có tồn tại nhưng không đọc được — bị từ chối như aggrega inspect từ chối nó, trước khi bất cứ thứ gì khác được đọc: lỗi là 1004 entity-not-resolvable, thông điệp của nó là báo cáo mà dòng lệnh in ra cho thư mục đó, trên một dòng ([CATALOG_ERROR] <directory>: catalog load: …), và không có đồ thị nào được dựng trên các thư mục còn lại. Một thư mục mà cấu hình workspace liệt kê nhưng không phải là thư mục — chẳng hạn không có gì tồn tại ở đó — bị từ chối theo cùng cách và vào cùng thời điểm, 1004 entity-not-resolvable, với thông điệp là lời từ chối mà mọi lệnh đưa ra cho nó, nêu tên mục đó, tệp cấu hình và dòng liệt kê nó, cùng thiết lập liên quan (Where local entities are read from). Một thư mục catalog chứa một liên kết dẫn ra ngoài thư mục mà các lần đọc của nó phải ở bên trong — một tài liệu hoặc một thư mục được liên kết từ nơi khác, bên dưới một thư mục catalog trong workspace hoặc bên dưới một thư mục mà cấu hình chỉ định ở ngoài workspace — bị từ chối theo cùng cách và vào cùng thời điểm, với 1004 và câu thông báo riêng của điều kiện đó nêu tên liên kết và nơi nó dẫn tới: không có gì được đọc qua một liên kết như vậy, và một đồ thị được dựng khi không có nó có thể phân giải một thực thể khác cùng tên thay vào chỗ của nó. Một liên kết dẫn ra ngoài nằm giữa các tài liệu bên cạnh Release cũng vậy, khi Release chỉ định Aggregate hoặc Manifest của nó theo định danh. Một tệp mà Release, Manifest của nó hoặc một Release mà nó kế thừa chỉ định bằng đường dẫn — aggregate:, manifest:, extends: hoặc một $import: trong parameters — mà dẫn ra ngoài workspace, theo cách viết hay qua một liên kết, bị từ chối với câu thông báo riêng của điều kiện đó (fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Một tham chiếu tới tệp khác dẫn ra ngoài thư mục mà nó phải ở bên trong)”), phần data của lỗi đặt nó vào khóa trong Release đã dẫn tới tệp đó, và không có gì được đọc từ tệp đó; một Release mà cấu hình chỉ định ở ngoài workspace cũng bị giới hạn theo cùng cách trong thư mục chứa nó, nên một đường dẫn mà nó hoặc một Release trong chuỗi của nó dẫn tới viết ra mà rời khỏi thư mục đó cũng bị từ chối. Lưu ý rằng aggrega/releaseCandidates trả lời bằng đường dẫn tuyệt đối, nên một client chuyển dữ liệu từ bề mặt này sang bề mặt kia cần chuyển đổi giữa hai dạng. Việc tham số này từ chối một cách viết mà các tham số theo từng tài liệu file và uri chấp nhận là có chủ ý, và Which spellings a parameter you send accepts nói điều gì quyết định việc đó. Đồ thị giữ kín mọi giá trị mà tác giả đã khai báo là nhạy cảm, đúng như --ir-graph giữ kín chúng trên dòng lệnh: mỗi giá trị được thay bằng dấu đánh dấu mà mục “Machine-readable output” của aggrega-inspect mô tả, và mọi thứ khác được mang theo đúng như trình biên dịch đã ghi lại. unredacted: true yêu cầu các giá trị đó ở dạng rõ — cách viết của giao thức cho --unredacted của dòng lệnh, và là cách duy nhất để yêu cầu; khi vắng mặt hoặc là false, câu trả lời giữ kín chúng. Khi đó, mọi nơi câu trả lời đến đều mang các giá trị ở dạng rõ, nên một client chỉ yêu cầu chúng khi người đang dùng nó đã yêu cầu.
  • aggrega/build — biên dịch một Release và ghi các artifact của nó vào thư mục đầu ra của workspace, cũng là thư mục mà aggrega build ghi vào khi chạy từ gốc workspace. release mang cùng hợp đồng như ở trên. Nó render với mọi cổng kiểm tra được bật, nên một sai lệch khiến bản build trên dòng lệnh dừng lại cũng sẽ dừng ở đây. Một thư mục catalog mà Release đọc nhưng không thể duyệt — chẳng hạn một thư mục có tồn tại nhưng không đọc được — bị từ chối như cách aggrega build từ chối nó, trước khi bất cứ thứ gì được ghi: không có artifact nào, và không có lockfile nào khi autoPull được đặt. Một thư mục mà cấu hình workspace liệt kê nhưng không phải là thư mục cũng bị từ chối như vậy, bằng chính lời mà aggrega build dùng để từ chối nó (Nơi các thực thể cục bộ được đọc). Việc từ chối giống với việc aggrega/irGraph đưa ra cho cùng thư mục, 1004 entity-not-resolvable kèm báo cáo của dòng lệnh trên một dòng, và một liên kết dẫn ra ngoài phạm vi đọc của một thư mục catalog, hoặc ra ngoài các tài liệu nằm cạnh Release, bị từ chối như cách aggrega/irGraph từ chối nó, và không có gì được ghi. Câu trả lời nêu outputDirectory mà nó đã ghi vào và các files mà nó đã ghi, mỗi tệp tương đối với thư mục đó và được sắp xếp, cùng với mọi notices mà lần chạy phát sinh; các phát hiện mang vị trí trong tài liệu thì được gửi qua aggrega/publishDiagnostics. Một Release từ chối trong khi render được trả lời bằng chính lời từ chối đó theo lời của trình biên dịch, bao gồm mọi nguyên nhân, và lời từ chối được công bố tại nơi nó trỏ tới — xem Một lời từ chối phát sinh trong khi render. Khi autoPull được đặt, câu trả lời còn mang dependencyResolution, cùng báo cáo mà aggrega/resolveDependencies trả về, để một client đã điền các phụ thuộc như một phần của bản build đọc được những gì đã được ghim mà không cần hỏi lại — và nơi quá trình phân giải của bản build này lấy từng tham chiếu, một thông tin về lần chạy đó mà lockfile không ghi lại. Mỗi thông báo mang class của bề mặt đã phát sinh nó — deprecation, catalog, catalog-lint, extends, release-composition, hoặc dependency-resolution cho một dòng do quá trình phân giải phụ thuộc bên dưới phát sinh — và một class rỗng khi daemon không có tên cho bề mặt đó, mà client hiển thị dưới dạng text trần thay vì đoán một tên gần đúng nhất. Các tệp mà việc ghi tìm thấy trong thư mục đầu ra, hoặc trong một thư mục bên dưới nó mà nó đã ghi một tệp vào hoặc đã đi qua, nhưng không do bản build này ghi, được để nguyên tại chỗ và được nêu tên trong một thông báo sau các thông báo của chính lần chạy, dưới một class rỗng, bằng câu mà aggrega build dùng để in cảnh báo của nó — xem Các tệp mà bản build không ghi; files không bao giờ nêu tên chúng. outputParent cho biết các artifact được đặt ở đâu bên trong workspace, và tên của nó nói lên toàn bộ ý nghĩa của nó: đó là thư mục mà thư mục đầu ra được tạo bên trong, nên gửi docs sẽ ghi các artifact vào docs/dist chứ không phải vào chính docs — đúng như những gì một bản build chạy trong docs tại terminal tạo ra. Bỏ qua nó thì bản build ghi vào nơi mà một lần chạy tại gốc workspace ghi vào. Nó được hiểu khác với outputDir mà các yêu cầu ghi khác ở đây nhận, và điều đó là có chủ ý: những tham số kia nêu thư mục được ghi vào, còn tham số này nêu thư mục cha của thư mục đó, và hai tham số mang tên khác nhau vì chúng là những thứ khác nhau. Nó vẫn là một đích đến bên trong workspace, nên một giá trị tuyệt đối, một giá trị leo ra khỏi gốc, và một giá trị dẫn ra ngoài gốc qua một liên kết — một thư mục được liên kết nằm ngoài gốc, hoặc một thư mục chưa được tạo nằm bên dưới một thư mục như vậy — đều bị từ chối thay vì được phân giải. Thư mục đầu ra được tạo bên trong nó, và mọi tệp mà bản build ghi vào đó, cũng bị giới hạn trong workspace: khi một trong số chúng dẫn ra ngoài workspace qua một liên kết, bản build bị từ chối với 1004 và câu riêng của điều kiện đó nêu tên liên kết và nơi nó dẫn tới, và không có gì bị xóa hay được ghi. autoPull phân giải các phụ thuộc của Release trước khi render, cùng quá trình phân giải mà aggrega/resolveDependencies thực hiện, và tắt trừ khi một yêu cầu đề nghị bật, khớp với mặc định của chính dòng lệnh; không có nó, một Release không có lockfile bị từ chối với lỗi lockfile-absent nêu rõ lệnh cần chạy. Khi autoPull được đặt, yêu cầu này truy cập các registry và ghi lockfile — xem Truy cập registry và ghi. Một yêu cầu phân giải trước vẫn chỉ render Release một lần: việc tìm ra những tham chiếu từ xa nào mà một Release sử dụng tự nó đã là một lần render, nên quá trình phân giải đã render những gì bản build hướng tới, và bản build được trả lời từ lần render đó thay vì lặp lại nó. policyInput nêu tên một thư mục bên trong workspace, tương đối với gốc của nó, mà bản build cũng ghi vào đó payload mà mỗi vai trò quản trị trao cho plugin được gắn ở đó — các tệp mà aggrega build --policy-input ghi, với cùng tên — dù bản build hoàn tất hay dừng lại; khi đó notices của câu trả lời cho biết đã ghi bao nhiêu tệp và nêu tên từng vai trò không được ghi tệp nào, dưới một class rỗng. Với một yêu cầu thất bại, các tệp đã ghi vẫn nằm trên đĩa và bản kê đó không có trong câu trả lời: envelope lỗi chỉ mang lời từ chối. Đây là một đích đến, nên một giá trị tuyệt đối hoặc một giá trị leo ra khỏi workspace sẽ bị từ chối trước khi bất cứ thứ gì chạy.
  • aggrega/buildPreview — báo cáo những gì một bản build của Release sẽ ghi, mà không ghi gì cả. release mang cùng hợp đồng như ở trên. Nó chạy cùng phép tính mà aggrega/build chạy, dưới cùng các cổng kiểm tra, nên một Release hoặc sẽ bị từ chối ở cả hai hoặc được cả hai báo cáo — đó là điều khiến việc chọn giữa chúng là lựa chọn về đầu ra chứ không phải về mức độ nghiêm ngặt. Một thư mục catalog mà Release đọc nhưng không thể duyệt, hoặc chứa một liên kết dẫn ra ngoài thư mục mà phạm vi đọc của nó phải nằm trong, bị từ chối theo cùng cách, trước khi bất cứ thứ gì được render, và một thư mục mà cấu hình workspace liệt kê nhưng không phải là thư mục cũng vậy, như trên aggrega/build. Câu trả lời mang files, các tên tương đối với đầu ra mà một bản build sẽ tạo ra, được sắp xếp, cùng với mọi notices; không có outputDirectory, vì không có gì được ghi ở đâu để mà nêu tên. Một Release từ chối trong khi render được trả lời và công bố đúng như cách aggrega/build trả lời và công bố nó. Nó từ chối autoPull với một lỗi invalid-params nêu rõ cần gửi gì thay thế: việc điền các phụ thuộc sẽ ghi lockfile, còn yêu cầu này không ghi lockfile. Nó không truy cập registry nào. policyInput là lần ghi duy nhất mà nó thực hiện, và chỉ khi được gửi: nó ghi các payload quản trị vào thư mục đó đúng như aggrega/build làm — các tệp mà aggrega build --dry-run --policy-input ghi — không động đến thư mục đầu ra và lockfile, với cùng bản kê trong notices và cùng giới hạn: với một yêu cầu thất bại, các tệp đã ghi vẫn nằm trên đĩa và bản kê không có trong câu trả lời.
  • aggrega/resolveDependencies — phân giải các phụ thuộc catalog và nguồn của Release vào cache, ghim các đầu vào bên ngoài mà quá trình render của nó tiêu thụ vào kho định địa chỉ theo nội dung, và ghi lockfile của nó. release là một đường dẫn tương đối so với thư mục gốc của workspace, cùng giá trị mà aggrega/irGraph nhận và bị từ chối theo cùng các dạng. upgrade loại bỏ các ghim đã ghi và phân giải lại, đẩy mỗi phụ thuộc lên phiên bản cao nhất hiện có; targets thu hẹp điều đó vào các tham chiếu thực thể mà nó nêu tên, giữ nguyên mọi ghim khác. verify kiểm tra kết quả phân giải đã ghi so với kết quả mà yêu cầu này sẽ thực hiện khi không có nó, tôn trọng các ghim đã ghi theo cùng cách, và không ghi lockfile, bản ghi tin cậy plugin hay entity.lock nào — cache vẫn được đọc và lấp đầy như khi không có nó — trả lời verified: true cùng toolchain mà lockfile ghi lại. verify bị từ chối là tham số không hợp lệ khi đi cùng upgrade, cùng targets, và cùng pinSources dù mang giá trị nào, trước khi bất cứ thứ gì được phân giải hay bất kỳ tiến độ nào được báo cáo: một lần nâng cấp bỏ đi các ghim mà verify tồn tại để tôn trọng, các mục tiêu được nêu tên chỉ được phân giải lại bởi một lần nâng cấp, và pinSources quyết định việc một lần phân giải sẽ ghi lại các ghim mà một entity.lock còn thiếu hay từ chối vì chúng, điều mà một phép so sánh không ghi entity.lock nào đều không làm. Dòng lệnh và công cụ trợ lý từ chối cùng các cặp này. Câu trả lời nêu tên lockfile mà nó đã ghi hoặc so sánh, cùng mọi tham chiếu nó đã ghim, trong entities, libraries và plugins, mỗi mục mang version mà nó phân giải tới và source của nó — nơi lần chạy này lấy tham chiếu, bằng từ mà aggrega pull --detail in ra cho cùng lần phân giải: fetched-fresh, cache-reuse, local, in-binary hoặc external — kèm theo sourceArtifacts, trustedPlugins, externalInputs — số đầu vào bên ngoài mà lockfile ghim sau khi lần chạy kết thúc, tính cả những đầu vào được chuyển tiếp lẫn những đầu vào lần chạy này phát hiện — và mọi notices mà quá trình phân giải phát sinh. 🔴 Một câu trả lời thành công tự nó không có nghĩa là việc ghim đầu vào bên ngoài đã hoàn tất. Khi lần chạy đã ghim mọi phụ thuộc nhưng không thể xác định xong những đầu vào bên ngoài nào mà Release tiêu thụ, nó trả lời incompleteExternalInputs cho biết điều gì đã dừng việc phát hiện, và vẫn trả lời là thành công — các ghim phụ thuộc đã hoàn chỉnh và nằm trên đĩa, nên báo cáo toàn bộ yêu cầu là thất bại sẽ bảo bạn làm lại công việc vốn đã đúng. Hãy đọc trường đó trước khi coi một lockfile là đã được ghim đầy đủ: nó vắng mặt khi không còn gì chưa được phát hiện, nên sự hiện diện của nó chính là tín hiệu. Không có tham số thư mục catalog: ngăn tìm kiếm là ngăn mà workspace cấu hình. Đây là yêu cầu ghim duy nhất của phiên cho một Release, và cũng là nơi các đầu vào bên ngoài được ghim — những URL nào mà một lần render tiêu thụ phụ thuộc vào những gì nó render, nên yêu cầu này render Release để tìm ra, và một yêu cầu build sau đó được phục vụ từ những gì nó đã ghi lại. Một Recipe hoặc FeatureRecipe mà Release build, có entity.lock không ghi ghim cho một đầu vào mà thực thể đọc, sẽ khiến yêu cầu bị từ chối, nêu tên aggrega pin và từng đầu vào chưa được ghi; pinSources: true thay vào đó chạy bước ghim đó trên các thực thể ấy, ghi entity.lock bên cạnh mỗi thực thể — cùng bước mà aggrega/pin chạy, ghi cùng các byte. Khi vắng mặt, pinSources theo pin_sources_at_pull của workspace; khi được gửi, nó ghi đè thiết lập đó theo cả hai chiều, nên false từ chối ngay cả trong một workspace được cấu hình để ghim. Yêu cầu này truy cập các registry và ghi — xem Truy cập registry và ghi.
  • aggrega/pin — ghi lại, trong entity.lock bên cạnh một Recipe hoặc FeatureRecipe, ghim nội dung cho mọi đầu vào mà thực thể đọc từ bên ngoài tài liệu của chính nó: một nguồn từ xa có tọa độ được viết đầy đủ, một tệp mà một mục artifacts nhập vào, và mỗi tệp mà một nguồn cục bộ đóng góp vào những gì một bản phát hành của thực thể mang theo. Đó là cùng bước mà aggrega pin chạy tại terminal, và nó ghi cùng các byte. entity là bắt buộc và là một đường dẫn tương đối so với thư mục gốc của workspace, nêu tên tài liệu thực thể, bị từ chối theo cùng ba dạng như release. Không có Release nào được nêu tên: một nguồn từ xa có tọa độ không mang template chỉ định một artifact cho mọi Release sử dụng thực thể, nên không cần gì từ một Release để ghim nó, trong khi một nguồn từ xa có tọa độ đến từ một template được ghim theo từng Release bởi aggrega/resolveDependencies; một nguồn cục bộ được viết dưới dạng template đóng góp mọi tệp trong thư mục của thực thể, và mỗi tệp đó được ghim tại đây. dryRun phân giải các đầu vào và trả lời bằng lock mà bước này sẽ ghi dưới dạng content, không ghi gì bên cạnh thực thể; cache nội dung vẫn được lấp đầy. Câu trả lời mang entity, kind, name và pinnable — false đối với một kind không đọc gì mà lock ghi lại, khi đó không có gì bên cạnh thực thể bị động đến và mọi trường khác vắng mặt — và nếu không thì có lock mà nó đã ghi, changed (false khi lock đã ghi mọi ghim và được giữ nguyên từng byte), removed khi thực thể giờ không đọc gì mà lock ghi lại và lock của nó đã bị xóa, và pins, mỗi mục cho một loại ghim kèm số lượng mà lock chứa. Bản thân tệp thực thể không bao giờ bị ghi. Yêu cầu này ghi bên cạnh thực thể, bên trong workspace, và truy cập các host mà nguồn của thực thể nêu tên — xem Truy cập registry và ghi.
  • aggrega/cacheStatus — những gì các cache trên đĩa đang chứa: mỗi mục cho một phần tử được cache với kích thước của nó và, nếu có, digest nội dung của nó, được nhóm theo loại. Chỉ nhận workspace và không gì khác. Mỗi loại mang một reach — workspace cho cache artifact nằm dưới thư mục cache riêng của workspace này, machine cho các kho module đã biên dịch, plugin-describe và gói tài liệu mà mọi dự án trên máy dùng chung — và scope nêu tên trực tiếp các loại dùng chung toàn máy. Nó không ghi gì. Xem Truy cập registry và ghi để biết vì sao reach có mặt trên một câu trả lời không thay đổi gì.
  • aggrega/cachePrune, aggrega/cacheEvict, aggrega/cacheClear — thu hồi nội dung đã cache. Một lần prune xóa những gì không lockfile nào của workspace tham chiếu; một lần evict cắt giảm kho module đã biên dịch xuống maxSize, một lượng byte được viết theo cách dòng lệnh viết (5GiB, 512MiB, hoặc một số byte); một lần clear xóa sạch mọi cache mà phiên này quản lý. Mỗi câu trả lời nêu tên những gì nó đã xóa, với mỗi mục bị xóa mang reach của loại mà nó thuộc về, và mỗi câu trả lời mang scope. Mỗi câu trả lời cũng nêu tên những gì nó để lại vì một tiến trình khác đang mở chúng — Windows từ chối xóa một tệp đang mở, và thao tác tiếp tục với phần còn lại thay vì thất bại: một lần prune hoặc evict liệt kê các mục đó trong heldOpen, và một lần clear đếm, cho mỗi cache mà nó làm trống, số tệp để lại trong heldOpenFiles và kích thước của chúng trong heldOpenBytes. Ở các nơi khác, danh sách trống và các số đếm bằng không, và một lần chạy sau có thể thu hồi những gì còn lại. Các yêu cầu này vươn ra ngoài workspace — xem Truy cập registry và ghi.
  • aggrega/registryList — các registry mà workspace này được cấu hình để truy cập: host của mỗi mục, bí danh tùy chọn, việc nó có phải là mặc định hay không, tư thế tin cậy của nó dưới dạng các trường riêng biệt, và việc có thông tin xác thực cho host đó hay không. Chỉ nhận workspace và không gì khác. Nó không liên hệ với registry nào. Trạng thái thông tin xác thực chỉ báo cáo sự hiện diện — không bao giờ là thông tin xác thực, không bao giờ là dạng của nó, và không bao giờ là việc registry có chấp nhận nó hay không, điều sẽ cần một lượt mạng mà một thao tác liệt kê không thực hiện — và nó được đọc từ kho thông tin xác thực dùng chung toàn máy, điều mà credentialStateIsMachineWide nói rõ.
  • aggrega/search — tìm kiếm trong chỉ mục cục bộ của các registry đã cấu hình. Mọi trường đều thu hẹp kết quả và đều không bắt buộc, nên một đối tượng params rỗng sẽ yêu cầu mọi thứ chỉ mục đang giữ. Yêu cầu này không liên hệ mạng: chỉ mục là bản chụp ngoại tuyến được ghi trong thư mục cache riêng của workspace này. Phiên bản được báo cáo là phiên bản mà một lần phân giải sẽ chọn — một phiên bản có lệnh thu hồi mang chữ ký mà workspace này tin cậy sẽ bị loại trừ và được nêu tên trong retracted — và câu trả lời mang theo nguồn gốc của chính nó: indexes cho biết tuổi bản chụp của từng registry đã tìm, stale đánh dấu bản chụp nên làm mới, và missingIndexHosts nêu tên các registry đã cấu hình nhưng không có chỉ mục cục bộ, do đó nội dung của chúng vắng mặt trong câu trả lời.
  • aggrega/registryAdd — đăng ký một registry cùng chính sách tin cậy chữ ký của nó. host là bắt buộc; mọi thứ khác định hình chính sách hoặc đích ghi. keyPath và trustedRoot nêu tên các tệp: một giá trị tuyệt đối — chẳng hạn một tệp được chọn trong hộp thoại — được đọc tại nơi nó chỉ đến; một giá trị tương đối nêu tên một tệp bên trong workspace, được phân giải theo gốc workspace chứ không theo thư mục mà daemon đang chạy, và một giá trị leo ra khỏi gốc hoặc dẫn ra ngoài gốc qua một liên kết sẽ bị từ chối với lỗi invalid-params trước khi bất cứ thứ gì được đọc hay ghi. Một trustedRoot tương đối được ghi lại là tệp mà nó nêu tên trong workspace, nên mục đăng ký nêu tên tệp đó bất kể một lần xác minh sau này chạy trong thư mục nào. fetchTrust mặc định là true khi khóa vắng mặt, khớp với dòng lệnh, và lấy chính sách mà registry tự quảng bá ở lần liên hệ đầu tiên; trust trong câu trả lời cho biết điều gì đã xảy ra — chính sách đã được ghim, registry không quảng bá chính sách nào (và, với unreachable bên cạnh, hoàn toàn không thể kết nối được), đường cơ sở tích hợp sẵn của hub chính thức đã được ghim thay thế, hoặc không có lần lấy nào được thử. Việc đăng ký này giống hệt việc mà aggrega registry add thực hiện: cùng một lần lấy dưới cùng tư thế mạng, ghi cùng một mục đến từng byte. Trong một workspace ngoại tuyến, lần lấy bị từ chối trước khi bất cứ kết nối nào được quay số, nên registry không bao giờ được hỏi, và một registry khác với hub chính thức sẽ bị từ chối trừ khi yêu cầu cung cấp identities hoặc keyPath, vốn đăng ký đúng những gì đã gửi và không thực hiện lần lấy nào: thông điệp của lỗi là câu mà dòng lệnh in ra, đứng trước là mã ngắn của điều kiện E0310 — giống như thông điệp của mọi lần từ chối yêu cầu này có nêu một điều kiện đều mở đầu bằng mã ngắn của nó — và không có gì được ghi. Hub chính thức vẫn được ghi với đường cơ sở tích hợp sẵn, được trả lời với trust.baseline là true và trust.reason cho biết hub không được hỏi về chính sách tin cậy vì workspace đang ngoại tuyến — lý do mà thông báo của dòng lệnh mở đầu — và không có notAdvertised, vì hub chưa bao giờ được hỏi. Yêu cầu này mặc định ghi vào cấu hình toàn cục — xem Kết nối registry và ghi.
  • aggrega/registryRemove — xóa mục của một registry, được xác định theo host hoặc bí danh thân thiện. Một token không khớp với gì sẽ bị từ chối thay vì được trả lời là thành công trên một cấu hình không thay đổi. Yêu cầu này mặc định ghi vào cấu hình toàn cục — xem Kết nối registry và ghi.
  • aggrega/logout — xóa thông tin xác thực đã lưu cho một registry, cũng là thao tác xóa mà aggrega logout thực hiện tại terminal. registry là bắt buộc và nêu tên host của registry đúng như khi bạn xác thực với nó; ở đây không có bí danh thân thiện nào để phân giải, vì kho thông tin xác thực được đánh khóa theo địa chỉ mà client xác thực tới chứ không theo bất cứ thứ gì một cấu hình đặt tên, nên một host mà không workspace nào cấu hình vẫn có thể có thông tin xác thực mà bạn có thể xóa. Một host mà kho không giữ thông tin xác thực nào được xóa thành công và không có gì được ghi lại — một caller yêu cầu một host không có thông tin xác thực đã nhận được điều nó yêu cầu, nên đó là một câu trả lời chứ không phải lỗi, và lệnh terminal cũng làm như vậy. Câu trả lời mang registry và scope. Nó không mang bất kỳ phần nào của thông tin xác thực dưới bất kỳ dạng nào, và không báo cáo gì về việc trước đó có thông tin xác thực hay không: xác lập điều đó sẽ cần một lần đọc kho thứ hai mà không ai yêu cầu, nên hãy hỏi aggrega/registryList khi câu hỏi là có hay không. Yêu cầu này không liên hệ registry nào — xóa một thông tin xác thực đã lưu là một thao tác cục bộ, và việc registry đó có chấp nhận thông tin xác thực hay không thì không được hỏi. Yêu cầu này thay đổi kho thông tin xác thực mà mọi dự án trên máy dùng chung — xem Kết nối registry và ghi.
  • aggrega/registryUpdate — làm mới chỉ mục tìm kiếm cục bộ mà aggrega/search đọc. Khi registry vắng mặt, mọi registry đã cấu hình đều được làm mới; nêu tên một registry thì chỉ làm mới registry đó. upgrade đọc lại toàn bộ mọi repository, không so sánh gì với chỉ mục đã được ghi; một lần làm mới không có nó vốn đã đọc lại bất cứ thứ gì đã thay đổi. Câu trả lời mang số lượng bản ghi của từng host, các repository không đọc được — mỗi repository kèm một reason mở đầu bằng loại lỗi cuối cùng của lần đọc khi có — readsRetried, số lần đọc mà registry đã từ chối hoặc ngắt giữa chừng và được yêu cầu lại, mỗi lần đọc chỉ tính một lần và có cả giá trị 0, các dấu ngừng hỗ trợ đã gặp, error của một host bị lỗi — với unreachable bên cạnh khi registry đó không thể kết nối được — và indexRoot, thư mục trong cache riêng của workspace này nơi các chỉ mục được ghi vào. Yêu cầu này kết nối tới mọi registry mà nó làm mới — xem Kết nối registry và ghi.
  • aggrega/publishEntity — đóng gói một thực thể catalog và phát hành nó lên một registry. entity là một đường dẫn tương đối so với thư mục gốc của workspace, chỉ tới tài liệu cần phát hành, và bị từ chối trong cùng ba trường hợp như release — vắng mặt, tuyệt đối, hoặc phân giải ra ngoài thư mục gốc. Một thực thể Plugin còn cần plugin, cùng loại đường dẫn, chỉ tới tệp thực thi được phát hành bên trong manifest của chính thực thể đó. registry là đích đến và mặc định là registry đã cấu hình của workspace. dryRun tính toán gói và digest mà một lần phát hành gói đó sẽ tạo ra, và không liên hệ registry nào. Bỏ qua sign thì theo chính sách riêng của registry đích, đúng như dòng lệnh làm khi không có cờ của nó, còn gửi trường này là lựa chọn của bên gọi — và cả hai đều không nới lỏng việc từ chối, vì một chính sách của registry hoặc workspace yêu cầu chữ ký sẽ từ chối một lần phát hành không ký bất kể trường này nói gì. pinSources: true chạy bước ghim của tác giả thực thể trên thực thể trước khi nó được đóng gói, nên entity.lock mà bước này ghi bên cạnh là một phần của những gì được phát hành — cùng bước mà aggrega/pin chạy. Bước này chạy trước mọi lần từ chối đánh giá nội dung của thực thể — một chính sách ký, cơ chế bảo vệ tính bất biến — nên một lần phát hành bị từ chối ở đó vẫn để lại tệp lock đã ghi; một lần từ chối về chính yêu cầu, chẳng hạn workspace ngoại tuyến hoặc không có đích đến, xảy ra trước và không ghim gì, và lần từ chối một thực thể dùng chung thư mục với một thực thể khác cũng vậy, vì bước này không được ghi tệp lock vào đó. Khi vắng mặt, nó theo pin_sources_at_push của workspace; khi được gửi, nó ghi đè thiết lập đó theo cả hai chiều. Dưới dryRun, bước này báo cáo tệp lock mà nó sẽ ghi và không ghi gì. Một lần phát hành không chạy bước này sẽ từ chối một Recipe hoặc FeatureRecipe có entity.lock không ghi nhận ghim nào cho một đầu vào mà nó đọc, hoặc một ghim mà đầu vào không còn khớp, trước khi đóng gói bất cứ thứ gì — cả dưới dryRun — nêu tên aggrega pin, pinSources và pin_sources_at_push; đó là lần từ chối mà aggrega/resolveDependencies đưa ra trên cùng tệp lock. Câu trả lời mang reference, tag, kind, mediaType, cặp size, digest đã phát hành — dưới dryRun là digest mà lần phát hành đó sẽ tạo ra, chính là digest mà aggrega push --dry-run in ra — signed, alreadyPublished, dryRun và reach; pin — cùng câu trả lời mà aggrega/pin đưa ra — khi bước này đã chạy; và wholeDirectorySource khi nguồn cục bộ của thực thể được viết dưới dạng mẫu, nêu tên nguồn đó như được viết. Một nguồn như vậy chỉ chọn thư mục của nó khi một Release điền vào mẫu, nên lần phát hành mang theo mọi tệp trong thư mục của thực thể thay vì chỉ các tệp mà thực thể nêu tên, và trường này là cách bên gọi biết điều đó đã xảy ra — cả trong một lần chạy thử. Nó cũng mang windowsUnusableEntries khi kho lưu trữ mà lần phát hành mang theo chứa các mục mà Windows không thể lưu như đã viết — một đường dẫn có một phần mang tên một thiết bị, chẳng hạn CON, AUX hoặc NUL, ở bất kỳ kiểu chữ hoa thường nào và bất kể phần mở rộng theo sau, hoặc một phần kết thúc bằng dấu chấm hoặc dấu cách — nêu tên từng mục, tên tệp của chính tài liệu thực thể trước, rồi đến các tệp nó mang theo; trường này vắng mặt khi không có mục nào như vậy, bao gồm cả một thực thể được phát hành chỉ với tài liệu của nó. aggrega chạy trên Windows từ chối giải nén một mục như vậy, nên một workspace Windows không thể dùng phiên bản đó. Đây là các mục mà aggrega push cảnh báo, và một yêu cầu đã yêu cầu được báo cáo sẽ đọc thấy cùng các dòng cảnh báo trong tiến trình của lần phát hành; cả hai đều không từ chối gì, nên lần phát hành tiếp tục hoặc bị từ chối đúng như khi không có chúng, cả dưới dryRun. Thao tác này ghi vào một registry và vươn ra ngoài máy này, và với bước ghim, nó còn ghi bên cạnh thực thể — xem Tiếp cận một registry và ghi.
  • aggrega/publishArtifact — phát hành một artifact dữ liệu độc lập, chẳng hạn một gói tài liệu. file là một đường dẫn tương đối so với thư mục gốc của workspace, tuân theo cùng hợp đồng, và các byte của nó được phát hành nguyên văn: không phân tích lớp bao thực thể nào và không phân phối theo kind nào. name và tag đặt tên cho thứ được phát hành, và cả hai đều bắt buộc. mediaType mặc định là kiểu gói tài liệu. Câu trả lời mang reference, tag, mediaType, cặp size, digest đã phát hành, alreadyPublished, dryRun và reach. Nó không ký gì — một artifact đã phát hành được ký sau đó theo tham chiếu bằng aggrega/signArtifacts, vốn chỉ cần tham chiếu mà câu trả lời này báo cáo. Thao tác này ghi vào một registry và vươn ra ngoài máy này — xem Tiếp cận một registry và ghi.
  • aggrega/signArtifacts — ký các artifact đã phát hành và đính kèm từng chữ ký. references mang một hoặc nhiều địa chỉ registry chứ không phải đường dẫn, nên chúng không theo hợp đồng tương đối với workspace; một danh sách rỗng, hoặc một mục rỗng trong đó, bị từ chối. Một danh tính phục vụ cả lô và được phân giải trước khi ký bất kỳ tham chiếu nào, nên một lô hoàn toàn không có thông tin xác thực nào sẽ bị từ chối ngay từ đầu chứ không phải giữa chừng. Một lô có các tham chiếu cần những thông tin xác thực khác nhau cũng vậy: một yêu cầu không nêu khóa nào, nên đó là trường hợp cấu hình của workspace chỉ định một khóa đang giữ cho registry của một tham chiếu và không có khóa nào, hoặc một khóa khác, cho registry của tham chiếu thứ hai — không gì được ký, và lần từ chối nêu tên các registry ở mỗi bên, như References signed together need different signing credentials (Các tham chiếu được ký cùng nhau cần các thông tin xác thực ký khác nhau) mô tả. Việc ký một tham chiếu mà không có gì được phát hành sẽ bị từ chối chứ không đính kèm vào hư không, và một tham chiếu đã mang chữ ký mà chính sách tin cậy của registry của nó xác minh được sẽ được giữ nguyên và tính là đã ký, như aggrega sign mô tả. jobs, là tùy chọn, cho biết có bao nhiêu tham chiếu được ký cùng lúc: nếu vắng mặt, chúng được ký lần lượt từng cái, và một giá trị nhỏ hơn 1 bị từ chối với lỗi invalid-params trước khi bất kỳ tham chiếu nào được đọc. Mỗi tham chiếu vẫn được ký đúng như khi được ký riêng lẻ, như aggrega sign mô tả, và cả tiến trình mà yêu cầu báo cáo lẫn câu trả lời đều giữ thứ tự mà các tham chiếu được đưa ra. Câu trả lời mang signed, mỗi mục nêu một reference và digest đã phát hành mà chữ ký của nó cam kết, cùng với reach; một lô trong đó bất kỳ tham chiếu nào thất bại được trả lời là một thất bại nêu tên từng tham chiếu chứ không phải một kết quả với danh sách thiếu. Thao tác này ghi vào một registry và vươn ra ngoài máy này — xem Tiếp cận một registry và ghi.
  • aggrega/deprecateArtifact — đính kèm một dấu ngừng hỗ trợ có chữ ký vào một artifact đã phát hành. Gửi hoặc một reference duy nhất cùng severity và reason của nó, hoặc from chỉ tới một tệp lô tương đối so với thư mục gốc của workspace — gửi cả hai sẽ bị từ chối. Các trường nội dung là bắt buộc chứ không được nhắc nhập: không ai theo dõi luồng này, nên một yêu cầu thiếu một trường sẽ bị từ chối kèm tên thứ cần gửi. Chúng chỉ thuộc về một reference duy nhất: một tệp lô mang nội dung của mỗi dấu trong các mục riêng của nó, nên một severity, reason, replacement hoặc message được gửi cùng với from sẽ bị từ chối như một tham số không hợp lệ, kèm tên từng trường đã gửi, thay vì bị bỏ qua. Cùng các đầu vào không khóa mà hai yêu cầu ký nhận cũng áp dụng ở đây, vì dấu này được ký theo chính digest của nó, và các mục của một tệp lô bị ràng buộc vào một thông tin xác thực đúng như các tham chiếu của một lô ký. Câu trả lời mang marked, mỗi mục nêu reference bị rút lại, severity của nó, dấu thời gian issuedOn và digest manifest của chính dấu đó — dấu được đính kèm như một referrer không gắn tag của artifact mà nó rút lại, nên không gì khác định địa chỉ cho nó — cùng với reach. Thao tác này ghi vào một registry và vươn ra ngoài máy này — xem Tiếp cận một registry và ghi.
  • aggrega/catalogIndex — chỉ mục thực thể: kind, name, apiVersion, description, labels, tệp nguồn và origin của mọi thực thể trong workspace mà yêu cầu đã nêu. Nhận workspace và, tùy chọn, release: tập hợp này là thuộc tính của thư mục gốc workspace đó và các thư mục catalog mà nó cấu hình, hoặc, với release, của các thư mục mà cấu hình cấp cho Release đó — xem Trả lời theo các điều kiện của một Release. Nó bao quát cả hai nơi một thực thể có thể đến từ — các tài liệu Aggrega dưới thư mục gốc workspace, và các Features mà các thư mục catalog đã cấu hình mang theo — vì đây là bề mặt mà một client đối chiếu khi cần các trường mô tả của một thực thể, và một chỉ mục chỉ biết một trong hai sẽ khiến một phần của mọi danh sách ứng viên không thể phân giải. Một tài liệu workspace được tính là thực thể khi nó khai báo cả kind: lẫn metadata.name và không khai báo apiVersion nào thuộc nhóm của một dự án khác, nên YAML tình cờ nằm trong cây thư mục — tệp values của một chart, một cấu hình CI, một manifest Kubernetes đã render — bị bỏ qua thay vì được liệt kê. Một tài liệu không khai báo apiVersion nào thì được báo cáo: đó là một tài liệu Aggrega bị thiếu một trường, và việc thấy nó được liệt kê là cách bạn biết nó cần được sửa. Xem Cách một thực thể được định địa chỉ để biết origin và một file rỗng có nghĩa là gì. Không tài liệu nào nằm sau một liên kết dẫn ra ngoài thư mục gốc workspace được đọc: một thư mục ngoài thư mục gốc không được tìm kiếm, và một tệp ngoài đó không được đọc bất kể nó khai báo gì, nên một thực thể mà trình soạn thảo của bạn hiển thị dưới một liên kết như vậy không được liệt kê là của chính workspace — cũng không được aggrega/attachCandidates hay aggrega/connectionCandidates đề xuất, vì chúng đọc cùng các tài liệu đó, ngay cả khi trình soạn thảo của bạn đang mở tài liệu ấy. Điều đó đúng bất kể tài liệu khai báo gì. Ngoại lệ duy nhất là một Release mà cấu hình workspace của bạn nêu tên — dưới dạng build.authoring_release, hoặc là một khóa của workspace.releases, được xét theo tệp mà liên kết dẫn tới, nên việc nêu tên liên kết hay tệp đó đều như nhau — Release này được đọc, từ tệp mà liên kết dẫn tới, được liệt kê tại vị trí của chính liên kết, như aggrega/releaseCandidates liệt kê nó, và không bị nêu tên; một tệp mà một trong các thiết lập đó nêu tên nhưng khai báo bất cứ thứ gì khác ngoài một Release thì không được liệt kê, và liên kết của nó bị nêu tên. Các thư mục catalog đã cấu hình là cách một workspace đọc các thực thể khác được lưu ở nơi khác, nên một liên kết tới một thư mục mà cấu hình liệt kê dưới catalog_dirs — cho workspace hoặc cho một Release — không được tìm kiếm như các tài liệu của chính workspace và cũng không bị nêu tên: cấu hình đã với tới nó, và các Features của nó được liệt kê từ catalog, như của mọi thư mục catalog đã cấu hình. Các Features được liệt kê từ các thư mục catalog không bao giờ bao gồm một Feature nằm sau một liên kết dẫn ra ngoài thư mục mà việc đọc của một thư mục catalog phải nằm trong — workspace, đối với một thư mục catalog bên trong nó, hoặc chính thư mục đó, đối với một thư mục mà cấu hình nêu tên bên ngoài workspace — nên một thực thể mà câu trả lời nêu là nằm sau một liên kết nó không đọc sẽ không bao giờ đồng thời được liệt kê bên cạnh tên đó. Câu trả lời nêu tên mỗi liên kết như vậy trong unreadLinkedDirs, với liên kết tới một thư mục, và unreadLinkedFiles, với liên kết có tên riêng kết thúc bằng .yaml hoặc .yml và dẫn tới một tệp — tương đối so với thư mục gốc, tại nơi liên kết nằm, theo thứ tự workspace được tìm kiếm — để client có thể giải thích lý do. Một liên kết mà việc tìm kiếm bỏ qua, do tên của nó, do vị trí của nó hoặc do một .gitignore, thì không bị nêu tên, và trong một câu trả lời theo các điều kiện của một Release thì cũng không nêu tên liên kết nằm dưới một thư mục catalog mà chỉ các Releases khác đọc. Một liên kết nằm dưới một thư mục catalog bên ngoài workspace không có vị trí tương đối so với thư mục gốc để được nêu tên, và không bị nêu tên. Cả hai trường luôn có mặt, và rỗng khi không có liên kết nào như vậy. Khi chính tệp cấu hình của workspace, hoặc lớp phủ do CI sở hữu nằm bên cạnh nó, là một liên kết dẫn ra ngoài workspace, tệp đó được nêu tên trong unreadLinkedFiles bất kể việc tìm kiếm xử lý nó thế nào, và chỉ mục là bản đọc của chính workspace mà không có gì được cấu hình — không thư mục catalog nào được đọc cho nó, và một chỉ mục theo các điều kiện của một Release bị từ chối; xem Thư mục gốc workspace và Release đang hoạt động.
  • aggrega/entityDefinition — thực thể được nêu tên phân giải thành gì: kind của nó, name và version của chính nó, description và publishScope nếu có, file nơi nó được khai báo, authoredLength của văn bản được soạn đứng sau nó, và definition của nó dưới dạng một tài liệu YAML đã áp dụng kế thừa. file được báo cáo cho mọi kind, dưới dạng một đường dẫn bạn có thể mở — tương đối so với thư mục gốc workspace đối với tài liệu bên trong, tuyệt đối đối với tài liệu bên ngoài, theo Cách một đường dẫn được báo cáo được viết. Nó rỗng trong một trường hợp: một thực thể được phân giải từ registry không có tài liệu được soạn nào trên máy này để nêu tên. authoredLength trả lời một câu hỏi khác — việc phân giải đã giữ lại bao nhiêu văn bản được soạn — và chỉ một Aggregate mới được phục vụ kèm văn bản đó, nên hãy đọc hai trường này riêng rẽ thay vì như một cặp. name là định danh của một thực thể, được viết theo cách một thực thể tham chiếu thực thể khác, và có thể mang hậu tố phiên bản. Đây là yêu cầu duy nhất ở đây bắt đầu từ một tên thay vì từ con trỏ, nên đó là yêu cầu nên dùng khi bạn đã biết mình muốn nói tới thực thể nào. release là tùy chọn và phân giải tên theo các điều kiện của Release đó — xem Trả lời theo các điều kiện của một Release. Một tên không phân giải thành gì sẽ bị từ chối thay vì được trả lời bằng một tài liệu rỗng; xem Phân biệt hai kiểu từ chối theo tên. name cũng có thể là một tham chiếu registry — oci://<host>/<repository>:<tag>, hoặc @<digest> thay cho :<tag> — và khi đó câu trả lời là thực thể được xuất bản tại tọa độ đó, được đọc từ registry của nó, với published nêu rõ những gì đã được đọc; xem Hỏi về một tọa độ.
  • aggrega/releaseClosure — bao đóng phụ thuộc của một Release: những thực thể nào nó với tới và ở các phiên bản đã phân giải nào, trong entities, libraries và plugins, cùng với các định danh aggregate và manifest mà hai con trỏ của nó phân giải thành, mọi mappingDiagnostics mà quá trình phân giải phát sinh, và các deprecations được ghi nhận đối với những gì nó với tới — trong lockfile của nó và trong bản ghi tin cậy plugin bên cạnh, nên một plugin đã bị rút lại được gắn trong một vai trò phán quyết được nêu tên giống như một tham chiếu đã ghim bị rút lại. release là một đường dẫn tương đối so với thư mục gốc workspace, nêu tên một Release bên trong đó, cùng giá trị mà aggrega/irGraph nhận và bị từ chối trong cùng các dạng, và nó yêu cầu một lockfile vì cùng lý do. Không có gì được render. Các mục của nó không nêu source: chúng cho biết Release phụ thuộc vào gì, chứ không phải một lần chạy đã làm gì, là điều mà aggrega/resolveDependencies báo cáo. Xem Một bao đóng không phải là đồ thị, vì một client đã nhận đồ thị vẫn không có thông tin này.
  • aggrega/attachCandidates — những Features nào có thể gắn vào một nút: những Feature có khả năng áp dụng đã khai báo được các nhãn của nút thỏa mãn. Gửi đúng một tọa độ. node chỉ định một tài liệu trong workspace theo metadata.name của nó; graphNode chỉ định một nút trên đồ thị đã biên dịch của release, theo id mà đồ thị đó dùng làm khóa cho nút; labels mang trực tiếp một tập nhãn và không chỉ định gì, dành cho client đã có sẵn một tập nhãn. Phản hồi lặp lại tọa độ mà nó trả lời — để trống khi không có gì để lặp lại — mang nodeLabels, các cặp nhãn mà việc so khớp được đánh giá dựa trên, labelSource cho biết đó là loại tập nhãn nào, và mỗi ứng viên dưới dạng kind, name, tệp nguồn và origin dùng để định địa chỉ nó. Việc trả lại các nhãn là điều giúp câu trả lời tự kiểm chứng được: client có thể giải thích vì sao một Feature được đề xuất mà không phải tự hình dung các nhãn của nút, vốn là chỗ câu trả lời của client và của trình biên dịch tách rời nhau. Với một nút đồ thị, các Features được đề xuất là những Feature mà Release của nút đó đạt tới. Bên cạnh graphNode, connection chỉ định một kết nối mà component của nút đó vẽ ra — socket và alias của nó — và khi đó câu trả lời còn mang slots, mỗi slot mà socket của kết nối đó khai báo cùng các Features có thể lấp vào nó, hoặc noSlotReason khi không slot nào có thể được lấp. Xem Phản hồi attach-candidate cho bạn biết gì.
  • aggrega/connectionCandidates — thực thể được chỉ định có thể kết nối tới những gì. node là metadata.name của một thực thể, cùng tọa độ mà aggrega/attachCandidates nhận dưới tên đó. Xem Phản hồi connection-candidate cho bạn biết gì bên dưới, vì hai nửa của câu trả lời không đầy đủ như nhau và phản hồi cho biết nửa nào là nửa nào.
  • aggrega/insertionPoint — vị trí trong một tài liệu được soạn mà một mục mới dưới một container được chỉ định thuộc về, được biểu diễn để client áp dụng mà không phải tự phân tích tài liệu. file chỉ định một tài liệu mà workspace chứa, tương đối so với thư mục gốc của workspace, tuyệt đối, hoặc dưới dạng địa chỉ file:// của nó; một tài liệu nằm ngoài thư mục gốc, theo cách viết hoặc qua một liên kết dẫn ra ngoài — tới tệp, hoặc tới một thư mục trên đường đi — đều bị từ chối dù được chỉ định bằng cách viết nào, và dù bạn có giữ một bản sao của nó hay không; container là đường dẫn cấu trúc từ gốc tài liệu tới container mà mục sẽ nằm bên trong, mỗi phần tử là một khóa mapping hoặc một vị trí trong sequence viết bằng số thập phân. Bạn cung cấp đường dẫn đó — daemon đọc cấu trúc riêng của tài liệu và không bao giờ suy ra một thứ thuộc về đâu từ tên gọi của nó. Xem Phản hồi insertion-point cho bạn biết gì, vì riêng vị trí thì chưa đủ để áp dụng thay đổi.
  • aggrega/attachmentContainer — việc gắn một Feature cho một nút thuộc về tài liệu nào, và container nào bên trong tài liệu đó. graphNode chỉ định một nút trên đồ thị đã biên dịch của release, theo id mà đồ thị đó dùng làm khóa cho nút, và cả hai đều bắt buộc: id của nút là một khóa của đồ thị của một Release và không có nghĩa gì nếu thiếu Release đó. Câu trả lời mang node, file và container — một danh sách các phân đoạn đúng theo dạng mà aggrega/insertionPoint nhận, để hai yêu cầu ghép với nhau mà không phải tính toán gì ở giữa. Với việc gắn trên một kết nối mà component của nút vẽ ra, thêm connection với socket, alias và document của nó — aggregate hoặc release — và câu trả lời sẽ chỉ định container features riêng của kết nối đó trong tài liệu đó. Xem Phản hồi attachment-container cho bạn biết gì, vì file là một phần của câu trả lời chứ không phải thứ bạn đã biết sẵn.
  • aggrega/connectionAtPosition — một vị trí trong một Aggregate hoặc một Release nằm bên trong mục của kết nối nào, được trả lời theo cách mà hai yêu cầu ở trên nhận một kết nối. file chỉ định tài liệu theo cách aggrega/insertionPoint chỉ định, và được đọc trước tiên từ những gì phiên đang giữ cho nó; position là vị trí trong đó, gồm line và character đếm từ không theo mã hóa của phiên; release chỉ định Release có đồ thị đã biên dịch ghi lại các kết nối, và nó bắt buộc cả với một vị trí trong Aggregate, vì nút đồ thị và kết nối chỉ tồn tại trên một đồ thị đã biên dịch. Câu trả lời mang graphNode và connection — socket, alias của nó và document nơi vị trí được đọc — để chuyển nguyên vẹn cho aggrega/attachCandidates và aggrega/attachmentContainer, hoặc noConnectionReason khi không có kết nối nào được viết ở đó. Xem Phản hồi connection-at-position cho bạn biết gì.
  • aggrega/editDocument — áp dụng một thay đổi có cấu trúc, có giới hạn, lên một tài liệu được soạn, giữ nguyên mọi byte mà nó không chạm tới. Đây là nửa còn lại của hai phương thức định vị ở trên: chúng cho biết một mục thuộc về đâu và để bạn tự soạn và áp dụng, còn phương thức này soạn và áp dụng một mục. edit chỉ định một trong bốn loại — add-component, attach-feature, wire-edge, set-value — và một giá trị ngoài các loại này bị từ chối thay vì được diễn giải; node là đường dẫn cấu trúc từ gốc tài liệu, một danh sách các phân đoạn đúng theo dạng mà aggrega/insertionPoint nhận; name là khóa mà mục được viết dưới đó và value là nội dung nó mang, ý nghĩa của chúng tùy theo edit; socket được đọc với wire-edge và bị bỏ qua trong các trường hợp khác. dryRun làm mọi việc như yêu cầu thông thường trừ việc ghi, trả lời bằng tài liệu đã sửa dưới dạng content, dành cho client muốn đưa kết quả cho tác giả xem trước; không có gì được tạo ra khi dùng nó và written để trống. file chỉ định tài liệu tương đối so với thư mục gốc của workspace hoặc theo đường dẫn tuyệt đối, và một tài liệu nằm ngoài thư mục gốc — theo cách viết, hoặc qua một liên kết dẫn ra ngoài, tới tệp hoặc tới một thư mục trên đường đi — bị từ chối mà không có gì được đọc hay ghi. Thao tác này ghi vào tài liệu bạn chỉ định, bên trong workspace — nó không phân giải phụ thuộc nào, không truy cập registry nào và không chạm tới mạng ở cả hai cách phân phối, và việc ghi chỉ diễn ra khi tài liệu đã soạn hợp lệ theo schema của chính kind của nó. Xem Phản hồi document-edit cho bạn biết gì, vì mặc định là ghi và một lần từ chối để tệp nguyên vẹn từng byte như trước.
  • aggrega/releaseCandidates — các tài liệu Release của workspace mà yêu cầu nêu tên, dưới dạng đường dẫn tuyệt đối. Chỉ nhận workspace và không gì khác: tập hợp này là thuộc tính của thư mục gốc workspace đó. Tư cách thành viên được quyết định theo loại tài liệu — kind: của tệp là Release — chứ không theo tên tệp, nên một Release được đặt tên không có tiền tố theo quy ước vẫn được đưa ra, còn một tệp chỉ đơn thuần được đặt tên giống như vậy thì không. Đây là những gì bộ chọn “Release nào?” của trình soạn thảo nên liệt kê, vì đó chính là tập hợp mà chuỗi xác định Release đang hoạt động bên dưới chọn từ đó. Câu trả lời còn mang lockfiles, ánh xạ mỗi Release được liệt kê — có khóa đúng bằng chuỗi mà releases liệt kê nó — tới đường dẫn tuyệt đối của lockfile của nó; trường này luôn có mặt, và là một đối tượng rỗng khi workspace không chứa Release nào. Nó cũng mang unreadLinkedDirs, nêu tên — tương đối so với thư mục gốc, nơi liên kết nằm — mỗi liên kết đứng ở chỗ mà việc liệt kê sẽ đọc một thư mục và dẫn tới một thư mục bên ngoài thư mục gốc workspace: không thư mục nào bên ngoài thư mục gốc được tìm kiếm, nên một Release mà trình soạn thảo của bạn hiển thị bên trong một thư mục như vậy sẽ không được liệt kê, và trường này là thứ cho phép bộ chọn giải thích lý do. Một liên kết tới thư mục mà cấu hình workspace của bạn liệt kê dưới catalog_dirs thì không được nêu tên: cấu hình đã tiếp cận nó, với tư cách thư mục catalog chứ không phải nơi lưu giữ Releases. Trường này luôn có mặt, và rỗng khi không có liên kết như vậy. Bên cạnh nó, unreadLinkedFiles nêu tên theo cùng cách mỗi liên kết có tên kết thúc bằng .yaml hoặc .yml và dẫn tới một tệp bên ngoài thư mục gốc workspace: không tệp nào như vậy được đọc, bất kể nó chứa gì, nên một Release chỉ tiếp cận được qua một trong các liên kết này sẽ không được liệt kê, và bước một-Release duy nhất của chuỗi bên dưới không tính nó. Ngoại lệ là một tệp mà cấu hình workspace của bạn nêu tên là một Release — dưới dạng build.authoring_release, hoặc là một khóa của workspace.releases, được đánh giá theo tệp mà liên kết dẫn tới, nên nêu tên liên kết hay nêu tên tệp đó đều được tính như nhau — tệp này được đọc và liệt kê tại vị trí của chính liên kết, và không bị nêu tên, miễn là nó khai báo một Release; tệp khai báo bất cứ thứ gì khác thì không được liệt kê, và liên kết của nó bị nêu tên. Trường này luôn có mặt, và rỗng khi không có liên kết như vậy. Khi chính tệp cấu hình của workspace, hoặc lớp phủ do CI sở hữu bên cạnh nó, tự là một liên kết dẫn ra ngoài workspace, tệp đó được nêu tên ở đây bất kể việc tìm kiếm xử lý nó thế nào, và việc liệt kê được đọc mà không có cấu hình nào, nên một Release mà cấu hình lẽ ra đã nêu tên qua một liên kết sẽ không được liệt kê; xem Thư mục gốc workspace và Release đang hoạt động. Xem Lockfile của một Release nằm ở đâu.
  • aggrega/activeRelease — workspace mà yêu cầu nêu tên đang trỏ tới Release nào, dưới dạng đường dẫn tuyệt đối trong trường release, dành cho client đang quyết định chọn gì làm mặc định. Chỉ nhận workspace và không gì khác. Trường này luôn có mặt, và giá trị rỗng nghĩa là workspace không trỏ tới Release nào — đây là một câu trả lời thành công chứ không phải lỗi, nên một client làm mới thông tin này mỗi lần daemon khởi động lại không bị buộc phải coi một workspace bình thường là thất bại. Khi giá trị rỗng, câu trả lời còn mang reason, bản tóm tắt một dòng về những gì chuỗi xác định đã tìm, và trace, bản giải trình theo từng bước; cả hai bị lược bỏ khi một Release được xác định. Khi một Release được xác định, câu trả lời mang lockfile thay vào đó, là đường dẫn tuyệt đối của lockfile của Release đó, trường này bị lược bỏ khi không có Release nào được xác định. Release mà nó nêu tên không nhất thiết là một Release mà aggrega/releaseCandidates liệt kê — một marker có thể nêu tên một Release trong thư mục mà việc liệt kê đó bỏ qua, chẳng hạn vendor/, hoặc một Release được đặt tên không có phần mở rộng YAML — nên câu trả lời này là nơi client đọc lockfile của Release mặc định. Xem Lockfile của một Release nằm ở đâu. Hãy hỏi nó thay vì tự suy ra câu trả lời từ một trong các đầu vào của chuỗi: một đầu vào mà chuỗi cuối cùng không dùng sẽ nêu tên một Release khác với Release nó đã chọn. Câu trả lời được tính tại thời điểm bạn hỏi, nên hỏi lại sau khi ghi một marker, sửa cấu hình hoặc thêm một tệp Release sẽ báo câu trả lời mới chứ không phải trạng thái workspace lúc daemon khởi động.
  • aggrega/setActiveRelease — ghi nhận một Release làm mặc định của workspace mà yêu cầu nêu tên, bằng cách ghi marker .aggrega/active-release của workspace đó, và trả lời đúng như aggrega/activeRelease trả lời sau khi marker đã được ghi. Nhận workspace và release: một đường dẫn tương đối so với thư mục gốc workspace, nêu tên một Release bên trong nó, tuân theo cùng ràng buộc mà release của aggrega/irGraph tuân theo — đường dẫn tuyệt đối, đường dẫn leo ra ngoài workspace và giá trị rỗng đều bị từ chối, và cũng vậy với đường dẫn dẫn ra ngoài qua một liên kết, trừ khi cấu hình workspace của bạn nêu tên Release đó. Marker là một dòng nêu tên Release tương đối so với thư mục gốc, đúng dạng mà chuỗi bên dưới đọc. Nó được ghi bên trong workspace và không ở đâu khác: khi .aggrega, hoặc chính marker, là một liên kết dẫn ra ngoài workspace — dù nơi nó dẫn tới đã tồn tại hay chưa — yêu cầu bị từ chối với lỗi invalid-params, thông điệp của lỗi là câu mô tả chính điều kiện đó với mã ngắn đứng trước, E0320: … (fatal-halts.md §“A path the operation writes leads through a link out of the directory it must stay inside (Một đường dẫn mà thao tác ghi đi qua một liên kết ra ngoài thư mục mà nó phải ở bên trong)”), nêu tên liên kết và nơi nó dẫn tới, và không có gì được ghi; một liên kết nằm trong workspace thì được ghi xuyên qua. Câu trả lời nêu tên thứ mà chuỗi xác định chọn chứ không lặp lại những gì bạn gửi, và hai thứ này khác nhau khi build.authoring_release nêu tên một Release, vì cấu hình được ưu tiên hơn marker. Hãy ghi nhận mặc định theo cách này thay vì tự ghi tệp, để nơi marker được đặt được đánh giá theo quy tắc mà mọi tệp sản phẩm ghi trong workspace đều tuân theo — xem Ranh giới workspace.
  • aggrega/effectiveConfiguration — cấu hình đang có hiệu lực cho workspace mà yêu cầu nêu tên, và lớp mà mỗi thiết lập đến từ đó. Chỉ nhận workspace và không gì khác: câu trả lời là thuộc tính của workspace đó. layers liệt kê các tệp cấu hình và các ghi đè từ biến môi trường đã đóng góp, theo thứ tự ưu tiên thấp nhất trước; settings mang mỗi thiết lập được quy nguồn dưới dạng tên phân tách bằng dấu chấm, giá trị hiệu lực của nó, và source đã quyết định nó. Một source được viết đúng như mục tương ứng trong layers, nên hai thứ này nối trực tiếp với nhau. Xem Phản hồi effective-configuration bao quát những gì để biết một source nêu tên lớp nào và giới hạn về ý nghĩa của một hàng.
  • aggrega/configInit — khởi tạo một cấu hình dùng được bằng cách đăng ký một registry và chính sách tin cậy chữ ký của nó, để một máy mới có thể kéo về và xác minh các artifact đã ký mà không cần sửa YAML bằng tay. registry là tùy chọn và khi vắng mặt thì hub chính thức được khởi tạo, cũng là giá trị mặc định mà aggrega config init dùng; host của câu trả lời cho biết cái nào đã được dùng. global và workspace là các tùy chọn ghi đè đích ghi, và gửi cả hai sẽ bị từ chối. Yêu cầu này từ chối thay vì ghi đè một tệp cấu hình đã có, nêu tên tệp đó — gửi force để vẫn tiếp tục, khi đó mục registry được hợp nhất vào nội dung đã có và các thiết lập khác được giữ nguyên. dryRun làm mọi việc mà yêu cầu thông thường làm trừ việc ghi, trả lời bằng cấu hình được khởi tạo dưới dạng content, dành cho client muốn đưa tài liệu cho tác giả xem trước khi lưu; không có gì được tạo ra và written là false. Việc từ chối khi tệp đã tồn tại cũng áp dụng dưới dryRun, nên hãy gửi kèm force để nhận được kết quả hợp nhất mà một lần ghi đè sẽ tạo ra. Trong một workspace ngoại tuyến, chỉ hub chính thức có thể được khởi tạo: yêu cầu này không nhận danh tính hay khóa nào, nên mọi registry khác đều bị từ chối đúng như cách aggrega/registryAdd từ chối, kể cả mã ngắn và câu thông báo, và thay vào đó được thêm qua yêu cầu đó với một chính sách cung cấp bằng tay. Câu trả lời mang host, scope, trust và written, cùng existed, là true khi tệp cấu hình đã có sẵn — nên mục registry được hợp nhất vào đó thay vì tạo tệp mới — và vắng mặt khi tệp được tạo mới. Theo mặc định, yêu cầu này ghi vào cấu hình toàn cục — xem Truy cập registry và ghi.
  • aggrega/configCapture — cố định cấu hình hiệu lực quan trọng cho việc build vào chính tệp cấu hình của workspace này, để workspace build giống hệt mà không cần cấu hình toàn cục của máy bên dưới. Không nhận đích ghi: việc cố định tồn tại để làm cho một workspace tự chứa, nên nó luôn ghi vào tệp của workspace đó. allPlugins mở rộng tập được cố định từ các socket quyết định đầu ra được render — các binding provider và các gắn kết governance label-transform — sang mọi socket plugin, thêm các cổng governance verdict và linter cùng socket import. Câu trả lời mang configFile, workspaceRoot, captured, sockets và catalogDirs. Xem Những gì một lần ghi cấu hình để lại, vì câu trả lời nêu tên một tài liệu giờ đã tồn tại và hành động tiếp theo của client là mở nó.
  • aggrega/skillsInstall — ghi skill Aggrega được tích hợp sẵn trong tệp nhị phân này vào thư mục skill của từng trợ lý mà yêu cầu nêu tên, cũng là việc cài đặt mà aggrega skills install thực hiện tại terminal. agents liệt kê các trợ lý theo định danh, tức các định danh mà aggrega/skillsList báo cáo; một định danh được đưa hai lần chỉ được cài một lần, và khi nhiều trợ lý được nêu tên cùng đọc một thư mục dùng chung thì skill chỉ được ghi vào đó một lần. Việc cài đặt vào dự án bắt buộc phải có trường này. Một yêu cầu global không nêu tên trợ lý nào sẽ cài cho các trợ lý tìm thấy trên máy này, như aggrega skills install --global làm khi không có --agent — mỗi trợ lý có thư mục cấu hình nằm trong thư mục home, hoặc có lệnh nằm trên PATH của môi trường daemon — và bị từ chối mà không ghi gì khi không tìm thấy trợ lý nào; không có gì được hỏi, và installed nêu tên các trợ lý mà skill đã được ghi cho. Không có global, skill được đặt vào thư mục dự án của từng trợ lý bên trong workspace mà yêu cầu nêu tên, không bao giờ vào thư mục mà daemon được khởi động; với global: true, nó được đặt vào thư mục theo người dùng của từng trợ lý dưới thư mục home mà môi trường của daemon chỉ định (HOME, hoặc USERPROFILE trên Windows). Mọi đích đến đều được kiểm tra trước khi ghi bất cứ thứ gì, nên một lần từ chối để nguyên mọi thư mục: một định danh không có thư mục skill nào được biết sẽ bị từ chối kèm tên của nó và các định danh hiện có, và một tệp tại đích đến không mang dòng chú thích mà mọi bản sao skill đã ghi đều mang sẽ bị từ chối kèm đường dẫn của nó. Một bản sao mang dòng đó — do một lần cài trước ghi, hoặc lấy từ kho skill đã phát hành — sẽ bị thay thế, đó là cách một aggrega mới hơn đưa skill lên phiên bản của chính nó. Một thư mục dự án được tiếp cận qua một liên kết dẫn ra ngoài workspace sẽ bị từ chối và không có gì được ghi, như mọi lần ghi mà daemon thực hiện trong một workspace — xem Ranh giới workspace. Câu trả lời mang skill, installed — mỗi thư mục đã ghi một mục, theo thứ tự các trợ lý được nêu tên, mỗi mục kèm các agents đọc nó, folder tuyệt đối và replaced — và scope. Với global, thao tác này ghi các thư mục mà mọi dự án trên máy đều đọc — xem Truy cập registry và ghi.
  • aggrega/skillsList — các skill mà tệp nhị phân này đi kèm và mọi trợ lý mà aggrega/skillsInstall có thể ghi chúng cho, tức danh sách mà aggrega skills list in ra. Chỉ nhận workspace và không đọc gì từ đó. skills mang name và description của từng skill; agents mang id, name, projectFolder của từng trợ lý — tương đối với gốc của một dự án, mà trên bề mặt này là workspace mà yêu cầu nêu tên — và userFolder, tương đối với thư mục home; cả hai được phân tách bằng dấu gạch chéo, và các mục được sắp xếp theo định danh. Nó không ghi gì và không truy cập gì.
  • aggrega/pluginAdd — tìm trong registry đã cấu hình một plugin thuộc loại được nêu và thêm nó vào cấu hình. type và query đều bắt buộc: type là một trong provider, governance, linter, importer và cli, còn query được so khớp với tên các plugin thuộc loại đó và phải phân giải ra đúng một, nên một truy vấn khớp nhiều plugin sẽ bị từ chối kèm danh sách ứng viên thay vì được phân giải tùy ý. capability nêu capability mà một binding provider phục vụ và là bắt buộc ở đó; role nêu vai trò của một gắn kết governance — label-transform, ir-verdict hoặc render-verdict — và là bắt buộc ở đó; mỗi trường chỉ được đọc cho loại của riêng nó và bị từ chối ở mọi loại khác, vì một trường lặng lẽ không làm gì sẽ trông như đã có tác dụng. acceptCapabilities là bắt buộc với cli và xác nhận các capability mà plugin đó khai báo: lệnh terminal có được quyết định đó bằng cách hỏi, còn giao diện này không có ai để hỏi, nên bên gọi tự có quyết định đó và gửi đi. global và workspace là các tùy chọn ghi đè đích ghi, và gửi cả hai sẽ bị từ chối. dryRun làm mọi việc mà yêu cầu thông thường làm trừ việc ghi, trả lời bằng cấu hình kết quả dưới dạng content; không có gì được tạo hay sửa đổi và written là false. Registry vẫn được tìm kiếm và phiên bản vẫn được phân giải, vì danh tính trong nội dung đó chính là danh tính mà một lần ghi sẽ ghim. dryRun bị từ chối với loại cli, thay vì bị bỏ qua: thứ mà một lần thêm phần mở rộng lệnh ghi lại là digest nội dung của các byte nó đã xác minh, một bản ghi do trình biên dịch duy trì chứ không phải nội dung để ai đó chỉnh sửa, và việc thêm sẽ cache các byte đó trong quá trình thực hiện — nên nó được ghi thay vì trả lại. Phiên bản được ghim giúp bạn — truy vấn phân giải ra một plugin, và phiên bản mà truy vấn nêu dưới dạng <name>:<version>, hoặc nếu không có thì phiên bản được phát hành cao nhất của plugin, được ghi vào mục; một phiên bản được nêu tên đã bị một tuyên bố thu hồi được workspace này tin cậy thu hồi vẫn được ghim như thường và câu trả lời mang withdrawn: true. Yêu cầu này truy cập registry, và một lần thêm loại cli không nêu phạm vi nào sẽ ghi vào cấu hình toàn cục — xem Truy cập registry và ghi. Xem Một thay đổi plugin cho bạn biết gì.
  • aggrega/pluginRemove — bỏ mục của một plugin đã cấu hình để nó không còn tham gia. type là cùng tập mà việc thêm nhận, còn query xác định mục: tên ngắn của plugin, tham chiếu đã ghim của nó, hoặc — với provider — capability mà binding phục vụ. Cả hai đều bắt buộc. global và workspace là cùng các tùy chọn ghi đè đích ghi, bị từ chối khi gửi cùng nhau theo cùng cách. Một truy vấn không khớp mục nào sẽ bị từ chối thay vì được trả lời là thành công trên một cấu hình không đổi, nên bên gọi không bao giờ được báo rằng một plugin đã ngừng tham gia khi thực ra không phải, và một lỗi gõ không bao giờ xóa nhầm plugin khác. Yêu cầu này không liên hệ registry nào: việc xóa chỉ thao tác trên văn bản cấu hình. Một lần xóa loại cli không nêu phạm vi nào sẽ ghi vào cấu hình toàn cục — xem Truy cập registry và ghi. Xem Một thay đổi plugin cho bạn biết gì.
  • aggrega/pluginSync — đồng bộ các bản ghi do máy quản lý của một thực thể Plugin với module của nó: tập host-function suy ra từ chính các import của module, và bản phản chiếu lệnh đọc từ phần tự báo cáo của module. Không bản ghi nào được viết bằng tay, vì cả hai đều là sự thật gốc nằm trong module. Cả hai trường đều bắt buộc và không trường nào có giá trị mặc định — các bản ghi được suy ra từ module, nên một lần đồng bộ không nêu gì thì không có gì để đồng bộ theo — và cả hai đều là đường dẫn tương đối so với thư mục gốc của workspace, bị từ chối khi là đường dẫn tuyệt đối hoặc phân giải ra ngoài thư mục gốc, dù theo cách viết hay qua một liên kết. Chỉ hai khối đó thay đổi: mọi byte khác được giữ nguyên văn, kể cả chú thích, dòng trống và kiểu trích dẫn, và một tệp đã ghi đúng những gì module ngụ ý sẽ được giữ nguyên từng byte và được báo là không thay đổi. Yêu cầu này ghi vào tệp thực thể bạn nêu, bên trong workspace, và không liên hệ registry nào. Xem Một thay đổi plugin cho bạn biết gì.
  • aggrega/pluginGenCatalog — sinh một thực thể Plugin cho mỗi guest được chọn, hợp nhất các trường hợp đồng suy ra từ bản tự báo cáo của guest với một lớp phủ (overlay) do người viết soạn cho từng plugin. fromEmbedded và plugin là hai chế độ chọn và chỉ đúng một chế độ được áp dụng: mọi guest mà binary này mang theo, hoặc một module tại đường dẫn bạn chỉ định; chỉ định cả hai, hoặc không chỉ định cái nào, đều bị từ chối thay vì được tự giải quyết. overlay là bắt buộc, và nó là một thư mục chứa các overlay khi dùng fromEmbedded hoặc một tệp overlay duy nhất khi dùng plugin — một overlay được khớp với một guest theo định danh khi có nhiều guest, và không có gì để khớp khi chỉ có một. outputDir là bắt buộc trong cả hai cách chuyển giao, và dryRun không miễn cho nó: một lần chạy thử thay đổi nơi nội dung được đưa tới, chứ không thay đổi nội dung đó dành cho tệp nào, nên mỗi tài liệu trả về vẫn nêu đường dẫn mà nó dành cho và đường dẫn đó được ghép từ thư mục này. Ba đường dẫn ở đây không được đánh giá như nhau, và sự phân chia theo những gì quá trình sinh làm với từng đường dẫn. plugin và overlay được đọc, và cả hai đều là tệp bạn đã chọn — một module nằm dưới bất kỳ thư mục nào mà toolchain của nó build vào, và overlay của nó được soạn bên cạnh nó — nên mỗi đường dẫn có thể là tuyệt đối và được đọc ở nơi nó thực sự nằm. outputDir được ghi vào, nên nó tương đối với thư mục gốc của workspace và bị từ chối khi là đường dẫn tuyệt đối hoặc phân giải ra ngoài thư mục gốc, dù theo cách viết hay qua một liên kết — một thư mục chưa được tạo nằm dưới một thư mục liên kết dẫn ra ngoài cũng bị từ chối như chính thư mục đó. Chạy lại trên các đầu vào không thay đổi sẽ tạo ra các thực thể giống hệt nhau từng byte. Lệnh này ghi các thực thể được sinh vào dưới outputDir, bên trong workspace, trừ khi dryRun yêu cầu nhận chúng dưới dạng nội dung. Xem What a plugin change tells you.
  • aggrega/getSchema — JSON Schema cho một loại thực thể hoặc loại hợp đồng, đọc từ bản được biên dịch vào binary đang chạy. kind là token schema viết thường nối bằng gạch ngang — component, aggregate, release, recipe, ir, wasm-provider, v.v. — và nó là tùy chọn, vì nó chọn bạn đang hỏi câu nào trong hai câu hỏi. Chỉ định một kind thì phản hồi mang kind và schema, schema ở dạng một tài liệu JSON chứ không phải một chuỗi chứa tài liệu đó. Không chỉ định thì phản hồi mang kinds và entityKinds: những kind bạn có thể chỉ định, ở hai phạm vi. kinds là mọi token mà binary này có thể được hỏi, theo cùng thứ tự mà aggrega get-schema --list in ra. entityKinds là tập hẹp hơn gồm các kind mà người viết soạn tài liệu, mỗi mục mang token kind để gửi lại, giá trị documentKind đặt vào trường kind: của chính tài liệu, và acceptedBy, cho biết việc xác thực một thực thể, xuất bản và kiểm tra theo tên có chấp nhận tài liệu thuộc kind đó hay không. Xem Which kinds you may offer an author trước khi bạn xây dựng một bộ chọn từ một trong hai tập. Câu trả lời schema và bản liệt kê không bao giờ được kết hợp, nên có thể đọc từ phản hồi xem câu hỏi nào đã được trả lời. Một token không có schema nào tương ứng sẽ bị từ chối kèm toàn bộ tập hợp lệ trong thông báo, nên lỗi gõ được sửa mà không cần gọi lần thứ hai. Lệnh này không lấy gì từ workspace, không liên hệ registry nào và không ghi gì, nên nó trả lời được trong một workspace hoàn toàn trống — chính điều đó khiến nó dùng được để gắn liên kết schema của trình soạn thảo với binary mà trình soạn thảo thực sự đang điều khiển, thay vì với bất kỳ bản schema nào được cài ở nơi khác.
  • aggrega/scaffoldEntity — một tài liệu khởi đầu cho một loại thực thể: đúng các trường mà schema của kind đó yêu cầu, với apiVersion và kind cố định đã được điền sẵn và một giá trị giữ chỗ ở mọi nơi cần giá trị. kind là bắt buộc và là token schema viết thường nối bằng gạch ngang — component, aggregate, release, recipe, manifest, feature, v.v.; aggrega/getSchema khi không có kind cho biết bạn có thể gửi những token nào, và một token không có schema nào tương ứng sẽ bị từ chối kèm tập đó trong thông báo, nên lỗi gõ được sửa mà không cần gọi lần thứ hai. Một client cho người viết chọn kind sẽ đọc entityKinds của phương thức đó, là tập các kind mà một tài liệu có thể được soạn. name là tùy chọn và điền sẵn metadata.name cho các kind có schema yêu cầu trường này. Phản hồi mang kind và skeleton. Xem What a scaffold response gives you, vì câu trả lời là một tài liệu để ghi chứ không phải một tài liệu đã được ghi. Khung tài liệu được suy ra từ cùng schema mà aggrega/getSchema báo cáo, nên cả hai trả lời từ một nguồn. Khi được gửi example thay cho kind, nó ghi một trong các ví dụ chạy được của tài liệu vào một thư mục mới của workspace, như aggrega scaffold --example làm tại terminal; khi chỉ được gửi list: true, nó trả lời bằng mọi ví dụ hiện có và không ghi gì. Cả hai dạng đều cần workspace, nên một yêu cầu cho dạng nào cũng nêu tên workspace trong workspaceRoot, và yêu cầu không nêu tên workspace nào sẽ bị từ chối. dir đặt tên thư mục mới tương đối với thư mục gốc của workspace, và mặc định là tên của ví dụ; một giá trị tuyệt đối, hoặc một giá trị phân giải ra ngoài thư mục gốc — theo cách viết, hoặc qua một liên kết — bị từ chối trước khi bất cứ thứ gì được đọc, và một thư mục chứa bất cứ thứ gì bị từ chối và được giữ nguyên. Câu trả lời cho một danh sách mang examples, mỗi mục có name, level và summary; câu trả lời cho một lần ghi mang example, dir, files — mỗi tệp đã ghi, tương đối với dir — next, các lệnh mà trang của ví dụ đưa ra để build nó, vắng mặt khi trang không đưa ra lệnh nào, và version, phiên bản tài liệu mà ví dụ được đọc từ đó. Các trường của hai dạng được gửi cùng nhau — kind với example, list với example hoặc kind, name với example hoặc list, hoặc dir khi không có example — bị từ chối trước khi bất cứ thứ gì được đọc, bằng chính câu chữ mà công cụ của trợ lý dùng để từ chối chúng. Một lần ghi sẽ lấy gói tài liệu khi máy không có bản sao nào được bước kiểm tra chữ ký của chính workspace chấp nhận, và ghi bên trong workspace — xem Truy cập registry và ghi.
  • aggrega/import — chuyển một mô tả nguồn bên ngoài thành các tệp soạn thảo Aggrega dạng bản nháp, cùng phép chuyển đổi mà aggrega import thực hiện tại terminal. source là bắt buộc và chỉ định tệp hoặc thư mục cần chuyển đổi, dưới dạng đường dẫn tuyệt đối hoặc tương đối với thư mục gốc của workspace — một mô tả do công cụ khác xuất ra nằm ở bất cứ nơi nào bạn đã lưu, nên nó được đọc ở nơi nó thực sự nằm chứ không chỉ bên trong workspace. Một thư mục được đọc như cách aggrega import đọc: các tệp trong đó mà các mẫu tệp do importer khai báo chọn ra, trừ thư mục đầu ra build của workspace là dist/, và giới hạn trong chính nó dù nó nằm ở đâu, nên không liên kết nào bên trong được theo ra ngoài nó. outputDir là tùy chọn và chỉ định thư mục chứa các bản nháp, và nó không mang hợp đồng đó: nó được ghi vào, nên nó là một đường dẫn bên trong workspace, và một giá trị tuyệt đối, hoặc một giá trị phân giải ra ngoài thư mục gốc — theo cách viết, hoặc qua một liên kết, kể cả một thư mục chưa được tạo nằm dưới liên kết đó — sẽ bị từ chối. Bỏ qua nó thì các bản nháp được đặt dưới thư mục gốc của workspace, nơi aggrega import ghi chúng khi không chỉ định đích — kể cả khi dùng dryRun. format chỉ định rõ định dạng nguồn; bỏ qua nó thì định dạng được nhận diện bằng các chữ ký mà các importer khai báo — của catalog trong workspace cũng như của các importer lõi của trình biên dịch — và một nguồn không importer nào nhận diện được, hoặc được nhận diện bởi importer của nhiều hơn một định dạng, sẽ bị từ chối kèm yêu cầu cung cấp format thay vì bị đoán. target chỉ định một capability của provider, chẳng hạn compose hoặc helm — từ mà spec.capability của một Recipe gắn vào — và soạn nháp, bên cạnh các bản nháp của importer, Manifest mà Release được soạn nháp build dựa vào cho provider đó, đúng như aggrega import --target làm: manifest.yaml, ánh xạ mỗi loại component và loại tính năng mà các bản nháp cần — kể cả các loại của một Aggregate trong catalog mà Aggregate được soạn nháp kết hợp — tới Recipe hoặc công thức tính năng của capability đó mà catalog của workspace cung cấp cho nó, theo tên có định danh capability và không có phiên bản: cái duy nhất hiện có, hoặc trong số nhiều cái thì cái được đặt theo tên của loại. spec.manifest của Release được đặt trỏ tới nó; một loại không có cái nào, hoặc có nhiều cái nhưng không cái nào được đặt tên như vậy, được để không ánh xạ kèm một phát hiện warn nêu tên loại đó, và một ánh xạ mà chính importer đã soạn nháp được giữ lại nếu catalog cung cấp nó cho loại và capability đó, nếu không thì bị loại bỏ kèm một phát hiện warn. Một target mà không Recipe nào trong catalog gắn vào sẽ bị từ chối trước khi importer chạy, kèm tên của nó và các capability mà các Recipes của catalog gắn vào, và không có gì được ghi; bỏ qua nó thì không có Manifest nào được soạn nháp — trừ khi dùng sync, khi đó bản nháp được soạn cho target mà bản ghi của lần import trước chỉ định. Một importer lõi mà máy chưa có sẽ được tải về bởi lần import đầu tiên cần nó — xem What an import response tells you. dryRun làm mọi việc mà yêu cầu thông thường làm trừ việc ghi, trả lời bằng các bản nháp dưới dạng nội dung, dành cho client muốn đưa chúng cho người viết xem trước; không có gì được tạo và written để trống. sync cập nhật những gì một lần import trước đã soạn nháp trong outputDir theo nguồn, chỉ thay đổi những gì lần import đó đã ghi, như aggrega import --sync làm; không có nó, một yêu cầu mà các bản nháp sẽ ghi đè lên một Aggregate đã có sẽ bị từ chối. Câu trả lời mang format, outputDir, written, files, drift, diagnostics, decisions và halted. Xem What an import response tells you, vì một nguồn mà importer không thể chuyển đổi hoàn toàn là một câu trả lời thành công chứ không phải một lỗi.
  • aggrega/explainError — những gì trình biên dịch khai báo về điều kiện mà một mã chỉ đến, cùng các mục đã xuất bản hướng dẫn cách sửa khi soạn thảo. code là bắt buộc và nhận một trong hai định danh của điều kiện: mã ngắn mà một chẩn đoán mang trong shortCode, hoặc mã mô tả trong code. Đây là phần diễn giải của một mã mà các chẩn đoán trên giao thức này vốn đã mang, và là cùng câu trả lời mà aggrega explain in ra tại terminal. Câu trả lời luôn mang điều kiện — shortCode, code và message — vì phần đó được khai báo bên trong binary và không cần mạng; entries mang phần hướng dẫn chi tiết đã xuất bản, và note cho biết lý do khi phần đó vắng mặt. Lệnh này tải gói tài liệu về khi máy không giữ bản sao nào mà bước kiểm tra chữ ký của chính workspace chấp nhận — xem Truy cập registry và ghi. Xem Diễn giải một mã mà chẩn đoán mang.
  • aggrega/invalidate — tín hiệu vô hiệu hóa cache từ trình theo dõi tệp của editor.

Thông báo:

  • $/cancelRequest — từ client đến server: dừng yêu cầu đang thực hiện được gửi với id đó. Daemon hủy công việc của yêu cầu đó; một thao tác nhận biết việc hủy tại ranh giới bước kế tiếp chứ không ngay lập tức, nên công việc đang diễn ra vẫn chạy thêm một lúc. Hủy một id không có gì đang chạy là thao tác an toàn, không có tác dụng gì.
  • $/progress — từ server đến client: một thao tác dài đang làm gì trong khi nó thực hiện, trên token mà yêu cầu đã đề nghị được báo cáo. Chỉ được gửi cho yêu cầu có mang token. Xem Theo dõi một thao tác dài.
  • aggrega/shutdown — bắt đầu quá trình dừng có phối hợp: các yêu cầu đang thực hiện được hoàn tất, các yêu cầu mới bị từ chối, rồi daemon thoát.
  • aggrega/publishDiagnostics — một tập chẩn đoán do server đẩy xuống (dùng cho cảnh báo lệch lockfile và trạng thái lúc khởi động). Mỗi mục mang một source cho biết lớp chẩn đoán nào của daemon đã phát sinh nó: aggrega cho phát hiện về các tài liệu đã soạn, aggrega-build cho một khuyến nghị mà bản build phát sinh — mọi khuyến nghị nó phát sinh, tức cùng tập mà aggrega build in ra — và aggrega-lint cho phát hiện về quy ước xuất bản, cùng các phát hiện mà aggrega lint in ra. Trường này luôn có mặt trên mọi mục, nên client có thể nhóm chúng thay vì hiển thị một danh sách lẫn lộn, và không bao giờ phải phân biệt một source vắng mặt với một trong các lớp. Một frame chỉ được gửi cho một tệp khi tập của nó khác với tập mà client này được báo lần gần nhất, nên một yêu cầu tính lại cùng các phát hiện sẽ không gửi gì; frame đầu tiên của một tệp, và frame làm rỗng tập của một tệp, đều là khác biệt và luôn được gửi.

Yêu cầu chính tiến trình dừng lại cũng đến daemon theo cùng điều kiện. Một tín hiệu ngắt từ terminal, hoặc một yêu cầu kết thúc từ trình giám sát hay container runtime, bắt đầu cùng quá trình dừng mà aggrega/shutdown bắt đầu: các yêu cầu đang thực hiện được hoàn tất, các yêu cầu mới bị từ chối, rồi daemon thoát. Yêu cầu thứ hai kết thúc tiến trình ngay lập tức. Client khởi chạy daemon có thể dừng nó theo cả hai cách, và client dừng nó qua giao thức hay client gửi tín hiệu cho nó đều nhận được cùng một quá trình dừng.

Xác thực trực tiếp

Với mỗi aggrega/validate, daemon xác thực bộ đệm của trình soạn thảo theo schema của tài liệu và trả về các chẩn đoán trỏ vào khóa gây lỗi — cùng phán quyết mà một bản build sẽ đưa ra, trên nội dung chưa lưu. Một yêu cầu không gửi content là hỏi về tệp như nó đang có trên đĩa; một content gửi rỗng là một bộ đệm rỗng, không phải yêu cầu về tệp. Một tệp gửi mà không kèm nội dung phải là tệp mà workspace chứa và có thể đọc được — một tệp nằm ngoài workspace, một tệp được truy cập qua một liên kết dẫn ra ngoài workspace, hoặc một tệp không tồn tại sẽ bị từ chối với mã invalid-params. Các thực thể catalog, Aggregates, Manifests và Releases được nhận diện qua apiVersion và kind của chúng. Hai tài liệu không mang phần đầu như vậy — tệp cấu hình workspace .aggrega-config.yaml và lockfile của Release mà yêu cầu nêu tên — được nhận diện qua tên tệp, nên một khóa rác hoặc sai hình dạng trong một trong hai tệp đó cũng được gạch chân trực tiếp. Các tệp không phải tài liệu Aggrega — template của Helm chart, tệp Compose, manifest Kubernetes, và các tệp .lock của hệ sinh thái khác như Cargo.lock hay flake.lock — không nhận chẩn đoán nào; daemon không bao giờ báo cáo về tệp ngoại lai.

Một placeholder còn thiếu được nêu tại khóa của nó, kèm theo giá trị mà nó nhận. Một thực thể catalog thuộc loại mà aggrega validate kiểm tra như một thực thể đơn lẻ cũng được đọc để tìm các giá trị bắt buộc mà nó để là chuỗi rỗng, theo cách đọc mà lệnh đó áp dụng, nên daemon nêu mọi placeholder mà lệnh nêu cho cùng các byte. Mỗi placeholder là một mục: message của nó cho biết khóa là một placeholder còn thiếu, suggest cho biết giá trị nhận gì, và keyPath mang đường dẫn phân cách bằng dấu chấm của khóa. Mục này thay thế phát hiện của chính schema cho giá trị rỗng đó, và mọi phát hiện khác trên tài liệu được báo cáo như phép kiểm tra schema báo cáo. Một placeholder mà schema chấp nhận để rỗng cũng được nêu, dù phép kiểm tra schema không báo cáo gì về nó — capability và implements của một Recipe hay FeatureRecipe đang soạn thảo là những trường hợp bạn sẽ gặp. Khi phép kiểm tra schema cũng từ chối tài liệu, mỗi mục mang mã của phép kiểm tra đó, E0215, còn khi nó chấp nhận tài liệu thì các mục không mang mã nào: cùng các định danh mà báo cáo của lệnh mang cho các byte đó. Một mục được vẽ tại khóa chứa giá trị rỗng, trên dòng mà lệnh nêu nó — kể cả một khóa mà tên của chính nó chứa dấu chấm, như nhãn component.aggrega.ai/type, nơi một phát hiện mà phép kiểm tra schema báo cáo trên khóa đó được vẽ tại khóa bao quanh nó — và keyPath nêu đầy đủ khóa. Điều này đúng dù yêu cầu có nêu một Release hay không, vì đây là câu hỏi mà tài liệu tự trả lời, và một tài liệu còn thiếu giá trị chưa phải là tài liệu được hỏi về các quy ước xuất bản: lớp đó được xóa cho nó, giống như cho một tài liệu có hình dạng bị schema từ chối.

Mỗi yêu cầu nêu Release mà nó liên quan, và daemon không giữ Release nào của riêng nó. Các phép kiểm tra ngữ nghĩa phân giải bao đóng phụ thuộc của Release đó và đọc lockfile của Release đó để lấy các pin — hoặc, với một thực thể catalog, đọc các thư mục catalog mà Release đó build cùng, như đoạn tiếp theo mô tả — nên hai yêu cầu nêu hai Releases được trả lời về Release mà mỗi yêu cầu đã nêu. Không có gì được mang sang giữa chúng: không có Release được chọn nào để thay đổi, và việc đổi Release mà bạn xác thực theo chỉ là một giá trị khác trong yêu cầu tiếp theo chứ không phải điều gì daemon cần được bảo phải quên.

Một thực thể catalog được nêu kèm một Release được kiểm tra như một thực thể đơn lẻ, theo các điều kiện của Release đó. Một file chứa một Component, một Feature, một Recipe, một FeatureRecipe hoặc một Plugin, gửi kèm một release, nhận phép kiểm tra mà aggrega validate <path> --release <release> chạy, trên bộ đệm chưa lưu của trình soạn thảo: các tham chiếu của nó — Component mà một Recipe hiện thực, một thư viện mà một trụ cột tham chiếu — được phân giải qua các thư mục catalog mà cấu hình workspace cấp cho Release đó, nên một tệp có thể sạch theo điều kiện của Release build cùng nó và thất bại theo điều kiện của một Release có các thư mục không chứa thứ nó tham chiếu. Đó là phán quyết mà dòng lệnh và công cụ validate của aggrega mcp đưa ra cho cùng thực thể bên cạnh cùng Release, và giống như chúng, nó không duyệt bao đóng nào và không đọc lockfile nào. Một phát hiện chặn là một mục lỗi theo lời của chính phép kiểm tra và mang các mã của nó, được vẽ trên khóa mà nó nêu trong thực thể và, khi nó không nêu khóa nào, trên khóa kind: của thực thể, như Những gì một mục chẩn đoán mang theo mô tả — trừ khi một bản build đã báo cáo lỗi đó trên tệp, khi ấy mục của bản build là báo cáo duy nhất; một cảnh báo tư vấn mà phép kiểm tra nêu ra khi đọc catalog là một mục cảnh báo đứng trước nó; một phép kiểm tra sạch trên các thư mục đều tồn tại không trả về mục nào. Một assertion thất bại — một assertion gọi fail, trong Recipe hoặc trong Component mà nó hiện thực — ở đây không phải phát hiện chặn mà là một mục cảnh báo, theo lời của phép kiểm tra và mang các mã của nó, kết thúc bằng câu A Release must satisfy this assertion before a build of it can pass., và được vẽ tại nơi phát hiện chặn sẽ được vẽ: assertion của một Recipe trên chính khóa của assertion đó dưới assertions, assertion của một Component trên khóa kind: của Recipe. Giống như một phát hiện chặn, nó nhường chỗ cho mục của một bản build báo cáo cùng lỗi trên tệp. Phép kiểm tra dựng thực thể quanh các placeholder và giá trị mặc định của schema thay vì các giá trị mà một Release đặt, nên nó không thể phân biệt một assertion đang chờ một Release với một assertion bị hỏng, và để lại phán quyết cho một bản build, vốn báo cáo cùng assertion đó là lỗi (một assertion thất bại là một cảnh báo). Một thư mục mà cấu hình workspace liệt kê cho Release nhưng không phải là thư mục — chẳng hạn không có gì tồn tại ở đó — khiến phép kiểm tra dừng lại tại đó: tệp mang một mục lỗi duy nhất thay cho phán quyết của phép kiểm tra, tức là lời từ chối mà mọi lệnh đưa ra cho thư mục đó, nêu mục ấy, tệp cấu hình và dòng liệt kê nó, cùng thiết lập (Nơi đọc các thực thể cục bộ). Một release không nêu tệp nào, hoặc nêu một thư mục, được trả lời trên tệp bằng câu mà dòng lệnh dùng để từ chối nó, thay vì được kiểm tra theo điều kiện của workspace. Những gì một bản build của một thực thể không thể thay thế được đánh giá như dòng lệnh đánh giá, và những gì dòng lệnh bỏ qua hoặc không kiểm tra thì ở đây không trả về mục nào — xem những gì tính đúng đắn của thực thể đơn lẻ không kiểm tra, và, với một Recipe có template đọc một giá trị mà chỉ một cạnh topology hoặc một thông tin xác thực được gắn mới cung cấp, tính đúng đắn của thực thể đơn lẻ. Aggregate của chính Release, một Manifest, một Release và một thư viện không được kiểm tra từng cái một, vì phép kiểm tra thực thể đơn lẻ không nhận các loại đó; chúng giữ các phép kiểm tra bao đóng ở trên. Một bộ đệm chứa nội dung Workload được đọc như YAML không phải tài liệu Aggrega, vì nội dung đó được viết bên trong trường workload: của một Recipe hoặc FeatureRecipe và được kiểm tra ở đó, nơi nó nằm; dòng lệnh và công cụ validate, khi được trao một tệp Workload theo đường dẫn, tự kiểm tra hình dạng của nó.

Việc nêu tên một Release là tùy chọn, và câu trả lời cho biết bạn đã yêu cầu loại nào trong hai loại. Nêu tên một Release và bạn nhận được mọi thứ ở trên. Không nêu tên Release nào và bạn nhận được các kiểm tra mà một tài liệu tự trả lời được — nó có phân tích cú pháp được không, hình dạng của chính nó có chấp nhận được không, và, với một thực thể danh mục thuộc loại được xác thực như một thực thể đơn lẻ, những placeholder nào nó còn thiếu — mà không phân giải Release nào, không duyệt closure nào và không đọc lockfile nào; khi đó câu trả lời mang checked: "document". Nêu tên một Release thì khóa đó vắng mặt, vì câu trả lời đó là phán quyết đầy đủ của phương thức và không có gì cần giới hạn.

Hãy đọc khóa này thay vì suy ra từ các chẩn đoán, vì hai câu trả lời có thể trông giống hệt nhau. Một tài liệu hợp lệ được xác thực mà không có Release sẽ trả về một danh sách chẩn đoán rỗng, đúng như một phán quyết đầy đủ sạch lỗi trả về, nên checked là thứ duy nhất phân biệt “không có gì sai” với “không có gì cần đến Release được xem xét”. Một hệ quả suy ra từ cùng quy tắc này: một lockfile được nhận diện qua mối liên hệ với Release mà yêu cầu nêu tên, nên một yêu cầu không nêu tên Release nào sẽ không nhận diện lockfile nào và không báo cáo gì về lockfile.

Một workspace không chứa Release nào vẫn được trả lời thay vì bị từ chối, và đó là điều giữ cho phần còn lại của daemon dùng được ở đó. Việc xác thực là thứ nạp bộ đệm phân tích cú pháp mà mọi thao tác tệp khác đọc, nên một kho chỉ có danh mục, một scaffold chỉ có một Aggregate hay một thư mục nháp vẫn có hover, completion, go-to-definition, references, implementations và các chẩn đoán đã lưu đệm. Nếu từ chối, tất cả những thứ đó sẽ mất theo, đúng trong những workspace mà client không có Release nào để nêu tên.

Một mục chẩn đoán mang những gì

Mỗi mục tự định vị bằng line và column, cả hai đều đếm từ 1 theo bảng mã vị trí đã thỏa thuận lúc bắt tay, và thêm end_line cùng end_column khi nó trải trên cả một token. message là văn bản client hiển thị cho người dùng, severity phân loại nó, và source cho biết lớp nào của daemon đã đưa ra nó, như đã mô tả ở trên.

Các lớp trả lời những câu hỏi khác nhau về cùng một tệp, nên mỗi lớp có thể có một mục trên cùng một dòng mà không mục nào trùng lặp với mục kia: một mục nói việc triển khai không đúng, mục khác nói thực thể không thể xuất bản. Một client hiển thị chúng thành một danh sách sẽ báo cáo một vấn đề hai lần, và việc đọc source là thứ phân biệt chúng.

Vị trí của một mục phụ thuộc vào việc nó nói về điều gì, không phụ thuộc vào lớp nào đưa ra nó. Một phát hiện về điều tác giả đã viết được đặt trên khóa mà họ viết điều đó dưới đó, để trình soạn thảo vẽ nó ở chỗ cần sửa. Một phát hiện về hình dạng của topology được triển khai nêu tên một component và một khóa phân phối thay vì một dòng — đó là tọa độ trong topology được triển khai, không phải trong tài liệu — nên nó được vẽ trên khóa kind: của tài liệu và nêu các tọa độ của nó trong thông điệp. Cả hai loại đều đến lớp aggrega-build, vì một bản build đưa ra cả hai. Một sự từ chối mà bản build đưa ra trong khi render cũng đến lớp đó, trên tài liệu mà chính sự từ chối chỉ tới — một Workload không thỏa các kiểm tra của nó trên khóa workload của Recipe của nó, một assertion thất bại của Recipe trên chính khóa của assertion đó, một mục mà việc kết hợp đồ thị từ chối trên khóa mà Release hoặc Aggregate đã viết nó dưới đó, và mỗi phát hiện của một sự từ chối gộp nhiều phát hiện trên tài liệu và khóa riêng của nó — và, khi nó không chỉ tới tài liệu nào, trên khóa kind: của Aggregate; Một sự từ chối đưa ra khi render mô tả điều này. Vì vậy client đặt mọi mục theo chính line và column của nó và không bao giờ suy ra vị trí từ lớp.

Một phát hiện không nêu tên khóa nào tài liệu chứa sẽ được vẽ trên khóa nêu tên tài liệu. Một phát hiện mà các kiểm tra riêng của tài liệu đưa ra về nội dung nó nói, phát hiện của kiểm tra thực thể đơn lẻ, và một cảnh báo hay một sự từ chối mà bản build đưa ra đều được vẽ trên khóa chúng nêu tên; khi chúng không nêu tên khóa nào, hoặc nêu một khóa tài liệu không chứa, chúng được vẽ trên khóa kind: của tài liệu, hoặc trên metadata.name của nó khi nó không khai báo kind:, và chỉ ở đầu tệp khi tài liệu không khai báo cả hai hoặc không phân tích cú pháp được. Một tài liệu thường mở đầu bằng một chú thích — mọi tệp danh mục đều mang một header giấy phép — và một mục vẽ trên dòng đầu sẽ nằm trên chú thích đó và trông như một lỗi trong nó, trong khi danh tính của chính tài liệu là một dòng do tác giả viết. Một mục nói về điều gì khác ngoài nội dung tài liệu được đặt ở đầu tệp: một mục Dependencies: về các phụ thuộc của Release, một giai đoạn dừng lại mà không nêu tên gì trong tài liệu, một lockfile bị lệch, một tham chiếu mà việc render phải từ chối, một Release không tải được — và một mục aggrega-lint mà quy tắc của nó không tính được dòng nào cũng vậy. Khi vị trí được nêu ra thay vì được vẽ, một phát hiện không nêu tên khóa vẫn không có khóa: câu trả lời lỗi của một sự từ chối không nêu tên khóa chỉ mang tài liệu trong data của nó.

Một mục được xuất bản trên tài liệu nào cũng suy ra từ cùng quy tắc này. Một lần xác thực có nêu tên Release trả lời cho Aggregate của Release đó, chính Release, tài liệu của mỗi module mà Aggregate nhập vào, và Manifest mà Release nêu tên. Một phát hiện được định vị trong Release — sự từ chối một mục mà Release viết trên một kết nối của một component, sự định cỡ nó cho kết nối đó, một attachment nó điền hoặc định cỡ ở đó, một kết nối nó nối, một Feature chỉ Release gắn vào một component hay một boundary, hoặc infra nó cấp cho một attachment — được xuất bản khi tài liệu Release được xác thực, trên khóa trong Release đã viết nó, và hoàn toàn không trên Aggregate. Một phát hiện được định vị trong tài liệu riêng của một module — sự từ chối điều mà một component của module khai báo, một socket mà các attachment của nó nối, các giá trị của nó hoặc các giá trị trên các kết nối riêng của nó — được xuất bản khi tài liệu của module đó được xác thực, trên khóa ở đó đã viết nó, và hoàn toàn không trên Aggregate. Một phát hiện về bảng ánh xạ của Manifest — một mục ánh xạ một kiểu tới một Recipe hoặc FeatureRecipe không triển khai kiểu đó, một mục có pin phiên bản không phân tích được, hoặc một kiểu được ánh xạ có chuỗi extends không lần theo được — được xuất bản khi Manifest đó được xác thực, trên khóa của mục ánh xạ mà nó nói tới, và hoàn toàn không trên Aggregate; khi văn bản đang mở của Manifest không viết mục đó — một mục nó kế thừa qua extends của chính nó, hoặc một mục mà một chỉnh sửa chưa lưu đã xóa — phát hiện được xuất bản ở dòng đầu tiên của Manifest. Mọi phát hiện khác mà việc xác thực Release đó đưa ra được xuất bản trên Aggregate, trong đó có các phát hiện ở cấp phụ thuộc không nêu tên tài liệu nào trong workspace của bạn — một tham chiếu hoặc plugin đã bị rút lại, một Component hoặc Feature trong catalog có chuỗi extends không phân giải được hoặc có schema không hợp lệ, một plugin cổng không khớp với bản ghi tin cậy, một instance component mà không ánh xạ nào phân giải được, một Recipe hoặc FeatureRecipe có trình cung cấp không render được một loại đầu vào mà nó khai báo, và các khuyến nghị về chồng lấn schema pillar và thu hẹp khi extend. Vì vậy một phát hiện về điều người vận hành đã viết sẽ xuất hiện khi Release đang mở, một phát hiện về điều một module khai báo sẽ xuất hiện khi module đó đang mở, và một phát hiện về một ánh xạ sẽ xuất hiện khi Manifest đang mở, dù giai đoạn nào của bản build đưa ra nó; một trình soạn thảo xác thực mọi tài liệu đang mở theo Release sẽ hiển thị từng phát hiện ở đó. Một Release mà các phụ thuộc hoàn toàn không phân giải được sẽ không đưa ra phát hiện nào trong số đó, và việc không phân giải được là một mục ở đầu tài liệu của chính Release và của mọi tài liệu khác được xác thực theo nó mà daemon nhận diện, như Xác thực trực tiếp mô tả, và không kiểm tra như một thực thể đơn lẻ — Aggregate của nó, Manifest của nó, một library, một Release khác, cấu hình workspace — có tiền tố Dependencies: và mang lời giải thích của chính quá trình phân giải về điều đã chặn nó. Trên tài liệu của chính Release, mục đó chỉ là lời giải thích đó. Trên mọi tài liệu khác, trước hết nó nói rằng tài liệu được kiểm tra theo Release đó và nêu tên Release như một yêu cầu nêu tên nó — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved: rồi đến lời giải thích — vì không có gì trong tài liệu đó cho biết nó được kiểm tra theo Release nào: một trình soạn thảo kiểm tra mọi tài liệu đang mở theo một Release được chọn sẽ đặt mục đó lên các tài liệu chẳng liên quan gì đến Release đó, và cái tên cho bạn biết sự lựa chọn là nguyên nhân. Một tệp daemon không nhận diện thì không mang mục như vậy, dù Release nào được nêu tên cùng nó.

Một câu trả lời mang mọi lớp đang có trên tệp, dù việc xác thực đi được bao xa. Câu trả lời aggrega/validate là toàn bộ trạng thái hiện tại của tệp: những gì lần xác thực này tìm thấy, các mục aggrega-build mà một bản build, một bản xem trước hay một yêu cầu đồ thị đã xuất bản trên tệp, và các phát hiện về quy ước xuất bản của nó, mỗi thứ dưới source riêng. Một lần xác thực dừng ở buffer — buffer không phân tích cú pháp được, hoặc một tài liệu có envelope bị schema từ chối — cũng trả lời như vậy: nó báo cáo phát hiện của chính nó và giữ nguyên mọi mục build trên tệp, vì nó không biết thêm gì về bản build. Vì vậy client có thể thay thế những gì nó giữ cho tệp, theo từng lớp, từ bất kỳ câu trả lời nào.

Một lỗi chỉ được báo một lần. Việc xác thực riêng của một tài liệu và một bản build có thể tìm thấy cùng một lỗi trong tài liệu đó: phép kiểm tra thực thể đơn lẻ render một Recipe mà bản build cũng render, việc xác thực kết hợp đồ thị mà bản build kết hợp, và một Release có các phụ thuộc không phân giải được thì thất bại ở cả hai. Trong khi một bản build báo một lỗi như vậy trên một tài liệu, việc xác thực tài liệu đó không báo lại lần thứ hai: một mục aggrega nêu cùng một điều kiện — cùng code — với lời từ chối của bản build trên cùng tài liệu, được đặt tại cùng khoảng hoặc không tại khóa nào của riêng nó — được vẽ ở nơi một mục không nêu khóa nào được vẽ, hoặc ở đầu tệp — sẽ bị loại khỏi mọi câu trả lời và mọi lần công bố cho tài liệu đó, và báo cáo của bản build đứng một mình. Báo cáo của bản build là mục của lời từ chối trên lớp aggrega-build; hoặc, với aggrega/build, aggrega/buildPreview hay aggrega/irGraph bị từ chối với 1004 vì một phụ thuộc không phân giải được, thì chính câu trả lời đó — thứ không gì công bố — trên tài liệu mà data.file của nó nêu, nếu không thì data.lockfile của nó, nếu không thì Release mà yêu cầu đã nêu, trong đó câu trả lời mới nhất như vậy cho một Release là câu trả lời được tính. Việc xác thực giữ lại những gì nó tìm thấy: khi không còn bản build nào báo lỗi đó — lần chạy tiếp theo công bố lớp không có lỗi đó, câu trả lời build, preview hoặc graph tiếp theo cho Release đó là bất kỳ thứ gì khác, hoặc một client kết nối mà chưa nhận câu trả lời 1004 như vậy — mục riêng của tài liệu lại được báo, và ở nơi chưa có bản build nào chạy thì không có gì bị loại. Một mục aggrega được đặt tại một khóa mà không lời từ chối build nào nằm ở đó thì vẫn được giữ, ngay cả khi nó nêu cùng điều kiện, vì nó có thể là một lỗi thứ hai thuộc loại đó mà bản build chưa báo.

code là một mã ổn định, máy có thể so khớp, cho điều mà mục báo cáo, để client có thể rẽ nhánh theo nó mà không phải so khớp văn bản thông báo. Một khóa mang mã bất kể ai gán nó, và source cho bạn biết bạn đang giữ loại nào, vì các lớp đặt tên mọi thứ theo các bộ từ vựng khác nhau.

  • Trên một mục aggrega — một phát hiện về các tài liệu được soạn — mã là chuỗi mà điều kiện được đăng ký dưới đó, viết dưới dạng gói khai báo rồi đến quy tắc ở dạng kebab-case. Đó là cùng giá trị mà một chương trình Go đọc bằng CodeOf, có dạng thức và bề mặt so khớp được mô tả trong tài liệu tham khảo error-sentinels.
  • Trên một mục aggrega-build — một cảnh báo mà bản build đưa ra — mã là bất cứ thứ gì nơi đưa ra đã gán, và lớp này mang các cảnh báo từ hai bộ từ vựng khác nhau vì một bản build đưa ra cảnh báo về hai loại thứ khác nhau. Một cảnh báo về hình dạng của topology được triển khai mang một mã lớp, chẳng hạn unsupported-field, được gán ở bất cứ nơi nào nó được đưa ra, dù đó là một plugin render hay chính quá trình render; một mã lớp đặt tên cho một lớp cảnh báo chứ không phải một điều kiện được đăng ký, nên nó không có hàng nào trong tài liệu tham khảo sentinel, và tài liệu tham khảo cảnh báo mô tả lớp unsupported-field cùng cờ làm nó im lặng. Một cảnh báo về các tài liệu được soạn — một tên chỉ cách một tên đã khai báo một lần sửa, một tham số không gì đọc — mang chuỗi mà điều kiện của nó được đăng ký dưới đó, cùng dạng như một mục aggrega và có một hàng trong tài liệu tham khảo sentinel. Dù thế nào, mã nêu phát hiện là gì chứ không phải ai tìm ra nó, nên một lớp duy nhất đến với bạn dưới một mã dù có bao nhiêu nơi đưa ra nó, và việc đọc mã thay vì lớp mới cho bạn biết bạn đang giữ loại nào trong hai loại. Lời từ chối mà bản build dừng lại khi render là mục duy nhất ở đây không phải là cảnh báo, và nó mang chuỗi mà điều kiện của nó được đăng ký dưới đó theo cùng cách.
  • Trên một mục aggrega-lint — một phát hiện về các quy ước xuất bản — mã là danh tính của phát hiện: danh tính của quy tắc lint đã tạo ra nó, hoặc, với một phát hiện không nêu tên quy tắc nào — điều mà một linter của riêng bạn có thể báo cáo dưới một mã của riêng nó — thì chính là mã đó. Đó là định danh mà aggrega lint in trên hàng của phát hiện, sau mã ngắn nếu có, và là giá trị mà aggrega lint --output json mang cho cùng phát hiện đó, dưới dạng ruleId, hoặc dưới dạng code với một phát hiện không nêu tên quy tắc nào. Một phát hiện giữ một danh tính trên mọi bề mặt, nên một client nhóm hoặc ẩn một quy tắc trong trình soạn thảo cũng nhóm và ẩn cùng quy tắc đó trong terminal. Mỗi quy tắc của bộ quy tắc publishing-linter mà Aggrega khai báo được đăng ký như một điều kiện dưới danh tính đó, nên nó được liệt kê trong bảng mọi điều kiện dưới mã ngắn mà aggrega lint in ở đầu hàng của cùng phát hiện và aggrega lint --output json mang trên đó dưới dạng shortCode. Một quy tắc từ linter của riêng bạn mà Aggrega không khai báo thì không nêu tên điều kiện đã đăng ký nào, và một phát hiện không nêu tên quy tắc nào cũng vậy, ngay cả khi mã của chính nó viết đúng danh tính của một quy tắc mà Aggrega khai báo — nên cả hai đều không được liệt kê ở đó. Các quy tắc được mô tả trong aggrega lint — tài liệu tham chiếu.

Dù là lớp nào, khóa trả lời một câu hỏi — đây là gì, theo cách máy có thể so khớp — nên một tiện ích mở rộng trình soạn thảo làm nổi bật, nhóm hoặc ẩn một lớp phát hiện sẽ dựa vào mã, và vẫn hoạt động khi cách diễn đạt của thông báo thay đổi.

Lưu ý đối tượng nào mang cái nào: đây là một chuỗi trên một mục chẩn đoán, khác với code dạng số trên phong bì lỗi JSON-RPC được mô tả trong Mã lỗi bên dưới. Một phản hồi mang cái này hoặc cái kia, không bao giờ cả hai ở cùng một chỗ.

Khóa bị bỏ qua ở nơi không thứ gì tạo ra mục đã gán mã, và loại nào cũng có trường hợp đó. Một buffer mà không trình phân tích YAML nào đọc được sẽ báo văn bản riêng của trình phân tích và không có mã, vì không có điều kiện nào của riêng Aggrega đứng sau nó; một giai đoạn báo một thất bại mà không nêu điều kiện cũng không có mã để báo; và một cảnh báo mà nơi đưa ra không gán mã thì đến mà không có mã. Vì vậy hãy coi code là tùy chọn, giống như end_line và end_column, và chỉ rẽ nhánh theo nó khi nó có mặt. Mã là thứ một chẩn đoán báo cáo chứ không bao giờ là thứ chọn ra một chẩn đoán: không yêu cầu nào nhận mã, và việc viết lại một mã vào code của riêng bạn chỉ cho bạn một chuỗi chứ không phải một cách để so khớp.

Định danh mà chương trình đối khớp, và định danh mà con người trích dẫn

Một điều kiện mang hai định danh, và chúng dành cho hai kiểu người đọc khác nhau. code là định danh đã nói ở trên: có tiền tố và nối bằng gạch ngang, để một chương trình rẽ nhánh theo nó đọc lên đúng với ý nghĩa của nó. shortCode là chữ E kèm bốn chữ số — E0164 — và đó là định danh mà một con người có thể đọc to, gõ vào ô tìm kiếm hoặc dán vào một issue. Cả hai cùng chỉ một điều kiện và không cái nào là dạng viết tắt của cái kia.

Dùng định danh nào tùy vào ai đang đọc. Hãy đối khớp theo code trong extension của bạn; hãy hiển thị shortCode cho tác giả. Một extension chỉ hiển thị code sẽ để người đọc cầm một định danh dành cho chương trình, còn một extension đối khớp theo shortCode là đang đối khớp theo một con số không nói gì về điều kiện. Sự phân chia đó là lý do cả hai cùng được gửi thay vì chỉ một.

codeDescription là nơi điều kiện được công bố, được mang dưới dạng { "href": … }, tức cấu trúc riêng của giao thức cho một tham chiếu cần mở để tìm hiểu thêm về một chẩn đoán. Một trình soạn thảo hiểu giao thức sẽ biến nó thành một lựa chọn “tìm hiểu thêm” mà không cần được dạy gì về Aggrega, và không client nào cần giữ một bản sao các phần giải thích. Địa chỉ này trỏ tới danh sách đã công bố của mọi điều kiện, nơi mục ứng với một shortCode nêu tên điều kiện và dẫn tiếp tới phần hướng dẫn từng bước cách sửa khi soạn thảo.

Bản thân phần văn bản giải thích không nằm trên mục, và đó là chủ ý. Một chẩn đoán được phát ra ở mỗi lần chỉnh sửa, nên nếu phần giải thích đi kèm mỗi chẩn đoán thì cùng những đoạn văn đó sẽ bị công bố lại ở mỗi lần gõ phím cho một người đọc thường đã đọc chúng rồi. Client nào muốn có văn bản thì yêu cầu một lần, bằng aggrega/explainError bên dưới; client nào có thể theo một liên kết thì không cần cả hai.

Cả hai khóa có mặt đúng khi mục nêu tên một điều kiện đã đăng ký, và cùng vắng mặt trong mọi trường hợp khác. Điều quyết định chúng là thứ đứng sau mục chứ không phải layer nào đã công bố nó, vì vậy hãy đọc các khóa thay vì đọc layer:

  • Một mục nêu tên một điều kiện đã đăng ký mang cả ba. shortCode phân giải được, và tham chiếu trỏ tới danh sách mà nó phân giải trong đó.
  • Một mục có mã chỉ một lớp chỉ mang riêng code. Lớp của một cảnh báo khi render, và định danh của một phát hiện về quy ước từ một linter của riêng bạn — một quy tắc mà Aggrega không khai báo, hoặc mã mà một phát hiện không nêu tên quy tắc nào mang theo — là những định danh thực sự mà bạn có thể nhóm và ẩn theo, và không cái nào là một điều kiện đã đăng ký — nên không có con số nào để trích dẫn và không có gì ở địa chỉ kia mô tả chúng. Nếu vẫn gửi một tham chiếu thì đó sẽ là một liên kết mở ra một trang không nói về vấn đề của người đọc, đó là lý do không tham chiếu nào được gửi. Đây là dạng thông thường trên layer aggrega-build, dù một cảnh báo build có nêu tên một điều kiện đã đăng ký vẫn mang cả ba như mọi mục khác. Trên layer aggrega-lint, dạng thông thường là bộ đầy đủ: một quy tắc thuộc bộ quy tắc publishing-linter mà Aggrega khai báo là một điều kiện đã đăng ký, nên phát hiện của nó mang cùng shortCode mà aggrega lint in ở đầu dòng của phát hiện, cùng với tham chiếu bên cạnh.
  • Một mục không nêu tên gì thì không mang định danh nào cả.

Vì vậy chỉ từ các khóa là có thể phân biệt ba trường hợp: không có code nghĩa là không có gì để nêu tên, một code không có shortCode bên cạnh nghĩa là một định danh không phân giải xa hơn được, và bộ đầy đủ nghĩa là một định danh có chỗ để đọc về nó. Hãy coi hai khóa mới là tùy chọn giống như code, và chỉ đưa cho người đọc thứ gì đó để mở khi codeDescription có mặt.

Mở rộng một mã mà chẩn đoán mang theo

aggrega/explainError biến một trong hai định danh của một điều kiện thành những gì trình biên dịch khai báo về nó và các mục đã công bố hướng dẫn cách sửa khi soạn thảo. Đó là cùng phép mở rộng mà aggrega explain thực hiện ở terminal và công cụ explain-error thực hiện cho một trợ lý, và cả ba trả lời từ cùng một nơi, nên một mã được mở rộng ở đây và cùng mã đó được mở rộng ở nơi khác là một câu trả lời duy nhất chứ không phải ba câu trả lời tình cờ trùng nhau.

code là bắt buộc và nhận một trong hai định danh — shortCode mà một chẩn đoán mang theo, hoặc code bên cạnh nó — vì một client đang giữ một trong hai không có cách nào lấy được cái kia mà không hỏi. Một giá trị rỗng bị từ chối kèm theo nêu rõ cần gửi gì.

Câu trả lời luôn mang shortCode, code và message: hai định danh của điều kiện và câu mở đầu của mọi chẩn đoán nêu tên nó. Những thứ này được khai báo bên trong tệp nhị phân, nên chúng có mặt mà không cần mạng và không cần cache, đó là điều cho phép một workspace không có tài liệu vẫn được trả lời. reference là cùng địa chỉ mà codeDescription của một chẩn đoán mang theo, dành cho client muốn đưa người đọc tới tài liệu thay vì hiển thị văn bản.

entries mang phần hướng dẫn từng bước đã công bố, mỗi mục gồm heading mở đầu nó và body bên dưới, theo thứ tự mà chính tài liệu ghép chúng với điều kiện. Nó bị bỏ qua khi không thể thêm phần hướng dẫn, và khi đó note cho biết lý do: trang đã công bố chưa ghi mục nào cho điều kiện này, hoặc workspace này không đọc được tài liệu — máy không có bản sao nào, hoặc chỉ có một bản mà bước kiểm tra chữ ký của workspace từ chối. Dù thế nào, điều kiện phía trên vẫn giữ nguyên — câu trả lời không phải là một lỗi, và client hiển thị những gì đã nhận cùng ghi chú bên cạnh. entries và note không bao giờ cùng có mặt.

Một mã không phân giải được bị từ chối thay vì được trả lời bằng một điều kiện có mọi trường đều rỗng, và mỗi lần từ chối cho biết đó là trường hợp nào: một mã không có điều kiện nào được đăng ký dưới nó, một con số từng chỉ một điều kiện và sẽ không bao giờ chỉ điều kiện khác, hoặc một mã mà tệp nhị phân này không khai báo trong khi hoàn toàn không đọc được danh sách đã công bố — trường hợp cuối để ngỏ cả hai cách khắc phục, vì một danh sách công bố cho phiên bản khác có thể nêu tên một điều kiện mà tệp nhị phân này không khai báo.

Tài liệu được đọc từ gói được cache cho workspace mà yêu cầu nêu tên, được tải về ở lần dùng đầu tiên khi chưa có, và đó là thứ duy nhất mà yêu cầu này cần truy cập registry — xem Truy cập registry và ghi dữ liệu. Không có gì được ghi vào workspace. Không lần xác thực nào kích hoạt nó: việc mở rộng chỉ xảy ra vì một yêu cầu đã đòi nó, nên registry không bao giờ bị truy cập trong khi một tài liệu đang được xác thực hoặc kiểm tra.

Công bố các quy ước, theo yêu cầu và ở mỗi lần chỉnh sửa

Daemon trả lời hai câu hỏi khác nhau về một thực thể catalog, và đó là các câu hỏi mà aggrega validate và aggrega lint trả lời trong terminal: liệu việc triển khai có đúng không, và liệu thực thể có công bố được theo các quy ước của catalog không. Một lần xác thực luôn trả lời câu hỏi thứ nhất. Nó chỉ trả lời câu hỏi thứ hai khi bạn yêu cầu.

aggrega/lint yêu cầu điều đó một cách trực tiếp. Gửi entity cho một thực thể catalog, release cho mọi thực thể mà bao đóng phụ thuộc của Release đó chạm tới, hoặc không gửi cả hai để kiểm tra mọi thực thể trong các thư mục catalog đã cấu hình — ba phạm vi mà lệnh có. Gửi cả entity lẫn release là nêu tên hai đối tượng khác nhau và bị từ chối. Câu trả lời mang checked, số tài liệu thực thể mà lần chạy đã bao quát, và files, các phát hiện được nhóm theo tài liệu mà mỗi phát hiện liên quan và sắp xếp theo đường dẫn, các mục của mỗi tệp có dạng chẩn đoán đã mô tả ở trên. halted cho biết phán quyết của chính lần chạy có từ chối việc công bố hay không.

Không gửi cả hai sẽ kiểm tra toàn bộ catalog theo cách aggrega lint làm khi không có đối số. Một workspace mà cấu hình không đưa ra thư mục catalog Release riêng nào được kiểm tra một lần, trên các thư mục của chính nó, và câu trả lời là câu trả lời đã mô tả ở trên. Một workspace nêu tên các Releases dưới workspace.releases được kiểm tra một lần cho mỗi Release trong đó, trên các thư mục mà Release đó đọc, và không bao giờ trên tất cả chúng cùng lúc — nên các biến thể catalog được giữ song song, mỗi biến thể cho một Release, đều được kiểm tra theo các điều kiện của Release đọc chúng. Khi đó câu trả lời còn mang passes, một mục cho mỗi lượt: releases, các Releases mà lượt đó được chạy cho, mỗi cái tương đối với gốc workspace, với các Releases đọc cùng thư mục dùng chung một mục; catalogDirs, các thư mục nó đã đọc, được viết theo cách files viết một đường dẫn, và rỗng đối với một Release không đọc thư mục nào, điều này được báo cáo thay vì làm hỏng các lượt khác; và các số đếm cùng files riêng của lượt đó, là thứ cho biết một phát hiện được tìm thấy cho Release nào. checked, các số đếm và files bao quanh chúng bao quát mọi lượt cộng lại, nên một client không đọc passes vẫn đọc được toàn bộ lần chạy. Một lần chạy mà không lượt nào có thư mục để đọc sẽ bị từ chối thay vì được trả lời như một catalog sạch.

Đặt prePublish cùng với entity để so sánh thực thể đó với phiên bản đã công bố trước đó của nó và phân loại mức tăng phiên bản được đề xuất so với phiên bản đó. Đây là chế độ duy nhất ở đây chạm tới một registry, và nó chạy vì yêu cầu đã nêu tên nó: điều cho phép một thao tác vươn ra ngoài là việc một bên gọi đã yêu cầu nó. Nó chỉ có ý nghĩa khi đi cùng entity, nên prePublish không có thực thể sẽ bị từ chối.

aggrega/lint không công bố gì vào phiên làm việc. Nó trả lời về đối tượng nó được giao, và việc ghi các phát hiện của nó vào danh sách vấn đề của trình soạn thảo sẽ thay thế những gì một lần xác thực đã công bố cho các tệp mà yêu cầu không hề bao quát. Không có gì được ghi xuống đĩa ở bất kỳ chế độ nào.

serve.lint_on_validate chạy cùng các quy tắc ở mỗi lần xác thực, và nó tắt trừ khi bạn bật nó. Bật nó trong .aggrega-config.yaml, trong workspace có các thực thể mà bạn muốn nhận lời khuyên:

serve:
lint_on_validate: true

Không có flag cho việc này, vì câu hỏi nó trả lời là về nội dung riêng của một workspace và người có câu hỏi đó là người đang soạn workspace chứ không phải người đã khởi chạy daemon. Khi bật, một lần xác thực thực thể catalog cũng công bố các phát hiện về quy ước dưới nguồn aggrega-lint; khi tắt — mặc định — một lần xác thực chỉ báo cáo các lớp về tính đúng đắn và không phát hiện quy ước nào đến được bạn. Một phiên trình soạn thảo không nói gì về việc một thực thể có công bố được hay không cho tới khi bạn yêu cầu lớp đó.

Ba điều luôn đúng trên lớp đó bất kể khóa nói gì. Chỉ chế độ đọc nội dung cục bộ được chạy, nên không registry nào được tham khảo, không gì được tải về và không gì được ghi; phép so sánh trước khi công bố được thực hiện bằng cách gửi aggrega/lint với prePublish, không bao giờ bằng một lần xác thực, vì một phép kiểm tra chạy ở mỗi lần chỉnh sửa chính là nơi không được chạm tới registry. Các quy tắc được đánh giá trên buffer mà yêu cầu mang theo chứ không phải tệp trên đĩa, nên một tên bạn sửa sẽ ngừng bị báo cáo trước khi bạn lưu. Và các phát hiện là tư vấn — một tài liệu có chúng vẫn xác thực được, và Release của nó vẫn phân giải và render được — nên nó thêm một lớp và không bao giờ là một sự từ chối.

Khóa này chỉ kiểm soát lớp đó và không gì khác. aggrega/lint trả lời bất cứ điều gì nó được hỏi dưới cả hai giá trị, vì bên gọi gửi nó đã yêu cầu phép kiểm tra theo tên.

Chỉ những loại được công bố lên một catalog mới được kiểm tra, vì đó là điều các quy ước nói đến. Các tài liệu không phải nội dung catalog — trong đó có một Aggregate và một Release — được bỏ qua, và YAML hoàn toàn không phải tài liệu Aggrega cũng vậy. Đó là điều giữ cho một phiên làm việc im lặng về những tài liệu mà tác giả dành phần lớn thời gian làm việc.

Cách viết một đường dẫn được báo cáo

Khi một câu trả lời nêu tên một tài liệu mà daemon đã định vị giúp bạn, một quy tắc duy nhất quyết định cách viết đường dẫn đó: tương đối so với gốc workspace khi tài liệu nằm bên trong nó, và là đường dẫn tuyệt đối khi không nằm bên trong. Điều đó bao gồm file trên định danh của một thực thể, file trên định nghĩa của một thực thể, và file làm khóa cho mỗi nhóm trong một câu trả lời lint. Cả hai cách viết đều là đường dẫn bạn có thể mở — cách thứ nhất so với gốc bạn đã chỉ định, cách thứ hai nguyên như nó là — và không cách nào bị để trống chỉ vì vị trí của tài liệu.

Nửa sau của quy tắc là điều mà một thư mục catalog được cấu hình cần đến. Một workspace có thể trỏ đến các thư mục catalog ở bất kỳ đâu trên máy, và một tài liệu trong đó cũng thật như một tài liệu dưới gốc. Đường dẫn tuyệt đối là thứ gọi tên nó, và đó cũng chính là cách viết mà aggrega lint và một chẩn đoán dừng in ra cho tệp đó tại terminal — nên một tệp có một tên dù bạn hỏi qua bề mặt nào. Điều bạn sẽ không nhận được là một đường dẫn leo lên trên gốc, vì nó sẽ chỉ đến các tệp khác nhau tùy theo nơi nó được đọc.

Bạn nhận được cách viết nào có thể đọc ra từ chính giá trị: bất cứ thứ gì nền tảng của bạn đọc là đường dẫn tuyệt đối là dạng thứ hai, và mọi thứ khác là tương đối so với gốc workspace. Bạn không cần kiểm tra điều này để mở tệp — nối một đường dẫn tương đối vào gốc và mở một đường dẫn tuyệt đối nguyên như nó là đều hoạt động — nhưng một client nhóm theo tài liệu của workspace có thể phân biệt hai dạng mà không cần hỏi.

Những gì quy tắc này không áp dụng tới. Một đường dẫn bạn gửi được điều chỉnh bởi hợp đồng riêng của yêu cầu đó, được nêu cùng yêu cầu ở trên và thường chặt chẽ hơn: một đích bị từ chối trừ khi nó tương đối so với gốc workspace và phân giải vào bên trong gốc, kể cả qua các liên kết của nó. Thông báo aggrega/publishDiagnostics mang file của nó ở dạng tuyệt đối trong mọi trường hợp, trong gốc lẫn ngoài gốc, vì giá trị đó là định danh bạn đối chiếu với các tài liệu đang mở của riêng bạn chứ không phải một tọa độ trong workspace — trình soạn thảo của bạn phân giải nó như một đường dẫn hệ thống tệp. aggrega/releaseCandidates và aggrega/activeRelease gọi tên mọi Release và lockfile bằng đường dẫn tuyệt đối, như các mục riêng của chúng ở trên đã nói. Và aggrega/irGraph mang đồ thị đã biên dịch đúng như trình biên dịch đã ghi lại — chỉ giữ lại các giá trị mà tác giả khai báo là nhạy cảm — nên mọi đường dẫn được ghi trong đó là đường dẫn trình biên dịch đã ghi, theo dạng mà hợp đồng riêng của đồ thị ấn định, chứ không phải đường dẫn do giao thức này tạo ra cho bạn.

Một tham số bạn gửi chấp nhận những cách viết nào

Điều một đường dẫn gọi tên — chứ không phải phương thức nào mang nó — quyết định tham số đó chấp nhận những cách viết nào. Mục riêng của mỗi yêu cầu ở trên nêu hợp đồng cho các tham số mà nó nhận; phần sau đây là sự tương phản giữa chúng, và lý do đó là một sự tương phản chứ không phải một sự thiếu nhất quán mà bạn phải ghi nhớ theo từng phương thức.

Một tham số gọi tên một tài liệu bạn đang giữ có thể được viết theo bất kỳ cách nào trong ba cách: tương đối so với gốc workspace, tuyệt đối, hoặc là địa chỉ file:// mà một client language-server gửi cho một tài liệu đang mở. Đó là file hoặc uri của aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint và aggrega/connectionAtPosition. Cả ba cùng gọi tên một tài liệu và được trả lời như nhau, vì mỗi cách được quy về một cách viết chuẩn duy nhất tại ranh giới yêu cầu trước khi bất cứ thứ gì đọc nó — nên một tài liệu bạn đã validate theo đường dẫn của nó được tìm thấy theo địa chỉ của nó, và ngược lại, và việc bạn gửi cách viết nào không thay đổi gì trong câu trả lời. Một địa chỉ được đọc là đường dẫn mà nó gọi tên, với các percent-escape được giải mã, khi authority của nó rỗng hoặc là localhost; một địa chỉ gọi tên máy khác được đọc là thư mục chia sẻ mạng của máy đó trên hệ thống mở tài liệu ở đó theo cách ấy, và không gọi tên thứ gì daemon có thể mở ở nơi khác. Một địa chỉ còn mang query, fragment, thông tin xác thực hoặc cổng cũng không gọi tên thứ gì daemon có thể mở. Một giá trị không bắt đầu bằng file://, bất kể chữ hoa hay thường, không bao giờ được đọc là một địa chỉ, và lời từ chối file-not-validated nêu đúng giá trị bạn đã gửi, dù đó là cách viết nào. Trong số này, aggrega/insertionPoint và aggrega/connectionAtPosition là hai yêu cầu đọc tài liệu từ đĩa khi bạn không giữ bản sao nào của nó, và chúng chỉ trả lời cho một tài liệu bên trong workspace: một tài liệu ngoài gốc — như được viết, hoặc thông qua một liên kết dẫn ra ngoài, tới tệp hay tới một thư mục trên đường đi — bị từ chối dù cách viết nào trong ba cách gọi tên nó, và một tài liệu bên trong gốc được trả lời ở cả ba. Tám yêu cầu còn lại không đọc gì từ đĩa tại đường dẫn mà chúng gọi tên — aggrega/validate lấy các byte của tài liệu từ content, và các yêu cầu còn lại trả lời từ những gì đã được validate — nên chúng trả lời cho một tài liệu dù bạn giữ nó ở đâu, trong workspace hay không, và không liên kết nào chúng gọi tên được đi theo để đọc một tệp. Một tham số gọi tên một tài liệu bạn đã chọn từ bên ngoài workspace là cùng trường hợp vì cùng lý do: source của aggrega/import được đọc tại nơi nó thực sự nằm, như mục riêng của nó nói. Cả hai đều là ngoại lệ đối với ranh giới workspace theo loại — một tài liệu client đang giữ mở, và một tệp do một người chọn — và Ranh giới workspace giải thích vì sao mỗi cái là một ngoại lệ.

Một tham số mà qua đó daemon phải định vị một tài liệu bên trong workspace chỉ nhận một đường dẫn tương đối so với workspace và không gì khác. release là tham số cần biết — trên aggrega/irGraph, và theo cùng hợp đồng ở bất cứ nơi nào khác nó xuất hiện — và một giá trị tuyệt đối bị từ chối bằng lỗi invalid-params, lỗi này nêu hợp đồng rồi gọi tên lỗi cụ thể. Các yêu cầu ghi vào bên trong workspace giữ các đích của chúng theo cùng hợp đồng đó, như mục riêng của mỗi yêu cầu nói. Mỗi đường dẫn như vậy sau đó được đánh giá theo nơi nó dẫn tới, bằng một quy tắc duy nhất dù yêu cầu đọc hay ghi nó — định nghĩa về “bên trong” mà Ranh giới workspace nêu — và một đường dẫn dẫn ra ngoài bị từ chối bằng lỗi riêng của yêu cầu đó, trích nguyên giá trị như bạn đã gửi, không đọc hay ghi gì: một liên kết tới một tệp bên ngoài và một liên kết tới một thư mục trên đường đi đều như nhau, và một đường dẫn chưa được tạo nằm dưới một thư mục liên kết dẫn ra ngoài, bị từ chối vì liên kết đó chứ không được ghi vào, hay được tìm ở bên ngoài rồi báo là thiếu. Điều đó bao gồm mọi đường dẫn mà một yêu cầu gọi tên để daemon đọc — release ở bất cứ đâu nó xuất hiện, entity của aggrega/lint, và entity, plugin, file và from của các yêu cầu xuất bản — nên một yêu cầu không thể đọc qua một liên kết một tệp mà các danh sách riêng của workspace bỏ ra ngoài, và mọi đích: các thư mục mà một lần sinh, một lần import và một lần build ghi vào, thực thể mà aggrega/pin ghi lock bên cạnh, tệp thực thể và module mà aggrega/pluginSync đọc và ghi lại, và tài liệu mà aggrega/editDocument chỉnh sửa. Một release gọi tên một Release mà cấu hình workspace của bạn gọi tên là ngoại lệ duy nhất, như mục của aggrega/irGraph nói.

Hai loại khác nhau vì các lỗi khác nhau. Một tham số gọi tên một tài liệu bạn đang giữ chỉ để lại một câu hỏi — tài liệu nào — nên việc quy cách viết của bạn về cách viết chuẩn không làm mất gì, và việc chấp nhận từng cách cũng không khiến bạn tốn gì. Một tham số chọn một tài liệu ra khỏi workspace không ở vị trí đó: trong các thư viện đường dẫn mà một client có khả năng đang dùng, việc nối một giá trị tuyệt đối vào một gốc cho ra chính giá trị tuyệt đối đó chứ không phải một lỗi. Vì vậy một giá trị được sửa ngầm sẽ khiến daemon đọc — và báo cáo các phát hiện đối với — một đường dẫn mà workspace chưa từng chứa, và bạn sẽ được báo về một tệp không tồn tại. Từ chối là câu trả lời chứ không phải sửa chữa, vì một daemon sửa một giá trị như vậy sẽ khiến mọi client gửi nó tin rằng hợp đồng là tùy chọn.

Cách định địa chỉ một thực thể

Mọi thực thể mà một phản hồi nêu tên đều được định địa chỉ theo cùng một cách: kind, name và file. Hãy kết nối theo ba khóa đó với aggrega/catalogIndex cho bất cứ thứ gì bạn muốn hiển thị: đó là bề mặt mang toàn bộ tập mô tả của một thực thể — apiVersion, description và labels — nên một phản hồi chỉ cần nêu tên một thực thể sẽ báo cáo ba khóa định địa chỉ và để việc mô tả cho một nơi duy nhất. Một truy vấn theo tên như aggrega/entityDefinition lặp lại một vài trường mô tả mà chính câu trả lời của nó nói đến; chỉ mục vẫn là bề mặt để kết nối khi bạn muốn có cả tập.

Ở nơi một phản hồi có thể nêu tên các thực thể từ nhiều hơn một nơi, mỗi định danh mang origin bên cạnh ba khóa đó. aggrega/catalogIndex và aggrega/attachCandidates đều như vậy, vì các thực thể của chúng đến từ các tài liệu workspace và từ các thư mục catalog đã cấu hình. Một phản hồi chỉ lấy từ một nơi sẽ chỉ báo cáo ba khóa và không có origin, vì một khóa chỉ có một giá trị khả dĩ không cho bạn biết gì — mọi thực thể mà phản hồi như vậy nêu tên đều là một tài liệu workspace, và file của nó là một đường dẫn tương đối với workspace mà bạn có thể mở. Vì vậy hãy đọc origin ở nơi nó có mặt thay vì đòi hỏi nó ở mọi nơi; ba khóa là thứ bạn dùng để kết nối trong cả hai trường hợp.

origin thuộc về một phản hồi liệt kê các thực thể, nơi việc phân biệt các tập hợp là vấn đề của người đọc. Một câu trả lời theo tên như aggrega/entityDefinition không mang nó: câu trả lời nêu tên một thực thể duy nhất mà tên đó phân giải tới, nên không có tập hợp nào cần phân tách. Mục riêng của nó ở trên cho biết khi nào file của nó rỗng; đừng đọc sự rỗng đó qua các giá trị origin dưới đây, vốn mô tả một danh sách.

origin cho biết daemon đã đọc thực thể từ đâu, và chính nó làm cho file có thể đọc được.

  • workspace — một tài liệu Aggrega nằm dưới gốc workspace. file là đường dẫn của nó tương đối với gốc đó, là một đường dẫn mà client của bạn có thể mở.
  • catalog — một thực thể được phân giải từ các thư mục catalog đã cấu hình. file rỗng trong danh sách này, và name là toàn bộ địa chỉ. Nó rỗng vì danh sách báo cáo những gì phép tra cứu catalog đã liệt kê, vốn là một định danh chứ không phải một tài liệu, nên mục này không mang đường dẫn nào để báo cáo — chứ không phải một đường dẫn bị giữ lại vì vị trí của nó. Hãy hỏi aggrega/entityDefinition với cùng tên khi bạn muốn có tài liệu: yêu cầu đó phân giải thực thể và báo cáo file của nó theo quy tắc ở trên, nên một thư mục catalog nằm ngoài gốc workspace được nêu tên bằng đường dẫn tuyệt đối của nó ở đó. Dù sao name cũng là tọa độ mà một Aggregate, một Recipe và phép tra cứu catalog đều sử dụng.

Hãy đọc cả hai cùng nhau thay vì chỉ kiểm tra file. Riêng một file rỗng không thể cho bạn biết thực thể không có đường dẫn workspace hay chỉ đơn giản là đường dẫn không được báo cáo; origin trả lời điều đó trực tiếp.

Ở nơi một Feature có thể tiếp cận theo cả hai cách — bản thân gốc workspace là một trong các thư mục catalog đã cấu hình, một bố cục phổ biến — nó được báo cáo một lần, dưới dạng tài liệu workspace, vì đó là bản sao có tệp mà bạn có thể mở.

Phản hồi attach-candidate cho bạn biết điều gì

aggrega/attachCandidates trả lời một câu hỏi duy nhất — tập nhãn này chấp nhận những Features nào — và cung cấp ba cách để nói bạn muốn chỉ tập nhãn nào. Hãy gửi đúng một tọa độ; gửi hai, hoặc không gửi tọa độ nào, sẽ bị từ chối chứ không được xếp hạng.

{node} chỉ đến một tài liệu trong workspace theo metadata.name của nó và không cần gì thêm. Việc khớp được đánh giá dựa trên các nhãn mà tài liệu đó khai báo tại metadata.labels, và phản hồi báo labelSource: "declared".

{graphNode, release} chỉ đến một nút trên một đồ thị đã biên dịch. graphNode là id mà đồ thị dùng làm khóa cho nút — chính id bạn đọc được từ aggrega/irGraph, kể cả dạng đầy đủ mà một nút do một sub-aggregate đóng góp mang theo. release là một đường dẫn tương đối với gốc workspace, chỉ Release có đồ thị cần dựng, cùng giá trị mà aggrega/irGraph nhận. Việc khớp được đánh giá dựa trên các nhãn cuối cùng của nút, và phản hồi báo labelSource: "resolved".

{labels} mang chính tập nhãn và không chỉ đến gì cả. Đây là dạng nằm bên dưới hai dạng kia: việc khớp là một hàm của một tập nhãn và các Features hiện có, nên một client đã có sẵn tập nhãn thì không có gì để đặt tên và không có gì để chờ. Hãy gửi một đối tượng JSON gồm các cặp nhãn; phản hồi báo labelSource: "supplied" và một node rỗng, vì yêu cầu này không chỉ đến nút nào. Một đối tượng rỗng là một tọa độ — nó hỏi về một nút không mang nhãn nào — còn việc bỏ hẳn khóa, hoặc gửi null, thì không chỉ đến gì và bị từ chối.

Hai tọa độ tên được tách riêng vì không gian định danh của chúng chồng lấn nhau. Một id nút đồ thị và metadata.name của một tài liệu có thể là cùng một chuỗi nhưng chỉ những thứ khác nhau, nên một tham số mang cả hai sẽ mơ hồ, và một daemon đoán xem bạn muốn nói không gian nào đôi khi sẽ trả lời một cách tự tin cho sai đối tượng. Chính việc nói rõ bạn đang hỏi câu hỏi nào là điều loại bỏ sự mơ hồ.

labelSource cho bạn biết câu trả lời có phạm vi đến đâu, và ba giá trị không thay thế cho nhau được. declared là kết quả khớp trên những gì một tài liệu nói về chính nó, tức là những gì việc đọc mã nguồn có thể thấy. resolved là kết quả khớp trên các nhãn mà nút thực sự có cuối cùng, tức là những gì một lần build dùng để đánh giá khả năng áp dụng — nên một câu trả lời resolved là một khẳng định về điều một lần build sẽ quyết định, còn một câu trả lời declared thì không. supplied cho biết daemon không đọc nhãn nào cả và chỉ khớp những gì bạn gửi; câu trả lời đó mạnh đến đâu hoàn toàn phụ thuộc vào nguồn gốc tập nhãn của bạn.

Đó là lý do một client đang giữ một đồ thị nên gửi {labels} thay vì một tên. Các nhãn cuối cùng của một nút là nhãn của kiểu component mà nó phân giải tới, không phải của một tài liệu tình cờ trùng id, và sau đó một attachment label-transform có thể thêm, thay đổi hoặc xóa chúng — nên các nhãn quyết định khả năng áp dụng của một nút không nhất thiết là các nhãn mà bất kỳ tài liệu nào khai báo. Một client đang vẽ đồ thị đã có tập nhãn đó từ aggrega/irGraph; gửi lại nó sẽ đạt cùng câu trả lời mà tọa độ {graphNode, release} đưa ra, mà không phải dựng lại đồ thị. Hãy gửi lại một tập mà chính daemon đã báo — của một nút từ aggrega/irGraph, của một thực thể từ aggrega/catalogIndex — và hình dung của bạn về nhãn của một nút không thể lệch khỏi của daemon, vì tập nhãn chưa bao giờ rời khỏi câu trả lời của chính nó. Tự lắp ráp một tập thì bạn đang hỏi một giả định, được trả lời trung thực và không phải là khẳng định về bất kỳ nút nào mà workspace chứa.

Các ứng viên đến từ workspace và từ catalog. Một workspace giữ các Features của nó trong một catalog thay vì trong cây thư mục của chính nó thì không có Feature cục bộ nào cả, và các ứng viên của nó hoàn toàn là origin: "catalog". Với một nút đồ thị, cả hai đều được đọc theo góc nhìn Release của nút đó: các Features của catalog là những Features mà các thư mục catalog do cấu hình workspace cấp cho Release đó khai báo, và các tài liệu riêng của workspace được cung cấp trừ đi những tài liệu nằm dưới một thư mục catalog mà chỉ các Releases khác đọc. Vì vậy, một workspace giữ mỗi Release một biến thể của một Feature sẽ cung cấp cho đồ thị của mỗi Release biến thể riêng của nó và không bao giờ là biến thể của Release khác, trong khi một Feature được viết bên cạnh các catalog, không nằm dưới thư mục catalog nào, được cung cấp cho mọi Release. {node} và {labels} không chỉ Release nào, nên chúng dựa trên mọi tài liệu workspace và trên catalog_dirs của chính workspace. Một Feature không khai báo khả năng áp dụng nào là ứng viên cho mọi nút — một khai báo vắng mặt không nêu yêu cầu nào — còn một Feature có khai báo không đọc được thì không là ứng viên cho nút nào, vì coi một selector không đọc được là thỏa mãn sẽ để một lỗi gõ mở rộng những gì bạn cung cấp.

Một tên không phân giải được là một lỗi, không phải một danh sách rỗng. Hai câu trả lời đó mang nghĩa khác nhau: một mảng candidates rỗng nói rằng nút này không có gì có thể gắn vào nó, và báo một tên gõ sai theo cách đó sẽ trình bày một lỗi gõ như một câu trả lời đã chắc chắn. Lời từ chối nêu tên không gian mà nó đã tìm, để bạn biết nên tìm một tài liệu workspace hay một nút đồ thị. {labels} không có rủi ro như vậy — không có tên nào để gõ sai — nên một tập nhãn không được gì chấp nhận sẽ trả về một phản hồi thành công mang một mảng rỗng, và một yêu cầu mà daemon không đọc được vẫn bị từ chối trước khi bất kỳ việc khớp nào chạy.

Tọa độ nút đồ thị cần một lockfile; hai tọa độ kia thì không. Dựng một đồ thị nghĩa là phân giải những gì Release vươn tới, nên đường đó từ chối với lỗi thiếu lockfile khi chưa có lockfile nào được tạo, kèm tên lệnh cần chạy — cùng điều kiện tiên quyết mà aggrega/irGraph có, vì cùng lý do. Chỉ đến một tài liệu workspace không dựng đồ thị nào, và cung cấp một tập nhãn thì không dựng gì cả, nên cả hai đều trả lời được trên một workspace chưa ai chuẩn bị.

Nó chỉ báo cáo và không bao giờ tạo. Phương thức này không thay đổi gì, không ghi gì, và không tạo attachment nào. Việc soạn và áp dụng bất kỳ chỉnh sửa nào là việc của trình soạn thảo, nơi có buffer và lịch sử hoàn tác.

Những gì nó phân giải phụ thuộc vào tọa độ, và ba tọa độ không giống nhau. {node} không phân giải gì và không truy cập registry hay mạng nào — các ứng viên đến từ workspace và từ các thư mục catalog, cả hai đều đã có trên đĩa. {labels} còn phân giải ít hơn: nó không tra cứu gì, vì không có gì để tra cứu. {graphNode, release} dựng đồ thị của Release, nên nó phân giải bao đóng phụ thuộc của Release đó giống như aggrega/irGraph: trước tiên từ các thư mục catalog cục bộ và bộ nhớ đệm artifact, rồi từ registry đã cấu hình cho một thực thể mà cả hai nguồn đó không có. Cả ba đều trả lời ngoại tuyến cho một workspace có mọi thực thể đều cục bộ; chỉ tọa độ nút đồ thị mới có thể tìm xa hơn.

Hỏi về một kết nối

Một kết nối mà một component vẽ ra có thể mang các attachment của riêng nó, lấp đầy các slot mà socket của nó khai báo trên Component tiêu thụ — chẳng hạn một thông tin xác thực mà component xuất trình cho bất cứ thứ gì kết nối đó dẫn tới. Gửi connection cùng với {graphNode, release} để hỏi những gì có thể đặt vào đó: socket là socket phụ thuộc mà kết nối được nối qua và alias là tên mà kết nối mang trong socket đó, cả hai đúng như tác giả đã viết. Một kết nối chỉ tồn tại trên một đồ thị đã biên dịch, nên connection đi cùng node hoặc labels sẽ bị từ chối, cũng như một kết nối không nêu socket hoặc không nêu alias, hoặc một kết nối mà node không vẽ ra.

Câu trả lời là câu trả lời cho graph node cộng thêm các slot của kết nối. candidates giữ nguyên ý nghĩa — các Features có thể gắn vào chính node đó — và slots được thêm vào, mỗi mục cho một slot mà socket khai báo, theo thứ tự Component khai báo chúng:

  • slot — tên mà một attachment lấp đầy slot này được viết dưới đó trong features của kết nối.
  • selector, required, inject, sensitive và description — slot đúng như Component khai báo nó trên socket, rỗng hoặc false ở chỗ không khai báo gì. selector là ràng buộc đã dùng để thu hẹp các ứng viên, nên bạn có thể giải thích một ứng viên, hoặc sự vắng mặt của nó, chỉ từ câu trả lời.
  • candidates — các Features có thể lấp đầy slot này trên kết nối này. Một bản build áp hai quy tắc cho một attachment như vậy, và cả hai đều được áp dụng: khả năng áp dụng mà Feature khai báo, đối chiếu với các label cuối cùng của node, điều mà mọi attachment node mang đều phải tuân theo, và selector của slot, đối chiếu với các label của chính Feature. Vì vậy các ứng viên của một slot luôn nằm trong số các ứng viên của node, được thu hẹp bởi selector. Một Feature mà selector không thể đánh giá được trên các label của nó sẽ không được đề xuất, vì một bản build sẽ từ chối thay vì chấp nhận nó.

Khi không slot nào có thể được lấp đầy, slots là một danh sách rỗng và noSlotReason cho biết lý do. Hãy đọc lý do thay vì coi danh sách rỗng là “không Feature nào khớp” — đó sẽ là một câu trả lời khác, và lý do chính là điều giúp phân biệt chúng:

  • feature-created-connection — một Feature đã vẽ ra kết nối, từ khối phụ thuộc của chính nó. Một attachment chỉ được viết trên kết nối mà một component hoặc Release vẽ ra, nên không có gì được đặt ở đây bất kể socket khai báo gì.
  • ad-hoc-socket — socket là một socket mà Component không khai báo. Tác giả đã đặt tên cho nó, điều này hợp lệ, và một socket không được khai báo thì không khai báo slot nào.
  • no-slot-declared — Component khai báo socket mà không có slot nào trên đó.

noSlotReason vắng mặt ở bất cứ đâu có slot, và cả slots lẫn noSlotReason đều vắng mặt trong câu trả lời cho một request không nêu kết nối nào — nên một request không nêu kết nối nào được trả lời mà không có trường nào trong hai trường đó.

document được chấp nhận và không thay đổi gì ở đây. Các slot là của socket và các ứng viên là của các Features, như nhau bất kể attachment được viết trong document nào; việc nó được đặt ở đâu là câu trả lời của aggrega/attachmentContainer. Một giá trị khác aggregate hoặc release vẫn bị từ chối, vì một giá trị được chấp nhận rồi bị bỏ qua sẽ khiến người gửi hiểu là nó đã được tôn trọng.

Phản hồi connection-candidate cho bạn biết điều gì

aggrega/connectionCandidates trả lời hai câu hỏi cùng lúc, và chỉ một trong hai có câu trả lời đầy đủ. Đọc phản hồi như một danh sách đã lọc duy nhất sẽ hiểu sai câu còn lại.

Mỗi socket được báo cáo mang targets — các Components cục bộ trong workspace có nhãn được khai báo thỏa mãn ràng buộc nhãn mà socket đó khai báo về những gì có thể thỏa mãn nó — cùng với selector mà các target đó được tính từ, cờ required mà socket khai báo, và declaration. targets luôn là một mảng, rỗng chứ không vắng mặt, nên một socket không có gì thỏa mãn vẫn được báo cáo là một socket mà thực thể khai báo.

Nửa về target là đầy đủ. Tập hợp được quyết định bằng cách đánh giá ràng buộc được khai báo của socket so với các nhãn được khai báo của một ứng viên, cùng phép đánh giá mà một bản build thực hiện, nên những gì bạn đề xuất chính là những gì cùng ràng buộc đó chấp nhận trong một bản build. Một socket không khai báo ràng buộc nào để các target của nó không bị ràng buộc và báo cáo mọi Component — đó là ý nghĩa của ngôn ngữ ràng buộc đối với một selector rỗng, không phải một lỗi.

Nửa về socket là mở, và declaration cùng adHocSocketsAccepted là cách bạn phân biệt. Tác giả của một Aggregate sở hữu topology của nó và có thể nối một socket mà thực thể catalog của component chưa từng khai báo, nên các socket mà một thực thể khai báo là một tập khởi đầu hữu ích và không phải tập các tên socket hợp lệ. Hãy trình bày chúng như các gợi ý, không phải như các lựa chọn duy nhất — một bộ chọn chỉ đề xuất các socket đã khai báo sẽ cho tác giả biết rằng sự tự do của họ hẹp hơn thực tế.

  • declaration là declared khi thực thể được chỉ định liệt kê socket trong usesSchema của nó, và là ad-hoc khi không liệt kê. Đây là cùng hai giá trị mà một cạnh mang trong đồ thị IR, nên một bộ từ vựng duy nhất trả lời câu hỏi “socket này đến từ đâu” ở bất cứ nơi nào bạn gặp nó.
  • adHocSocketsAccepted báo cáo liệu bề mặt của thực thể được chỉ định có chấp nhận một socket mà khai báo của chính nó không liệt kê hay không. Giá trị này không phải lúc nào cũng là true: bề mặt phụ thuộc của chính một Component chấp nhận, còn bề mặt đính kèm của một Feature thì không, vì một attachment tham gia vào topology mà Feature được đính kèm khai báo thay vì tự tạo topology riêng. Một socket ad-hoc trên một bề mặt không chấp nhận nó được báo cáo không có target nào, vì không kết nối nào qua nó có thể build được.

Việc nêu tên một socket trong yêu cầu giới hạn câu trả lời vào đúng socket đó, và đó là cách duy nhất để hỏi về một socket mà thực thể không khai báo — một socket chưa khai báo không xuất hiện trong khai báo nào để liệt kê. Bỏ nó đi để nhận mọi socket mà thực thể khai báo, theo thứ tự chúng được viết.

Những gì nó báo cáo là một phép khớp trên các nhãn được khai báo. Một bản build đánh giá ràng buộc của socket so với các nhãn đã hoàn tất của node ở đầu xa của cạnh, và đó là các nhãn của kiểu component mà node đó phân giải thành, sau khi mọi attachment label-transform đã tác động — không nhất thiết là các nhãn của tài liệu bạn đã nêu. Vì vậy một câu trả lời khẳng định ở đây không phải là một cam kết về những gì bản build sẽ quyết định — cùng giới hạn mà aggrega/attachCandidates mang theo dưới nguồn nhãn declared của nó.

Nó báo cáo và không bao giờ tạo ra. Phương thức này không phân giải gì, không truy cập registry hay mạng nào, và không ghi gì: nó không tạo cạnh nào và không đề xuất văn bản nào. Việc soạn và áp dụng chỉnh sửa là của trình soạn thảo, nơi có bộ đệm và lịch sử hoàn tác.

Với định danh thực thể trong targets — kind, name và file — hãy join với aggrega/catalogIndex như mô tả trong Cách một thực thể được chỉ định. Các trường mô tả được báo cáo ở đó và có chủ ý không lặp lại ở đây, nên phản hồi này không mang bản sao thứ hai nào của chúng có thể trở nên lệch nhau. Các target là Components của workspace, nên mỗi target đều có một file mà bạn có thể mở và không target nào mang origin: phản hồi này lấy dữ liệu từ một nơi duy nhất, và phép join dựa trên ba khóa.

Phản hồi attachment-container cho bạn biết điều gì

aggrega/attachmentContainer nằm giữa các yêu cầu ứng viên ở trên và điểm chèn ở dưới. Các yêu cầu đó cho biết cái gì có thể gắn vào một nút; yêu cầu này cho biết một attachment cho nút đó thuộc về container nào, và trong tài liệu nào; yêu cầu tiếp theo cho biết văn bản được đặt ở đâu trong các byte của tài liệu đó.

Hãy hỏi container thay vì tự ghép nó. Id của một nút và đường dẫn subsystem bao quanh nó đều được viết với dấu chấm giữa các phần, và dấu chấm là ký tự hợp lệ trong một tên mà tác giả gõ — vì vậy từ bên ngoài tài liệu không có cách nào phân biệt một dấu chấm cấu trúc với một dấu chấm nằm trong tên. Một client tự ghép đường dẫn sẽ tạo ra thứ trông đúng nhưng trỏ tới một khóa không ai viết, và chỉnh sửa theo sau sẽ tạo ra khóa đó thay vì bị từ chối. Trình biên dịch đã ghép cả hai đường dẫn, nên chính trình biên dịch là bên tách chúng ra.

Id của một nút hoàn toàn không mang dấu vết nào của subsystem bao quanh nó. Một component được viết bên trong subsystems.billing.subsystems.payments được đặt khóa trên đồ thị là ledger, giống hệt một component ở cấp cao nhất, nên trong id không có gì để client dựa vào, dù nó tách cẩn thận đến đâu.

Câu trả lời gồm ba trường.

  • node lặp lại nút mà câu trả lời nói đến, để một client có nhiều yêu cầu đang chờ ghép mỗi câu trả lời với câu hỏi của nó mà không phải tự giữ thứ tự.
  • file là tài liệu nơi nút được viết, tính tương đối với workspace. Nó là một phần của câu trả lời chứ không phải điều bạn đã biết: một nút do một module được import đóng góp được viết trong chính tài liệu của module đó dưới tên mà module đặt cho nó, nên cả file lẫn phân đoạn cuối của container đều khác với bất cứ thứ gì yêu cầu đã nêu.
  • container là đường dẫn cấu trúc từ gốc của tài liệu đó, dưới dạng danh sách các phân đoạn — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Mỗi cấp của một subsystem bao quanh lại nằm dưới khóa subsystems, đó là cách tài liệu viết nó. Một component mà tác giả viết ở cấp cao nhất thì thay vào đó nêu ["spec", "components", "checkout", "features"], vì phạm vi mà một component như vậy được biên dịch vào không phải là phạm vi mà file nào chứa.

Nó là một danh sách các phân đoạn và không bao giờ là một chuỗi đã nối, và đó chính là mục đích của hình dạng này. Một đường dẫn đã nối sẽ phải được bên nhận tách lại, tức là sự mơ hồ ở trên quay lại ở lời gọi tiếp theo. Hãy truyền nguyên danh sách cho aggrega/insertionPoint làm container của nó.

Nó đọc cấu trúc và không bao giờ đọc ý nghĩa. Câu trả lời được suy ra từ tài liệu nơi nút được viết, phạm vi mà nó nằm trong và tên mà tác giả đã gõ. Không có gì được đọc ra từ việc một component được gọi là gì, mang kiểu gì hay một nhãn nào nói gì.

Nó chỉ báo cáo và không bao giờ ghi. Phương thức không thay đổi gì và không ghi gì vào bất kỳ tài liệu nào. Nó không tạo attachment, không soạn văn bản và không áp dụng chỉnh sửa; nó không phán quyết cái gì có thể gắn vào, việc đó là của aggrega/attachCandidates.

Một yêu cầu nêu một nút mà đồ thị không chứa sẽ bị từ chối thay vì được trả lời. Id của nút là chính các khóa của đồ thị — hãy đọc chúng từ đồ thị mà aggrega/irGraph trả về — và một nút do một module được import đóng góp mang một id có định danh đầy đủ. Một nút mà đồ thị không ghi nhận tài liệu nào cũng bị từ chối: attachment thuộc về đâu là một sự thật về một tài liệu, nên một nút không có tài liệu thì không có câu trả lời, chứ không phải một câu trả lời rỗng.

Nó yêu cầu một lockfile, vì cùng lý do như aggrega/irGraph: việc nêu container đồng nghĩa với việc xây dựng đồ thị của Release, và một đồ thị được xây từ các byte không có gì bảo đảm sẽ được báo cáo giống hệt một đồ thị đã được kiểm tra.

Một attachment trên một kết nối

Hãy gửi connection cùng với {graphNode, release} — gồm socket, alias và document của nó — và câu trả lời sẽ nêu container features trên chính mục của kết nối đó thay vì của nút. Ở đây document là bắt buộc, vì cả hai tài liệu đều có thể chứa một attachment trên một kết nối mà Aggregate đã vẽ: nhà phát triển viết nó trên mục của kết nối trong Aggregate, người vận hành viết trên mục theo cạnh của Release dành cho nó.

  • aggregate nêu mục của kết nối trong tài liệu nơi nút được viết — ["spec", "components", "gateway", "uses", "models", "gpt", "features"] cho một component ở cấp cao nhất, với mỗi subsystem bao quanh được viết từng cấp như ở trên. Một kết nối do Release vẽ không có mục nào trong Aggregate, nên nó bị từ chối ở đó.
  • release nêu mục theo cạnh nằm dưới chính mục của Release dành cho nút — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] — dù Release đã viết mục theo cạnh đó hay chưa. Nếu chưa, aggrega/insertionPoint báo cáo các khóa còn phải viết trong missingContainerKeys. Khi đó file là tài liệu Release. Một Release hoàn toàn không viết mục nào cho nút sẽ bị từ chối: việc nút được đặt ở đâu là do người vận hành viết, và câu trả lời không quyết định điều đó.

Một kết nối do một Feature vẽ bị từ chối trong cả hai tài liệu, vì lý do mà feature-created-connection nêu ở trên. Nút, socket và alias được so khớp chính xác như đã viết, và một kết nối mà nút không vẽ sẽ bị từ chối thay vì được trả lời bằng một đường dẫn. Mọi thuộc tính khác ở trên vẫn giữ nguyên: câu trả lời là một danh sách các phân đoạn, nó đọc cấu trúc và không bao giờ đọc ý nghĩa, và nó không ghi gì.

Phản hồi connection-at-position cho bạn biết điều gì

aggrega/connectionAtPosition là bước đứng trước hai yêu cầu về kết nối ở trên, dành cho một client đang giữ một vị trí trong tài liệu thay vì một nút trên đồ thị — chẳng hạn một con trỏ đặt trên mục của một kết nối. Nó trả lời kết nối nào được viết ở đó, theo hệ tọa độ mà các yêu cầu kia nhận, rồi dừng lại.

Câu trả lời là một trong hai nửa, không bao giờ cả hai.

  • graphNode và connection — nút có component vẽ kết nối, theo id mà đồ thị đã biên dịch dùng làm khóa cho nó, và kết nối theo socket và alias của nó, với document nêu tài liệu mà vị trí được đọc trong đó: aggregate cho Aggregate hoặc một module mà nó import, release cho Release. Hãy truyền graphNode, cùng release đó và connection cho aggrega/attachCandidates để lấy các slot mà socket của kết nối khai báo, và cho aggrega/attachmentContainer để biết một attachment trên nó được đặt ở đâu; container mà nó nêu nằm ngay bên trong chính mục mà vị trí rơi vào.
  • noConnectionReason — lý do không có kết nối nào được báo cáo. Tập giá trị là đóng:
    • no-connection-entry — vị trí không nằm trên mục nào mà một attachment được viết trong đó. Một kết nối được viết dưới dạng danh sách đích (db: [store]) và một kết nối do khối phụ thuộc riêng của một Feature vẽ đều không có mục như vậy, nên một vị trí trên một trong hai cũng trả về giá trị này.
    • feature-created-connection — vị trí nằm trên mục của Release cho một kết nối mà một Feature đã vẽ, vốn không mang attachment vì lý do mà câu trả lời về slot đã nêu ở trên. Một Release viết mục như vậy khi khối phụ thuộc của một Feature vẽ qua một socket mà Component tiêu thụ cũng khai báo; mục đó vẫn build được dù nó không cấu hình gì hay đặt infra theo từng cạnh của kết nối.
    • unknown-connection — vị trí nằm trên một mục mà Release viết cho một kết nối mà đồ thị đã biên dịch không có. Một Release build được vẫn có thể chứa mục như vậy — ví dụ một mục dưới một alias mà không gì vẽ và không cấu hình gì (không target, không infra, không features), hoặc một mục cho một component bị một toggle active: tắt đi, mà các kết nối của nó rời khỏi bản build cùng với nó.

Những mục nào được tính. Trong Aggregate, mọi kết nối mà một component vẽ, tại mục của nó dưới alias của kết nối trong tài liệu mà component được viết trong đó — với một component do một module được import đóng góp, đó là tài liệu riêng của module đó. Trong Release, mọi mục theo từng cạnh mà nó viết, dù mục đó tự vẽ kết nối hay cấu hình một kết nối mà Aggregate đã vẽ. Vị trí của mỗi mục là điều đồ thị đã biên dịch ghi lại, nên việc một khóa có phải là kết nối hay không không bao giờ được suy ra từ tên gọi của nó. Một component bị một toggle active: tắt đi không có trong đồ thị đã biên dịch, nên các mục riêng của nó trong Aggregate trả về no-connection-entry, còn mục của Release cho một trong các kết nối của nó trả về unknown-connection.

Một vị trí ở bất kỳ đâu bên trong một mục là ở trong mục đó. Mục kéo dài từ khóa alias của nó đến dòng cuối cùng được thụt lề bên dưới, nên một vị trí trên alias, trên target của nó, hoặc bên trong features của nó được trả lời cho kết nối đó, và mục trong cùng được chọn khi các mục lồng nhau. Một vị trí trên khóa riêng của một socket, phía trên các alias viết dưới nó, không nằm trong alias nào — dù socket chứa một hay nhiều alias — và một vị trí trong phần thụt lề trước một khóa alias cũng vậy.

Tài liệu nào là tài liệu nào được suy ra từ Release. Tệp riêng của Release được đọc để lấy các mục mà nó viết; mọi tệp khác được đọc để lấy các mục mà đồ thị ghi nhận các component được viết trong đó. Một tài liệu mà đồ thị của Release không đọc gì từ nó sẽ trả về no-connection-entry tại mọi vị trí.

Nó chỉ báo cáo và không bao giờ ghi, và nó đọc tài liệu theo cách aggrega/insertionPoint làm: từ bản sao của phiên trước, nếu không thì từ đĩa, bên trong workspace, với cùng các trường hợp từ chối cho một tài liệu nằm ngoài workspace, không đọc được, hoặc không phải YAML hợp lệ. Nó yêu cầu một lockfile, vì cùng lý do như aggrega/attachmentContainer, và build đồ thị mà không render gì.

Phản hồi insertion-point cho bạn biết điều gì

aggrega/insertionPoint là phần đối ứng với hai yêu cầu ứng viên ở trên. Các yêu cầu đó cho biết cái gì có thể gắn vào hoặc kết nối; yêu cầu này cho biết văn bản cho nó thuộc về đâu trong một tài liệu cụ thể. Nó trả lời và dừng ở đó.

Bạn đặt tên container; daemon định vị nó. container là một đường dẫn cấu trúc tính từ gốc tài liệu — ["spec", "components", "web", "features"] — và đó là khẳng định của bạn về nơi một mục thuộc loại này nằm trong một tài liệu thuộc loại này. Daemon không suy ra đường dẫn đó từ tên của một thực thể, kiểu mà nó mang, hay ý nghĩa mà nó có vẻ có. Nó đọc các byte mà tác giả đã viết và báo cáo những đoạn nào của đường dẫn mà tài liệu này đã có, các cột mà các mục của nó nằm ở, và dòng cuối cùng mà khối trong cùng của nó vươn tới. Vì vậy, việc biết khóa nào vẫn thuộc về bên gọi, còn việc biết các mục của khóa đó nằm ở đâu trong tệp này thì đến từ đây.

Đối với một attachment Feature trên một nút của đồ thị đã biên dịch, bên gọi không phải tự biết khóa đó: hãy hỏi aggrega/attachmentContainer để lấy tài liệu và container, rồi truyền cả hai vào đây mà không thay đổi.

Câu trả lời là một vị trí có độ rộng bằng không cùng với những gì bạn phải viết quanh nó. file là tài liệu, tương đối với workspace. container lặp lại đường dẫn bạn đã hỏi, để một client có nhiều yêu cầu đang chờ ghép mỗi câu trả lời với câu hỏi của nó mà không phải tự giữ thứ tự. position chèn vào chứ không thay thế: không có gì đã có trong tài liệu bị ghi đè hay bị dịch chuyển.

  • precededByLineBreak — bắt đầu văn bản bạn viết bằng một dấu xuống dòng. Vị trí nằm ở cuối dòng mà mục mới đi sau, vị trí này nằm trong phạm vi dù tệp có kết thúc bằng ký tự xuống dòng hay không và không làm xáo trộn byte nào đã được viết. Nó chỉ là false đối với một tài liệu không chứa gì để đứng sau, khi đó bạn viết từ đầu tệp.
  • missingContainerKeys — các đoạn của đường dẫn container mà tài liệu này chưa có, ngoài cùng trước. Mỗi đoạn phải được viết thành một khóa riêng trước khi mục có thể đặt vào bên trong đoạn trong cùng. Nó rỗng khi toàn bộ đường dẫn đã có sẵn.
  • entryIndent — cột mà dòng đầu tiên của chính mục bắt đầu, tính bằng số khoảng trắng từ đầu dòng.
  • indentStep — mỗi cấp lồng nhau được thụt vào thêm bao nhiêu.
  • indentStepMeasured — bước đó có được đo từ cấu trúc lồng nhau của chính tài liệu này hay không. Khi nó là false, tài liệu không có cấu trúc lồng nhau nào để đo và bước là giá trị dự phòng, nên một client muốn áp đặt bước riêng của mình biết rằng nó được tự do làm vậy.
  • entryShape — mapping hoặc sequence, đọc ra từ những gì container đã chứa, và unknown khi container chưa có hoặc không chứa gì. unknown không phải là một lỗi: tài liệu chưa cho biết các mục của nó có dạng gì, nên lựa chọn đó là của bạn.

Áp dụng nó. Viết một dấu xuống dòng khi precededByLineBreak được đặt. Sau đó là một dòng cho mỗi mục của missingContainerKeys, ngoài cùng trước, mỗi dòng là khóa theo sau bởi dấu hai chấm — dòng đầu tiên thụt vào ở entryIndent trừ indentStep nhân với số khóa còn thiếu, và mỗi dòng tiếp theo thụt thêm indentStep. Sau đó là chính mục, thụt vào ở entryIndent. Khi missingContainerKeys rỗng, mục là dòng duy nhất bạn viết.

Hãy đọc missingContainerKeys ngay cả khi bạn cho rằng container đã có. Một vị trí được áp dụng mà thiếu các khóa phải đứng trước nó sẽ tạo ra một tài liệu không còn phân tích được, đó là lỗi duy nhất mà câu trả lời này không được hiểu là vắng mặt.

position đếm từ không, khác với vị trí của một chẩn đoán. Cả line và character đều bắt đầu từ 0, khớp với các giá trị vị trí theo dạng LSP mà giao thức này tái sử dụng, trong khi line và column trên một mục chẩn đoán bắt đầu từ 1 như được mô tả trong What a diagnostic entry carries. Một client đưa dữ liệu từ bề mặt này sang bề mặt kia sẽ chuyển đổi giữa chúng.

positionEncoding cho biết đơn vị dùng để đo character, và đó là bảng mã đã được thương lượng lúc bắt tay. Nó được báo cáo trên câu trả lời thay vì để ngầm định vì một vị trí mà bên gọi phải đoán đơn vị là một vị trí nó không thể áp dụng: các offset đo theo một cách và áp dụng vào một buffer đo theo cách khác sẽ làm hỏng tài liệu ở ký tự đầu tiên nằm ngoài ASCII.

Một yêu cầu không trỏ tới nơi một mục có thể đặt vào sẽ bị từ chối thay vì được trả lời. Mỗi trường hợp sau là trạng thái của yêu cầu chứ không phải của workspace, nên nó trả về với mã invalid-params tiêu chuẩn và việc thử lại không thay đổi gì cho đến khi file hoặc container thay đổi.

  • Tài liệu không được chỉ định, không nằm trong workspace, không đọc được, hoặc không phải YAML hợp lệ — một tài liệu không có cấu trúc thì không có vị trí nào để báo cáo.
  • Đường dẫn container không chỉ tới gì: nó không có đoạn nào, hoặc một trong các đoạn của nó rỗng.
  • Đường dẫn đi qua một giá trị mà tài liệu chứa dưới dạng scalar. Không thể nối thêm gì vào bên trong một scalar, và thay thế nó sẽ là viết lại chứ không phải chèn.
  • Đường dẫn chạm tới một collection mà tác giả viết theo kiểu flow. Nối thêm một mục vào đó sẽ viết lại các byte tác giả đã viết thay vì thêm một dòng, đó là một chỉnh sửa chứ không phải một vị trí.
  • Đường dẫn trỏ tới một block sequence bằng một thứ không phải là chỉ số của nó. Các mục của một sequence được truy cập theo vị trí, nên một tên không chạm tới gì trong đó và không thể tạo mục nào để mang tên đó.

Nó đọc buffer mà trình soạn thảo đang giữ, không chỉ tệp trên đĩa. Bộ nhớ đệm phân tích của daemon được tra cứu trước, nên vị trí được báo cáo dựa trên nội dung chưa lưu nếu có, và dựa trên chính tệp khi bộ nhớ đệm không có gì cho nó.

Nó chỉ báo cáo và không bao giờ ghi. Phương thức này không thay đổi gì, không phân giải gì, không truy cập registry hay mạng nào, và không ghi gì vào bất kỳ tài liệu nào. Nó không soạn văn bản của một mục và không áp dụng mục nào. Việc soạn và áp dụng chỉnh sửa thuộc về trình soạn thảo, nơi có buffer và lịch sử hoàn tác.

Phản hồi document-edit cho bạn biết điều gì

aggrega/editDocument là nửa còn lại của cặp ở trên: các yêu cầu đó cho biết một mục thuộc về đâu và để bạn tự soạn và áp dụng nó; yêu cầu này soạn và áp dụng một mục, và nó ghi. Cả hai đều được giữ lại, vì một client đang giữ một buffer chưa lưu và một client chỉnh sửa những gì trên đĩa cần hai nửa khác nhau — một trình soạn thảo có lịch sử hoàn tác riêng tự đặt văn bản, còn một client muốn tệp được chỉnh sửa thay vì được cho biết chỗ cần sửa thì gửi yêu cầu này.

Một lời gọi áp dụng một chỉnh sửa, và tập các chỉnh sửa là đóng. edit cho biết là chỉnh sửa nào: add-component thêm một thể hiện component dưới một container components, attach-feature gắn một Feature vào một nút, wire-edge nối một kết nối bên trong một trong các socket phụ thuộc của nút, và set-value đặt một giá trị trên một nút. Không có chỉnh sửa nào xóa, thay thế một khối bạn đã viết, sắp xếp lại bất cứ thứ gì, hoặc ghi nguyên văn các byte bạn cung cấp — nên đây không phải là một công cụ ghi tệp mang một cái tên hẹp hơn, và một giá trị nằm ngoài bốn giá trị này bị từ chối thay vì được diễn giải. Lời từ chối liệt kê những gì bạn có thể nêu.

Bạn nêu nút dưới dạng một đường dẫn cấu trúc, đúng như hai yêu cầu ở trên nhận. node là breadcrumb từ gốc tài liệu — ["spec", "components", "web"] — và container mà mục được đặt vào được suy ra từ edit. Với add-component, đường dẫn nêu chính container components, vì mục được thêm chính là nút. name là khóa mà mục được ghi dưới đó: tên thể hiện, tên của phần gắn, bí danh của kết nối, hoặc khóa của giá trị. value là những gì mục đó mang, và ý nghĩa của nó được suy ra từ edit — thực thể mà mục yêu cầu, nút mà một kết nối trỏ tới, hoặc giá trị vô hướng mà một giá trị được đặt thành. socket được đọc cho wire-edge và bị bỏ qua trong các trường hợp khác.

Dùng đường dẫn thay vì tên, vì cùng lý do yêu cầu định vị nhận một đường dẫn: một cái tên sẽ phải được tìm kiếm, và một cái tên xuất hiện ở hai cấp sẽ để trình biên dịch tự quyết định bạn muốn nói cái nào. Vì vậy một client biết mình đang chỉnh sửa nút nào sẽ nói rõ, còn một client không biết thì biết rằng nó có một câu hỏi cần trả lời trước khi chỉnh sửa bất cứ thứ gì.

Mọi byte mà chỉnh sửa không chạm tới đều được giữ nguyên. Tài liệu chỉ được phân tích để định vị container và dòng mà khối của nó kết thúc; mục được kết xuất và chèn ở cấp dòng. Chú thích, dòng trống, kiểu trích dẫn, các scalar dạng folded và literal, biểu thức template và dạng ký tự xuống dòng cuối tệp đều được giữ nguyên không đổi, và bước lồng được đo từ thụt lề của chính tài liệu thay vì bị áp đặt — nên một mục nằm đúng theo phong cách bạn đang viết. Cùng một yêu cầu trên cùng một tài liệu tạo ra cùng các byte, nên một client có thể so sánh hai lần chạy và một lần review đọc một chỉnh sửa như một diff.

Kết quả phải là một tài liệu mà bạn đã có thể tự gõ, và việc ghi phụ thuộc vào điều đó. Tài liệu được soạn được xác thực theo schema của chính kind của nó và chỉ được ghi xuống đĩa nếu vượt qua. Một yêu cầu sẽ tạo ra thứ mà schema soạn thảo từ chối sẽ trả về E0275 — chỉnh sửa bị từ chối vì tài liệu kết quả sẽ không hợp lệ, và không có gì được ghi — kèm theo thuộc tính mà schema không chấp nhận và vị trí của nó. Tệp được giữ nguyên từng byte như trước, nên một chỉnh sửa bị từ chối không thể phân biệt với một chỉnh sửa chưa từng được thử, và bạn có thể thử lại một yêu cầu đã sửa trên chính tài liệu ban đầu. Đó cũng là lý do không có quy tắc nào được nhắc lại ở đây: yêu cầu một tài liệu Release mang một giá trị dành cho developer sẽ bị từ chối bởi chính schema vốn sẽ từ chối tài liệu gõ tay.

Điều gì được chấp nhận về mặt ngữ nghĩa không được quyết định ở đây. Việc một socket phụ thuộc có phải là socket mà bên cung cấp khai báo hay không, hoặc khả năng áp dụng của một Feature có được thỏa mãn hay không, thuộc về quá trình phân giải mà một lần build thực hiện, mỗi thứ có cách báo cáo riêng. Vì vậy bạn có thể nêu một kết nối mà yêu cầu này chưa từng biết tới, và một Aggregate có thể soạn một socket mà thực thể catalog của nó không khai báo trước; những gì có thể được tiêu thụ qua một socket vẫn do bên cung cấp khai báo. Hãy chạy aggrega/validate với một Release, hoặc yêu cầu đồ thị, khi đó là câu hỏi của bạn.

Câu trả lời nêu những gì đã được đặt vào và những gì đã được ghi xuống đĩa, và đó là hai câu hỏi khác nhau. content mang tài liệu mà chỉnh sửa tạo ra trong cả hai cách phân phối. written nêu tệp đã được ghi xuống đĩa, và rỗng khi dùng dryRun. container là đường dẫn cấu trúc của container mà mục được đặt vào, nên bạn có thể định vị thứ vừa thêm mà không phải tự suy ra lại quy tắc đó. createdContainers nêu các phân đoạn mà chỉnh sửa này đã ghi vì tài liệu chưa có chúng, từ ngoài vào trong — rỗng trong trường hợp thông thường khi toàn bộ đường dẫn đã có sẵn, và đọc nó là cách bạn phân biệt một mục được thêm vào bên trong một khối có sẵn với một mục tự tạo ra khối của riêng nó. file và edit lặp lại những gì bạn đã gửi, nên một client có nhiều yêu cầu đang chờ có thể ghép mỗi câu trả lời với câu hỏi của nó. written, container và createdContainers luôn là mảng, rỗng thay vì vắng mặt.

Khi dùng dryRun không có gì được tạo. written rỗng, content mang tài liệu mà một lần ghi lẽ ra sẽ tạo ra, và tệp không bị động tới — nên một trình soạn thảo có thể đưa kết quả cho tác giả để lưu, sửa hoặc bỏ. Mặc định là ghi, vì sản phẩm của thao tác là một tài liệu đã chỉnh sửa và một bề mặt tạo ra nó có trách nhiệm cung cấp nó: một yêu cầu không nói gì về cách phân phối sẽ chỉnh sửa tệp.

Mọi việc khác mà một lần ghi làm, một lần chạy thử cũng làm. Tài liệu được soạn được xác thực theo schema của chính kind của nó trong cả hai trường hợp, nên một chỉnh sửa mà lần ghi sẽ từ chối cũng bị từ chối khi dùng dryRun, nêu cùng thuộc tính — nghĩa là lỗi bạn nhận được từ một lần chạy thử chính là lỗi mà lần ghi sẽ trả về.

Một mục đã có sẵn, mang đúng những gì bạn yêu cầu, là một thao tác không làm gì — tài liệu được trả về không đổi và không có gì được ghi. Một mục cùng tên nhưng mang thứ khác sẽ bị từ chối thay vì bị thay thế, vì thay thế những gì tác giả đã viết không phải là một trong bốn chỉnh sửa.

Sau khi ghi, daemon đọc lại tài liệu. Những gì nó đang giữ cho tệp đó bị loại bỏ và góc nhìn cấp workspace của nó được đặt lại, nên yêu cầu validation, hover, completion hoặc đồ thị tiếp theo được trả lời từ các byte mà chỉnh sửa tạo ra thay vì từ phiên bản bị thay thế. Bản thân chỉnh sửa đọc tệp trên đĩa chứ không đọc buffer bạn đang giữ — khác với yêu cầu định vị ở trên, vốn tham khảo nội dung chưa lưu trước. Điều đó là có chủ đích: ghi từ một buffer chưa lưu sẽ đưa nội dung tác giả chưa lưu vào trang dưới danh nghĩa áp dụng một mục. Hãy lưu buffer, rồi chỉnh sửa.

Một yêu cầu không trỏ tới một vị trí mà mục có thể được đặt vào sẽ bị từ chối thay vì được trả lời, với mã invalid-params tiêu chuẩn, và thử lại sẽ không thay đổi gì cho đến khi yêu cầu thay đổi. Tài liệu không được nêu, không nằm trong workspace, không đọc được, không phải YAML hợp lệ về cấu trúc, hoặc không khai báo kind nào có schema để kiểm tra kết quả; edit không được nêu hoặc không phải một trong bốn giá trị; node không trỏ tới gì, hoặc một trong các phân đoạn của nó rỗng; không có name nào được cung cấp; wire-edge không nêu socket; set-value được cung cấp một mapping hoặc một sequence ở chỗ cần một scalar; đường dẫn nút chạm tới một scalar hoặc một sequence, hoặc một collection viết theo flow style, nơi việc thêm một dòng sẽ ghi lại các byte đã có trên trang; hoặc đường dẫn nút không chạm tới gì trong tài liệu.

Nó không phân giải phụ thuộc nào, không truy cập registry nào và không chạm tới mạng trong cả hai cách phân phối.

Phản hồi effective-configuration bao gồm những gì

aggrega/effectiveConfiguration trả lời hai câu hỏi: cấu hình nào áp dụng trong phiên này, và lớp nào đã quyết định từng thiết lập. Đây chính là câu trả lời mà aggrega config show --origin in ra, được tính một lần và báo cáo trên cả hai giao diện, nên hai bên không thể bất đồng về nguồn gốc của một thiết lập.

Một source có một trong bốn dạng. Đường dẫn tuyệt đối của một tệp cấu hình — bao gồm cả tệp toàn cục mà daemon được khởi động bằng aggrega --config <file> serve đọc, được ghi bằng đường dẫn đã được truyền vào; một biến môi trường đứng sau tiền tố env:, chẳng hạn env:AGGREGA_SIGNING_REQUIRED; một cờ toàn cục được gõ trên dòng lệnh đã khởi động daemon, được ghi bằng tên cờ, chẳng hạn --offline cho daemon được khởi động bằng aggrega --offline serve; hoặc (built-in defaults) cho một thiết lập mà không lớp nào đặt. Ba dạng đầu xuất hiện nguyên văn trong layers. Các giá trị mặc định thì không, vì các giá trị mặc định không phải là một lớp đã đóng góp — chúng là thứ áp dụng ở nơi không lớp nào lên tiếng.

Một thiết lập được quy cho lớp có độ ưu tiên cao nhất đặt nó, bất kể lớp đó ghi giá trị gì. Một tệp cấu hình ghi giá trị mặc định tích hợp, hoặc nhắc lại một giá trị mà tệp bên dưới nó đã đặt, vẫn là tệp được nêu tên: nó là tệp giữ giá trị đó tại chỗ. Một tệp đặt một thiết lập bằng cách chứa khóa của thiết lập đó, kể cả khóa đi kèm _append của một danh sách, còn một biến môi trường đặt thiết lập bằng cách được export với một giá trị không rỗng. Tệp cấu hình do pipeline của bạn sở hữu không bao giờ được nêu tên cho một khóa mà nó bỏ qua. aggrega config show --origin báo cáo theo cùng quy tắc.

Mọi thiết lập mà lược đồ cấu hình khai báo đều được tính đến, dù không phải mỗi thiết lập đều có một hàng riêng. Khóa đi kèm bổ sung _append của một danh sách được báo cáo trên hàng của danh sách mà nó bổ sung vào, nên một lớp chỉ đóng góp qua khóa đi kèm sẽ được nêu tên trên hàng của danh sách đó và khóa đi kèm không có hàng riêng. Một thiết lập nằm bên trong các mục của một danh sách — chính sách tin cậy của một registry, các đầu vào của một plugin attachment — được bao gồm trong hàng của danh sách đó.

Thêm hai giới hạn, mỗi giới hạn khiến câu trả lời thô hơn vẻ ngoài của nó.

  • Một thiết lập dạng danh sách hoặc map được quy cho toàn bộ, cho lớp có độ ưu tiên cao nhất đặt nó. Việc quy theo từng mục không được theo dõi, nên một danh sách được ghép từ hai lớp chỉ báo cáo lớp có độ ưu tiên cao hơn, và một mục do lớp thấp hơn đóng góp không thể phân biệt với một mục do lớp cao hơn ghi.
  • Yêu cầu ký được quy cho lớp đầu tiên đã bật nó, không phải lớp cuối cùng nhắc đến nó. Thiết lập đó được kết hợp sao cho bất kỳ lớp nào bật nó đều thắng và không lớp nào sau đó có thể tắt nó, nên lớp đầu tiên bật nó chính là lớp đã tạo nên giá trị hiệu lực. Một lớp ghi required: false không bật gì cả, nên khi mọi lớp nhắc đến nó đều ghi false thì thiết lập báo cáo (built-in defaults).

Mọi giá trị được báo cáo là kết quả phân giải được lấy khi workspace đó được nêu tên lần đầu. Chỉnh sửa một tệp cấu hình không làm thay đổi giá trị ở đây; khởi động lại daemon thì có. Điều này là có chủ ý — các giá trị này là cấu hình mà mọi yêu cầu khác về workspace đó được trả lời theo, và đó là điều khiến chúng có thể so sánh với gốc và lớp cấu hình mà bước bắt tay đã báo cáo cho nó. Một client hiển thị cấu hình bên cạnh một tệp người dùng đang chỉnh sửa nên cho biết nó đang hiển thị cái nào trong hai cái.

Việc quy lớp được tính khi bạn hỏi, dựa trên các tệp như hiện trạng của chúng. Vì vậy một tệp cấu hình được chỉnh sửa sau đó có thể làm thay đổi một source trong khi giá trị bên cạnh vẫn giữ như khi đã được phân giải. Hai nửa trả lời hai câu hỏi khác nhau — cái gì đang có hiệu lực, và lớp nào đã quyết định nó — và chỉ nửa đầu là cố định. Hãy khởi động lại daemon để đưa chúng khớp lại với nhau.

Nó chỉ báo cáo và không bao giờ ghi. Phương thức này không thay đổi cấu hình nào, không tạo tệp nào, và không phân giải gì từ registry hay mạng.

Nội dung tệp của từng lớp riêng lẻ không được cung cấp ở đây. Dòng lệnh có thể in nguyên văn các byte của riêng một lớp, giữ nguyên chú thích và định dạng; phương thức này báo cáo kết quả phân giải chứ không phải các byte. Một client muốn lấy văn bản của một lớp có đường dẫn trong layers và có thể mở nó.

Một thao tác ghi cấu hình để lại gì

aggrega/configInit và aggrega/configCapture đều tạo ra một tài liệu cấu hình, và cả hai đều ghi nó ra. Câu trả lời nêu tên tệp; mở tệp là bước tiếp theo của bạn, không phải thứ thay thế cho việc ghi. Không cái nào trao cho bạn nội dung để tự đặt vào, trừ khi bạn yêu cầu điều đó một cách rõ ràng, vì một khả năng mà sản phẩm là một tài liệu chưa từng được ghi là một khả năng khác mang cùng tên.

Hai yêu cầu khác nhau ở phạm vi tác động, và mỗi câu trả lời cho biết phạm vi nào. Hãy đọc nó trước khi hiển thị kết quả.

  • Theo mặc định, việc khởi tạo ghi vào cấu hình dùng chung cho mọi workspace trên máy. Một registry và các danh tính bạn tin cậy trên đó thường giống nhau ở bất cứ đâu bạn làm việc, nên mục đó được ghi vào đây trừ khi yêu cầu gửi workspace: true. scope mang configFile đã được ghi và machineWide cho biết đó có phải là tệp dùng chung hay không — được suy ra từ tệp mà thao tác ghi đã phân giải tới chứ không phải từ những gì yêu cầu đã đòi, nên một câu trả lời không thể mô tả một thay đổi trên toàn máy như một thay đổi cục bộ.
  • Việc đóng băng không bao giờ vượt ra ngoài workspace. Nó không nhận đích ghi và không nhận ghi đè: toàn bộ mục đích của nó là làm cho một dự án tự chứa, nên nó luôn ghi vào .aggrega-config.yaml của chính dự án đó. Đó là lý do câu trả lời của nó mang configFile và workspaceRoot và không khẳng định phạm vi nào — không có phạm vi nào để nêu.

Việc khởi tạo từ chối thay vì ghi đè. Một tệp cấu hình đã tồn tại được giữ nguyên và lời từ chối nêu tên tệp đó, vì việc khởi tạo dành cho một cấu hình chưa tồn tại, trong khi thao tác ghi dùng chung mà nó ủy thác cho thì hợp nhất theo thiết kế. Gửi force để vẫn ghi; mục registry được hợp nhất vào những gì đã có và các thiết lập khác được giữ nguyên. Một yêu cầu bị từ chối không thay đổi gì cả.

trust cho biết chính sách mà registry công bố đã dẫn đến điều gì, dưới dạng các kết quả riêng biệt chứ không phải văn xuôi. pinned nghĩa là registry đã công bố một chính sách và chính sách đó đã được áp dụng, với identities đếm số danh tính. notAdvertised nghĩa là registry đã được hỏi và không công bố chính sách nào, điều này không phải là lỗi — việc khởi tạo vẫn tiếp tục, và reason cho biết endpoint đã làm gì. Một registry không thể truy cập cũng được báo cáo như vậy, vì không có chính sách nào trả về và việc khởi tạo vẫn tiếp tục như thế, và mang thêm unreachable bên cạnh khi chính lỗi đó cho thấy registry chưa từng được truy cập: tên của nó không phân giải được, kết nối tới nó bị từ chối hoặc không thể mở, hoặc không thể thiết lập kết nối bảo mật tới nó. Một registry đã trả lời — bằng not-found, hoặc bằng một trạng thái lỗi — không bao giờ mang unreachable, vì vậy hãy đọc khóa đó thay vì câu chữ của reason để phân biệt một registry không công bố chính sách với một registry chưa từng được hỏi. baseline nghĩa là baseline tích hợp sẵn của hub chính thức đã được ghim vì không có chính sách công bố nào được áp dụng, với reason cho biết lý do; mục đó mang một chính sách, nên không có gì cần ghim thủ công. Hai khóa trả lời hai câu hỏi khác nhau, nên một hub đã được hỏi và không công bố gì sẽ mang cả hai, còn một hub trong một workspace ngoại tuyến — chưa từng được hỏi — chỉ mang baseline, với reason cho biết workspace đang ngoại tuyến. Bất kỳ registry nào khác không công bố gì chỉ mang notAdvertised, được khởi tạo không có chính sách, và lời khuyên đi kèm là ghim danh tính thủ công; khi ngoại tuyến, yêu cầu đó bị từ chối thay vì được trả lời. skipped nghĩa là không có lần tải nào được thực hiện. Một client coi mọi thứ trừ pinned là lỗi sẽ báo cáo một cấu hình đang hoạt động là bị hỏng.

Dưới dryRun không có gì được tạo ra. written là false, content mang tài liệu mà một thao tác ghi sẽ tạo ra, và tệp mà nội dung đó dành cho là scope.configFile. Không thư mục nào được tạo và không tệp nào bị động đến, nên một trình soạn thảo có thể đặt văn bản trước mặt tác giả và để họ lưu, sửa hoặc bỏ nó.

Một lần chạy thử khác với một thao tác ghi đúng ở một điểm — nó không ghi — nên mọi lời từ chối mà thao tác ghi thực hiện thì nó cũng thực hiện. Lời từ chối do tệp đã tồn tại là điều quan trọng ở đây: dryRun trên một tệp cấu hình đã tồn tại bị từ chối, nêu tên tệp, giống hệt như một thao tác ghi. Chính điều đó làm cho phản hồi dùng được như một vị từ — nếu lần chạy thử từ chối, thao tác ghi cũng sẽ từ chối, vì cùng lý do và với cùng thông báo. Gửi force cùng với dryRun để thay vào đó nhận được kết quả hợp nhất mà một thao tác ghi đè sẽ tạo ra, vẫn không ghi gì. Registry được liên hệ để lấy chính sách tin cậy đã công bố của nó dưới cả hai cách phân phối, vì chính sách trong nội dung đó là chính sách mà một thao tác ghi sẽ ghim.

Những gì một lần đóng băng báo cáo là những gì nó đã ghi, không phải một mô tả về điều đó. sockets liệt kê từng plugin socket đã được đóng băng cùng các attachment được đóng băng ở đó; catalogDirs mang các thư mục catalog. Cả hai luôn là mảng, rỗng chứ không vắng mặt.

  • socket và field không phải là cùng một chuỗi, và sự khác biệt không chỉ là hình thức. socket nêu tên socket mà các attachment được gắn vào; field là khóa mà chúng được ghi dưới đó trong tệp. Chúng chỉ khác nhau đối với socket provider, vốn được ghi dưới một khóa số nhiều — vì vậy hãy dùng field khi chỉ người đọc tới một dòng trong tài liệu và socket khi nêu tên chính socket.
  • Mỗi attachment mang uri, capability, function và role, chỉ có mặt khi attachment có giá trị đó. Chúng nêu tên attachment chứ không tái hiện toàn bộ: các đầu vào tùy chọn tại thời điểm gắn của một attachment được đóng băng nguyên văn vào tệp và không được lặp lại trong câu trả lời. Tệp là bản có thẩm quyền.
  • captured: false là một thành công. Một dự án mà quá trình build không tham gia vào cấu hình của nó thì không có gì thiết yếu cho build để đóng băng, nên tệp được giữ nguyên và cả hai danh sách trả về rỗng. Coi đó là lỗi sẽ báo cáo một workspace lành mạnh là bị hỏng.

Mặc định chỉ đóng băng những gì quyết định các byte đầu ra — các ràng buộc provider, và các attachment governance biến đổi nhãn. Các cổng governance phán quyết và linter cùng socket import bị loại ra, vì chúng được thiết kế để thay đổi giữa các môi trường và đóng băng chúng sẽ mang các cổng của một môi trường vào mọi bản checkout. allPlugins: true mở rộng tập hợp ra mọi plugin socket. Tư cách thành viên tính theo từng attachment, không theo từng socket, nên một socket governance mang một attachment biến đổi nhãn và một attachment phán quyết chỉ đóng góp cái đầu tiên theo mặc định.

Mỗi giá trị được đóng băng ở giá trị hiệu lực của nó — giá trị phân giải được khi cấu hình của máy và cấu hình riêng của dự án được hợp nhất — nên một ràng buộc hiện chỉ đến từ cấu hình của máy sẽ được ghi vào dự án và đi cùng với nó. Các thiết lập công cụ trên toàn máy, trong đó có chính sách tin cậy của một registry, không thiết yếu cho build và được giữ nguyên chỗ cũ. Đóng băng hai lần trên một cấu hình không đổi sẽ ghi lại đúng các byte cũ, nên một client có thể thoải mái đề xuất nó: lần gọi thứ hai giữ tài liệu mà người đọc đang mở y như cũ.

Một thay đổi plugin cho bạn biết điều gì

Cả bốn yêu cầu plugin đều ghi theo mặc định, và chúng chia theo thứ chúng ghi: hai yêu cầu thay đổi một tệp cấu hình, và hai yêu cầu tạo ra tài liệu trong workspace. Hai trong số đó — yêu cầu thêm và yêu cầu sinh — nhận dryRun, thực hiện mọi việc khác mà yêu cầu làm nhưng không ghi gì. Hãy đọc chính phần mô tả của câu trả lời về nơi thay đổi được áp dụng thay vì suy ra từ yêu cầu — với một trong số chúng, việc yêu cầu không nói gì về phạm vi có nghĩa là phạm vi rộng nhất.

Một yêu cầu thêm và một yêu cầu gỡ bỏ đều mang scope, và nó được suy ra từ tệp mà thao tác ghi đã phân giải tới. configFile là tệp đó, machineWide cho biết đó có phải là tệp mà mọi workspace trên máy này phân giải qua hay không, và workspaceRoot nêu tên workspace mà phiên này được mở trên đó, nên một câu trả lời có phạm vi workspace cho biết đó là workspace nào. machineWide được đọc từ tệp đã phân giải chứ không từ điều yêu cầu đòi hỏi, và chính điều này ngăn một câu trả lời mô tả một thay đổi trên toàn máy như một thay đổi cục bộ.

🔴 Một yêu cầu thêm loại cli không nêu global cũng không nêu workspace sẽ đăng ký lệnh trên toàn máy. Một phần mở rộng lệnh là công cụ trên toàn máy, nên khi không có ghi đè, nó được ghi vào tệp cấu hình toàn cục mà mọi workspace trên máy này phân giải qua — và lệnh mà nó đăng ký khi đó trở thành một lệnh aggrega cấp cao nhất cho mọi dự án trên máy đó, kể cả những dự án mà không ai trong phiên này nhắc đến. Một yêu cầu thêm loại provider, governance, linter hoặc importer thì ngược lại: chúng định hình bản build của một dự án, nên khi không có ghi đè, chúng được ghi vào chính .aggrega-config.yaml của dự án đó. Một yêu cầu gỡ bỏ tuân theo cùng quy tắc cho cùng các loại. Gửi workspace: true để giữ một phần mở rộng lệnh ở cục bộ, hoặc global: true để đẩy bất kỳ loại nào khác ra tệp dùng chung; gửi cả hai sẽ bị từ chối. Dù theo cách nào, scope trong câu trả lời là tuyên bố có thẩm quyền, và client nên hiển thị nó trước khi hành động dựa trên kết quả.

Một yêu cầu thêm nêu tên thứ đã được áp dụng, và đúng một trong ba trường cho biết đó là loại gì. type lặp lại loại mà mục được thêm cho, và sau đó: identity mang định danh thực thể trần đã ghim phiên bản cho một attachment governance, linter hoặc importer; uri mang địa chỉ artifact oci:// của plugin, cùng với capability mà nó hiện phục vụ, cho một binding provider; và reference mang tham chiếu đã ghim mà các lệnh của nó đã được đăng ký cho một cài đặt cli. Vì vậy, bên gọi đọc loại attachment nào đã được áp dụng từ câu trả lời thay vì suy lại từ loại mà nó đã gửi. Một yêu cầu gỡ bỏ chỉ lặp lại type và query bên cạnh scope của nó và không gì khác — không còn gì để báo cáo thêm về một mục đã biến mất.

Một yêu cầu thêm cũng mang written và, khi dùng dryRun, mang content. written là thứ client dùng để rẽ nhánh: true chỉ ra một tệp cấu hình hiện đã có trên đĩa mà client có thể mở, còn khi dùng dryRun thì nó là false và content mang tài liệu cấu hình mà thao tác ghi lẽ ra đã tạo ra. Hai trường này không bao giờ cùng có ý nghĩa, và tệp mà content dành cho là scope.configFile, nên không có gì trong câu trả lời mang bản sao thứ hai của đường dẫn đó — điều này quan trọng ở đây, vì tệp của một attachment global là tệp mà mọi workspace trên máy này phân giải qua.

Một plugin không có phiên bản nào được phát hành sẽ bị từ chối thay vì được gắn mà không ghim. Một yêu cầu thêm phân giải truy vấn tới một plugin và ghim phiên bản phát hành cao nhất của nó, nên mục mà nó ghi luôn mang một phiên bản. Một plugin có kho lưu trữ không phát hành phiên bản hợp lệ nào sẽ bị từ chối kèm tên của nó, và một phiên bản đã bị thu hồi bởi một retraction mà workspace này tin cậy sẽ bị bỏ qua để dùng phiên bản thấp hơn kế tiếp.

Một phiên bản mà truy vấn nêu tên vẫn được ghim ngay cả khi đã bị thu hồi, và withdrawn cho biết điều đó. Một query viết dưới dạng <name>:<version> sẽ ghim phiên bản đó thay vì phiên bản mới nhất — với mọi loại trừ provider, loại chỉ được gắn theo tên và từ chối phiên bản — và việc nêu tên một phiên bản chính là sự ghi đè: khi một tuyên bố thu hồi được workspace này tin cậy đã thu hồi phiên bản đó, nó vẫn được ghim như thường, và câu trả lời mang withdrawn: true — sự việc mà aggrega plugin add nêu bằng một dòng retraction: trên terminal. withdrawn vắng mặt trong mọi câu trả lời khác, nên sự hiện diện của nó là toàn bộ tín hiệu — và sự vắng mặt của nó không phải là một khẳng định rằng phiên bản không bị thu hồi. Khi không thể đọc được các dấu thu hồi của một phiên bản được nêu tên, withdrawn vắng mặt và retraction mang unscreened, cho biết lý do, giống như với một lần thêm không nêu phiên bản nào gặp cùng lỗi đó; một lần thêm không nêu phiên bản nào thì thay vào đó báo cáo trong retraction kết luận của việc kiểm tra thu hồi về phiên bản nó đã chọn.

Một yêu cầu đồng bộ báo cáo liệu nó có thay đổi gì không, và đó là trường để dựa vào khi hành động. changed phân biệt một thao tác ghi với một lần đồng bộ thấy các bản ghi đã đúng: một tệp không thay đổi được giữ nguyên từng byte, nên client đang giữ tài liệu đó không cần tải lại gì, và chạy yêu cầu hai lần sẽ báo cáo không có thay đổi ở lần thứ hai. entity nêu tên tệp, hostFunctions mang tập đã suy ra, và commands mang bản phản chiếu dưới dạng giá trị chứ không phải dòng mà terminal in ra — mỗi mục gồm một name, một description tùy chọn, và flags, mỗi flag mang name của nó cùng shorthand, description, type và default tùy chọn. Thao tác ghi là nguyên tử, nên client đọc tệp đó trong lúc đồng bộ đang chạy không bao giờ thấy một tài liệu dở dang.

Một yêu cầu sinh chỉ điền đúng một nửa câu trả lời, và chính dryRun của câu trả lời cho biết nửa nào. Theo mặc định, các thực thể được ghi và notices mang những gì quá trình sinh nói về các thao tác ghi mà nó đã thực hiện. Khi dùng dryRun, không có gì được tạo hay sửa đổi: documents mang từng thực thể được sinh dưới dạng path mà nó dành cho và content của nó, để client có thể đưa chúng vào mô hình tài liệu của riêng mình, nơi chúng hiển thị trước khi được lưu và có thể được chỉnh sửa hoặc loại bỏ. Hai nửa không bao giờ cùng được điền, nên cách thực hiện nào đã chạy có thể đọc được từ phản hồi chứ không phải từ điều đã được yêu cầu.

Nơi một yêu cầu plugin GHI luôn nằm bên trong workspace mà yêu cầu đó nêu tên; thứ nó ĐỌC được quyết định theo từng trường. Một đích tuyệt đối, một đích leo ra khỏi thư mục gốc, và một đích dẫn ra ngoài thư mục gốc qua một liên kết đều bị từ chối thay vì được phân giải — nên một yêu cầu sinh không thể tạo thực thể trong một cây thư mục mà phiên của bạn chưa từng được mở trên đó, bất kể nó gửi gì. Một đường dẫn mà yêu cầu chỉ đọc là một câu hỏi riêng, được trả lời theo từng trường chứ không bằng một quy tắc chung cho tất cả: aggrega/pluginGenCatalog đọc một module và overlay của nó từ bất cứ đâu bạn đã chọn, vì một module bạn build nằm dưới thư mục đầu ra của toolchain, và từ chối đọc nó ở đó sẽ là từ chối chính mục đích của thao tác. aggrega/pluginSync đọc hai đường dẫn của nó bên trong workspace, vì yêu cầu đó liên quan đến một tệp mà workspace đã có sẵn. Các yêu cầu định vị ở trên chấp nhận đường dẫn tuyệt đối vì một lý do khác nữa — một tài liệu mà client đã đang mở, được gọi theo bất kỳ cách viết nào mà client đang giữ.

Một yêu cầu thiếu thứ mà thao tác cần sẽ bị từ chối kèm tên trường cần gửi. Một yêu cầu thêm hoặc gỡ bỏ thiếu type hoặc query; một yêu cầu thêm provider thiếu capability, hoặc một yêu cầu thêm governance thiếu role; một yêu cầu thêm cli thiếu acceptCapabilities; một yêu cầu đồng bộ thiếu entity hoặc plugin; một yêu cầu sinh nêu cả hai chế độ chọn hoặc không nêu chế độ nào, hoặc thiếu overlay hoặc outputDir. Mỗi trường hợp trả về mã invalid-params tiêu chuẩn, và thử lại sẽ không thay đổi gì cho đến khi yêu cầu thay đổi. Một yêu cầu gỡ bỏ có truy vấn không khớp mục nào cũng bị từ chối, kèm tên loại, truy vấn và tệp mà nó đã tìm — trường hợp này là trạng thái của cấu hình chứ không phải của yêu cầu, nên thứ cần sửa có thể là bên nào cũng được.

Không có gì được hỏi qua lời nhắc, và quyết định duy nhất lẽ ra phải hỏi một người sẽ đến dưới dạng một trường. Lệnh trên terminal hỏi người đang theo dõi xem họ có chấp nhận các capability đã khai báo của một plugin phần mở rộng lệnh hay không. Không ai theo dõi luồng này, nên acceptCapabilities là thứ bên gọi phải tự lấy và gửi, và một yêu cầu không mang nó sẽ bị từ chối kèm nêu rõ thứ cần gửi, thay vì cài đặt dựa trên một sự đồng ý mà không ai đưa ra. Một daemon được khởi động mà không có khả năng cài đặt phần mở rộng lệnh sẽ từ chối thẳng một yêu cầu thêm cli, thay vì báo cáo một thành công mà không cài đặt gì.

Những kind bạn có thể đề xuất cho người viết

aggrega/getSchema không kèm kind sẽ trả lời những kind bạn có thể nêu tên, và nó trả lời ở hai độ rộng vì client cần độ rộng khác nhau cho công việc khác nhau. Hãy đọc đúng độ rộng bạn đang hỏi.

kinds là mọi token mà binary phản hồi. entityKinds là tập kind mà người viết soạn tài liệu. Danh sách rộng chứa biểu diễn trung gian, lockfile, cấu hình workspace và các hợp đồng socket của plugin bên cạnh các kind bạn soạn — mỗi cái đều là schema thật, nhưng không phải tài liệu mà ai đó viết thành file. Vì vậy, danh sách rộng là danh sách dùng để nối liên kết schema của trình soạn thảo, còn danh sách hẹp là danh sách dùng để xây dựng bộ chọn. Một bộ chọn xây từ danh sách rộng sẽ đề xuất những giá trị mà không schema soạn thảo nào chấp nhận, và người viết chỉ gặp lời từ chối sau khi đã chọn một giá trị.

Tập hẹp cũng hẹp hơn các entity kind, và không schema nào cho bạn biết đó là những kind nào. Một kind do nền tảng sở hữu mà nội dung được viết bên trong tài liệu của kind khác thì không phải là tài liệu để đề xuất cho người viết bắt đầu. Workload là một kind như vậy: nội dung workload được viết trong trường workload: của một Recipe hoặc một FeatureRecipe, hoặc trực tiếp, hoặc từ một file mà trường đó import, nên không có tài liệu workload nào để tự định địa chỉ riêng — xem bề mặt soạn thảo Workload để biết nội dung đó đặt ở đâu. Schema của nó cố định apiVersion và kind y như schema của một kind được soạn, vì đó là điều cho phép nội dung được xác thực tại chỗ nó nằm; các giá trị cố định nhận diện nội dung chứ không làm nó trở nên định địa chỉ được. Vì vậy, chúng không phải là dấu hiệu cho thấy một kind là kind để soạn thảo. entityKinds mang câu trả lời, còn không gì trong các byte của schema mang nó.

Mỗi mục entityKinds mang cả hai cách viết mà client cần, và không cách nào suy ra được từ cách kia. kind là token viết thường nối bằng gạch ngang — gửi lại nó dưới dạng kind cho phương thức này hoặc cho aggrega/scaffoldEntity. documentKind là giá trị mà chính tài liệu mang trong trường kind: ở cấp cao nhất. Với kind có tên gồm nhiều hơn một từ, hai giá trị khác nhau không chỉ ở chữ hoa chữ thường: không thao tác nào trên featurerecipe cho ra được FeatureRecipe. Hãy lấy từng giá trị từ mục thay vì suy giá trị này từ giá trị kia, và client sẽ không còn ánh xạ nào phải tự duy trì.

Mỗi mục cũng cho biết những thao tác nào chấp nhận tài liệu thuộc kind của nó, để một control đề xuất các thao tác đó trên một tài liệu chỉ đề xuất những thao tác không từ chối tài liệu vì kind của nó. acceptedBy mang ba giá trị boolean, mỗi giá trị đều có mặt trong mọi mục, và mỗi giá trị nói về một tài liệu thuộc kind đó được nêu riêng — theo đường dẫn, hoặc theo tên đối với việc kiểm tra — mà không gửi kèm gì khác. singleEntityValidation cho biết aggrega validate <path> có kiểm tra tài liệu thuộc kind đó hay không, thay vì từ chối nó và nêu phạm vi toàn catalog hoặc phạm vi Release sẽ kiểm tra nó. publication cho biết aggrega/publishEntity khi chỉ nêu tài liệu có phát hành nó hay không: một Plugin là false, vì việc phát hành nó còn gắn kèm tệp thực thi mà request nêu trong plugin, nên request chỉ nêu tài liệu sẽ bị từ chối; một Manifest và một Release là false vì cả hai kind đều không được phát hành. inspectionByName cho biết aggrega/entityDefinition có phân giải một tên thành entity thuộc kind đó hay không, với tên được gửi đúng như cách viết khi một entity tham chiếu đến entity khác — một Plugin là <pluginType>/<name>, còn một Recipe hoặc một FeatureRecipe là <capability>/<name>, hoặc chỉ bằng tên khi chỉ có một capability khai báo tên đó. Giá trị true cho biết thao tác không từ chối tài liệu vì nó thuộc kind đó; thao tác vẫn có thể từ chối một tài liệu cụ thể vì nội dung tài liệu đó.

Đừng giữ danh sách của riêng bạn. Những kind nào tồn tại là thuộc tính của binary bạn đang giao tiếp, nên một danh sách viết cứng trong client chỉ khớp vào ngày nó được viết và thôi khớp vào ngày có một kind được thêm — và khi đó người viết thấy kind của họ bị thiếu trong chính control lẽ ra phải đề xuất nó. Hãy hỏi, và câu trả lời sẽ theo binary.

Cả hai nửa đến cùng nhau, và chỉ khi bạn không nêu kind nào. Request nêu một kind sẽ được trả lời bằng schema của kind đó và không mang danh sách nào, nên câu hỏi bạn đã hỏi có thể đọc ra từ response. Một token mà không schema nào phản hồi sẽ bị từ chối, kèm toàn bộ tập hợp lệ trong thông báo, với mã invalid-params tiêu chuẩn, nên lỗi gõ là một request cần sửa chứ không phải điều phải hỏi một người.

Nó trả lời ngay cả trong một workspace không chứa gì. Bộ từ vựng được biên dịch vào binary, nên việc này không cần tài liệu, lockfile hay catalog nào — đó chính là workspace mà người viết đang ở khi bắt đầu tài liệu đầu tiên của họ.

Phản hồi scaffold cho bạn những gì

Phần này nói về việc soạn bản nháp. Dạng còn lại của phương thức ghi một ví dụ chạy được, và câu trả lời của nó được mô tả cùng với phương thức ở trên.

aggrega/scaffoldEntity trả về văn bản. skeleton là YAML cho kind bạn đã nêu: mọi trường mà schema của kind đó yêu cầu, theo thứ tự schema khai báo chúng. Một trường mà schema cố định vào một giá trị duy nhất sẽ được điền sẵn — apiVersion và kind là những trường bạn sẽ nhận thấy — metadata.name mang name bạn đã gửi, và mọi giá trị bắt buộc khác đến dưới dạng placeholder có kiểu theo những gì schema khai báo ở đó: một chuỗi rỗng, số không, false, một danh sách rỗng, một mapping rỗng. kind lặp lại token mà tài liệu được tạo ra cho nó, để một client có nhiều yêu cầu đang chờ có thể xác định câu trả lời thuộc về yêu cầu nào từ chính câu trả lời, thay vì tự giữ một bảng đối chiếu riêng.

Nó không ghi gì cả, và đó là phần cần thiết kế xoay quanh. Phương thức này không tạo tệp, không chọn đường dẫn và không động đến thư mục nào. Những gì bạn nhận được là một tài liệu cần ghi, không phải một tài liệu đã được ghi — vì vậy trình soạn thảo đặt văn bản vào một buffer mới chưa lưu mà tác giả có thể đọc, sửa hoặc bỏ đi, và thời điểm một tệp mới được ghi xuống đĩa vẫn nằm ở nơi có buffer và lịch sử hoàn tác. Không có yêu cầu nào khác nhận tài liệu này và đặt nó vào đâu đó thay cho bạn; việc quyết định một tài liệu mới nằm ở đâu là việc của trình soạn thảo.

Nó không phân giải gì cả, và không cần gì từ workspace. Tài liệu được tạo ra từ các schema mà binary mang theo, nên phương thức không truy cập registry hay mạng, không tra cứu catalog nào và không đọc tệp nào. Nó trả lời như nhau trong mọi workspace, kể cả một thư mục trống chưa có tài liệu Aggrega nào — đó chính là workspace mà một tác giả bắt đầu tài liệu đầu tiên đang ở trong, và là nơi phần lớn các phương thức khác ở đây trước hết sẽ cần một tài liệu hoặc một lockfile.

Cùng một yêu cầu cho ra cùng các byte, dù được hỏi ở đâu. Tài liệu được tạo bởi một phép tính dùng chung với các bề mặt khác cung cấp khả năng này, nên một trình soạn thảo và một trợ lý được hỏi cùng kind và cùng tên sẽ cho tác giả thấy cùng một văn bản khởi đầu.

Skeleton mang các trường mà kind của nó yêu cầu, và nó không phải là một tài liệu hoàn chỉnh. Nó mang các trường bắt buộc và không gì khác: một trường tùy chọn bạn muốn là trường bạn tự thêm, và mỗi placeholder là một giá trị vẫn còn nợ. Hãy điền các placeholder, rồi chạy aggrega/validate trên buffer. Với một thực thể catalog thuộc kind mà aggrega validate kiểm tra như một thực thể đơn lẻ, phương thức đó nêu mọi placeholder còn nợ, mỗi cái tại khóa của nó kèm theo những gì nó cần, theo cùng cách đọc mà lệnh áp dụng cho tệp đã lưu — kể cả một placeholder mà schema chấp nhận để trống, với capability và implements của một Recipe hoặc FeatureRecipe đang soạn thảo là những cái bạn sẽ gặp. Với bất kỳ kind nào khác, nó kiểm tra buffer theo schema của kind đó, nên một placeholder mà schema không chấp nhận để trống — chẳng hạn một phiên bản — sẽ trả về dưới dạng phát hiện của schema đó, còn một placeholder mà schema chấp nhận để trống thì không có phát hiện nào. Xác thực trực tiếp mô tả mục mà mỗi placeholder xuất hiện dưới dạng đó.

Phản hồi import cho bạn biết điều gì

aggrega/import chuyển đổi một nguồn được viết cho công cụ khác thành các tài liệu Aggrega nháp, và nó ghi chúng ra — khác với scaffold ở trên, vốn trả lại văn bản cho bạn. written nêu tên từng tệp đã được ghi xuống đĩa, tương đối với outputDir; files mang mọi tệp mà yêu cầu ghi cùng với content của nó, dù tệp đó có được ghi hay không — mọi bản nháp mà importer tạo ra, rồi đến bản ghi về những gì lần import đã ghi, hoặc dưới sync là những gì lần đồng bộ thay đổi. Hai trường này trả lời hai câu hỏi khác nhau, vì vậy hãy đọc trường ứng với câu hỏi bạn đang đặt ra: cái gì hiện đang nằm trên đĩa, hay cái gì đã được tạo ra.

Bạn chọn nơi đặt các bản nháp, hoặc để cho thư mục gốc của workspace. outputDir là tùy chọn, cũng như aggrega import --output-dir và output_dir của công cụ import của trợ lý: một yêu cầu không nêu thư mục nào sẽ tạo bản nháp bên dưới thư mục gốc của workspace — nơi aggrega import ghi ra khi không được chỉ định đích, bất kể nó chạy ở đâu — còn một yêu cầu có nêu thư mục sẽ tạo bản nháp ở đó. Một thư mục được nêu tên là một đường dẫn bên trong workspace, và một giá trị tương đối được phân giải theo thư mục gốc của workspace chứ không theo một thư mục mà daemon tình cờ đang đứng. source mà bạn chuyển đổi là trường hợp còn lại và không bị giới hạn như vậy: bạn đã chọn tệp hoặc thư mục đó, nên nó được đọc ở bất cứ đâu nó nằm, và việc đọc nó ở đó không làm thay đổi nơi các bản nháp được đặt. Thư mục sẽ được tạo nếu chưa tồn tại. Dưới dryRun không có gì được ghi, và mỗi bản nháp vẫn nêu đường dẫn dành cho nó, tương đối với outputDir mà phản hồi nêu — thư mục bạn đã gửi, hoặc thư mục gốc của workspace.

Một yêu cầu không bao giờ ghi đè lên một Aggregate đã có trong outputDir. Aggregate là tài liệu mà tác giả tiếp tục chỉnh sửa sau khi đã được tạo bản nháp, vì vậy một yêu cầu có bản nháp sẽ rơi vào một tệp được đọc là Aggregate sẽ bị từ chối, kèm tên bản nháp và vị trí của Aggregate đó, và không có gì được ghi cả — kể cả khi dùng dryRun, vì một lần chạy thử từ chối những gì lần ghi từ chối. Thay vào đó, hãy gửi sync để cập nhật nó theo nguồn, hoặc đặt tên một outputDir khác để tạo bản nháp bên cạnh nó. Mọi tệp khác đã có tại một đường dẫn được tạo bản nháp đều bị ghi đè, và một tệp mà lần import trước đã tạo bản nháp nhưng lần này không tạo thì được giữ nguyên tại chỗ. Mọi yêu cầu tạo bản nháp cho bất cứ thứ gì cũng ghi .aggrega-import.json trong outputDir, bản ghi về những gì lần import đã ghi — target mà nó được gửi, nếu có gửi, bản chụp catalog mà nó đã đọc, nếu có đọc, và từng tệp được tạo bản nháp và, trong một Aggregate hoặc Release được tạo bản nháp, từng khóa ở mọi cấp độ sâu, kèm một digest của văn bản được ghi ở đó, mọi tệp được tạo bản nháp khác được ghi lại toàn bộ — và files cùng written mang nó sau các bản nháp. Nó là JSON, nên không có gì đọc các tài liệu YAML của workspace đọc nó; sync, giống như aggrega import --sync, đọc nó để cập nhật các bản nháp theo nguồn của chúng. Một sync không được gửi target sẽ tạo bản nháp cho target mà bản ghi nêu tên, nên nó tạo bản nháp cho Manifest mà lần import trước đã tạo; một lần được gửi target sẽ tạo bản nháp cho target đó, và bản ghi khi đó nêu tên nó. Một target được ghi lại mà không có Recipe nào trong catalog gắn với nó sẽ bị từ chối giống như một target được gửi, với lời từ chối nói rằng target đó là target đã được ghi lại. Vì một Release được tạo bản nháp được ghi lại theo từng khóa, môi trường mà tác giả của nó viết vào chỗ lần import để lại một chú thích cho nó là một khóa do tác giả viết, và một lần sync giữ nguyên nó từng byte.

Gửi sync để cập nhật những gì một lần import trước đã tạo nháp trong outputDir theo nguồn, chỉ thay đổi những gì lần import đã ghi. Mỗi phần được đánh giá theo ba cách — những gì bản ghi nói lần import gần nhất đã ghi ở đó, những gì có trên đĩa, và những gì nguồn hiện tạo nháp. Một phần mà nguồn để nguyên như lần import gần nhất đã ghi sẽ giữ chính xác như trên đĩa, dù tác giả có chỉnh sửa nó hay không. Một phần mà nguồn đã thay đổi sẽ được ghi mới, một phần mà nguồn đã bỏ đi sẽ bị xóa — một tệp được tạo nháp bị xóa nguyên tệp — và một phần mà nguồn có thêm sẽ được thêm vào bên cạnh các phần mà bản nháp nêu xung quanh nó, mỗi việc chỉ diễn ra khi những gì trên đĩa đúng là những gì lần import gần nhất đã ghi và không chứa gì do tác giả thêm vào. Mọi thứ khác được giữ nguyên từng byte: một khóa mà tác giả thêm vào ở bất cứ đâu — một tham số, một Feature, kể cả dưới một thể hiện Component được tạo nháp, một Component khác — một chú thích không được viết ngay phía trên một khóa được tạo nháp, và mọi tệp mà bản ghi không liệt kê. Một lần đồng bộ vào một thư mục không chứa bản ghi và không có gì tại các đường dẫn được tạo nháp sẽ ghi toàn bộ bản nháp, như một yêu cầu không có sync.

drift là những gì một lần đồng bộ đã cập nhật, và đó là câu trả lời cho câu hỏi “nguồn đã thay đổi chưa”. Nó liệt kê từng phần mà lần đồng bộ đã thay đổi — hoặc, dưới dryRun, từng phần nó sẽ thay đổi — theo thứ tự bản nháp nêu chúng, mỗi phần dưới dạng change (added, removed hoặc changed), file, tệp được tạo nháp chứa nó, tương đối với outputDir, và key, các khóa dẫn tới nó trong một Aggregate hoặc Release được tạo nháp dưới dạng một danh sách, để một khóa chứa dấu chấm vẫn là một mục; key để trống khi phần đó là toàn bộ tệp, đó là cách một tệp được tạo nháp mà lần đồng bộ xóa được nêu tên. aggrega import in cùng các mục này ra standard error dưới dạng <change> <key> in <file> hoặc <change> <file>, và mã thoát của nó dưới --sync --dry-run cho biết nguồn có thay đổi hay không; giao diện này không có mã thoát, vì vậy hãy gửi sync cùng dryRun và xem drift có trống hay không. drift là một danh sách rỗng đối với một yêu cầu không phải là đồng bộ, đối với một lần đồng bộ khớp với nguồn của nó, và đối với một lần đồng bộ mà importer không thể hoàn tất. Dưới sync, files mang từng tệp được tạo nháp mà lần đồng bộ thay đổi, cùng nội dung nó gán cho tệp, rồi đến bản ghi khi bản ghi cũng thay đổi, và written nêu tên những tệp đã được ghi xuống đĩa — nên một lần đồng bộ đã khớp trả về cả hai là danh sách rỗng. Một tệp được tạo nháp mà lần đồng bộ xóa được nêu trong drift và không nằm trong danh sách nào: mục removed của nó, với key trống, là nơi duy nhất câu trả lời đề cập đến nó, và dưới dryRun thì nêu tệp mà một lần ghi sẽ xóa.

Một lần đồng bộ không bao giờ ghi lại những gì tác giả đã viết, mà sẽ từ chối. Một lần đồng bộ sẽ thay đổi hoặc xóa một phần mà tác giả đã chỉnh sửa, thêm một phần vào chỗ tác giả đã viết sẵn một phần, hoặc xóa một phần chứa thứ gì đó do tác giả thêm vào sẽ bị từ chối, nêu từng phần như vậy và lý do trên một dòng riêng, theo đúng cách diễn đạt mà aggrega import --sync dùng — <file> <key>: <why>, hoặc <file>: <why> cho toàn bộ tệp — và không có gì được ghi; một chú thích được viết ngay phía trên một khóa được tạo nháp được coi là chỉnh sửa khóa đó. Một lần đồng bộ trên một Aggregate mà không bản ghi nào liệt kê sẽ bị từ chối kèm tên Aggregate và bản ghi, cũng như một lần đồng bộ có bản ghi không đọc được, vì không có bản ghi thì không thể phân biệt các phần của nó với phần của tác giả. Cả hai lời từ chối đều trả về lỗi invalid-params, kể cả dưới dryRun, và nêu sync. Hãy tự tay điều chỉnh từng phần được nêu, hoặc khôi phục những gì lần import đã ghi ở đó, rồi gửi lại yêu cầu.

🔴 halted: true không phải là lỗi, và coi nó là lỗi chính là sai lầm cần tránh khi thiết kế. Một importer không thể chuyển đổi mọi thứ vẫn tạo nháp những gì nó làm được: phản hồi mang các bản nháp đó, written nêu tên chúng, và diagnostics cho biết những gì bị bỏ sót. Đó là câu trả lời hữu ích nhất mà thao tác này đưa ra, và nó đến dưới dạng một kết quả chứ không phải một thất bại chính là để bạn có thể cho tác giả thấy cả hai nửa. Dưới sync, cùng câu trả lời đó không ghi gì — files, written và drift đều trống — vì một bản nháp dở dang sẽ được hiểu là một nguồn đã bỏ đi mọi phần mà importer chưa xử lý tới. Một nguồn mà importer hoàn toàn không đọc được là một trường hợp khác và thực sự trả về lỗi.

Mỗi chẩn đoán mang severity và message, cùng code khi importer có gán. Hãy rẽ nhánh theo code khi bạn muốn phản ứng với một tình huống cụ thể và hiển thị message cho người đọc; severity lấy từ cùng tập giá trị mà mọi socket plugin báo cáo — halt, warn, info — nên halted là bản tóm tắt của các mục chứ không phải một đánh giá riêng. files, written, drift, diagnostics và decisions luôn là mảng, rỗng chứ không vắng mặt.

decisions cho biết import đã phỏng đoán ở đâu. Nó mang một mục cho mỗi nút nguồn mà importer đã ánh xạ, theo thứ tự của importer và đúng như importer báo cáo: sourceNode, gồm id, type và paramsSummary của nút; candidates, mỗi Component trong catalog mà importer đã cân nhắc cho nút đó dưới dạng componentName, score, tier và signals — mức đóng góp của từng tín hiệu, dưới table, category, domainLabels, shape và name; chosen, gồm target mà nó đã chọn, mode mà nó dùng để viết — một reference tới một Component có sẵn hoặc một draft — và tier của lựa chọn; rationale, lý do; và swapHint, cách để chọn khác đi. candidates vắng mặt khi importer không cân nhắc ứng viên nào, chosen vắng mặt khi nó không đưa ra lựa chọn, còn rationale và swapHint vắng mặt khi nó không viết gì. Mọi giá trị đều là của chính importer — cách nó chấm điểm một ứng viên và ranh giới các tier là lựa chọn của nó — vì vậy hãy hiển thị một mục như lời tường thuật của nó về việc ánh xạ chứ không phải như một phán quyết. Các quyết định được trả về cả dưới dryRun lẫn khi halted là true: các phỏng đoán của một lần import dở dang chính là thứ mà tác giả đang xem xét nó cần, và một importer không báo cáo quyết định nào trả về một danh sách rỗng. Nếu bạn hiển thị chúng dưới dạng văn bản, aggrega import đã diễn đạt một quyết định là mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, trong đó điểm là điểm của ứng viên tốt nhất.

Định dạng được nhận diện từ nguồn trừ khi bạn chỉ định nó. Việc nhận diện dùng các chữ ký mà các importer khai báo — của catalog trong workspace cũng như của các importer lõi của trình biên dịch — được thực thể Plugin của mỗi importer ghi lại — cú pháp dùng để đọc nguồn, các tên tệp mà 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 — vì vậy bản thân daemon không biết định dạng nào, và định dạng của một importer mới được nhận diện mà không cần thay đổi gì khác. Việc phát hiện chỉ đọc nguồn bạn đã gửi — với một thư mục, chỉ các tệp mà mẫu tệp của chữ ký chọn — và không dùng mạng, phân tích mỗi tệp nó đọc bằng parser mà catalog của workspace cung cấp cho một cú pháp — hoặc, với cú pháp mà catalog không cung cấp parser, parser do chính trình biên dịch mang theo — một lần cho mỗi cú pháp mà một chữ ký áp dụng cho tên tệp đó dùng để đọc; sau đó importer đọc nguồn qua cùng parser ấy. Một chữ ký không khai báo mẫu tệp nào áp dụng cho tệp bạn gửi bất kể tên gì, và không áp dụng cho tệp nào của một thư mục; chữ ký của các importer Langflow, Flowise và n8n thuộc loại đó và đọc JSON, còn chữ ký của importer Dify đọc YAML, nên việc nhận diện một tệp bạn gửi riêng lẻ sẽ đọc nó dưới dạng JSON và YAML, điều không cần parser nào trong catalog của workspace: trình biên dịch mang sẵn một parser JSON và một parser YAML, và parser do catalog cung cấp sẽ được dùng thay thế. Một nguồn không khớp chữ ký nào bị từ chối, yêu cầu format và liệt kê các định dạng mà các importer công bố — hoặc, với một thư mục, yêu cầu một trong các tệp của nó được gửi riêng lẻ hoặc một format có importer khai báo mẫu tệp, chỉ liệt kê các định dạng đó — theo điều kiện No importer recognises the source (Không có importer nào nhận diện được nguồn); một nguồn khớp chữ ký của nhiều hơn một định dạng bị từ chối kèm tên các định dạng đó, theo điều kiện More than one importer recognises the source (Có nhiều hơn một importer nhận diện được nguồn). data của mỗi lần từ chối mang code và shortCode của điều kiện tương ứng, để client hỏi định dạng dựa trên mã chứ không dựa trên câu chữ. Không trường hợp nào được đoán, vì một định dạng đoán mò sẽ phân giải sai importer và tạo ra kết quả vô nghĩa đầy tự tin. format trong phản hồi là định dạng đã được dùng, dù được phát hiện hay được chỉ định, để một client đã bỏ qua nó biết mình nhận được gì.

Một thư mục bạn gửi được đọc thành các tệp mà importer của nó chỉ định, và thư mục nào nó không đọc được là một lỗi. Khi source chỉ định một thư mục, importer được giao những tệp trong đó mà các mẫu tệp do chữ ký của nó khai báo chọn, trừ thư mục đầu ra build của workspace dist/, 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, bên cạnh các tệp mà mục plugins.importer của nó chỉ định dưới with.sources. Một importer không khai báo mẫu tệp nào, một thư mục không chứa tệp nào được chọn, một tệp của thư mục và một tệp with.sources trùng tên, và một liên kết trong số các tệp mà import sẽ đọc, hoặc trỏ tới một thư mục, dẫn ra ngoài thư mục — mỗi trường hợp đều trả về lỗi mang mã của điều kiện, và không có gì được ghi.

Importer nào chạy là quyết định của workspace, không phải của yêu cầu. Định dạng được phân giải tới importer công bố nó trong số các plugin catalog của workspace và các importer lõi của trình biên dịch — importer mà một mục plugins.importer trong cấu hình workspace gắn vào, nếu nó gắn một trong số đó — vì vậy một yêu cầu không thể chọn một module hay trỏ tới một module trên đĩa. Một định dạng không có importer nào công bố bị từ chối kèm tên định dạng, và một định dạng được hai importer công bố mà không cái nào được gắn — trong đó có một importer lõi và một importer khác tên mà catalog chứa cho cùng định dạng — bị từ chối vì mơ hồ thay vì được phân giải tùy ý.

Một core importer mà máy chưa có sẽ được tải về một lần, bởi lần import đầu tiên cần đến nó. Nó được lấy từ registry mặc định của workspace, ràng buộc với module mà bản phát hành của trình biên dịch công bố và được xác minh giống như lệnh pull xác minh một plugin mà nó tải về: chữ ký theo chính sách tin cậy của registry đó, và các host function mà nó sử dụng. Sau đó nó được giữ trong content cache của workspace, và đây là thứ duy nhất được ghi cho nó: không có lockfile, và không có bản ghi các plugin được tin cậy. Mọi lần import sau đều đọc nó từ đó và không truy cập registry nào. Một module không vượt qua xác minh là một lỗi mang mã điều kiện của nó, và không có gì được giữ lại. Một module không thể tải về (workspace đang ngoại tuyến, không thể truy cập registry của nó, hoặc registry không chứa nó) là một lỗi thuộc A plugin’s .wasm is not on this machine (Tệp .wasm của một plugin không có trên máy này), nêu tên importer, phiên bản của nó và cách đưa module của nó lên máy. Bản thân yêu cầu không nêu registry nào, và một lần import mà mọi importer cùng catalog nó đọc đều đã có trên máy thì hoàn toàn không truy cập mạng.

Khi workspace không nêu thư mục catalog nào, lần import đọc catalog mà registry mặc định của nó xuất bản. Một workspace mà workspace.catalog_dirs, AGGREGA_CATALOG_DIRS và thư mục gốc đều không nêu thư mục catalog nào sẽ đọc catalog của thư viện chuẩn dưới dạng một bản chụp duy nhất có chữ ký, tại catalog/snapshot trên registry mặc định của nó. Một bản chụp được tải về một lần: chữ ký của nó được xác minh theo chính sách tin cậy của registry đó, rồi nó được giữ trong content cache của workspace và được đọc ở đó như một thư mục catalog, ràng buộc với digest của nó, mà không hỏi lại registry nào. Bản chụp mà một yêu cầu đọc: với upgrade, bản mới nhất; nếu không, bản mà bản ghi trong outputDir nêu tên, được tải về theo digest của nó khi máy chưa có; nếu không, bản mà workspace tải về gần nhất dưới dạng bản mới nhất; nếu không, bản mới nhất. Bản ghi mà lần import ghi ra nêu tên bản chụp nó đã đọc, theo digest của nó, để một yêu cầu sau đó vào cùng outputDir đọc cùng catalog. Ở chế độ ngoại tuyến, một yêu cầu phải tải về một bản chụp là một lỗi thuộc The workspace is offline and the step needs the network (Workspace đang ngoại tuyến và bước này cần mạng), nêu rõ cần chạy gì, và upgrade bị từ chối bất kể máy đang có gì, vì chỉ registry mới có thể cho biết bản chụp nào là mới nhất. Một registry không xuất bản bản chụp nào khiến lần import không có catalog, và một mục warn trong diagnostics cho biết điều đó. Một workspace nêu một thư mục catalog sẽ import dựa trên thư mục đó và không tải bản chụp nào, và upgrade không thay đổi gì ở đó.

Dưới dryRun không có gì được tạo. written rỗng, files mang đúng những tệp mà một lần ghi sẽ tạo ra — với sync, là các tệp mà sync sẽ ghi, bên cạnh drift mà nó sẽ cập nhật — và không thư mục nào được tạo — để một trình soạn thảo có thể đưa chúng cho tác giả lưu, sửa hoặc bỏ đi. Mọi việc khác mà một lần ghi làm đều được thực hiện: cùng importer chạy trên cùng nguồn và báo cáo cùng các chẩn đoán, nên một nguồn mà lần ghi sẽ từ chối thì ở đây cũng bị từ chối. Một importer lõi hoặc một bản chụp catalog được tải về dưới dryRun được lưu trong content cache như khi ghi, vì việc có được những gì lần import dựa vào để chạy là một phần của việc chạy nó chứ không phải của việc đặt các bản nháp.

Một đường dẫn mà importer trả về được giữ bên trong outputDir. Đường dẫn của các bản nháp đến từ importer chứ không phải từ bạn, nên một đường dẫn leo ra khỏi thư mục đầu ra sẽ bị từ chối và hoàn toàn không có gì được ghi — kể cả các bản nháp có đường dẫn hợp lệ. Lời từ chối nêu tên đường dẫn vi phạm, cho bạn biết rằng importer mới là thứ cần sửa chứ không phải yêu cầu của bạn.

Mỗi yêu cầu về thực thể trả lời câu hỏi nào

Có bốn yêu cầu ở đây sẽ cho bạn biết về một thực thể, và chúng không thể thay thế cho nhau. Việc chọn giữa chúng phụ thuộc vào thứ bạn đang nắm trong tay khi hỏi.

Bạn đang nắm một con trỏ. aggrega/hover và aggrega/resolve nhận một tệp và một vị trí, rồi xác định thực thể nào được nhắc đến từ những gì được viết ở đó. Chúng bao quát các dạng tham chiếu mà một tài liệu thực sự chứa — một giá trị extends, một kiểu component hoặc feature, implements của một Recipe, các tham chiếu recipe của một Manifest, hai con trỏ đường dẫn của một Release, một đích uses, và metadata.name của chính một thực thể. Hãy dùng chúng khi con trỏ của người dùng là tọa độ: người dùng đang đọc một tài liệu và muốn biết một tham chiếu trỏ tới đâu.

Bạn đang nắm một tên. aggrega/entityDefinition nhận trực tiếp định danh. Không cần mở gì cả, không liên quan đến vị trí nào, và thực thể không cần được nhắc đến ở bất kỳ đâu mà client có thể tìm thấy. Hãy dùng nó khi người dùng gõ một tên, chọn một tên từ danh sách, hoặc đi theo một thứ mà chính client của bạn đã biết định danh — một hover đòi hỏi bạn trước hết phải tìm một nơi tên đó được viết, đó là công việc bạn không cần làm.

Bạn chưa nắm gì cả. aggrega/catalogIndex liệt kê những gì workspace chứa, kèm các trường mô tả cho mỗi thực thể. Hãy dùng nó để điền một bộ chọn, rồi đưa tên đã chọn cho aggrega/entityDefinition.

Bạn đang nắm một Release. aggrega/releaseClosure trả lời về một Release thay vì về một thực thể, và nó là mục bên dưới.

Định nghĩa mà một yêu cầu theo tên trả về là thực thể sau khi được phân giải, chứ không phải như bất kỳ tệp đơn lẻ nào khai báo nó. Một Component hoặc Feature mở rộng một base sẽ được trả về kèm hợp đồng của base đó, thứ không xuất hiện ở đâu trong tài liệu khai báo tên của nó — vì vậy câu trả lời là về thực thể đó là gì, và tự đọc tệp sẽ không cho bạn cùng một kết quả.

Nó được trả về dưới dạng một tài liệu YAML thay vì cấu trúc bên trong phản hồi, và điều đó là có chủ ý: một trụ cột schema có nhiều dạng soạn thảo — nội dung được viết ra, một tham chiếu đến một tài liệu dùng chung, hoặc dấu đánh dấu cho biết nội dung đến từ một base — và tài liệu tái hiện đúng dạng mà quá trình phân giải đã đạt tới, theo thứ tự khóa của chính tác giả. Hãy phân tích nó như một tài liệu nếu bạn cần các trường của nó; hiển thị nguyên trạng nếu bạn đặt nó vào một bảng điều khiển.

Phân biệt hai kiểu từ chối theo tên

Một tên không phân giải ra gì sẽ bị từ chối thay vì được trả lời bằng một tài liệu rỗng, vì một câu trả lời rỗng sẽ báo một lỗi gõ nhầm như thể một thực thể không có gì để nói về bản thân. Có hai cách một tên không phân giải ra gì, chúng đòi hỏi người đọc những việc khác nhau, và bạn phân biệt chúng qua những gì data của lỗi mang theo, chứ không phải bằng cách đọc thông báo:

  • Không có file trong data. Không có gì trong workspace khai báo tên đó và không tầng catalog nào phân giải được nó. Gần như luôn luôn đây là yêu cầu cần sửa — một lỗi gõ nhầm, hoặc một tên từ một catalog mà workspace này không có trên đường dẫn tìm kiếm.
  • Có file trong data. Một tài liệu của workspace có khai báo tên đó, nhưng catalog vẫn không phân giải được gì cho nó. Thực thể đã được viết ra và có thứ gì đó đã từ chối nó, đó là một trạng thái của workspace mà một người phải sửa. Khi đúng một tài liệu mà catalog đã đọc và từ chối khai báo tên đó — nguyên nhân thường gặp — thông báo mở đầu bằng lời từ chối đó, nêu một lần: loại và mã ngắn của nó, tài liệu theo đường dẫn mà nó được báo cáo, và điều gì sai ở nó, chẳng hạn dòng và ràng buộc mà nó vi phạm; sau đó ghi chú rằng tệp đã bị bỏ qua khi tải, và liệt kê mọi tệp khác mà quá trình tải đã từ chối. Nếu không, thông báo nêu tên tài liệu khai báo, liệt kê các tệp mà quá trình tải đã từ chối, và cho biết workspace này đọc các thực thể cục bộ từ đâu và cần thay đổi gì để tài liệu được đọc — phần giải thích được bỏ qua khi một tài liệu bị từ chối khai báo tên đó, vì tài liệu đó vốn đã nằm ở nơi catalog đọc.

Cả hai đều mang mã entity-not-resolvable, vì vậy hãy rẽ nhánh dựa trên sự có mặt của file thay vì dựa trên mã.

Hỏi về một tọa độ

Bạn đang nắm một tham chiếu registry. Hãy gửi nó làm name của aggrega/entityDefinition, và câu trả lời là thực thể được công bố tại tọa độ đó, với cùng dạng kết quả mà một tên nhận được cộng thêm published, được điền từ những gì đã được công bố thay vì từ những gì một catalog đã phân giải:

  • definition là tài liệu thực thể đúng như khi được công bố. Một tọa độ có thực thể được công bố cùng các tệp mà nó khai báo sẽ mang một archive, và tài liệu được giải nén từ đó; một tọa độ có thực thể không khai báo tệp nào mang tài liệu của nó nguyên vẹn, và thực thể của một Plugin được đọc từ manifest của nó thay vì từ tệp thực thi được công bố kèm theo. Không áp dụng kế thừa.
  • authoredLength là độ dài của tài liệu đó, vì định nghĩa ở đây là một tài liệu được soạn thảo chứ không phải bản kết xuất của một tài liệu đã phân giải.
  • file để trống, vì một thực thể được đọc từ registry không có tài liệu nào trên máy này để nêu tên.
  • publishScope bị lược bỏ: bạn đã nắm tọa độ, đó chính là nơi thực thể được công bố.
  • published là những gì đã được đọc, và nó có mặt trong câu trả lời này và không có trong câu trả lời theo tên nào: reference; archive, cho biết các byte của nó có phải là một archive mà tài liệu được giải nén từ đó hay không — false khi tọa độ chứa chính tài liệu; mediaType mà manifest khai báo; và manifestDigest của manifest đó, thứ bạn có thể gửi sau @ thay cho tag để đọc lại chính xác các byte đó.

Yêu cầu truy cập registry mà tham chiếu nêu tên, với thông tin xác thực của người dùng mà daemon này chạy dưới danh nghĩa và chế độ mạng của workspace này, vì vậy một workspace ngoại tuyến sẽ từ chối nó. Các byte được tải về được kiểm tra với digest mà chính manifest của artifact ghi lại cho chúng và không với gì khác — không chữ ký nào được xác minh và không việc thu hồi nào được báo cáo — và không có gì được ghi. Một tham chiếu không đọc được sẽ bị từ chối với entity-not-resolvable, và thông báo mở đầu bằng mã ngắn của điều kiện cho biết lý do — cùng các điều kiện mà aggrega inspect báo cáo — và kết thúc bằng việc cần làm. Một tham chiếu không nêu repository nào, hoặc không có cả tag lẫn digest, là một yêu cầu sai định dạng và bị từ chối là invalid params.

Một closure không phải là đồ thị

aggrega/irGraph và aggrega/releaseClosure được suy ra từ cùng một lần phân giải của cùng một Release và trả lời những câu hỏi khác nhau. Một client đã nhận được đồ thị có thể hợp lý cho rằng nó cũng đã có cái này, nhưng không phải vậy.

Đồ thị cho biết Release triển khai những gì — các nút của nó, các ranh giới mà chúng nằm trong, cái gì được nối với cái gì, cùng các giá trị và attachment mà mỗi nút mang. Đó là bức tranh.

Closure cho biết những gì đã được kéo vào để xây dựng nó, và ở những phiên bản nào. Mọi thực thể mà Release chạm tới, dù nó có trở thành một nút hay không; các tài liệu dùng chung mà các thực thể đó dựa vào; và các plugin định hình đầu ra. Đó là bảng kê vật tư.

Không cái nào có thể khôi phục được từ cái kia. Một thực thể có thể được chạm tới mà không bao giờ xuất hiện như một nút — Recipe mà một Manifest ánh xạ một kiểu component tới được chạm tới bởi mọi lần build và không là nút trong lần nào cả — và một nút không mang phiên bản mà kiểu của nó đã phân giải tới. Vì vậy người đọc hỏi “vì sao phiên bản này thay đổi?”, “thay đổi tài liệu dùng chung này sẽ ảnh hưởng tới gì?”, hoặc “Release này thực sự phụ thuộc vào gì?” là đang hỏi về closure, còn người đọc hỏi “Release này triển khai những gì?” là đang hỏi về đồ thị.

Những gì yêu cầu closure không làm. Nó không render gì và không công bố bất cứ điều gì nó tìm thấy. Cụ thể, nó không đưa ra cảnh báo drift nào và không có khuyến nghị render nào: những thứ đó thuộc về yêu cầu đã hỏi chúng, và việc công bố thay thế toàn bộ một lớp chẩn đoán, nên một danh sách mà công bố sẽ xóa những gì yêu cầu đồ thị đã đặt trước mắt người dùng. Hãy yêu cầu đồ thị khi bạn muốn có kết luận về drift. Điều duy nhất nó có công bố không phải là phát hiện của riêng nó: một yêu cầu phát hiện lockfile đã mất sẽ rút lại cảnh báo drift dựa trên nó, bất kể đó là yêu cầu nào — xem Nhận biết lockfile.

Nó cần một lockfile, giống như đồ thị. Các phiên bản mà danh sách báo cáo là những phiên bản Release này đã phân giải tới, và một workspace chưa ai chuẩn bị thì chưa phân giải chúng. Một danh sách được tạo ra mà không có lockfile sẽ báo cáo những gì catalog tình cờ chứa hôm nay, đó là một câu hỏi khác với việc Release này phụ thuộc vào gì. Lời từ chối nêu tên lockfile và Release, để client có thể đề xuất trực tiếp aggrega pull --release <release>.

kind trên một mục closure chỉ có mặt khi nó được biết. Một tham chiếu được thu thập từ một vị trí trong tài liệu, và có những vị trí cho biết loại mà chúng trỏ tới trong khi những vị trí khác thì không. Trường này được báo cáo khi vị trí tham chiếu đã ghi lại một loại và bị bỏ qua khi không có, thay vì được đoán từ hình dạng của tên. Nó được báo cáo dưới dạng từ mà tác giả viết ở đầu tài liệu, cũng là từ mà mọi bề mặt báo cáo closure dùng cho cùng một mục.

Cùng một từ yêu cầu cùng một tài liệu ở nơi khác. aggrega inspect <release> --closure trả lời câu hỏi này ở dòng lệnh, và chế độ release của công cụ describe trả lời nó qua giao thức công cụ trợ lý. Cả ba đều chạy một lần phân giải trên Release, nên chúng không thể bất đồng về việc một Release phụ thuộc vào gì. Xem aggrega inspect “Closure phụ thuộc”.

Mô hình bộ nhớ đệm

Các thao tác dựa trên bộ nhớ đệm: hãy gọi aggrega/validate cho một tệp trước khi gọi hover / completion / resolve / diagnostics trên tệp đó. Lệnh gọi khởi tạo này không cần một Release — một lần xác thực không nêu Release nào vẫn phân tích bộ đệm soạn thảo và nạp dữ liệu vào bộ nhớ đệm — nên các thao tác này hoạt động được trong một workspace không có Release nào để nêu. Bộ nhớ đệm phân tích được đối chiếu với thời điểm sửa đổi trên đĩa của từng tệp ở mỗi lần đọc, nên các thay đổi từ bên ngoài (một lần lưu trong trình soạn thảo, một lệnh git checkout) được tự động nhận biết — aggrega/invalidate của trình soạn thảo là một tối ưu hóa, không phải một yêu cầu để đảm bảo tính đúng đắn.

Bộ nhớ đệm thuộc về workspace đã khởi tạo nó. Một tệp được xác thực trong một workspace được lưu đệm cho workspace đó, nên cùng đường dẫn ấy khi được hỏi trong một workspace khác sẽ được báo là chưa được xác thực, thay vì được trả lời từ mục của workspace thứ nhất. Chính điều này giữ cho một câu hỏi về workspace thứ hai không trả lời sai, cũng không làm workspace thứ nhất mất trạng thái đã nạp sẵn — và aggrega/invalidate cũng chỉ xóa workspace mà nó nêu.

Yêu cầu chẩn đoán trong khi một lần xác thực đang chạy

Một lần xác thực khởi tạo hai thứ về một tệp — kết quả phân tích mà nó chuyển cho các thao tác khác, và các phát hiện mà nó báo cáo — và nó khởi tạo chúng cách nhau một khoảnh khắc. aggrega/diagnostics là yêu cầu duy nhất đọc cả hai: nó cần kết quả phân tích để biết tệp là tệp nó có thể trả lời, và nó trả lời dựa trên các phát hiện. Vì vậy, một yêu cầu đến giữa hai thời điểm đó sẽ quyết định rằng nó có thể trả lời trong khi chưa có gì để trả lời.

Thay vào đó, nó chờ. Gửi aggrega/diagnostics cho một tệp đang được xác thực ngay lúc này thì phản hồi sẽ đến khi lần xác thực đó kết thúc, mang theo những gì nó tìm thấy. Mỗi tệp chỉ có một câu trả lời đúng bất kể thời điểm, và đó là câu trả lời bạn nhận được — nó không bao giờ là một danh sách rỗng cho một tệp mà lần xác thực sắp báo lỗi, vốn là câu trả lời sai duy nhất mà client không thể khắc phục, vì không có gì nhắc bạn hỏi lại về một tệp bạn đã được báo là sạch. Các thao tác dựa trên vị trí khác — hover, completion, resolve, findReferences, findImplementations — đọc kết quả phân tích và trả lời từ kết quả phân tích, nên chúng không có gì để chờ và không bao giờ chờ.

Có hai điều kết thúc việc chờ sớm, và cả hai đều là thứ bạn đã có. $/cancelRequest cho id của yêu cầu đó sẽ dừng nó, và một lệnh aggrega/shutdown hợp tác cũng dừng nó. Không điều nào cần thêm gì vào yêu cầu.

Và việc chờ có giới hạn. Nếu lần xác thực chưa kết thúc trong khoảng thời gian daemon dành cho nó, yêu cầu bị từ chối với mã validation-in-flight thay vì được trả lời rỗng — xem Mã lỗi. Sự từ chối đó có nghĩa là công việc bạn đang chờ thực sự đang diễn ra, nên việc cần làm là hỏi lại sau ít phút; đó không phải tín hiệu để gửi thêm một lần xác thực khác, vốn sẽ chỉ thêm việc mà không trả lời được gì.

Một daemon chạy từng yêu cầu một sẽ trả lời chúng theo thứ tự đến, nên không có gì chồng lấn và không bao giờ phải chờ. Một daemon chạy chúng đồng thời sẽ trả lời cùng các câu hỏi theo cùng một cách, và việc chờ chính là điều làm cho điều đó đúng: câu trả lời bạn nhận được là câu trả lời mà một thứ tự tuần tự lẽ ra đã cho bạn.

Kích thước trong một câu trả lời

Một câu trả lời báo cáo một lượng byte sẽ báo cáo nó hai lần: dưới dạng số, và dưới dạng chính lượng đó được viết ra. Trường dạng viết là tên của trường số kèm thêm Text — size và sizeText, totalSize và totalSizeText, reclaimedBytes và reclaimedBytesText, và cứ thế cho mọi câu trả lời mang một kích thước.

Hãy hiển thị dạng viết và tính toán bằng con số. Mục đích của việc gửi cả hai là để client không bao giờ phải tự viết ra một kích thước: daemon viết nó bằng cùng bộ định dạng mà dòng lệnh dùng, nên aggrega cache status và aggrega/cacheStatus hiển thị một bộ đệm nhất định giống hệt nhau, đến tận cách làm tròn. Một client tự soạn văn bản của riêng nó sẽ lệch khỏi đó ngay lần đầu tiên nó khác biệt về một giá trị biên.

Dạng viết dùng đơn vị nhị phân — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB — đây cũng là bộ từ vựng mà aggrega/cacheEvict chấp nhận trong maxSize, nên một kích thước đọc từ một câu trả lời có thể được gửi lại trong yêu cầu tiếp theo mà không cần viết lại. Trên mức byte, văn bản mang một chữ số thập phân, nên nó nêu lượng đó theo cách người đọc muốn thấy chứ không chính xác đến từng byte; khi bạn cần số đếm chính xác, đó là việc của trường số.

Khi con số là tùy chọn thì văn bản cũng tùy chọn theo, và hai trường không bao giờ chỉ có một nửa: kích thước plugin trong câu trả lời publish mang cả pluginSize và pluginSizeText cùng nhau hoặc không mang trường nào.

Mỗi yêu cầu đều nêu tên workspace mà nó liên quan

Hãy gửi workspaceRoot trong mọi yêu cầu: đường dẫn tuyệt đối của thư mục gốc workspace mà yêu cầu đó tác động. Daemon không giữ workspace nào của riêng nó và không ghi nhớ workspace nào giữa các yêu cầu, nên điều mà một yêu cầu được trả lời là về workspace mà nó đã nêu và không gì khác. Hai yêu cầu nêu hai workspace sẽ nhận hai câu trả lời, và không câu nào thấy được các entity, Releases, kết quả phân tích đã lưu đệm hay chẩn đoán của workspace kia.

Một yêu cầu không nêu workspace nào sẽ bị từ chối với lỗi invalid-params tiêu chuẩn, nêu tên tham số đó, và một giá trị rỗng cũng vậy, vì nó không chỉ ra workspace nào và được trả lời như một workspace bị thiếu. Hai dạng khác cũng bị từ chối vì cùng lý do, mỗi dạng được nêu trong thông báo: đường dẫn tương đối, vì thư mục gốc workspace không có gì để làm mốc tương đối; và đường dẫn không phải là một thư mục đang tồn tại, vì workspace là một cây thư mục.

Ba yêu cầu không cần workspaceRoot, và mỗi yêu cầu như vậy là vì đối tượng của nó không phải là một workspace. aggrega/getSchema và aggrega/scaffoldEntity trả lời dựa trên các schema được biên dịch sẵn vào tệp nhị phân đang chạy, nên workspace không đóng góp gì cho cả hai — chính điều đó cho phép cả hai trả lời trong một thư mục chưa ai chuẩn bị. aggrega/initialize là yêu cầu thứ ba, và đó là nơi bạn khai báo một workspace thay vì tác động lên nó. Dạng còn lại của aggrega/scaffoldEntity, tức ghi hoặc liệt kê các ví dụ chạy được của tài liệu, thì có tác động lên một workspace, và yêu cầu cho dạng đó nêu tên một workspace như mọi yêu cầu khác.

Trạng thái lưu đệm của mỗi workspace được giữ riêng biệt, và việc nêu một workspace thứ hai không làm tốn gì của workspace thứ nhất. Chỉ mục catalog, bộ đệm phân tích và các chẩn đoán của một workspace thuộc về workspace đó, nên một câu hỏi về nơi khác không loại bỏ những gì một trình soạn thảo đã tích lũy cho thư mục mà ai đó đang mở. Hai cách viết của cùng một thư mục gốc là một workspace, nên một đường dẫn chứa . ở giữa hoặc dấu phân cách bị lặp sẽ đến cùng trạng thái đã được làm nóng như dạng viết thông thường của nó.

Khai báo workspace mà bạn muốn nhận chẩn đoán được đẩy về

Chẩn đoán đến theo hai cách: bạn yêu cầu chúng, hoặc daemon đẩy chúng về. Daemon chỉ đẩy chẩn đoán cho workspace bạn đã khai báo lúc bắt tay. Mọi yêu cầu khác trả lời bằng các phát hiện của nó trong chính phản hồi của nó và không đẩy gì.

Hãy khai báo nó bằng cách gửi workspaceRoot trong aggrega/initialize. Đó là toàn bộ những gì việc khai báo làm — nó không neo bất cứ thứ gì, và không yêu cầu nào sau đó được trả lời dựa trên nó.

Lý do giới hạn nó nằm ở mục đích của một chẩn đoán được đẩy. Việc đẩy là điều giữ cho danh sách vấn đề của trình soạn thảo luôn cập nhật khi ai đó đang gõ, và đó chính là điều sai khi làm với một câu trả lời mà không ai yêu cầu xem: nếu không có quy định này, một câu hỏi về workspace thứ hai — chẳng hạn từ một công cụ khác dùng chung daemon — sẽ lấp đầy danh sách vấn đề của người đọc bằng những phát hiện về các tệp họ chưa từng mở. Giới hạn việc đẩy giúp câu hỏi của một bên gọi không lọt vào danh sách vấn đề của bên gọi khác.

Trường này là tùy chọn, và ba điều bạn có thể muốn nói qua nó là phân biệt được:

bạn gửi gìchẩn đoán được đẩy đến đâulúc bắt tay báo cáo gì
không gì cảworkspace mà tiến trình được khởi chạy trên đóworkspace đó
một thư mục gốc workspaceworkspace đóworkspace đó
chuỗi rỗngkhông đâu cả — không chẩn đoán nào được đẩymột thư mục gốc rỗng

Không gửi gì sẽ giữ việc đẩy chẩn đoán ở workspace mà tiến trình được khởi chạy trên đó, nên một client không khai báo gì sẽ nhận chẩn đoán cho workspace đó. Gửi chuỗi rỗng là cách khai báo trung thực cho một bên gọi không phải trình soạn thảo và không có danh sách vấn đề nào cần đồng bộ: mọi phát hiện vẫn đến với nó, trong phản hồi cho yêu cầu đã tạo ra phát hiện đó.

Một workspace được khai báo được phân giải đúng như một workspace được nêu trong yêu cầu, nên một khai báo nêu đường dẫn tương đối, hoặc đường dẫn không phải là thư mục, sẽ bị từ chối ngay lúc bắt tay thay vì để chẩn đoán được đẩy đến một nơi không mong đợi.

Thư mục gốc workspace và Release đang hoạt động

Daemon phân giải mỗi workspace mà một yêu cầu nêu tên theo cùng cách mọi lệnh aggrega phân giải, và Cấu hình mô tả điều gì neo một thư mục gốc và theo thứ tự nào. Có hai hệ quả quan trọng với một client. Một .aggrega-config.yaml không có khối workspace: thì không neo: nó vẫn đóng góp các thiết lập của mình, nhưng một tệp thiết lập trơn không thể biến mọi thư mục cha thành thư mục gốc workspace. Và khi không có gì neo, thư mục làm việc được dùng — daemon vẫn khởi động và các thao tác đơn giản là không phân giải được gì, thay vì từ chối chạy.

Tiến trình cũng được khởi chạy trên một workspace, lấy từ --workspace-root hoặc bằng cách đi ngược lên từ thư mục làm việc của nó, và việc phân giải đó làm đúng hai việc và không gì khác: nó xác định kích thước nhóm worker, vốn là thuộc tính của tiến trình chứ không của yêu cầu nào, và nó là khai báo mặc định cho các chẩn đoán được đẩy. Không yêu cầu nào được trả lời dựa trên nó.

Cấu hình cũng là cùng một chuỗi phân tầng mà mọi lệnh đọc, và Cấu hình là nơi mô tả nó. Điều daemon thêm vào chỉ là việc đọc cấu hình của mỗi workspace được thực hiện một lần, khi workspace đó được nêu tên lần đầu, và được dùng lại cho mọi yêu cầu sau về nó. Một tệp cấu hình mà chuỗi phân tầng đó sẽ đọc và là một liên kết dẫn ra ngoài workspace — .aggrega-config.yaml của chính workspace, hoặc lớp phủ do CI sở hữu bên cạnh nó — sẽ không được đọc, ở đây cũng như tại terminal, và không có gì khác mà tệp đó lẽ ra cấu hình được đọc thay thế. Điều khác với terminal là những gì vẫn được trả lời. Daemon khởi chạy trên một workspace như vậy vẫn khởi động, và thông báo điều đó một lần trên luồng lỗi của nó; một yêu cầu nêu tên workspace đó được trả lời như sau trong cả hai trường hợp. aggrega/releaseCandidates và aggrega/catalogIndex — hai yêu cầu liệt kê những gì một workspace chứa — trả lời nó, được đọc mà không có cấu hình nào: các tài liệu của chính workspace được liệt kê, không thư mục catalog nào được đọc, và tệp bị giữ lại được nêu tên trong unreadLinkedFiles, dù việc tìm kiếm có gặp nó hay không. Cái tên đó là cách một client nhận biết rằng cấu hình của workspace dẫn ra ngoài nó. Mọi yêu cầu khác nêu tên workspace — một bản build, một đồ thị, một lần kiểm tra hợp lệ, Release mặc định, cấu hình hiệu lực, một thao tác ghi, và aggrega/catalogIndex theo nghĩa của một Release — đều được quyết định bởi cấu hình đó, nên nó bị từ chối với lỗi invalid-params mang E0321 — read-leads-out-of-workspace trong data của lỗi — và câu nêu tên liên kết cùng nơi nó dẫn tới. Bước bắt tay cũng trả lời cho một workspace như vậy, báo cáo defaults làm configSource của nó, vì không tệp cấu hình nào đóng góp điều gì mà các danh sách dùng để trả lời. Hãy gỡ liên kết, hoặc làm cho nó dẫn tới một tệp bên trong workspace, và yêu cầu tiếp theo sẽ đọc cấu hình. Bên dưới các tệp của dự án là lớp toàn cục: tệp mà --config nêu tên trên dòng lệnh đã khởi động daemon, cho mọi workspace nó phục vụ; nếu không thì tệp mà biến môi trường AGGREGA_CONFIG nêu tên khi nó được đặt; và nếu không nữa thì vị trí mặc định — trên Windows là aggrega\config.yaml bên trong thư mục mà biến môi trường APPDATA nêu tên, và ở nơi khác là aggrega/config.yaml bên trong thư mục mà XDG_CONFIG_HOME nêu tên, dự phòng về ~/.config/aggrega/config.yaml — được nạp khi có mặt. Các giá trị mặc định tích hợp nằm dưới lớp đó.

Các thao tác tác động lên một Release nhận Release đó làm tham số; daemon không tự chọn Release nào. Một workspace vẫn khai báo Release mà nó trỏ tới, và một chuỗi phân tầng bốn bước đọc khai báo đó: trường cấu hình build.authoring_release, sau đó là tệp đánh dấu .aggrega/active-release, sau đó là phép suy đoán một-Release-duy-nhất-trong-workspace, rồi đến phương án dự phòng chỉ dùng Aggregate. Vì vậy một tệp đánh dấu bạn ghi được ưu tiên hơn phép suy đoán, và một tệp đánh dấu nêu tên một Release không thể nạp sẽ rơi xuống phép suy đoán chứ không xuống phương án dự phòng. Một tệp đánh dấu nêu tên một Release nằm ngoài workspace — bằng đường dẫn tuyệt đối, bằng đường dẫn leo ra khỏi thư mục gốc, hoặc qua một liên kết dẫn ra ngoài nó — sẽ không được đọc, trừ khi cấu hình workspace của bạn nêu tên Release đó làm build.authoring_release hoặc làm một khóa của workspace.releases: cấu hình là cách để tiếp cận một Release được giữ bên ngoài workspace, còn tệp đánh dấu thì không. Khi đó chuỗi phân tầng tiếp tục đúng như với một tệp đánh dấu mà nó không thể nạp, và khi nó không chọn được gì, trace cho biết lý do trên dòng của tệp đánh dấu và reason trong câu của nó về tệp đánh dấu.

aggrega/activeRelease báo cáo điều mà chuỗi phân tầng đó chọn, và đó là một gợi ý cho client chứ không phải một thiết lập mà daemon hành động theo. Hãy hỏi daemon thay vì tự đọc các đầu vào của chuỗi phân tầng: trường cấu hình và tệp đánh dấu là hai trong bốn đầu vào, nên đầu vào nào bạn đọc cũng chỉ cho biết lựa chọn của workspace khi nó tình cờ là đầu vào thắng. Một tệp đánh dấu nêu tên một Release không thể nạp là trường hợp rõ nhất — chuỗi phân tầng chọn một Release hoàn toàn khác, còn người đọc tệp đánh dấu sẽ báo cáo Release đã thất bại.

Chuỗi phân tầng chạy khi bạn hỏi chứ không chạy trước, điều này có hai hệ quả đáng để dựa vào. Bước bắt tay luôn nhanh bất kể kích thước cây thư mục, vì nó không chờ việc duyệt workspace. Và câu trả lời theo sát workspace: hãy ghi một tệp đánh dấu — bằng aggrega/setActiveRelease, yêu cầu này trả lời bằng chính lựa chọn mới — sửa cấu hình, thêm hoặc xóa một tệp Release, rồi hỏi lại, và bạn nhận được câu trả lời mới từ cùng daemon. Việc đổi Release bạn làm việc không bao giờ đòi hỏi khởi động lại daemon — client chỉ cần gửi một release khác trong yêu cầu tiếp theo.

Các thao tác tìm kiếm toàn bộ workspace thay vì một buffer — completion, hover, resolve, findReferences và findImplementations — liệt kê YAML dưới thư mục gốc workspace, và việc liệt kê đó tuân theo .gitignore. Mọi .gitignore từ thư mục gốc workspace xuống tới thư mục của chính tệp đều đóng góp, với tệp gần nhất được ưu tiên, nên một tệp YAML mà kho mã của bạn bỏ qua sẽ không được đề xuất làm ứng viên hoàn thành và không được báo cáo là một định nghĩa hay một tham chiếu. Một .gitignore là liên kết dẫn ra ngoài workspace sẽ không được đọc, nên một tệp ở nơi khác trên máy không bao giờ quyết định tài liệu nào của workspace được tìm kiếm. Do đó các cây vendored và đầu ra được sinh nằm ngoài kết quả liên tệp mà không cần thiết lập loại trừ riêng nào để duy trì — và một tài liệu bạn mong được tìm thấy nhưng đã bị bỏ qua sẽ không xuất hiện, đây là trường hợp đáng kiểm tra khi một tham chiếu có vẻ bị thiếu. Các Components và Features mà completion cũng đề xuất từ catalog_dirs đã cấu hình của bạn là một cách đọc khác: chúng đến từ các thư mục đó như được cấu hình — cùng các thư mục mà một bản build của một Release đọc khi cấu hình không cấp cho Release đó thư mục riêng, hoặc, với một yêu cầu nêu tên một Release, các thư mục riêng của Release đó — nên các thực thể của một thư mục catalog được đề xuất dù có .gitignore bao phủ nó hay không — trừ một thực thể nằm sau một liên kết dẫn ra ngoài thư mục mà các lần đọc của thư mục catalog phải ở bên trong, thực thể đó không được đọc và không được đề xuất.

Một yêu cầu nêu tên một Release sẽ đọc các thư mục catalog của Release đó, cũng chính là các thư mục mà một lần build Release đó tại terminal đọc: các thư mục riêng của nó, khi cấu hình workspace cấp cho nó dưới workspace.releases, và catalog_dirs của workspace trong trường hợp còn lại. Điều đó áp dụng cho aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate và aggrega/lint khi nêu tên một Release, aggrega/attachCandidates và aggrega/attachmentContainer khi gửi tới một nút trong đồ thị của một Release, và aggrega/connectionAtPosition, cùng các yêu cầu mà phần tiếp theo liệt kê khi chúng nêu tên một Release. Vì vậy, một phiên trả lời được cho mọi Release trong một workspace giữ một biến thể catalog cho mỗi Release, mỗi Release từ biến thể riêng của nó, mà không cần gửi gì ngoài đường dẫn của Release. Một yêu cầu không liên quan đến một Release đơn lẻ nào — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover và resolve khi không nêu tên Release nào, và aggrega/attachCandidates khi gửi tới một thực thể hoặc một tập nhãn — sẽ đọc catalog_dirs của workspace. aggrega/lint khi không nêu tên thực thể nào cũng như Release nào là ngoại lệ trong một workspace nêu tên các Releases dưới workspace.releases: ở đó nó kiểm tra toàn bộ catalog một lần cho mỗi Release, mỗi lượt trên các thư mục của Release đó, như Công bố các quy ước, theo yêu cầu và ở mỗi lần chỉnh sửa mô tả. Xem Cấp cho một Release các thư mục catalog riêng.

Trả lời theo phạm vi của một Release

aggrega/catalogIndex, aggrega/entityDefinition và năm yêu cầu bắt đầu từ một con trỏ — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences và aggrega/findImplementations — không liên quan đến một Release đơn lẻ nào, và mỗi yêu cầu nhận một release tùy chọn để khiến nó liên quan đến một Release. Đó là một đường dẫn tương đối so với gốc workspace, tuân theo cùng hợp đồng mà các yêu cầu nhận Release khác áp dụng; một giá trị không nêu tên tệp Release nào, hoặc nêu tên một thư mục, sẽ bị từ chối thay vì được trả lời theo phạm vi của workspace trong khi trông như theo phạm vi của Release.

Những gì một Release tiếp cận được, cho mọi yêu cầu ở đây: các tài liệu workspace nằm dưới các thư mục catalog mà ngăn xếp của nó đọc, và mọi tài liệu workspace không nằm dưới thư mục catalog nào — một Release, Aggregate của nó và Manifest của nó được viết bên cạnh các catalog. Một tài liệu workspace nằm dưới một thư mục catalog mà chỉ các Releases khác đọc thì không thuộc câu trả lời của nó: không được liệt kê, không được phân giải, không được đề xuất. Chính điều đó giữ cho các biến thể của cùng một thực thể, được giữ cạnh nhau cho các Releases khác nhau, không bị nhầm lẫn với nhau.

  • Danh sách. Nêu tên một Release sẽ liệt kê các thực thể mà Release đó thấy. Các Features được liệt kê là những Features mà các thư mục catalog của Release đó khai báo, và một tài liệu workspace nằm dưới một thư mục catalog mà chỉ các Releases khác đọc sẽ bị loại ra — vì vậy một workspace giữ một biến thể của một thực thể cho mỗi Release sẽ liệt kê đúng một biến thể mà Release đó dùng để build, thay vì mọi biến thể cạnh nhau. Một tài liệu không nằm dưới thư mục catalog nào, chẳng hạn một Release, Aggregate của nó và Manifest của nó được viết bên cạnh các catalog, thuộc về danh sách của mọi Release.
  • Tra cứu theo tên. Nêu tên một Release sẽ phân giải tên qua các thư mục catalog của Release đó, vì vậy một tên mà nhiều biến thể khai báo sẽ phân giải tới biến thể mà Release đó dùng để build. Một tên mà các thư mục của nó không phân giải được sẽ bị từ chối kèm một giải thích nêu mục của Release đó dưới workspace.releases, vì mục đó chính là thứ mà lần tra cứu đã đọc. Một tham chiếu registry không nhận Release, và bị từ chối nếu kèm một Release: nó được đọc từ registry công bố nó, bất kể Release nào được nêu tên.
  • Hover và go-to-definition. Khi nêu tên một Release, tham chiếu tại con trỏ trước tiên được phân giải qua các thư mục catalog của Release đó, theo thứ tự mà cấu hình workspace đưa ra — cùng cách phân giải mà một lần tra cứu theo tên trong phạm vi của Release đó thực hiện — vì vậy thực thể được hiển thị, và tài liệu được mở, là biến thể mà các thư mục đó phân giải tới, ngay cả khi một tài liệu workspace ở nơi khác khai báo cùng tên. Chỉ khi không có tài liệu nào dưới các thư mục đó trả lời cho nó thì các tài liệu workspace mà Release đó tiếp cận được mới được tìm kiếm. Khi không nêu tên Release nào, thứ tự ngược lại: các tài liệu workspace được tìm trước, vì vậy một tham chiếu mà một tài liệu workspace trả lời sẽ giữ câu trả lời đó, và catalog_dirs riêng của workspace chỉ được tham khảo khi không có tài liệu nào khai báo tên đó — đây là cách tìm ra một thực thể mà chỉ một thư mục catalog đã cấu hình chứa, kể cả một thực thể nằm ngoài cây workspace. Khi trình soạn thảo đang giữ một bản chưa lưu của tài liệu mà các thư mục của một Release phân giải tới, và bản đó vẫn khai báo tên, câu trả lời được đọc từ bản đó, vì vậy vị trí rơi đúng vào dòng mà trình soạn thảo hiển thị.
  • Completion. Khi nêu tên một Release, các tên được đề xuất là những tên mà các tài liệu workspace mà Release đó tiếp cận được khai báo, cùng với các Components và Features mà các thư mục catalog của Release đó khai báo.
  • Tham chiếu và triển khai. Khi nêu tên một Release, một vị trí trong tài liệu workspace mà Release đó không tiếp cận được sẽ không được báo cáo, vì vậy một biến thể được giữ cho Release khác không bao giờ được liệt kê là tham chiếu hoặc triển khai của Release này.
  • Những gì có thể gắn vào một nút đồ thị. aggrega/attachCandidates gửi tới một nút trong đồ thị của một Release luôn theo phạm vi của Release đó — xem What an attach-candidate response tells you (Phản hồi attach-candidate cho bạn biết điều gì).

Khi không nêu tên Release nào, câu trả lời dựa trên các thư mục catalog riêng của workspace, như đoạn ở trên mô tả.

Truy cập registry và ghi dữ liệu

Hầu hết các yêu cầu ở đây trả lời từ workspace và từ những gì đã được lưu trong cache, và không ghi gì cả. Một số ít yêu cầu được nêu tên làm nhiều hơn, và chúng được phân chia theo hai trục độc lập: yêu cầu truy cập tới đâu, và những gì nó thay đổi lan rộng tới đâu.

Các yêu cầu đi ra registry chia thành loại đọc và loại xuất bản. aggrega/resolveDependencies tải về những gì một Release cần, và aggrega/build cũng thuộc nhóm này khi — và chỉ khi — trường autoPull của nó yêu cầu phân giải các phụ thuộc trước, khi đó nó truy cập registry và ghi lockfile trước khi render; aggrega/registryUpdate duyệt qua mọi registry đã cấu hình để xây dựng lại chỉ mục tìm kiếm cục bộ; aggrega/pluginAdd tìm trong registry đã cấu hình plugin mà yêu cầu nêu tên và đọc các phiên bản đã xuất bản của nó để ghim một phiên bản; aggrega/registryAdd hỏi registry mà nó đăng ký về chính sách tin cậy mà registry đó công bố, trừ khi yêu cầu từ chối việc tải về hoặc cung cấp chính sách của riêng nó, và aggrega/configInit hỏi registry mà nó đang khởi tạo điều tương tự; aggrega/explainError lấy gói tài liệu mà nó dùng để đọc phần giải thích một điều kiện, một lần, khi cache mà mọi dự án trên máy dùng chung không có bản sao nào được bước kiểm tra chữ ký của chính workspace chấp nhận — xem aggrega explain; aggrega/scaffoldEntity khi được gửi example hoặc list sẽ lấy cùng gói đó với cùng điều kiện, và khi ghi thì sau đó ghi ví dụ vào một thư mục mới của workspace; aggrega/import tải một importer lõi từ registry mặc định của workspace, một lần, khi máy chưa có nó, và, trong một workspace không nêu thư mục catalog nào, tải bản chụp catalog đã xuất bản mà nó đọc — xem Phản hồi import cho bạn biết điều gì; và aggrega/entityDefinition đọc thực thể mà một tham chiếu registry nêu tên khi tham chiếu đó được gửi làm name của nó, mà không ghi gì. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts và aggrega/deprecateArtifact ghi vào registry — các byte, một chữ ký, hoặc một dấu thu hồi. Một yêu cầu chỉ truy cập registry khi nó được gửi để làm việc đó: một danh sách báo cáo những gì cấu hình ghim, một lượt tìm kiếm đọc một bản chụp ngoại tuyến, và một lượt xuất bản được yêu cầu với dryRun tính toán những gì nó sẽ gửi và không liên hệ với ai.

Quy định này nói về thời điểm một thao tác chạy, không phải về bề mặt nào chạy nó. Một thao tác tải về hoặc ghi chạy vì một yêu cầu đã nêu tên nó, và không bao giờ là tác dụng phụ của việc kiểm tra hợp lệ một tài liệu, xem xét một đồ thị hay liệt kê các thực thể của một workspace. Vì vậy một trình soạn thảo kiểm tra hợp lệ ở mỗi lần gõ phím không truy cập mạng và không ghi lại lockfile nào, còn một thao tác “phân giải phụ thuộc” mà người dùng nhấp vào làm đúng những gì aggrega pull làm — cùng một lượt phân giải, đằng sau cả hai bề mặt, ghi ra một lockfile giống hệt từng byte và lấp đầy cùng một cache artifact.

Không có gì được hỏi qua lời nhắc. Không ai theo dõi luồng này, nên danh tính được phân giải từ một nguồn thông tin xác thực được cung cấp hoặc có sẵn trong môi trường và không bao giờ bằng cách hỏi. Ở chỗ lệnh terminal lẽ ra sẽ đặt câu hỏi cho một người — một registry cần thông tin xác thực, một năng lực mà nhiều plugin provider cùng phục vụ, nội dung mà một lượt thu hồi cần mang — yêu cầu thất bại với thông báo nêu rõ cần cung cấp gì thay vì chặn lại chờ một câu trả lời sẽ không bao giờ đến. Một lượt từ chối giữ nguyên workspace như cũ: không lockfile nào được ghi và không bản ghi dở dang nào bị để lại, và một lượt xuất bản không thể phân giải được thông tin xác thực sẽ từ chối trước khi bất kỳ byte nào đến registry.

Một số thay đổi vượt ra ngoài workspace này, và câu trả lời cho biết đó là những thay đổi nào

Một yêu cầu nêu tên một workspace, nên một câu trả lời không nói gì về phạm vi của chính nó được hiểu là nói về workspace đó. Với một số yêu cầu trong nhóm này cách hiểu đó sẽ sai, nên mỗi yêu cầu mang theo phạm vi của nó và client nên hiển thị phạm vi đó trước khi hành động dựa trên kết quả.

Xuất bản, ký và thu hồi vượt hẳn ra ngoài máy, đó là phạm vi rộng nhất của mọi thứ ở đây. Các thao tác ghi khác dưới đây thay đổi những gì máy này phân giải; các thao tác này thay đổi những gì mọi người phân giải từ registry đó nhận được. Các byte đã xuất bản là thứ mà mọi bên dùng registry đó nhận, và việc xuất bản lại nội dung khác đè lên một tag bị từ chối thay vì được chấp nhận, nên không yêu cầu nào ở đây rút lại một lượt xuất bản — cách xử lý là xuất bản một phiên bản mới. Chữ ký và dấu thu hồi được gắn như các mục ngang hàng với artifact thay vì thay thế nó, nên bản thân các byte không bị động đến; nhưng bất kỳ ai tải artifact về sau đó cũng tải cả chúng, và không thứ nào trong hai thứ này có thể thu hồi được từ người đã có nó. Thu hồi là thao tác dễ hiểu sai nhất trong ba: phiên bản vẫn tải về được, trong khi một retraction mà workspace tin cậy sẽ loại nó khỏi những gì một lượt phân giải ở đó sẽ chọn.

Việc ký dùng thông tin xác thực, và bạn nên biết chúng đến từ đâu trước khi kết nối một client. Ký không dùng khóa phân giải một identity token, theo thứ tự, từ identityToken trong yêu cầu, rồi AGGREGA_IDENTITY_TOKEN trong môi trường của daemon, rồi endpoint OIDC của GitHub Actions có sẵn trong môi trường nếu truy cập được, rồi SIGSTORE_ID_TOKEN. Khi không nguồn nào cho ra token, thao tác từ chối và nêu rõ cần gửi gì; nó không bao giờ mở trình duyệt, vì không có ai để xem. Ký bằng khóa là phương án ngoại tuyến, và yêu cầu không nêu đường dẫn khóa nào: những gì một yêu cầu đọc đều nằm trong workspace mà nó nêu tên, và khóa riêng không bao giờ được giữ trong workspace, nên khóa đến từ khối signing: trong cấu hình riêng của workspace đó. Xem aggrega sign để biết hai chế độ ký và mỗi chế độ liên hệ với đâu.

Mỗi câu trả lời trong bốn câu trả lời đều mang reach, chứa registries — mọi host registry mà lệnh gọi đã gửi tới, mỗi host được nêu một lần, theo thứ tự lệnh gọi gửi tới nó lần đầu, nên một lô ký hoặc một tệp lô có các tham chiếu trải trên nhiều registry sẽ nêu tên từng registry — và beyondThisMachine, được suy ra từ những gì lệnh gọi thực sự đã gắn chứ không phải từ những gì nó yêu cầu: true đúng khi nó đã tải lên nội dung hoặc gắn một chữ ký, một ngày xuất bản hay một dấu deprecation, và false với một lượt chạy thử và với một lệnh gọi thấy mọi thứ nó định gắn đã có sẵn — một lượt xuất bản chạy lại trên một phiên bản đã hoàn chỉnh, hoặc một lô ký mà mọi tham chiếu đều đã mang một chữ ký xác minh được. Một lượt chạy thử vẫn nêu tên đích mà nó lẽ ra sẽ gửi tới. Hãy hiển thị nó trước khi hành động dựa trên kết quả.

Đăng ký hoặc gỡ bỏ một registry mặc định sẽ ghi vào cấu hình dùng chung cho mọi workspace trên máy. Một registry và các danh tính bạn tin cậy trên đó thường giống nhau ở bất cứ đâu bạn làm việc, nên mục đó được ghi vào đây trừ khi yêu cầu gửi workspace: true. Hệ quả cần được nói rõ: aggrega/registryAdd và aggrega/registryRemove thay đổi những gì mọi dự án trên máy đó dùng để phân giải, kể cả các dự án chưa ai trong phiên này nêu tên. Cả hai câu trả lời đều mang scope, với configFile đã được ghi và machineWide cho biết đó có phải là tệp dùng chung hay không. Gỡ bỏ là thao tác nghiêm trọng hơn trong hai, vì thêm lại không phải là cùng một hành động — chính sách tin cậy đã được ghim đã mất, và một lần đăng ký sau sẽ ghim bất cứ thứ gì registry công bố vào lúc đó.

Khởi tạo một cấu hình mặc định cũng ghi vào chính tệp dùng chung đó, và vì cùng lý do. aggrega/configInit đăng ký một registry và chính sách tin cậy của nó, vốn là công cụ trên toàn máy, nên khi không có ghi đè nó ghi vào cấu hình mà mọi dự án trên máy dùng để phân giải — và nó truy cập registry đó một lần để đọc chính sách mà registry công bố. Câu trả lời của nó mang cùng cặp scope mà hai phương thức registry mang. Nó khác chúng ở một điểm đáng để dựa vào: nó từ chối thay vì ghi đè một tệp cấu hình đã tồn tại, nên nó không thể thay thế một cấu hình mà ai đó đang dùng trừ khi yêu cầu gửi force. Cố định cấu hình là trường hợp ngược lại: aggrega/configCapture không nhận ghi đè nào, luôn ghi vào tệp cấu hình riêng của dự án và không truy cập registry nào, nên không việc gì nó làm hiển thị với dự án khác. Xem Một lần ghi cấu hình để lại gì.

🔴 Theo mặc định, việc thêm hoặc gỡ một plugin mở rộng lệnh ghi vào chính tệp dùng chung đó, và đây là điều cần đọc kỹ. aggrega/pluginAdd và aggrega/pluginRemove nhận một type, và khi không gửi giá trị ghi đè nào thì type quyết định nơi ghi. Một mục provider, governance, linter hoặc importer định hình bản build của một dự án, nên nó được ghi vào cấu hình riêng của dự án đó. Một mục cli là công cụ dùng cho toàn máy, nên một lần thêm có type cli mà không nêu global lẫn workspace sẽ đăng ký lệnh vào tệp cấu hình toàn cục mà mọi workspace trên máy này dùng để phân giải — lệnh trở thành một lệnh aggrega cấp cao nhất cho mọi dự án trên máy đó, kể cả những dự án chưa ai trong phiên này nêu tên, và việc rút lại là một thao tác gỡ riêng chứ không phải một lần hoàn tác. Gửi workspace: true để giữ nó cục bộ. Cả hai câu trả lời đều mang scope, với configFile đã được ghi và machineWide cho biết đó có phải tệp dùng chung hay không, được suy ra từ tệp mà thao tác ghi phân giải tới. Một lần thêm cũng truy cập registry mà nó đã tìm kiếm, nên nó nằm trên cả hai trục cùng lúc. Xem Một thay đổi plugin cho bạn biết điều gì.

Hai yêu cầu plugin còn lại chỉ ghi bên trong workspace. aggrega/pluginSync ghi tệp thực thể Plugin mà yêu cầu nêu tên, còn aggrega/pluginGenCatalog ghi các thực thể được sinh ra vào dưới outputDir mà yêu cầu nêu tên — cả hai đều ghi bên trong workspace mà yêu cầu đã nêu, cả hai đều từ chối một đích là đường dẫn tuyệt đối hoặc phân giải ra ngoài workspace, và không cái nào hiển thị với dự án khác. aggrega/pluginGenCatalog đọc module và overlay của nó từ bất cứ nơi nào bạn đã chọn, điều này không mở rộng nơi nó ghi: hai thứ được phân giải theo các quy tắc khác nhau, nên một lần sinh có thể đọc một module bạn build ở bất cứ đâu trong khi các thực thể nó tạo ra vẫn nằm bên trong workspace. aggrega/pluginGenCatalog với dryRun không ghi gì cả mà trả nội dung lại.

Việc ghim một thực thể cũng chỉ ghi bên trong workspace, và truy cập các host mà nguồn của nó nêu tên. aggrega/pin ghi entity.lock bên cạnh thực thể mà yêu cầu nêu tên, là một đường dẫn bên trong workspace, và nạp vào bộ đệm nội dung của workspace các nguồn mà nó đã tải về; không gì nó ghi hiển thị với dự án khác. Nó truy cập ra ngoài để phân giải từng nguồn từ xa mà thực thể nêu tên — một kho chart, một host Git, một URL — đó cũng là phạm vi truy cập mà aggrega/resolveDependencies có đối với các nguồn một Release sử dụng. aggrega/resolveDependencies và aggrega/publishEntity khi được gửi pinSources sẽ chạy chính bước này, nên mỗi yêu cầu đó cũng ghi bên cạnh các thực thể nó ghim; vì vậy một lần xuất bản có ghim sẽ chạm tới workspace cũng như registry. Một lần xuất bản không ghim thì không ghi gì bên cạnh thực thể, nhưng vẫn truy cập các host đó: so sánh tệp lock với những gì bước này sẽ ghi lại nghĩa là phải tải đầy đủ từng nguồn từ xa mà thực thể khai báo.

Việc cài skill trợ lý nằm trong workspace trừ khi yêu cầu gửi global. aggrega/skillsInstall ghi thư mục skill dự án của từng trợ lý được nêu tên bên trong workspace mà yêu cầu nêu tên, và không có gì nó ghi ở đó hiển thị với dự án khác; scope trong câu trả lời của nó mang machineWide là false. Với global: true, thay vào đó nó ghi thư mục theo người dùng của từng trợ lý dưới thư mục home, mà trợ lý đó đọc trong mọi dự án trên máy, và machineWide là true. Dù thế nào, nó cũng không truy cập registry hay mạng nào.

Việc gỡ một thông tin xác thực đã lưu có phạm vi rộng hơn bất cứ thứ gì khác ở đây mà dừng lại trong máy này. aggrega/logout thay đổi kho thông tin xác thực, và kho đó được dùng chung không chỉ bởi mọi dự án trên máy mà bởi mọi công cụ khác xác thực tới cùng các registry — nên một thông tin xác thực bị gỡ qua một phiên sẽ mất đối với tất cả chúng, và aggrega/registryList cũng sẽ báo nó không có trong mọi workspace khác. Câu trả lời của nó mang scope với machineWide, luôn là true: kho này không có dạng theo phạm vi workspace để phân giải tới, nên không có giá trị ghi đè nào để gửi và không có gì để một yêu cầu chọn tham gia. scope cố ý không nêu tệp nào, khác với các thao tác ghi cấu hình ở trên. Kho này ủy quyền cho bất kỳ credential helper hay keychain hệ điều hành nào mà máy đã cấu hình, nên việc gỡ thường được phục vụ bởi một thứ hoàn toàn không phải là tệp, và việc nêu một đường dẫn sẽ chỉ bạn tới một vị trí mà việc gỡ không nhất thiết đã chạm tới.

Việc gỡ không phải là đảo ngược của việc xác thực, và một client không nên đưa ra nó như vậy. Bề mặt này gỡ một thông tin xác thực chứ không lấy về một thông tin xác thực: muốn có lại thông tin xác thực nghĩa là phải xác thực lại bằng aggrega login tại một terminal, vì việc lưu một thông tin xác thực cần một bí mật do người gõ vào và không ai đang theo dõi luồng này. Vì vậy một thao tác “đăng xuất” mà client đưa ra là một chiều tính từ đây. Điều phân biệt hai việc là thao tác có phải lấy một thứ gì đó từ bên đang điều khiển nó hay không — việc gỡ mang giá trị duy nhất của nó trong yêu cầu, còn việc lấy một thông tin xác thực thì không — chứ không phải là có người tham gia hay không, vì cả hai đều do một người chọn.

Việc thu hồi nội dung bộ đệm cũng vươn ra ngoài workspace. Các kho module đã biên dịch và plugin-describe được dùng chung bởi mọi dự án trên máy, nên aggrega/cachePrune, aggrega/cacheEvict và aggrega/cacheClear có thể gỡ nội dung mà một dự án khác phụ thuộc vào. Mỗi lần gỡ mang reach của lớp mà nó thuộc về, và mỗi câu trả lời mang scope.machineWideClasses. aggrega/cacheStatus mang cùng reach trên mọi lớp dù nó không thay đổi gì, vì một client đang quyết định có thu hồi hay không cần nó trước khi hành động.

Việc làm mới chỉ mục tìm kiếm thì ngược lại. aggrega/registryUpdate truy cập mọi registry đã cấu hình, và những gì nó ghi nằm dưới thư mục bộ đệm đã cấu hình riêng của workspace này — nên nó không thay đổi gì mà dự án khác dùng để phân giải. indexRoot trong câu trả lời nêu tên thư mục đó.

Một lần làm mới một phần vẫn trả lời thay vì thất bại. Một yêu cầu nêu tên một registry mà việc làm mới thất bại là một lỗi, vì không có câu trả lời nào để đưa ra. Một yêu cầu làm mới mọi registry đã cấu hình thành công ngay cả khi một số, hoặc tất cả, thất bại: những registry đã làm mới được lập chỉ mục và ghi, failed nêu tên phần còn lại, và mỗi host mang lỗi riêng của nó. Hãy đọc failed thay vì dựa vào việc có lỗi hay không.

Việc một registry có truy cập được hay không là một khóa, không phải là cách đọc thông điệp. Một host thất bại mang unreachable: true khi registry chưa bao giờ được truy cập — tên của nó không phân giải được, một kết nối tới nó bị từ chối hoặc không mở được, hoặc không thể thiết lập một kết nối bảo mật tới nó — và lời từ chối của một yêu cầu nêu tên một registry mang cùng khóa đó trong data của nó. Một registry đã được truy cập và thất bại, với một danh sách tự lặp lại hoặc một trạng thái lỗi, không mang khóa nào, và error của nó, hoặc thông điệp của lời từ chối, cho biết nó đã trả lời gì. Khóa được đọc từ chính lỗi đó, nên nó không phụ thuộc vào cách bộ phân giải của máy này diễn đạt một lỗi, và nó chỉ được đặt khi lỗi cho thấy registry chưa bao giờ được truy cập: một lỗi không cho thấy điều gì theo cả hai hướng, chẳng hạn một giới hạn thời gian đã hết mà không có ghi nhận nào về bước nó đã làm gián đoạn, được báo cáo mà không có khóa này. Hãy xác định một registry là chưa được truy cập dựa trên khóa, và hiển thị lỗi làm lý do.

Dòng lệnh báo cáo chính lần duyệt đó bằng một mã thoát khác không, và việc bạn là bên đọc nào quyết định mã thoát đó có giá trị gì. Đối với một người tại terminal, nó không phải là toàn bộ thông tin: aggrega registry update in ra số registry đã chọn mà nó đã lập chỉ mục, những gì mỗi registry tìm thấy, những registry nó không lập chỉ mục, và nơi chỉ mục được ghi — nên phần tóm tắt cho biết điều gì đã xảy ra còn trạng thái thoát chỉ cho biết liệu tất cả có thành công hay không. Đối với một script, nó là toàn bộ thông tin, vì lệnh đó không cung cấp chế độ đầu ra có cấu trúc, nên trạng thái thoát của nó là phán quyết máy đọc được duy nhất có sẵn. Đó là lý do hai bề mặt trả lời cùng một lần duyệt một phần theo cách khác nhau và cả hai đều đúng: bề mặt này trao cho một bên gọi có cấu trúc failed và thành công, còn dòng lệnh chỉ có một bit để dùng và dùng nó cho “có registry nào bị bỏ sót không”.

Theo dõi một thao tác kéo dài

Hầu hết các yêu cầu ở đây trả lời từ những gì đã có trên đĩa và trả lời ngay lập tức. Một số ít thực hiện công việc thật trước — phân giải các phụ thuộc của một Release, ghim các đầu vào bên ngoài của nó, xuất bản, ký, thu hồi — và bên gọi phải chờ. Những yêu cầu đó báo cáo việc chúng đang làm trong khi làm, và việc này là tùy chọn bật theo từng yêu cầu.

Việc bật tùy chọn gồm hai bước, theo thứ tự này.

  1. Khai báo capability khi bắt tay, và chờ phản hồi. Gửi capabilities.window.workDoneProgress: true trong aggrega/initialize. Đừng gửi bất cứ thứ gì khác cho đến khi phản hồi đó đến: các yêu cầu được phục vụ đồng thời, nên một yêu cầu được ghi trước khi bắt tay được trả lời có thể chạy song song với chính lần bắt tay vốn để thương lượng cho nó. Mọi client vốn đã phải tuân theo thứ tự đó của giao thức; đây là thêm một điều phụ thuộc vào nó.
  2. Đặt một token vào params của yêu cầu. Thêm workDoneToken vào params của yêu cầu mà bạn muốn được báo cáo. Giá trị do bạn chọn — một chuỗi hoặc một số — và chính nó gắn các thông báo với lần gọi đó. Hãy tạo một token mới cho mỗi lần gọi.

Thông báo. Mỗi thông báo là $/progress với params.token được đặt bằng token của bạn và params.value mang một payload:

value.kindmangkhi nào
begintitle — điều đang diễn ra, bằng một cụm từ bạn có thể hiển thị cho người đọcmột lần, khi công việc bắt đầu
reportmessage — một dòng trong lời tự thuật của chính thao tácbất kỳ số lần nào, khi thao tác ghi chúng ra
endkhông có gì ngoài loạimột lần, khi công việc kết thúc

Đối chiếu theo token, không bao giờ theo id của yêu cầu. Một thông báo không mang id — nó không phải là phản hồi cho bất cứ điều gì — và token là thứ duy nhất trong đó trỏ ngược về lần gọi của bạn. Điều này là có chủ ý: trong nhiều client, id của yêu cầu thuộc về tầng truyền tải và không bao giờ đến được đoạn mã đã phát lệnh gọi, trong khi token là một giá trị mà đoạn mã đó đã nắm giữ.

Một report mang văn bản của chính trình biên dịch. Thông điệp là một dòng mà thao tác đã ghi trong lúc làm việc, được chuyển tiếp với khoảng trắng bao quanh bị loại bỏ và không thay đổi gì khác — không viết lại, không tóm tắt, không soạn lại — và một dòng mà thao tác ghi trống sẽ bị bỏ qua thay vì được báo cáo như một thông điệp rỗng. Vì vậy client hiển thị đúng những gì nó nhận được. Đây cũng là tính chất mà các chẩn đoán của chính phản hồi có: một điều kiện giữ một cách diễn đạt, dù có bao nhiêu bề mặt báo cáo nó.

Một bước mà thao tác phải chờ cũng là một report. Khi thao tác bước vào một bước mà nó phải chờ — đọc một registry, tải một artifact, biên dịch một plugin — một report mang tên của bước đó, bằng chính những từ mà dòng lệnh hiển thị bên cạnh biểu tượng chờ của nó cho cùng bước ấy. Chỉ những bước được bước vào giữa begin và end mới được báo cáo.

Một dòng đầu ra là một report. Một thao tác ghi nhiều dòng cùng lúc tạo ra một thông báo cho mỗi dòng, và một dòng mà thao tác ghi thành nhiều phần được báo cáo khi nó hoàn chỉnh — nên một thông điệp không bao giờ là nửa câu.

Không có tỷ lệ và không có phần trăm, và đó không phải là một thiếu sót đang chờ được bổ sung. Các thao tác báo cáo ở đây xử lý một tập hợp mà kích thước không được biết khi công việc bắt đầu — một lần phân giải duyệt qua bao nhiêu tham chiếu, một lần xuất bản tải lên bao nhiêu layer — nên bất kỳ tỷ lệ nào cũng sẽ là bịa đặt. Hãy vẽ một chỉ báo không xác định và hiển thị message mới nhất.

Các frame đến trước phản hồi và không bao giờ đến sau nó. Một begin đến khi công việc đã thực sự bắt đầu, nên một yêu cầu bị từ chối vì params — một đường dẫn tuyệt đối, một trường bắt buộc bị thiếu — không tạo ra thông báo nào cả, chỉ có lỗi của nó. end đến trước phản hồi, và việc thao tác có thành công hay không nằm trên phản hồi chứ không được lặp lại trong end.

Dừng công việc là một thông báo riêng. Gửi $/cancelRequest với id mà bạn đã dùng để gửi yêu cầu. Token không đóng vai trò gì trong việc hủy, và việc hủy không chặn các frame đã được gửi.

Những yêu cầu nào báo cáo, và điều gì xảy ra với phần còn lại

Đúng những yêu cầu này báo cáo: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.

Hai điều đúng với mọi yêu cầu trong số đó, và cả hai là lý do chúng có trong danh sách: nó truy cập một registry hoặc một URL từ xa thay cho bạn, nên thời gian nó mất được quyết định bởi thứ gì đó bên ngoài máy; và nó vốn đã tự ghi lời tự thuật của mình trong khi chạy — lời tự thuật mà một người theo dõi terminal đọc. Vì vậy việc báo cáo trao cho bạn chính lời tự thuật đó chứ không phải một bản thứ hai được soạn riêng để truyền đi, và không có gì trong những việc thao tác thực hiện phải thay đổi để tạo ra nó.

Mọi yêu cầu khác chấp nhận token và không gửi gì. Gửi một token là vô hại chứ không phải lỗi: nó được chấp nhận, không có thông báo nào đến, và câu trả lời giống hệt câu trả lời bạn sẽ nhận được nếu không có nó. Vì vậy một client có thể gắn token vào bất cứ yêu cầu nào nó muốn và đơn giản là không vẽ gì khi không có gì đến.

🔴 Đừng hiểu sự im lặng là “yêu cầu này tức thì.” Hầu hết phần còn lại đúng là trả lời từ những gì đã có trên đĩa — một lần kiểm tra hợp lệ, một hover, một completion, một đồ thị, một danh sách cache, một lần đọc cấu hình — nhưng không phải tất cả: làm mới chỉ mục registry, thêm một plugin, kiểm tra trước khi xuất bản, và lần mở rộng đầu tiên của một mã trên một máy không có tài liệu nào mà workspace được phép đọc đều truy cập registry, còn biên dịch một Release là công việc thật. Những yêu cầu đó mất bao lâu thì mất bấy lâu và hiện không báo cáo gì. Hãy hiển thị một chỉ báo không xác định cho bất kỳ yêu cầu nào bạn sẵn sàng chờ, và coi các thông báo là chi tiết bạn nhận được khi có, chứ không phải là thứ cho bạn biết công việc đang diễn ra.

Hai trường hợp từ chối

Cả hai đều là lỗi invalid-params và cả hai đều nêu việc cần làm, vì một token lặng lẽ không làm gì sẽ khiến bạn chờ một luồng không bao giờ đến.

  • Một token từ một phiên không khai báo capability window.workDoneProgress sẽ bị từ chối, kèm tên capability cần khai báo. Hãy khai báo nó khi bắt tay, hoặc bỏ token đi.
  • Một token không phải chuỗi cũng không phải số sẽ bị từ chối, kèm tên hai dạng hợp lệ. Một token vắng mặt, và một null tường minh, không bị từ chối — cả hai đều có nghĩa là bạn không yêu cầu báo cáo.

Nhận biết lockfile

Daemon kiểm tra lockfile xem có bị lệch (drift) hay không ở mỗi aggrega/irGraph, đối chiếu với Release mà yêu cầu đó nêu tên, và báo độ lệch dưới dạng cảnh báo không chặn. Cảnh báo nêu tên lệnh ghi lại lockfile đó có chứa Release, viết đúng như yêu cầu đã gửi — aggrega pull --release theo sau là release bạn đã gửi, đúng cách viết tại terminal ở thư mục gốc của workspace. aggrega/irGraph yêu cầu phải có lockfile. Không có bước kiểm tra riêng lúc khởi động: một yêu cầu cho biết nó nói về Release nào, nên kết luận được tính cho Release đó khi được hỏi, thay vì tính một lần cho một Release chọn trước.

Cảnh báo lệch biến mất khi lockfile của nó biến mất. Cảnh báo được công bố trên lockfile mà nó được nêu ra, và một lockfile không còn tồn tại thì không còn pin nào để bị lệch — lệnh mà cảnh báo nêu tên sẽ ghi một tệp mới thay vì sửa tệp cũ. Vì vậy, mọi yêu cầu phát hiện lockfile bị thiếu đều rút cảnh báo trước khi từ chối với lỗi thiếu lockfile: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates và aggrega/attachmentContainer khi được hỏi về một nút của đồ thị, và aggrega/connectionAtPosition. Việc rút cảnh báo đến dưới dạng một thông báo aggrega/publishDiagnostics cho lockfile mang một danh sách rỗng, trước lời từ chối. Nó đến từ yêu cầu nào trong số đó biết về việc xóa trước tiên, nên một client báo việc xóa rồi hỏi bất cứ điều gì về Release đó sẽ được xóa cảnh báo mà không cần hỏi riêng về đồ thị. Một lockfile vẫn còn và vẫn bị lệch giữ cảnh báo của nó qua mọi yêu cầu kể trên. aggrega/invalidate nêu tên lockfile sẽ bỏ những gì daemon giữ cho nó nhưng không gửi gì; yêu cầu tiếp theo mới là thứ báo cho client. Và một lockfile mà daemon thậm chí không thể kiểm tra — chẳng hạn một lockfile có thư mục mà daemon không được phép đọc — không rút gì cả, vì nó có thể vẫn còn đó và cảnh báo có thể vẫn đúng.

aggrega/build và aggrega/buildPreview cũng yêu cầu có lockfile, và chúng buộc Release tuân theo nó thay vì chỉ cảnh báo — chúng render theo tư thế của một bề mặt xuất ra artifact, nên một lockfile không còn khớp với những gì Release phân giải ra sẽ dừng chúng lại, trong khi ở một thao tác kiểm tra nó chỉ gây cảnh báo. Một Release không có lockfile bị từ chối với lỗi thiếu lockfile. Ngoại lệ là một bản build có trường autoPull yêu cầu phân giải dependency trước: bản build đó ghi lockfile rồi render dựa trên những gì nó đã ghi, và một lockfile được tạo theo cách đó không bị kiểm tra lệch lần thứ hai, vì quá trình phân giải ghi ra nó đã chạy cùng phép kiểm tra đó trên nó trước khi ghi và không ghi lockfile nào mà phép kiểm tra đó từ chối.

Một lockfile có tồn tại nhưng không ghi digest cho một plugin thì không chặn đồ thị — một lockfile vắng mặt thì có. Đó là hai điều kiện và chỉ điều kiện thứ hai gây từ chối. aggrega/irGraph không buộc các byte nó phân giải phải khớp với digest đã ghi: một pin mà nó không thể xác minh được báo cáo thay vì bị từ chối, và đồ thị được vẽ với phát hiện đó trên bảng Problems, vì một trình soạn thảo từ chối vẽ đồ thị sẽ để người đọc không có gì, trong khi một báo cáo để lại cho họ điều gì đó để xử lý. Ở những nơi khác plugin cũng vẫn chạy, kèm một cảnh báo nói rằng không có gì đã kiểm tra các byte của nó. Điều aggrega/irGraph từ chối là lockfile bị thiếu: nó dừng trước khi phân giải bất cứ thứ gì và trả lời bằng lỗi thiếu lockfile, nêu tên lockfile nó đã tìm và Release, để client có thể đề xuất trực tiếp aggrega pull --release <release> — hoặc gửi aggrega/resolveDependencies cho Release đó và ghi lockfile mà không rời phiên. Tách biệt hai điều này là quan trọng, vì một đồ thị đã vẽ là một bức tranh mà người đọc sau đó suy luận dựa vào, và một đồ thị dựng từ các byte không được kiểm tra được vẽ y hệt như một đồ thị đã được kiểm tra, với phát hiện nằm ở chỗ người đọc không nhìn tới. Vì vậy, một đồ thị không phải là kết luận về các byte đằng sau nó — aggrega/build và aggrega/buildPreview là các bề mặt buộc một Release tuân theo các digest đã ghi, dừng lại ở chỗ thao tác kiểm tra chỉ báo cáo.

aggrega/validate, khi một yêu cầu nêu tên một Release, chỉ đọc lockfile của Release đó để lấy các pin và thông báo ngừng hỗ trợ — và không đọc lockfile nào cho một entity của catalog mà nó kiểm tra như một entity đơn lẻ, giống như dòng lệnh không đọc lockfile nào. Nó không buộc các plugin nó chạy phải khớp với digest đã ghi, và không dựng lại tập gắn transform-plugin từ lockfile — nó xác thực dựa trên cấu hình workspace đúng như hiện có trước mắt bạn, đó là điều một trình soạn thảo phải làm khi bạn đang chỉnh sửa cấu hình đó. aggrega validate và aggrega build làm cả hai việc, và vẫn là các bề mặt có thẩm quyền cho một kết luận về một workspace đã commit.

Các thông báo ngừng hỗ trợ của nó bao quát cả hai nơi một lần rút lại được ghi nhận. Một dấu trên một tham chiếu đã ghim nằm trong lockfile; một dấu trên một plugin được gắn trong một vai trò trả về phán quyết chấp nhận-hoặc-từ chối — một gắn kết plugins.governance tại ir-verdict hoặc render-verdict, hoặc một gắn kết plugins.linter — nằm trong bản ghi tin cậy plugin bên cạnh, nên việc xác thực đọc cả hai và nêu từng tham chiếu bị rút lại và từng plugin bị rút lại dưới dạng một cảnh báo ở đầu Aggregate, theo đúng lời mà aggrega build in ra. Một thông báo không thay đổi phán quyết nào. Một bản ghi tin cậy có tồn tại nhưng không đọc được sẽ được báo cáo như một lỗi thay cho việc xác thực, thay vì được đọc như một bản ghi không ghi nhận gì. aggrega/releaseClosure báo cáo cùng tập hợp đó trong deprecations của nó.

Lockfile của một Release nằm ở đâu

Mọi câu trả lời nêu tên một Release đều nêu tên cả lockfile của nó, nên client không bao giờ phải tự suy ra đường dẫn. aggrega/activeRelease mang nó dưới dạng lockfile bên cạnh release, aggrega/releaseCandidates dưới dạng map lockfiles bên cạnh releases, và lỗi thiếu lockfile dưới dạng lockfile trong data của nó. Mỗi giá trị là tệp mà aggrega pull --release <release> ghi và aggrega build đọc, và là tệp mà mọi yêu cầu ở trên kiểm tra — nên một client theo dõi lockfile của một Release, để nhận biết nó được ghi, ghi lại hay bị xóa, sẽ theo dõi đúng tệp mà daemon muốn nói. Lockfile nằm cạnh Release của nó và lấy tên của Release, với phần mở rộng .yaml hoặc .yml được thay bằng .lock; một Release được đặt tên với bất kỳ phần mở rộng nào khác giữ nguyên toàn bộ tên, nên lockfile của release.rel là release.rel.lock. Hãy đọc đường dẫn từ câu trả lời thay vì tự ghép nó từ mô tả này, và hai thứ sẽ không thể lệch nhau.

Các tham chiếu bên ngoài mà một lần render yêu cầu

Một lần render có thể yêu cầu nội dung từ một URL từ xa — chẳng hạn schema values của một chart có tham chiếu từ xa. Đầu vào bên ngoài bị đóng băng cho mọi lần render mà daemon này thực hiện để trả lời một yêu cầu chỉ hỏi để được cho biết điều gì đó. Một tham chiếu mà lockfile của Release ghim được phục vụ từ kho định địa chỉ theo nội dung, tức là đọc nội dung đã có sẵn trên đĩa chứ không phải tải về, và nó được đối chiếu với những gì lockfile ghi lại trước khi các byte của nó được phục vụ — nên một lần render ở đây thấy những gì một lần build thấy, và đưa ra các cảnh báo mà một lần build đưa ra. Một tham chiếu mà lockfile không ghim sẽ bị từ chối thay vì được tải về: lấy nó sẽ phải truy cập mạng và ghi một blob vào kho, và một phiên không làm cả hai việc đó với một yêu cầu chỉ hỏi để được cho biết điều gì đó. Đó là quy tắc trong Truy cập registry và ghi nhìn từ phía lần render, và nó áp dụng bất kể lần render đó được kích hoạt bằng cách nào.

Yêu cầu tồn tại để ghim là ngoại lệ, và đó cũng chính là ngoại lệ mà quy tắc registry đã có. aggrega/resolveDependencies được yêu cầu để lấy về, nên lần render nó thực hiện để phát hiện Release này dùng những tham chiếu nào sẽ truy cập mạng và ghi lại những gì nó ghim — điều đó khiến kết quả của nó là một lockfile chứ không phải một báo cáo. Không lần render nào mà một yêu cầu graph hay build tự thực hiện làm bất kỳ việc nào trong số đó.

Một lần build được yêu cầu resolve trước sẽ được trả lời từ chính lần render đó, vì vậy nó chỉ render Release một lần. Việc resolve đã render những gì lần build nhắm tới, dựa trên các ghim vừa ghi và dưới các cổng kiểm tra mà một lần build chạy, nên lần build trình bày lần render đó thay vì thực hiện lần thứ hai — và việc lấy về vẫn thuộc về việc resolve chứ không thuộc về lần build. Chỉ một lần render đã hoàn tất mới được dùng như vậy: khi một lần resolve đã ghim các phụ thuộc nhưng không thể hoàn tất việc phát hiện các tham chiếu bên ngoài, lần build tự render dựa trên các ghim đã được ghi, và một tham chiếu chưa ghim bị từ chối và được báo cáo ở đó đúng như trên một lần build không resolve gì.

Việc từ chối được báo cáo chứ không bị nuốt mất, vì không có gì trong kết quả cho biết tham chiếu nào bị thiếu. Với các provider mà binary này mang theo, provider đã yêu cầu tham chiếu trả lại lời từ chối, nên một lần render chạm tới tham chiếu bị từ chối sẽ không hoàn tất. Do đó mỗi tham chiếu bị từ chối đến dưới dạng một mục riêng trên lớp aggrega-build, nêu tên tham chiếu và lệnh ghim nó: aggrega pull --release <release>, hoặc aggrega/resolveDependencies để làm cùng việc mà không rời phiên. Các mục này mang tính cảnh báo chứ không phải lời từ chối — graph vẫn được trả về, cùng vị thế với cảnh báo drift ở trên — và chúng được gán cho Aggregate ở đầu tệp, vì một tham chiếu mà lần render yêu cầu không ứng với khóa nào tác giả đã viết. Chúng đi cùng lần công bố với các cảnh báo riêng của lần render, lần công bố này thay thế toàn bộ lớp đó, nên một tham chiếu mà bạn ghim sau đó sẽ ngừng được báo cáo mà không cần gì xóa nó. Một lần render được ghim đầy đủ không nói gì về những điều này. Xem Một mục chẩn đoán mang những gì để biết dạng của mỗi mục.

Trên aggrega/irGraph, điều này phụ thuộc vào việc giai đoạn render có chạy hay không. Yêu cầu graph bỏ qua render trừ khi --build-on-inspect, hoặc khóa serve.build_on_inspect mà nó ghi đè, bật nó lên; khi tắt, không gì yêu cầu tham chiếu bên ngoài và không có gì để từ chối. Bật nó lên là điều đưa cả các cảnh báo riêng của lần render lẫn các cảnh báo này vào một phiên trình soạn thảo.

Chỗ một phiên khác với cùng sự đóng băng ở dòng lệnh. aggrega build cũng đóng băng đầu vào bên ngoài cho một lần chạy thử, và một tham chiếu chưa ghim hoạt động như nhau trên cả hai bề mặt: nó được báo cáo như một phát hiện nêu tên tham chiếu, rồi lần render dừng lại, vì provider đã yêu cầu nó trả lại lời từ chối. Điểm khác là việc tải lại. Ở dòng lệnh, một tham chiếu đã ghim mà bản sao lưu trữ bị mất sẽ được tải lại theo digest đã ghi; lần render trả lời một yêu cầu graph hay build không tải lại gì, vì lần render đó không truy cập mạng, nên nó không thể lấy lại một tham chiếu đã ghim mà kho không còn giữ — và tham chiếu như vậy không nằm trong các lần từ chối mô tả ở trên, vốn nêu tên những gì lockfile không ghim. Yêu cầu phiên ghim là cách khôi phục nó: các yêu cầu nêu ở trên truy cập mạng và đưa các byte bị thiếu trở lại. Xem aggrega pull để biết việc ghim tải về và ghi lại những gì.

Những gì một lần chạy bị từ chối vẫn cho bạn biết

Một yêu cầu bị từ chối sẽ trả lời bằng một error envelope, và các phát hiện mà lần chạy đã đưa ra không đi kèm trong envelope đó — envelope không mang phần thân kết quả nào cả. Chúng đến với bạn theo cùng cách như trên một lần chạy đã hoàn tất: dưới dạng một lần công bố chẩn đoán trên lớp aggrega-build, được mô tả trong Một mục chẩn đoán mang những gì. Vì vậy, một client xử lý lời từ chối sẽ đọc envelope để biết cần thay đổi gì và đọc bề mặt problems để biết lần chạy đã tìm thấy gì, và không cái nào thay thế cho cái kia. Lời từ chối phát sinh trong khi render là lời từ chối duy nhất đồng thời là một phát hiện về những gì tác giả đã viết, nên nó đến cả hai nơi, như phần tiếp theo mô tả.

Lần công bố đó diễn ra bất kể lần chạy có đi đến cuối hay không. Một lần chạy dừng giữa chừng vẫn đã tìm thấy mọi thứ trước điểm nó dừng, và người đọc mất các phát hiện đó sẽ phải chạy lại để thấy chúng — vì vậy các cảnh báo được công bố từ những gì lần chạy đã đạt tới, và lời từ chối được trả về sau đó. Đó là cùng một tập hợp với cùng độ chính xác, được định vị trên cùng các khóa do tác giả viết: lời từ chối không hạ một phát hiện xuống thành một câu văn. Các tham chiếu bên ngoài bị từ chối đi trong cùng lần công bố đó, vì cùng lý do và theo cùng con đường.

Điều giới hạn nó là lần chạy đã đi được bao xa, chứ không phải lớp có thể mang những gì. Một lời từ chối từ một trong các kiểm tra chạy trước khi compiler bắt đầu — không thể phân giải closure của Release, Manifest ánh xạ một kiểu vào một recipe không hiện thực kiểu đó, lockfile không còn khớp với những gì Release phân giải ra, một mục được ghim trong cache không còn khớp với digest được ghi cho nó và không thư mục catalog nào chứa các byte được ghim — không có cảnh báo nào để công bố, vì chưa có cảnh báo nào được đưa ra. Khi đó lớp không mang gì thay vì mang thứ đã cũ; và một lần chạy chưa đi tới mức nêu tên một tài liệu thì không công bố gì cả, để nguyên mọi thứ đang có trên bề mặt problems của bạn thay vì xóa các mục mà nó không biết gì thêm.

Lời từ chối phát sinh trong khi render

Một Release mà compiler từ chối trong khi render nó — một Workload nêu tên một slot mà Component của nó không khai báo, một assertion thất bại, một template không thể đánh giá, một realization thiếu những gì nó phải cung cấp — được báo cáo tại nơi nó trỏ tới và bằng lời của compiler, trên mọi yêu cầu render nó: aggrega/build, aggrega/buildPreview, và aggrega/irGraph khi giai đoạn render được bật. Câu trả lời là một error envelope với mã -32603, có message là lời từ chối cùng mọi nguyên nhân bên dưới nó, bằng chính lời mà dòng lệnh in ra cho cùng bản build: node đang được render, rồi phần nào trong nó từ chối, mỗi nguyên nhân đứng sau nguyên nhân mà nó giải thích — được mở đầu, khi lời từ chối nêu tên một điều kiện đã đăng ký, bằng mã ngắn của điều kiện đó, giống như mọi lời từ chối nêu tên một điều kiện. data của nó nêu tài liệu mà lời từ chối trỏ tới dưới dạng file, và phạm vi của khóa ở đó dưới dạng line, column, end_line và end_column, bên cạnh code và shortCode của điều kiện; một lời từ chối không nêu khóa nào, hoặc nêu một khóa mà tài liệu không chứa, chỉ mang file, và lời từ chối không trỏ tới tài liệu nào thì nêu Aggregate của Release.

Cùng lời từ chối đó được công bố trên lớp aggrega-build, trên tài liệu đó, tại khóa đó, dưới dạng một mục có mức độ error mang keyPath của chính lời từ chối và message của envelope nhưng không có mã ngắn phía trước, và — khi lời từ chối nêu tên một điều kiện đã đăng ký — code, shortCode và codeDescription của điều kiện đó, mã ngắn đi trong trường riêng của nó ở đó. Nó đi trong chính lần công bố mang các cảnh báo mà lần chạy đã đưa ra trước khi dừng, nên nó thay thế lớp giống như chúng: lần chạy tiếp theo của Release có render sẽ công bố lớp mà không có nó, và tài liệu nó nằm trên được công bố rỗng, đó là điều xóa nó khỏi bề mặt problems của bạn.

Nơi một lời từ chối trỏ tới là chính những gì lời từ chối nêu, và không chi tiết hơn. Các kiểm tra của một Workload đánh giá tài liệu mà template của nó tạo ra, và một template có thể viết những dòng mà không tác giả nào viết — một vòng lặp, một điều kiện, một đoạn văn bản nhập từ một file hoặc một thư viện — nên một dòng của Workload đã render không ánh xạ tới một dòng của Recipe. Vì vậy, lời từ chối về một Workload được đặt trên khóa workload của Recipe, và các đường dẫn nó nêu bên trong tài liệu đã render vẫn nằm trong message của nó. Một assertion thất bại được đặt trên khóa riêng của nó dưới assertions trong Recipe hoặc FeatureRecipe khai báo nó; một assertion do một Component hoặc một Feature khai báo được đưa ra trước khi có tài liệu nào trong tay để nêu, và được đặt trên khóa kind: của Aggregate. Lời từ chối từ một bước nêu một tài liệu nhưng không nêu khóa nào được đặt trên khóa kind: của tài liệu đó.

Một lời từ chối gộp nhiều phát hiện được công bố theo từng phát hiện. Việc kết hợp graph mà quá trình render dựa vào sẽ từ chối với mọi vi phạm nó tìm thấy trong một lời từ chối — một mục nêu một đích mà không gì đáp ứng, hai kết nối của một component được đặt cùng một alias — và dòng lệnh in mỗi vi phạm thành một chẩn đoán riêng, dưới tiêu đề riêng. Ở đây mỗi vi phạm là một mục riêng trên lớp aggrega-build, trên tài liệu và tại khóa mà phát hiện đó nêu — Release khi Release viết nó, Aggregate khi Aggregate viết nó — bằng lời riêng và với các mã riêng của nó. message của câu trả lời mang mọi phát hiện, và data của nó nêu nơi phát hiện đầu tiên trỏ tới.

Một giá trị mà tác giả khai báo là nhạy cảm được giữ kín ở đây đúng như dòng lệnh giữ kín nó. Văn bản của lời từ chối là văn bản compiler đưa ra, không gì trên bề mặt này diễn đạt lại nó, và compiler giữ kín giá trị đã khai báo tại nơi lời từ chối được đưa ra — <redacted> ở vị trí của nó — nên câu trả lời này, mục này và terminal mang nó bằng cùng lời lẽ; những gì một lời từ chối nói về một giá trị đã khai báo nêu cách thức, và những lời từ chối nào nằm ngoài điều đó.

Lời từ chối từ một cổng chạy trước khi render không thuộc trường hợp này. Các kiểm tra liệt kê ở trên trả lời như Những gì một lần chạy bị từ chối vẫn cho bạn biết mô tả. Một assertion do một Component hoặc một Feature khai báo, và một lời từ chối trên graph đã kết hợp, nằm giữa hai trường hợp: mỗi cái được đưa ra trước khi render, bởi mọi yêu cầu phân giải graph của một Release, nên aggrega/irGraph trả lời và công bố nó như trên cả khi giai đoạn render tắt; aggrega/releaseClosure, aggrega/attachCandidates và aggrega/attachmentContainer khi được hỏi về một node của graph, và aggrega/connectionAtPosition, trả lời nó bằng cùng envelope và không công bố gì, vì chúng không sở hữu bề mặt problems nào.

Mã lỗi

Các phản hồi dùng các mã lỗi JSON-RPC chuẩn cùng với một dải mã cấp ứng dụng trong khoảng 1xxx. Một client của trình soạn thảo có thể rẽ nhánh theo mã mà không cần phân tích thông báo.

  • 1001 file-not-validated — daemon không giữ gì cho tệp, ở trạng thái hiện tại của nó, mà yêu cầu có thể dựa vào để trả lời: không có kết quả phân tích nào của tệp, hoặc, đối với aggrega/diagnostics, không có kết quả phân tích nào của tệp hoặc không giữ gì cho tệp là câu trả lời của một lần xác thực cho văn bản mà daemon hiện đang giữ. Hãy gửi aggrega/validate cho tệp đó rồi hỏi lại.
  • 1003 lockfile-absent — Release mà yêu cầu nêu tên không có lockfile, trong khi thao tác được yêu cầu cần có một lockfile.
  • 1004 entity-not-resolvable — tên không khớp với thực thể nào trong bất kỳ tầng catalog nào, cũng không khớp trong Release mà yêu cầu nêu tên; hoặc tham chiếu registry được gửi làm tên không thể đọc thành một thực thể, và thông báo nêu tên điều kiện giải thích lý do; hoặc lockfile của Release là một liên kết dẫn ra ngoài workspace, điều này bị từ chối trước khi bất cứ thứ gì đọc nó, với data nêu tên lockfile và Release, còn thông báo mở đầu bằng mã ngắn của điều kiện, E0321 — xem ranh giới workspace.
  • 1005 shutting-down — daemon đang kết thúc dần sau một thông báo tắt và từ chối các yêu cầu mới. Không thử lại với cùng tiến trình con đó.
  • 1006 validation-in-flight — một lần xác thực tệp đang chạy và chưa hoàn tất trong khoảng thời gian mà yêu cầu đang chờ cho phép. Hãy hỏi lại sau ít lâu và không gửi gì thêm.

1002 chưa được cấp phát, và sẵn sàng cho điều kiện tiếp theo cần một mã.

File-not-validated và validation-in-flight báo cáo hai trạng thái trái ngược nhau, và hành động mà mỗi mã đòi hỏi cũng trái ngược nhau. File-not-validated nghĩa là daemon không giữ gì cho tệp, ở trạng thái hiện tại của nó, mà yêu cầu có thể dựa vào để trả lời — không có kết quả phân tích nào của tệp, hoặc, đối với aggrega/diagnostics, không có kết quả phân tích nào của tệp hoặc không giữ gì cho tệp là câu trả lời của một lần xác thực cho văn bản mà daemon hiện đang giữ: hãy gửi aggrega/validate rồi hỏi lại. Một lần xác thực bị hủy giữa chừng sẽ để tệp ở trạng thái này, vì nó không lưu gì và những gì một lần xác thực trước đó tìm thấy về một văn bản khác không phải là câu trả lời cho văn bản mà daemon hiện đang giữ; một câu trả lời trước đó vẫn còn hiệu lực khi văn bản vẫn là văn bản mà nó đã kiểm tra. Những phát hiện mà daemon đẩy về một tệp do chính nó đọc từ đĩa — một lockfile đã bị lệch, một Release không nạp được — không phải là một lần xác thực văn bản bạn đang giữ, nên chúng cũng không trả lời yêu cầu này. Hai lần xác thực cho hai văn bản khác nhau được gửi sát nhau cũng có thể khiến bạn rơi vào trạng thái này, khi lần xác thực có văn bản được daemon giữ lại hoàn tất trước: yêu cầu bị từ chối dù văn bản đó đã được kiểm tra, và xác thực lại sẽ trả lời được yêu cầu. Mã này được phát biểu theo kết quả phân tích chứ không theo tệp, vì một buffer mà không trình phân tích nào đọc cũng ở đúng vị trí đó — lần xác thực đã chạy và báo cáo những gì nó tìm thấy, nhưng vẫn không có kết quả phân tích nào để trả lời. Validation-in-flight nghĩa là một lần xác thực tệp đang chạy và chưa hoàn tất trong khoảng thời gian mà yêu cầu đang chờ cho phép: hãy hỏi lại sau ít lâu và không gửi gì thêm, vì trạng thái bạn cần đã đang trên đường tới và một lần xác thực thứ hai chỉ thêm việc. Coi hai mã là một điều kiện sẽ khiến client gửi một lần xác thực trong đúng trường hợp mà việc gửi là sai. Hai dải mã có ý nghĩa khác nhau đối với client: một mã 1xxx nêu tên một trạng thái của workspace mà người dùng có thể xử lý — xác thực tệp, tạo lockfile — còn một mã chuẩn như invalid-params nêu tên một yêu cầu sai dạng, mà client sửa chứ không phải người dùng. Một giá trị release có mặt nhưng sai dạng — là đường dẫn tuyệt đối, hoặc phân giải ra ngoài gốc workspace — thuộc dải thứ hai: không phải workspace ở trạng thái người dùng phải sửa, mà là yêu cầu. Việc bỏ qua release không thuộc dải nào, vì đó hoàn toàn không phải là lỗi; nó chọn câu trả lời hẹp hơn trong hai câu trả lời được mô tả ở Xác thực trực tiếp.

Một lỗi có thể mang một đối tượng data, và mỗi khóa trong đó nêu tên một thứ và chỉ thứ đó. file là tài liệu nguồn mà lỗi nói về — tài liệu đang được xác thực, Release có lần tải thất bại, tài liệu workspace khai báo một tên mà không gì phân giải được, hoặc tài liệu mà một lời từ chối phát sinh trong khi render trỏ tới — và đó là nơi mà line và column đi kèm (nếu có) định vị một vị trí bên trong. Bản thân hai khóa đó là tùy chọn: một lỗi về toàn bộ tài liệu chỉ mang file. lockfile là một lockfile. release là Release mà lỗi nói về, được viết theo cách yêu cầu đã nêu tên nó, để client có thể ghép aggrega pull --release <release> mà không phải phân tích lại nó từ thông báo. unreachable cho biết registry mà một yêu cầu bị từ chối nêu tên không thể truy cập được: một lần làm mới chỉ mục bị từ chối nêu tên một registry sẽ mang khóa này, được đọc từ chính lỗi, còn một registry đã trả lời thì không có khóa này. Mọi khóa đều là tùy chọn và chỉ có mặt khi daemon có sẵn giá trị đó; không khóa nào thay thế khóa khác, nên thứ mà một khóa trỏ tới không bao giờ phụ thuộc vào mã bên cạnh nó.

code và shortCode trong data nêu tên điều kiện mà một lời từ chối báo cáo, trên mọi lời từ chối báo cáo một điều kiện đã đăng ký, bất kể mã số của nó: mã mô tả mà chương trình rẽ nhánh theo và mã ngắn mà con người trích dẫn, cùng hai định danh ấy, dưới cùng các tên ấy, mà một mục chẩn đoán mang cho cùng điều kiện, và được liệt kê trong bảng mọi điều kiện. Hãy rẽ nhánh theo code. Mã số nêu tên trạng thái của yêu cầu và giữ nguyên cho nhiều điều kiện — một bản build bị từ chối vì một liên kết catalog dẫn ra ngoài và một bản build bị từ chối vì một tên không phân giải ra gì đều là 1004 — còn thông báo là văn xuôi có thể được diễn đạt lại, nên không cái nào phân biệt được điều kiện này với điều kiện khác. Invalid-params là một mã dùng chung như vậy: một yêu cầu nêu tên một workspace có tệp cấu hình dẫn ra ngoài nó cũng nhận mã này, và ở đó read-leads-out-of-workspace cho biết lỗi nằm ở bố cục của workspace, thứ mà con người sửa, chứ không phải ở yêu cầu. Một lời từ chối không báo cáo điều kiện đã đăng ký nào thì không mang khóa nào trong hai khóa, và hai khóa luôn có mặt cùng nhau hoặc không có cả hai. Thông báo của một lời từ chối nêu tên một điều kiện mở đầu bằng mã ngắn của nó, E0321: …, một lần, đó là dạng mà người đọc gặp trên mọi lời từ chối như vậy; một lời từ chối có thông báo đã mở đầu bằng một phần đầu trong ngoặc vuông mang mã — báo cáo một dòng về một tài liệu catalog mà lần tải đã từ chối — thì không được thêm mã lần nữa.

Bản tường thuật về cách chuỗi cascade Release của workspace đã chạy được truyền trên câu trả lời aggrega/activeRelease, trong trường trace của nó, chứ không trên một lỗi: một workspace không trỏ tới Release nào là một trạng thái bình thường chứ không phải một yêu cầu thất bại. Đây là văn xuôi chẩn đoán viết cho con người đọc, không phải một cấu trúc để phân tích. Hãy hiển thị nó nguyên dạng — ghi vào log, hoặc vào một bảng mà người dùng có thể mở — và đừng khớp mẫu với nó, trích giá trị từ nó, hay rẽ nhánh theo các nhãn nó dùng: cách diễn đạt, bố cục và các nhãn đó bám theo chính chuỗi cascade và thay đổi mỗi khi chuỗi cascade thay đổi. Một client chuyển tiếp nguyên văn bản sẽ tiếp tục hoạt động qua thay đổi như vậy; một client đã học thuộc hình dạng của nó sẽ hỏng.

Xem thêm

  • ../schema/other/serve-wire.md — các dạng thông điệp mà giao thức này trao đổi, được sinh ra từ schema đã công bố: đối tượng tham số của mọi phương thức, mọi kết quả và mọi payload thông báo, theo từng trường.
  • ./aggrega-build.md — lệnh build, có pipeline trình biên dịch, các cổng kiểm tra và cơ chế phân giải phụ thuộc mà aggrega/build cũng chạy, nhờ đó hai bề mặt ghi ra một cây đầu ra thay vì hai.
  • ./aggrega-version.md — lệnh version mà một tiện ích mở rộng của trình soạn thảo dùng để kiểm tra khả năng tương thích của daemon.
  • ./aggrega-pull.md — lockfile mà bề mặt phát hiện sai lệch của daemon đọc.
  • ./aggrega-lint.md — các quy ước xuất bản mà daemon báo cáo khi được yêu cầu, và trong mọi lần xác thực khi serve.lint_on_validate được bật.

Cú pháp

aggrega serve [flags]

Mô tả

Run the Aggrega compiler as a long-running service. The daemon
reads JSON-RPC 2.0 messages from stdin and writes responses to stdout
under the aggrega/ method namespace. State (parsed YAML, diagnostics,
resolved catalog) holds across requests so IDE clients can issue many
cheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path every
aggrega command uses: --workspace-root when set (used as-is, validated
to exist as a directory), otherwise discovery walking upward from the
current working directory. A directory anchors the workspace when it
holds a .aggrega-config.yaml carrying a workspace: block, or — as a
fallback — any of .aggrega/, aggregate*.yaml, release*.yaml,
manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yaml
files from the workspace root down to the working directory (nearer
overrides farther), beneath which the global config file — the one
--config names, else the one the AGGREGA_CONFIG environment variable
names, else the default location when a file is there — and the
built-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for a
cooperative cross-platform exit: the daemon completes the in-flight
handler if any, refuses new requests with code 1005, and exits
cleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, or
a termination request from a supervisor or container runtime — takes
the same path on the same terms: the first request drains the daemon
and it exits cleanly, and a second ends the process at once.

Cờ

CờMặc địnhMô tả
--build-on-inspectfalseChạy giai đoạn kết xuất artifact trong khi kiểm tra một đồ thị IR, để các cảnh báo mà aggrega build đưa ra trong lúc kết xuất cũng xuất hiện dưới dạng vấn đề trong trình soạn thảo. Cờ này không thêm bất kỳ phép kiểm tra nào khiến một lần build dừng lại. Không có gì được ghi ra đĩa: không có artifact đã kết xuất, không có thư mục đầu ra, không có lockfile. Mặc định tắt, giống với aggrega inspect, vốn cũng không đưa ra cảnh báo nào như vậy. Khi được đặt, cờ này ghi đè khóa cấu hình serve.build_on_inspect.