@yanglaofish/dsh-proxy-pro 1.0.2 → 1.0.4

package/docs/LESSONS.md

@@ -675,4 +675,52 @@ 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 校验直接失败。
+
+---
+
+## 25. 策略通道也要同一 undici 副本（2026-09-17）
+
+**症状**：1.0.3 面板「连通探测」（不勾选「使用代理」）显示
+`不可用：dispatcher rejected by this undici instance (UND_ERR_INVALID_ARG) — mixed undici copies`。
+
+**根因**：1.0.2 只修了强制通道（`und.fetch` + 同副本 dispatcher，§22）。策略通道一直用 Node
+内置 `fetch` 且不传 dispatcher —— 但全局 dispatcher 是 `installProxyFromEnvironment` 用 **app
+undici** 装的，内置 fetch 拿它发请求 = A 组合（内置 fetch + 外部 Agent）→ 必然
+UND_ERR_INVALID_ARG。之前没暴露，是因为面板默认勾选「使用代理」（强制通道）掩盖了它。
+
+**修法**（1.0.4）：策略通道同样走 app undici——
+`policyProbe()` = `und.fetch(url, { dispatcher: und.getGlobalDispatcher() })`。
+`getGlobalDispatcher()` 返回的正是 web_fetch 通道在用的全局 dispatcher，语义 = 模拟 web_fetch，
+且永远同副本。三条探测路径现在统一：policy = 全局 dispatcher / forced-direct = 新建 Agent /
+forced-proxy = 新建 ProxyAgent，全部由 `und.fetch` 发起。
+
+**连带**：所有展示文案（short/why/fix/hint）中文化——面板是中文 UI，英文 why/fix 让人无法
+行动；`proxy_test` 工具输出同步中文（模型照读）。教训：给用户看的文案别用英文"图省事"，
+判定结论必须能直接用。
+
+**测试**：断言随中文文案同步翻新（/混用/、/超时/、/上游|超时/、/ECONNREFUSED/）。

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,46 @@ function getUndici() {
   return undiciPromise
 }
 
+const PROBE_UA = 'dsh-proxy-pro/0.1'
+const PROBE_TIMEOUT_MS = 6000
+
+/**
+ * 一个探测尝试：先 HEAD，端点不支持 HEAD（405/501）时再用 GET 复测——
+ * 很多 API 只实现 GET，只用 HEAD 会冤枉一个可用主机。`request` 是调用方
+ * 的 fetch：两条通道现在都用 app undici 的 `und.fetch` 配同副本 dispatcher
+ * （LESSONS §22/§25 —— 绝不要把两份副本混在一起）。
+ *
+ * @returns 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 被拒绝但 GET 可用 — 主机可用。'
+    : 'HEAD 被拒绝；GET 复测也遇到同类问题。'
+  return retried
+}
+
 /**
  * Force the probe down one specific channel, bypassing the routing policy:
  * `'proxy'` goes through the configured proxy unconditionally, `'direct'`
@@ -173,7 +214,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: '强制通道不可用（undici 未能加载）',
+      why: '宿主进程无法加载 app 侧 undici 包。',
+      fix: '取消勾选「使用代理」改用策略通道，或重启 DSH；仍出现请反馈插件版本。' }
   }
   let dispatcher
   try {
@@ -181,10 +224,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: `代理地址无效：${String(error?.message ?? error)}`,
+      why: '当前生效的代理地址不是有效的 http(s) 代理 URL。',
+      fix: '在「代理配置」修复地址（mode = 自定义地址）或清空自定义地址。' }
   }
-  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,45 +235,47 @@ 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).
- * `channel` selects the probe path: 'policy' (default), 'proxy' (forced via
- * proxy), or 'direct' (forced bypass).
+ * 按已安装策略探测，与 web_fetch 走同一条路：用同一份 undici 的 fetch 加
+ * 全局 dispatcher。策略通道不能用 Node 内置 `fetch`——全局 dispatcher 由
+ * app 的 undici（installProxyFromEnvironment）安装，内置 fetch 拿它必然
+ * UND_ERR_INVALID_ARG（LESSONS §25，A 组合；面板当时显示"dispatcher
+ * rejected… mixed undici copies"）。
+ */
+async function policyProbe(target) {
+  const und = await getUndici()
+  if (und === null) {
+    return { ok: false, verdict: 'unusable', kind: 'unavailable', short: '策略通道不可用（undici 未能加载）',
+      why: '宿主进程无法加载 app 侧 undici 包。', fix: '重启 DSH；仍出现请反馈插件版本。' }
+  }
+  const dispatcher = typeof und.getGlobalDispatcher === 'function' ? und.getGlobalDispatcher() : undefined
+  return probeHttp((u, i) => und.fetch(u, i), target, dispatcher)
+}
+
+/**
+ * 按 web_fetch 的方式探测一个目标：先给路由判定，再用策略通道发真实请求
+ * （app undici 的 fetch + 全局 dispatcher，见 policyProbe）。`channel` 选择
+ * 探测路径：'policy'（默认）、'proxy'（强制走代理）、'direct'（强制绕过）。
  */
 async function probeTarget(url, snapshot, channel = 'policy') {
   let parsed
   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: 'URL 无效 — 需要 http(s)://主机/路径',
+        why: '输入不是可解析的绝对 URL。', fix: '用完整形式，如 https://github.com/foo/bar。' } }
   }
   let routeName = 'DIRECT'
   try {
-    const policyProbe = proxyRouteFor(parsed)
-    routeName = policyProbe.proxied ? `PROXIED ${policyProbe.proxy}` : 'DIRECT'
+    const routeProbe = proxyRouteFor(parsed)
+    routeName = routeProbe.proxied ? `PROXIED ${routeProbe.proxy}` : 'DIRECT'
   } catch {
     // proxyRouteFor unavailable in this composition → rely on state snapshot
   }
@@ -242,27 +287,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: '当前快照里没有可用的代理地址',
+        why: '代理开关处于关闭（或 Windows 系统代理关闭），没有可强制走代理的对象。',
+        fix: '打开代理，或在「代理配置」里修复地址/模式。' }
       : 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 policyProbe(parsed)
+  return { url, route: routeName, bypassed, probe }
 }
 
 // ---- browser-trust fence (mirrors dsh's /api fence) ------------------------
@@ -486,12 +518,19 @@ function apply(ctx, config) {
     output: {
       schema: PROXY_TEST_SCHEMA,
       render: (_args, value) => {
+        const p = value.probe ?? {}
+        const head = p.verdict === 'usable'
+          ? `可用${p.status === undefined ? '' : `（HTTP ${p.status}）`}`
+          : `${p.verdict === 'degraded' ? '降级' : '不可用'} — ${p.short ?? '未知'}`
         const lines = [
-          `Route: ${value.route}`,
-          `NO_PROXY bypassed: ${value.bypassed}`,
-          `Probe: ${value.probe?.ok === true ? `reachable (HTTP ${value.probe.status})` : value.probe?.short ?? 'unknown'}`,
+          `路由: ${value.route}`,
+          `NO_PROXY 命中: ${value.bypassed}`,
+          `连通探测: ${head}`,
         ]
-        if (value.hint) lines.push(`Hint: ${value.hint}`)
+        if (p.why) lines.push(`可能原因: ${p.why}`)
+        if (p.fix) lines.push(`挽救措施: ${p.fix}`)
+        if (p.note) lines.push(`备注: ${p.note}`)
+        if (value.hint) lines.push(`提示: ${value.hint}`)
         return [{ type: 'text', text: lines.join('\n') }]
       },
     },

package/lib/proxy-core.js

@@ -254,47 +254,148 @@ export function summarize(snapshot) {
 }
 
 /**
- * NTLM keepalive hint: SWG proxies (netentsec etc.) ask undici for NTLM auth
- * which undici cannot negotiate; a curl/browser NAT'd connection keeps a
- * window open. Only relevant when a 407 or auth-required response is seen.
- * The example URL is caller-supplied (the effective proxy), never hardcoded —
- * a fixed sample leaked this developer's own corporate proxy into every hint.
+ * NTLM keepalive 提示：SWG 类代理（netentsec 等）向 undici 索要 NTLM 认证，
+ * undici 无法协商；curl/浏览器最近一次经过同一代理的连接会保持一段已认证
+ * 窗口。仅在看到 407 或认证相关应答时才有意义。示例 URL 由调用方传入
+ * （生效代理地址），绝不硬编码——固定样例曾把开发者自己的公司代理泄漏进
+ * 每一条提示里。
  */
 export function keepaliveHint(message = '', proxyUrl = '') {
   const text = typeof message === 'string' ? message : ''
   if (!/407|NTLM|proxy authentication|authentication required/i.test(text)) return ''
   const example = typeof proxyUrl === 'string' && proxyUrl !== '' ? proxyUrl : 'http://localhost:7890'
-  return `This proxy asks for NTLM authentication, which undici cannot negotiate by itself. A recent curl/browser connection to the same proxy keeps an authenticated window open — run a \`curl\` through the proxy (e.g. \`curl -x ${example} -I https://github.com\`) once, then retry.`
+  return `该代理要求 NTLM 认证，undici 无法自行协商。最近一次 curl/浏览器到同一代理的连接会保持一段已认证窗口——先执行一次 \`curl -x ${example} -I https://github.com\`，然后重试。`
 }
 
 /**
- * Turn a fetch rejection into a short, actionable verdict for the panel and the
- * `proxy_test` tool.
+ * 单个 HTTP 应答的三态判定，供面板、`proxy_test` 与 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`   — 真实调用可用（2xx/3xx，以及 401：健康的 API 端点对
+ *                 不带凭证的探测就该回 401）。
+ *  - `degraded` — 拿到了 HTTP 应答（路由通），但这次调用多半会失败
+ *                 （403/404/405/429 等 4xx）。
+ *  - `unusable` — 路由或对端失败（407 认证墙、目标 5xx、网关/上游超时）。
  *
- * @param error - the rejection from `fetch`.
- * @returns `{ ok: false, kind, short }` with a cause-aware message.
+ * 每个结论都带 `why`（可能原因）与 `fix`（挽救措施），让诊断直接可行动，
+ * 而不是丢一个状态码（2026-09-17：504 曾与 200 一样显示成「可达」）。
+ *
+ * @param status - 探测收到的 HTTP 状态码。
+ * @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 — 代理要求 NTLM 认证',
+      why: '请求根本没到目标：代理拦下并索要 NTLM 认证，undici 无法协商。',
+      fix: '先用 curl/浏览器走同一代理过一次（如 curl -x <代理> -I https://github.com）打开认证窗口，再重试。' }
+  }
+  if (code >= 200 && code < 400) {
+    return { ...base, ok: true, verdict: 'usable', kind: 'ok', short: `HTTP ${code} — 目标正常响应`, why: '', fix: '' }
+  }
+  if (code === 401) {
+    return { ...base, ok: true, verdict: 'usable', kind: 'ok', short: 'HTTP 401 — 目标存活（需要凭证）',
+      why: '探测不带凭证，所以 401 是健康 API 端点的正常应答。',
+      fix: '真实调用需要有效 key/请求头；这条结果已经证明路由可用。' }
+  }
+  if (code === 403) {
+    return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: 'HTTP 403 — 目标拒绝了请求',
+      why: '已到达服务器但被拒绝：key 权限、IP 白名单、WAF，或探测 UA 被挡。',
+      fix: '对比直连/代理两侧，并检查该主机的 key/UA 规则。' }
+  }
+  if (code === 404) {
+    return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: 'HTTP 404 — 路径不存在',
+      why: '路由已到服务器，但该路径不存在（探测常打根路径）。',
+      fix: '用真实调用的完整路径复测；能通就忽略此结果。' }
+  }
+  if (code === 405 || code === 501) {
+    return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: `HTTP ${code} — 端点不支持 HEAD`,
+      why: '诊断用 HEAD 探测，有些 API/网关只实现 GET。',
+      fix: '面板已自动换 GET 复测；GET 成功即主机可用。' }
+  }
+  if (code === 429) {
+    return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: 'HTTP 429 — 被限流',
+      why: '服务器活着但在限流。',
+      fix: '稍后重试或降低请求频率；路由本身没问题。' }
+  }
+  if (code === 502) {
+    return { ...base, ok: false, verdict: 'unusable', kind: 'gateway', short: 'HTTP 502 — 网关错误（bad gateway）',
+      why: '中间环节（代理或目标网关）拿到无效上游响应——常见是代理连不上该主机。',
+      fix: '对比直连/代理两侧；若失败在代理侧，把该主机保留在 NO_PROXY 的另一边。' }
+  }
+  if (code === 503) {
+    return { ...base, ok: false, verdict: 'unusable', kind: 'gateway', short: 'HTTP 503 — 服务不可用',
+      why: '目标（或其网关）过载或维护中。',
+      fix: '稍后重试；这是服务端问题，与路由无关。' }
+  }
+  if (code === 504) {
+    return { ...base, ok: false, verdict: 'unusable', kind: 'gateway', short: 'HTTP 504 — 网关/上游超时',
+      why: '请求已转发但上游迟迟无响应：目标慢或挂了，或代理到目标这一段坏了。',
+      fix: '对比直连/代理两侧并重试；只有某一侧超时，问题就在那一侧。' }
+  }
+  if (code >= 500) {
+    return { ...base, ok: false, verdict: 'unusable', kind: 'server-error', short: `HTTP ${code} — 目标服务端错误`,
+      why: '服务器自身报错；路由没问题。',
+      fix: '稍后重试；无需改动代理配置。' }
+  }
+  return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: `HTTP ${code} — 请求被拒绝`,
+    why: '路由通（拿到了 HTTP 应答），但这次请求本身不成功。',
+    fix: '检查真实调用用的方法、路径和请求头。' }
+}
+
+/**
+ * 把 fetch 的拒绝转成可行动的结论。裸的 `fetch failed` 掩盖了真正原因：
+ * 一份 undici 造的 dispatcher 交给另一份使用时，会抛 UND_ERR_INVALID_ARG
+ * （"invalid onRequestStart method"）——1.0.2 之前强制通道诊断两个方向都
+ * 死在这里（LESSONS §22）；1.0.4 又发现策略通道也在混两份副本
+ * （LESSONS §25）。把 cause code 亮出来，下一次报告就能指名道姓。
+ *
+ * @param error - `fetch` 抛出的拒绝。
+ * @returns 带 cause 信息的 `{ ok, verdict, kind, short, why, fix }`（中文文案）。
  */
 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 解析失败（${code}）`,
+      why: '主机名没解析出来——名字/DNS 错，或代理无法解析它。',
+      fix: '检查主机名；该主机若必须走代理，把它移出 NO_PROXY（反之加进去）。' }
+  }
+  if (code === 'ECONNREFUSED') {
+    return { ok: false, verdict: 'unusable', kind: 'unreachable', short: '连接被拒绝（ECONNREFUSED）',
+      why: '有东西应答但拒绝连接：端口无人监听，或代理不在接受连接。',
+      fix: '检查端口与代理是否在运行；对比另一侧通道。' }
+  }
+  if (code === 'EACCES' || code === 'ENETUNREACH' || code === 'EHOSTUNREACH') {
+    return { ok: false, verdict: 'unusable', kind: 'unreachable', short: `直连不可达（${code}）—需要走代理`,
+      why: '本机到目标的网络路径本身不可用。',
+      fix: '让该主机走代理（从 NO_PROXY 移除）再重试。' }
+  }
+  if (code === 'ETIMEDOUT' || code === 'UND_ERR_CONNECT_TIMEOUT' || code === 'ABORT_ERR' || error?.name === 'AbortError') {
+    return { ok: false, verdict: 'unusable', kind: 'unreachable', short: `超时前无应答（${code || error?.name || 'timeout'}）`,
+      why: '到时间没应答——目标慢/挂，或代理静默丢弃该目标。',
+      fix: '对比直连/代理两侧并重试；只有某一侧超时，问题就在那一侧。' }
+  }
+  if (code === 'ECONNRESET' || code === 'UND_ERR_SOCKET' || code === 'EPIPE') {
+    return { ok: false, verdict: 'unusable', kind: 'unreachable', short: `连接被重置（${code}）`,
+      why: '连接中途被切断——中间设备或 TLS 问题（公司拦截、MTU、对端重置）。',
+      fix: '重试并对比另一侧；若有 TLS 拦截，确认公司 CA 已被信任（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 被当前 undici 副本拒绝（${code || 'UND_ERR_INVALID_ARG'}）—两份副本混用`,
+      why: '请求和它的 dispatcher 来自两份不同的 undici 副本；1.0.2 修过强制通道，1.0.4 修策略通道。',
+      fix: '更新插件；若仍出现，把插件版本连同这条信息一起反馈。' }
   }
-  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: '代理要求 NTLM 认证',
+      why: '代理索要 NTLM，undici 无法单独完成协商。',
+      fix: '先用 curl/浏览器走同一代理过一次（打开认证窗口），再重试。' }
   }
   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: '请求失败，探测器无法归类原因。',
+    fix: '对比直连/代理两侧并重试；用 proxy_status 查看生效路由。' }
 }

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.4",
   "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",