dsh-kylin-media 0.2.0 → 0.2.1

package/README.md

@@ -66,6 +66,8 @@ npm publish          # prepack 会自动跑 smoke
 > 1. `127.0.0.1` / `localhost` 只有**网关和插件跑在同一台机器**时才通。网关在远端（例如 Windows 主机）而插件在 Mac 上时，本机地址必然被拒绝。
 > 2. 局域网地址要求两者**在同一网段**，且网关监听 `HOST=0.0.0.0`（默认）、系统防火墙放行 8288（仓库里有 `add-firewall-rule.bat`）。可先用 `curl http://<主机IP>:8288/api/health` 验证。
 > 3. 上面两条都不满足时只能用 frp / 公网地址。把三条地址都加进「连接线路」，点「全部测速」即可看出哪条通、哪条最快；失败原因直接写在行内（拒绝连接 / 不可达 / 域名解析失败 / 协议写反）。
+>
+> 局域网里偶发 `EHOSTUNREACH`（刚唤醒、Wi-Fi 切换、ARP 未就绪）不用管：所有 GET 探测都会自动重试最多 2 次；仍失败时先在本机 `curl http://<主机IP>:8288/api/health` 复核。
 
 ## 工具
 

package/client.js

@@ -55,6 +55,7 @@ window.__ModuleLoader__.load({
       lineExists: '这个地址已经在列表里了',
       lineKeepOne: '至少要保留一条线路',
       noLineReachable: '所有线路都不通：检查网关是否运行、地址/端口是否正确、防火墙是否放行',
+      localNetworkHint: '（局域网目标全部 EHOSTUNREACH：多为 macOS「本地网络」权限拦截——去 系统设置 → 隐私与安全性 → 本地网络 放行本 App 后重试）',
       fastestLine: '最快线路：',
       saved: '已保存',
       failed: '操作失败：',
@@ -150,6 +151,7 @@ window.__ModuleLoader__.load({
       lineExists: 'That address is already in the list',
       lineKeepOne: 'Keep at least one line',
       noLineReachable: 'No line is reachable: check the gateway process, address/port and firewall',
+      localNetworkHint: ' (every LAN target returns EHOSTUNREACH: usually macOS Local Network privacy - allow this app in System Settings > Privacy & Security > Local Network, then retry)',
       fastestLine: 'Fastest line: ',
       saved: 'Saved',
       failed: 'Operation failed: ',
@@ -484,8 +486,14 @@ window.__ModuleLoader__.load({
             if (result.reachable && (best === null || result.latencyMs < best.latencyMs)) best = result;
           }
           setLineResults(next);
-          if (best === null) setNotice({ kind: 'error', text: t('noLineReachable') });
-          else setNotice({ kind: 'ok', text: t('fastestLine') + best.name + ' · ' + String(best.latencyMs) + 'ms' });
+          if (best === null) {
+            var blocked = false;
+            for (var check = 0; check < payload.value.results.length; check += 1) {
+              var failed = payload.value.results[check];
+              if (failed.reachable === false && failed.error && /EHOSTUNREACH/.test(String(failed.error.message))) blocked = true;
+            }
+            setNotice({ kind: 'error', text: t('noLineReachable') + (blocked ? t('localNetworkHint') : '') });
+          } else setNotice({ kind: 'ok', text: t('fastestLine') + best.name + ' · ' + String(best.latencyMs) + 'ms' });
         }).catch(function (error) {
           setNotice({ kind: 'error', text: t('failed') + (error && error.message ? error.message : String(error)) });
         }).then(function () {

package/entry.js

@@ -17,7 +17,7 @@ import { createTools } from './lib/tools.js'
 
 export const name = 'dsh-kylin-media'
 export const inject = ['tools', 'webServer']
-export const VERSION = '0.2.0'
+export const VERSION = '0.2.1'
 
 const ROOT = dirname(fileURLToPath(import.meta.url))
 const SKILLS_DIR = join(ROOT, 'skills')

package/lib/gateway.js

@@ -112,7 +112,10 @@ function reachabilityHint(base, detail) {
     return '。目标拒绝连接：确认网关进程在运行、端口正确，并已放行防火墙'
   }
   if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/i.test(detail)) return '。域名解析失败：检查地址拼写或 DNS'
-  if (/EHOSTUNREACH|ENETUNREACH|ETIMEDOUT|timed out|timeout/i.test(detail)) return '。地址不可达：确认与网关在同一网络，Windows 防火墙已放行该端口'
+  if (/EHOSTUNREACH|ENETUNREACH/i.test(detail)) {
+    return '。链路层没通：目标在同一局域网时，先在 macOS「系统设置 → 隐私与安全性 → 本地网络」放行本 App（被拦时就是 EHOSTUNREACH）；其次看网关主机是否休眠、刚切过 Wi-Fi 或 ARP 未就绪，隔几秒重试。可在终端 curl ' + base + '/api/health 复核'
+  }
+  if (/ETIMEDOUT|timed out|timeout/i.test(detail)) return '。SYN 没响应：多半是防火墙丢包（Windows 入站规则要放行该端口），或两台机器不在同一网段'
   return ''
 }
 
@@ -143,41 +146,59 @@ export function createGateway(settings) {
     return headers
   }
 
+  /** 刚唤醒 / Wi-Fi 切换 / ARP 未就绪时的瞬时失败，重试就能过去。 */
+  function isTransient(detail) {
+    return /EHOSTUNREACH|ENETUNREACH|ECONNRESET|EPIPE|EAI_AGAIN|socket hang up/i.test(detail)
+  }
+
   async function request(path, options) {
     const opts = options === undefined ? {} : options
+    const method = opts.method || 'GET'
     const timeoutMs = opts.timeoutMs === undefined ? defaultTimeout : opts.timeoutMs
-    const combined = combineSignal(opts.signal, timeoutMs)
-    try {
-      const response = await fetch(base + path, {
-        method: opts.method || 'GET',
-        headers: opts.headers || authHeaders({}),
-        body: opts.body,
-        signal: combined.signal
-      })
-      const text = await response.text()
-      let payload = null
-      if (text !== '') {
-        try {
-          payload = JSON.parse(text)
-        } catch {
-          payload = null
+    // 只重试幂等的 GET/HEAD；POST 可能已经在网关侧建了任务，绝不重放。
+    const attempts = method === 'GET' || method === 'HEAD' ? 3 : 1
+    let lastError = null
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      const combined = combineSignal(opts.signal, timeoutMs)
+      try {
+        const response = await fetch(base + path, {
+          method,
+          headers: opts.headers || authHeaders({}),
+          body: opts.body,
+          signal: combined.signal
+        })
+        const text = await response.text()
+        let payload = null
+        if (text !== '') {
+          try {
+            payload = JSON.parse(text)
+          } catch {
+            payload = null
+          }
         }
+        if (!response.ok || (isRecord(payload) && payload['ok'] === false)) {
+          throw failForStatus(response.status, payload, text)
+        }
+        return payload
+      } catch (error) {
+        if (error instanceof GatewayError) throw error
+        if (opts.signal !== undefined && opts.signal !== null && opts.signal.aborted) throw error
+        if (combined.timedOut()) {
+          throw new GatewayError('timeout', '请求网关超时（' + String(timeoutMs) + 'ms）：' + base + reachabilityHint(base, 'ETIMEDOUT'), 0, null)
+        }
+        const detail = describeCause(error)
+        const retryNote = attempt < attempts && isTransient(detail) ? '' : (attempts > 1 && isTransient(detail) ? '（已自动重试 ' + String(attempts - 1) + ' 次）' : '')
+        lastError = new GatewayError('gateway-unreachable', '无法连接网关 ' + base + '：' + detail + reachabilityHint(base, detail) + retryNote, 0, null)
+        if (attempt < attempts && isTransient(detail)) {
+          await new Promise(function (resolve) { setTimeout(resolve, 250 * attempt) })
+          continue
+        }
+        throw lastError
+      } finally {
+        combined.close()
       }
-      if (!response.ok || (isRecord(payload) && payload['ok'] === false)) {
-        throw failForStatus(response.status, payload, text)
-      }
-      return payload
-    } catch (error) {
-      if (error instanceof GatewayError) throw error
-      if (opts.signal !== undefined && opts.signal !== null && opts.signal.aborted) throw error
-      if (combined.timedOut()) {
-        throw new GatewayError('timeout', '请求网关超时（' + String(timeoutMs) + 'ms）：' + base + reachabilityHint(base, 'ETIMEDOUT'), 0, null)
-      }
-      const detail = describeCause(error)
-      throw new GatewayError('gateway-unreachable', '无法连接网关 ' + base + '：' + detail + reachabilityHint(base, detail), 0, null)
-    } finally {
-      combined.close()
     }
+    throw lastError
   }
 
   async function health() {

package/lib/routes.js

@@ -171,7 +171,7 @@ export async function handleRequest(store, request, body) {
   if (!pathname.startsWith(API_PREFIX)) return undefined
   const action = pathname.slice(API_PREFIX.length).replace(/^\/+/, '')
   if (method === 'GET' && action === 'state') {
-    return { status: 200, payload: { ok: true, value: { ...store.publicState(), name: PLUGIN_NAME, version: '0.2.0' } } }
+    return { status: 200, payload: { ok: true, value: { ...store.publicState(), name: PLUGIN_NAME, version: '0.2.1' } } }
   }
   if (method !== 'POST') {
     return { status: 405, payload: errorPayload('method-not-allowed', '写操作必须使用 POST') }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-kylin-media",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "麒麟（QiLin）/ DSH 多媒体网关插件：连接本地 comfyui-gateway，在会话里出图、出视频、出音乐、对口型，并做语音转写、合成与分离。",
   "keywords": [
     "deepseek-harness",

package/scripts/client-test.mjs

@@ -166,7 +166,7 @@ function respond(action, options) {
         latencyMs: reachable ? 18 : 3,
         gateway: reachable ? { version: '0.3.0', authMode: 'always' } : null,
         comfy: reachable ? { reachable: true, upstreams: 2 } : null,
-        error: reachable ? null : { code: 'connection-refused', message: '本机没有服务监听' }
+        error: reachable ? null : { code: 'gateway-unreachable', message: '无法连接网关：EHOSTUNREACH connect EHOSTUNREACH' }
       }
     }) } }
   }
@@ -324,6 +324,14 @@ const statuses = findAll(render(), function (node) {
   return typeof node.props.className === 'string' && node.props.className.indexOf('km-line-status') >= 0
 }).map(textOf)
 check(statuses.indexOf('18ms') >= 0 && statuses.indexOf('lineFailed') >= 0, 'test all renders per-line latency and failure')
+// 全部线路都 EHOSTUNREACH 时给出 macOS 本地网络权限提示
+const savedLineList = STATE.endpoints
+STATE.endpoints = [{ id: 'local', name: '127.0.0.1:8288', baseUrl: 'http://127.0.0.1:8288' }]
+const onlyLocalButton = findAll(render(), function (node) { return node.type === 'button' && textOf(node) === 'lineTestAll' })[0]
+onlyLocalButton.props.onClick()
+await settle()
+check(textOf(render()).includes('localNetworkHint'), 'all-EHOSTUNREACH lines surface the macOS local-network hint')
+STATE.endpoints = savedLineList
 
 const urlInput = findAll(render(), function (node) { return node.props.id === 'km-base-url' })[0]
 urlInput.props.onChange({ target: { value: 'http://192.168.1.5:8288' } })

package/scripts/selftest.mjs

@@ -130,6 +130,45 @@ await new Promise(function (resolve) { server.listen(0, '127.0.0.1', resolve) })
 const port = server.address().port
 const baseUrl = 'http://127.0.0.1:' + String(port)
 
+// GET 自动重试：瞬时 EHOSTUNREACH（刚唤醒 / ARP 未就绪）重试后应成功；一直失败时给出已重试次数
+const { createGateway } = await import(new URL('../lib/gateway.js', import.meta.url))
+function hostUnreachable() {
+  const error = new TypeError('fetch failed')
+  const cause = new Error('connect EHOSTUNREACH 192.168.1.71:8288')
+  cause.code = 'EHOSTUNREACH'
+  error.cause = cause
+  return error
+}
+const originalFetch = globalThis.fetch
+let flakyCalls = 0
+globalThis.fetch = async function (url, init) {
+  flakyCalls += 1
+  if (flakyCalls === 1) throw hostUnreachable()
+  return originalFetch(url, init)
+}
+try {
+  const flakyHealth = await createGateway({ baseUrl, apiKey: KEY, requestTimeoutMs: 5000 }).health()
+  check(flakyHealth.version === '0.3.0', 'a transient EHOSTUNREACH is retried and then succeeds')
+} finally {
+  globalThis.fetch = originalFetch
+}
+check(flakyCalls === 2, 'the transient GET was retried exactly once')
+
+let downCalls = 0
+globalThis.fetch = async function () {
+  downCalls += 1
+  throw hostUnreachable()
+}
+try {
+  await createGateway({ baseUrl, apiKey: KEY, requestTimeoutMs: 5000 }).health()
+  check(false, 'a permanently unreachable gateway should fail')
+} catch (error) {
+  check(error.message.includes('已自动重试 2 次'), 'exhausted retries are reported in the message')
+} finally {
+  globalThis.fetch = originalFetch
+}
+check(downCalls === 3, 'a GET is attempted three times before failing')
+
 const store = new MediaStore(HOME)
 let result = store.update({ baseUrl, waitSeconds: 10, pollIntervalMs: 500, requestTimeoutMs: 5000, autoDownload: true })
 check(result.ok, 'store.update accepts valid settings')