ard.json

Khám phá tài nguyên cho tác nhân (ARD) là một quy cách để lập danh mục tài nguyên cho tác nhân. Tệp kê khai ard.json mô tả các tài nguyên tác nhân trên một miền, chẳng hạn như máy chủ MCP, tác nhân A2A và kỹ năng của tác nhân, để các tác nhân AI và sổ đăng ký có thể tìm thấy các tài nguyên đó.

Cách hoạt động của quy trình kiểm tra Lighthouse

Quy trình khám phá: Quy trình kiểm tra tìm tệp kê khai dựa trên cơ chế khám phá trong quy cách ARD (§5.1):

  • Đang kiểm tra lệnh Agentmap: bên trong robots.txt.
  • Đang quét HTML để tìm thẻ <link rel="ard" href="...">.
  • Kiểm tra phản hồi tiêu đề HTTP Link: <...>; rel="ard".
  • Đang tìm nạp từ điểm cuối phổ biến /.well-known/ard.json.

Nếu không tìm thấy tệp kê khai chính, Lighthouse sẽ kiểm tra các đường dẫn cũ (chẳng hạn như rel="ai-catalog" hoặc /.well-known/ai-catalog.json). Mặc dù nội dung tìm thấy ở đây vẫn được xác thực, nhưng Lighthouse sẽ đưa ra cảnh báo vì các ứng dụng ARD tiêu chuẩn không bắt buộc phải hỗ trợ các tuyến không dùng nữa.

Quy tắc xác thực: Quy trình xác minh được thực hiện bằng cách sử dụng cổng JavaScript của bộ công cụ xác định tính tuân thủ ARD phiên bản 0.91, kiểm tra các tiêu chí sau:

Lỗi xác thực và lỗi tuân thủ:

  • Cú pháp và giản đồ: Tệp kê khai là JSON hợp lệ và khớp với giản đồ tệp kê khai ARD, đồng thời mỗi mục nhập khớp với giản đồ mục nhập ARD. Lighthouse không tìm nạp hoặc xác thực cấu phần phần mềm mà một mục nhập trỏ đến (ví dụ: thẻ máy chủ MCP tại url).
  • Trường bắt buộc: Tệp kê khai chứa một mảng entries và mọi mục nhập đều chứa identifier, displayName và type.
  • URN dựa trên miền: Mỗi identifier đều tuân theo định dạng urn:air:<publisher>:<namespace>:<name>.
  • Định nghĩa vị trí: Mỗi mục nhập xác định chính xác một trong url hoặc data cùng dòng, không bao giờ là cả hai hoặc không có mục nào.
  • Cấu trúc tệp kê khai tin cậy: Khi được đưa vào, trustManifest là một đối tượng có thuộc tính identity.

Cảnh báo về phương pháp hay nhất:

  • Cụm từ tìm kiếm đại diện: Mỗi mục nhập có một mảng representativeQueries gồm 2 đến 5 cụm từ tìm kiếm mẫu. Các sổ đăng ký xây dựng chỉ mục tìm kiếm từ những thông tin này, vì vậy, một mục không có những thông tin này sẽ không xuất hiện trong kết quả tìm kiếm. (Nếu có, thì đây phải là một mảng chuỗi; nếu không thì sẽ xảy ra lỗi.)
  • Loại nội dung nghe nhìn: type phải là loại nội dung nghe nhìn đúng định dạng. Lighthouse cảnh báo về các loại không dùng nữa (ví dụ: application/mcp-server+json đến application/mcp-server-card+json), các loại chuẩn có tham số bị thiếu hoặc thừa và các loại không được nhận dạng bên ngoài application/*. Bạn có thể sử dụng các loại application/* tuỳ chỉnh.
  • Bộ sưu tập: Gắn cờ một trường collections cấp cao nhất. Nó không còn là một phần của ARD và bị bỏ qua; thay vào đó, hãy phân cấp mô hình bên trong entries.
  • Điểm cuối cũ: Gắn cờ các tệp kê khai chỉ được tìm thấy thông qua các vị trí ai-catalog cũ.
  • Vị trí quảng cáo bị hỏng: Gắn cờ mọi vị trí quảng cáo (đường liên kết Agentmap:, rel="ard" hoặc rel="ai-catalog", hoặc tiêu đề Link) không tải được khi tệp kê khai được tìm thấy ở nơi khác.

Không bắt buộc:

  • specVersion và các trường cấp cao nhất khác không ảnh hưởng đến điểm số.
  • capabilities là không bắt buộc và không được tính điểm. Nếu tài nguyên của bạn hiển thị các công cụ hoặc kỹ năng có tên, hãy cân nhắc việc liệt kê các công cụ hoặc kỹ năng đó (ví dụ: ["WeatherTool", "ForecastTool"]) để các sổ đăng ký có thể lọc các công cụ hoặc kỹ năng đó mà không cần tìm nạp toàn bộ cấu phần phần mềm. Nếu được đưa vào, thì đây phải là một mảng chuỗi.

Đọc bảng kết quả

Cột Phần tử cho thấy Root đối với các vấn đề liên quan đến toàn bộ tệp kê khai. Đối với các vấn đề về một mục, công cụ này sẽ hiển thị displayName của mục đó, quay lại identifier hoặc Entry #n nếu không có mục nào. Một vấn đề về giản đồ có thể xuất hiện hai lần, một lần trong Root và một lần trong mục nhập, khớp với kết quả của kiểm thử tuân thủ chính thức.

Tìm hiểu về điểm số của bạn

Kết quả kiểm tra được thể hiện theo những cách sau:

  • Đạt (1): Đã tìm thấy tệp kê khai và không có lỗi hoặc cảnh báo nào.
  • Điểm một phần (0,9): Tệp kê khai hợp lệ nhưng có ít nhất một cảnh báo về phương pháp hay nhất.
  • Không đạt (0): Bất kỳ lỗi nào về việc không tuân thủ, chẳng hạn như JSON không đúng định dạng, vi phạm giản đồ, URN không hợp lệ hoặc cả hai hoặc không có url/data. Quá trình kiểm tra cũng không thành công nếu tệp kê khai được quảng cáo (thông qua robots.txt, đường liên kết rel="ard" hoặc rel="ai-catalog" hoặc tiêu đề Link) nhưng không tải được.
  • Không áp dụng: Không tìm thấy tệp kê khai nào bằng bất kỳ phương thức nào. Điều này không ảnh hưởng đến điểm Lighthouse của bạn.

Cách khắc phục

Để vượt qua quy trình kiểm tra, hãy làm theo các bước hữu ích sau:

  1. Phân phát tệp kê khai tại /.well-known/ard.json hoặc liên kết tệp đó với rel=ard. Nếu bạn sử dụng ai-catalog.json hoặc rel=ai-catalog, hãy chuyển sang tên mới.
  2. Khắc phục mọi lỗi được liệt kê trong bảng kiểm tra để tệp kê khai khớp với giản đồ ARD.
  3. Cung cấp cho mỗi mục nhập một giá trị nhận dạng urn:air:... và chính xác một trong hai giá trị url hoặc data.
  4. Sử dụng loại nội dung nghe nhìn ARD chuẩn trong type nếu có.
  5. Thêm từ 2 đến 5 representativeQueries vào mỗi mục để đạt điểm tối đa.