ard-registry-builder

ARD 注册表构建器

Agentic Resource Discovery（ARD）让 AI 客户端能够在运行时通过搜索发现 Agent、MCP 服务、技能和 API，而不必将它们硬编码。发布者在静态的 ai-catalog.json 能力清单中描述其资源；动态的 Agent 注册表会为这些清单建立索引，并响应 POST /search。此技能可帮助你构建这两者——编写、验证、测试并维护它们，使其真正符合规范并能被发现。

两种产物，一个心智模型——身份与位置：

• 清单（ai-catalog.json，静态）列出各个条目。每个条目的 identifier 都是永久的 urn:air: URN（身份）；其 url/data 是可变的端点（位置）。
• 注册表（REST API，动态）是用于搜索已建立索引条目的服务。

切勿将主机名写入 URN；切勿将 URL 当作身份。ARD 中几乎所有错误都源于混淆了这两者。

捆绑工具（请使用这些工具，不要另造工具）

所有脚本都仅使用 Python 3.8+ 标准库；若存在 jsonschema 库，validate_catalog.py 会使用它（建议：pip install jsonschema），否则会回退到内置检查器。

工具	用途
scripts/validate_catalog.py <path-or-url> [--json] [--strict]	验证清单：JSON Schema 以及 ARD 语义规则。出错时退出码为 1。
scripts/test_registry.py <base-url> [--query T] [--json]	探测在线注册表的 /search（必需）、/agents、/explore，检查其是否符合规范。
scripts/new_catalog.py --template minimal|enterprise|local-dev [--publisher D] [--host N] --out F	创建清单初始模板。
assets/ai-catalog.schema.json	ai-catalog.json 清单格式的 JSON Schema（Draft 2020-12），随附用于离线验证。
assets/ard-entry.schema.json	独立 ARD 条目和 ArdManifest（v0.91 ard.json 格式）的 JSON Schema。可用于逐条验证，或验证仅包含 entries 的清单。
assets/templates/*.json	可用的有效起始模板：minimal、enterprise（含信任信息和注册表条目）、local-dev。

每次编辑后都要验证；发布后还要验证在线 URL，而不只是本地文件。

判断用户的需求

• “创建 / 搭建初始模板 / 开始制作目录” → 工作流 1。
• “验证 / 检查 / 这是否有效 / 为什么无法通过合规性检查 / 修复此清单” → 工作流 2（先运行 validate_catalog.py，再阅读任何内容）。
• “测试 / 探测我的注册表 / 我的 /search 是否有效 / 我的 API 是否符合 ARD” → 工作流 3。
• “添加 Agent / 提升版本 / 更改端点 / 维护” → 工作流 4。
• “X 如何工作”（数据模型、API、信任、发布） → 阅读下方对应的参考资料。

工作流 1 — 构建清单

1. 选择最接近的模板并创建初始文件： python scripts/new_catalog.py --template enterprise --publisher mycorp.com --host "MyCorp AI" --out ./ard.json。 （如果不使用脚手架，可复制 assets/templates/ 中的文件。）
2. 为每种资源设置 identifier（urn:air:<publisher>:<namespace?>:<name>）、 displayName、type（产物的媒体类型），并设置 url 或 data，二者必须且只能设置一个。
3. 添加 description、tags、capabilities，尤其是 representativeQueries（2–5 条 自然语言查询）——这是影响语义搜索发现效果的最大因素。缺少该字段在 v0.91 中属于合规性警告；仍强烈建议提供。
4. 只有在具备真实身份信息或证明材料时才添加 trustManifest；简单条目应保持精简。
5. 根据部署环境选择发布者域名（企业 FQDN、github.com:you 这样的公共命名空间，或仅用于本地的 agent.localhost/example.com）。参见 references/data-model.md。
6. 验证：python scripts/validate_catalog.py ./ard.json。修复问题，直到验证通过。

工作流 2 — 验证 / 调试清单

1. 先运行验证器，再手动读取文件——它能快速定位问题： python scripts/validate_catalog.py <path-or-url>。
2. 按严重程度查看发现的问题。ERROR 必须修复；WARN 应当修复（在 CI 中使用 --strict 强制执行）；INFO 是建议。每条问题都包含 JSON 路径和稳定的 code。
3. 使用 references/validation-rules.md，根据 code 查找修复方法。常见问题：
   • urn-wrong-nid → 将 urn:ai: 改为 urn:air:。
   • value-or-reference → url / data 必须且只能保留一个。
   • schema（oneOf/required/pattern/minItems）→ 修复消息指出的结构。
   • urn-localhost / urn-publisher-fqdn → 使用可验证的域名或预留占位域名。
   • trust-domain-mismatch → 让 trustManifest.identity 域名与 URN 发布者匹配。
4. 重新运行，直到检查通过。在 CI 中，使用 --json（机器可读输出）和 / 或 --strict（有警告时失败）。

工作流 3 — 测试实时注册表 API

1. 探测 API：python scripts/test_registry.py https://registry.example.com/api/v1。 测试器会发送真实的 POST /search 请求，验证 results 封装（每个条目都是包含 score（0–100）和 source 的目录条目），确认格式错误的请求会被拒绝并返回 400 + errorCode + message，并检查可选的 /agents 和 /explore （当服务返回 404 / 501 时跳过，不视为失败）。
2. 如果必需检查失败 → 说明该服务未达到强制最低要求（/search），不符合 ARD 规范。 根据 references/registry-api.md 修复封装 / 状态码。
3. 对于探索性调用，直接使用 curl 请求端点（参见 references/registry-api.md）。

工作流 4 — 更新 / 维护

1. 编辑条目。保持 identifier URN 稳定——它是永久约定。要迁移端点，请更改 url（或 data），不要更改 URN。
2. 工件发生变化时，递增条目的 version 并更新 updatedAt（ISO 8601）。
3. 添加资源 → 追加条目；确保其 identifier 唯一（验证器会标记重复项）。
4. 重新验证文件；如果文件已发布，也要验证实时 URL 并重新探测任何注册表。将“通过验证”视为完成标准。

黄金规则（检查背后的原因）

• URN = 身份，url/data = 位置。 稳定的 URN 能让搜索索引、客户端引用 和编排在底层基础设施迁移时继续正常工作。
• 发布者部分必须是可验证的 FQDN。 注册表会提取该部分，并将其与 trustManifest.identity 绑定，以防止命名空间抢占。localhost 和纯单词会导致问题。
• url 和 data 必须且只能有一个。 企业流水线的可预测解析依赖这一规则。
• score 表示相关性，而非信任度。 切勿根据搜索分数判断安全性；应独立验证 trustManifest。
• 尽早验证、经常验证，并验证实时 URL。 大多数“无法编入索引”的问题都是架构或托管问题，只需运行一次 1 秒钟的验证器就能发现。

参考文件

阅读与任务匹配的文件；每个文件都包含目录。

• references/data-model.md — 清单 / 条目字段、URN 格式、媒体类型、值或引用、信任清单、JSON-LD 上下文扩展，以及已知的 urn:air: 与 urn:ai: 文档不一致问题。
• references/registry-api.md — /search、/explore、/agents、查询 / 筛选模型、 联邦模式和错误代码。
• references/validation-rules.md — 验证器执行的所有检查及其 code 和严重程度。
• references/publishing.md — 众所周知的 URI（ard.json）、CORS、DNS 发现，以及用于测试的公共参考注册表。

评估

evals/evals.json 保存了用于 skill-creator 评估循环的真实任务提示。可用它来评测或回归测试对此 skill 的更改。