dsh-url-tools：DSH 插件 URL 解析与重定向展开工具

前言¶

在 DSH（DeepSeek Harness）开发中，处理 URL 常涉及解析结构、清理跟踪参数、处理编码问题或追踪重定向链路。dsh-url-tools 插件提供了一套零依赖、纯 ESM 的 URL 处理方案。该插件由 ZhijiangTang 维护，旨在解决智能体在联网操作中遇到的 URL 处理痛点。

核心功能¶

插件注册了一个 url_tool 工具，提供以下四种能力：
1. 解析：拆解 URL 各部分。
2. 清理跟踪参数：移除常见的追踪参数。
3. 编解码：处理 URL 字符串的编码与解码。
4. 展开重定向：跟随 HTTP 重定向链路。

安装与启用¶

安装命令如下。该插件需要 network:outbound 权限。

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

典型用法¶

调用 url_tool 时，必须传入 action 参数（枚举值）和 url 参数（字符串）。

1. 解析 URL¶

解析后返回 URL 的各个组成部分，参数合并为数组。

// 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. 清理跟踪参数¶

使用 action: "clean" 可以移除 URL 中的追踪参数。插件仅删除以下参数：
- utm_*（任意前缀）
- fbclid、gclid、msclkid、mc_cid、mc_eid、yclid、wickedid

匹配对大小写不敏感。返回值包含清理后的 URL、被删除的参数键数组以及原始查询串。

3. 编解码¶

action: "encode"：对字符串进行 encodeURIComponent 编码。
action: "decode"：对字符串进行 decodeURIComponent 解码。

4. 展开重定向¶

使用 action: "expand" 跟踪 HTTP 重定向。
- 最多跟随 5 跳。
- 每跳超时 10 秒。
- 超过 5 跳仍在 3xx 状态码时停止，返回当前 URL 并标记 maxHopsReached: true。
- 若遇到非 3xx 状态码或网络错误，则停止。

错误处理与注意¶

永不抛异常：无论参数错误、非法 URL、网络错误还是非法 % 序列，函数均返回 { ok: false, error } 结构，而非抛出异常。
兼容性：要求 DSH 版本为 0.1.0-rc.6 或更高。
权限：运行时需要 network:outbound 权限。

总结¶

dsh-url-tools 提供了处理 URL 的标准化接口。通过解析、清理、编码和重定向展开功能，可以简化智能体在联网场景下的 URL 操作逻辑。安装前建议检查源码与许可证（MIT）。