# ComfyUI-RemoveBackgroundSuite 项目规则

## 项目概述

ComfyUI-RemoveBackgroundSuite 是一个基于 ComfyUI 的抠图工具包，支持多种抠图模型和细节处理方法。

## 开发规则

### 代码规范

1. **Python 代码风格**
   - 遵循 PEP 8 规范
   - 使用 4 个空格缩进
   - 行长度不超过 120 字符
   - 使用有意义的变量和函数名

2. **文件命名规范**
   - Python 文件使用小写字母和下划线：`model_utils.py`
   - 类名使用 PascalCase：`BiRefNetUltra_RBS`
   - 函数和变量使用 snake_case：`process_mask`

3. **注释规范**
   - 所有公共函数必须有文档字符串
   - 复杂逻辑需要行内注释
   - 使用中文注释说明业务逻辑

### 节点开发规则

1. **节点命名**
   - 所有节点类名必须以 `_RBS` 结尾
   - 节点显示名称应清晰描述功能

2. **输入输出规范**
   - 明确定义输入参数类型和范围
   - 提供合理的默认值
   - 输出结果应包含适当的元数据

3. **错误处理**
   - 所有节点必须包含适当的错误处理
   - 提供有意义的错误信息
   - 记录详细的错误日志

### 模型管理规则

1. **模型文件目录结构**
   - **BiRefNet 系列模型**：存储在 `models/BiRefNet/` 目录下
     - BiRefNet-General
     - BiRefNet_dynamic  
     - BiRefNet_HR
     - BiRefNet_HR-matting
   - **RMBG 模型**：存储在 `models/transparent-background/` 目录下
   - **其他第三方模型**：按模型类型分别存储在不同目录

2. **模型加载规范**
   - 使用 `model_utils.py` 中的统一加载函数
   - 支持 HuggingFace Hub 自动下载
   - 实现本地缓存机制
   - 支持 GPU 和 CPU 模式
   - 实现内存优化和模型缓存

3. **模型版本管理**
   - 每个模型目录包含完整的模型文件
   - 支持模型文件的版本控制
   - 提供模型兼容性检查
   - 实现模型热更新机制

4. **模型文件命名**
   - 使用统一的文件扩展名（.pth, .bin, .safetensors）
   - 文件名应包含模型版本信息
   - 避免文件名冲突

## 使用规则

### 安装要求

1. **系统要求**
   - Python 3.8 或更高版本
   - 支持 CUDA 的 GPU（推荐）
   - 至少 4GB 内存

2. **依赖管理**
   - 使用 `requirements.txt` 管理依赖
   - 定期更新依赖版本
   - 避免版本冲突

### 性能优化规则

1. **图像处理**
   - 大图像自动缩放到 `max_megapixels` 限制
   - 使用批处理提高效率
   - 实现内存友好的处理流程

2. **模型选择**
   - 根据图像质量选择合适的模型
   - 提供模型性能对比信息
   - 支持模型自动选择

## 版本管理规则

### 版本号规范

使用语义化版本号：`主版本.次版本.修订版本`

- **主版本**：不兼容的 API 修改
- **次版本**：向下兼容的功能性新增
- **修订版本**：向下兼容的问题修正

### 发布流程

1. **开发阶段**
   - 在功能分支开发新功能
   - 编写测试用例
   - 更新文档

2. **测试阶段**
   - 进行功能测试
   - 性能测试
   - 兼容性测试

3. **发布阶段**
   - 更新版本号
   - 更新 CHANGELOG
   - 创建发布标签

## 文档规则

### README 维护

1. **必需内容**
   - 项目简介和特性
   - 安装说明
   - 使用示例
   - 节点说明
   - 更新日志

2. **格式要求**
   - 使用 Markdown 格式
   - 包含代码示例
   - 提供截图说明

### 代码文档

1. **函数文档**
   - 描述功能用途
   - 参数说明
   - 返回值说明
   - 使用示例

2. **类文档**
   - 类的作用和职责
   - 主要方法说明
   - 使用场景

## 测试规则

### 测试覆盖

1. **单元测试**
   - 核心功能必须有测试
   - 测试覆盖率不低于 80%
   - 包含边界条件测试

2. **集成测试**
   - 节点间交互测试
   - 端到端工作流测试
   - 性能测试

### 测试环境

1. **测试数据**
   - 使用标准测试图像
   - 包含各种场景的测试用例
   - 测试数据应公开可用

## 安全规则

### 代码安全

1. **输入验证**
   - 验证所有用户输入
   - 防止路径遍历攻击
   - 限制文件大小

2. **依赖安全**
   - 定期检查依赖漏洞
   - 使用可信的包源
   - 及时更新安全补丁

## 维护规则

### 问题处理

1. **Issue 管理**
   - 及时响应问题报告
   - 提供解决方案或替代方案
   - 记录问题解决过程

2. **代码审查**
   - 所有代码变更需要审查
   - 关注代码质量和性能
   - 确保向后兼容性

### 性能监控

1. **性能指标**
   - 处理速度
   - 内存使用
   - 模型准确率

2. **优化目标**
   - 持续改进性能
   - 减少资源消耗
   - 提高用户体验

## 社区规则

### 交流规范

1. **沟通方式**
   - 使用中文交流
   - 保持礼貌和尊重
   - 提供详细的问题描述

2. **贡献认可**
   - 感谢所有贡献者
   - 在文档中致谢
   - 维护贡献者列表

---

**注意**：这些规则旨在确保项目的质量和可持续性。所有贡献者都应遵循这些规则，如有疑问请通过 Issue 或讨论区提出。