ComfyUI Extension: ComfyUI PS Connector

我不懂编程，所有代码都是AI生成，在WIN下拖动窗口会闪烁，Mac正常（多行文本窗口正常的，无解，如果你有方法，务必告诉我） I don't know how to program, and all the code is generated by AI. Dragging the window flickers on Windows, but it works fine on Mac (multi-line text windows are fine. This problem cannot be solved.. If you have a solution, please be sure to tell me).

注意：所有工作流模版需要导出为API格式 Note: All workflow templates need to be exported in API format

这是一套非常强大且高度定制化的ComfyUI 与 Photoshop (UXP) 联动插件。它不仅支持传统的 API 云端生图，还深度集成了 ComfyUI，甚至支持根据 ComfyUI 工作流动态生成 Photoshop UI 面板、无缝提取 PS 图层/选区/画布、以及自动解析模型与 Lora 触发词。 This is a very powerful and highly customizable integration plugin for ComfyUI and Photoshop (UXP). It not only supports traditional API-based cloud image generation, but also deeply integrates with ComfyUI. It even supports dynamically generating Photoshop UI panels based on ComfyUI workflows, seamlessly extracting PS layers/selections/canvas, and automatically parsing models and Lora trigger words.

以下是为该插件系统编写的详细介绍与使用说明。 Below is a detailed introduction and user manual written for this plugin system.

PS-ComfyUI 智能联动插件 (UXP) 详细说明书 PS-ComfyUI Smart Integration Plugin (UXP) Detailed Manual

一、 插件系统概述 I. Plugin System Overview

本系统由两部分组成：

1. ComfyUI 后端插件 (Python) ：负责提供通信接口、模型/Lora 智能扫描与缓存、工作流读取、以及专用的联动节点（如自动缩放、动态参数获取等）。
2. Photoshop 前端插件 (UXP/JS) ：运行在 Photoshop 内部，提供原生的 UI 面板。支持常规 API 生图（文生图、图生图、局部重绘、扩图）、以及与本地/云端 ComfyUI 的双向深度交互。 ComfyUI端的安装我就不介绍了，PS端的插件AI2PS-plugin_PS.ccx放包里了，可以让Adobe Creative Cloud自行安装或改成zip后缀自行解压到PS的Plug-ins目录。 ComfyUI首次启动时，插件会自动从 GitHub 拉取前置依赖 ComfyUI-Lora-Manager 。安装完成后建议重启一次 ComfyUI。并且会将3个工作流模版复制到所需路径。
3. 打开 PS 插件面板，点击 设置 (Settings) ，在 ComfyUI URL 处填入你的 ComfyUI 地址（默认 http://127.0.0.1:8188 ）。就可以和ComfyUI交互了； 在Base Url里填入你的Nano banana2的第三方API提供商的地址你就可以在PS直接使用Nano banana2了。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

This system consists of two parts:

1. ComfyUI Backend Plugin (Python): Responsible for providing communication interfaces, smart scanning and caching of models/Loras, reading workflows, and dedicated integration nodes (such as auto-scaling, dynamic parameter acquisition, etc.).
2. Photoshop Frontend Plugin (UXP/JS): Runs inside Photoshop, providing native UI panels. It supports standard API image generation (txt2img, img2img, inpainting, outpainting) and seamless bidirectional interaction with local/cloud ComfyUI. I won't introduce the installation of the ComfyUI part. The PS frontend plugin AI2PS-plugin_PS.ccx is included in the package. You can let Adobe Creative Cloud install it automatically, or change the extension to .zip and manually extract it to the PS Plug-ins directory. When ComfyUI is launched for the first time, the plugin will automatically pull the prerequisite dependency ComfyUI-Lora-Manager from GitHub. It is recommended to restart ComfyUI once the installation is complete. It will also copy 3 workflow templates to the required paths.
3. Open the PS plugin panel, click "Settings", and enter your ComfyUI address in the ComfyUI URL field (default is http://127.0.0.1:8188) to start interacting with ComfyUI. By filling in the address of your Nano banana2 third-party API provider in the Base Url, you can directly use Nano banana2 in PS.

二、 ComfyUI 专用节点说明 (面向工作流作者) II. ComfyUI Dedicated Node Instructions (For Workflow Authors)

为了让 PS 插件能完美识别您的工作流，插件提供了几个核心自定义节点（位于 PS_Connector 分类下）： In order for the PS plugin to perfectly recognize your workflows, the plugin provides several core custom nodes (located under the PS_Connector category):

1. PS Workflow Config (PS) 作用：工作流的“配置单”。 只有包含此节点的工作流，才能在 PS 默认模式下完美运作 。 用法：将其连入你的工作流。你可以通过它的选项告诉 PS 插件：“这个工作流需要几张输入图（img1-img4）？”、“是否需要蒙版（msk1-msk4）？” 效果：PS 端会根据这个节点的配置，自动隐藏或显示对应的图片/蒙版上传槽位。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1. PS Workflow Config (PS) Function: The "configuration sheet" of the workflow. Only workflows containing this node can function perfectly in PS Default Mode. Usage: Connect it to your workflow. Through its options, you can tell the PS plugin: "How many input images (img1-img4) does this workflow need?" and "Are masks (msk1-msk4) required?" Effect: The PS frontend will automatically hide or display the corresponding image/mask upload slots based on this node's configuration.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

2. PS Get (Custom UI) 作用：动态 UI 生成标志。如果你想在 PS 里直接控制 ComfyUI 里的某个参数（比如 CFG、Steps、降噪强度、某个文本），就把这个参数转换为输入，然后连接到这个节点。 用法：它是一个“直通”节点。两端都可以连接，对于导入模型、图片，以及多行字符串的节点，连在这些节点输出端旁路，对于节点面板的，填入你想在 PS 中显示的名称（如 "重绘幅度"）。PS 的 自定义模式 (Custom) 会自动读取它，并在 PS 面板里生成一个对应的滑块或输入框。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

2. PS Get (Custom UI) Function: The dynamic UI generation marker. If you want to directly control a specific parameter in ComfyUI from within PS (e.g., CFG, Steps, Denoise strength, or certain text), convert that parameter into an input and connect it to this node. Usage: It is a "passthrough" node. Both ends can be connected. For nodes importing models, images, or multi-line strings, connect it as a bypass at their outputs. For parameters on the node panel, fill in the name you want to display in PS (e.g., "Denoise Strength"). PS's Custom Mode will automatically read it and generate a corresponding slider or input box in the PS panel.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

3. PS Get Image Size 作用：获取图像尺寸，并允许 PS 端介入控制（只在获得的尺寸是提供给最后的采样器使用时PS端才会出现控制UI，否则无UI显示并强制解释为开启）。 用法：串联在图像之后，输出 width 和 height 给潜空间 (Empty Latent) 节点。 效果：PS 面板会生成一个包含宽高输入框和 As img (跟随图像尺寸) 勾选框的组件。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

3. PS Get Image Size Function: Obtains image dimensions and allows the PS frontend to intervene and control them (the control UI will only appear in PS if the obtained dimensions are provided to the final sampler; otherwise, no UI is displayed and it is forced to be interpreted as enabled). Usage: Connect it in series after the image, and output the width and height to the Empty Latent node. Effect: The PS panel will generate a component containing width and height input boxes along with an As img (follow image size) checkbox.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

4. PS Image Preview 作用：专门为 PS 打造的预览节点。 用法：将生成的图像连入此节点，它会生成特殊的临时文件供 PS 端通过 WebSocket 实时抓取并贴回 Photoshop 画布成为带图层的文件

<!-- 这是一个隐藏的分割线，用于打断列表 -->

4. PS Image Preview Function: A preview node specially created for PS. Usage: Connect the generated image to this node. It will generate special temporary files for the PS frontend to fetch in real-time via WebSocket and paste back onto the Photoshop canvas as a layered file.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

5. PSTextReceiver 作用：专门为为llm推理设置的输出节点。 用法：连在最后输出，但一般不需要

<!-- 这是一个隐藏的分割线，用于打断列表 -->

5. PSTextReceiver Function: An output node specifically set up for LLM inference. Usage: Connect it at the final output, though it is generally not needed.

三、 Photoshop 插件使用指南 III. Photoshop Plugin Usage Guide

插件分为Main View (基础 API 模式) 和ComfyUI View (Comfy 联动模式)。点击顶部的切换按钮即可切换。 The plugin is divided into Main View (Basic API Mode) and ComfyUI View (Comfy Integration Mode). Click the toggle button at the top to switch between them.

模式 A：Nano banana2 API / GPT Image2 API 适用于第三方的 API 服务 包含四个子标签页：

1. 文生图 (Page 1)：输入提示词，直接生成图片至 PS 画布。
2. 图生图 (Page 2)：左键点击或右键提取画布，提供参考图生成。
3. 扩图 (Page 3/Outpaint)：在 PS 中框选一个比原图更大的选区，直接点击生成按钮，AI 会自动识别边缘并进行扩展填充。
4. 局部重绘 (Page 4/Inpaint)：在 PS 中用虚线选框圈出需要修改的地方，直接点击生成按钮。插件会自动进行选区遮罩计算，发送给 AI 渲染后精准贴回原处。
5. 设置里参数解释

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1）在插件的设置页面中，“参数格式” 是一个非常硬核且精妙的设置项。它的存在是为了兼容市面上五花八门的第三方大 API 提供商 对Nano banana 各种自定义的生图接口，填入此输入框的格式必须是由 3 个竖线 | 分割的 4 个部分，即：参数A | 符号B | 参数C | 单位D。告诉后端 API，用来接收“比例”的 JSON 字段名是什么；将前端 UI 选择的比例（如 16:9）中的冒号替换为你指定的符号；告诉后端 API，用来接收“分辨率大小”的 JSON 字段名是什么；替换前端 UI 选择的分辨率（如 4K）中的字母 K。 2）模型名自定义：用于替换api提供商设置的生图大模型名称 3）自动化提示词预设：为扩图和局部修改模式提供了提示词的预设。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

Mode A: Nano banana2 API / GPT Image2 API Suitable for third-party API services. Contains four sub-tabs:

1. Txt2Img (Page 1): Enter prompt words to generate images directly onto the PS canvas.
2. Img2Img (Page 2): Left-click or right-click to extract the canvas and provide reference images for generation.
3. Outpaint (Page 3): Select an area larger than the original image in PS and click the generate button. AI will automatically recognize the edges and perform expansion filling.
4. Inpaint (Page 4): Use the dashed marquee tool in PS to circle the area that needs modification, and click the generate button directly. The plugin will automatically calculate the selection mask, send it to AI for rendering, and precisely paste it back into place.
5. Explanation of parameters in Settings:

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1. In the plugin's settings page, "Parameter Format" is a very hardcore and ingenious setting. Its existence is to be compatible with various customized image generation interfaces provided by numerous third-party large API providers for Nano banana. The format filled in this input box must consist of 4 parts separated by 3 vertical bars |, namely: Parameter A | Symbol B | Parameter C | Unit D. This tells the backend API what JSON field name to use to receive the "aspect ratio"; replaces the colon in the aspect ratio selected in the frontend UI (e.g., 16:9) with the symbol you specify; tells the backend API what JSON field name to use to receive the "resolution size"; and replaces the letter 'K' in the resolution selected in the frontend UI (e.g., 4K).
2. Model name customization: Used to replace the name of the large image generation model set by the API provider.
3. Automated prompt presets: Provides prompt presets for outpainting and local modification modes.

模式 B：ComfyUI 联动模式 在此模式下，PS 面板右上角的下拉菜单提供了两种布局： 默认 (Default) 和 自定义 (Custom) 。 设置页面的尺寸会对UI上的宽高值做限制

<!-- 这是一个隐藏的分割线，用于打断列表 -->

Mode B: ComfyUI Integration Mode In this mode, the drop-down menu in the upper right corner of the PS panel provides two layouts: Default and Custom. The size setting item on the settings page will impose restrictions on the width and height values on the UI.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1. 工作流的存放与命名规范 PS 插件只会读取 ComfyUI 特定目录下的工作流： 路径：ComfyUI/user/default/workflows/PSflows/ (请将做好的 API 格式 .json 工作流保存在这里)。 命名规则： 文件名必须以 ( 或 （ 开头才能被识别。 (LLM)开头：被识别为大模型推理工作流（如图生文打标）。 (C)开头：这代表 Custom 工作流。例如 (C)(SDXL) 高清放大.json ，非(C)开头的会被认为是默认模式的工作流，例如 (SDXL) 高清放大.json ，后续的标志代表工作流使用的大模型类型（需按C）

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1. Workflow Storage and Naming Conventions The PS plugin will only read workflows in specific directories of ComfyUI: Path: ComfyUI/user/default/workflows/PSflows/ (Please save your API format .json workflows here). Naming rules: The file name must start with ( or （ to be recognized. Starts with (LLM): Recognized as an LLM inference workflow (e.g., image-to-text tagging). Starts with (C): This represents a Custom workflow. For example, (C)(SDXL) Upscale.json. Those not starting with (C) will be considered default mode workflows, such as (SDXL) Upscale.json. The subsequent tags represent the type of large model used by the workflow (requires pressing C).

<!-- 这是一个隐藏的分割线，用于打断列表 -->

2. 默认模式 (Default Mode) 适用于标准工作流。UI 提供固定的 4 个图像槽和 4 个蒙版槽。 交互操作： 右键点击图片槽：弹出右键菜单。支持：提取画布 (全图)、提取选区 (自动裁剪出虚线选框内容)、上传图层、上传选区为蒙版 (支持自动羽化)。 左键双击图层：调用大模型 (LLM) 对当前图像进行反推打标。 拖拽交换：鼠标按住图片槽可以与其它槽位拖拽互换位置。 Lora 管理：双击面板上的“模型”标签可添加最多 2 个 Lora 槽位。选中 Lora 后，右侧会激活 Trigger Word 按钮，点击即可将触发词复制到剪贴板！

<!-- 这是一个隐藏的分割线，用于打断列表 -->

2. Default Mode Suitable for standard workflows. The UI provides a fixed set of 4 image slots and 4 mask slots. Interactions: Right-click an image slot: Opens the context menu. Supports: Extract Canvas (full image), Extract Selection (automatically crops the content of the dashed marquee), Upload Layer, Upload Selection as Mask (supports auto-feathering). Double-left-click a layer: Calls the large model (LLM) to perform reverse tagging on the current image. Drag to swap: Click and hold an image slot to drag and swap its position with other slots. Lora Management: Double-click the "Model" label on the panel to add up to 2 Lora slots. After selecting a Lora, the Trigger Word button on the right will be activated. Click it to copy the trigger words to the clipboard!

<!-- 这是一个隐藏的分割线，用于打断列表 -->

3. 自定义模式 (Custom Mode) 下拉菜单选择包含 (C) 前缀的工作流后触发。 完全动态的 UI：你不需要懂前端代码。只要你在 ComfyUI 工作流里接了 PS Get 节点，PS 就会自动生成对应的： 文本框（对应 String 节点） 滑动条/数值框（对应 INT/FLOAT 节点，并根据名字智能分配最大最小值，如 "CFG" 范围自动识别为 1-20）。 图片上传槽（对应 Image/Mask 节点）。 动态连线修复：即使你的工作流里只写了 1 个 Lora 节点，你在 PS 面板双击添加了 3 个 Lora，插件会在后台自动调整ComfyUI 的 Lora 节点，不需要手动改连线。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

3. Custom Mode Triggered after selecting a workflow with the (C) prefix from the drop-down menu. Fully Dynamic UI: You don't need to know frontend code. As long as you connect the PS Get node in the ComfyUI workflow, PS will automatically generate the corresponding: Text boxes (corresponding to String nodes). Sliders/numeric input boxes (corresponding to INT/FLOAT nodes, with intelligently assigned min and max values based on the name, e.g., the "CFG" range is automatically recognized as 1-20). Image upload slots (corresponding to Image/Mask nodes). Dynamic wiring fix: Even if you only put 1 Lora node in your workflow, if you double-click to add 3 Loras in the PS panel, the plugin will automatically adjust the ComfyUI Lora nodes in the background. No manual wiring modification is needed.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

4. 生成与回贴 点击 生成 (Generate) ，插件会通过 WebSocket 显示 ComfyUI 渲染进度。 完成后，插件会自动： 将生成的图像 作为新图层 插入到 Photoshop 中。 如果你之前是通过“提取画布”上传的图，并按该尺寸生图，插件会自动将生成的图像作为图层插入原图

<!-- 这是一个隐藏的分割线，用于打断列表 -->

4. Generate and Paste Back Click Generate, and the plugin will display the ComfyUI rendering progress via WebSocket. Once completed, the plugin will automatically: Insert the generated image into Photoshop as a new layer. If the image you previously uploaded was via "Extract Canvas" and you generated an image based on those dimensions, the plugin will automatically insert the generated image as a layer into the original image.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

附注： Note:

<!-- 这是一个隐藏的分割线，用于打断列表 -->

一、 PS Workflow Config (PS) 节点详细使用方法（可见样例工作流） I. Detailed Usage of the PS Workflow Config (PS) Node (See Sample Workflows)

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1. 节点定位与作用

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1. Node Positioning and Function

<!-- 这是一个隐藏的分割线，用于打断列表 -->

适用模式：仅适用于 “默认模式 (Default Mode)”。 作用：它是工作流与 PS 面板通讯的中枢。PS 插件在加载工作流时，会全图寻找这个节点。找到后，顺藤摸瓜地读取连在它身上的所有节点，从而知道“哪个节点是底模”、“哪个节点是图片 1”、“哪个参数控制宽和高”。 注意：这个节点没有输出端，它只是配置节点，只需要把其他节点的输出连到它的输入端即可。 Applicable mode: Only applicable to "Default Mode". Function: It is the hub for communication between the workflow and the PS panel. When loading a workflow, the PS plugin will search the entire graph for this node. Once found, it will trace along the connections to read all nodes attached to it, thereby knowing "which node is the base model", "which node is image 1", and "which parameters control width and height". Note: This node has no output port. It is purely a configuration node, and you only need to connect the outputs of other nodes to its inputs.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

2. 参数与连线详解

<!-- 这是一个隐藏的分割线，用于打断列表 -->

2. Detailed Explanation of Parameters and Wiring

<!-- 这是一个隐藏的分割线，用于打断列表 -->

这些参数控制了 PS 面板的基础行为： model (MODEL) ：连接你的 CheckpointLoader 输出的 MODEL 端。 lora (MODEL) ：如果你的工作流包含 Lora，把 Lora 节点的 MODEL 输出连到这里。 prompt (字符串) ：连接你的 正向提示词输入框 （如 Primitive 节点转换为 String）。 width / height (整数) ：连接控制生成图像宽和高的节点（或 Empty Latent Image 的宽高转换输入）。 image1 到 image4 (IMAGE) ：连接你的 Load Image 节点。你在 PS 界面传的图，就会替换掉这些节点。 mask1 到 mask4 (MASK) ：连接你的 Load Image (as Mask) 节点。 neg_prompt (字符串) ：连接你的 负向提示词 。连了之后，PS 界面会自动多出一个负向提示词折叠框。 size_logic (布尔值) ：不用填，由 PS 面板上的 As Img1 选框控制 long_side_pixels (整数) ：不用填，由 PS 设置面板上的 Szie 值控制 These parameters control the basic behavior of the PS panel: model (MODEL): Connect it to the MODEL output of your CheckpointLoader. lora (MODEL): If your workflow includes a Lora, connect the MODEL output of the Lora node here. prompt (String): Connect your positive prompt input box (e.g., a Primitive node converted to String). width / height (Integer): Connect the nodes that control the width and height of the generated image (or the width/height converted inputs of the Empty Latent Image). image1 to image4 (IMAGE): Connect your Load Image nodes. The images you upload in the PS interface will replace these nodes. mask1 to mask4 (MASK): Connect your Load Image (as Mask) nodes. neg_prompt (String): Connect your negative prompt. Once connected, a collapsible negative prompt box will automatically appear in the PS interface. size_logic (Boolean): No need to fill in; controlled by the As Img1 checkbox on the PS panel. long_side_pixels (Integer): No need to fill in; controlled by the Size value on the PS settings panel.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

img1_req 到 msk4_req (布尔值) ：这是给 PS 界面看的防呆开关。 设为 True ：PS 面板对应的图片槽会显示 橙色加号 。如果用户没传图点生成，PS 会 弹错拦截 。 设为 False ：显示 灰色加号 。用户可以不传图，生成时插件会自动在后台删掉多余的节点和连线。 img1_req to msk4_req (Boolean): These are idiot-proof switches for the PS interface. Set to True: The corresponding image slot on the PS panel will display an orange plus sign. If the user clicks Generate without uploading an image, PS will pop up an error and block the action. Set to False: Displays a gray plus sign. The user can skip uploading an image, and the plugin will automatically delete the extra nodes and wiring in the background during generation.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

二、 PS Get (Custom UI) 节点详细使用方法（可见样例工作流）

<!-- 这是一个隐藏的分割线，用于打断列表 -->

II. Detailed Usage of the PS Get (Custom UI) Node (See Sample Workflows)

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1. 节点定位与作用 适用模式：仅适用于“自定义模式 (Custom Mode)”（工作流文件名必须以 (C) 开头）。 作用：这是一个“直通/万能代理”节点 （Passthrough）。你想在 PS 界面里生成什么控制组件，就把这个节点“串联”在对应参数的连线上。 机制：PS 插件会扫描这个节点。如果它的下游连着 KSampler 的 cfg 端，PS 就会在界面上生成一个控制 CFG 的滑块；如果它上游连着 Load Image ，PS 就会生成一个图片上传槽。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1. Node Positioning and Function Applicable mode: Only applicable to "Custom Mode" (workflow file names must start with (C)). Function: This is a "passthrough/universal proxy" node (Passthrough). Whatever control component you want to generate in the PS interface, you simply connect this node "in series" along the wiring of that parameter. Mechanism: The PS plugin will scan this node. If its downstream connects to the cfg port of KSampler, PS will generate a slider to control CFG on the interface; if its upstream connects to Load Image, PS will generate an image upload slot.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

2. 节点参数 ui_label (输入框)：在这里输入的文字，就是生成到 PS 界面上的 组件名字 （例如填写： 降噪强度 、 重绘参考图 、 衣服颜色 ）。 is_required (布尔值)：仅对图像/蒙版生效。设为 True 时，PS 会强制要求上传该图才能点击生成。 get (输入输出端) ：接受任何类型的数据，并原样输出任何类型的数据。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

2. Node Parameters ui_label (Input Box): The text entered here will be the component name generated on the PS interface (e.g., you can fill in: Denoise Strength, Inpaint Reference Image, Clothing Color). is_required (Boolean): Only effective for images/masks. When set to True, PS will strictly require that the image be uploaded before you can click Generate. get (Input/Output Port): Accepts any type of data and outputs the exact same type of data as is.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

3. 具体使用与接线法 由于 PSGetNode 是 any_type，PS 插件怎么知道该生成文本框、滑块还是上传图片的格子呢？

<!-- 这是一个隐藏的分割线，用于打断列表 -->

3. Specific Usage and Wiring Method Since PSGetNode is an any_type, how does the PS plugin know whether to generate a text box, slider, or image upload grid?

<!-- 这是一个隐藏的分割线，用于打断列表 -->

逆向推导逻辑： 1）向后看（Downstreams）： JS 会顺着 PSGetNode 的连线往下找。如果它连到了 EmptyLatentImage 的 width 端口，JS 会去查 ComfyUI 的节点定义字典（objectInfoCache），发现 width 需要的是 INT（整数），最大值 4096，最小值 64，步长 8。于是 PS 就会生成一个带有这些限制的数字输入框。 2） 向前看（Upstreams）： 如果它往前连到了大模型加载器（CheckpointLoader），JS 就会判定这是一个 MODEL_MARKER，并在 PS 里生成一个包含可用模型的下拉菜单。 3） 关键字识别： 如果连线的端口名包含 width、height、seed、prompt，系统会自动给它们打上特殊标签（Role），触发特定的 UI 渲染逻辑。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

Reverse Deduction Logic:

1. Looking Backward (Downstreams): JS will trace downwards along the connections of PSGetNode. If it connects to the width port of EmptyLatentImage, JS will look up ComfyUI's node definition dictionary (objectInfoCache) and find that width requires an INT (integer) with a maximum of 4096, a minimum of 64, and a step size of 8. Thus, PS will generate a numerical input box with these limits.
2. Looking Forward (Upstreams): If it traces forwards and connects to a large model loader (CheckpointLoader), JS will determine that this is a MODEL_MARKER and generate a drop-down menu containing available models in PS.
3. Keyword Recognition: If the connected port names contain width, height, seed, or prompt, the system will automatically assign them special tags (Roles) to trigger specific UI rendering logic.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

4、 排序与分组逻辑（自定义 UI 布局） 在 ComfyUI 中修改节点标题（Title）时，只要按照 行号.列号_组名 的格式命名（例如：1.1_基础设置，1.2_尺寸），PS 就会自动按照这个规则排版；没有写编号的，按照在 JSON 中的顺序垫底。如果是同一行 (userRow 相同)，且没有列冲突，它们会被包裹在同一个 display: flex; flex-direction: row; 的 div 中，实现并排显示。 如果有 groupLabel，会在上方生成一个标题 Label。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

4. Sorting and Grouping Logic (Custom UI Layout) When modifying the node title in ComfyUI, as long as it is named in the format of RowNumber.ColumnNumber_GroupName (e.g., 1.1_Basic Settings, 1.2_Dimensions), PS will automatically lay it out according to this rule. Those without a number written will be placed at the bottom according to their order in the JSON. If they are in the same row (identical userRow) and there are no column conflicts, they will be wrapped in the same div with display: flex; flex-direction: row; to achieve side-by-side display. If there is a groupLabel, a title label will be generated above them.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

5、 特殊元素的组合与渲染

<!-- 这是一个隐藏的分割线，用于打断列表 -->

5. Combination and Rendering of Special Elements

<!-- 这是一个隐藏的分割线，用于打断列表 -->

通过识别节点的 Role（角色），customize.js 提供了多种“高级定制 UI”的生成逻辑： By recognizing the node's Role, customize.js provides multiple generation logic pathways for "Advanced Custom UI":

 1） 尺寸联动组合 (`SIZE_COMBO`)

识别： 如果 JS 发现有一个 Role 为 WIDTH 的节点和一个 Role 为 HEIGHT 的节点，它们连接到了同一个下游节点（例如都连到了同一个 Latent 节点）。 组合： 插件会触发 createComboSizePair。把它们俩拼成一行，中间加一个 × 号按钮。 功能： 点击 × 号可以一键调换长宽（横竖屏切换）。并且自带防超出最大像素面积的算法（enforceComboLimits）。

1. Size Linkage Combination (SIZE_COMBO) Recognition: If JS discovers a node with the Role WIDTH and a node with the Role HEIGHT, and they connect to the same downstream node (e.g., both connect to the same Latent node). Combination: The plugin triggers createComboSizePair. It splices them into a single row, adding an × button in the middle. Function: Clicking the × button can quickly swap the width and height (switching between landscape and portrait). It also comes with an algorithm to prevent exceeding the maximum pixel area (enforceComboLimits).

<!-- 这是一个隐藏的分割线，用于打断列表 -->

 2） 图片与蒙版成对组合 (`IMAGE` & `MASK`)

识别： 如果一个 PSGetNode 输出 IMAGE，另一个输出 MASK，并且它们都往回溯源到同一个父级图像（通过 upstreamId 判断）。 组合： 插件不会生成两个框，而是把它们合并成一个图片槽（createImageSlot）。 功能： 图片槽的左下角会生成一个切换图标（黑白圆圈），点击可以在原图和蒙版之间原地翻转切换。右键菜单会自动判断当前是图片状态还是蒙版状态，提供“提取 PS 选区”、“提取 PS 图层”、“提取为蒙版”等功能。 2) Image and Mask Paired Combination (IMAGE & MASK) Recognition: If one PSGetNode outputs IMAGE and another outputs MASK, and they both trace back to the same parent image (judged via upstreamId). Combination: The plugin will not generate two boxes; instead, it merges them into a single image slot (createImageSlot). Function: A toggle icon (a black and white circle) will be generated in the lower-left corner of the image slot. Clicking it will flip and switch between the original image and the mask right in place. The context menu will automatically determine whether it is currently in an image state or a mask state, providing functions like "Extract PS Selection", "Extract PS Layer", and "Extract as Mask".

<!-- 这是一个隐藏的分割线，用于打断列表 -->

 3） 动态大模型与 LoRA 注入 (`MODEL_MARKER` & `LORA_MARKER`)

识别： 只要连了 CheckpointLoader，就会生成模型下拉框（createCustomModelRow）。 组合机制： 这是一个极高难度的操作。在 PS 面板中，“模型”标签（Label）被设计为可以双击的。双击后，下方会动态生成最多 3 个 LoRA 选择框、权重滑块以及“触发词复制”按钮。 底层重构： 在点击生成时，JS 会在前端拦截 JSON，利用 customLoraValues，动态在 JSON 里凭空插拔构建 LoraLoader 节点链。这就是为什么在 ComfyUI 里不需要画 LoRA 节点，PS 面板里依然可以使用 LoRA 的原因。 3) Dynamic Large Model and LoRA Injection (MODEL_MARKER & LORA_MARKER) Recognition: As long as a CheckpointLoader is connected, a model drop-down box will be generated (createCustomModelRow). Combination Mechanism: This is a highly advanced operation. In the PS panel, the "Model" label is designed to be double-clickable. After double-clicking, up to 3 LoRA selection boxes, weight sliders, and a "Copy Trigger Word" button will be dynamically generated below. Underlying Reconstruction: When clicking generate, JS intercepts the JSON on the frontend, utilizes customLoraValues, and dynamically plugs in and builds a chain of LoraLoader nodes out of thin air within the JSON. This is why you don't need to draw LoRA nodes in ComfyUI, yet you can still use LoRAs perfectly from the PS panel.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

 4） 随机种子生成器 (`SEED`)

识别： 如果连线的端口叫 seed。 UI 生成： 生成一个数字输入框 + 一个“刷新”按钮 + 一个“fixed”复选框。 逻辑： 每次生成完毕，JS 会自动给输入框填入一个随机数（模拟 ComfyUI 的 randomized 功能）。如果勾选了 fixed，则不再刷新。 4) Random Seed Generator (SEED) Recognition: If the connected port is named seed. UI Generation: Generates a numerical input box + a "Refresh" button + a "fixed" checkbox. Logic: After each generation is completed, JS automatically fills the input box with a random number (simulating ComfyUI's randomized function). If "fixed" is checked, it will no longer refresh.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

 5) 获取画布尺寸开关 (`PSGetImageSize` 节点)

这是一个专门在 Python 中注册的新节点，专门用来处理图生图/重绘的尺寸逻辑。 UI 表现： createGetImageSizeRow。包含长宽输入框 + 一键调换按钮 + "As img" (跟随图像) 复选框。 交互逻辑： 勾选 "As img" 后，输入框置灰。点击生成时，如果勾选了该项，PS 会自动读取关联图像（提取自 PS 图层的图片）的真实尺寸，并强行覆盖 ComfyUI 里的宽和高。如果没勾选，则使用用户手动输入的尺寸。 5) Get Canvas Size Switch (PSGetImageSize Node) This is a new node specifically registered in Python, dedicated to handling the dimension logic for img2img/inpainting. UI Representation: createGetImageSizeRow. It contains width and height input boxes + a one-click swap button + an "As img" (follow image) checkbox. Interactive Logic: After checking "As img", the input boxes are grayed out. When clicking generate, if this option is checked, PS will automatically read the true dimensions of the associated image (the image extracted from the PS layer) and forcibly override the width and height in ComfyUI. If not checked, the manually entered dimensions provided by the user will be used.

三、 智能模型管理 TXT 文件格式与配置

<!-- 这是一个隐藏的分割线，用于打断列表 -->

III. Smart Model Management TXT File Format and Configuration

<!-- 这是一个隐藏的分割线，用于打断列表 -->

为了让 PS 的下拉菜单干净清爽，并且支持 Lora 触发词一键复制，插件设计了一套基于 TXT 缓存的智能读取机制。 To keep the PS drop-down menus clean and fresh, and to support one-click copying of Lora trigger words, the plugin designed a smart reading mechanism based on TXT caching.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1. 文件位置与生成逻辑 位置：ComfyUI 根目录下的 user/default/PSdate/model.txt 和 lora.txt。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

1. File Location and Generation Logic Location: model.txt and lora.txt under the user/default/PSdate/ directory in the ComfyUI root folder.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

生成方式：在 PS 插件面板点击 刷新模型列表 时，后端的 routes.py 会扫描你的 checkpoints 、 unet 、 loras 文件夹，并寻找同名的.json 文件（是通过ComfyUI-Lora-Manager生成的），提取元数据后写入这俩 TXT 文件，所以务必先在ComfyUI-Lora-Manager整理模型和lora信息。 Generation Method: When you click "Refresh Model List" on the PS plugin panel, the backend routes.py will scan your checkpoints, unet, and loras folders, and look for .json files of the same name (which are generated via ComfyUI-Lora-Manager). It extracts the metadata and writes it into these two TXT files. Therefore, be sure to organize your model and Lora information in ComfyUI-Lora-Manager first.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

2. TXT 文件的格式解析 打开 lora.txt，你会看到每行都是这种格式（字段之间用 ｜ 或 | 隔开）：

<!-- 这是一个隐藏的分割线，用于打断列表 -->

2. TXT File Format Parsing Open lora.txt and you will see that each line is in this format (fields are separated by ｜ or |):

<!-- 这是一个隐藏的分割线，用于打断列表 -->

[前缀符号]相对路径 ｜ 模型名 ｜ 绝对物理路径 ｜ 基础底模 ｜ 触发词 [Prefix Symbol]Relative Path | Model Name | Absolute Physical Path | Base Model | Trigger Words

<!-- 这是一个隐藏的分割线，用于打断列表 -->

示例 Example anime/pixel_art.safetensors ｜ PixelArt v1 ｜ D:/ComfyUI/models/loras/anime/pixel_art.safetensors ｜ SDXL ｜ pixel art, 1girl

<!-- 这是一个隐藏的分割线，用于打断列表 -->

各字段含义： 1） 前缀：&，如果文件没有匹配到 JSON 导致不知道底模，第四个字段会显示为 - ，或者JSON里显示Unknown，会自动加&屏蔽；，用户自定义屏蔽该文件。 2）相对路径：在下拉菜单中显示的实际文件名（包含子文件夹）。 3）模型名：JSON 里读取到的作者取的花名。 4） 绝对物理路径：用于后端去重，防止 ComfyUI 配置了多个路径导致重复扫描。 5）基础底模 (Base Model)： Civitai的分类规范 常见的值有 SDXL , SD 1.5 , Illustrious , Pony 。 6） 触发词 (Trigger Words)：仅 Lora.txt 有触发词。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

Meaning of each field:

1. Prefix: &. If the file does not match a JSON, resulting in an unknown base model, the fourth field will display as -, or if the JSON shows 'Unknown', & will automatically be added to mask it. Users can also customize masking for this file.
2. Relative Path: The actual file name displayed in the drop-down menu (including subfolders).
3. Model Name: The nickname chosen by the author, read from the JSON.
4. Absolute Physical Path: Used by the backend for deduplication to prevent repeated scanning if ComfyUI has multiple paths configured.
5. Base Model: Civitai's classification specification. Common values include SDXL, SD 1.5, Illustrious, Pony.
6. Trigger Words: Only lora.txt contains trigger words.

<!-- 这是一个隐藏的分割线，用于打断列表 -->

3. 如何实现“只显示对应底模”的智能过滤？ 规则：在 PS 中读取的工作流文件名，如果在括号里写了底模名，PS 就会自动过滤 TXT。 举例：你的工作流命名为 (C)(SDXL) 高清质感放大.json。 效果：PS 读取到 SDXL，然后去 model.txt 和 lora.txt 里面找。只有第四个字段（基础底模）包含 SDXL 的模型，才会被显示在下拉菜单里。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

3. How to achieve smart filtering that "only displays the corresponding base model"? Rule: For the workflow file names read in PS, if the base model name is written inside parentheses, PS will automatically filter the TXT. Example: Your workflow is named (C)(SDXL) High-Res Texture Upscale.json. Effect: PS reads SDXL, and then searches in model.txt and lora.txt. Only models where the fourth field (Base Model) contains SDXL will be displayed in the drop-down menu.<!-- 这是一个隐藏的分割线，用于打断列表 -->

<!-- 这是一个隐藏的分割线，用于打断列表 -->

4. 如何手动配置和修改 TXT 有时候由于没有下载 JSON 导致扫描出来的触发词为空，或者底模识别不到。你可以手动修改 TXT 的底模名称和触发词，以及，系统设计了对修改的保护机制 。

<!-- 这是一个隐藏的分割线，用于打断列表 -->

4. How to manually configure and modify the TXT Sometimes, because the JSON was not downloaded, the scanned trigger words end up empty, or the base model cannot be recognized. You can manually modify the base model name and trigger words in the TXT, and the system is designed with a protection mechanism for these modifications.