工具名：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。