SplazMatte 项目的 AI 协作规范与编码约定
- 不要提前实现未来可能需要的功能。MVP 阶段只做设计文档中明确描述的功能。
- 不要因为"以后可能用到"就添加额外的抽象层、配置项或扩展点。
- 如果某个功能在 Phase 2 规划中，现在就不要做。
- 选择最简单的实现方式。如果一个函数能解决，不要拆成三个类。
- 避免引入不必要的设计模式。MVP 阶段不需要工厂模式、策略模式等复杂抽象。
- 代码的可读性优先于"优雅"或"灵活"。
- 一步一步来，先让最小的东西跑起来。
- 开发顺序：单模型推理 → Engine 封装 → Pipeline 串联 → Gradio UI。
- 每一步都应该可以独立验证，不依赖后续步骤。
- 先用脚本/命令行验证功能正确性，再考虑接入 UI。
sdks/目录下存放的是开源项目的源代码（SAM 3、MatAnyone、VideoMaMa 等），仅供阅读和参考。- 不要直接 import sdks/ 下的模块。如果需要用到其中的代码逻辑，将相关代码复制到项目自身的模块中（如
engines/、utils/），并根据项目需要进行适当修改。 - 这样做是为了：
- 保持项目代码结构的一致性和可控性
- 避免对上游代码的隐式依赖
- 方便后续定制和维护
- 严格遵循设计文档中定义的目录结构，不要随意新增顶层目录或模块。
- 每个模块职责单一明确，不要出现"utils 里什么都有"的情况。
- 使用 Python 3.10+ 语法特性（type hints、match-case 等）。
- 函数和类必须有 docstring，说明用途、参数和返回值。
- 变量和函数命名使用
snake_case，类命名使用PascalCase。 - 单个函数不超过 50 行。如果超过，考虑拆分。
- 单个文件不超过 300 行。如果超过，考虑拆分模块。
- 不要写用不到的抽象基类。除非确实有多个实现（如 MatAnyone 和 VideoMaMa 共享接口），否则不需要 ABC。
- 不要过早优化。先让功能正确运行，性能问题在实际测试中发现再处理。
- 不要做过度的错误处理。MVP 阶段，合理的异常捕获 + 清晰的错误信息即可，不需要自定义异常层级体系。
- 不要写过度的配置系统。
config.py用简单的常量或 dataclass 即可，不需要 YAML/TOML 解析。 - 不要搞复杂的日志系统。
logging标准库 + 基本的 INFO/ERROR 级别足够。
- 所有依赖在
requirements.txt中声明，并指定版本号。 - 不要引入不必要的第三方库。Python 标准库能解决的就用标准库。
- 大型依赖（PyTorch、Gradio 等）的版本要与模型兼容性对齐。
- 模型权重路径、工作目录等通过
config.py集中管理，不硬编码在业务代码中。 - 路径操作统一使用
pathlib.Path，不用字符串拼接。 - 环境相关的配置（如 GPU 设备号）通过环境变量获取，提供合理的默认值。
- Commit message 使用英文，格式：
<type>: <description>- type:
feat,fix,refactor,docs,chore,test - 例如：
feat: add SAM3 engine with text prompt support
- type:
- 每个 commit 保持原子性，一个 commit 只做一件事。
workspace/、models/、__pycache__/等目录不要提交到 git。
- 修改代码前先阅读相关模块的现有代码，理解上下文。
- 新增功能前先确认：这个功能是 MVP 需要的吗？
- 遇到模型相关问题，先查看
sdks/下的原始实现和文档。 - 每完成一个最小验证单元，确保它能独立运行和测试。