📥 大文件下载器

何时使用

在从 HTTP/HTTPS URL 下载文件时使用此技能，特别是大文件（>100MB）。

典型场景：

• 下载软件安装包（DMG、EXE、ZIP）
• 下载大型数据集
• 下载视频/音频文件
• 下载文档/PDF 文件
• 任何通过 URL 的文件下载

触发关键词：

• "下载这个文件"
• "保存这个 DMG"
• "从这个 URL 下载"
• "获取这个文件"
• "帮我下载 xxx"（中文）

核心原则

⚠️ 必须遵循的最佳实践

1. 始终使用后台执行 - 绝不要同步运行大文件下载
2. 始终设置超时时间 - 根据文件大小配置合理的超时时间
3. 始终支持断点续传 - 使用 curl -C - 实现可恢复下载
4. 始终显示进度 - 使用 --progress-bar 标志
5. 始终验证结果 - 下载完成后检查文件大小

标准流程

步骤 1：启动下载（后台模式）

exec(
  command="curl -L -C - --progress-bar -o <destination_path> <URL>",
  background=true,
  timeout=600
)

参数说明：

• -L - 跟随重定向
• -C - - 恢复部分下载
• --progress-bar - 显示进度条
• -o - 输出文件路径
• background=true - 关键！ 在后台运行以避免超时
• timeout=600 - 10 分钟超时（根据文件大小调整）

步骤 2：监控进度

process(action="poll", sessionId="<session_id>")

定期轮询以检查下载进度，直到完成。

步骤 3：验证结果

exec(command="ls -lh <file_path>")

检查：

• 文件是否存在
• 文件大小是否合理
• 文件是否完整（如有 MD5/SHA 可比对）

完整示例

示例 1：下载 DMG 文件（215MB）

用户： "下载 https://github.com/example/app/releases/download/v1.0/app.dmg"

代理操作：

{
  "tool": "exec",
  "command": "curl -L -C - --progress-bar -o ~/Downloads/app.dmg https://github.com/example/app/releases/download/v1.0/app.dmg",
  "background": true,
  "timeout": 600
}

返回： {status: "running", sessionId: "xxx"}

然后定期轮询：

{
  "tool": "process",
  "action": "poll",
  "sessionId": "xxx"
}

下载完成后验证：

{
  "tool": "exec",
  "command": "ls -lh ~/Downloads/app.dmg && file ~/Downloads/app.dmg"
}

示例 2：下载小文件（<50MB）

对于小文件，可接受简化处理：

exec(command="curl -L -o ~/Downloads/small.pdf https://example.com/small.pdf", timeout=120)

小文件可同步运行，但仍需设置超时。

超时参考

错误处理

常见错误及解决方案

1. 下载中断

# 重新运行相同命令，curl -C - 会自动续传
curl -L -C - --progress-bar -o file.zip <URL>

2. 权限不足

# 确保目标目录可写
mkdir -p ~/Downloads

3. 重定向失败

# 使用 -L 标志跟随重定向
curl -L -o file.zip <URL>

4. 网络超时

# 增加超时时间或使用 --retry
curl -L --retry 3 --connect-timeout 30 -o file.zip <URL>

高级选项

多线程下载（aria2）

如果系统中存在 aria2，可使用多线程加速下载：

exec(
  command="aria2c -x 16 -s 16 -k 1M --continue -o ~/Downloads/file.zip <URL>",
  background=true,
  timeout=600
)

完整流程带进度监控

# 1. 启动下载
exec(command="curl -L -C - --progress-bar -o ~/Downloads/file.zip <URL>", background=true, timeout=600)

# 2. 每 30 秒轮询一次
process(action="poll", sessionId="xxx")

# 3. 完成后验证
exec(command="ls -lh ~/Downloads/file.zip")

# 4. 可选：计算校验和
exec(command="md5sum ~/Downloads/file.zip")

安全注意事项

1. 仅从可信来源下载 - 验证 URL 来源
2. 检查文件类型 - 使用 file 命令确认
3. 必要时进行病毒扫描 - 下载后可进行扫描
4. 避免覆盖重要文件 - 检查目标路径是否已存在

相关技能

• feishu-send-file - 将下载的文件发送至飞书
• file-read - 读取下载文件内容
• video-frames - 若为视频文件，提取帧

故障排除

若下载失败，请按以下步骤排查：

1. 检查网络连接

   curl -I <URL>

1. 检查磁盘空间

   df -h ~/Downloads

1. 查看详细错误信息

   curl -v -o /dev/null <URL>

1. 尝试使用其他工具

   wget --continue <URL>

**记住：大文件下载时务必使用 background=true！** 🎯