dsh-fetch-file

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

参数

参数	类型	必填	默认	说明
url	string	是	—	要下载的 URL（http/https），自动跟随重定向
dest	string	否	URL 的 basename	保存路径（相对工作区根）。URL 无 basename 时退化为 download-<时间戳>
overwrite	boolean	否	false	dest 已存在时是否覆盖；false 且已存在则返回规范错误值

输出（规范值）

• 成功：{ 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（内置）
用途	下载为文件，落盘到工作区	阅读网页，返回正文文本给模型
内容	原始字节，二进制友好（图片/压缩包/PDF…）	抓取后提取正文，丢弃二进制
结果	文件路径 + 字节数 + 状态码	摘要文本
上限	maxSizeBytes（默认 200MB）	受模型上下文/抓取策略限制

一句话：需要「拿回来一个文件」用 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