注册表加入目录后可能发生变化或离线。注册表健康检查会持续监控，让用户了解注册表是否正常工作，也帮助维护者尽早发现问题。
我们会检查注册表是否在线、是否符合注册表格式，以及能否与 shadcn CLI 配合使用。检查结果会汇总为状态和评分。
我们会收集评分数据，但目前不会据此影响注册表的可见性或排序。正式上线前，评分模型和阈值可能会调整。
**注册表健康检查仅适用于 shadcn/ui 注册表目录中的注册表。**它不会监控或影响私有注册表、直接在项目中配置的注册表，或通过 owner/repo/item 地址使用的 GitHub 注册表。
注册表发布后才会开始监控。监控不会决定注册表能否加入目录，检查失败也不会导致其被撤下。未来版本的注册表目录可能会在常规浏览中隐藏不可用的注册表，但仍会将它保留在 API 中。
检查内容#
| 频率 | 检查项 | 检查内容 |
|---|---|---|
| 每小时 | 注册表索引 | 索引在线、有效且配置正确。 |
| 每日 | 注册表项 | 轮换抽样的项目可下载并通过验证。 |
| 每周 | CLI | 轮换抽样的项目可通过 shadcn add --dry-run 使用。 |
项目检查会在约 30 天内轮流覆盖整个目录。定时任务尽力运行，因此我们使用每次实际观察的时间，而不假定所有计划中的检查都已执行。
状态#
状态会显示注册表当前的运行情况：
| 状态 | 含义 |
|---|---|
| Observing | 正在至少 24 小时内收集前 24 次索引检查结果。 |
| Healthy | 初始观察期已结束，近期检查均已通过。 |
| Degraded | 注册表在线，但近期有一项或多项检查失败。 |
| Unavailable | 注册表索引已至少 24 小时未通过检查。 |
初始观察期结束前，注册表也可能变为 Unavailable。出现以下情况时，我们会将注册表标记为 Degraded：
- 索引连续三次检查失败。
- 最新索引不符合注册表模式。
- 至少完成 10 次检查后，抽样项目的通过率仍低于 90%。
- 最近两次 CLI 检查均失败。
状态可能会先于总评分对近期问题作出反应。因此，注册表即使评分较高，也可能处于 Degraded 状态。
每种状态都会附带一条简短、易读的原因说明。API 使用方可以读取稳定的 statusReason.code，也可以显示 statusReason.message。监控器的原始错误不会公开。
可用性检查失败后，注册表需要连续两次通过索引和模式检查才能恢复。其他降级状态会在相应失败检查恢复正常后解除。
评分#
每个注册表都会获得一个满分为 100 分的总评分，由四个部分相加得出。各部分的分值并非各自按 100 分计算。
| 组成部分 | 分值 | 衡量内容 |
|---|---|---|
| 可靠性 | 45 | 过去 7 天和 30 天内注册表索引的可用情况。 |
| 正确性 | 25 | 索引和抽样项目是否符合注册表模式。 |
| 可安装性 | 20 | 抽样项目能否通过 shadcn CLI 安装。 |
| 注册表配置 | 10 | HTTPS、JSON 响应、项目名称唯一性以及注册表名称是否匹配。 |
评分衡量的是可靠性和兼容性，不代表受欢迎程度、代码质量、设计质量或注册表包含的项目数量。
分值计算方式#
近期的可用性比更早的记录权重更高：
Reliability = 45 * (0.65 * availability7d + 0.35 * availability30d)正确性部分中，索引最多占 10 分，抽样项目最多占 15 分：
Correctness = 10 * indexSchemaPassRate30d
+ 15 * sampledItemPassRate30d可安装性根据 CLI 检查结果计算：
Installability = 20 * dryRunPassRate30d注册表配置部分包含四项检查，每项 2.5 分。如果尚未观察到某项配置信号，在能够检查之前，该项先计 1.25 分。
每个组成部分都四舍五入到小数点后三位。公开评分是这些舍入后数值的总和。
新注册表的评分#
新注册表的历史数据不足以支撑可靠评分。我们会将早期结果与所有受监控注册表的平均值进行平滑处理。随着检查数据不断积累，该注册表自身结果所占的比重会逐渐增加。
这样可以避免一次成功检查就得到满分，或一次失败检查就得到零分。这也解释了为什么处于 Observing 状态的注册表仍可能获得接近总体平均值的评分。
供 API 使用方参考的平滑公式为：
(successes + globalMean * priorWeight) / (observations + priorWeight)先验权重根据各项检查的频率设定：
| 指标 | 先验权重 |
|---|---|
| 可用性 | 24 |
| 索引模式有效性 | 12 |
| 抽样项目有效性 | 10 |
| CLI 检查 | 3 |
当整个注册表目录的数据不足以计算平均值时，可用性先验值设为 85%，其他测量比率的先验值设为 90%。公式、权重或阈值发生变化时，必须更新 scoreVersion。
API 中的健康数据#
/r/registries.json 会为每个注册表添加可选的 health 对象，其中包括：
- 当前的
status和statusReason。 - 总评分
score及其组成部分breakdown。 - 经过平滑处理的
availability7d和availability30d可用率，取值范围为 0 到 1。 firstObservedAt、checkedAt和lastSuccessfulCheck时间戳。- 供集成使用的
schemaVersion和scoreVersion。
该对象还包含两个标记：
monitoringLimited表示最近一次注册表索引请求受到 CDN 或 WAF 挑战阻拦。挑战响应不会计为可用性或抽样项目验证失败。- 连续七天不可用后，
hidden会变为true。
目前注册表目录不会使用 hidden 标记。
监控限制#
所有检查都来自同一个托管运行器。因此，延迟只作为内部诊断数据保存，不会影响评分，以免某些地区获得不公平的优势。
CDN 和 WAF 挑战也会单独处理。挑战只表示我们的运行器无法完成检查，并不代表该注册表对所有人都不可用。
后续计划#
在注册表目录使用健康数据之前，我们会先收集并审查基线数据。监控数据达到可靠水平后，排名、筛选和健康状态界面会作为单独更新发布。