@noob-stupid/dsh-plugin-console 0.5.46 → 0.5.48

package/lib/server/infra/http.js

@@ -1,10 +1,18 @@
 // 由 Step 1 搬运工具从 lib/index.js 原样切出（只移动、未改逻辑）
 // 分层分组：L0 · infra（边界由 tests/test-architecture-guard.mjs 断言）
 
-import { execFile } from 'node:child_process'
+// ★ 出网/起进程的唯一出口（0.5.47 接线）：本文件的每条网络/进程通道都是 infra/egress.js
+// makeEgress 造出来的**包装**（stub 优先 → 计数 → 真实现）。单测 `__setEgressStub({…})`
+// 注入替身之后，`egressStatsNow()` 能如实证明"0 次真实出网、0 次真实 spawn"——上一批那种
+// "给 node:child_process 命名空间打补丁 + 读 globalThis 空标志"的假守卫已废（ESM 下也打不上）。
+// ★ 连 `node:https` 的请求原语也不在本文件（在 egress.js）：于是"只有 egress.js 认识
+// node:https / node:child_process"是**静态可判**的（tests/test-repo-manifest-channels.mjs 钉死），
+// 而不是靠注释约定。本文件只留"怎么用"（协议/重试/竞速）。
+import { execFile as nodeExecFile } from 'node:child_process'
+import { promisify } from 'node:util'
 import { resolve } from 'node:path'
-import { request as httpsRequest } from 'node:https'
-import { GH_BIN_CANDIDATES, execFileAsync } from './exec.js'
+import { GH_BIN_CANDIDATES } from './exec.js'
+import { __setEgressRealImpl, egressHttpsRequestOnce, makeEgress } from './egress.js'
 
 /** 单次 https 请求；卡死的连接会在超时后被销毁。 */
 
@@ -38,9 +46,14 @@ import { GH_BIN_CANDIDATES, execFileAsync } from './exec.js'
 
 /** raw.githubusercontent.com 的镜像竞速前缀（与浏览器端四通道一致）。 */
 
-function githubRequestOnce(url, { signal, accept, token, timeout = 20000 } = {}) {
+// ── 出网单点的**真实现**（0.5.47）────────────────────────────────────────────────────
+// 下面这一块是本文件里**唯一**碰 node 进程/网络原语的地方（另一处是 egress.js）。对外导出的
+// 同名函数则是 egress 包装：stub 优先 → 记一笔 → 回到这里。`__setEgressRealImpl` 把真实现登记给
+// egress，于是"生产到底接上没有"是**可断言的**（egress 的 gaps 会列出被登记过的出口名），
+// 不靠读代码猜 —— 上一批的教训正是"加了文件但没人 import"。
+function githubRequestOnceReal(url, { signal, accept, token, timeout = 20000 } = {}) {
   return new Promise((resolve, reject) => {
-    const req = httpsRequest(url, {
+    const req = egressHttpsRequestOnce(url, {
       method: 'GET',
       headers: {
         'user-agent': GITHUB_UA,
@@ -59,6 +72,84 @@ function githubRequestOnce(url, { signal, accept, token, timeout = 20000 } = {})
     }
   })
 }
+function httpsRequestReal(url, options) {
+  return egressHttpsRequestOnce(url, options)
+}
+const execFileAsyncReal = promisify(nodeExecFile)
+async function githubViaGhReal(apiPath, token = null) {
+  // 环境变量而不是命令行参数：token 不能出现在进程命令行（同机其他进程可见）
+  const env = token === null ? undefined : { ...process.env, GH_TOKEN: token, GITHUB_TOKEN: token }
+  let lastError = null
+  for (const bin of GH_BIN_CANDIDATES) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const { stdout } = await execFileAsyncReal(bin, ['api', apiPath, '--jq', '.'], { windowsHide: true, timeout: 45000, maxBuffer: 8 * 1024 * 1024, ...(env === undefined ? {} : { env }) })
+      try {
+        return JSON.parse(stdout)
+      } catch {
+        throw new Error('gh api 兜底返回的不是合法 JSON')
+      }
+    } catch (error) {
+      lastError = error
+      // ENOENT = 该路径不存在，继续下一个候选；其他错误（网络/认证）直接失败
+      if (error?.code === 'ENOENT') continue
+      throw new Error(`gh api 兜底失败：${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  throw new Error(lastError?.code === 'ENOENT'
+    ? 'gh api 兜底失败：未找到 gh CLI'
+    : `gh api 兜底失败：${lastError instanceof Error ? lastError.message : String(lastError)}`)
+}
+async function curlJsonReal(url, timeout = 15000, headers = {}, { ipv4 = false } = {}) {
+  const bin = process.platform === 'win32' ? 'curl.exe' : 'curl'
+  const args = ['-s', '-m', String(Math.max(5, Math.ceil(timeout / 1000))), '-H', 'accept: application/json', '-w', '\n__HTTP__%{http_code}']
+  // ipv4：只给 GitHub 域名用——「解析出 IPv6 但没有 IPv6 路由」的环境里 curl 默认要先空等 ~5.2s 才回退
+  // IPv4（2026-09-20 另一位用户实测：默认 5473ms vs `-4` 的 461ms）；双栈正常的环境无副作用。
+  if (ipv4) args.push('-4')
+  for (const [key, value] of Object.entries(headers)) args.push('-H', `${key}: ${value}`)
+  args.push(url)
+  const { stdout } = await execFileAsyncReal(bin, args, { timeout: timeout + 3000, windowsHide: true, maxBuffer: 8 * 1024 * 1024 })
+  const m = String(stdout).match(/\n__HTTP__(\d+)\s*$/u)
+  const code = m ? Number(m[1]) : 0
+  const body = m ? String(stdout).slice(0, m.index) : String(stdout)
+  if (code !== 0 && (code < 200 || code >= 300)) throw new Error(`请求失败 (HTTP ${code})`)
+  return JSON.parse(body)
+}
+async function curlTextReal(url, timeout = 10000, { ipv4 = false } = {}) {
+  const bin = process.platform === 'win32' ? 'curl.exe' : 'curl'
+  const args = ['-s', '-m', String(Math.max(3, Math.ceil(timeout / 1000))), '-H', 'accept: text/plain', '-w', '\n__HTTP__%{http_code}']
+  // 见 curlJson 注释：GitHub 域名走 IPv4 快通道（IPv6 无路由的环境下默认要白等 ~5.2s）
+  if (ipv4) args.push('-4')
+  args.push(url)
+  const { stdout } = await execFileAsyncReal(
+    bin,
+    args,
+    { timeout: timeout + 3000, windowsHide: true, maxBuffer: 8 * 1024 * 1024 },
+  )
+  const m = String(stdout).match(/\n__HTTP__(\d+)\s*$/u)
+  const code = m ? Number(m[1]) : 0
+  const body = m ? String(stdout).slice(0, m.index) : String(stdout)
+  if (code !== 0 && (code < 200 || code >= 300)) throw new Error(`HTTP ${code}`)
+  return body
+}
+
+// ── 对外导出的出网出口 = egress 包装（stub 优先 → 计数 → 真实现）──────────────────────
+const githubRequestOnce = makeEgress('httpsRequestOnce', 'network')
+const httpsRequest = makeEgress('httpsRequest', 'network')
+const githubViaGh = makeEgress('githubViaGh', 'spawn')
+const curlJson = makeEgress('curlJson', 'spawn')
+const curlText = makeEgress('curlText', 'spawn')
+
+/** 登记真实现（**方向单向**：egress 不 import 本文件，避免 infra 内部成环）。 */
+__setEgressRealImpl({
+  httpsRequestOnce: githubRequestOnceReal,
+  httpsRequest: httpsRequestReal,
+  execFileAsync: execFileAsyncReal,
+  githubViaGh: githubViaGhReal,
+  curlJson: curlJsonReal,
+  curlText: curlTextReal,
+})
+
 function raceFirst2xx(promises) {
   return new Promise((resolve, reject) => {
     let pending = promises.length
@@ -127,36 +218,8 @@ function collectBody(res) {
 }
 /** gh CLI 通道。传 token 时用 GH_TOKEN/GITHUB_TOKEN 环境变量**覆盖 gh 的 keyring 凭据** ——
  * 这是"校验某个 token 是否有效"时唯一安全的用法：否则 gh 会拿本机已登录的身份作答，
- * 一个填错的 token 也会"验证成功"（详见 routes/github-login.js 的说明）。 */
-function githubViaGh(apiPath, token = null) {
-  // 环境变量而不是命令行参数：token 不能出现在进程命令行（同机其他进程可见）
-  const env = token === null ? undefined : { ...process.env, GH_TOKEN: token, GITHUB_TOKEN: token }
-  return new Promise((resolve, reject) => {
-    const attempt = (index) => {
-      if (index >= GH_BIN_CANDIDATES.length) {
-        reject(new Error('gh api 兜底失败：未找到 gh CLI'))
-        return
-      }
-      execFile(GH_BIN_CANDIDATES[index], ['api', apiPath, '--jq', '.'], { windowsHide: true, timeout: 45000, maxBuffer: 8 * 1024 * 1024, ...(env === undefined ? {} : { env }) }, (error, stdout) => {
-        if (error) {
-          // ENOENT = 该路径不存在，继续下一个候选；其他错误（网络/认证）直接失败
-          if (error.code === 'ENOENT') {
-            attempt(index + 1)
-            return
-          }
-          reject(new Error(`gh api 兜底失败：${error.message}`))
-          return
-        }
-        try {
-          resolve(JSON.parse(stdout))
-        } catch {
-          reject(new Error('gh api 兜底返回的不是合法 JSON'))
-        }
-      })
-    }
-    attempt(0)
-  })
-}
+ * 一个填错的 token 也会"验证成功"（详见 routes/github-login.js 的说明）。
+ * 真实现见上面的 githubViaGhReal；这里往下都是**组合逻辑**（竞速/兜底），不再直接碰进程。 */
 async function githubJson(url, signal, token = null) {
   const apiPath = url.startsWith(GITHUB_API) ? url.slice(GITHUB_API.length) : null
   // https 主通道（官方重试+镜像并行）与 gh CLI **并行竞速**：黑洞期 gh 秒回，不再等 https 超时
@@ -193,38 +256,6 @@ async function githubText(url, signal, token = null) {
   if (status < 200 || status >= 300) return null
   return body
 }
-async function curlJson(url, timeout = 15000, headers = {}, { ipv4 = false } = {}) {
-  const bin = process.platform === 'win32' ? 'curl.exe' : 'curl'
-  const args = ['-s', '-m', String(Math.max(5, Math.ceil(timeout / 1000))), '-H', 'accept: application/json', '-w', '\n__HTTP__%{http_code}']
-  // ipv4：只给 GitHub 域名用——「解析出 IPv6 但没有 IPv6 路由」的环境里 curl 默认要先空等 ~5.2s 才回退
-  // IPv4（2026-09-20 另一位用户实测：默认 5473ms vs `-4` 的 461ms）；双栈正常的环境无副作用。
-  if (ipv4) args.push('-4')
-  for (const [key, value] of Object.entries(headers)) args.push('-H', `${key}: ${value}`)
-  args.push(url)
-  const { stdout } = await execFileAsync(bin, args, { timeout: timeout + 3000, windowsHide: true, maxBuffer: 8 * 1024 * 1024 })
-  const m = String(stdout).match(/\n__HTTP__(\d+)\s*$/u)
-  const code = m ? Number(m[1]) : 0
-  const body = m ? String(stdout).slice(0, m.index) : String(stdout)
-  if (code !== 0 && (code < 200 || code >= 300)) throw new Error(`请求失败 (HTTP ${code})`)
-  return JSON.parse(body)
-}
-async function curlText(url, timeout = 10000, { ipv4 = false } = {}) {
-  const bin = process.platform === 'win32' ? 'curl.exe' : 'curl'
-  const args = ['-s', '-m', String(Math.max(3, Math.ceil(timeout / 1000))), '-H', 'accept: text/plain', '-w', '\n__HTTP__%{http_code}']
-  // 见 curlJson 注释：GitHub 域名走 IPv4 快通道（IPv6 无路由的环境下默认要白等 ~5.2s）
-  if (ipv4) args.push('-4')
-  args.push(url)
-  const { stdout } = await execFileAsync(
-    bin,
-    args,
-    { timeout: timeout + 3000, windowsHide: true, maxBuffer: 8 * 1024 * 1024 },
-  )
-  const m = String(stdout).match(/\n__HTTP__(\d+)\s*$/u)
-  const code = m ? Number(m[1]) : 0
-  const body = m ? String(stdout).slice(0, m.index) : String(stdout)
-  if (code !== 0 && (code < 200 || code >= 300)) throw new Error(`HTTP ${code}`)
-  return body
-}
 async function fetchJsonUrl(url, timeout = 15000, headers = {}) {
   let lastError
   const isHttps = /^https:\/\//u.test(url)
@@ -241,7 +272,8 @@ async function fetchJsonUrl(url, timeout = 15000, headers = {}) {
     // 否则会抛出 "Protocol http: not supported" 掩盖 curl 的真实连接错误
     if (!isHttps) continue
     try {
-      const res = await githubRequest(url, { headers })
+      // 走 egress 包装（不是上面的真实现）：单测注入替身后这条兜底也发不出去
+      const res = await httpsRequest(url, { headers })
       const status = res.statusCode ?? 0
       const body = await collectBody(res)
       if (status < 200 || status >= 300) throw new Error(`请求失败 (HTTP ${status})`)
@@ -279,61 +311,14 @@ const FETCH_OK = 'ok'
 const FETCH_NOT_FOUND = 'not-found'
 const FETCH_UNREACHABLE = 'unreachable'
 
-/** 竞速组合（纯逻辑，导出供单测）：通道结果 + 预算 → { state, body }。
- * · anyPromise 以 null 成功 = 某通道确定性 404 → not-found
- * · anyPromise 以字符串成功 = 读到内容 → ok
- * · anyPromise 全部失败（AggregateError）或超出预算 → unreachable（**不再与 404 混为一谈**） */
-function raceFetchOutcome(anyPromise, budgetMs) {
-  const settled = Promise.resolve(anyPromise)
-    .then((body) => (body === null ? { state: FETCH_NOT_FOUND, body: null } : { state: FETCH_OK, body }))
-    .catch(() => ({ state: FETCH_UNREACHABLE, body: null }))
-  return Promise.race([
-    settled,
-    new Promise((resolve) => setTimeout(() => resolve({ state: FETCH_UNREACHABLE, body: null }), budgetMs)),
-  ])
-}
+// 旧的 raceFetchOutcome(anyPromise, budgetMs) 已被下面的通道版取代（胜出通道 + 逐条失败原因）。
 
-/** raw 抓取（带状态）：返回 { state, body }。state 区分「确定性 404」与「超时/全部通道不可达」——
- * 二者都以"没内容"结束，但给用户看的文案必须不同（否则永远误报"文件不存在"，误导排查方向）。 */
-async function rawTextFetch(repo, branch, path, budgetMs = FETCH_BUDGET_MS) {
-  const url = `${GITHUB_RAW}/${repo}/${encodeURIComponent(branch)}/${path}`
-  // 404/4xx：确定性"不存在"，立即以 null 胜出（不等慢分支）
-  const notFound = (promise) => promise
-    .catch((error) => {
-      if (error instanceof Error && /HTTP 404|HTTP 400|Not Found|not found|非 2xx|HTTP 非 2xx/u.test(error.message)) return null
-      throw error
-    })
-  // 各通道统一口径：状态 2xx **且** body 非空白，才算读到文件（否则抛"非 2xx"→ 归一为 null）
-  const real = (promise) => promise.then((body) => {
-    const text = readBodyOrNull(body)
-    if (text === null) throw new Error('HTTP 非 2xx')
-    return text
-  })
-  const https = notFound(real(githubText(url)))
-  const gh = notFound(githubViaGh(`repos/${repo}/contents/${path}?ref=${encodeURIComponent(branch)}`)
-    .then((data) => {
-      if (data && typeof data.content === 'string') return Buffer.from(data.content, 'base64').toString('utf8')
-      throw new Error('contents 无内容')
-    })
-    .then((text) => {
-      const body = readBodyOrNull(text)
-      if (body === null) throw new Error('contents 无内容')
-      return body
-    }))
-  const curl = notFound(real(curlText(url, 9000, { ipv4: true })))
-  const cdn = notFound(real(curlText(`https://cdn.jsdelivr.net/gh/${repo}@${encodeURIComponent(branch)}/${path}`, 9000, { ipv4: true })))
-  return await raceFetchOutcome(Promise.any([https, gh, curl, cdn]), budgetMs)
-}
+// 旧的 rawTextFetch/rawTextWithFallback 已被下面的通道版取代（四条既有通道一条不删）。
 
-/** 兼容入口：调用方只关心"有没有内容"（null = 没有）。需要区分超时/404 的场景用 rawTextFetch。 */
-async function rawTextWithFallback(repo, branch, path) {
-  const { state, body } = await rawTextFetch(repo, branch, path)
-  return state === FETCH_OK ? body : null
-}
 function postJsonUrl(url, formBody) {
   return new Promise((resolve, reject) => {
     const body = new URLSearchParams(formBody).toString()
-    const req = httpsRequest(url, {
+    const req = httpsRequestReal(url, {
       method: 'POST',
       headers: {
         'content-type': 'application/x-www-form-urlencoded',
@@ -370,4 +355,163 @@ const RAW_MIRROR_PREFIXES = [
   'https://ghproxy.net/https://raw.githubusercontent.com',
   'https://ghfast.top/https://raw.githubusercontent.com',
 ]
-export { githubRequestOnce, raceFirst2xx, githubRequest, collectBody, githubViaGh, githubJson, githubText, curlJson, curlText, fetchJsonUrl, rawTextWithFallback, rawTextFetch, raceFetchOutcome, readBodyOrNull, looksLikeGitmodules, postJsonUrl, GITHUB_API, GITHUB_RAW, GITHUB_UA, API_MIRROR_PREFIXES, RAW_MIRROR_PREFIXES, FETCH_BUDGET_MS, META_BUDGET_MS, FETCH_OK, FETCH_NOT_FOUND, FETCH_UNREACHABLE }
+// ── 通道身份 + 逐通道失败原因（2026-10-13 加法）─────────────────────────────────
+// 缺口：Promise.any 只把**胜出者**当返回值，胜出的是哪条通道被丢弃；全失败时 AggregateError
+// 被 catch 成一句 unreachable —— 用户看到的只有"抓取超时"，**看不到哪几条通道试过、各自为什么没成**，
+// 于是无从判断该修网络、该换源，还是该等一会儿重试。下面把两样都带出来。
+//
+// 关键性能约束（与旧行为逐字一致）：**成功必须早返回** —— 旧代码 curl 400ms 赢时不会去等
+// node:https 的 20s 超时；所以这里用"首个成功即解析"的 race，只有**全部失败**时才收齐全量原因
+// （那时本来就要等到预算耗尽）。
+const CHANNEL_LABELS = {
+  local: '本地落地',
+  https: 'https（GitHub 主通道/镜像竞速）',
+  gh: 'gh CLI',
+  curl: 'curl 直连',
+  jsdelivr: 'jsDelivr CDN',
+  'npm-mirror': 'npm 镜像（npmmirror）',
+  'npm-official': 'npm 官方源（registry.npmjs.org）',
+  budget: '总预算',
+}
+/** 通道 id → 用户可读名（未知 id 原样返回，绝不显示空标签）。 */
+function channelLabel(id) {
+  return CHANNEL_LABELS[String(id ?? '')] ?? String(id ?? '未知通道')
+}
+/** 失败原因归一：超时/HTTP 状态/网络原话，取最短且可读的一句（保留原始 error.message 关键片段）。 */
+function compactFailReason(error) {
+  const message = error instanceof Error ? error.message : String(error ?? '失败')
+  const text = message.replace(/\s+/gu, ' ').trim()
+  if (text === '') return '失败（无原因）'
+  if (/timed out|timeout|超时|ETIMEDOUT|too slow/iu.test(text)) return `超时（${text.slice(0, 80)}）`
+  if (/^(HTTP \d+|请求失败 \(HTTP \d+\))/u.test(text)) return text
+  return text.slice(0, 120)
+}
+/** 各通道结果 → 逐条「通道名：原因」清单（供用户可读报错；顺序即探测顺序，可追溯）。 */
+function channelFailureLines(failures) {
+  const list = Array.isArray(failures) ? failures : []
+  return list.filter((f) => f !== null && typeof f === 'object').map((f) => {
+    const reason = typeof f.reason === 'string' && f.reason !== '' ? f.reason : '失败（无原因）'
+    return `· ${channelLabel(f.id)}：${typeof f.detail === 'string' && f.detail !== '' ? `${reason} —— ${f.detail}` : reason}`
+  })
+}
+/** 逐通道原因清单文本（空列表 → 空串，调用方据此决定要不要加这段）。 */
+function channelFailureSummary(failures) {
+  const lines = channelFailureLines(failures)
+  return lines.length === 0 ? '' : lines.join('\n')
+}
+
+/** 竞速组合（纯逻辑，导出供单测）：通道描述数组 + 预算 → `{ state, body, channel, failures }`。
+ * · 某通道返回 null（确定性 404）→ 立刻 not-found（旧语义：不等慢分支）
+ * · 某通道返回字符串（2xx 且内容非空白）→ 立刻 ok，并带出**胜出通道 id**
+ * · 全部失败 / 超出预算 → unreachable，且 `failures` **逐条**列出每条通道各自的原因
+ * 成败的判定权仍在通道自己（它们已按 notFound/real 归一成 null/string/throw）。
+ * **向后兼容**：旧形态 `raceFetchOutcome(promise, budgetMs)`（单个 Promise 竞速）仍然可用 ——
+ * 单测与老调用点一个字都不用改，只是它现在也会带上 channel/failures。 */
+function raceFetchOutcome(input, legacyBudgetMs) {
+  const isObjectForm = input !== null && typeof input === 'object' && !Array.isArray(input)
+    && (Array.isArray(input.channels) || typeof input.channels !== 'undefined')
+  const channels = isObjectForm ? (input.channels ?? []) : [input]
+  const deps = isObjectForm ? (input.deps ?? {}) : {}
+  const timeoutMs = Number.isFinite(isObjectForm ? input.timeoutMs : legacyBudgetMs) ? (isObjectForm ? input.timeoutMs : legacyBudgetMs) : FETCH_BUDGET_MS
+  const setTimer = deps.setTimeout ?? setTimeout
+  const list = (Array.isArray(channels) ? channels : [channels])
+    // 旧形态：单个 Promise / 值，包成一条通道（默认 id 沿用最老的那条 'https'，语义不变）
+    .map((ch, index) => (ch !== null && typeof ch === 'object' && typeof ch?.run === 'function'
+      ? ch
+      : { id: `channel-${index}`, label: channelLabel(`channel-${index}`), run: () => (typeof ch?.then === 'function' ? ch : Promise.resolve(ch)) }))
+  if (list.length === 0) return Promise.resolve({ state: FETCH_UNREACHABLE, body: null, channel: null, failures: [] })
+  // 每条通道**只启动一次**：raw[index] 同时是"结果"与"该通道已了结"的标记（null = 还在等）。
+  const raw = new Array(list.length).fill(null)
+  let settled = false
+  let pending = list.length
+  return new Promise((resolve) => {
+    const done = (outcome) => { if (!settled) { settled = true; resolve(outcome) } }
+    const failuresOf = () => raw.map((entry, index) => (entry === null
+      ? { id: list[index].id ?? `channel-${index}`, label: channelLabel(list[index].id), reason: '预算内未返回（超时/仍在等待）', state: FETCH_UNREACHABLE, detail: '' }
+      : { id: list[index].id ?? `channel-${index}`, label: entry.label, reason: entry.reason, state: entry.state, detail: entry.detail ?? '' }))
+    const settleOne = (index, body) => {
+      const label = list[index].label ?? channelLabel(list[index].id)
+      raw[index] = { state: body === null ? FETCH_NOT_FOUND : FETCH_OK, reason: '', detail: '', label }
+      pending -= 1
+      // ★ 胜出通道与"当时已知的其余通道失败原因"一起带出（确定性 404 同样立即胜出，不等慢分支）
+      done(body === null
+        ? { state: FETCH_NOT_FOUND, body: null, channel: list[index].id ?? `channel-${index}`, failures: failuresOf() }
+        : { state: FETCH_OK, body, channel: list[index].id ?? `channel-${index}`, failures: failuresOf() })
+    }
+    const failOne = (index, error) => {
+      raw[index] = { state: FETCH_UNREACHABLE, reason: compactFailReason(error), detail: '', label: list[index].label ?? channelLabel(list[index].id) }
+      pending -= 1
+      // 全部失败 → unreachable + **逐条**原因（这时本来就要等到预算耗尽，收齐不影响速度）
+      if (pending === 0) done({ state: FETCH_UNREACHABLE, body: null, channel: null, failures: failuresOf() })
+    }
+    for (let index = 0; index < list.length; index += 1) {
+      // 同步抛出也算这条通道失败（不能让它把整个竞速掀掉）
+      try {
+        Promise.resolve().then(list[index].run).then(
+          (body) => settleOne(index, body),
+          (error) => failOne(index, error),
+        )
+      } catch (error) {
+        failOne(index, error)
+      }
+    }
+    // 外层预算兜底（与旧实现同为 FETCH_BUDGET_MS）
+    setTimer(() => done({ state: FETCH_UNREACHABLE, body: null, channel: null, failures: failuresOf() }), timeoutMs)
+  })
+}
+
+/** raw 抓取（带状态 + **通道身份** + 逐通道失败原因）：返回 `{ state, body, channel, failures }`。
+ * 通道 = 既有 4 条竞速（node:https 官方+镜像 / gh CLI / curl 直连 / curl jsDelivr，一条不删）
+ * **加上**调用方注入的额外通道（本地落地、npm registry 包清单 —— 见 domain/landed-source.js、
+ * domain/registry-manifest.js）。额外通道排在既有 4 条**之后**：优先级按可达性，
+ * 本地 > 既有网络通道 > registry。 */
+async function rawTextFetch(repo, branch, path, budgetMs = FETCH_BUDGET_MS, deps = {}) {
+  const url = `${GITHUB_RAW}/${repo}/${encodeURIComponent(branch)}/${path}`
+  // 404/4xx：确定性"不存在"，立即以 null 胜出（不等慢分支）
+  const notFound = (promise) => promise
+    .catch((error) => {
+      if (error instanceof Error && /HTTP 404|HTTP 400|Not Found|not found|非 2xx|HTTP 非 2xx/u.test(error.message)) return null
+      throw error
+    })
+  // 各通道统一口径：状态 2xx **且** body 非空白，才算读到文件（否则抛"非 2xx"→ 归一为 null）
+  const real = (promise) => promise.then((body) => {
+    const text = readBodyOrNull(body)
+    if (text === null) throw new Error('HTTP 非 2xx')
+    return text
+  })
+  const https = notFound(real(githubText(url)))
+  const gh = notFound(real(githubViaGh(`repos/${repo}/contents/${path}?ref=${encodeURIComponent(branch)}`)
+    .then((data) => {
+      if (data && typeof data.content === 'string') return Buffer.from(data.content, 'base64').toString('utf8')
+      throw new Error('contents 无内容')
+    })
+    .then((text) => {
+      const body = readBodyOrNull(text)
+      if (body === null) throw new Error('contents 无内容')
+      return body
+    })))
+  const curl = notFound(real(curlText(url, 9000, { ipv4: true })))
+  const cdn = notFound(real(curlText(`https://cdn.jsdelivr.net/gh/${repo}@${encodeURIComponent(branch)}/${path}`, 9000, { ipv4: true })))
+  // 额外通道（本地落地 / npm registry 包清单）：按注入顺序追加，**排在既有 4 条之后** ——
+  // 既有 4 条仍是主力（能力不许删），额外通道只增加可达性。
+  const extra = (Array.isArray(deps.extraChannels) ? deps.extraChannels : [])
+    .filter((ch) => ch !== null && typeof ch?.run === 'function')
+    // 口径与既有 4 条完全一致：确定性 404 → null（立即胜出）；空内容 → 当作"没读到"
+    .map((ch) => ({ id: ch.id, label: ch.label, run: () => notFound(real(Promise.resolve().then(ch.run))) }))
+  const channels = [
+    { id: 'https', run: () => https },
+    { id: 'gh', run: () => gh },
+    { id: 'curl', run: () => curl },
+    { id: 'jsdelivr', run: () => cdn },
+    ...extra,
+  ]
+  const race = deps.race ?? raceFetchOutcome
+  return await race({ channels, timeoutMs: budgetMs, deps })
+}
+
+/** 兼容入口：调用方只关心"有没有内容"（null = 没有）。需要区分超时/404 的场景用 rawTextFetch。 */
+async function rawTextWithFallback(repo, branch, path) {
+  const { state, body } = await rawTextFetch(repo, branch, path)
+  return state === FETCH_OK ? body : null
+}
+export { githubRequestOnce, raceFirst2xx, githubRequest, collectBody, githubViaGh, githubJson, githubText, curlJson, curlText, fetchJsonUrl, rawTextWithFallback, rawTextFetch, raceFetchOutcome, readBodyOrNull, looksLikeGitmodules, postJsonUrl, GITHUB_API, GITHUB_RAW, GITHUB_UA, API_MIRROR_PREFIXES, RAW_MIRROR_PREFIXES, FETCH_BUDGET_MS, META_BUDGET_MS, FETCH_OK, FETCH_NOT_FOUND, FETCH_UNREACHABLE, CHANNEL_LABELS, channelLabel, compactFailReason, channelFailureLines, channelFailureSummary }

package/lib/server/infra/paths.js

@@ -52,9 +52,65 @@ function baseDirOf(baseUrl) {
  * require.resolve('pkg/package.json') 对声明了 exports 且不含 './package.json' 的包会抛错
  * （2026-09-04 教训：@openviking/dsh-memory-plugin 因此被 heal 误判模块缺失并自动禁用）——
  * fallback 直接查 node_modules 物理路径。
+ *
+ * ★ 2026-10-13（0.5.48）改错：**对 exports 子路径的假阳性**。
+ *   现场：装 ds-bot 时 `verifyInstalledEntry` 拿 `ds-bot/web-search` 来核实，旧代码把引用名拼成
+ *   `ds-bot/web-search/package.json` ⇒ ds-bot 的 exports 里没有这个子路径 ⇒
+ *   `ERR_PACKAGE_PATH_NOT_EXPORTED` ⇒ 退物理路径 `node_modules/ds-bot/web-search/package.json`
+ *   ⇒ **也不存在**（包的清单在 `node_modules/ds-bot/package.json`，不在子目录里）⇒ 返回 null
+ *   ⇒ 误报"缺模块会崩/会被自动禁用"。
+ *   但按**真实解析语义**这个引用是好的：本机实测 `require.resolve('ds-bot/web-search')` **成功**
+ *   （`包/子路径` 是生态既有约定，官方 patch 里也有这种 entry），`import.meta.resolve` 同理，
+ *   模块也能真 `import()`。
+ *   ⇒ 现在先用**真实解析语义**解析「引用名本身」（不再拿字符串拼 `/package.json`），
+ *     成功后从解析结果**向上找最近的 package.json** 作为该包的清单。
+ *   ⇒ 负控不变：真不存在的子路径，三条路都失败 ⇒ 仍然返回 null（**绝不放松成"一律放行"**）。
  */
+function nearestPackageJson(fromPath) {
+  try {
+    let dir = dirname(fromPath)
+    for (let depth = 0; depth < 40; depth += 1) {
+      const candidate = join(dir, 'package.json')
+      if (existsSync(candidate)) return candidate
+      const parent = dirname(dir)
+      if (parent === dir) break
+      dir = parent
+    }
+  } catch {}
+  return null
+}
+
+/** 该引用是不是"包 + 子路径"形态（`pkg/sub`、`@scope/pkg/sub`）。
+ * 判据与 packageNameOf 同源：剥掉包名后还剩东西 ⇒ 是子路径引用。 */
+function isSubpathRef(refName) {
+  if (typeof refName !== 'string' || refName === '') return false
+  return refName !== packageNameOf(refName)
+}
+
+/** 用真实解析语义解析「包/子路径」引用的清单路径：先解析引用本身，再向上找最近的清单。 */
+function resolveViaRealSemantics(refName, base) {
+  if (typeof base !== 'string' || base === '') return null
+  try {
+    const entry = createRequire(join(base, 'package.json')).resolve(refName)
+    return nearestPackageJson(entry)
+  } catch {
+    return null
+  }
+}
+
 function resolvePackageJson(pkgName, baseDir, fallbackBase) {
   const name = packageNameOf(pkgName)
+  // ① 真实解析语义（认 exports 子路径）—— 优先，且**不**拼 `/package.json`
+  const real = resolveViaRealSemantics(pkgName, baseDir)
+  if (real !== null) return real
+  // ★ 子路径引用（`包/子路径`）到此为止：**不许**再退到"按包名找清单"的那两条 fallback。
+  //   为什么：那两条是按**包名**（packageNameOf 剥掉子路径后的 name）找 `node_modules/<包名>/package.json`，
+  //   对不存在的子路径也会命中**包根**那份清单 ⇒ 把一个坏引用判成好的
+  //   —— 正是"校验被放松成一律放行"，任务红线明令不许。
+  //   （本机实测：`@scope/tool/nope` 在 @scope/tool 存在时会从 fallback 拿到包根清单。）
+  //   而真实解析语义对这一类已经给出权威答案：能解析就是好，不能解析就是坏 ⇒ 直接返回 null。
+  if (isSubpathRef(pkgName)) return null
+  // ② 既有两条（顺序与行为不变）：`<name>/package.json` 解析 → node_modules 物理路径
   try {
     return createRequire(join(baseDir, 'package.json')).resolve(`${name}/package.json`)
   } catch {}
@@ -65,6 +121,8 @@ function resolvePackageJson(pkgName, baseDir, fallbackBase) {
   // 官方 @deepseek-ai/* 恰好可见、第三方插件全部解析失败 → 详情/版本/仓库全空。
   // 回退到 profile 目录（fallbackBase）再试一次。
   if (typeof fallbackBase === 'string' && fallbackBase !== '' && fallbackBase !== baseDir) {
+    const realFallback = resolveViaRealSemantics(pkgName, fallbackBase)
+    if (realFallback !== null) return realFallback
     try {
       return createRequire(join(fallbackBase, 'package.json')).resolve(`${name}/package.json`)
     } catch {}

package/lib/server/infra/pnpm-release-gate.js

@@ -0,0 +1,74 @@
+// L0 · infra —— pnpm 供应链闸门（minimumReleaseAge）的**判据与错误翻译**（0.5.48 加法）
+//
+// 为什么单开一个模块：这两个函数的归属是自洽的（"把 pnpm 的闸门原文翻译成用户能照着做的错误"），
+// 而 infra/exec.js 贴着 tests/test-architecture-guard.mjs 的 **单文件 ≤ 600 行**硬顶（0.5.48 实测
+// 723 行被棘轮拦下）⇒ 抽出来是**只搬移与新增**，exec.js 只留调用点。
+//
+// 现场（用户实测，装 ds-bot 时撞出来）：
+//   pnpm 的 minimumReleaseAge 闸门拦下了太新的版本，而它在**可交互**时会弹提问等人回答；
+//   桌面壳/服务进程给的是**永不关闭的 stdin 管道** ⇒ 不抛错、不超时，**永久挂住**
+//   （实测两次分别挂到 90s / 180s 被杀）。
+//
+// 闸门实现（本机 pnpm 11.7.0 `dist/pnpm.mjs`，只读反编译取证）：
+//   L194277  const inCi = opts3.ci ?? isCI
+//   L194278  const canPrompt = !inCi && Boolean(process.stdin.isTTY)
+//   L194305  if (canPrompt) { await promptForApproval(immature) }
+//   L194307  else { throw failOnImmature(immature) }   ← 我们要走的分支
+//   L194330    confirmed = await dist_default5({ message, default: false })  ← prompt 库读 stdin 到 EOF
+//   L63849   MINIMUM_RELEASE_AGE_VIOLATION_CODE = 'MINIMUM_RELEASE_AGE_VIOLATION'
+//
+// ★ 红线：本模块只做"识别 + 翻译成可操作错误"，**绝不**提供任何绕过闸门的手段
+//   （不使用忽略锁文件校验 / 强制安装一类开关）。闸门该拦还是拦，只是把"等人回答"换成"立刻报错并给解法"。
+//
+// 分层：L0 · infra（不得 import domain/routes/index —— tests/test-architecture-guard.mjs 断言②）。
+
+/** 命中 pnpm 供应链闸门的**判据**（纯函数，单测覆盖）。
+ * 两代真实文案都要认（照 exec.js#unknownPnpmOption 的教训：缺一条就等于"闸门命中被当成普通失败"，
+ * 用户拿不到"怎么加白名单"的解法）：
+ *   · pnpm 11.7.0 的违规码 `MINIMUM_RELEASE_AGE_VIOLATION` / `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`；
+ *   · 严格模式不可交互时 pnpm 抛 `NO_MATURE_MATCHING_VERSION`（同文件 194308 的 failOnImmature）；
+ *   · 用户在提问处拒绝时是 `MINIMUM_RELEASE_AGE_DENIED`（同文件 194340）。 */
+function releaseAgeGateHit(message) {
+  const text = String(message ?? '')
+  return /MINIMUM_RELEASE_AGE_VIOLATION|MINIMUM_RELEASE_AGE_DENIED|NO_MATURE_MATCHING_VERSION|ERR_PNPM_MINIMUM_RELEASE_AGE/iu.test(text)
+}
+
+/** 从 pnpm 原始输出里抠出"被闸门拦下的 `包@版本`"清单（尽力而为，抠不到就返回 []）。
+ * 两种真实排版：`  <name>@<version> <reason>`（failOnImmature）与裸 `<name>@<version>`。 */
+function releaseAgeBlockedSpecs(message) {
+  const found = new Set()
+  for (const line of String(message ?? '').split(/\r?\n/u)) {
+    const m = line.match(/(@?[A-Za-z0-9][\w.@/-]*?)@(\d+\.\d+\.\d+(?:-[\w.]+)?)/u)
+    if (m) found.add(`${m[1]}@${m[2]}`)
+  }
+  return [...found]
+}
+
+/** 把"命中供应链闸门"翻译成**用户能照着做**的错误（纯函数，单测覆盖）。
+ * 需求红线：**必须快速如实失败并给出解法**。所以这里只说三件事：
+ *   ① 哪个包被拦下 ② 命中哪条闸 ③ 怎么加白名单。 */
+function releaseAgeGateError({ spec, profileDir, message } = {}) {
+  const blocked = releaseAgeBlockedSpecs(message)
+  const who = blocked.length > 0 ? blocked.join('、') : String(spec ?? '（未能从 pnpm 输出解析出包名）')
+  const lines = [
+    `pnpm 供应链闸门（minimumReleaseAge）拦下了 ${who}：该版本发布时间还没满 pnpm 配置的最短"冷静期"。`,
+    '这不是网络故障。闸门是安全特性，本控制台**不会绕过它**（既不忽略锁文件校验，也不强制装），',
+    '所以这里选择**立刻如实失败**，并把解法交给你：',
+    '解法（任选其一）：',
+    `  ① 加白名单：在 profile 的 pnpm-workspace.yaml 里把该版本追加进 minimumReleaseAgeExclude，例如`,
+    `     minimumReleaseAgeExclude:\n       - '${blocked[0] ?? '<包名>@<版本>'}'`,
+    '     ★ 该清单是**逐版本**匹配的（pnpm 只认 `包名@精确版本`，不支持范围）⇒ 每发一个新版本都要加一行。',
+    '  ② 等：过了冷静期后重试同一操作即可，无需改配置。',
+    '  ③ 调低/关闭该策略：不推荐，等于放弃这道供应链保护。',
+  ]
+  if (typeof profileDir === 'string' && profileDir !== '') lines.push(`目标 profile：${profileDir}`)
+  const error = new Error(lines.join('\n'))
+  error.name = 'PnpmSupplyChainGateError'
+  error.code = 'DSH_PNPM_RELEASE_AGE_GATE'
+  error.gate = 'minimumReleaseAge'
+  error.blocked = blocked
+  error.pnpmMessage = String(message ?? '')
+  return error
+}
+
+export { releaseAgeGateHit, releaseAgeBlockedSpecs, releaseAgeGateError }