40 KiB
📖 Error & Experience Summary (开发避坑与经验总结)
This document serves as an architectural retrospective and UX diagnostic log for the development of the Anomalous Model Browser. 这份文档旨在记录 Anomalous 插件开发过程中的架构演进、UX 设计教训以及核心 Bug 排查经验。
1. UX Scroll Traps (交互嵌套滚动陷阱)
The Problem (问题): In the Notebook modal, the translation editor had a max-height and overflow-y. Since the parent modal was also scrollable, it created a "Scroll Trap". Hitting the bottom of the editor unpredictably transferred the scroll event to the outer body.
(在笔记本弹窗中，由于翻译编辑器固定了最大高度并允许滚动，导致与父级弹窗的滚动条发生冲突。用户滚动到底部时会突然把外层页面卷走，体验极差。)
The Solution (方案): Removed the max-height and internal scrollbar. Letting the translation editor expand naturally utilizing the primary window scrollbar guarantees a continuous experience.
(彻底移除内部最大高度和滚动条。让编辑器自然撑开，统一使用最外层的主滚动条，保证心流不断档。)
2. Artificial Metadata Pollution (伪造数据的反噬)
The Problem (问题): To make the "Base Model" dropdown look complete, the backend artificially injected hardcoded architectures (SDXL, HunyuanVideo) even if the user didn't own them. This confused users.
(为了让“模型架构”下拉菜单看起来更“丰满”，后端硬编码注入了一些用户根本没下载过的新架构。结果让用户极度困惑，以为自己眼花了。)
The Solution (方案): Data truth must strictly reflect the local disk state. Dropped artificial padding; the UI dropdown now accurately mirrors only the physical files on disk.
(数据必须绝对忠于本地磁盘。删除了所有的硬编码注入，确保下拉菜单严格反映本地真实的生态。)
3. UI Strobe Effects on Grid Hovers (网格悬浮的“光污染”)
The Problem (问题): Standard transition: all 0.2s meant quickly sweeping the mouse across the model grid caused all cards to rapidly light up like a strobe light.
(为卡片设置了标准的 0.2秒 悬浮动画，导致鼠标快速扫过网格时，所有卡片像迪厅频闪一样疯狂亮起，显得非常廉价。)
The Solution (方案): Introduced a transition-delay: 0.08s low-pass filter. The recommended UX range for hover intent is 50ms - 100ms. This 80ms delay is imperceptible for intentional clicks but completely eliminates flashes from accidental sweeps.
(引入了 0.08s 动画延迟作为低通滤波器。根据人机交互体验，区分“无意滑过”与“有意悬停”的黄金推荐区间是 50ms - 100ms。我们采用的 80ms 延迟对正常点击毫无察觉，但完美过滤了鼠标无意扫过造成的闪烁。)
4. The ComfyUI Manager Auto-Update File Wipe (Manager自动更新导致文件丢失)
The Problem (问题): A custom documentation file (docs/核心按钮操作指南_大白话版.md) generated by AI locally was silently deleted when clicking "Update" on the node inside ComfyUI Manager.
(本地让 AI 写的说明文件，在点击 ComfyUI Manager 的更新按钮后离奇失踪了。)
The Solution (方案): ComfyUI Manager's update mechanism often performs a raw git pull or hard reset. If a local file is not tracked in the remote GitHub repository (i.e., you haven't committed and pushed it), it is highly likely to be overwritten or wiped during the sync process. Always commit and push your documentation, or keep personal untracked notes outside the extension directory!
(ComfyUI Manager 的更新机制依赖 Git 同步（类似 git reset --hard 或强制 pull）。如果你在本地创建了文件却没有提交并推送到 GitHub，更新时 Manager 会强行把本地状态与云端对齐，导致这些“未追踪（untracked）”的文件被直接抹杀。教训：重要的文档一定要及时 push，或者别放在插件目录下！)
5. "Hostage" Inline Confirmations (被“绑架”的内联确认)
The Problem (问题): Clicking "Delete" changed the button to "Are you sure?" with a 3-second timeout, but lacked a "Cancel" button. Users misclicking were held hostage for 3 seconds.
(点击删除后会变成“确定删除吗？”并锁定 3 秒，但没有“取消”按钮。用户如果不小心点错，只能像被绑架一样干等 3 秒它恢复。)
The Solution (方案): Wrapped the logic to instantly reveal a secondary [✕] cancel button upon the first click, giving control back immediately.
(在点击删除时，立马在旁边弹出 [✕] 取消按钮。点击取消直接清空倒计时，立刻把控制权还给用户。)
6. First-load "Dead Interface" Avoidance (首次加载的“白屏假死”)
The Problem (问题): Initializing the sidebar to the root directory / presented a blank screen if users only had models nested deep in subfolders.
(插件默认打开根目录 /。如果用户的模型全都在很深的子文件夹里，打开插件就会看到一片空白，以为插件坏了。)
The Solution (方案): Implemented firstLoadDone to automatically force the UI to open the very first directory possessing model_count > 0.
(加入了智能寻路逻辑，插件首次加载时自动扫描目录树，直接定位并打开第一个存有模型的文件夹。)
7. Structural Layout Breakages (流式布局的坍塌)
The Problem (问题): Placing varying lengths of translation tags sequentially caused extreme layout jitter when hovering.
(把中英文标签简单并排放在一起，由于字符串长度不一，鼠标悬浮时极容易发生换行挤压，导致整个界面疯狂跳动。)
The Solution (方案): Enforced a strict "Row-based" flex architecture (align-items: stretch). Each tag pair is locked into a geometrical row.
(采用极其严格的行级 Flex 布局，把中英文双语硬性锁死在同一个拉伸行内，无论字数多少，几何结构绝对稳定。)
8. Modal State Persistence (弹窗状态的幽灵)
The Problem (问题): Closing and reopening the Notebook modal showed a blank editor because the JS object cached this.currentNotebook but the DOM was obliterated.
(关掉笔记本弹窗再打开，右侧编辑器全空。因为 JS 内存里还记着上一次的状态，但 DOM 节点已经被销毁重建了。)
The Solution (方案): Explicitly check cached state during modal initialization and force renderNotebookEditor() if necessary.
(在弹窗初始化时主动校验缓存，强制触发重新渲染，实现了完美的“会话级记忆”。)
9. Missing Visual Feedback for Background Operations (无反馈的幽灵进程)
The Problem (问题): The Notebook "Save" button executed a background fetch perfectly, but provided absolutely no visual feedback. Users assumed it was broken.
(点击“保存”按钮后，后台默默完成了请求，但按钮本身没有任何变化。用户以为没点上，引发数据丢失的焦虑。)
The Solution (方案): Clicking Save instantly changes the button to a green ✅ state for 1.5 seconds.
(点击保存后强制变绿 ✅ 1.5 秒，给用户极强的心理安全感。)
10. Spatial Geometry for Multi-Node Spawning (多节点生成的空间重叠)
The Problem (问题): Spawning an entire Notebook (Main Model + Loras + CLIPs) caused all nodes to clump perfectly at (0,0).
(一键生成整个笔记本（主模型+N个Lora+提示词）到画布时，所有节点全叠在同一个坐标上，变成了一坨。)
The Solution (方案): Implemented a "Relative Offset Matrix Layout" (X + 350*N, Y + 250) and bound it to the mousemove event (Magnetic Sticking).
(加入了偏移矩阵计算，并绑定鼠标移动。用户可以直观地拖着排成流水的节点序列在画布上移动，然后再点击放下。)
11. Localization Host-Environment Constraints (寄生环境的本地化陷阱)
The Problem (问题): Reading document.documentElement.lang failed because ComfyUI forces the host HTML to en-US, breaking our Chinese translations.
(插件试图读取网页根节点的 lang 属性来决定语言。但 ComfyUI 强行把底座设成了纯英文，导致中国用户永远看不到中文提示。)
The Solution (方案): Never trust the host document properties. Rerouted localization strictly to our internal currentLang variable.
(永远不要相信宿主环境。彻底切断外部依赖，纯靠插件内部自己的 currentLang 变量来统治中英文环境。)
12. Strict Path Separator Validation (路径分隔符的玄学崩溃)
The Problem (问题): Windows uses backslashes (\), but assigning anime/model to a node's combo widget failed ComfyUI's strict string matching, causing red nodes.
(Windows 的底层模型路径带反斜杠，但前端组件要求精确匹配字符串，哪怕是一个斜杠方向不对，节点也会标红报错。)
The Solution (方案): Built setWidgetValuePath to normalize both target paths and native options with .replace(/\\/g, '/') before assignment.
(做了一个拦截器，强行把系统内的选项和我们要赋的值全部统一转成正斜杠再进行比较，直接绕过操作系统的路径陷阱。)
13. Backend Starvation During Inference (算力挤兑导致的接口饿死)
The Problem (问题): Fetching plugin data while ComfyUI is generating an image causes timeouts because of PyTorch GIL-locking. (在 ComfyUI 画图满载的时候，点插件会导致接口超时。因为单线程的 Python 完全被 GPU 推理抢占了。) The Solution (方案): Accept it gracefully. Database management and intense GPU inference are mutually exclusive workflows. (优雅地接受这个现实。不需要过度工程化地去做离线队列，画图和管理模型本来就不该同时进行。)
14. DOM Obliteration vs Virtual DOM Hoarding (物理毁灭 vs 虚拟回收)
The Problem (问题): Maintaining performance when navigating folders containing thousands of models.
(当一个文件夹里有上千个模型时，频繁切换文件夹会导致浏览器内存爆炸。)
The Solution (方案): Instead of display: none hoarding, strictly enforce this.grid.innerHTML = '' to physically obliterate nodes and trigger immediate Garbage Collection.
(放弃“隐藏重用”的传统思路。切文件夹时直接暴力清空内部的 HTML 节点，强迫浏览器立马回收内存，保持零负担。)
15. The "Missing Plugin Icon" Trap (LocalStorage 坐标越界飞天)
The Problem (问题): If the floating trigger button was saved at X=3000px on a 4K monitor, loading it on a 1920px laptop rendered it permanently off-screen.
(在大显示器上把插件按钮拖到了最右边，换到小笔记本上时，坐标超出了屏幕，按钮彻底消失，再也点不出来了。)
The Solution (方案): Implemented a bounds clamp checking coordinates against window.innerWidth. If out of bounds, snap it to the bottom-right corner.
(在启动时强制对比当前屏幕大小，一旦发现越界，立刻把它抓回到右下角的安全区内。)
16. The [vite:preloadError] Template Literal Crash (一个反引号引发的血案)
The Problem (问题): A missing backtick in a dynamic ES Module dictionary crashed the entire ComfyUI extension loader before execution. (在汉化字典里不小心删掉了一个反引号，导致 Vite 打包工具报语法错误，整个插件直接在加载前暴毙，UI 按钮全都没了。) The Solution (方案): JS zero-tolerance for syntax errors requires extreme validation. Fixed the missing backtick. (原生 JS 没有任何编译容错，任何语法拼写都必须如履薄冰，及时修复了那个反引号。)
17. Target Size Deduplication Bug (重叠目录的体积匹配悖论)
The Problem (问题): Fixing models by file size required finding exactly one matching file. But users mapping checkpoints and diffusion_models to the same folder caused os.walk to find the same physical file twice, aborting the fix.
(物理寻址兜底算法要求“体积必须唯一”。但用户配置了多个虚拟路径指向同一个物理文件夹，导致同一个文件被扫出两次，系统误判为“体积不唯一”而放弃修复。)
The Solution (方案): Added os.path.realpath deduplication matrix to condense multiple virtual paths back to a single hard drive sector.
(引入了绝对物理地址 realpath 去重机制，无论虚拟路径怎么重叠，物理层面上都将其归一化。)
18. The "Lightweight Scan" Re-Hash Catastrophe (轻量扫描的重算灾难)
The Problem (问题): The lightweight scan (--skip-media) demanded both an .info file and a preview image to skip hashing. Since it didn't download images, it forcefully re-hashed hundreds of GBs of models every time.
(轻量化极速扫描因为不会下载图片，导致“是否跳过计算”的判断条件（既有 info 又有图）永远不成立。引发了灾难性的全盘重新计算 SHA256，慢如蜗牛。)
The Solution (方案): Modified skip logic conditionally: if explicitly skipping media, the existence of .info is sufficient to bypass hashing.
(加入了情境判断：只要是在极速模式下，不管有没有图，只要有文字信息就无条件跳过，恢复了真正的极速。)
19. The Stale Dropdown Visual Residue (顽固的红框残留)
The Problem (问题): Even after a model path was auto-fixed, ComfyUI maintained a permanent red error border on the node if the frontend cache was stale.
(底层其实已经修复并加载了正确的模型，但因为前端选项缓存没刷过来，ComfyUI 死死把节点标红，看着十分闹心。)
The Solution (方案): Forcefully execute delete node.color; delete node.bgcolor; to violently strip native error states without requiring a refresh.
(既然修好了，就直接暴力删除节点的 color 属性，强行洗白红框，无需刷新网页。)
20. The Silent Subprocess Death (DEVNULL 黑洞)
The Problem (问题): scraper.py crashed due to Python indentation, but piping stderr to DEVNULL made it totally invisible. The UI waited forever.
(后台脚本缩进写错了导致崩溃，但代码里把报错信息塞进了无尽深渊 DEVNULL，没有任何提示，前端界面只能干等着，陷入死局。)
The Solution (方案): Never pipe stderr to DEVNULL during active development. Let it log.
(开发阶段绝对不要屏蔽底层报错，必须让 stderr 打印到控制台以便排查。)
21. Tiered Fallback Resolution for O(1) Scans (多级降级寻址打造 O(1) 扫描)
The Problem (问题): Unscanned 10GB models required full disk read to calculate SHA256, taking minutes. (即便是第一次扫描，遇到几十 GB 的新模型，完整计算 SHA256 也要几分钟，用户体验极度卡顿。) The Solution (方案):
- 0ms: Read existing
.info. (直接读取已有的 info) - 0.01s: Extract 64KB JSON header from
.safetensorsviastructfor pre-computed hash. (用 struct 撬开文件头瞬间提取内置的 Hash，降维打击) - Fallback: Full SHA256 only for legacy models. (真找不到了才迫不得已做全量计算)
22. Zero-API Tensor Fingerprinting (零API脱机张量基因识别)
The Problem (问题): HuggingFace or private models returned 404 from Civitai, failing to generate .info and completely breaking UI integration.
(从 HF 拿到的或者是自己练的私模，由于 C站 没有记录，API 直接报错 404，导致模型彻底被忽略，前端里连看都看不到。)
The Solution (方案): Read the first 500 Tensor Keys via struct. Identifying double_blocks.0.img_attn strictly confirms Flux.1 D architecture completely offline.
(不管你有没有网，强行读取模型前 500 层的网络结构。只要看到里面有 double_blocks，直接盖章确认为 Flux 架构。完全脱机，无缝融入前端兼容雷达。)
23. Gemini-Style Popover UI (告别全屏遮罩，采用悬浮弹窗)
The Problem (问题): Center-screen settings modals with blur backgrounds felt heavy and disconnected users from the workspace.
(原本的设置面板是个带有大面积模糊遮罩的全屏居中弹窗，显得特别笨重，像个垃圾网页游戏。)
The Solution (方案): Refactored to a lightweight side-popover (left: 100%; bottom: 15px;) imitating Gemini's web UI, maintaining deep workflow immersion.
(改成绝对定位，像 Gemini 网页端那样从侧边栏右侧悄悄弹出一个悬浮气泡，点外侧自动收起，极大保证了沉浸感。)
24. Dock & Mode Lock (全宽底座与多状态锁死)
The Problem (问题): Floating capsules looked cramped, and entering fullscreen Gallery while the Sidebar menu remained clickable caused DOM rendering conflicts. (底部按钮挤在一起极其难看。而且进入全屏图库的时候，居然还能点左上角的汉堡菜单，导致页面状态直接崩溃交织在一起。) The Solution (方案): Extended to a 100% width solid Dock. Disabled sidebar triggers during fullscreen views via strict State Locks. (把底部做成了满宽的实体底座，稳固了视觉重心。一旦进入图库这种排他性的全视图，强行给菜单上互斥锁，彻底断绝乱按引发的 Bug。)
25. Resolving "Missing" vs "Unscanned" Conflicts (防重叠逻辑拦截自相踩踏)
The Problem (问题): Deleting a model and reloading the workflow popped BOTH the "Missing Model" dark modal and the "Unscanned Model" orange toast.
(把一个模型删掉后重新加载图片，系统一方面觉得“模型丢了”弹出黑框，一方面因为缓存里没它又觉得它是“没扫过的新模型”弹出橙黄色的警告，两个弹窗叠在一块极其弱智。)
The Solution (方案): The unscanned detector now ignores nodes already flagged with red error colors (node.color === "#FF3333"), preventing system overlapping.
(加入了双轨防踩踏：未扫描检测器只要看到这个节点已经红了（彻底丢了），就主动闭嘴放弃拦截，边界极其清晰。)
26. The CSS zoom Devastation (Zoom 属性对坐标系的降维打击)
The Problem (问题): Using zoom to scale the UI broke bounding boxes. container.offsetHeight > window.innerHeight caused Y coordinates to become negative, permanently launching the window off-screen into the void.
(早期为了偷懒，用 CSS zoom 属性来做 UI 缩放。结果它彻底破坏了浏览器的物理坐标系，一旦窗口过大，防越界系统就算出了个负数坐标，导致插件整个闪现飞出屏幕外，再也拖不回来了。)
The Solution (方案): Banned zoom. Transitioned to relative scaling via font-size: calc(16px * var(--anomalous-scale)). Fixed bounding clamps to execute < 0 checks last.
(彻底封杀 zoom。改用 calc(16px * scale) 的底层字体相对推算放大法。并且把防负数的保底检测代码调到了逻辑的最后一行，永远杜绝负数坐标。)
27. Vanilla JS "Fake" i18n Failure (原生状态管理漏斗下的假性汉化失效)
The Problem (问题): Newly added permanent buttons ("UI Scale", "Reset") remained in Chinese when English was toggled. Since we lacked React/Vue two-way binding, they missed the global state update and got stuck.
(新加了“UI缩放”等按钮后，即使点了切换英文，它们还是中文。因为我们没有使用 Vue 的数据绑定，纯靠原生 JS。如果新加了常驻按钮，却忘了把它登记到顶层 langBtn.onclick 突变循环里，它就永远被隔离在旧时间线里了。)
(只要是常驻的按钮，必须强制在语言切换中枢里注册重写一遍。同时开发过程中如果遇到“代码没变”的灵异现象，第一反应永远是按 Ctrl+F5 强制破除浏览器静态缓存。)
28. The Image Cropping Dilemma (图库的裁切与留白博弈)
The Problem (问题): Using object-fit: cover in the image gallery created perfectly uniform grid squares, but brutally decapitated tall images (like 9:16 vertical character portraits).
(在图库排版时，为了让网格看起来绝对整齐，使用了 object-fit: cover。结果导致偏长的图片（如 9:16 的人物竖图）顶部和底部被无情裁掉，经常出现“砍头”现象。)
The Solution (方案): Changed to object-fit: contain and paired it with a deep black background (#000). The images now scale down to fit entirely, and the resulting letterboxing seamlessly blends into the dark UI as a natural frame.
(改为 object-fit: contain，完整显示图片。由于底层卡片背景本身就是极黑（#000），缩小后产生的黑边完美融入了 UI 背景，不仅没有任何违和感，反而像是一圈高级的画框，一举两得。)
29. Vanilla JS Global Click-Outside (原生悬浮面板的全局点击收起)
The Problem (问题): The settings popover only closed if the user explicitly clicked the gear icon again. Clicking elsewhere on the canvas did nothing, making the popover feel rigid and intrusive.
(点击齿轮打开设置悬浮气泡后，必须再点一次齿轮才能关掉。如果随手点一下旁边或者点画布，面板居然不收回，交互显得非常死板和占眼。)
The Solution (方案): Attached a temporary mousedown event listener to the document when the popover opens. If the click target is outside the modal, it triggers display: none and instantly removeEventListener to prevent memory leaks.
(面板弹出时，立刻给全局 document 挂载一个监听器。只要检测到鼠标点击了面板外部区域，立刻收缩面板，并且顺手注销掉这个监听器，实现了极度顺滑的 Gemini 式收放体验且毫无性能负担。)
30. Context Preservation vs UX Intention (上下文保留与用户意图的冲突)
The Problem (问题): After picking a new cover from the Gallery while inside the Model Edit Modal, the UI destroyed the modal, showed the gallery, and then restored the modal upon completion to 'preserve context'. However, users who just wanted to change the cover felt confused, thinking they still needed to click 'Save' to apply it. (在编辑面板中点击更换封面后，UI 会先销毁面板，进入图库，选完后再把编辑面板弹回来以“保留上下文”。但用户其实只想换个封面，重新弹出的面板反而让他们误以为必须再点一次“保存”才算数。) The Solution (方案): Respect the primary intention. When the cover is changed, directly return to the model card/grid. Do not stubbornly restore intermediate modals unless necessary. (顺应主要意图。换完封面直接回到网格卡片，干脆利落。不要去死板地恢复中间态面板。)
31. The Missing Reference Crash (引用丢失导致的状态黑洞)
The Problem (问题): A refactor failed to assign this.models = data.models in the load function. When a UI callback later tried to find the updated model using this.models.find(), JS threw an undefined error and aborted execution midway. This left the UI with both the gallery and grid hidden, resulting in a completely blank screen.
(重构时忘了一行赋值代码，导致 this.models 为空。后续 UI 切换时试图从中查找模型直接报错崩溃。由于崩溃发生在显示/隐藏面板的切换中途，导致所有面板都被隐藏，屏幕变成了彻底的“真空空白”。)
The Solution (方案): Always ensure foundational state variables are populated before executing callbacks that depend on them.
(底层状态变量必须绝对可靠，一旦中途崩溃，UI 的半途状态是毁灭性的。)
32. Backup Entanglement of Non-Platform Models (非平台模型的备份污染)
The Problem (问题): To ensure a 'Reset' always had a fallback, changing any cover backed up the original file to .civitai_bak. For non-Civitai models, this meant user's manual .png covers were forcefully renamed to .civitai_bak, causing severe semantic confusion.
(为了保证“重置”功能永远有退路，之前的逻辑会把任何被替换的封面强行改名为 .civitai_bak。这就导致用户自己放的非 C 站模型封面，也被莫名其妙打上了 C 站的烙印，逻辑极其混乱。)
The Solution (方案): Decouple custom covers by strictly saving them as .preview.* and leaving original standard .png files untouched. Resetting now just deletes the .preview.* file, naturally falling back to the untouched original, or copying the true .civitai_bak if it actually came from Civitai.
(让自定义封面独占 .preview.* 后缀，绝不触碰原有的标准封面。重置时只需删掉自定义后缀，系统就会自然回退。彻底切断了非 C 站模型与 C 站备份标识的无理纠缠。)
33. DOM Video Audio Leaks on innerHTML Clear (DOM 销毁导致的幽灵音频泄漏)
The Problem (问题): When navigating from a model detail view containing an actively playing
34. The Search Bar "Hidden State" Trap (搜索框的隐藏状态盲区)
The Problem (问题): Users typing in the global search bar while viewing a Model Detail panel thought search was broken because the filtered results were successfully generated but the grid container was hidden (display: none).
(用户在模型详细页里直接使用全局搜索框搜索，后台成功过滤了网格卡片，但因为当前网格容器是隐藏状态，用户看不见结果，误以为搜索功能坏了。)
The Solution (方案): Added an explicit state-exit in the searchInput.oninput event. If a detail panel is open, it destroys the panel and forces the grid back to display: grid so results are immediately visible.
(在搜索输入事件中强制介入。只要开始搜索，立刻销毁详情面板并强行把网格视图切换回可见状态，保证搜索结果永远“所见即所得”。)
35. The Metadata Overwrite Paradox (伪元数据强行覆盖的惨案)
The Problem (问题): A background script updating a model's custom name without fetching full Civitai data wrote a .civitai.info file containing only the custom name. This obliterated the real Civitai data (description, tags) and caused the frontend to render an empty detail page.
(后台在更新自定义名字时，遇到了一个没有 .info 的模型，直接暴力生成了一个只包含自定义名字的 .civitai.info。结果反而把原本应有的全量 C 站详情数据给“排挤”掉了，导致详细页一片空白。)
The Solution (方案): Never trust partial updates to structural files. If it's corrupted or just a stub, delete it so the frontend can freshly pull real data from the Civitai API via the Scan Wizard.
(对于结构性文件，宁缺毋滥。发现被污染成只有两个空字段的残疾文件后直接删除，让向导重新去 C 站抓取原汁原味的完整数据。)
36. The API Response Mismatch & Cache Deadlock (前后端格式割裂与缓存死锁)
The Problem (问题): api.py was updated to send an array of strings (['/view?...']) but main.js expected objects ([{url: '/view?...'}]). When trying to fix main.js, the browser's aggressive caching of ComfyUI extensions meant the fix never propagated. Changing api.py to match the cached JS failed until the ComfyUI server was restarted, causing a "nothing works" deadlock.
(后端发送字符串，前端却按对象去读取，导致图片全部变成 undefined 的隐形方块。试图修改前端修复时，遇到浏览器死忠缓存；试图修改后端去迎合缓存时，又遇到 ComfyUI 不重启不重新加载后端的死锁，导致两头受堵。)
The Solution (方案): Implement "Double-Blind Compatibility". The backend strictly returns structural objects {'url': ...} to satisfy legacy cached frontends, and the frontend JS falls back via el.src = img.url || img; to parse anything. Most importantly: ALWAYS restart ComfyUI completely when touching backend Python APIs.
(实施"双盲兼容"。后端退回发送对象格式来迎合那些死活不肯刷新的旧版缓存；前端同时加上 img.url || img 双轨读取能力。最核心的教训：只要改了后端的 Python 文件，别折腾了，必须彻底重启整个控制台黑框。)
37. The Identifier Collision Catastrophe (变量重名引发的插件暴毙)
The Problem (问题): When moving the "Model Doctor" button from TopNav to the Sidebar, a new const doctorBtn declaration was injected without removing the original one. Since both lived in the same function scope, JavaScript threw SyntaxError: Identifier 'doctorBtn' has already been declared at parse time, which silently killed the entire plugin before any code executed — including the trigger icon.
(把"模型医生"按钮从顶部导航栏搬到底部侧边栏时，新代码里声明了一个新的 const doctorBtn，但旧的那个忘删了。由于两个 const 在同一个函数作用域里，JS 直接在编译阶段就报语法错误，整个插件的代码一行都不会执行——连那个 📦 入口图标都跟着蒸发了。)
The Solution (方案): When relocating UI elements across DOM zones, always perform a full-text search for the old declaration and its associated event handlers. Remove both the element creation AND its appendChild call. A single leftover const can nuke an entire 5000-line module.
(搬家 UI 元素时，必须全局搜索旧的变量声明和所有关联调用（创建、事件绑定、appendChild），全部清理干净。一个多余的 const 就能让整个 5000 行模块原地爆炸。)
38. The this vs Closure Scope Mismatch (this 指向错误导致的静默失败)
The Problem (问题): hideAllPanels() was defined as a plain const closure function inside createDOM(), but the doctor button's click handler called it as this.hideAllPanels(). Since it was never defined as a class method, this.hideAllPanels resolved to undefined, and calling undefined() threw a TypeError — silently aborting the entire click handler. The doctor panel never became visible, and the node listener never activated, making it look like the button "did nothing".
(hideAllPanels() 是 createDOM() 内部的一个普通闭包函数，但医生按钮的点击回调里错误地用 this.hideAllPanels() 去调用它。由于它并不是类方法，this.hideAllPanels 为 undefined，直接抛出 TypeError。这个错误静默中断了整个 onclick 执行链——面板没打开、节点监听没激活，用户只看到"按钮点了没反应"。)
The Solution (方案): Audit every function reference in click handlers. If it's a closure-scoped const, call it directly (hideAllPanels()). If it's a class method, call via this.. Mixing the two is the most common silent-failure trap in Vanilla JS class patterns.
(必须逐一审计点击回调里的每个函数引用。闭包函数直接裸调，类方法才走 this.。两者混用是原生 JS 类模式中最常见的静默失败陷阱。)
39. The Tool-Escaped Backslash Corruption (编辑工具转义反斜杠的连环陷阱)
The Problem (问题): When fixing a Python str.replace('\\', '/') call via code-editing tools, the tool's internal escaping mechanism quadrupled the backslashes: the file ended up containing replace('\\\\', '/'), which searches for a four-character literal string \\\\ that never exists in real Windows paths. The fix was invisible because the diff output looked correct due to terminal rendering also escaping backslashes. This wasted two full restart-debug cycles.
(通过代码编辑工具修复 Python 的 replace('\\', '/') 时，工具内部的转义机制把反斜杠翻了四倍：文件里实际写入的是 replace('\\\\\\\\', '/')，也就是在搜索一个根本不存在的四字符字符串。更可怕的是，diff 输出看起来是对的，因为终端渲染本身也会做转义，所以肉眼完全看不出问题。白白浪费了两轮重启调试。)
The Solution (方案): Never use hardcoded backslash literals in Python path operations when editing through intermediary tools. Use os.sep or os.path.normpath() instead. These are immune to any escaping chain and are also cross-platform correct. Always verify the actual file content with view_file after editing path-related strings.
(通过中间工具编辑路径代码时，永远不要手写反斜杠字面量。用 os.sep 或 os.path.normpath() 代替，它们对任何转义链路完全免疫，且天然跨平台。编辑完路径相关字符串后，务必用 view_file 验证文件里的实际内容。)
40. The Uninitialized State Guard (未初始化状态的跨入口崩溃)
The Problem (问题): When a user clicked "View Model Profile" from the Model Doctor panel without ever having opened the main browser grid, showDetail() → renderSidebar() was called. But renderSidebar() internally accessed this.foldersData.length, and since loadFolders() (which populates foldersData) only runs when the main grid initializes, foldersData was undefined. The resulting Cannot read properties of undefined (reading 'length') error aborted the entire transition. Similarly, this.historyStack could be undefined if accessed before the class constructor's initialization path completed.
(用户直接从模型医生面板点击"查看模型档案"，但此时从未打开过主浏览器网格。showDetail() 内部调用了 renderSidebar()，而 renderSidebar() 访问了 this.foldersData.length。由于 loadFolders()（负责填充 foldersData）只在主网格初始化时运行，此时 foldersData 还是 undefined，直接报错崩溃。类似地，historyStack 如果在构造函数初始化路径完成前被访问，也会 undefined。)
The Solution (方案): Any cross-entry-point function (accessible from multiple UI paths like Doctor → Detail, or Grid → Detail) must defensively guard ALL state dependencies. Use this.historyStack = this.historyStack || []; and if (this.foldersData) this.renderSidebar();. Never assume the "happy path" initialization order.
(任何可以从多个 UI 入口调用的函数，必须对所有状态依赖做防御性守卫。用 this.x = this.x || [] 和 if (this.x) 兜底。永远不要假设"正常流程"的初始化顺序。)
41. Ternary String Replace Crash (暴力替换引发的连锁崩溃)
The Problem (问题): Using Python code.replace() to globally replace localized strings with window.anomalous_browser_lang === 'zh' ? ... : ... was efficient but dangerous. A previous script accidentally deleted the declaration of const checkUnscannedBtnRef in the language toggle handler while doing a replacement. The missing declaration caused a ReferenceError, which crashed the langBtn.onclick event silently halfway through execution. This left the user permanently stuck in an English interface with no way to switch back, as the re-render code was never reached.
(在使用脚本暴力全局替换双语三元运算符时，不小心干掉了某一个不相干按钮的 const 声明，导致点击语言切换时直接触发 ReferenceError 崩溃。最终结果是，界面再也无法切换回中文，用户被死死锁在英文界面里且没有任何明显报错。)
The Solution (方案): Always test interactive elements (like Language toggles) thoroughly after bulk string replacements. If a bulk replace is needed, verify syntax with node -c web/main.js and double-check variable scopes.
(每次用脚本跑完正则替换后，一定要检查所有的点击事件是否还能完整跑完。或者用 node -c 检查语法。)
42. The CSS ID "Display None" Trap (幽灵般的 CSS ID 冲突)
The Problem (问题): We tried to fix a dynamic translation bug by adding an ID to a DOM element (settingsBtn.id = 'anomalous-settings-btn'). However, the original developer had previously written a CSS rule #anomalous-settings-btn { display: none !important; } in styles.css (inside a narrow-mode @container query). By adding the ID, we unintentionally activated the CSS trap, causing the settings button to vanish completely!
(为了让 JS 能够抓取齿轮按钮更新中英文，我们给它加上了 anomalous-settings-btn 这个 ID。没想到 CSS 样式表里竟然潜伏着一条专门针对这个 ID 的 display: none 隐藏规则。加上 ID 的瞬间，齿轮按钮就因为命中规则而原地蒸发了！)
The Solution (方案): Never assign generic DOM IDs without grep searching the .css files first! We changed the ID to anomalous-global-settings-btn, completely sidestepping the hidden CSS rule.
(在给已有组件加上新的 ID 时，必须先搜索整个 .css 文件确认是否撞名！最终我们用 anomalous-global-settings-btn 作为新 ID 绕过了这个地雷。)
43. The Hash Injection Toggle Misunderstanding (哈希注入总闸的认知错位)
The Problem (问题): The system relied on anomalous_inject_hash (Model Provenance Binding) to inject and read hashes. Users misunderstood this toggle, thinking they could turn it off and still use the Model Doctor to auto-fix nodes. Without the injected hashes, the Model Doctor was completely blind.
(用户误以为关掉“模型溯源绑定”不影响模型医生的工作，结果关掉后生成的工作流完全没有哈希值，导致不论怎么用深度扫描，医生都无法替换爆红节点，形成了一个逻辑认知死锁。)
The Solution (方案): Explicitly documented in the README and Help Panel that the Model Doctor STRICTLY REQUIRES workflows to be exported with this plugin's hash injection enabled.
(在所有文档和帮助面板中加上极其醒目的警告，明确指出模型医生的前提条件，打破用户的认知盲区。)
44. UI Documentation Factual Disconnect (UI 文档的物理错位)
The Problem (问题): The Deep Hash Scan button was physically moved to the Model Doctor panel, but the README and in-app Help Panel still told users to find it in the Scan Wizard / Settings panel.
(把“深度哈希扫描”按钮从设置面板搬到了模型医生面板里，但说明书和 UI 帮助文本没跟着改，还在让用户去设置面板里找，导致用户完全找不到。)
The Solution (方案): Restructured the documentation into a strict visual-flow-based SOP (Standard Operating Procedure). Every UI feature mentioned in the docs is now paired with its exact corresponding Emoji icon (e.g., 🩺, 🤖) and location, completely eliminating navigational ambiguity.
(按视觉动线重构了整份说明书。给文档里提到的每一个按钮都加上了精准的 Emoji 图标（如 🩺、🤖）和精确位置定位，实现了文档与界面的 100% 物理映射。)