HF Model Downloader

Appearance

text
# Related Code
Makefile             - 构建命令
build.py             - PyInstaller 配置
pyproject.toml       - 项目依赖
.github/workflows/   - CI/CD 流程

开发指南 ​

环境准备 ​

依赖工具 ​

工具用途安装
Python 3.13+运行时brew install python@3.13
uv包管理器（推荐）curl -LsSf https://astral.sh/uv/install.sh | sh
ruff代码检查uv tool install ruff

首次设置 ​

bash
# 克隆仓库
git clone https://github.com/samzong/hf-model-downloader.git
cd hf-model-downloader

# 安装依赖
uv sync

# 验证安装
uv run main.py

开发工作流 ​

日常开发 ​

bash
# 运行应用
make dev
# 或
uv run main.py

# 代码检查
make lint

# 自动修复
make lint-fix

# 格式化
make format

构建测试 ​

bash
# 构建应用
make build

# 创建 DMG (macOS)
make dmg

# 清理构建产物
make clean

Makefile 命令一览 ​

命令说明
make help显示所有命令
make install安装依赖
make dev开发模式运行
make lint代码检查
make lint-fix自动修复
make format代码格式化
make build构建应用
make dmg创建 DMG (macOS)
make clean清理构建产物
make release-dry-run预览下一版本
make release执行发布

代码规范 ​

Ruff 配置 ​

项目使用 ruff 进行代码检查，配置位于 .ruff.toml。

提交规范 ​

使用 Conventional Commits 格式：

<type>(<scope>): <description>

[optional body]

类型：

类型说明版本影响
feat新功能minor
fix修复patch
docs文档patch
refactor重构patch
perf性能patch
test测试patch
chore杂项patch

测试 ​

E2E 测试 ​

bash
# 运行端到端测试
pytest tests/test_e2e_basic.py -v -s

测试内容：

  • 下载小型模型/数据集
  • 验证双平台功能
  • 检查进度回调

构建验证 ​

bash
# 验证构建（不创建 DMG）
make test-build

调试技巧 ​

日志级别 ​

默认日志级别为 INFO。需要更详细的日志：

python
import logging
logging.getLogger("huggingface_hub").setLevel(logging.DEBUG)
logging.getLogger("modelscope").setLevel(logging.DEBUG)

进程调试 ​

下载进程的输出通过 Pipe 发送。调试时可以在 unified_download_model() 函数中添加 print 语句，会通过 Pipe 传递到主进程。

PyInstaller 调试 ​

bash
# 查看打包详情
pyinstaller --debug=all main.py

发布流程 ​

自动发布 ​

推送到 main 分支后，GitHub Actions 自动：

  1. 检测版本变更（基于 Conventional Commits）
  2. 更新版本号和 CHANGELOG
  3. 创建 Git Tag
  4. 触发多平台构建
  5. 上传 DMG/EXE 到 Release
  6. 更新 Homebrew Cask

手动发布 ​

bash
# 预览版本
make release-dry-run

# 执行发布（仅 main 分支）
make release