@yanglaofish/dsh-proxy-pro 1.0.1 → 1.0.3

package/README.md

@@ -21,7 +21,7 @@
 
 ```sh
 dsh plugin --profile web add @yanglaofish/dsh-proxy-pro
-dsh plugin --profile obsidian-web add @yanglaofish/dsh-proxy-pro
+dsh plugin --profile test add @yanglaofish/dsh-proxy-pro
 ```
 
 **方式 B：GitHub 源安装**
@@ -70,7 +70,7 @@ proxy:
 
 ```sh
 dsh plugin --profile web remove @yanglaofish/dsh-proxy-pro
-dsh plugin --profile obsidian-web remove @yanglaofish/dsh-proxy-pro
+dsh plugin --profile test remove @yanglaofish/dsh-proxy-pro
 ```
 
 卸载即恢复原始路由行为，不留残留。

package/docs/ACCEPTANCE.md

@@ -7,7 +7,7 @@
 ## 0. 前置（已就绪，无需操作）
 
 - [x] 单测 16/16 通过、语法 OK、git 干净（head = afb96b4）
-- [x] web / obsidian-web 两 profile 已装入 `dsh-proxy-pro`（node_modules 为 Junction 软链）
+- [x] web / test 两 profile 已装入 `dsh-proxy-pro`（node_modules 为 Junction 软链）
 - [x] `dsh --dump-config` 预检：两 profile 组合树均含 `- id: dsh-proxy-pro` 行
 - [x] settings.yaml 的 `proxy.enabled: true` → 重启后插件**启动即接管**系统代理（预期行为）
 
@@ -52,9 +52,9 @@
 `<profile>/cordis.patch.yml` 追加一行 `- id: proxy, disabled: true`（禁旧
 dsh-plugin-proxy）→ 重启 → 复测 A1-A6。回滚 = 删该行，settings.yaml 全程不动。
 
-## 6. obsidian-web 复用
+## 6. test 复用
 
-用 `dsh --profile obsidian-web` 启动 → 重复 §2-§3（A10）。
+用 `dsh --profile test` 启动 → 重复 §2-§3（A10）。
 
 ---
 

package/docs/LESSONS.md

@@ -106,7 +106,7 @@ const envLike = {
 ## 5. 为什么新插件放独立目录（避开 node_modules）
 
 ```
-C:\Users\...\profiles\[web|obsidian-web]\node_modules\dsh-plugin-proxy\package.json
+C:\Users\...\profiles\[web|test]\node_modules\dsh-plugin-proxy\package.json
   LinkType = HardLink → C:\Users\...\pnpm\store\v11\files\...（pnpm 全局 store）
 ```
 
@@ -167,7 +167,7 @@ window.__ModuleLoader__.load({
 });
 ```
 
-技能库里的 `dsh-skill-manager@4.3.3`（obsidian-web profile 已装）是**现代写法参照模板**：
+技能库里的 `dsh-skill-manager@4.3.3`（test profile 已装）是**现代写法参照模板**：
 
 ```js
 ctx.slots.inject("settings.section", () => ctx.slots.register({
@@ -270,7 +270,7 @@ POST /dsh-proxy-pro/api/toggle {"enabled":bool} → 更新 settings + 立即 syn
 | Web GUI | http://127.0.0.1:43120（NodeService 21872 监听） |
 | 系统代理 | proxyhk.huawei.com:8080（NTLM SWG，Proxy ON） |
 | NO_PROXY | 大列表：`*.huawei.com` 等内网全量 + localhost/127.0.0.1/::1 |
-| profile | web / obsidian-web（两份，插件需都装） |
+| profile | web / test（两份，插件需都装） |
 | settings.yaml | proxy: {enabled: true, mode: system, customUrl: http://127.0.0.1:7890} |
 | 验证基线 | github → PROXIED；deepseek.com → DIRECT；web_fetch PR#3574 → 200 |
 | loadLayeredEnv | process.env + cwd/.env + ~/.dsh/.env（仅 undefined 时写入） |
@@ -280,8 +280,8 @@ POST /dsh-proxy-pro/api/toggle {"enabled":bool} → 更新 settings + 立即 syn
 - 打包源码：`C:\Users\w00958282\AppData\Local\Programs\DSH Desktop\resources\app\node_modules\@deepseek-ai\...`
   （dsh-web-fetch-http / dsh-http-proxy / dsh-app-boot / dsh-web / dsh-tool-web /
    dsh-client-ui-conversation / dsh-client-ui-chat / dsh-client-modules / dsh-settings）
-- 原插件（已打补丁 + .bak）：`~/.dsh/profiles\{web,obsidian-web}\node_modules\dsh-plugin-proxy\lib\`
-- 参照模板：`~/.dsh/profiles\obsidian-web\node_modules\dsh-skill-manager\lib\`（index.js + client.js）
+- 原插件（已打补丁 + .bak）：`~/.dsh/profiles\{web,test}\node_modules\dsh-plugin-proxy\lib\`
+- 参照模板：`~/.dsh/profiles\test\node_modules\dsh-skill-manager\lib\`（index.js + client.js）
 - 本插件：`~/.dsh/plugins/dsh-proxy-pro/`（git 仓库，发布形态，见 §12）
 - 环境事实：`~/.dsh/.env`（已删，纯冗余证据）；`settings.yaml`、`cordis.patch.yml`、`cordis.yml`
 
@@ -390,7 +390,7 @@ POST /dsh-proxy-pro/api/toggle {"enabled":bool} → 更新 settings + 立即 syn
   ——这就是 8ce5e21 修的那个 schema bug（跑在修复前）。
 - 决定性证据：`profiles/web/package.json` LastWriteTime = **11:50:28**，
   恰好在 desktop 的 `recovery plugin uninstall failed`（11:50:09 error.log）
-  窗口内；对读 `profiles/obsidian-web/package.json` 完好（11:35 未动）。
+  窗口内；对读 `profiles/test/package.json` 完好（11:35 未动）。
 - **根因：桌面版启动时对解析失败的插件执行 recovery 卸载**
   （`dsh plugin --profile web remove @yanglaofish/dsh-skill-manager`），
   该操作重写了 web profile 的 package.json，**把我们手工加的两处
@@ -401,7 +401,7 @@ POST /dsh-proxy-pro/api/toggle {"enabled":bool} → 更新 settings + 立即 syn
 
 ### 14.2 修复与预防
 
-- 修复：对照 obsidian-web 的形态把 `dependencies["dsh-proxy-pro"] =
+- 修复：对照 test 的形态把 `dependencies["dsh-proxy-pro"] =
   link:...` 与 `dsh.profile.bundles` 里的 `"dsh-proxy-pro"` 加回
   web/package.json；`dsh --profile web --dump-config` 预检两行都在、exit=0。
 - 预防：每次用户重启前**先读 profile 的 package.json** 确认条目在（read
@@ -633,4 +633,70 @@ git log --oneline  # 历史完整（refs/heads/master 里的 tip 仍在）
 前提：`.git.broken/refs/heads/<branch>` 仍指向有效 commit、objects 完整（松散或 pack）。
 若 refs 也没了，就只能等网络恢复后 `git fetch` 远端历史再 `git reset --mixed origin/<branch>`。
 本例 `git fetch` 失败于 `Could not resolve proxy: proxyhk.huawei.com`——git 的 `http.proxy`
-指向公司代理，离开公司网络（或代理关闭）时 GitHub 不可达；此时**不要** push/force push。
+指向公司代理，离开公司网络（或代理关闭）时 GitHub 不可达；此时**不要** push/force push。
+
+---
+
+## 22. 强制通道探测必须用同一个 undici 副本（2026-09-17）
+
+**症状**：设置页「代理配置」的逐 URL 诊断，无论勾不勾「使用代理」都返回 `fail`
+（面板只显示 `fetch failed`）；而 `curl`、独立 node 进程、policy 通道都正常。
+
+**根因（实测）**：`forceChannelProbe` 用 `import('undici')`（app 的 undici 包）造
+`Agent`/`ProxyAgent`，却把它交给**全局 `fetch`**（Node 内置的另一份 undici）当 `dispatcher`：
+
+```
+CONTROL 内置 fetch（无 dispatcher）        -> OK 401
+A  内置 fetch + 外部 undici Agent         -> ERR fetch failed | UND_ERR_INVALID_ARG: invalid onRequestStart method
+B  外部 undici 的 fetch + 同一 Agent      -> OK 401
+D  内置 fetch + 外部 ProxyAgent           -> ERR fetch failed | UND_ERR_INVALID_ARG
+E  外部 undici 的 fetch + 同一 ProxyAgent -> OK 401
+```
+
+**规矩**：凡是要传 `dispatcher` 的请求，**请求与被传的 dispatcher 必须来自同一次
+`import('undici')`**（即 `und.fetch(url, { dispatcher })`）。这正是 §3 的老教训
+（mixed undici instances → UND_ERR_INVALID_ARG）——插件主干一直靠"委托
+`installProxyFromEnvironment`、自己绝不碰 undici"规避它，而强制通道绕过了这条原则。
+
+**顺带修掉的诊断缺陷**：`classifyTargetFailure` 原本只回 `error.message`（"fetch failed"），
+丢掉了 `error.cause` 里的 `code`。现在优先输出 cause code，并把 `UND_ERR_INVALID_ARG`
+单独归类（`kind: 'dispatcher'`，提示 "mixed undici copies"）。
+
+---
+
+## 23. 与 @deepseek-ai/dsh-http-proxy 插件行共存会抢全局 dispatcher
+
+同一天的另一条线索：把 `@deepseek-ai/dsh-http-proxy` **作为插件行同时启用**时，policy 通道
+探测也出现过 `fetch failed`；从 profile 的 bundles/依赖里移除该行后恢复正常。
+
+原因：两个插件都调同一个库的 `installProxyFromEnvironment()`，各自
+`setGlobalDispatcher()`；谁先卸载，谁的 disposer 就把"它安装前"的 dispatcher
+（`previousDispatcher`）恢复回去，全局 dispatcher 于是可能指向已关闭/陈旧实例。
+
+**结论**：本插件与 `dsh-http-proxy` 插件行**二选一**。库本身必须保留——插件 import 它的
+`installProxyFromEnvironment` / `proxyRouteFor`，而 DSH 的 web_fetch 通道读的正是同一模块的
+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/docs/SPEC.md

@@ -65,7 +65,7 @@
 | NFR-3 | 可回滚 | 切回原插件只需恢复 cordis.patch.yml 一行 + 保留 `.bak` |
 | NFR-4 | 单一 dispatcher 主人 | 与 dsh-plugin-proxy 二选一启用，不同时 |
 | NFR-5 | 无新增第三方依赖 | 纯 ESM + 现有 DSH 包；逻辑层（proxy-core.js）零依赖可单测 |
-| NFR-6 | 双 profile 部署 | web + obsidian-web 都要装 |
+| NFR-6 | 双 profile 部署 | web + test 都要装 |
 
 ---
 
@@ -321,7 +321,7 @@ systemPollMs: 30000
 3. 重启 DSH → `proxy_status` 确认 active=true、url=proxyhk → 手动 web_fetch
    一个被墙 URL（如 github）确认 200。
 4. 验证 proxy_test github=PROXIED / deepseek=DIRECT。
-5. 再对 obsidian-web profile 做同样操作，重复验证。
+5. 再对 test profile 做同样操作，重复验证。
 6. 回滚 = 恢复原插件行 enabled（settings.yaml 没动过，天然安全），或
    `dsh plugin --profile web remove @yanglaofish/dsh-proxy-pro`。
 
@@ -378,4 +378,4 @@ _运行时快照（2026-09-17，⚠️ 尚未重启）：`/dsh-proxy-pro/api/sta
 5. ✅ 已装入两 profile + `--dump-config` 预检通过（两个组合树都含 dsh-proxy-pro 行）；
    ⏳ 待用户重启（当前**尚未重启**，403 为应用安全门、非插件响应）
 6. ⏳ GUI 确认 A1/A2（头部胶囊 + 设置页「代理管理」）→ 运行时验收 A3-A9
-   → obsidian-web A10 → 发布收尾
+   → test A10 → 发布收尾

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,8 @@ import { installProxyFromEnvironment, proxyRouteFor } from '@deepseek-ai/dsh-htt
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import {
+  classifyProbeStatus,
+  classifyTargetFailure,
   keepaliveHint,
   makeSystemProxyReader,
   normalizeProxyUrl,
@@ -149,18 +151,8 @@ function renderStatusText(snapshot) {
   ].join('\n')
 }
 
-/** Isolate NetworkError-ish codes that mean "could not connect at all". */
-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` }
-  }
-  if (/407|NTLM|authentication required/i.test(String(error?.message ?? ''))) {
-    return { ok: false, kind: 'auth', short: 'the proxy asks for NTLM authentication' }
-  }
-  return { ok: false, kind: 'other', short: (error?.message ?? String(error)).slice(0, 120) }
-}
+// classifyTargetFailure lives in proxy-core.js (pure logic, unit-tested) so the
+// panel's verdict can name the undici cause instead of a bare "fetch failed".
 
 // Forced-channel probing uses undici directly. Load lazily and never let a
 // resolution failure block boot (LESSONS §14: boot must not depend on a new
@@ -173,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'`
@@ -182,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 {
@@ -190,36 +225,26 @@ 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 {
-    const res = await 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)
+    // 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
+    // built by one handed to the other rejects with UND_ERR_INVALID_ARG
+    // ("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.
+    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).
  */
@@ -228,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 {
@@ -245,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) ------------------------
@@ -489,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

@@ -266,3 +266,138 @@ export function keepaliveHint(message = '', proxyUrl = '') {
   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.`
 }
+
+/**
+ * Three-state verdict for one HTTP answer, shared by the panel, `proxy_test`
+ * and the HTTP API:
+ *
+ *  - `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, verdict, kind, short, why, fix }` with a cause-aware message.
+ */
+export function classifyTargetFailure(error) {
+  const cause = error?.cause
+  const code = cause?.code ?? error?.code ?? ''
+  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, 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(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 ?? '')
+  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.1",
+  "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",