158 lines
16 KiB
Markdown
158 lines
16 KiB
Markdown
# 模型来源中控：链接管理范围与后续方案
|
||
|
||
更新：2026-09-18。实施基线：`1b2013fe69`；接手时先核对最新代码。
|
||
**状态：2026-09-18 已完成“交给 5.6Sol”范围的代码与自动化验收；真实 ComfyUI 后端需重启后再做最终页面复核。** 本文是唯一交接计划，后续原地更新。
|
||
|
||
## 交给 5.6Sol：本轮只做目录范围对齐与基础组件折叠
|
||
|
||
### 目标与已确认原因
|
||
|
||
来源中控仍只管理链接。补齐本地模型列表，让用户通过现有文件夹管理决定纳入哪些目录，同时将基础组件默认收起，降低整理负担。
|
||
|
||
已确认的代码问题：
|
||
|
||
- 中控 `fetchAllLibraryModels()` 调用 `/anomalous/all_scan_models`，后端 `_collect_all_scan_models()` 只读分类模式的 `get_active_folder_types()`，没有遵循当前物理目录模式。
|
||
- 本次本地配置中，物理目录模式的 `clip` 已开启，但分类配置的 `text_encoders` 关闭。这能解释本地库遗漏 CLIP；不能因此认定所有缺项都只有这一种原因。
|
||
- 此接口只枚举 `.safetensors/.ckpt/.pt/.bin/.sft`，遗漏 `.gguf/.pth`，且扩展名比较区分大小写。
|
||
- 上轮提交只补了工作流收集、基础组件标签与对应类别的元数据读取，没有修复本地目录范围。
|
||
|
||
### 一、目录范围与文件格式
|
||
|
||
1. **本地库遵循文件夹管理当前模式。** 分类模式按分类勾选；物理目录模式按物理目录勾选。隐藏目录不遍历、不读取元数据；不自动开启 CLIP 等目录，不改用户配置。
|
||
2. 复用 `api/folder_types.py` 的模式、启用目录规则。若需提取目录枚举，放在该职责内，返回真实的 `type/path_idx/base_dir`；不能只拿物理目录名当模型类别。物理模式下同一类别可对应多个根目录，必须逐根判断，不能把启用其中一个解释为全部启用。
|
||
3. 对同一实际根目录进行规范化去重，保留可被后续接口解析的类别与路径索引。不要按 basename 合并模型；不同目录里的同名文件是独立条目。
|
||
4. 补齐此列表的 GGUF/PTH，并统一大小写判断。仅表示“可列出并记录链接”，不代表这些格式已支持元数据解析、身份恢复或云端识别。不要直接扩大全局 `MODEL_EXTENSIONS` 后让所有读写路径被动接受新格式。
|
||
5. `/all_scan_models` 同时被 `ui_model_selector.js` 使用。先检查两处调用；保持返回结构、分页与 `limit=0` 语义，验证选择器没有因此丢项或出现重复。确需区分调用用途时再加最小兼容参数，不先造专用数据库或另一套扫描系统。
|
||
6. **当前工作流仍列出实际引用的模型**，不被本地库隐藏目录设置抹掉。文件夹设置控制库盘点范围，不能让分享工作流时遗漏依赖。
|
||
|
||
### 二、基础组件默认折叠
|
||
|
||
- 工作流和本地库都保留两个显示组：主要模型直接显示；基础组件放进默认收起的 **“基础组件（高级） · N”**。使用可键盘操作的折叠控件，不再加一层弹窗。
|
||
- 本轮基础组件固定为现有策略已覆盖的 `clip/text_encoders/clip_vision/vae/vae_approx`。Checkpoint、扩散模型、LoRA、ControlNet 留在主要列表。其他已启用类别维持原有展示，避免顺手建设全站“核心/非核心”分类系统。
|
||
- 展开状态由当前中控会话持有，筛选、编辑、保存后的刷新应保留；重新打开默认收起。折叠时不要生成所有组件行的 DOM。
|
||
- 无来源的基础组件显示 **“未填写（可选）”**，不警告、不计入主要模型“来源待补充”数量；已有来源照常查看、修改和保存。
|
||
- “全部/已填写来源/来源待补充”筛选作用于主要模型；组件组独立于这三个来源状态筛选，展开后显示全部组件。搜索同时作用于两组，折叠栏数量随搜索更新；文案明确“基础组件来源可选，不计入待补”。
|
||
- 工作流里确定缺少本地文件的组件，折叠栏仍显示 **“缺少本地文件 × 项”**；该警告按当前范围全部组件计算，不被搜索或来源筛选隐藏。动态下拉选项未知不等于文件缺失，保留上轮判断保护。
|
||
- 底部统计明确标为“主要模型来源：已填写 X / Y”，使用当前搜索与筛选后的主要列表；组件数量单列在折叠栏，不把未填可选来源算成未完成任务。
|
||
- 无主要模型但存在组件时，保留组件入口；不能显示“未检测到任何模型”。目录未纳入范围时提供简短提示“本地库范围跟随设置 → 文件夹管理”，不增加重复配置界面。
|
||
- 所有新增文案同步中英文。使用现有样式变量和中性标签，不加发光、动效或强提醒。
|
||
|
||
### 三、保存、性能与职责边界
|
||
|
||
- 折叠只影响显示，不能删除已有来源或改变底层模型集合。保存到工作流、生成 Note 保留当前整份工作流语义；复制摘要应明确当前显示范围，不能因折叠悄悄改成导出所有内容。
|
||
- 本地保存继续使用准确的 `type/path_idx/subfolder/filename`。未定位实际文件的工作流组件只允许记录工作流链接，不得猜测路径写入 `.civitai.info`。
|
||
- 保留人工链接、原文件名、封面和已有 info。打开、展开、筛选均不触发云端扫描、哈希计算或附属文件写入。
|
||
- 列表枚举继续放在已有工作线程路径；折叠、搜索只处理已加载数据，不反复全盘读取。加载成功但为空、加载失败、尚未加载要能区分；打开时若指定 library 范围也须正确加载。
|
||
- `ui_model_sources.js` 已超过规模阈值：优先把目录结果整形、分组/筛选等有明确职责的逻辑提取到来源中控专用模块，弹窗保留生命周期与协调。只在本轮需要处提取，不做全仓拆分，也不把业务塞入通用 utils。
|
||
|
||
### 修改落点
|
||
|
||
| 位置 | 本轮责任 |
|
||
| --- | --- |
|
||
| `api/folder_types.py`、`api/model_catalog.py` | 当前模式对应的目录范围、路径去重、列表格式支持 |
|
||
| `web/modules/ui_model_sources.js` 及必要的来源专用模块 | 组件折叠、分组筛选、统计、空态与加载状态 |
|
||
| `web/modules/model_policies.js` | 复用现有类型判断，避免改动重命名或身份恢复策略 |
|
||
| `web/modules/locales.js`、`web/styles/10-model-sources.css` | 中英文文案、局部折叠布局 |
|
||
| `tests/model_sources_hub.mjs`、`tests/model_source_components.mjs` | 更新为新交互，同时保留准确定位与保存保护测试 |
|
||
| 对应 Python 测试 | 使用临时目录验证目录模式、过滤与去重，不能拿真实模型做写入夹具 |
|
||
|
||
### 验收清单
|
||
|
||
1. 物理模式开启 `clip`、分类配置关闭 `text_encoders` 时，库仍显示所选物理目录里的 CLIP；反向关闭物理目录时不枚举它。分类模式按自身配置工作。
|
||
2. 多根目录只启用其中一个、路径别名指向同一实际根、不同根有同名文件，均得到正确范围与去重结果；隐藏根目录零遍历、零元数据读取。
|
||
3. 无来源模型仍出现；GGUF/PTH 及大写扩展名可列出。现有格式、分页、选择器调用继续可用。
|
||
4. 基础组件初始折叠，展开后可查看/编辑；切换筛选或保存不丢展开状态与输入内容。主要待补计数不含组件；搜索、仅有组件、全空、加载失败均有明确结果。
|
||
5. 折叠时仍能看到组件缺文件告警；“无来源”和“文件缺失”独立。搜索无匹配不能抹掉当前工作流的缺文件告警。
|
||
6. 折叠与筛选不清空已保存链接。已定位文件准确保存；未知目标不写本地；关闭窗口后迟到请求不重新渲染。
|
||
7. 跑上述两组 JS 测试和对应 Python 目录枚举测试。实际 ComfyUI 验证两个范围、展开/收起、筛选搜索、窄窗口和原有选择器；写入/缺失场景用隔离夹具，不清空真实链接来制造测试条件。
|
||
8. Python 改动需重启 ComfyUI 才生效；只有前端刷新不能证明新接口已加载。不要强停有任务的实例；如暂不能验证新后端，明确报告缺口。
|
||
9. 完成后审查差异、更新本文状态与最窄的架构专题、本地提交，不推送。架构中的目录范围说明也要同步区分分类与物理模式。
|
||
|
||
### 本轮实施记录（2026-09-18）
|
||
|
||
- 已增加文件夹管理范围的统一根目录枚举，来源库按当前分类/物理模式取根，保留 `type/path_idx`、真实路径去重，并只在来源库列表补充大小写无关的 GGUF/PTH。
|
||
- 已提取来源中控专用的数据整形与分组模块；工作流和本地库的基础组件默认折叠，主要模型筛选、组件搜索计数、缺文件提示和当前可见范围复制各自保持独立语义。
|
||
- 自动化验证：来源中控两组 JS 专项测试、95 项 Python 测试、CSS/本地化契约通过；临时目录覆盖物理/分类范围、隐藏根零遍历与零元数据、路径别名、同名文件和 GGUF/PTH 大小写。
|
||
- 已在运行中的 ComfyUI 页面验证默认折叠、键盘展开、来源筛选不隐藏组件、搜索计数、主要模型统计与本地库范围提示；并在独立 Python 进程按真实物理配置确认 7 个启用根，其中 `text_encoders/path_idx=1` 正确对应已开启的 `clip` 根。运行实例未强停；Python 路由仍是重启前模块，目录范围新逻辑须在安全重启后复核。当前浏览器控制器不支持临时窄视口覆盖，窄窗口实机检查仍待补。
|
||
|
||
### 本轮不做
|
||
|
||
多来源切换、HF 抓图/info、平台多选、一键补全、扫描结果共享、全站格式支持和目录设置重做均不做。下文“链接可信度”中的历史识别/保存问题另列后续，不因本次计划一并扩张；若阻断上述验收，才做最小必要修复并说明。
|
||
|
||
## 已完成：工作流基础组件链接展示（2026-09-18）
|
||
|
||
- 复用模型类别判断，显示文本编码器、VAE、预览 VAE、视觉编码器标签；纳入无扩展名的组件选项及 PTH/GGUF 文件引用。
|
||
- 来源待补充使用普通提示，与本地缺失警告独立；保留手动填写和保存到工作流的能力。
|
||
- 基础组件只按对应类别、明确相对路径读取本地元数据，不搜索其他类别或进行云端扫描。不能定位实际文件时不提供本地附属文件写入；无扩展名选项、后端尚不支持定位的文件格式仍可保存工作流链接。
|
||
- 本地库目录范围、封面、文件名保持现状。大于 16 项的组件分批读取，覆盖后端请求上限。
|
||
- 验证：来源中控与组件专项测试通过；真实 ComfyUI 页面确认 CLIP/VAE 标签和已有链接正常。真实库当前没有待补来源条目，缺失、手动填写和保存分支使用隔离夹具验证，未改写用户链接或画布。
|
||
|
||
## 当前方向：先把链接管好
|
||
|
||
中控现阶段定位为模型链接管理页，负责查看、填写、修改、打开与保存来源链接。保留已有工作流/本地库范围与各自保存含义；不因为缩小范围顺手删除现有功能。
|
||
|
||
下次实施优先解决与链接可信度直接相关的问题：
|
||
|
||
- 无来源的模型必须能够被看到并补链接。“没有来源链接”不能成为排除模型的条件。
|
||
- 区分“未填写来源”和“本地缺少模型文件”，不把两者都显示成缺失模型。
|
||
- 自动识别失败返回的搜索页只能作为“去搜索”入口，不能保存为已识别来源、显示识别成功或计入已补全数量。当前 `autoDetectModelSource()` 的搜索回退及调用方提示需要一起检查。
|
||
- 保存成功以实际写入结果为准；明确“保存到本地”和“写入当前工作流”的区别。无法确定本地文件身份时，不凭同名文件猜测写入位置。
|
||
- 保留手工录入的合法网页链接，不把用户填写的地址称为“已验证官方来源”。打开链接不隐式抓图、覆盖介绍或启动扫描。
|
||
|
||
用户报告“缺失来源的模型没有显示”，当前静态代码没有直接按空链接排除列表项。本次已确认目录模式不一致与格式遗漏，见上面的实施范围；其他来源识别与保存问题仍需分别复现，不将它们统称为已修复。
|
||
|
||
## 暂缓一：模型详情的多来源入口
|
||
|
||
双链接可行，但应理解为“同一模型有多个来源”，不是切换到另一份模型数据。以下是后续建议，尚未实现。
|
||
|
||
- 只有一个来源时保持现有入口；两个来源时，详情的来源区域并列显示 `Civitai`、`Hugging Face` 两个文字按钮。无需为了两个链接引入整个页面的切换标签。
|
||
- 如果确实需要默认入口，可提供“首选来源”单选；切换只影响默认打开哪个链接，不改变封面、介绍、模型文件、哈希或扫描设置。
|
||
- 第三个及更多来源再考虑菜单，不预先建设无限多平台管理器。无链接的平台不显示空按钮。
|
||
- 当前 `civitai_url` 是独立字段，`source_url` 是通用自定义来源，不能假定后者必然是 HF。初版可优先复用现有字段；确需额外首选来源字段时，单独定义兼容规则。
|
||
- 多个链接并存不证明文件一致。确认匹配仍依赖现有模型身份规则；不能根据名称近似自动合并模型。
|
||
|
||
不建议首版让“切换来源”同时切换整套封面和 info：这会引入两套详情状态、缓存和失败回退，超出当前链接管理范围。
|
||
|
||
## 暂缓二：扫描来源的单选/多选
|
||
|
||
放在现有扫描向导或相关设置里，不在中控再做另一套扫描控制台。
|
||
|
||
明确区分三件事：
|
||
|
||
| 选项 | 含义 |
|
||
| --- | --- |
|
||
| 模型范围 | 扫描哪些本地模型，沿用现有选择能力 |
|
||
| 来源平台 | 去哪些已支持的平台获取信息，可单选或多选 |
|
||
| 首选链接 | 默认打开哪个已保存来源，与扫描平台互不联动 |
|
||
|
||
推荐平台选择采用复选框：只勾一个就是单来源，勾多个就是多来源，无需再增加“单选模式/多选模式”开关。只展示真正实现并可用的提供方，不能提前让 HF 扫描成为可点击的空功能。
|
||
|
||
多平台补全规则另行实施时必须一起确定：优先复用本地信息、只补缺项、保留人工内容、一个平台失败不丢其他结果、明确取消语义。已有链接不等于已有封面；已有 info 文件也不等于每个字段完整。
|
||
|
||
## 暂缓三：中控与扫描共享结果
|
||
|
||
两者共用现有模型附属信息读写能力，不建立中控专用数据库，也不让两个界面分别维护一份权威副本。
|
||
|
||
- 向导保存结果后，中控在打开时或收到完成通知后重新读取；不用持续轮询所有模型。
|
||
- 中控保存的手工链接，向导可读取并保护。链接只说明用户记录的来源，不代表扫描器已经支持解析该平台。
|
||
- 如增加“补全缺失来源”，仅复用已有扫描任务，限定当前范围并显示真实成功/未找到/失败结果，不自动扫描整个模型库。
|
||
|
||
## 暂缓四：HF 信息补全
|
||
|
||
- 工作流基础组件展示已完成，见上文；不据此扩大本地库目录范围或重做全站模型类型系统。
|
||
- 基础组件保留原文件名，不强制提供封面；没有封面时使用类型图标。
|
||
- 填写 HF 链接时保留现有封面、介绍和 Civitai 信息，不将自定义链接写进 Civitai 身份字段。
|
||
- 将来如实现 HF 信息读取，先只读明确仓库的模型卡与有明确声明的缩略图；缺失时保留本地信息。不做自动抓任意 README 图片、全网找封面或无限平台适配。
|
||
- 图片和介绍的来源与下载链接可以不同，但应可辨别，且不能把仓库级说明误当成已验证的具体文件信息。
|
||
|
||
参考：[HF 模型卡官方说明](https://huggingface.co/docs/hub/model-cards)。这只是后续技术参考，不表示本项目已支持自动抓取。
|
||
|
||
## 后续实施顺序
|
||
|
||
1. 先完成本文“交给 5.6Sol”范围：目录模式对齐、列表格式补齐、基础组件折叠与统计。
|
||
2. 再单独核查历史识别结果与保存反馈，完成链接管理的基本用途。
|
||
3. 确有需要时再做模型详情双来源入口；此时仍不联动封面或扫描。
|
||
4. 最后评估扫描结果共享、平台多选及 HF 元数据读取，逐项实施，不一次打包上线。
|
||
|
||
实施时遵循 [AGENTS.md](../../AGENTS.md)，核对最新代码和相关测试；本文不替代架构契约，也不授权自动启用所有暂缓功能。
|