@yanglaofish/dsh-proxy-pro 1.0.6 → 1.0.7

package/docs/LESSONS.md

@@ -750,4 +750,34 @@ scope.watch(() => { void requestSync().catch(() => {}) })
 
 **教训**：① ESM 顶层 import 命中断言是**加载期**错误——一次错误的 import 能杀死整个进程，所以
 对外部包的导出要查运行环境的实际版本，而不是凭记忆；② 能从服务拿到的（settings 是 inject 服务）
-就不要 import 包；③ 「桌面版」与「全局 CLI 版」是两套依赖树，一个功能必须两端都能加载。
+就不要 import 包；③ 「桌面版」与「全局 CLI 版」是两套依赖树，一个功能必须两端都能加载。
+
+---
+
+## 27. HEAD 404 ≠ 路径不存在：探测必须 GET 复测（2026-09-18）
+
+**症状**：面板测 `https://dashscope.aliyuncs.com/compatible-mode/v1` 和 `.../v1/models`
+一律显示「降级 — HTTP 404 — 路径不存在」；连测几个厂商的 API 都是 404，用户开始怀疑
+「是不是网络不可达」。
+
+**真相**（实测对照）：
+
+| 请求 | DashScope 应答 |
+| --- | --- |
+| GET `/compatible-mode/v1/models` | **401**（端点存在，只缺 API Key） |
+| GET `/compatible-mode/v1/chat/completions` | **400**（端点存在，请求不合法） |
+| GET `/` | 404 |
+| HEAD `/compatible-mode/v1/models` | **404** ← 同一个端点！ |
+
+网关不给 HEAD 注册路由，对 HEAD 一律回 404；而 404 被探测当成「路径不存在」，健康的
+API 端点就这样被误判。**404 从来不是「网络不可达」的证据**——它恰恰证明拿到了 HTTP 应答
+（真正的不可达是 ENOTFOUND/ECONNREFUSED/ETIMEDOUT/代理 407）。
+
+**改法**（1.0.7）：回退条件从 405/501 扩到 **404/405/501**，提为纯函数
+`headNeedsGetRetry(status)`（proxy-core，可单测）。GET 复测带 `Range: bytes=0-0` 只取首
+字节，代价极小；note 写明「HEAD 返回 X，GET 得到 Y — 以 GET 为准」。404 的 why/fix 改为
+「HEAD 与 GET 都 404」并引导换真实完整端点复测。
+
+**教训**：① 探测方法本身就是误判来源——HEAD「轻量」不等于「等价」；② 把 404 当「不存在」
+之前先问「服务器认不认这个方法」；③ 状态码是二手的，链路层结论只能由「是否拿到 HTTP
+应答」给出。

package/docs/SPEC.md

@@ -199,7 +199,9 @@ installProxyFromEnvironment 的 none-branch 完成：恢复首次安装前的 en
 
 `proxy_test` 内部：`proxyRouteFor(parsed)` 判路由名（try/catch，不可用时回退快照
 推导）→ NO_PROXY 列表命中判断 → `fetch(url, {method:'HEAD', redirect:'manual'})`
-实测 6s 超时（AbortController）→ `classifyTargetFailure` 归类
+实测 6s 超时（AbortController）；HEAD 状态为 404/405/501 时按 `headNeedsGetRetry`
+用 GET（`Range: bytes=0-0`）复测并以 GET 为准（LESSONS §27：网关常不给 HEAD 注册
+路由，HEAD 404 ≠ 路径不存在）→ `classifyTargetFailure` 归类
 （EACCES/ENETUNREACH/EHOSTUNREACH → "needs a proxy route"；407/NTLM → auth）。
 
 ### 4.7 系统提示段落

package/lib/index.js

@@ -32,6 +32,7 @@ import { promisify } from 'node:util'
 import {
   classifyProbeStatus,
   classifyTargetFailure,
+  headNeedsGetRetry,
   keepaliveHint,
   makeSystemProxyReader,
   normalizeProxyUrl,
@@ -171,10 +172,12 @@ 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 —— 绝不要把两份副本混在一起）。
+ * 一个探测尝试：先 HEAD，HEAD 结论不可信（404/405/501）时再用 GET 复测——
+ * 405/501 是「不支持该方法」，404 是网关不给 HEAD 注册路由时的伪装
+ * （LESSONS §27：DashScope `HEAD /models` → 404，同路径 GET → 401），只用
+ * HEAD 会把健康端点误判成「路径不存在」。`request` 是调用方的 fetch：两条
+ * 通道都用 app undici 的 `und.fetch` 配同副本 dispatcher（LESSONS §22/§25
+ * —— 绝不要把两份副本混在一起）。
  *
  * @returns classifyProbeStatus / classifyTargetFailure 的判定。
  */
@@ -197,13 +200,16 @@ async function probeHttp(request, target, dispatcher) {
   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
+  if (verdict.kind !== 'http-error' || !headNeedsGetRetry(head.res.status)) 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 复测也遇到同类问题。'
+  const sameStatus = get.res.status === head.res.status
+  retried.note = sameStatus
+    ? `HEAD 与 GET 均返回 ${get.res.status} — 该路径确实不可用。`
+    : retried.ok === true
+      ? `HEAD 返回 ${head.res.status}，GET 得到 ${get.res.status} — 以 GET 为准（网关常不给 HEAD 注册路由）。`
+      : `HEAD 返回 ${head.res.status}，GET 得到 ${get.res.status} — 以 GET 为准。`
   return retried
 }
 

package/lib/proxy-core.js

@@ -282,6 +282,23 @@ export function keepaliveHint(message = '', proxyUrl = '') {
  * @param status - 探测收到的 HTTP 状态码。
  * @returns `{ ok, verdict, kind, status, short, why, fix }`（中文文案）。
  */
+/**
+ * HEAD 结论不可信、必须换 GET 复测的状态码。
+ *
+ * 405/501 是服务器明说「不支持该方法」；**404 同样是陷阱**：很多网关不给
+ * HEAD 注册路由，对 HEAD 一律回 404，而同一路径 GET 会正常回 401/200 ——
+ * 实测 DashScope：`HEAD /compatible-mode/v1/models` → 404，同路径 GET → 401
+ * （2026-09-18 用户报「测什么都 404」时定位）。不复测就会把健康端点误判成
+ * 「路径不存在」。
+ *
+ * @param status - HEAD 探测收到的状态码。
+ * @returns 是否需要用 GET 复测。
+ */
+export function headNeedsGetRetry(status) {
+  const code = Number(status)
+  return code === 404 || code === 405 || code === 501
+}
+
 export function classifyProbeStatus(status) {
   const code = Number(status)
   const base = { status: code }
@@ -305,8 +322,8 @@ export function classifyProbeStatus(status) {
   }
   if (code === 404) {
     return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: 'HTTP 404 — 路径不存在',
-      why: '路由已到服务器，但该路径不存在（探测常打根路径）。',
-      fix: '用真实调用的完整路径复测；能通就忽略此结果。' }
+      why: 'HEAD 与 GET 都拿到了 404：路由已到服务器，但该路径确实没有资源（探测常打根路径或裸前缀）。',
+      fix: '改用真实调用的完整端点复测（如 .../models、.../chat/completions）；那里有响应就说明主机可用。' }
   }
   if (code === 405 || code === 501) {
     return { ...base, ok: false, verdict: 'degraded', kind: 'http-error', short: `HTTP ${code} — 端点不支持 HEAD`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanglaofish/dsh-proxy-pro",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "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",