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