xinhua-resource-downloader

这个 skill 的工作流分两步：

Preflight（环境预检） — 在做任何下载前，先确保 Python 依赖、Playwright Chromium、ffmpeg 都就绪。
Main workflow（主工作流） — 扫描 → 下载 → 生成报告。

每次任务开始时，先跑预检；如已就绪就跳过，缺什么就装什么。

Step 0 · Preflight 环境预检（每次任务必跑）

跨平台脚本会自动检测并安装所有依赖。运行：

python <skill_dir>/scripts/preflight_check.py

预检动作清单

| 顺序 | 检查项 | 检测方式 | 缺失时的动作 | |---|---|---|---| | 1 | Python ≥ 3.8 | sys.version_info | 直接报错退出，让用户升级 Python | | 2 | playwright | pip show | pip install playwright | | 3 | Pillow | pip show | pip install Pillow | | 4 | requests | pip show | pip install requests | | 5 | Playwright Chromium | playwright install chromium | 自动下载 Chromium 浏览器 | | 6 | ffmpeg | where ffmpeg（Windows）/ which ffmpeg（Unix） | 按平台安装并配置 PATH |

ffmpeg 安装策略（按 OS 分支）

Windows：从 BtbN GitHub Release 下载静态构建 zip，解压到 C:\ffmpeg\，然后用 setx PATH "...;C:\ffmpeg\bin" 永久写入用户 PATH。
macOS：brew install ffmpeg（检测到没装 Homebrew 时给出提示，不静默失败）。
Linux (Debian/Ubuntu)：sudo apt-get update && sudo apt-get install -y ffmpeg。
Linux (Fedora/RHEL)：sudo dnf install -y ffmpeg。
Linux (CentOS/RHEL 旧版)：sudo yum install -y ffmpeg。

ffmpeg PATH 配置策略

优先 which ffmpeg / where ffmpeg，命中即完成。
未命中时扫描常见安装目录（C:\ffmpeg\bin、C:\Program Files\ffmpeg\bin、/usr/local/bin、/opt/homebrew/bin 等），找到则把 bin 目录加进用户 PATH。
仍找不到才触发平台对应的安装流程。
Windows 用 setx 写注册表用户环境变量；macOS / Linux 把 export PATH=...:$PATH 追加到 ~/.bashrc。

预检结果展示

脚本结束时输出表格化的检查报告（OK / FAIL / WARN），并在 PATH 变更后给出提示：

============================================================
 Preflight Check Report
============================================================
 [OK]   Python         3.11.0
 [OK]   playwright     1.61.0       kept
 [OK]   Pillow         12.3.0       kept
 [OK]   requests       2.34.2       kept
 [OK]   chromium       installed    ensured
 [OK]   ffmpeg         ffmpeg version 8.1 ...     kept
       path: D:\Program Files (x86)\ffmpeg\ffmpeg-8.1.2-essentials_build\bin\ffmpeg.exe
============================================================

如果只想看 JSON：

python <skill_dir>/scripts/preflight_check.py --json

跳过 ffmpeg 检测（已知不需要视频/音频转码时）：

python <skill_dir>/scripts/preflight_check.py --skip-ffmpeg

Step 1 · 扫描页面资源

支持两种扫描模式：

1.1 连接当前已打开的浏览器（CDP 模式）

要求浏览器以远程调试模式启动：

# Chrome
chrome.exe --remote-debugging-port=9222

# Edge
msedge.exe --remote-debugging-port=9222

然后执行：

python <skill_dir>/scripts/scan_media.py --cdp --output media_list.json

脚本会扫描所有打开标签页中的 <img> / <video> / <audio> / <picture> / <source> / <a> 链接 / CSS 背景图等所有媒体资源。

1.2 扫描指定 URL

python <skill_dir>/scripts/scan_media.py --url "https://example.com" --output media_list.json

Step 2 · 批量下载并按格式保存

python <skill_dir>/scripts/download_media.py \
    --input media_list.json \
    --image-format jpg \
    --video-format mp4 \
    --audio-format mp3 \
    --output download_results.json

支持的格式：

图片：jpg / jpeg / png（用 Pillow 转换）
视频：mp4 / mov（用 ffmpeg 转换）
音频：mp3 / wav（用 ffmpeg 转换）

文件会保存到 ~/Desktop/download/<日期>抓取资源/{图片,视频,音频}/ 下，按标题或 URL hash 命名。

如果 ffmpeg 不可用，视频/音频会以原始格式保存，控制台会打印警告。

Step 3 · 生成可视化 HTML 报告

python <skill_dir>/scripts/generate_report.py \
    --input download_results.json \
    --output download_report.html

报告包含：总览统计、类型分布、文件夹路径、明细表格（编号 / 类型 / 标题 / 文件名 / 大小 / 状态 / 错误）。

完整一次性命令（main workflow）

把扫描、下载、报告三步串起来：

# 1. 预检
python <skill_dir>/scripts/preflight_check.py

# 2. 扫描
python <skill_dir>/scripts/scan_media.py --cdp --output media_list.json
# 或者：--url "https://example.com"

# 3. 下载
python <skill_dir>/scripts/download_media.py \
    --input media_list.json \
    --image-format jpg \
    --video-format mp4 \
    --audio-format mp3 \
    --output download_results.json

# 4. 报告
python <skill_dir>/scripts/generate_report.py \
    --input download_results.json \
    --output download_report.html

使用前提

首次使用前会自动安装依赖（preflight 阶段会处理）：

pip install playwright Pillow requests
playwright install chromium

ffmpeg（可选，用于视频/音频转码）：从 https://ffmpeg.org/download.html 下载，或由预检脚本自动安装并配置 PATH。

已交付文件包括打包的 zip 文件和全部源码，可直接安装使用。