dsh-url-tools
DSH URL 工具插件。注册一个 url_tool 工具，提供 URL 解析、跟踪参数清理、字符串编解码、重定向展开四种能力。零依赖、纯 ESM、无构建。
简介
- 工具名：
url_tool - 能力：
parse（解析）/clean（清理跟踪参数）/decode（解码）/encode（编码）/expand（展开重定向）。 - 行为：永不抛异常。参数错误、非法 URL、网络错误、非法
%序列都折叠为{ ok: false, error }；成功返回{ ok: true, ... }，且始终带回action回显。
安装
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 输出示例
// 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