DemonGatanjieu-Anomalous_Model_Browser/docs/guides/model-check-rules.md

模型检查（模型医生）的判断规则

English: model-check-rules.en.md

模型检查是本插件最复杂的部分之一。这一页是它判断规则的唯一总览：什么算“同一个模型”，什么只是“可能”，缺的模型从哪里下载、怎么核对。改模型检查之前先读这一页；改了规则，同时改这一页和英文版。

一句话：模型检查只认“同一个文件”，唯一可靠的证据是文件指纹（SHA-256 哈希）。 名字、路径、封面都不能证明是同一个模型。

1. 指纹从哪里来

装了本插件的人出图、保存工作流时，插件会把用到的每个模型的指纹（SHA-256）和文件大小写进工作流（设置里可以关）。别人打开这个工作流，模型检查就能按指纹在自己电脑上找同一个文件，不管它被改了什么名、放在哪个文件夹。

没装本插件的人存的工作流没有指纹，只剩模型的文件名，能做的事就少得多（见下面的表）。

2. 两类模型

类别	包括	规则
普通模型	大模型（Checkpoint）、UNET / 扩散模型、LoRA、ControlNet、放大模型等	指纹最可靠；没有指纹时，大小或名字可以给出“候选”，由用户确认
基础组件	VAE、TAESD（vae_approx）、CLIP / 文本编码器、CLIP Vision	只认指纹。不按名字猜；大小只能作为手动候选显示

基础组件只认指纹的原因：它们的文件名高度重复（ae.safetensors、clip_l.safetensors、t5xxl_fp16.safetensors……），同名的经常是不同的文件，按名字猜错的风险太大。

3. 本机找回：三档可信度

打开工作流时，模型检查逐个看模型下拉框（包括 rgthree Power Lora Loader 里开着的每一行）：

看到的情况	结论	怎么处理	普通模型	基础组件
下拉框里就有这个值	正常	不动	✓	✓
只是路径里斜杠写法不同	同一个（确定）	可一键换上	✓	✓
本机有指纹一致的文件，只是名字或文件夹不同	同一个（确定）	可一键换上，也可用画布上方提示条的“换上 N 个”一起换	✓	✓
工作流没记指纹但记了大小；本机有同名且大小相同的文件	很可能（半信）	逐行按一下才换，不算进“换上 N 个”	✓	✓（只手动）
本机只有大小完全相同的文件	可能	逐行按一下才换	✓	✓（只手动）
工作流什么都没记（不是本插件存的）；下拉框里恰好一个同名文件	可能	逐行按一下才换	✓	✗ 不提供
好几个文件都可能是它	说不清	不换，让用户自己挑	✓	✓
按指纹和按大小找到的是两个不同文件	冲突	拒绝替换	✓	✓
文件还在，但指纹和工作流记的不一样	文件变了	只提醒，不算缺失、不替换，ComfyUI 照常用它	—	✓

所以普通模型实际上是三档：指纹一致 = 信；同名且同大小 = 半信（很可能）；只同大小或只同名 = 可能。只有第一档能一键或批量换上，后两档都要用户逐行确认。基础组件只有第一档能换上；大小一致（无论名字是否也一样）只作手动候选；只凭名字永远不算。

永远不当作证据的：文件名（除了上表里那两种要确认的情况）、显示名、路径、封面、“看起来像”。确定是同一个文件之后，名字和路径只用来找到下拉框里对应的那一项。

换上的结果只能是这个节点下拉框里本来就有的选项；插件不会往下拉框里塞别的值来假装找到了。确认一个候选只对这一个节点有效，不会被记成以后的规则。

4. 本机没有：从哪里下载

本机确实没有时，模型检查页可以直接下载。来源按这个顺序问，问到就停：

1. Civitai（C 站），按指纹：工作流记了指纹，就问 C 站有没有这个指纹的文件。
2. 工作流带着的链接：本插件保存时记下的下载链接，或者 ComfyUI 自己写进工作流的模型链接（官方模板就带着，在 models 里）：C 站某个版本、Hugging Face / hf-mirror 的文件、GitHub 上的文件。
3. ComfyUI-Manager 的模型清单：本机装的 Manager 自带的 model-list.json，几百个常用模型（大模型、VAE、文本编码器、放大模型、ControlNet……，大多在 Hugging Face 上），按文件名和节点需要的文件夹类型对上。

核对规则：

情况	结果
工作流有指纹，来源文件的 SHA-256 一致	确定，可以直接下载，也算进“下载全部”
工作流有指纹，来源文件的 SHA-256 不一致	拒绝（不是同一个文件）
工作流有指纹，Manager 清单里有几个同名的	逐个核对指纹，只用对上的那个
工作流没有指纹，Manager 清单里恰好一个同名文件	标成“按文件名下载”，写明只是同名、核对不了，由用户决定；不算进“下载全部”，AI 助手（MCP）也不会自动下
工作流没有指纹，清单里有好几个同名的	不提供（不知道是哪一个）

没有指纹时，下载前没有任何东西能拿来核对：所以只是同名，永远只到“可能”，由用户决定。下载下来的文件从此有了自己的指纹，但没有原始指纹可比，证明不了它就是工作流原来用的那个。

5. ComfyUI Manager 的位置

ComfyUI Manager 是一本“官方常用模型的下载目录”：它只回答“这个文件名去哪里下”，不回答“你电脑里这个文件是不是它”（清单里没有指纹，只有文件名、类型、底模和下载地址）。所以：

• 只用在下载这一步，排在 C 站（按指纹）和工作流自带的链接后面；本机找回从不用它当证据。
• 有指纹：清单里同名的文件逐个去下载站点读出 SHA-256 核对，对上才算，和别的来源一样。
• 没指纹：清单里恰好一个同名、类型也对得上的，才提供“按文件名下载”，并写出清单里的名字和文件在哪个网站 / 仓库，供用户判断。清单没写类型的条目，只在节点类型也不明时才考虑。
• 基础组件也提供“按文件名下载”。统一的规矩是：名字只能提出候选；基础组件的同名候选还要再有一条独立证据。本机找回时这条证据是“大小一致”（所以只同名不提供）；下载时这条证据是“官方清单收录了它，而且类型对得上”。再加上下载是用户自己看清“只是同名”后按的，不会自动发生。
• 哪里都没找到的基础组件：那一行有“去 Hugging Face 搜”按钮（开了国内镜像就去 hf-mirror），按文件名打开搜索页，由用户自己找、自己下。插件不替用户挑。通用的名字（model.safetensors、ae.safetensors）可能搜出很多，这正是它不自动做的原因。
• 没装 Manager：就少这一个来源；模型检查页在有模型找不到下载地址时提示“装了 ComfyUI Manager，还能多一个下载来源”。
• 清单从本机装的 Manager 里读（model-list.json），不联网。

下载本身：只从 https 的 C 站、Hugging Face、hf-mirror、GitHub 下；先写 .part，有指纹时核对 SHA-256 一致才改成正式文件名；从不覆盖已有文件；先检查磁盘空间。开了国内镜像时，在 C 站找到的文件如果在 Hugging Face 上有同一个（同一 SHA-256），就改从 hf-mirror 下。某个网站连不上就跳过它，继续问别的。

6. 不变的承诺

（同 AGENTS.md“功能原则”第 1 条）

• 检查只读，从不自己改工作流。只有用户按了“换上”或“下载”才动节点。
• 只换成同一个文件。“可能”和“很可能”都要用户逐行确认。
• 每一项都在界面上说清楚为什么（找到了同一个 / 只是大小相同 / 只是同名……）和下载地址来自哪里。

7. 代码在哪（给维护的 AI）

• 前端判断：web/modules/model_check.js（各种状态和 via）、web/modules/model_policies.js（哪些类型只认指纹）、web/modules/ui_doctor.js（每一项的说明文字）。
• 后端按指纹 / 大小找文件：api/model_resolution.py（/anomalous/resolve_hash_batch）。
• 下载来源：api/download_sources.py（find_source 的顺序和核对）、api/manager_catalog.py（Manager 清单）、api/model_download.py。
• 英文的实现细节：docs/architecture/model-resolution.md、docs/architecture/backend.md 的 “Model downloads”。
• 为什么这么定：docs/decisions/README.md 的 AD-005（认模型不看名字）、AD-006（基础组件只认指纹）、AD-020（下载与 ComfyUI Manager）。