Add project rules documentation

Introduce rules.md outlining coding standards, model management, usage, versioning, documentation, testing, security, maintenance, and community guidelines for the ComfyUI-RemoveBackgroundSuite project.
2025-06-30 21:57:50 +08:00
parent 4c1e3f13e8
commit 9e24aece53
1 changed files with 231 additions and 0 deletions
@@ -0,0 +1,231 @@
+# ComfyUI-RemoveBackgroundSuite 项目规则
+
+## 项目概述
+
+ComfyUI-RemoveBackgroundSuite 是一个基于 ComfyUI 的抠图工具包，支持多种抠图模型和细节处理方法。
+
+## 开发规则
+
+### 代码规范
+
+1. **Python 代码风格**
+   - 遵循 PEP 8 规范
+   - 使用 4 个空格缩进
+   - 行长度不超过 120 字符
+   - 使用有意义的变量和函数名
+
+2. **文件命名规范**
+   - Python 文件使用小写字母和下划线：`model_utils.py`
+   - 类名使用 PascalCase：`BiRefNetUltraV3_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 或讨论区提出。