Web Downloader
Overview
在 Windows + 可选代理的环境下，可靠地完成"从一个网站下载一批文件"的任务。核心能力：链接发现与大小探测、curl 断点续传、一次性 token 站点的 URL 重取、绝不误删文件、带暂停/继续/跳过的可视化监控面板。
开始前必读：references/pitfalls.md 记录了真实任务验证过的坑（Python requests 挂起、过期 token 追加损坏文件、cookie 路径写法等）。第一次使用本技能、或遇到不熟悉的站点时，务必加载该文档。
硬性规则（优先级最高）
- 绝不自动删除任何文件。大小不符、疑似损坏 → 只报告，标记
oversized/error，等用户手动判断。 - 一切下载走 curl（
subprocess调用），不用 Python requests（走代理会挂起）。 - 所有 curl 带断点续传
-C -、--connect-timeout、--max-time。 - 一次性 token 站点：每次续传尝试前重新获取 URL（过期 token +
-C -会把错误页追加进文件，悄悄损坏数据）。 - 批量任务按大小从小到大下载，并启动监控面板。
- 完成判据用字节数比对，不只信 curl 返回码。
Workflow
Step 1 — 明确需求
确认：源页面 URL（或用户已知的文件列表）、目标目录、是否需要登录/许可证、是否有代理。凭据由用户提供或来自会话记忆；不要把凭据写入本技能的任何文件。
Step 2 — 发现链接与大小
- 页面已知 →
scripts/extract_links.py <page.html | URL> --probe --proxy <proxy>生成带 Content-Length 的files.json。 - 站点有 API（如 GitHub：
api.github.com/repos/<owner>/<repo>/releases，分页?page=N）→ 优先走 API，一次拿到 URL + size，注意未认证限速 60 次/小时。 - 站点需要登录才能看到链接 → 先执行 Step 3 登录拿 cookie，再用
-b cookie.txt抓页面。
Step 3 — 处理认证（如需要）
典型登录型站点流程（DevTools 抓包确认具体端点）：
# 1. 登录，拿 cookie（cookie 文件用 Windows 风格路径 D:/dir/.cookies.txt）
curl -s -c "D:/dir/.cookies.txt" -X POST "https://SITE/login" \
-d "username=...&password=..." --proxy "$PROXY" -o /dev/null
# 2. 可选：接受许可证/协议（AJAX 端点）
curl -s -b "D:/dir/.cookies.txt" "https://SITE/ajax_agree?file=..." -o /dev/null
# 3. 拿一次性下载 URL：请求下载入口，-w '%{url_effective}' 取最终重定向地址
curl -s -b "D:/dir/.cookies.txt" -L -o /dev/null -w '%{url_effective}' \
"https://SITE/download-entry?file=..."
- 校验拿到的 URL 含预期的下载域名特征，否则视为登录/token 失效 → 重新登录。
- 一次性 token 站点：把"取新 URL"封装成一个脚本/命令，在配置里用
url_cmd字段引用，保证每次尝试都是新 URL。
Step 4 — 生成配置并启动管理器
写 config.json（schema 见 scripts/download_manager.py 文件头注释），然后：
python scripts/download_manager.py config.json
# 监控面板: http://127.0.0.1:<port>
- 用
run_in_background启动；登录面板 URL 告知用户。 - 管理器自带：断点续传、状态持久化（重启自动跳过已完成）、pause/resume/skip API、从小到大排序、watchdog。
- 单文件 / 少量小文件可以不用管理器，直接一段带重试循环的 curl 脚本（参考
references/pitfalls.md第 11 条的进度判断逻辑）。
Step 5 — 校验与汇报
- 对比每个文件的磁盘字节数与期望值；不一致的只报告。
- GitHub LFS 文件警惕指针文件（HEAD size 只有几百字节）。
- 向用户汇报：完成数 / 失败数 / 需人工核对的文件清单。
- 大文件建议追加解压测试或哈希校验提示。
Scripts
scripts/download_manager.py— 通用批量下载管理器 + 监控面板。配置 JSON 驱动，支持url（静态）与url_cmd（每次尝试重取 URL，适配一次性 token 站点）。scripts/extract_links.py— 从页面提取下载链接，--probe经 curl HEAD 补充大小，输出可直接用的 files JSON。
References
references/pitfalls.md— 踩坑记录：环境坑（Windows/代理/沙箱）、一次性 token 损坏文件的机制、GitHub/免登录站点注意事项。每个新站点任务开始时加载。
