ard.json

代理資源探索 (ARD) 是代理資源的目錄規格。ard.json 資訊清單會說明網域上的代理資源，例如 MCP 伺服器、A2A 代理和代理技能，讓 AI 代理和註冊資料庫能找到這些資源。

Lighthouse 稽核的運作方式

探索程序：稽核會根據 ARD 規範 (§5.1) 中的探索機制尋找資訊清單：

  • 正在檢查 robots.txt 內是否有 Agentmap: 指令。
  • 正在掃描 HTML，找出 <link rel="ard" href="..."> 標記。
  • 檢查 HTTP Link: <...>; rel="ard" 標頭回應。
  • 正在從已知端點 /.well-known/ard.json 擷取。

如果主要探索失敗，Lighthouse 會檢查舊版路徑 (例如 rel="ai-catalog" 或 /.well-known/ai-catalog.json)。雖然系統仍會驗證在此找到的內容，但由於標準 ARD 用戶端不一定要支援已淘汰的路徑，因此會顯示警告。

驗證規則：系統會使用 ARD 0.91 版合規套件的 JavaScript 通訊埠進行驗證，測試下列條件：

符合性與驗證錯誤：

  • 語法和結構定義：資訊清單是有效的 JSON，且符合 ARD 資訊清單結構定義，每個項目都符合 ARD 項目結構定義。Lighthouse 不會擷取或驗證項目指向的構件 (例如 url 的 MCP 伺服器資訊卡)。
  • 必填欄位：資訊清單包含 entries 陣列，且每個項目都包含 identifier、displayName 和 type。
  • 網域錨定 URN：每個 identifier 都採用 urn:air:<publisher>:<namespace>:<name> 格式。
  • 位置定義：每個項目都只會定義 url 或內嵌 data，不會同時定義兩者，也不會兩者都不定義。
  • 信任資訊清單結構：如果包含 trustManifest，則為具有 identity 屬性的物件。

最佳做法警告：

  • 代表性查詢：每個項目都有一個 representativeQueries 陣列，其中包含 2 到 5 個範例查詢。登錄檔會根據這些資訊建立搜尋索引，因此如果項目不含這些資訊，就不會出現在搜尋結果中。(如有，則必須是字串陣列，否則會發生錯誤)。
  • 媒體類型： type 必須是格式正確的媒體類型。Lighthouse 會針對已淘汰的類型 (例如 application/mcp-server+json 至 application/mcp-server-card+json)、缺少或多餘參數的標準類型，以及 application/* 以外無法辨識的類型發出警告。允許自訂 application/* 類型。
  • 集合：標記頂層 collections 欄位。這項屬性已不再是 ARD 的一部分，因此會遭到忽略；請改用 entries 內的模型階層。
  • 舊版端點：標記僅透過舊版 ai-catalog 位置找到的資訊清單。
  • 損壞的廣告位置：如果資訊清單在其他位置找到，但無法載入任何廣告位置 (Agentmap:、rel="ard" 或 rel="ai-catalog" 連結，或 Link 標頭)，則會標記。

非必要：

  • specVersion 和其他額外的頂層欄位不會影響分數。
  • capabilities為選填，不計分。如果資源提供具名工具或技能，建議列出這些工具或技能 (例如 ["WeatherTool", "ForecastTool"])，讓登錄檔可以篩選，而不必擷取完整構件。如要加入，必須是字串陣列。

解讀結果表格

如果整個資訊清單有問題，「元素」欄會顯示 Root。如果項目有問題，系統會顯示項目的 displayName，如果沒有，則會顯示 identifier，如果兩者都沒有，則會顯示 Entry #n。單一結構定義問題可能會出現兩次，一次在 Root 下方，另一次在項目下方，與官方一致性測試的輸出內容相符。

瞭解分數

稽核結果會以下列方式呈現：

  • 通過 (1)：已找到資訊清單，且沒有錯誤或警告。
  • 部分分數 (0.9)：資訊清單有效，但至少有一項最佳做法警告。
  • 失敗 (0)：任何一致性錯誤，例如 JSON 格式錯誤、違反結構定義、URN 無效，或 url/data 兩者皆有或皆無。如果資訊清單已透過 robots.txt、rel="ard" 或 rel="ai-catalog" 連結或 Link 標頭宣傳，但無法載入，稽核也會失敗。
  • 不適用：未透過任何方法找到資訊清單。這不會影響 Lighthouse 分數。

如何修正

如要通過稽核，請按照下列步驟操作：

  1. 請透過 /.well-known/ard.json 提供資訊清單，或使用 rel=ard 連結至資訊清單。如果您使用 ai-catalog.json 或 rel=ai-catalog，請改用新名稱。
  2. 修正稽核表格中列出的所有錯誤，讓資訊清單符合 ARD 結構定義。
  3. 為每個項目提供 urn:air:... 識別碼，以及 url 或 data 其中之一。
  4. 在type中使用標準 ARD 媒體類型 (如適用)。
  5. 為每個項目新增 2 到 5 個representativeQueries，即可獲得滿分。