Introduction

In DSH (DeepSeek Harness) development, URL handling often involves parsing the structure, cleaning tracking parameters, handling encoding issues, or tracing redirect chains. The dsh-url-tools plugin provides a zero-dependency, pure ESM solution for URL processing. It is maintained by ZhijiangTang and is designed to address the URL handling pain points encountered by agents in online operations.

Core Features

The plugin registers a url_tool tool that provides the following four capabilities:
1. Parsing: Breaks down the components of a URL.
2. Cleaning tracking parameters: Removes common tracking parameters.
3. Encoding and decoding: Handles encoding and decoding of URL strings.
4. Expanding redirects: Follows HTTP redirect chains.

Installation and Enablement

The installation command is as follows. The plugin requires the network:outbound permission.

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

Typical Usage

When calling url_tool, you must pass the action parameter (an enum value) and the url parameter (a string).

1. Parsing a URL

After parsing, it returns the individual components of the URL, with parameters merged into arrays.

// url_tool { action: "parse", url: "https://example.com:8080/a/b?x=1&utm_source=g&y=2#f" }
{
  "ok": true,
  "action": "parse",
  "scheme": "https",
  "host": "example.com",
  "port": "8080",
  "pathname": "/a/b",
  "search": "?x=1&utm_source=g&y=2",
  "hash": "#f",
  "username": "user",
  "params": { "x": ["1"], "utm_source": ["g"], "y": ["2"] }
}

2. Cleaning Tracking Parameters

Using action: "clean" removes tracking parameters from the URL. The plugin deletes only the following parameters:
- utm_* (any prefix)
- fbclid, gclid, msclkid, mc_cid, mc_eid, yclid, wickedid

Matching is case-insensitive. The return value includes the cleaned URL, an array of the removed parameter keys, and the original query string.

3. Encoding and Decoding

  • action: "encode": Encodes the string using encodeURIComponent.
  • action: "decode": Decodes the string using decodeURIComponent.

4. Expanding Redirects

Use action: "expand" to follow HTTP redirects.
- Follows at most 5 hops.
- Each hop times out after 10 seconds.
- If the URL still returns a 3xx status code after 5 hops, stop and return the current URL with maxHopsReached: true.
- Stop if a non-3xx status code or network error is encountered.

Error Handling and Notes

  • Never throws exceptions: Whether due to parameter errors, invalid URLs, network errors, or invalid % sequences, the functions return an { ok: false, error } structure rather than throwing exceptions.
  • Compatibility: Requires DSH version 0.1.0-rc.6 or higher.
  • Permissions: Requires the network:outbound permission at runtime.

Summary

dsh-url-tools provides a standardized interface for URL handling. Through parsing, cleaning, encoding, and redirect expansion, it can simplify the URL operation logic of agents in online scenarios. It is recommended to review the source code and license (MIT) before installation.