前言¶
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 调试入口。它弥补了高层文档提取工具在协议细节控制上的不足，适合需要精确交互或排查网络问题的场景。
