前言¶

智能體在排查網絡問題時，常需要回答“爲什麼連不上服務器”、“端口是否開放”、“證書何時過期”或“DNS 解析結果是什麼”這類問題。如果讓智能體直接通過 Shell 執行 ping 或 nslookup，存在注入風險且結果非結構化。dsh-netdoctor 插供了經過驗證的只讀探針，讓智能體可以直接調用並讀取結構化結果。

插件概覽¶

dsh-netdoctor 是 DeepSeek Harness (DSH) 的網絡診斷工具箱，由 TYEclipse 維護。它提供 7 個只讀探針，零運行時依賴，僅使用 Node.js 內置模塊實現。

核心功能¶

插件包含以下 7 個探針：

• dns_lookup：查詢 A/AAAA/CNAME/MX/TXT/NS/SOA/SRV/PTR/CAA 記錄。支持指定自定義 DNS 服務器，可用於測試 DNS 傳播情況。
• ping_host：執行 ICMP Ping，統計丟包率及最小/平均/最大往返時間（RTT）。
• check_port：TCP 連接探測，返回端口狀態（開放/關閉/過濾/不可達）及連接耗時。
• check_tls：執行真實的 TLS 握手，報告協議版本、密碼套件、證書主體/頒發者、有效期窗口、距離過期的天數、SANs 及指紋。證書會被檢查但不驗證信任鏈，因此過期或自簽名證書也能被診斷。
• trace_route：逐跳路徑追蹤，顯示每一跳的 RTT。
• my_ip：獲取本機公網 IP。可選附加地理信息（國家/地區/城市/ISP/AS/時區/座標），該功能可在調用時或配置中關閉。
• whois：通過 TCP 端口 43 協議查詢域名註冊信息。支持自動註冊表發現，返回原始 WHOIS 文本及結構化摘要（註冊商、狀態、創建/更新/到期日期、名稱服務器）。

安全模型¶

該插件在設計上優先考慮安全性：

1. 只讀操作：所有探針均爲只讀，不會寫入、配置或修改任何內容。
2. 防注入：調用外部二進制文件（ping, traceroute 等）時使用固定的參數數組，絕不通過 Shell 轉發，且會對目標進行嚴格的 hostname/IP 模式校驗。
3. 硬超時：每個探針都有硬超時限制，防止因某個探針卡死而掛起整個會話。
4. 無憑據依賴：whois 僅連接註冊表服務器的 TCP 43 端口併發送單行查詢，不使用任何憑證或第三方 API Key。
5. 隱私可控：my_ip 的地理定位功能默認開啓，但可在調用參數或配置中關閉。

安裝¶

將插件添加到 DSH 配置中：

dsh plugin --profile web add github:TYEclipse/dsh-netdoctor

配置¶

所有配置均爲可選，默認值如下：

plugins:
  dsh-netdoctor:
    timeoutMs: 3000        # TCP/TLS 探測默認超時（毫秒）
    pingCount: 4           # ICMP Ping 默認發送次數
    pingTimeoutSec: 2      # Ping 每次回覆等待時間（秒）
    maxHops: 20            # Traceroute 最大跳數
    traceTimeoutSec: 2     # Traceroute 每跳等待時間（秒）
    includeGeo: true       # 是否在 my_ip 結果中附加地理信息
    httpTimeoutMs: 5000    # my_ip HTTP 查詢超時（毫秒）
    whoisTimeoutMs: 5000   # WHOIS 查詢超時（毫秒）

使用示例¶

智能體可以直接調用以下提示詞來使用工具：

• “Is port 5432 open on db.internal.example.com?”
• “When does the TLS certificate for example.com expire?”
• “Trace the route to 1.1.1.1 and find where packets stall.”
• “What A records does example.com return from 8.8.8.8?”
• “What’s our public IP and where does it geolocate to?”
• “Who registered example.com and when does the domain registration expire?”
• “What CAA records does github.com publish for certificate authorities?”

結尾¶

dsh-netdoctor 爲 DeepSeek Harness 提供了一套安全、結構化的網絡診斷能力，適合需要讓 Agent 獨立排查網絡連通性、域名狀態及證書問題的場景。更多細節可查閱插件目錄或源碼倉庫。