ChildHood/tools/image-downloader/README.md

参考图素材批量下载工具

从 markdown 文件中提取 URL，按域名自动分类，调用合适的开源工具批量下载图片。

支持的站点类型

引擎	支持站点	说明
gallery-dl	Pinterest、Instagram、Reddit	需 Chrome 登录态 cookies
yt-dlp	YouTube	仅下载视频缩略图
BeautifulSoup4	GAME Watch、博客、Wiki 等	静态页面通用抓取
Playwright	LaunchBox、MobyGames、Getty 等	动态页面 headless 浏览器

安装

# 安装 Python 依赖
pip install -r requirements.txt

# 安装 Playwright 浏览器引擎（BS4 不需要此步骤）
playwright install chromium

使用方法

# 1. 先 dry-run 查看分类结果
python download.py "../../ai-art-research/参考图/参考图素材链接清单.md" --dry-run

# 2. 快速模式（仅 gallery-dl + yt-dlp）
python download.py "../../ai-art-research/参考图/参考图素材链接清单.md" --quick

# 3. 完整下载
python download.py "../../ai-art-research/参考图/参考图素材链接清单.md"

# 4. 仅下载某个章节
python download.py "../../ai-art-research/参考图/参考图素材链接清单.md" --section 我的暑假

# 5. 指定输出目录
python download.py "../../ai-art-research/参考图/参考图素材链接清单.md" -o "../../ai-art-research/参考图"

命令行参数

参数	说明
markdown	包含 URL 的 markdown 文件路径（必填）
-o, --output	输出根目录（默认：markdown 文件所在目录）
--dry-run	仅打印 URL 分类结果，不下载
--section 关键词	仅处理包含指定关键词的章节
--quick	快速模式：仅使用 gallery-dl 和 yt-dlp

输出目录结构

参考图/
├── 游戏截图/
│   ├── 我的暑假/          ← 章节一
│   └── 放学后少年/        ← 章节二
├── 美术风格/              ← 章节四（Lowpoly/怀旧美术）
├── 真实场景/              ← 章节三（千禧年中国城郊）
└── 其他/                  ← 未匹配章节

站点规则配置

site_rules.json 可自定义各站点的抓取行为：

{
  "example.com": {
    "engine": "bs4",
    "img_selector": "img.article-image",
    "min_size_kb": 20,
    "note": "说明文字"
  }
}

字段	类型	说明
engine	string	下载引擎：bs4 / playwright / gallery-dl / yt-dlp
img_selector	string	CSS 选择器（仅 bs4 引擎）
min_size_kb	int	最小图片体积，小于此值的图标被跳过
wait_seconds	int	Playwright 页面等待时间（秒）
scroll_to_load	bool	是否滚动页面触发懒加载
cookies_required	bool	是否需要浏览器 cookies（gallery-dl）
watermark_warning	bool	水印警告标记

注意事项

• Pinterest / Instagram：需要先在 Chrome 浏览器中登录，gallery-dl 会自动读取 cookies
• Getty / Alamy / iStock：下载的图片带水印，仅供美术参考
• 反爬延迟：每次请求间自动加入 1.5~4 秒随机延迟
• 版权声明：所有抓取图片仅供个人美术参考/灵感素材，不应直接用于商业发布