前言¶
在 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 工作流中集成。完整文檔與源碼見下方鏈接。
