前言¶

智能体在排查网络问题时，常需要回答“为什么连不上服务器”、“端口是否开放”、“证书何时过期”或“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 独立排查网络连通性、域名状态及证书问题的场景。更多细节可查阅插件目录或源码仓库。