前言¶
在 DeepSeek Harness (DSH) 的开发场景中，智能体经常需要处理远程资源，例如下载图片、压缩包或安装包。虽然 DSH 内置的 web_fetch 工具擅长抓取网页正文，但它会丢弃二进制数据，不适合文件下载场景。dsh-fetch-file 插件专门填补这一空白，它允许智能体将任意 URL 的响应流式写入工作区文件，同时内置了安全围栏和大小限制。
简介¶
这是一个由 ZhijiangTang 维护的 DSH 插件。它的核心价值是将任意 URL 的响应流式写入工作区文件，支持二进制内容，并内置路径安全围栏与大小限制。
核心功能¶
- 下载任意 URL 为工作区文件：支持 http/https 协议，自动跟随重定向。
- 二进制友好，流式落盘：响应通过流式写入磁盘，不会把整个文件读进内存，适合大文件。
- 路径围栏：确保写入路径位于工作区根目录内，防止越界。
- 200MB 单次下载上限：默认
MAX_SIZE_BYTES = 200 * 1024 * 1024，超限即中止并返回规范错误。 - 零依赖、纯 ESM：无构建步骤，安装简单。
安装与启用¶
安装前请确认你的 DSH 版本为 0.1.0-rc.6 或更高，并已配置好 profile。执行以下命令安装插件：
dsh plugin --profile <你的 profile> add file:./plugins/dsh-fetch-file
典型用法¶
调用 download 工具时，需传入 url 和 dest 参数。
参数说明¶
url(string, 必填): 要下载的 URL。插件会自动跟随重定向。dest(string, 可选): 保存路径（相对工作区根）。默认为 URL 的 basename；若 URL 无 basename 则退化为download-<时间戳>。overwrite(boolean, 可选): 是否覆盖已存在文件。默认为false。
返回值规范¶
插件不抛异常，所有结果通过规范值返回。
- 成功：
{ "ok": true, "path": "...", "absPath": "...", "sizeBytes": 1024, "status": 200, "contentType": "..." }
- 失败：
{ "ok": false, "error": "..." }
`error` 可为字符串（如 "dest 越出工作区"），也可为对象（包含 `stage` 字段，如 `http`, `network`, `timeout`, `size`, `fs` 等）。
与 web_fetch 的区别¶
| 特性 | download (本插件) |
web_fetch (内置) |
|---|---|---|
| 用途 | 下载为文件，落盘到工作区 | 阅读网页，返回正文文本 |
| 内容 | 原始字节，二进制友好 | 抓取后提取正文，丢弃二进制 |
| 结果 | 文件路径 + 字节数 + 状态码 | 摘要文本 |
| 上限 | 200MB (可配置) | 受模型上下文/抓取策略限制 |
注意事项¶
- 权限要求：插件运行需要
filesystem:write和network:outbound权限。 - 生态背景：DSH 插件生态由社区维护，与 DeepSeek / 幻方无官方从属关系。
- 安装前检查：安装前建议查看源码与许可证（MIT），确认符合项目安全规范。
后续¶
该插件通过规范值返回结果，不抛异常，适合在 DSH 工作流中集成。完整文档与源码见下方链接。
