diff --git a/AGENTS.md b/AGENTS.md index 4725470..d751113 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,7 +126,7 @@ ComfyUI 的内存、显存和 CPU 是留给出图的。插件闲着的时候应 几个功能对用户的承诺。改这些功能时不能破坏；确需例外，先问维护者： -1. **模型检查（模型医生）从不自己改工作流。** 检查只读；只有用户按了“换上”或“下载”才动节点，而且只换成同一个文件（SHA-256 指纹一致）。只是同名、没法核对的候选，标明“按文件名”由用户决定。下载的来源（C 站按指纹、工作流带的链接、ComfyUI-Manager 模型清单）在界面上写明。完整的判断规则（三档可信度、基础组件只认指纹、下载来源与核对）见 `docs/model-check-rules.md`，改模型检查前先读、改了规则同时改它。 +1. **模型检查（模型医生）从不自己改工作流。** 检查只读；只有用户按了“换上”或“下载”才动节点，而且只换成同一个文件（SHA-256 指纹一致）。只是同名、没法核对的候选，标明“按文件名”由用户决定。下载的来源（C 站按指纹、工作流带的链接、ComfyUI-Manager 模型清单）在界面上写明。完整的判断规则（三档可信度、基础组件只认指纹、下载来源与核对）见 `docs/guides/model-check-rules.md`，改模型检查前先读、改了规则同时改它。 2. **搭配只记住，从不修改参数数值。** 存的时候是什么，放回画布就是什么：强度、CLIP 层数、提示词等一律原样，不用节点默认值顶替，也不替用户“调”。想要别的数值，在画布上调好再存一个新搭配。放上画布只新放一组节点，从不改画布上已有的节点。 ## 6. 清理旧实现 diff --git a/CHANGELOG.md b/CHANGELOG.md index ef176a8..4694dd1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,7 +31,7 @@ - A **Download by name** from ComfyUI-Manager's model list now also says where the list's file is (the site and repository), to help you decide. - A list entry that does not say its type is no longer offered for a node whose type is known. - Without ComfyUI Manager, Model Check says it would add one more place to download from when a model's source is not found. -- The rules of Model Check (what counts as the same model, the confidence levels, foundation components, download sources and where ComfyUI-Manager fits) are now written in one place: `docs/model-check-rules.md`. +- The rules of Model Check (what counts as the same model, the confidence levels, foundation components, download sources and where ComfyUI-Manager fits) are now written in one place: `docs/guides/model-check-rules.md`. ### ⭐ Combos kept from a picture are easy to tell apart (图片存的搭配一眼认得出) - **The card shows the picture you kept it from**, with the main model's cover as a small round badge in its corner, instead of the model's cover alone (several combos of one model used to look the same). diff --git a/docs/architecture/model-resolution.md b/docs/architecture/model-resolution.md index f864d9e..ba71284 100644 --- a/docs/architecture/model-resolution.md +++ b/docs/architecture/model-resolution.md @@ -3,7 +3,7 @@ Read this document for Model Check, workflow provenance, missing-model recovery, hash caches, Civitai metadata resolution, or model scanning. The rules as a whole, in plain words (what counts as the same model, the confidence levels, foundation components, download -sources), are in `docs/model-check-rules.md`; keep both in step. +sources), are in `docs/guides/model-check-rules.md`; keep both in step. ## Identity boundary diff --git a/docs/guides/model-check-rules.md b/docs/guides/model-check-rules.md new file mode 100644 index 0000000..5bf5b6e --- /dev/null +++ b/docs/guides/model-check-rules.md @@ -0,0 +1,90 @@ +# 模型检查（模型医生）的判断规则 + +模型检查是本插件最复杂的部分之一。这一页是它判断规则的**唯一总览**：什么算“同一个模型”，什么只是“可能”，缺的模型从哪里下载、怎么核对。改模型检查之前先读这一页；改了规则，同时改这一页。 + +一句话：**模型检查只认“同一个文件”，唯一可靠的证据是文件指纹（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. **工作流带着的链接**：保存时记下的下载链接（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 核对，对上才算，和别的来源一样。 +- **没指纹**：清单里恰好一个同名、类型也对得上的，才提供“按文件名下载”，并写出清单里的名字和文件在哪个网站 / 仓库，供用户判断。清单没写类型的条目，只在节点类型也不明时才考虑。 +- **基础组件也提供“按文件名下载”**。统一的规矩是：名字只能提出候选；基础组件的同名候选还要再有一条独立证据。本机找回时这条证据是“大小一致”（所以只同名不提供）；下载时这条证据是“官方清单收录了它，而且类型对得上”。再加上下载是用户自己看清“只是同名”后按的，不会自动发生。 +- **没装 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”。