前言¶

在 DSH 生態中，聯網能力是核心。模型或 Code Mode 程序需要可靠的數據結構來處理網絡錯誤，而不是拋出異常。dsh-http 插件解決了這個問題。它註冊了一個 http_request 工具，將結果規範化爲結構化 JSON 對象，以便於程序化調用。

簡介¶

dsh-http 是一個由 ZhijiangTang 維護的本地工具，用於在 DSH 中發起 HTTP/HTTPS 請求。它基於 Node 內置 fetch。零依賴、純 ESM、無構建。它將所有網絡錯誤摺疊爲標準錯誤對象，而不是拋出異常。

安裝¶

將插件文件添加到配置中。

dsh plugin --profile <name> add file:./plugins/dsh-http

核心功能¶

該工具支持任意 HTTP 方法（GET/POST/PUT/PATCH/DELETE/HEAD）、自定義請求頭、原始 body 和 JSON 自動序列化。它提供便捷的 Bearer 和 Basic 認證參數。它處理超時和響應體截斷。輸出始終是結構化 JSON。

典型用法¶

參數說明¶

• url: 目標 URL，僅允許 http/https。
• method: 請求方法，默認 GET。
• headers: 自定義請求頭。
• body: 原始請求體（與 json 互斥）。
• json: JSON 值，自動序列化並設置 content-type（與 body 互斥）。
• timeoutMs: 請求超時時間，默認 10000 毫秒。
• maxBodyChars: 響應體返回上限，默認 4000 字符。
• auth: 認證配置對象。

認證示例¶

使用 Bearer Token 或 Basic Auth：

// Bearer
{ "auth": { "type": "bearer", "token": "<token>" } }
// Basic
{ "auth": { "type": "basic", "username": "user", "password": "pass" } }

輸出格式¶

該工具始終返回 JSON 對象。

成功響應¶

{
  "ok": true,
  "status": 200,
  "statusText": "OK",
  "durationMs": 123,
  "sizeBytes": 456,
  "contentType": "application/json",
  "headers": {},
  "json": {}, // 響應體解析爲 JSON
  "text": "...",
  "truncated": false
}

失敗響應¶

網絡錯誤、超時、參數錯誤均摺疊爲該格式：

{
  "ok": false,
  "error": {
    "stage": "request",
    "message": "..."
  }
}

安全與注意事項¶

• SSRF 風險：不內置 SSRF 攔截。它可以訪問內網地址，包括 localhost、127.0.0.1、10.x、192.168.x、172.16-31.x、169.254.x 等。
• 本地工具：本地個人工具，勿在不可信的 prompt 或多租戶環境中使用。
• 權限要求：需要 network:outbound 權限。
• 依賴：零依賴、純 ESM、無構建。

結語¶

該工具爲 DSH 提供了結構化的 HTTP 能力。有關更多細節，請參閱 GitHub 或 目錄。