dsh-fetch-file

DSH 插件：把任意 URL 下载为工作区里的文件（二进制友好，流式落盘）。纯 ESM、零依赖、无构建。

简介

download 工具接收一个 URL，跟随重定向抓取响应，流式写入工作区内的文件，返回落盘绝对路径、实际字节数、HTTP 状态码与 Content-Type。适合下载图片、压缩包、PDF、音频、安装包等二进制资源——这正是 web_fetch 不擅长、而模型常常需要的场景。

安装

dsh plugin --profile <你的 profile> add file:./plugins/dsh-fetch-file
# 或发布到 npm 后：
dsh plugin --profile <你的 profile> add dsh-fetch-file

参数

输出（规范值）

• 成功：{ ok: true, path, absPath, sizeBytes, status, contentType }（path/absPath 均为绝对路径）
• 失败：{ ok: false, error }，error 为字符串（越界/已存在）或对象（{ stage: 'http'|'network'|'timeout'|'size'|'aborted'|'fs', ... }）。所有失败都走规范值，不抛异常。

与 web_fetch 的区别

一句话：需要「拿回来一个文件」用 download，需要「读一篇文章」用 web_fetch。

大小限制

默认单次下载上限 200MB（MAX_SIZE_BYTES = 200 * 1024 * 1024），超限即中止并返回 { ok: false, error: { stage: 'size' } }，不会留下半成品文件（失败会清理临时写入）。响应通过流式写入磁盘，不会把整个文件读进内存。抓取超时 120 秒（AbortSignal.timeout）。

安全

• 路径围栏：resolve(dest) 必须位于工作区根（exec.agent.session.header.cwd ?? process.cwd()）之内，否则返回 { ok: false, error: 'dest 越出工作区' }。
• 挂载时自检：真实下载一次 https://example.com/ 到临时文件并删除，再验证越界路径被拒绝，证据行打印到日志。

License

MIT