dsh-url-tools

Readme

# dsh-url-tools

DSH URL 工具插件。注册一个 `url_tool` 工具，提供 URL 解析、跟踪参数清理、字符串编解码、重定向展开四种能力。**零依赖、纯 ESM、无构建**。

## 简介

- 工具名：`url_tool`
- 能力：`parse`（解析）/ `clean`（清理跟踪参数）/ `decode`（解码）/ `encode`（编码）/ `expand`（展开重定向）。
- 行为：**永不抛异常**。参数错误、非法 URL、网络错误、非法 `%` 序列都折叠为 `{ ok: false, error }`；成功返回 `{ ok: true, ... }`，且始终带回 `action` 回显。

## 安装

```sh
dsh plugin --profile <name> add file:./plugins/dsh-url-tools
# 或发布后：
dsh plugin --profile <name> add dsh-url-tools
```

## 参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `action` | enum | ✅ | `parse`/`clean`/`decode`/`encode`/`expand` |
| `url` | string | ✅ | 目标 URL（`decode`/`encode` 时是待处理字符串） |

## action 表

| action | 输入 | 输出（`ok: true`） | 失败 |
|---|---|---|---|
| `parse` | 任意合法 URL | `{ scheme, host, port, pathname, search, hash, username, params }`；`params` 为 `key → [值...]`，重复键合并为数组 | `ok: false` + `error`（非法 URL） |
| `clean` | 含跟踪参数的 URL | `{ url, removed, search }`：`url` 清理后完整 URL、`removed` 被删参数键数组、`search` 原始 query 串 | `ok: false` + `error`（非法 URL） |
| `decode` | 百分号编码串 | `{ input, output }`，整串 `decodeURIComponent` | `ok: false` + `error`（非法 `%` 序列） |
| `encode` | 任意字符串 | `{ input, output }`，整串 `encodeURIComponent` | — |
| `expand` | 任意 `http/https` URL | `{ finalUrl, hops, statuses }`；`statuses` 为每跳状态码（含末跳非 3xx） | `ok: false` + `error`（网络错/非法 URL/非法 Location） |

### parse 输出示例

```jsonc
// url_tool { action: "parse", url: "https://user:pw@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"] }
}
```

## 跟踪参数清单

`clean` **只删**以下参数，其余（含 `ref`、`gclsrc` 等）一律保留：

- `utm_*`（任意 `utm_` 前缀，如 `utm_source`/`utm_medium`/`utm_campaign`/`utm_term`/`utm_content`/`utm_id`）
- `fbclid`、`gclid`、`msclkid`、`mc_cid`、`mc_eid`、`yclid`、`wickedid`

匹配对大小写不敏感；`removed` 返回被删的键（去重、按首次出现顺序）。

## expand 上限说明

`expand` 手动跟随重定向：每跳先 `HEAD`、失败回退 `GET`，读 `location` 头（绝对/相对都解析），最多跟 **5 跳**。超过 5 跳仍在 3xx 时停止，返回当前 URL 并带 `maxHopsReached: true`；非 3xx（或无 `location`）即停。每跳超时 **10 秒**，网络错误返回 `ok: false`。

## License

MIT