前言¶
在 DSH（DeepSeek Harness）里开发智能体时，有时需要把远程资源拿到本地。内置的 web_fetch 能把网页正文读出来，但无法直接落盘；直接在对话里让 Agent 用 shell 命令下载，又受权限限制，容易遇到 spawn EPERM 或长时间挂起。download_file 插件解决的就是这个问题：让 Agent 能以当前进程的权限直接把任意 URL 的文件写到磁盘，并返回文件路径、字节数和内容预览。
插件简介¶
dsh-download-file 是一个给 DSH Agent 加上 download_file 工具的插件。它把 URL 对应的原始字节流写入本地磁盘，支持文本和二进制文件，不转换换行符，不限制文件大小，并在下载完成后返回文件开头几行预览。插件纯 ESM 实现，零依赖，无需构建，在 Windows / Linux / macOS 上都能用。维护者为 zchrissirhcz。
安装¶
命令行方式：
# profile 通常是 desktop 或 web，见 ~/.dsh/profiles 下的子目录
# 从本地目录安装
dsh plugin --profile <profile> add file:./dsh-download-file
# 或发布到 npm 后按包名安装
dsh plugin --profile <profile> add dsh-download-file
桌面版：DSH 桌面版 → 插件 → 填入 “https://github.com/zchrissirhcz/dsh-download-file” 即可。
工具签名¶
download_file(url, save_path?, overwrite?)
| 参数 | 必填 | 说明 |
|---|---|---|
url |
是 | 文件完整 URL（内网 GitLab raw、公网 GitHub 等任意 http/https） |
save_path |
否 | 省略→当前工作目录（文件名取 URL 原始名）；以 / 结尾或指向已存在目录→作为目录；否则作为完整文件路径（自动建父目录） |
overwrite |
否 | 文件已存在时：false（默认）→ 跳过、不覆盖；true → 覆盖 |
如果 URL 末尾没有文件名（如 https://x/），会用 download-<时间戳> 当文件名，避免重名。
在会话中使用¶
准确的给出 URL，下载速度最快：
下载 https://raw.githubusercontent.com/nihui/ruapu/refs/heads/master/ruapu.h
也支持二进制文件的下载：
下载 https://github.com/nihui/vkpeak/releases/download/20260527/vkpeak-20260527-windows.zip
只给个大概描述也行，DSH 会自动调用搜索 API，不过速度可能稍慢：
下载 github 上的 ruapu.h
如果文件已经存在，会检测到并询问是否覆盖。
在 SKILL.md 中¶
下面是一个真实可用的 skill 例子，用于安装 asan.cmake：
---
name: install-asan-cmake
description: 下载并安装 asan.cmake 到指定目录（默认当前目录），目标已存在时先询问是否更新。
---
# 安装 asan.cmake
下载源：`https://raw.githubusercontent.com/zchrissirhcz/rocbuild/refs/heads/main/plugins/asan.cmake`
## 步骤
1. **目标目录**：用户指定则用之，否则取当前目录（不存在则创建）。
2. **已存在？**：每次执行都先用 `read`/`glob` **实际检查磁盘**目标路径是否已有 `asan.cmake`（**禁止凭对话历史判断**）。存在时才询问是否更新；回答「否」则跳过并说明未改动，回答「是」才覆盖。
3. **下载**：用 `download_file`，`url` 填下载源，`save_path` 填目标目录下的 `asan.cmake`（绝对路径）。`download_file` 返回的字节数即校验结果，**不要再额外读取校验**。
## 注意
- 内容原样落盘，不加工。
- 失败时说明原因，不写空文件。
- 未获确认不覆盖已有文件。
- 尽量减少工具调用轮次：每多一个回合就多一次 LLM 往返耗时。
返回结果¶
成功下载：
{ "ok": true, "url": "...", "saved_to": "E:\\proj\\configs\\xxxbuild.cmake",
"bytes": 2048, "binary": false, "preview": "cmake_minimum_required(VERSION 3.16)\nproject(example)" }
saved_to：文件实际落盘的绝对路径。bytes：字节数。binary：false表示文本；true表示二进制（图片、压缩包等）。preview：文件开头几行，用来确认内容对不对；二进制时是一句提示。
文件已存在、默认没覆盖：
{ "ok": true, "skipped": true, "exists": true,
"saved_to": "E:\\proj\\configs\\xxxbuild.cmake", "bytes": 2048 }
模型看到 skipped 就知道没覆盖，会再来问你是否强制刷新。
与内置 web_fetch 的区别¶
download_file（本插件） |
web_fetch（内置） |
|
|---|---|---|
| 用途 | 下载成文件，落到磁盘 | 阅读网页，返回正文给模型 |
| 内容 | 原始字节，二进制友好 | 提取正文，丢弃二进制 |
| 结果 | 文件路径 + 字节数 + 文本预览 | 摘要文本 |
| 大小 | 不限（流式） | 受上下文/抓取策略限制 |
一句话：要「拿回来一个文件」用 download_file，要「读一篇文章」用 web_fetch。
其他特性¶
- 磁盘级存在检查：目标是否已存在以磁盘为准，默认不覆盖，避免静默覆盖。
- 逐字节原样保存：文本换行符（
\n/\r\n）、二进制字节均不转换、不丢失。 - 无大小上限：流式写入，不把整个文件读进内存。
- 120 秒超时保护：下载/写入卡死时自动中止，不会无限挂起。
- 写盘不弹授权：在主机进程直接落盘，不需要逐次授权。
- 失败走 DSH 原生
isError：网络/HTTP 错误作为工具失败返回，模型处理统一。
适用场景与注意¶
适合需要把远程配置、脚本、二进制包直接落到本地的智能体场景，比如自动安装工具、拉取本地配置模板、下载资源文件等。插件以当前 DSH 进程的权限运行，因此需要确保进程有目标目录的写入权限。安装前建议查看源码与许可证。
小结¶
dsh-download-file 让 DSH Agent 能安全、可控地把远程文件落到本地磁盘，避免依赖 shell 权限和手动下载。配合磁盘级存在检查和覆盖控制，可以在 SKILL 中实现可靠、可复用的下载逻辑。更多细节可参考：GitHub 仓库。
