Introduction

In the DSH ecosystem, networking capability is core. Models or Code Mode programs need reliable data structures to handle network errors, rather than throwing exceptions. The dsh-http plugin solves this problem. It registers an http_request tool, normalizing results into structured JSON objects for programmatic invocation.

Overview

dsh-http is a local tool maintained by ZhijiangTang for making HTTP/HTTPS requests in DSH. It is based on Node’s built-in fetch. Zero dependencies, pure ESM, no build. It folds all network errors into a standard error object instead of throwing exceptions.

Installation

Add the plugin file to your configuration.

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

Core Features

The tool supports any HTTP method (GET/POST/PUT/PATCH/DELETE/HEAD), custom request headers, raw body, and automatic JSON serialization. It provides convenient Bearer and Basic authentication parameters. It handles timeouts and response body truncation. Output is always structured JSON.

Typical Usage

Parameters

  • url: Target URL, http/https only.
  • method: Request method, defaults to GET.
  • headers: Custom request headers.
  • body: Raw request body (mutually exclusive with json).
  • json: JSON value, automatically serialized and sets content-type (mutually exclusive with body).
  • timeoutMs: Request timeout, defaults to 10000 milliseconds.
  • maxBodyChars: Maximum returned response body size, defaults to 4000 characters.
  • auth: Authentication configuration object.

Authentication Examples

Use Bearer Token or Basic Auth:

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

Output Format

The tool always returns a JSON object.

Successful Response

{
  "ok": true,
  "status": 200,
  "statusText": "OK",
  "durationMs": 123,
  "sizeBytes": 456,
  "contentType": "application/json",
  "headers": {},
  "json": {}, // 响应体解析为 JSON
  "text": "...",
  "truncated": false
}

Failed Response

Network errors, timeouts, and parameter errors are all collapsed into this format:

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

Security and Caveats

  • SSRF Risk: No built-in SSRF interception. It can access internal network addresses, including localhost, 127.0.0.1, 10.x, 192.168.x, 172.16-31.x, 169.254.x, etc.
  • Local Tool: A local personal tool; do not use it in untrusted prompts or multi-tenant environments.
  • Permission Requirements: The network:outbound permission is required.
  • Dependencies: Zero dependencies, pure ESM, no build.

Conclusion

This tool provides DSH with structured HTTP capability. For more details, see GitHub or Directory.