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

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/routes/components.js

@@ -157,24 +157,78 @@ function openFolderBin() {
   return process.platform === 'darwin' ? 'open' : 'xdg-open'
 }
 
-// ── 唯一进程创建点（可注入 + 默认安全；2026-10-13 两次事故记录）──────────────────────────
+// ── 唯一进程创建点（可注入 + 默认安全；2026-10-13 三次事故记录）──────────────────────────
 // 事故一（0.5.45）：上一批测试为了覆盖"成功路径"直接调真路由 ⇒ 真的起了 explorer.exe，而夹具路径
 // 当时不存在 ⇒ 用户桌面弹出 Windows「位置不可用」对话框。
 // 事故二（0.5.46 施工中）：又弹了一次 —— 根因是**默认不安全**：那时"默认真 spawn，只靠外部设
 // DSH_OPEN_FOLDER_NO_SPAWN=1 才拦得住"，任何人/任何 CI 不带那个变量跑测试就会重新踩到。
-// ⇒ 现在把语义**反过来**：真 spawn 必须**显式 opt-in**，缺席时的默认结局是**被拒绝**（不是弹窗）。
-// 进程创建只此一处，四重防线：
+// 事故三（2026-10-13，用户第三次截图）：**又弹了一次**，指到夹具
+// `tests\.testdir\open-folder-home\repos\probe-org\landed-re…`（"位置不可用"= 启动时目标已不存在）。
+// 根因不是"少设了一个变量"，而是**两道门都只保护"不传 allowRealSpawn 的调用方"**：
+//   · opt-in 门：`routeRepoOpen` **永远**传 allowRealSpawn:true（它代表用户点了按钮）⇒ 测试里
+//     调一次真路由 = 一次真 opt-in；
+//   · 注入门：测试里一句 `__setOpenFolderSpawn(null)`（原语义"还原生产实现"）就把桩摘掉 ⇒
+//     两个条件同时成立，真 explorer.exe 就在测试进程里起来了。
+// 现在把语义收成**测试进程不可自解**的两层（不需要任何环境变量、任何调用方配合）：
+//   ⓪ **测试进程判定**（isTestProcess）：只看自己进程的入口脚本是不是本仓 `tests/**`（run-all 的子进程也算）
+//      ⇒ 是 ⇒ 模块**加载即装**测试桩（injectedSpawn = tripwire），且 `__setOpenFolderSpawn(null)`
+//      还原到的仍然只能是这个测试桩 —— 安全网拆不掉；
 //   ① 注入缝：单测 `__setOpenFolderSpawn(stub)` 换成桩（一次进程都不建）；
 //   ② 保险丝：`DSH_OPEN_FOLDER_NO_SPAWN=1` 时**绝不**走到 spawn —— 如实返回结构化拒绝
 //      （不是静默跳过：调用方照旧把这条原因报给用户）；
 //   ③ **默认安全（opt-in）**：回落到真 `defaultSpawn` 需要 `allowRealSpawn:true` 或
 //      `DSH_OPEN_FOLDER_ALLOW_REAL_SPAWN=1`；两者都没有 ⇒ 结构化拒绝。生产的 routeRepoOpen 是
 //      唯一的 opt-in 调用方 —— 于是"测试漏了注入"的默认结局是**红/被拒**，而不是弹用户一个窗口；
-//   ④ 计数：真实 spawn 调用次数可读，测试断言恒为 0；`__openFolderSelfCheck()` 是计数器的正控
-//      （真的起一次**不弹任何窗口**的进程，证明计数不是死的 —— 桩自校验，本仓既有做法）。
+//   ④ **运行期断言**：测试进程里"即将真 spawn"（无注入桩可选）⇒ **当场抛错**（见 openFolderVerified 顶部）
+//      —— 这一条专治"测试调真路由 ⇒ 真 opt-in"那条路（事故三）；
+//   ⑤ 计数：真实 spawn 调用次数可读，测试断言恒为 0（自检那一次除外）；`__openFolderSelfCheck()` 是
+//      计数器的正控（真的起一次**不弹任何窗口**的进程，证明计数不是死的）。
 let injectedSpawn = null
 let realSpawnCalls = 0
 
+/** **测试进程判定**（2026-10-13 第三次事故的根修；刻意**不依赖任何环境变量**）。
+ *
+ * 为什么必须有它：opt-in 那道门只保护"没传 allowRealSpawn 的调用方"，而 **routeRepoOpen 永远传
+ * allowRealSpawn:true**（它代表"用户点了按钮"）。于是"测试里调了一次真路由"= 一次真 opt-in
+ * ⇒ explorer.exe 照样弹窗；再叠上测试里一句 `__setOpenFolderSpawn(null)`（"还原生产实现"），
+ * 安全网就被彻底拆掉。前两次事故（0.5.45 / 0.5.46 施工中）就是这么来的，第三次（2026-10-13
+ * 用户截图 `tests\.testdir\open-folder-home\repos\probe-org\landed-re…` 位置不可用）仍是这条路。
+ *
+ * 判据只看**自己进程的入口脚本**：`<repo>/tests/test-*.mjs`（含 run-all.mjs 的子进程）⇒ 测试进程。
+ * 生产入口（dsh / bin.js / 桌面端运行时）不匹配 ⇒ 行为与生产完全一致。绝不猜别的进程、绝不看环境变量。 */
+function isTestProcess() {
+  // 子进程同样受保护：测试进程在加载本模块时会把标记写进环境（见文件下方"模块加载即装"），
+  // 于是 `node -e` / 临时脚本 / 任何由测试拉起的 node 子进程都被判成测试进程 —— 这一条**不是**
+  // "靠用户设环境变量才安全"：标记是代码自己写、自己继承的，用户什么都不用做。
+  try {
+    if (process.env.DSH_TEST_PROCESS === '1') return true
+  } catch {}
+  try {
+    const entry = String(process.argv[1] ?? '').replace(/\\/gu, '/')
+    if (entry === '') return false
+    return /\/tests\/(?:test-[^/]*\.mjs|run-all\.mjs|probe-[^/]*\.cjs)$/u.test(entry)
+  } catch {
+    return false
+  }
+}
+
+/** 测试进程里的默认桩：**在创建进程之前**抛错 —— 这就是"即将真 spawn ⇒ 当场红"的运行期断言
+ * （不是放行、也不是结构化拒绝：漏注入的结局必须是红）。 */
+function testProcessTripwire() {
+  throw new Error('测试红线：测试进程里绝不允许真的启动文件管理器（explorer.exe）—— 请在测试里注入 spawnFn / __setOpenFolderSpawn(stub)，或用 rc.deps.openFolderLauncher')
+}
+
+// ★ 模块加载即装（无需任何 env、无需任何调用方配合）：测试进程里 `injectedSpawn` 永远是一个桩，
+//   连生产的 opt-in 调用方（routeRepoOpen）也绕不过它 —— 测试**永远**不 opt-in。
+//   同时把"我是测试进程"写进环境，让子进程（node -e / 临时脚本 / 任何 node 子进程）继承同一道保护：
+//   光看 argv[1] 只能认出"入口就是测试文件"的那一层，而测试拉起的子进程完全可能调真路由（事故三的形状）。
+if (isTestProcess()) {
+  injectedSpawn = testProcessTripwire
+  try {
+    process.env.DSH_TEST_PROCESS = '1'
+  } catch {}
+}
+
 /** 真 spawn 的**显式 opt-in**（默认拒绝；见 openFolderVerified 第 ③ 条）。 */
 function realSpawnOptIn(allowRealSpawn) {
   return allowRealSpawn === true || process.env.DSH_OPEN_FOLDER_ALLOW_REAL_SPAWN === '1'
@@ -185,9 +239,12 @@ function defaultSpawn(bin, args, options) {
   return spawn(bin, args, options)
 }
 
-/** 单测注入启动桩：传函数 = 打桩（**不创建任何进程**）；传 null = 还原生产实现。 */
+/** 单测注入启动桩：传函数 = 打桩（**不创建任何进程**）；传 null = 还原生产实现 ——
+ * **但在测试进程里"还原"到的只能还是测试桩**（见 isTestProcess 顶部注释：一句
+ * `__setOpenFolderSpawn(null)` 就把真实 explorer 重新武装起来，正是第三次弹窗的根因）。
+ * 返回 `injectedSpawn !== null`（测试进程里恒为 true：安全网不可被测试自己拆掉）。 */
 function __setOpenFolderSpawn(fn) {
-  injectedSpawn = typeof fn === 'function' ? fn : null
+  injectedSpawn = typeof fn === 'function' ? fn : (isTestProcess() ? testProcessTripwire : null)
   return injectedSpawn !== null
 }
 
@@ -196,6 +253,19 @@ function __openFolderRealSpawnCalls() {
   return realSpawnCalls
 }
 
+/** 安全网现状（只读；测试用来断言"测试进程里桩摘不掉"这件事本身）。 */
+function __openFolderSafetyState() {
+  return { testProcess: isTestProcess(), injected: injectedSpawn !== null, realSpawnCalls }
+}
+
+/** **仅测试用**：故意把注入桩摘掉，用来证明"即将真 spawn ⇒ 当场抛错给红"这条运行期断言是活的
+ * （不是一句没人走的空话）。正常路径下测试进程**永远**摘不掉桩 —— 本函数只服务变异验证/负控，
+ * 生产代码不得调用（它在测试进程里只会让下一次真实启动请求当场抛错）。 */
+function __forceUnsafeSpawnForTest() {
+  injectedSpawn = null
+  return injectedSpawn === null
+}
+
 /** 计数器正控（桩自校验）：用**生产同一个** defaultSpawn 起一次 node -e ""（无窗口、无副作用），
  * 返回它是否被计数到。返回 false ⇒ 计数桩坏了，测试必须据此响亮失败，而不是拿 0 当"没启动过"。 */
 async function __openFolderSelfCheck() {
@@ -237,6 +307,13 @@ function openFolderPathIssue(target) {
  * 判据（本仓口径）：宁可红也不报假绿；静默一律不许。 */
 function openFolderVerified({ target, bin = null, spawnFn = null, launchWaitMs = 1200, allowRealSpawn = false } = {}) {
   const started = Date.now()
+  // ★ 运行期断言（2026-10-13 第三次事故的根修）：**测试进程里"即将真 spawn"一律当场抛错**。
+  //   判定发生在任何进程创建之前、且**先于** opt-in：生产的 routeRepoOpen 会传 allowRealSpawn:true，
+  //   测试里调真路由 = 真 opt-in ⇒ 只有这一道断言能拦住它（"测试永远不 opt-in"就是这么落实的）。
+  const injectedNow = typeof spawnFn === 'function' ? spawnFn : injectedSpawn
+  if (injectedNow === null && isTestProcess()) {
+    throw new Error('测试红线：测试进程里即将真的启动文件管理器（explorer.exe）—— 已当场拒绝并给红（请注入 spawnFn / __setOpenFolderSpawn(stub) / rc.deps.openFolderLauncher）')
+  }
   return new Promise((resolve) => {
     // ② 保险丝：测试红线。**先于任何进程创建**判定，且如实说明被拦下的原因。
     if (process.env.DSH_OPEN_FOLDER_NO_SPAWN === '1') {
@@ -433,4 +510,4 @@ async function routeComponentStatus(req, res, rc) {
     return
 }
 
-export { routeComponents, routeRepoClone, routeRepoList, routeRepoLandConfig, routeRepoRemove, routeRepoOpen, routeComponentAutostart, routeComponentStart, routeComponentStop, routeComponentStatus, openFolderBin, openFolderVerified, __setOpenFolderSpawn, __openFolderRealSpawnCalls, __openFolderSelfCheck }
+export { routeComponents, routeRepoClone, routeRepoList, routeRepoLandConfig, routeRepoRemove, routeRepoOpen, routeComponentAutostart, routeComponentStart, routeComponentStop, routeComponentStatus, openFolderBin, openFolderVerified, isTestProcess, __setOpenFolderSpawn, __openFolderRealSpawnCalls, __openFolderSelfCheck, __openFolderSafetyState, __forceUnsafeSpawnForTest }

package/lib/server/routes/install.js

@@ -1,12 +1,16 @@
 // L2 · routes —— 安装（POST /install · POST /install-status）
 // 分层 Step 8b：从 lib/index.js 的 handle() 原样搬出（只搬移未改逻辑；缩进保持原样）
 
+import { dirname } from 'node:path'
 import { installJobView } from '../domain/install.js'
 import { runInstallJob } from '../domain/install-job.js'
+import { failedJobEvidence } from '../domain/install-verify.js'
 import { fetchRepoPackageEx, githubRepoInfo, subpackageCandidates } from '../domain/market.js'
 import { runSkillInstallJob } from '../domain/skills.js'
+import { normalizeSubdir } from '../domain/subdir-install.js'
 import { probeGitmodules, resolveInstallKind, runSuiteInstallJob } from '../domain/suite.js'
 import { sendError, sendJson } from '../infra/httpd.js'
+import { findPatchPath } from '../infra/paths.js'
 import { installJobs, nextInstallJobSeq } from '../state.js'
 
 async function routeInstall(req, res, rc) {
@@ -38,6 +42,20 @@ async function routeInstall(req, res, rc) {
       return
     }
     const source = body.source === 'gitee' ? body.source : 'github'
+    // 子目录插件的一键安装（2026-10-13 加法，第二轮）：面板在「插件在 <子目录>/ 下」那张卡片上
+    // 直接带 `subdir` 过来。**格式先在这里拦住**（与 packageName 同一套"来源校验一视同仁"的写法），
+    // 判据的权威仍是 domain/subdir-install.js#normalizeSubdir —— 两边同一把尺子。
+    const rawSubdir = typeof body.subdir === 'string' ? body.subdir.trim() : ''
+    const subdir = rawSubdir === '' ? null : normalizeSubdir(rawSubdir)
+    if (rawSubdir !== '' && subdir === null) {
+      sendError(res, 400, 'subdir 不合法：只接受仓库里第 1～2 层的相对目录（如 ds-bot 或 packages/foo），不接受绝对路径、盘符、反斜杠与 . / ..')
+      return
+    }
+    if (subdir !== null && repo === '') {
+      sendError(res, 400, '从子目录安装必须提供仓库（owner/name）')
+      return
+    }
+    const branch = typeof body.branch === 'string' && body.branch.trim() !== '' ? body.branch.trim() : null
     const npmNamePattern = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u
     if (givenName !== '' && (!npmNamePattern.test(givenName) || givenName.length > 214)) {
       sendError(res, 400, 'packageName 不是合法的 npm 包名')
@@ -77,6 +95,9 @@ async function routeInstall(req, res, rc) {
       lastError: null,
         update: body.update === true,
       kind,
+      // 子目录插件安装（纯加法：不带 subdir 时这两项就是 null，作业形状与改动前逐字相同）
+      subdir,
+      branch,
     }
     if (suiteNote !== null) job.suiteNote = suiteNote
     installJobs.set(job.id, job)
@@ -117,6 +138,12 @@ async function routeInstallStatus(req, res, rc) {
     sendJson(res, 200, {
       ok: true,
       ...installJobView(job),
+      // ★「其实已经装上了」核实（0.5.47 改错，用户被误导过）：**报失败/给重试之前**先查三处
+      // （依赖清单 / dsh.profile.bundles / node_modules）——已装 ⇒ 面板显示「已安装 vX（无需重装）」，
+      // 历史失败降级为次要信息。作业自己的那份（例如子目录安装早退时算的）在没有失败时照旧下发。
+      installedEvidence: job.status === 'failed'
+        ? (failedJobEvidence(dirname(findPatchPath(ctx)), job) ?? job.installedEvidence ?? null)
+        : (job.installedEvidence ?? null),
       // 结构化建议动作（2026-09-27 加法，向后兼容）：老客户端忽略该字段；
       // 新客户端在安装结果卡片里渲染「执行 / 复制」小框（POST /plugin-console/run-suggested）。
       // 放这里而不是 install.js#installJobView：那个模块已贴着 600 行架构棘轮（见 test-architecture-guard.mjs）。