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）。