@yanglaofish/dsh-proxy-pro 1.0.2 → 1.0.3

package/docs/LESSONS.md

@@ -675,4 +675,28 @@ E  外部 undici 的 fetch + 同一 ProxyAgent -> OK 401
 
 **结论**：本插件与 `dsh-http-proxy` 插件行**二选一**。库本身必须保留——插件 import 它的
 `installProxyFromEnvironment` / `proxyRouteFor`，而 DSH 的 web_fetch 通道读的正是同一模块的
-module-level policy（§2-§3）。卸载"插件行"是安全的，删除"包"会让本插件 import 直接失败。
+module-level policy（§2-§3）。卸载"插件行"是安全的，删除"包"会让本插件 import 直接失败。
+
+---
+
+## 24. 诊断结论要三态 + 可行动（2026-09-17）
+
+**症状**：面板与 `proxy_test` 的「连通探测」只分可达/不可达两档——`HTTP 504`（网关/上游超时）
+和 `HTTP 200` 都打印成「可达」，用户无法判断"到底能不能用"。
+
+**改法**（1.0.3）：
+
+- `classifyProbeStatus(status)` 产出三态：
+  - `usable`：2xx/3xx，以及 **401**（探测不带凭证，服务健康就该回 401）；
+  - `degraded`：403/404/405/429 等 4xx —— **路由通、这次调用会失败**；
+  - `unusable`：407、5xx（500/502/503/504）—— 路由或对端失败。
+- 每个结论都带 `why`（可能原因）+ `fix`（挽救措施）：面板显示三层
+  （连通探测 / 可能原因 / 挽救措施），`proxy_test` 输出 `Why:` / `Fix:` 行。
+- `classifyTargetFailure` 同样补齐 why/fix，并按 ENOTFOUND / ECONNREFUSED / ETIMEDOUT /
+  ECONNRESET / UND_ERR_INVALID_ARG / 407 分别归类。
+- 探测顺序：**HEAD →（405/501 时）GET `Range: bytes=0-0` 复测**。很多 API 只实现 GET，
+  单用 HEAD 会冤枉一个可用主机；复测结果里附 `note` 说明。
+
+**教训**：诊断工具的返回值必须回答"能不能用"和"下一步怎么办"——只回一个状态码，等于把问题
+又丢回给用户。另外 `additionalProperties: false` 的 schema 必须同步列出新字段
+（verdict/why/fix/note），否则 defineTool 校验直接失败。

package/lib/client.js

@@ -71,6 +71,8 @@ window.__ModuleLoader__.load({
       ".dsxprx-diagbtn{flex:none;padding:6px 12px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;background:var(--dsw-specific-tip);color:var(--dsw-alias-label-primary);font:inherit;font-size:12px;cursor:pointer}",
       ".dsxprx-diagbtn:disabled{opacity:.5;cursor:not-allowed}",
       ".dsxprx-diagout{display:flex;flex-direction:column;gap:3px;padding:8px 10px;border:1px solid var(--dsw-alias-border-l1);border-radius:8px;background:var(--dsw-specific-tip);font-size:12px;line-height:17px;color:var(--dsw-alias-label-primary)}",
+      ".dsxprx-diagwhy{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption)}",
+      ".dsxprx-diagfix{font-size:11px;line-height:16px;color:var(--dsw-alias-label-secondary)}",
       ".dsxprx-title{font-size:16px;font-weight:700;line-height:22px;color:var(--dsw-alias-label-primary)}",
       ".dsxprx-diagcheck{flex:none;display:flex;align-items:center;gap:5px;font-size:12px;line-height:16px;color:var(--dsw-alias-label-secondary);cursor:pointer;white-space:nowrap}",
       ".dsxprx-diagcheck input{width:14px;height:14px;accent-color:#4d6bfe;margin:0}",
@@ -295,6 +297,14 @@ window.__ModuleLoader__.load({
       }
       var diagUseProxy = useState(true);
       var setDiagUseProxy = diagUseProxy[1];
+      /** Three-state headline for one probe verdict (usable / degraded / unusable). */
+      function probeHeadline(probe) {
+        if (!probe) return "未知";
+        if (probe.verdict === "usable") return "可用" + (probe.status === undefined ? "" : "（HTTP " + probe.status + "）");
+        if (probe.verdict === "degraded") return "降级：" + (probe.short || "未知");
+        if (probe.verdict === "unusable") return "不可用：" + (probe.short || "未知");
+        return probe.ok ? "可用" : (probe.short || "未知");
+      }
       function runDiag() {
         var target = diagUrl.trim();
         if (!target) return;
@@ -408,7 +418,10 @@ window.__ModuleLoader__.load({
                 : [
                   react.createElement("span", { key: "c" }, "测试通道： " + (diag.channel === "proxy" ? "经代理（强制）" : diag.channel === "direct" ? "直连（强制绕过）" : "按当前策略")),
                   react.createElement("span", { key: "r" }, "策略判定： " + diag.route + (diag.bypassed ? "（NO_PROXY 命中）" : "")),
-                  react.createElement("span", { key: "p" }, "连通探测： " + (diag.probe && diag.probe.ok ? "可达（HTTP " + diag.probe.status + "）" : (diag.probe && diag.probe.short) || "未知")),
+                  react.createElement("span", { key: "p" }, "连通探测： " + probeHeadline(diag.probe)),
+                  diag.probe && diag.probe.why ? react.createElement("span", { key: "w", className: "dsxprx-diagwhy" }, "可能原因： " + diag.probe.why) : null,
+                  diag.probe && diag.probe.fix ? react.createElement("span", { key: "f", className: "dsxprx-diagfix" }, "挽救措施： " + diag.probe.fix) : null,
+                  diag.probe && diag.probe.note ? react.createElement("span", { key: "n", className: "dsxprx-diagwhy" }, "备注： " + diag.probe.note) : null,
                   diag.hint ? react.createElement("span", { key: "h" }, "提示： " + diag.hint) : null,
                 ]
             )

package/lib/index.js

@@ -31,6 +31,7 @@ import { installProxyFromEnvironment, proxyRouteFor } from '@deepseek-ai/dsh-htt
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import {
+  classifyProbeStatus,
   classifyTargetFailure,
   keepaliveHint,
   makeSystemProxyReader,
@@ -164,6 +165,47 @@ function getUndici() {
   return undiciPromise
 }
 
+const PROBE_UA = 'dsh-proxy-pro/0.1'
+const PROBE_TIMEOUT_MS = 6000
+
+/**
+ * One probe attempt: HEAD first, then a GET retry when the endpoint does not
+ * implement HEAD (405/501) — many APIs only answer GET, and a HEAD-only probe
+ * would libel a perfectly usable host. `request` is the caller's fetch: the
+ * global one for the policy channel, this undici copy's `fetch` for forced
+ * channels (LESSONS §22 — the two must never be mixed).
+ *
+ * @returns a verdict from classifyProbeStatus / classifyTargetFailure.
+ */
+async function probeHttp(request, target, dispatcher) {
+  const attempt = async (method) => {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS)
+    try {
+      const init = { method, redirect: 'manual', signal: controller.signal, headers: { 'user-agent': PROBE_UA } }
+      if (method === 'GET') init.headers.range = 'bytes=0-0'
+      if (dispatcher !== undefined) init.dispatcher = dispatcher
+      const res = await request(target, init)
+      return { res }
+    } catch (error) {
+      return { error }
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+  const head = await attempt('HEAD')
+  if (head.error !== undefined) return classifyTargetFailure(head.error)
+  const verdict = classifyProbeStatus(head.res.status)
+  if (verdict.kind !== 'http-error' || (head.res.status !== 405 && head.res.status !== 501)) return verdict
+  const get = await attempt('GET')
+  if (get.error !== undefined) return classifyTargetFailure(get.error)
+  const retried = classifyProbeStatus(get.res.status)
+  retried.note = retried.ok === true
+    ? 'HEAD was rejected but GET works — the host is usable.'
+    : 'HEAD was rejected; the GET retry hit the same class of problem.'
+  return retried
+}
+
 /**
  * Force the probe down one specific channel, bypassing the routing policy:
  * `'proxy'` goes through the configured proxy unconditionally, `'direct'`
@@ -173,7 +215,9 @@ function getUndici() {
 async function forceChannelProbe(url, channel, proxyUrl) {
   const und = await getUndici()
   if (und === null) {
-    return { ok: false, kind: 'unavailable', short: 'forced channel unavailable (undici could not be loaded)' }
+    return { ok: false, verdict: 'unusable', kind: 'unavailable', short: 'forced channel unavailable (undici could not be loaded)',
+      why: 'The app-side undici package could not be imported by the host process.',
+      fix: 'Uncheck 使用代理 to use the policy channel, or restart DSH; report the plugin version if it persists.' }
   }
   let dispatcher
   try {
@@ -181,10 +225,10 @@ async function forceChannelProbe(url, channel, proxyUrl) {
       ? new und.Agent({ connections: 1 })
       : new und.ProxyAgent(proxyUrl)
   } catch (error) {
-    return { ok: false, kind: 'bad-proxy', short: `invalid proxy address: ${String(error?.message ?? error)}` }
+    return { ok: false, verdict: 'unusable', kind: 'bad-proxy', short: `invalid proxy address: ${String(error?.message ?? error)}`,
+      why: 'The effective proxy address is not a valid http(s) proxy URL.',
+      fix: 'Fix the address in 代理配置 (mode = 自定义地址) or clear the custom URL.' }
   }
-  const controller = new AbortController()
-  const timer = setTimeout(() => controller.abort(), 6000)
   try {
     // MUST issue the request with THIS undici copy. The host runs two copies —
     // Node's built-in `fetch` and the app's `undici` package — and a dispatcher
@@ -192,31 +236,15 @@ async function forceChannelProbe(url, channel, proxyUrl) {
     // ("invalid onRequestStart method"); the panel rendered that as a bare
     // "fetch failed" for BOTH forced channels (LESSONS §22). und.fetch and the
     // Agent/ProxyAgent above come from the same import, so they always agree.
-    const res = await und.fetch(url, {
-      method: 'HEAD',
-      redirect: 'manual',
-      signal: controller.signal,
-      dispatcher,
-      headers: { 'user-agent': 'dsh-proxy-pro/0.1' },
-    })
-    // 407 is an authentication failure, not "reachable": reporting it as ok
-    // made the panel print 「可达（HTTP 407）」 and silenced the keepalive hint
-    // (review fix, 2026-09-17).
-    if (res.status === 407) {
-      return { ok: false, kind: 'auth', short: 'HTTP 407 — the proxy asks for authentication (NTLM), which undici cannot negotiate' }
-    }
-    return { ok: true, status: res.status }
-  } catch (error) {
-    return classifyTargetFailure(error)
+    return await probeHttp((u, i) => und.fetch(u, i), url, dispatcher)
   } finally {
-    clearTimeout(timer)
     try { dispatcher.close?.().catch?.(() => {}) } catch { /* best effort */ }
   }
 }
 
 /**
  * Probe one target the way web_fetch will see it: route verdict first, then a
- * real HEAD through the installed policy (global fetch → policy dispatcher).
+ * real request through the installed policy (global fetch → policy dispatcher).
  * `channel` selects the probe path: 'policy' (default), 'proxy' (forced via
  * proxy), or 'direct' (forced bypass).
  */
@@ -225,7 +253,9 @@ async function probeTarget(url, snapshot, channel = 'policy') {
   try {
     parsed = new URL(url)
   } catch {
-    return { url, route: 'invalid', bypassed: false, probe: { ok: false, kind: 'invalid', short: 'invalid URL — expected http(s)://host/path' } }
+    return { url, route: 'invalid', bypassed: false,
+      probe: { ok: false, verdict: 'unusable', kind: 'invalid', short: 'invalid URL — expected http(s)://host/path',
+        why: 'The text is not a parseable absolute URL.', fix: 'Use the full form, e.g. https://github.com/foo/bar.' } }
   }
   let routeName = 'DIRECT'
   try {
@@ -242,27 +272,14 @@ async function probeTarget(url, snapshot, channel = 'policy') {
   if (channel === 'proxy' || channel === 'direct') {
     const proxyUrl = channel === 'proxy' ? (snapshot?.effective?.url ?? '') : ''
     const probe = proxyUrl === '' && channel === 'proxy'
-      ? { ok: false, kind: 'bad-proxy', short: 'no active proxy url in the current snapshot' }
+      ? { ok: false, verdict: 'unusable', kind: 'bad-proxy', short: 'no active proxy url in the current snapshot',
+        why: 'The proxy switch is off (or the Windows system proxy is off), so there is nothing to force traffic through.',
+        fix: 'Turn the proxy on, or fix the address/mode in 代理配置.' }
       : await forceChannelProbe(parsed, channel, proxyUrl)
     return { url, route: routeName, bypassed, channel, probe }
   }
-  try {
-    const controller = new AbortController()
-    const timer = setTimeout(() => controller.abort(), 6000)
-    const res = await fetch(parsed, {
-      method: 'HEAD',
-      redirect: 'manual',
-      signal: controller.signal,
-      headers: { 'user-agent': 'dsh-proxy-pro/0.1' },
-    })
-    clearTimeout(timer)
-    if (res.status === 407) {
-      return { url, route: routeName, bypassed, probe: { ok: false, kind: 'auth', short: 'HTTP 407 — the proxy asks for authentication (NTLM), which undici cannot negotiate' } }
-    }
-    return { url, route: routeName, bypassed, probe: { ok: true, status: res.status } }
-  } catch (error) {
-    return { url, route: routeName, bypassed, probe: classifyTargetFailure(error) }
-  }
+  const probe = await probeHttp((u, i) => fetch(u, i), parsed, undefined)
+  return { url, route: routeName, bypassed, probe }
 }
 
 // ---- browser-trust fence (mirrors dsh's /api fence) ------------------------
@@ -486,11 +503,18 @@ function apply(ctx, config) {
     output: {
       schema: PROXY_TEST_SCHEMA,
       render: (_args, value) => {
+        const p = value.probe ?? {}
+        const head = p.verdict === 'usable'
+          ? `usable${p.status === undefined ? '' : ` (HTTP ${p.status})`}`
+          : `${p.verdict === 'degraded' ? 'degraded' : 'unusable'} — ${p.short ?? 'unknown'}`
         const lines = [
           `Route: ${value.route}`,
           `NO_PROXY bypassed: ${value.bypassed}`,
-          `Probe: ${value.probe?.ok === true ? `reachable (HTTP ${value.probe.status})` : value.probe?.short ?? 'unknown'}`,
+          `Probe: ${head}`,
         ]
+        if (p.why) lines.push(`Why: ${p.why}`)
+        if (p.fix) lines.push(`Fix: ${p.fix}`)
+        if (p.note) lines.push(`Note: ${p.note}`)
         if (value.hint) lines.push(`Hint: ${value.hint}`)
         return [{ type: 'text', text: lines.join('\n') }]
       },

package/lib/proxy-core.js

@@ -268,33 +268,136 @@ export function keepaliveHint(message = '', proxyUrl = '') {
 }
 
 /**
- * Turn a fetch rejection into a short, actionable verdict for the panel and the
- * `proxy_test` tool.
+ * Three-state verdict for one HTTP answer, shared by the panel, `proxy_test`
+ * and the HTTP API:
  *
- * A bare `fetch failed` hides the real cause. The host runs TWO undici copies —
- * Node's built-in `fetch` and the app's `undici` package — and a dispatcher
- * built by one handed to the other rejects with UND_ERR_INVALID_ARG ("invalid
- * onRequestStart method"); that is exactly how the forced-channel diagnostic
- * failed (LESSONS §22). Surface the cause code so the next report names it.
+ *  - `usable`   — the route works for real calls (2xx/3xx, plus 401: a healthy
+ *                 API endpoint answering the credential-less probe).
+ *  - `degraded` — an HTTP answer came back, so the route works, but the call
+ *                 itself would likely fail (403/404/405/429 and other 4xx).
+ *  - `unusable` — the route or the far end failed (407 auth wall, 5xx from the
+ *                 target, gateway/upstream timeouts).
+ *
+ * Every verdict carries `why` (the likely cause) and `fix` (what to try), so a
+ * diagnosis is actionable instead of a bare status code (2026-09-17: 504 and
+ * 200 both rendered as "reachable", which answered nothing).
+ *
+ * @param status - the HTTP status code a probe received.
+ * @returns `{ ok, verdict, kind, status, short, why, fix }`.
+ */
+export function classifyProbeStatus(status) {
+  const code = Number(status)
+  const base = { status: code }
+  if (code === 407) {
+    return { ...base, ok: false, verdict: 'unusable', kind: 'auth', short: 'HTTP 407 — the proxy asks for authentication (NTLM)',
+      why: 'The request never reached the target: the proxy demands NTLM, which undici cannot negotiate.',
+      fix: 'Run one curl/browser request through the same proxy (e.g. curl -x <proxy> -I https://github.com) to open an authenticated window, then retry.' }
+  }
+  if (code >= 200 && code < 400) {
+    return { ...base, ok: true, verdict: 'usable', kind: 'ok', short: `HTTP ${code} — the target answered`, why: '', fix: '' }
+  }
+  if (code === 401) {
+    return { ...base, ok: true, verdict: 'usable', kind: 'ok', short: 'HTTP 401 — the target is alive (credentials required)',
+      why: 'The probe sends no credentials, so 401 is the healthy answer from an API endpoint.',
+      fix: 'Real calls need a valid key/header; the route itself is proven to work.' }
+  }
+  if (code === 403) {
+    return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: 'HTTP 403 — the target refused the request',
+      why: 'The server was reached but denies this client: key scope, IP allow-list, WAF, or a blocked probe User-Agent.',
+      fix: 'Compare the other channel (direct vs proxy) and check the key/UA rules for this host.' }
+  }
+  if (code === 404) {
+    return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: 'HTTP 404 — path not found',
+      why: 'The route reached the server; that path does not exist there (probes often hit the bare origin).',
+      fix: 'Re-test with the concrete path you really call; if that works, ignore this result.' }
+  }
+  if (code === 405 || code === 501) {
+    return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: `HTTP ${code} — the endpoint does not accept HEAD`,
+      why: 'The diagnostic probes with HEAD; some APIs and gateways only implement GET.',
+      fix: 'The panel retries with GET automatically; a GET success means the host is usable.' }
+  }
+  if (code === 429) {
+    return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: 'HTTP 429 — rate limited',
+      why: 'The server is alive but throttling this client.',
+      fix: 'Retry later or lower the request rate; the route itself is fine.' }
+  }
+  if (code === 502) {
+    return { ...base, ok: false, verdict: 'unusable', kind: 'gateway', short: 'HTTP 502 — bad gateway',
+      why: 'An intermediary (the proxy or the target gateway) got an invalid answer from upstream — often the proxy cannot reach this host.',
+      fix: 'Compare the other channel (direct vs proxy); if the proxy is the failing leg, keep this host on the working side of NO_PROXY.' }
+  }
+  if (code === 503) {
+    return { ...base, ok: false, verdict: 'unusable', kind: 'gateway', short: 'HTTP 503 — service unavailable',
+      why: 'The target (or its gateway) is overloaded or in maintenance.',
+      fix: 'Retry later; this is server-side and unrelated to the route.' }
+  }
+  if (code === 504) {
+    return { ...base, ok: false, verdict: 'unusable', kind: 'gateway', short: 'HTTP 504 — gateway/upstream timeout',
+      why: 'The request was forwarded but nothing answered upstream in time: the target is slow or dead, or the proxy leg to it is broken.',
+      fix: 'Compare the other channel (direct vs proxy) and retry; if only one channel times out, that channel is the problem.' }
+  }
+  if (code >= 500) {
+    return { ...base, ok: false, verdict: 'unusable', kind: 'server-error', short: `HTTP ${code} — the target failed`,
+      why: 'The server answered with an error of its own; the route is fine.',
+      fix: 'Retry later; nothing to change in the proxy configuration.' }
+  }
+  return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: `HTTP ${code} — request rejected`,
+    why: 'The route works (an HTTP answer came back) but the request itself was not successful.',
+    fix: 'Check the method, path and headers your real calls use.' }
+}
+
+/**
+ * Turn a fetch rejection into an actionable verdict. A bare `fetch failed`
+ * hides the real cause: a dispatcher built by one undici copy handed to another
+ * rejects with UND_ERR_INVALID_ARG ("invalid onRequestStart method"), which is
+ * how the forced-channel diagnostic failed for both channels (LESSONS §22).
  *
  * @param error - the rejection from `fetch`.
- * @returns `{ ok: false, kind, short }` with a cause-aware message.
+ * @returns `{ ok, verdict, kind, short, why, fix }` with a cause-aware message.
  */
 export function classifyTargetFailure(error) {
   const cause = error?.cause
   const code = cause?.code ?? error?.code ?? ''
-  if (code === 'EACCES' || code === 'ENETUNREACH' || code === 'EHOSTUNREACH' || code === 'ENOTFOUND' || code === 'ECONNREFUSED' || code === 'ETIMEDOUT') {
-    return { ok: false, kind: 'unreachable', short: `cannot reach directly (${code}) — needs a proxy route` }
+  const message = String(error?.message ?? error)
+  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
+    return { ok: false, verdict: 'unusable', kind: 'unreachable', short: `DNS lookup failed (${code})`,
+      why: 'The hostname did not resolve — a wrong name/DNS, or a proxy that cannot resolve it.',
+      fix: 'Check the hostname; if this host must go through the proxy, remove it from NO_PROXY (or add it if it must go direct).' }
+  }
+  if (code === 'ECONNREFUSED') {
+    return { ok: false, verdict: 'unusable', kind: 'unreachable', short: 'connection refused (ECONNREFUSED)',
+      why: 'Something answered but refused the connection: nothing listens on that port, or the proxy is not accepting.',
+      fix: 'Check the port and that the proxy is running; compare the other channel.' }
+  }
+  if (code === 'EACCES' || code === 'ENETUNREACH' || code === 'EHOSTUNREACH') {
+    return { ok: false, verdict: 'unusable', kind: 'unreachable', short: `cannot reach directly (${code}) — needs a proxy route`,
+      why: 'The network path itself is unavailable from this machine.',
+      fix: 'Route this host through the proxy (remove the NO_PROXY entry) and retry.' }
+  }
+  if (code === 'ETIMEDOUT' || code === 'UND_ERR_CONNECT_TIMEOUT' || code === 'ABORT_ERR' || error?.name === 'AbortError') {
+    return { ok: false, verdict: 'unusable', kind: 'unreachable', short: `no answer before the timeout (${code || error?.name || 'timeout'})`,
+      why: 'Nothing answered in time — a slow/dead target, or a proxy that silently drops this destination.',
+      fix: 'Compare the other channel (direct vs proxy) and retry; if only one channel times out, that channel is the problem.' }
+  }
+  if (code === 'ECONNRESET' || code === 'UND_ERR_SOCKET' || code === 'EPIPE') {
+    return { ok: false, verdict: 'unusable', kind: 'unreachable', short: `connection reset (${code})`,
+      why: 'The connection was cut mid-flight by an intermediary or a TLS problem (corporate interception, MTU, or a reset by the far end).',
+      fix: 'Retry; compare the other channel; if TLS interception is in play, confirm the corporate CA is trusted (NODE_EXTRA_CA_CERTS).' }
   }
   if (code === 'UND_ERR_INVALID_ARG' || /invalid onRequestStart/i.test(String(cause?.message ?? ''))) {
-    return { ok: false, kind: 'dispatcher', short: `dispatcher rejected by this undici instance (${code || 'UND_ERR_INVALID_ARG'}) — mixed undici copies` }
+    return { ok: false, verdict: 'unusable', kind: 'dispatcher', short: `dispatcher rejected by this undici instance (${code || 'UND_ERR_INVALID_ARG'}) — mixed undici copies`,
+      why: 'The request and its dispatcher came from two different undici copies; the diagnostic had this bug (fixed in 1.0.2).',
+      fix: 'Update the plugin; if it persists, report the plugin version with this message.' }
   }
-  if (/407|NTLM|authentication required/i.test(String(error?.message ?? ''))) {
-    return { ok: false, kind: 'auth', short: 'the proxy asks for NTLM authentication' }
+  if (/407|NTLM|authentication required/i.test(message)) {
+    return { ok: false, verdict: 'unusable', kind: 'auth', short: 'the proxy asks for NTLM authentication',
+      why: 'The proxy demands NTLM, which undici cannot negotiate by itself.',
+      fix: 'Run one curl/browser request through the same proxy to open an authenticated window, then retry.' }
   }
   const detail = cause?.code
     ? `${cause.code}${cause?.message ? `: ${String(cause.message).slice(0, 90)}` : ''}`
     : (cause?.message ?? '')
-  const base = String(error?.message ?? error)
-  return { ok: false, kind: 'other', short: (detail ? `${base} (${detail})` : base).slice(0, 180) }
+  return { ok: false, verdict: 'unusable', kind: 'other', short: (detail ? `${message} (${detail})` : message).slice(0, 180),
+    why: 'The request failed for a reason the probe could not classify.',
+    fix: 'Compare the other channel (direct vs proxy) and retry; check proxy_status for the effective route.' }
 }

package/lib/tool-schemas.js

@@ -68,9 +68,17 @@ export const PROXY_TEST_SCHEMA = {
       required: true,
       properties: {
         ok: { type: 'boolean', required: true },
+        // Three-state verdict plus the actionable pair the panel and the tool
+        // render (2026-09-17: a 504 used to print as "reachable"). Every field
+        // must be listed here — the object is additionalProperties:false, so an
+        // undeclared field fails schema validation.
+        verdict: { type: 'string' },
         status: { type: 'number' },
         kind: { type: 'string' },
         short: { type: 'string' },
+        why: { type: 'string' },
+        fix: { type: 'string' },
+        note: { type: 'string' },
       },
     },
     hint: { type: 'string' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanglaofish/dsh-proxy-pro",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "DSH proxy manager: route model requests, web fetches and spawned tools through the Windows system proxy or a custom address; per-URL route diagnosis, one-click toggle from the conversation header, a dedicated Settings page, and keepalive-aware 407 hints.",
   "type": "module",
   "main": "./lib/index.js",