前言¶

在 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 或 目录。