ard.json

Agentic Resource Discovery (ARD) เป็นข้อกำหนดเฉพาะสำหรับการจัดทำแคตตาล็อกทรัพยากร Agentic ไฟล์ Manifest ard.json อธิบายทรัพยากร Agentic ในโดเมน เช่น เซิร์ฟเวอร์ MCP, A2A Agent และทักษะของ Agent เพื่อให้ AI Agent และรีจิสทรีค้นหาทรัพยากรเหล่านั้นได้

วิธีการทำงานของการตรวจสอบ Lighthouse

กระบวนการค้นพบ: การตรวจสอบจะค้นหาไฟล์ Manifest โดยอิงตามกลไกการค้นพบในข้อกำหนดเฉพาะของ ARD (§5.1) ดังนี้

  • กำลังตรวจสอบคำสั่ง Agentmap: ภายใน robots.txt
  • กำลังสแกน HTML เพื่อหาแท็ก <link rel="ard" href="...">
  • ตรวจสอบการตอบกลับส่วนหัว HTTP Link: <...>; rel="ard"
  • กำลังดึงข้อมูลจากปลายทางที่รู้จักกันดี /.well-known/ard.json

หากการค้นพบหลักไม่สำเร็จ Lighthouse จะตรวจสอบเส้นทางเดิม (เช่น rel="ai-catalog" หรือ /.well-known/ai-catalog.json) แม้ว่าเนื้อหาที่พบที่นี่ยังคงได้รับการตรวจสอบ แต่ระบบจะแสดงคำเตือนเนื่องจากไคลเอ็นต์ ARD มาตรฐานไม่จำเป็นต้องรองรับเส้นทางที่เลิกใช้งานแล้ว

กฎการตรวจสอบ: การยืนยันจะดำเนินการโดยใช้พอร์ต JavaScript ของชุดกระบวนการทดสอบ ARD v0.91 โดยทดสอบเกณฑ์ต่อไปนี้

ข้อผิดพลาดด้านความสอดคล้องและการตรวจสอบ:

  • ไวยากรณ์และสคีมา: ไฟล์ Manifest เป็น JSON ที่ถูกต้องและตรงกับสคีมาไฟล์ Manifest ของ ARD และแต่ละรายการตรงกับสคีมารายการ ARD Lighthouse ไม่ได้ดึงข้อมูลหรือตรวจสอบอาร์ติแฟกต์ที่จุดแรกเข้าชี้ไป (เช่น การ์ดเซิร์ฟเวอร์ MCP ที่ url)
  • ฟิลด์ที่ต้องกรอก: ไฟล์ Manifest มีอาร์เรย์ entries และทุกรายการมี identifier, displayName และ type
  • URN ที่ยึดตามโดเมน: identifier แต่ละรายการจะเป็นไปตามรูปแบบ urn:air:<publisher>:<namespace>:<name>
  • คำจำกัดความของตำแหน่ง: แต่ละรายการจะกำหนด url หรือ data ในบรรทัดอย่างใดอย่างหนึ่งเท่านั้น ไม่ใช่ทั้ง 2 อย่างหรือไม่มีเลย
  • โครงสร้างไฟล์ Manifest ของความน่าเชื่อถือ: เมื่อรวม trustManifest ไว้ จะเป็นออบเจ็กต์ที่มีพร็อพเพอร์ตี้ identity

คำเตือนเกี่ยวกับแนวทางปฏิบัติแนะนำ

  • คำค้นหาที่เป็นตัวแทน: แต่ละรายการมีอาร์เรย์ representativeQueries ที่มีคำค้นหาตัวอย่าง 2-5 รายการ รีจิสทรีจะสร้างดัชนีของ Search จากข้อมูลเหล่านี้ ดังนั้นรายการที่ไม่มีข้อมูลดังกล่าวจะไม่ปรากฏในผลการค้นหา (หากมี ต้องเป็นอาร์เรย์ของสตริง ไม่เช่นนั้นจะเกิดข้อผิดพลาด)
  • ประเภทสื่อ: type ต้องเป็นประเภทสื่อที่มีรูปแบบถูกต้อง Lighthouse จะเตือนเกี่ยวกับประเภทที่เลิกใช้งานแล้ว (เช่น application/mcp-server+json ถึง application/mcp-server-card+json) ประเภทมาตรฐานที่มีพารามิเตอร์ขาดหายไปหรือมีพารามิเตอร์เพิ่มเติม และประเภทที่ไม่รู้จักนอก application/* อนุญาตให้ใช้ประเภท application/* ที่กำหนดเอง
  • Collections: แจ้งว่าช่อง collections ระดับบนสุดไม่เหมาะสม เนื่องจากไม่ได้เป็นส่วนหนึ่งของ ARD อีกต่อไปและระบบจะไม่สนใจ โดยจะใช้ลำดับชั้นของโมเดลภายใน entries แทน
  • ปลายทางเดิม: แจ้งเตือนไฟล์ Manifest ที่พบผ่านตำแหน่งเดิม ai-catalog เท่านั้น
  • ตำแหน่งที่โฆษณาเสีย: แจ้งว่าตำแหน่งที่โฆษณา (ลิงก์ Agentmap:, rel="ard" หรือ rel="ai-catalog" หรือส่วนหัว Link) โหลดไม่ได้เมื่อพบไฟล์ Manifest ที่อื่น

ไม่จำเป็น:

  • specVersion และช่องระดับบนสุดอื่นๆ ที่เพิ่มเข้ามาจะไม่ส่งผลต่อคะแนน
  • capabilities เป็นเพียงตัวเลือกและไม่มีการให้คะแนน หากทรัพยากรของคุณแสดงเครื่องมือหรือทักษะที่มีชื่อ ให้พิจารณาระบุเครื่องมือหรือทักษะเหล่านั้น (เช่น ["WeatherTool", "ForecastTool"]) เพื่อให้รีจิสทรีสามารถกรองเครื่องมือหรือทักษะเหล่านั้นได้โดยไม่ต้องดึงอาร์ติแฟกต์ทั้งหมด หากรวมไว้ ต้องเป็นอาร์เรย์ของสตริง

การอ่านตารางผลลัพธ์

คอลัมน์องค์ประกอบจะแสดง Root สำหรับปัญหาเกี่ยวกับไฟล์ Manifest โดยรวม สำหรับปัญหาเกี่ยวกับรายการ ระบบจะแสดง displayName ของรายการ โดยจะเปลี่ยนกลับไปเป็น identifier หรือ Entry #n หากไม่มีทั้ง 2 รายการ ปัญหาเกี่ยวกับสคีมาเดียวอาจปรากฏ 2 ครั้ง โดยปรากฏในส่วน Root 1 ครั้งและในรายการอีก 1 ครั้ง ซึ่งตรงกับเอาต์พุตของการทดสอบความสอดคล้องอย่างเป็นทางการ

ทำความเข้าใจคะแนนของคุณ

ผลการตรวจสอบจะแสดงในลักษณะต่อไปนี้

  • ผ่าน (1): พบไฟล์ Manifest และไม่มีข้อผิดพลาดหรือคำเตือน
  • คะแนนบางส่วน (0.9): ไฟล์ Manifest ถูกต้อง แต่มีคำเตือนเกี่ยวกับแนวทางปฏิบัติแนะนำอย่างน้อย 1 รายการ
  • ไม่ผ่าน (0): ข้อผิดพลาดด้านความสอดคล้อง เช่น JSON มีรูปแบบไม่ถูกต้อง การละเมิดสคีมา URN ไม่ถูกต้อง หรือทั้ง 2 อย่าง หรือไม่มี url/data เลย การตรวจสอบจะล้มเหลวด้วยหากมีการโฆษณาไฟล์ Manifest (ผ่าน robots.txt, ลิงก์ rel="ard" หรือ rel="ai-catalog" หรือส่วนหัว Link) แต่โหลดไม่ได้
  • ไม่เกี่ยวข้อง: ไม่พบไฟล์ Manifest ไม่ว่าจะใช้วิธีใดก็ตาม การดำเนินการนี้จะไม่ส่งผลต่อคะแนน Lighthouse

วิธีแก้ไข

โปรดทำตามขั้นตอนที่นำไปใช้ได้จริงต่อไปนี้เพื่อให้ผ่านการตรวจสอบ

  1. แสดงไฟล์ Manifest ที่ /.well-known/ard.json หรือลิงก์กับไฟล์ Manifest ด้วย rel=ard หากคุณใช้ ai-catalog.json หรือ rel=ai-catalog ให้เปลี่ยนไปใช้ชื่อใหม่
  2. แก้ไขข้อผิดพลาดที่แสดงในตารางการตรวจสอบเพื่อให้ไฟล์ Manifest ตรงกับสคีมา ARD
  3. ระบุตัวระบุ urn:air:... และ url หรือ data เพียง 1 รายการให้กับทุกรายการ
  4. ใช้ประเภทสื่อ ARD มาตรฐานในtype หากมี
  5. เพิ่ม representativeQueries 2-5 รายการในแต่ละรายการเพื่อให้ได้คะแนนเต็ม