前言¶
DeepSeek Harness (DSH) 採用「一切皆插件」的理念。現有的 web_fetch 或 web_search 等工具通常將目標網頁轉換爲 Markdown 文檔，這適合閱讀，但不適合調試網絡交換細節或需要精確控制 HTTP 協議的場景。
dsh-http-debug 爲 DSH 提供了一個通用型 HTTP 客戶端。它專注於原始 HTTP 語義（方法、頭、體、狀態碼、時序、大小），並內置了 SSRF / 私有網絡防護、會話請求歷史記錄以及 HAR 導出功能。對於需要在 DSH 生態中進行精細網絡調試的開發者來說，這是一個零依賴的 CLI 工具。
核心功能¶
- 通用 HTTP 客戶端：支持完整定義請求（方法、頭、體、超時、重定向策略）和結構化響應（狀態、頭、體、時序、大小）。
- SSRF 與私有網絡防護：默認阻斷迴環地址、RFC 1918 私有網段、CGNAT、鏈路本地地址、多播及保留地址。所有重定向跳轉也都會經過檢查。
- 請求歷史與重放：內存環形緩衝區保存每對請求/響應，支持查看列表、檢查詳情或重放。
- WAF 友好：提供可選的默認 User-Agent 和 Referer 頭，避免觸發簡單的 Web 應用防火牆。
- 響應檢查與導出：支持 JSON 校驗和 HAR 1.2 格式導出。內置硬體大小限制，防止超大響應導致上下文溢出。
- 零依賴 CLI：獨立的命令行工具，不依賴其他庫。
安裝與啓用¶
該插件以 Bundle 形式分發，包含 cordis.patch.yml 配置文件。安裝後，它會將三個工具註冊到 ctx.tools 中，供 Agent 直接調用。
通過 dsh plugin 命令安裝到指定 Profile：
dsh plugin --profile <name> add dsh-http-debug
或者直接從 GitHub 倉庫安裝：
dsh plugin --profile <name> add github:JohnXu22786/net-debug
安裝完成後，可在 REPL 或 Agent 中驗證工具是否可用，或在配置中調整 SSRF 白名單、超時時間等參數。
主要工具使用¶
插件提供三個 DSH 工具：
1. http_request¶
執行或重放一次 HTTP 交互。參數包括：
* url: 絕對 HTTP(S) URL（重放時可省略）。
* method: 請求方法（GET, POST, PUT, PATCH, DELETE 等）。
* headers / body: 請求頭和請求體（UTF-8 文本或 Base64）。
* timeout_ms / max_redirects: 超時和最大重定向次數。
* validate_json / include_har: 校驗響應 JSON 並導出 HAR 文檔。
* bypass_ssrf: 危險，禁用單次請求的 SSRF 檢查。
返回結構化響應對象，網絡錯誤（超時、網絡、SSRF 阻斷）會拋出帶錯誤碼的異常。
2. http_history¶
管理會話內的請求歷史。
* action: 操作類型（list 列出摘要，get 獲取詳情，clear 清空，stats 統計）。
* id: 歷史記錄 ID（僅 get 時需要）。
3. http_rules¶
管理運行時 SSRF 白名單規則。
* action: list, add, remove, clear。
* rule: 主機名、通配符（如 *.example.com）、IP 或 CIDR。
注意：通過此工具添加的規則僅在當前會話有效，持久化配置需在插件配置文件中設置 ssrf.whitelist。
注意事項¶
- 體大小限制：爲了防止超大響應導致提示詞上下文溢出，插件對捕獲的響應體有硬性大小限制（默認爲 131072 字節）。
- SSRF 風險：
bypass_ssrf標誌存在安全風險，僅應在極度必要時謹慎使用。 - 開發預覽：DSH 內部機制仍在快速迭代中，Profile 機制和 Loader 的具體實現可能隨版本變動。
總結¶
dsh-http-debug 爲 DSH 生態提供了一個安全、可控的 HTTP 調試入口。它彌補了高層文檔提取工具在協議細節控制上的不足，適合需要精確交互或排查網絡問題的場景。
