Lighthouse 中的 ARD 一致性校验器：ai-catalog.json 资源发现清单的校验实现与集成指南

Lighthouse 中的 ARD 一致性校验器ai-catalog.json 资源发现清单的校验实现与集成指南【免费下载链接】lighthouseAutomated auditing, performance metrics, and best practices for the web.项目地址: https://gitcode.com/GitHub_Trending/lig/lighthouse本篇指南围绕 Lighthouse 仓库中third-party/ard目录下的 Agentic Resource DiscoveryARD一致性校验工具展开说明它如何将上游ards-project/ard-spec的 Python 一致性测试脚本移植为 JavaScript 模块ConformanceTester以及为适配 Lighthouse 运行环境所做的四项关键改造结构化错误返回、预编译独立校验器、ESM 格式校验、lighthouse-logger 日志。读完本文你将掌握 ARD 校验规则的具体内容、ai-catalog.json清单的字段约束与校验语义以及如何在依赖升级和 CI 中同步上游规范。ARD Conformance Validator 是什么Agentic Resource DiscoveryARD是一套让自主 AI Agent 与注册表registry发现并验证 Web 上资源Agent、工具、能力等的规范其核心载体是ai-catalog.json能力清单capability manifest文件。ARD 规范同时维护了一套官方一致性测试工具Conformance Testing Tool用于判断某个ai-catalog.json是否完全符合规范要求。Lighthouse 中的third-party/ard目录README是该工具的JavaScript 移植版本上游信息如下上游仓库ards-project/ard-spec源脚本conformance/bin/conformance-testSchemaspec/schemas/ai-catalog.schema.json锁定提交Pinned Commit SHAaa3e598bb7752a9175897823234311216acfa864移植的核心目标是保持校验规则与测试套件与上游1:1 对等同时让代码能够在 Lighthouse 的浏览器/打包环境下安全运行。移植后的主要产物有三个文件文件作用third-party/ard/ard.jsConformanceTester类实现对应上游validate_manifest逻辑third-party/ard/schema-validator.js预编译的独立 JSON Schema 校验器由构建脚本自动生成third-party/ard/ard-test.js与上游校验规则逐条对齐的单元测试Schema 本体位于 third-party/ard/spec/schemas/ai-catalog.schema.json许可协议为 Apache-2.0见 LICENSE。为 Lighthouse 集成所做的四项改造README 明确指出尽管校验规则与测试套件保持 1:1 对等但为了集成进 Lighthouse做了如下适配。理解这些改造有助于理解后续每个源文件的形态。1. 结构化错误返回Structured Error Return上游 Python 脚本以 ANSI 彩色字符串输出校验结果移植后的ConformanceTester则把结果存为结构化对象/** * typedef {{ * element: string, * message: string, * }} ValidationError */errors与warnings两个数组中的每一项都是{ element, message }结构见 ard.js。element默认取值为Root在逐条校验entries时会替换为条目的displayName或identifier。这一设计直接服务于 Lighthouse 审计渲染core/audits/agentic/ard-schema.js可以将errors/warnings直接映射为审计详情表格的element、issue、severity三列无需再做字符串解析。2. 预编译独立校验器schema-validator.js这是最关键的一项改造。构建脚本 build/build-ard-schema.js通过yarn build-ard-schema触发在构建期用 Ajv2020 与ajv/dist/standalone把ai-catalog.schema.json预编译成一个纯 JavaScript、无任何外部运行时依赖的校验器schema-validator.js而不是在运行时动态编译。这样做带来三个直接收益规避 CSPunsafe-eval违规运行时不再调用new Function()/eval()因此可以安全地在 Chrome DevTools 前端环境中运行避免浏览器/打包环境下的fs.readFileSyncSchema 不需要在运行时从磁盘读取保持 Ajv 不进入客户端 bundle预编译产物本身自包含schema-validator.js有约 1700 行内嵌格式化后的 Schema 对象与校验函数客户端无需携带完整的 Ajv 库。从产物头部可见生成痕迹// auto-generated by build/build-ard-schema.js /* eslint-disable */ // ts-nocheck import {fullFormats} from ajv-formats/dist/formats.js; export const validate validate20; export default validate20;3. ESM 格式校验uri / date-timeSchema 中url、documentationUrl、logoUrl等字段使用了format: uriupdatedAt使用了format: date-time。构建脚本以静态导入方式从ajv-formats/dist/formats.js引入这两个格式校验器而不是打包完整的ajv-formats动态插件const ajv new Ajv2020({ allErrors: true, allowUnionTypes: true, code: {source: true, esm: true, lines: true}, }); addFormats(ajv, [uri, date-time]);生成时还会把 standalone 代码中 CommonJS 的require(ajv-formats/dist/formats)替换为 ESM 的fullFormats.uri/fullFormats[date-time]引用见 build/build-ard-schema.js保证产物可被 ESM 模块系统直接消费。4. Lighthouse Logger 替换原始console.log全部替换为lighthouse-logger。在ard.js中每条错误/警告在记录到结构数组的同时也会通过log.verbose(ARD, ...)输出详细日志例如add_error(message, element Root) { this.errors.push({element, message}); log.verbose(ARD, Validation Error [${element}]: ${message}); }这样既保留了 CLI 下的可观测性又统一了 Lighthouse 的日志通道。校验规则全解析从 JSON 解析到语义检查ConformanceTester.validate_manifest(raw_content, source_label)见 ard.js的完整校验流程分三个阶段基础 JSON 解析 → 严格 JSON Schema 校验 → 自定义语义/协议校验。第一阶段JSON 解析try { data JSON.parse(raw_content); } catch (e) { this.add_error(Malformed JSON in manifest: ${e}, Root); return false; }无法解析为合法 JSON 时直接报错返回。第二阶段严格 JSON Schema 校验调用预编译校验器validateAiCatalog(manifest_data)。校验失败时提取 Ajv 的errors[0]信息并把instancePath如/entries/0/url转换成点号路径便于阅读当关键字为required时给出人性化提示xxx is a required property。如果校验器本身抛异常例如输入类型异常则记为 warning 并放行保守策略见run_json_schema_validationard.js。Schema 本体ai-catalog.schema.json为 JSON Schema Draft 2020-12根对象约束如下必填字段specVersion枚举值仅1.0、entries可选字段host发布者信息必填displayName可含identifier、documentationUrl、logoUrl、trustManifest根级additionalProperties: false。entries数组中的每个catalogEntry元素字段类型/约束说明identifierstringpattern^urn:air:[a-zA-Z0-9.-](:[a-zA-Z0-9._-])$RFC 8141 规范的 URN格式urn:air:publisher:namespace:agent-namedisplayNamestring必填人类可读名称typestring必填IANA Media Type指明协议包装或载荷结构如application/mcp-server-cardjsonurl/dataoneOf约束二选一且只能选一个url引用完整文档地址format: uridata内嵌完整规格 JSON 对象descriptionstring能力简介tagsstring[]分类与过滤标签capabilitiesstring[]供索引使用的技能/工具/函数标签如[WeatherTool, ForecastTool]representativeQueriesstring[]minItems: 2、maxItems: 5用于向量索引嵌入的代表性自然语言查询versionstring语义化版本号updatedAtstringformat: date-time最后修改时间ISO 8601metadataobject任意键值扩展值限 string/number/boolean/nulltrustManifestobject必填identity零信任安全/身份/合规信封元数据trustManifest子结构还支持identityType枚举spiffe、did、https、other、trustSchema、attestations可验证声明如 SOC 2 审计、合规声明每条必填type、uri、mediaType。第三阶段自定义语义与协议校验Schema 校验通过后ard.js还会执行一组 Schema 难以表达或规范演进中的语义检查specVersion 语义缺失时报错存在但非1.0时给出警告Unrecognized specVersionentries 结构缺失、为null或非数组时报错identifier 的 URN 形态除 Schema 的 pattern 外代码内还维护了更严格的正则const URN_REGEX /^urn:air:([a-zA-Z0-9.-])(?::([a-zA-Z0-9._:-]))?:([a-zA-Z0-9._-])$/;publisher、namespace、agent-name 三段结构不匹配时报错信息会明确给出期望格式urn:air:publisher:namespace:agent-nametype 的标准发现类型白名单见 ard.js使用白名单之外的媒体类型只记警告不阻断const valid_types [ application/ai-catalogjson, application/agent-cardjson, application/a2a-agent-cardjson, application/mcp-server-cardjson, application/agent-skillszip, application/agent-skillsgzip, text/markdown; profile\urn:air:agent-skills\, application/ai-registry, application/ai-registryjson, ];Value-or-Reference 二选一约束url与data同时出现、或同时缺失都报MUST provide exactly one错误representativeQueries 建议缺失或数量不在 25 区间内时警告提示用于向量索引嵌入的推荐区间元素非字符串时报错trustManifest 渐进信任检查非对象时报错缺少必填identity时报错ADR-0003 废弃字段检查根级出现collections数组时报错——该字段已在 ADR-0003 中移除目录层级必须改用entries内type: application/ai-catalogjson建模。最终validate_manifest以this.errors.length 0作为整体通过条件。在 Lighthouse 中的落地ard-schema 审计ARD 校验器并不是孤立组件它被 core/audits/agentic/ard-schema.js 直接引用构成 Lighthouse 的ard-schema审计requiredArtifacts: [AgentResourceDiscovery]支持navigation与snapshot两种模式依据robotsTxtAgentmap、htmlLink、httpHeaderLink等发现信号判断站点是否声明了 ARD 目录若ai-catalog.json返回非 200 或内容为空审计给出 0 分与解释对ard.content调用new ConformanceTester().validate_manifest(content, ai-catalog.json)将errors渲染为Error严重级别、warnings渲染为Low严重级别输出到审计表格评分规则存在 Error 得 0 分仅存在 Low 警告得 0.9 分完全通过得 1 分。也就是说第三方目录中的这个校验器直接决定了 Lighthouse 报告里ai-catalog.json审计的通过与否这是它进入 Lighthouse 客户端的核心应用场景。对应的 Agent 资源发现采集器测试位于 core/test/gather/gatherers/agentic/ard-test.js冒烟测试定义在 cli/test/smokehouse/core-tests.js。测试套件与上游 1:1 对等的保证third-party/ard/ard-test.js 用 Mocha 逐条复刻了上游conformance-test的validate_manifest校验规则覆盖以下场景根节点非对象、缺少specVersion→ ErrorspecVersion为未知值如2.0→ Warning根级出现废弃的collections字段ADR-0003→ Errorentries缺失或非数组 → Error条目非对象、缺少identifier、URN 格式非法如http://not-a-urn→ Error缺少displayName或type→ Error非标准媒体类型 → Warningurl/data同时存在或同时缺失 → ErrorrepresentativeQueries非数组、元素非字符串 → Error数量不在 25 → Warning缺失 → WarningtrustManifest非对象、缺少identity→ Error完全符合规范的清单含url引用形式与data内嵌形式→ 零 Error。完整通过的示例清单摘自测试用例可以当作编写自己ai-catalog.json的模板{ specVersion: 1.0, entries: [ { identifier: urn:air:google:search:web-search, displayName: Web Search API, type: application/mcp-server-cardjson, url: https://example.com/mcp.json, representativeQueries: [search web, find articles], trustManifest: {identity: google.com} } ] }与上游同步更新 conformance 脚本的完整流程ARD 的 Schema 与一致性测试会随上游演进README 给出了明确的同步机制依赖升级期间通过core/scripts/upgrade-deps.sh定期检查同时由 CI 每周监控node core/scripts/update-ard-spec.js --check对应 GitHub Actions 的cron-weekly.yml。同步脚本 core/scripts/update-ard-spec.js 支持两种模式node core/scripts/update-ard-spec.js拉取上游最新提交的ai-catalog.schema.json更新本地 Schema 文件与 README 中锁定的Pinned Commit SHAnode core/scripts/update-ard-spec.js --check仅检查本地锁定 SHA 与上游是否同步只关注spec/schemas/与conformance/前缀下的文件变更不同步时输出受影响文件清单并以退出码 1 结束供 CI 判定。package.json 中对应封装了三个脚本见 package.json# 拉取最新 Schema 并更新锁定的提交 SHA yarn update:ard-spec # 检查本地与上游是否同步CI 每周使用 yarn check:ard-spec # 重新生成预编译独立校验器 schema-validator.js yarn build-ard-schema # 运行 ARD 一致性校验单测 yarn mocha third-party/ard/ard-test.js当检测到上游变更时按以下四步完成升级运行yarn update:ard-spec拉取最新ai-catalog.schema.json并更新锁定的提交 SHA审阅打印出的conformance/bin/conformance-test差异将更新后的校验规则适配进third-party/ard/ard.js运行yarn build-ard-schema重新生成独立校验器schema-validator.js运行yarn mocha third-party/ard/ard-test.js验证一致性测试全部通过。其中--check模式在检测到不同步时会明确打印后续五步操作指引更新 Schema、审阅 diff、同步ard.js与ard-test.js、重建校验器、跑测试并提交可作为自动化升级的 SOP 参考。小结ARD Conformance Validator 是 Lighthouse 引入第三方 Agent 资源发现能力的关键基础设施ConformanceTesterard.js承载了与上游完全对等的校验规则schema-validator.js通过构建期预编译解决了浏览器环境的 CSP 与打包约束而ard-schema审计core/audits/agentic/ard-schema.js将其能力暴露给最终用户。若你的站点提供ai-catalog.json只需保证根级specVersion/entries、条目级identifierURN/displayName/type、url/data二选一以及representativeQueries25 条等约束全部满足即可在 Lighthouse 的 Agentic 浏览类审计中获得满分。【免费下载链接】lighthouseAutomated auditing, performance metrics, and best practices for the web.项目地址: https://gitcode.com/GitHub_Trending/lig/lighthouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考