dsh-fetch-file

Readme

# dsh-fetch-file

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

## 简介

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

## 安装

```sh
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