ZhijiangTang/dsh-fetch-file

dsh-fetch-file

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

简介

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

安装

dsh plugin --profile  add file:./plugins/dsh-fetch-file
或发布到 npm 后：
dsh plugin --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