企业官网建设流程全解析

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 Discovery（ARD）一致性校验工具展开，说明它如何将上游ards-project/ard-spec的 Python 一致性测试脚本移植为 JavaScript 模块ConformanceTester，以及为适配 Lighthouse 运行环境所做的四项关键改造（结构化错误返回、预编译独立校验器、ESM 格式校验、lighthouse-logger 日志）。读完本文，你将掌握 ARD 校验规则的具体内容、ai-catalog.json清单的字段约束与校验语义，以及如何在依赖升级和 CI 中同步上游规范。

ARD Conformance Validator 是什么

Agentic Resource Discovery（ARD）是一套让自主 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-test
• Schema：spec/schemas/ai-catalog.schema.json
• 锁定提交（Pinned Commit SHA）：aa3e598bb7752a9175897823234311216acfa864

移植的核心目标是保持校验规则与测试套件与上游1:1 对等，同时让代码能够在 Lighthouse 的浏览器/打包环境下安全运行。移植后的主要产物有三个文件：

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.readFileSync：Schema 不需要在运行时从磁盘读取；
• 保持 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-time）

Schema 中url、documentationUrl、logoUrl等字段使用了format: "uri"，updatedAt使用了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_validation（ard.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元素：

trustManifest子结构还支持identityType（枚举spiffe、did、https、other）、trustSchema、attestations（可验证声明，如 SOC 2 审计、合规声明，每条必填type、uri、mediaType）。

第三阶段：自定义语义与协议校验

Schema 校验通过后，ard.js还会执行一组 Schema 难以表达或规范演进中的语义检查：

• specVersion 语义：缺失时报错；存在但非"1.0"时给出警告（Unrecognized 'specVersion'）；
• entries 结构：缺失、为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-name>；

• type 的标准发现类型白名单（见 ard.js），使用白名单之外的媒体类型只记警告，不阻断：

const valid_types = [ "application/ai-catalog+json", "application/agent-card+json", "application/a2a-agent-card+json", "application/mcp-server-card+json", "application/agent-skills+zip", "application/agent-skills+gzip", "text/markdown; profile=\"urn:air:agent-skills\"", "application/ai-registry", "application/ai-registry+json", ];

• Value-or-Reference 二选一约束：url与data同时出现、或同时缺失，都报MUST provide exactly one错误；
• representativeQueries 建议：缺失或数量不在 2～5 区间内时警告（提示用于向量索引嵌入的推荐区间），元素非字符串时报错；
• trustManifest 渐进信任检查：非对象时报错；缺少必填identity时报错；
• ADR-0003 废弃字段检查：根级出现collections数组时报错——该字段已在 ADR-0003 中移除，目录层级必须改用entries内type: application/ai-catalog+json建模。

最终validate_manifest以this.errors.length === 0作为整体通过条件。

在 Lighthouse 中的落地：ard-schema 审计

ARD 校验器并不是孤立组件，它被 core/audits/agentic/ard-schema.js 直接引用，构成 Lighthouse 的ard-schema审计（requiredArtifacts: ['AgentResourceDiscovery']，支持navigation与snapshot两种模式）：

1. 依据robotsTxtAgentmap、htmlLink、httpHeaderLink等发现信号判断站点是否声明了 ARD 目录；若ai-catalog.json返回非 200 或内容为空，审计给出 0 分与解释；
2. 对ard.content调用new ConformanceTester().validate_manifest(content, 'ai-catalog.json')；
3. 将errors渲染为Error严重级别、warnings渲染为Low严重级别，输出到审计表格；
4. 评分规则：存在 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→ Error；
• specVersion为未知值（如'2.0'）→ Warning；
• 根级出现废弃的collections字段（ADR-0003）→ Error；
• entries缺失或非数组 → Error；
• 条目非对象、缺少identifier、URN 格式非法（如http://not-a-urn）→ Error；
• 缺少displayName或type→ Error；
• 非标准媒体类型 → Warning；
• url/data同时存在或同时缺失 → Error；
• representativeQueries非数组、元素非字符串 → Error；数量不在 2～5 → Warning；缺失 → Warning；
• trustManifest非对象、缺少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-card+json", "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 SHA；
• node 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

当检测到上游变更时，按以下四步完成升级：

1. 运行yarn update:ard-spec拉取最新ai-catalog.schema.json并更新锁定的提交 SHA；
2. 审阅打印出的conformance/bin/conformance-test差异，将更新后的校验规则适配进third-party/ard/ard.js；
3. 运行yarn build-ard-schema重新生成独立校验器（schema-validator.js）；
4. 运行yarn mocha third-party/ard/ard-test.js验证一致性测试全部通过。

其中--check模式在检测到不同步时，会明确打印后续五步操作指引（更新 Schema、审阅 diff、同步ard.js与ard-test.js、重建校验器、跑测试并提交），可作为自动化升级的 SOP 参考。

小结

ARD Conformance Validator 是 Lighthouse 引入第三方 Agent 资源发现能力的关键基础设施：ConformanceTester（ard.js）承载了与上游完全对等的校验规则，schema-validator.js通过构建期预编译解决了浏览器环境的 CSP 与打包约束，而ard-schema审计（core/audits/agentic/ard-schema.js）将其能力暴露给最终用户。若你的站点提供ai-catalog.json，只需保证根级specVersion/entries、条目级identifier（URN）/displayName/type、url/data二选一以及representativeQueries2～5 条等约束全部满足，即可在 Lighthouse 的 Agentic 浏览类审计中获得满分。

【免费下载链接】lighthouseAutomated auditing, performance metrics, and best practices for the web.项目地址: https://gitcode.com/GitHub_Trending/lig/lighthouse