From 8c5d565eecfe55a7e8332283d5dc87903ed81466 Mon Sep 17 00:00:00 2001 From: Your Name Date: Sun, 28 Dec 2025 14:17:36 +0700 Subject: [PATCH] docs: add guidelines and principles for adding and updating nodes. --- .agent/workflows/add-node.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 .agent/workflows/add-node.md diff --git a/.agent/workflows/add-node.md b/.agent/workflows/add-node.md new file mode 100644 index 0000000..9b372cc --- /dev/null +++ b/.agent/workflows/add-node.md @@ -0,0 +1,33 @@ +--- +description: how to add or update nodes in ComfyUI-FrameIO +--- + +Follow these steps to add a new node or update existing ones in this repository. + +### 1. Implementation Principles +- **Asynchronous I/O**: Use `ThreadPoolExecutor` for disk-heavy operations (saving/loading). +- **PyTorch Optimization**: Perform tensor normalization (`.float().div_(255.0)`) directly in PyTorch rather than NumPy to avoid memory overhead. +- **Visual Feedback**: Always include `comfy.utils.ProgressBar`. +- **Standard Outputs**: Every node should return an `INT` as the second output representing the `count` of items processed. +- **Detailed Descriptions**: Include a `DESCRIPTION` class attribute for ComfyUI tooltips. + +### 2. Adding a New Node +1. **Create Python File**: Create a new `.py` file for your node (e.g., `new_node_feature.py`). +2. **Implement Node Class**: + - Ensure `CATEGORY = "FrameIO"`. + - Implement `DESCRIPTION`. + - Implement `RETURN_TYPES = ("IMAGE", "INT")` (or similar). +3. **Register in `__init__.py`**: + - Import `NODE_CLASS_MAPPINGS` and `NODE_DISPLAY_NAME_MAPPINGS` from the new file. + - Update the global mappings in `__init__.py`. +4. **Update Documentation**: + - Add the new node details to `README.md` under the appropriate section. +5. **Security Check**: + - For saving nodes, use `os.path.commonpath` to ensure the target directory is within the ComfyUI `output` folder. + +### 3. Update Checklist +- [ ] Add `DESCRIPTION` to class. +- [ ] Ensure `INT` output for item count. +- [ ] Use `ThreadPoolExecutor` if I/O bound. +- [ ] Update `README.md`. +- [ ] Register in `__init__.py`.