结构化健康检查契约

本页介绍面向检查作者的结构化健康检查契约。操作者运行 doctor 时无需了解本页内容。

结构化健康检查¶

若要检查 registry 克隆形态，请运行 openclaw doctor --lint --only core/doctor/project-clone-shape --json。 该检查也会在普通 Doctor 和 --lint --all 中运行。 不可读的克隆会产生一条跳过检查（skipped-inspection）警告，而不会中断其余检查。 修复指南会移除所有 partial-clone 过滤器，从 origin 重新拉取（仅在需要时取消 shallow），按 ID 获取缺失对象，清除 promisor 设置和 extensions.partialclone，然后重新打包。在手动执行这些网络和磁盘操作之前，请参阅修复顺序。

使用结构化健康检查注册表的 Doctor 检查项声明了一个小型拆分契约：

detect(ctx, scope?) -> HealthFinding[]
repair?(ctx, findings) -> HealthRepairResult

detect() 为 doctor --lint 提供能力。repair() 是可选的，并且只在 doctor --fix / doctor --repair 下运行。只声明 run() 处理器而没有声明 healthChecks 的 Doctor 贡献不会通过此契约暴露。

修复上下文（repair contexts）可以携带 dryRun/diff 请求；修复结果可以返回结构化的 diffs（配置/文件编辑）和 effects（服务、进程、包、状态或其他副作用），因此迁移后的检查可以逐步支持 doctor --fix --dry-run，而无需将变更规划移入 detect()。

repair() 返回 status: "repaired" | "skipped" | "failed"（省略状态时表示 repaired）。当修复返回 skipped 或 failed 时，doctor 会报告原因，并跳过对该检查项的验证。修复成功后，doctor 会在已修复的 findings 范围内重新运行 detect()；如果 finding 仍然存在，doctor 会报告一条修复警告，而不是将此次变更视为已完成。

一个 finding 包含以下字段：

声明了结构化健康检查的 Core doctor 检查项仍会附着于拥有其面向用户的 doctor / doctor --fix 行为的那个有序 doctor contribution 上。共享的结构化健康检查注册表是扩展点：一旦所属包在活动命令路径中注册了内置（bundled）或插件支持的检查项，这些检查项就会在 core doctor 检查项之后运行。openclaw/plugin-sdk/health 为插件作者暴露了相同的契约。