@thincoder/core 0.10.3 → 0.10.5

package/provider-flows.mjs

@@ -21,7 +21,7 @@
  * M9 语义定死：**准入永不阻断写** —— 探针只出读数 ∕ 失败消息（消息本体逐字长句），绝不抛出 ∕
  * 绝不回滚已完成的保存；失败不缓存（下次配置动作重探）。
  *
- * 消费面：桌面 `thincoder-desktop/src/main/providers.mjs`（四通道壳——判据面：`FORMATS` ∕
+ * 消费面：桌面 `thincoder-desktop/src/main/providers.mjs`（四通道壳——判据：`FORMATS` ∕
  * `customFieldsError` ∕ `probeAdmission`；端侧 reason 词法不动）；三流程本体 = 桌面 ∕ VSC（已随本批迁移改指）消费，CLI 待迁。
  */
 import { PROVIDER_PRESETS } from "./config-presets.mjs"
@@ -54,17 +54,16 @@ export function providerNameError(name, existing = new Set()) {
 }
 
 /**
- * 自定形必填字段校验（VSC `addProviderFlow` 自定径输入步步序 = baseURL → model → format；
- * name 步单列见 `providerNameError`）。三拒因串 = 核持久化面**同条件串**逐字（`config-io.mjs`
- * `addProviderEntry`）——VSC 该三步为静默中止位（无消息可搬）⇒ 取同条件核串，保「同条件同词」。
+ * 自定形必填字段校验（VSC `addProviderFlow` 自定径输入步步序 = baseURL → format；
+ * name 步单列见 `providerNameError`。2026-10-09 清除批：model 步退场——渠道不携模型）。
+ * 两拒因串 = 核持久化面**同条件串**逐字（`config-io.mjs`
+ * `addProviderEntry`）——VSC 该两步为静默中止位（无消息可搬）⇒ 取同条件核串，保「同条件同词」。
  * `format` 缺省 = `"openai"`（沿端侧形判同式）。
  * @returns {string|null} 首个失败字段的拒因串；全过 ⇒ `null`
  */
 export function customFieldsError(fields) {
   const baseURL = String(fields?.baseURL ?? "").trim()
   if (!baseURL) return "Base URL is required"
-  const model = String(fields?.model ?? "").trim()
-  if (!model) return "Model is required"
   const format = fields?.format ?? "openai"
   if (!FORMATS.includes(format)) return `Unknown API format: ${format} (expected ${FORMATS.join("/")})`
   return null
@@ -73,19 +72,21 @@ export function customFieldsError(fields) {
 /**
  * M9 探针目标构造（上提源 = VSC `provider-flows.mjs:38` 的实参面 `presets.mjs` `probeTargetFromEntry`——
  * 逐条随迁）：渠道条目 ⇒ `listModels` 可消费的探针目标。代理链与 chat 请求同规则（per-provider `proxy: true`
- * ∧ 全局 `proxy.model === true` ⇒ 探针也走该代理）；apiKey 归一（trim；缺 ⇒ 空串——探针会如实失败 ⇒
- * 渠道标「不可用」——准入判据 M8）。
+ * ∧ `proxy.uri` 在案 ⇒ 探针也走该代理；无全局闸——2026-10-08 批落）；apiKey 归一（trim；缺 ⇒ 空串——探针会
+ * 如实失败 ⇒ 渠道标「不可用」——准入判据 M8）。`headers` 字段面（#1048①）：仅 plain-object 才携；缺 ∥ 非法 ⇒
+ * 零键（同 apiKey 归一律）——来源面 = 盘上条目 ∥ 表单；消费点 = `list-models` 各 format 分支请求头展开。
  */
 export function probeTargetOf(entry) {
   const raw = loadRaw()
   const proxyCfg = normalizeProxy(raw.proxy)
-  const proxyUri = entry?.proxy === true && proxyCfg?.uri && proxyCfg.model === true ? proxyCfg.uri : undefined
+  const proxyUri = entry?.proxy === true && proxyCfg?.uri ? proxyCfg.uri : undefined
   return {
     name: entry?.name,
     baseURL: entry?.baseURL,
     apiKey: typeof entry?.apiKey === "string" ? entry.apiKey.trim() : "",
     format: entry?.format,
     proxyUri,
+    ...(entry?.headers && typeof entry.headers === "object" && !Array.isArray(entry.headers) ? { headers: entry.headers } : {}),
   }
 }
 
@@ -146,8 +147,8 @@ export async function addProviderFlow(ui, refresh, deps = {}) {
 
   const items = Object.entries(PROVIDER_PRESETS)
     .filter(([name]) => !existing.has(name))
-    .map(([name, p]) => ({ label: name, description: p.desc, detail: p.model ?? "", kind: "preset", name }))
-  items.push({ label: "Custom (manual config)", description: "enter baseURL/model/format", kind: "custom" })
+    .map(([name, p]) => ({ label: name, description: p.desc, detail: p.baseURL ?? "", kind: "preset", name }))
+  items.push({ label: "Custom (manual config)", description: "enter baseURL/format", kind: "custom" })
 
   const sel = await host.pick(items, {
     placeHolder: "Add provider — select a preset",
@@ -166,14 +167,12 @@ export async function addProviderFlow(ui, refresh, deps = {}) {
       placeHolder: "https://api.example.com/v1",
     }))?.trim()
     if (!baseURL) return
-    const model = (await host.input({ prompt: `Model name for ${name}` }))?.trim()
-    if (!model) return
     const format = await host.pick(
       FORMATS.map((f) => ({ label: f, description: f === "openai" ? "(default)" : f === "anthropic" ? "Messages API" : "streamGenerateContent" })),
       { placeHolder: "API format" },
     )
     if (!format) return
-    const err = addProviderEntry({ custom: { name, baseURL, model, format: format.label } })
+    const err = addProviderEntry({ custom: { name, baseURL, format: format.label } })
     if (err) { host.error(err); return }
     const key = await host.input({ prompt: `API key for ${name} (leave empty to skip)`, password: true })
     if (key?.trim()) {
@@ -213,7 +212,7 @@ export async function removeProviderFlow(ui, refresh) {
     return
   }
   const sel = await host.pick(
-    candidates.map((p) => ({ label: p.name, description: p.model ?? "" })),
+    candidates.map((p) => ({ label: p.name, description: p.baseURL ?? "" })),
     { placeHolder: "Remove provider" },
   )
   if (!sel) return

package/proxy-chunked.mjs

@@ -0,0 +1,102 @@
+/**
+ * proxy-chunked.mjs — HTTP/1.1 分块传输（`Transfer-Encoding: chunked`）流式剥帧器（#1065）。
+ *
+ * 单出 `createChunkedDecoder`（设计 = `docs/core/design/PROXY.md` §2 ∥ §7 D-PX11）：
+ * - **流式保形**：边收边吐、只保有帧头（块长行上限 1KiB）；块数据到达即吐 `min(可用, 待吐)`；
+ * - 块长 = 十六进制（行长 ≤1KiB、数值须安全整数——越界判畸形）+ 可选 `;扩展`（扩展忽略）；块尾须恰为 CRLF；`0` 块 ⇒ `onEnd`
+ *   （其后 trailer ∥ 余字节读取即弃——`Connection: close` 语义下无复用面）；
+ * - **畸形帧回退 = 透传**：已持有字节原样吐出 + 其后全部字节直通——不报错（不把协议违规
+ *   升级成连接失败）、不截断（零静默丢数据）；
+ * - 纯状态机、无自有 `'error'` 面（#16 契约零变——body 终止守卫族照旧对 body 单点直作）。
+ * 零依赖：Node built-ins only。
+ */
+
+/** 块长行上限（超限判畸形——防无界持有帧头）。 */
+const MAX_SIZE_LINE = 1024
+const CRLF = Buffer.from("\r\n")
+const EMPTY = Buffer.alloc(0)
+
+/** 十六进制字节判定（0-9 ∥ a-f ∥ A-F——大小写不敏感）。 */
+const isHexByte = (b) => (b >= 0x30 && b <= 0x39) || (b >= 0x61 && b <= 0x66) || (b >= 0x41 && b <= 0x46)
+
+/**
+ * 建流式分块解码器（消费单点 = `proxy-transport.mjs` `streamHttpResponse` chunked 径）。
+ * @param {{ onData?: (chunk: Buffer) => void, onEnd?: () => void }} [handlers]
+ *   `onData` 逐段收解码后的块数据（任意分包边界）；`onEnd` 于 `0` 块到达时触发一次。
+ * @returns {{ push: (buf: Buffer) => void, mode: "chunked" | "raw" | "done" }}
+ *   `push` 喂入原始字节；`mode` = `chunked`（解码中）∥ `raw`（畸形回退透传）∥
+ *   `done`（`0` 块已终，其后字节读取即弃）——供测试与诊断。
+ */
+export function createChunkedDecoder({ onData, onEnd } = {}) {
+  let state = "size" // size → data → crlf → size …
+  let mode = "chunked"
+  let buf = EMPTY // 未消费字节（只保有帧头——块数据即到即吐）
+  let need = 0 // data 阶段待吐字节数
+
+  const emit = (chunk) => { if (chunk.length > 0) onData?.(chunk) }
+  /** 畸形回退：已持有字节原样吐出，此后全量直通（不再解析）。 */
+  const fallback = () => {
+    mode = "raw"
+    const held = buf
+    buf = EMPTY
+    emit(held)
+  }
+  /** `0` 块终：body 随 0 块结束。 */
+  const finish = () => { mode = "done"; buf = EMPTY; onEnd?.() }
+
+  /** 帧推进：逐状态消费 buf；块数据即吐（只保有帧头）。 */
+  function step() {
+    for (;;) {
+      if (state === "size") {
+        const idx = buf.indexOf(CRLF)
+        if (idx < 0) {
+          // 未成行：首字节非十六进制 ∥ 超限 ⇒ 畸形；否则等下一包
+          if (buf.length > 0 && !isHexByte(buf[0])) return fallback()
+          if (buf.length > MAX_SIZE_LINE) return fallback()
+          return
+        }
+        const line = buf.subarray(0, idx)
+        const semi = line.indexOf(0x3b) // ";"——块扩展起点（忽略）
+        const hex = semi < 0 ? line : line.subarray(0, semi)
+        // 畸形行（超限 ∥ 空 ∥ 非十六进制）⇒ 整段原样吐出（行 ∥ CRLF 零丢弃——不截断）；行有效才消费
+        if (idx > MAX_SIZE_LINE || hex.length === 0) return fallback()
+        for (const b of hex) if (!isHexByte(b)) return fallback()
+        const size = Number.parseInt(hex.toString("latin1"), 16)
+        if (!Number.isSafeInteger(size)) return fallback() // 数值越界（>2^53——double 溢出可为 Infinity）⇒ 归畸形
+        buf = buf.subarray(idx + 2)
+        if (size === 0) return finish()
+        need = size
+        state = "data"
+        continue
+      }
+      if (state === "data") {
+        if (buf.length === 0) return
+        const take = Math.min(buf.length, need)
+        emit(buf.subarray(0, take))
+        buf = buf.subarray(take)
+        need -= take
+        if (need > 0) return
+        state = "crlf"
+        continue
+      }
+      // state === "crlf"：块尾须恰为 CRLF
+      if (buf.length < 2) {
+        if (buf.length === 1 && buf[0] !== 0x0d) return fallback()
+        return
+      }
+      if (buf[0] !== 0x0d || buf[1] !== 0x0a) return fallback()
+      buf = buf.subarray(2)
+      state = "size"
+    }
+  }
+
+  return {
+    push(d) {
+      if (mode === "done") return // 0 块后余字节（trailer 等）读取即弃
+      if (mode === "raw") { emit(d); return }
+      buf = buf.length > 0 ? Buffer.concat([buf, d]) : d
+      step()
+    },
+    get mode() { return mode },
+  }
+}

package/proxy-target.mjs

@@ -0,0 +1,54 @@
+/**
+ * proxy-target.mjs — 代理目标 ∥ 配置解析面（2026-10-08 拆档——原 `proxy.mjs` 迁出；#1037）。
+ * 逐渠判定 = 渠道旗 `providers[].proxy` ∧ `proxy.uri` 在案（无全局闸——D-PX1，2026-10-08 批落）。
+ * 零依赖：Node built-ins only（net, url）。
+ */
+import { isIP } from "node:net"
+import { URL } from "node:url"
+
+/**
+ * Resolve proxy URI.
+ * New format: { proxy: { uri: "http://host:port", web: true } }
+ * Old format: { proxy: "http://host:port" } — backwards compatible, web=true
+ * Env vars: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY
+ *
+ * @returns {{ uri: string|null, web: boolean }}
+ */
+export function resolveProxyConfig(ctx) {
+  const cfgProxy = ctx?.agent?.config?.proxy
+  if (!cfgProxy) {
+    const uri = process.env.HTTPS_PROXY || process.env.HTTP_PROXY || process.env.ALL_PROXY || null
+    return { uri, web: !!uri }
+  }
+  if (typeof cfgProxy === "string") {
+    // Backward compat: bare string → web only
+    return { uri: cfgProxy, web: true }
+  }
+  return {
+    uri: cfgProxy.uri || cfgProxy.url || null,
+    web: cfgProxy.web !== false,
+  }
+}
+
+/** Convenience: resolve proxy URI for web tools (websearch/fetch) */
+export function resolveWebProxy(ctx) {
+  const cfg = resolveProxyConfig(ctx)
+  return (cfg.uri && cfg.web) ? cfg.uri : null
+}
+
+/**
+ * Loopback 目标判定（NO_PROXY 语义——#1026，2026-10-07 用户案）：
+ * `localhost` ∥ `*.localhost`（RFC 6761）∥ `127.0.0.0/8` ∥ `::1` —— 此类目标永不经代理。
+ * 解析失败 ⇒ false（未知串不宣称 loopback）；尾点（`localhost.`）先归一。
+ */
+export function isLoopbackTarget(urlStr) {
+  let host
+  try { host = new URL(urlStr).hostname } catch { return false }
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1) // IPv6 带括号（URL.hostname 规范形）
+  if (host.endsWith(".")) host = host.slice(0, -1)
+  if (host === "localhost" || host.endsWith(".localhost")) return true
+  const v = isIP(host)
+  if (v === 4) return host.split(".")[0] === "127"
+  if (v === 6) return host === "::1"
+  return false
+}

package/proxy-transport.mjs

@@ -0,0 +1,298 @@
+/**
+ * proxy-transport.mjs — 传输面（2026-10-08 拆档——原 `proxy.mjs` 迁出；#1037）：
+ * CONNECT 隧道 ∥ 经典转发 ∥ 流式响应。`FETCH_TIMEOUT` = CONNECT/TLS 与经典转发建连超时（15s；
+ * 响应头阶段另有 `opts._headerTimeoutMs`）。
+ * 响应体 `Transfer-Encoding: chunked` ⇒ 解码器剥帧（`proxy-chunked.mjs`；#1065）；单 token 已知
+ * `content-encoding`（gzip ∥ x-gzip ∥ deflate ∥ br）⇒ 剥帧后接解压器（#1067）。chunked 径背压：
+ * body 前最后一级可写流拒收 ⇒ 暂停上游源，排空 ⇒ 恢复（#1087）。
+ * 零依赖：Node built-ins only（net, tls, stream, url, zlib）。
+ */
+import { connect } from "node:net"
+import { connect as tlsConnect } from "node:tls"
+import { PassThrough } from "node:stream"
+import { URL } from "node:url"
+import { createBrotliDecompress, createGunzip, createInflate } from "node:zlib"
+import { abortError, timeoutError } from "./abort-provenance.mjs"
+import { createChunkedDecoder } from "./proxy-chunked.mjs"
+import { destroyBody } from "./stream-destroy.mjs"
+
+export const FETCH_TIMEOUT = 15_000
+
+/** 响应头终止序列（头阶段按字节累积——#1065 K5：chunked 首段须以字节交接）。 */
+const HEADER_END = Buffer.from("\r\n\r\n")
+
+/** content-encoding 解压器族（#1067——单 token 且已列 ⇒ 解压；identity ∥ 未知 ∥ 多 token 列表透传）。 */
+const CE_DECODERS = { gzip: createGunzip, "x-gzip": createGunzip, deflate: createInflate, br: createBrotliDecompress }
+
+/**
+ * 在已建立的 socket 上发 HTTP 请求，响应头到齐即 resolve（流式）。
+ * 返回 Response-like: { ok, status, headers: Headers, body: PassThrough(异步迭代), text(): Promise<string> }
+ * body 边收边吐（SSE 流式消费方可逐 chunk 读取）；text() 消费流到底（非流式调用方用）。
+ * 响应头 `Transfer-Encoding: chunked` ⇒ 体经 `proxy-chunked.mjs` 解码器剥帧后入 body（#1065；
+ * 流式保形、畸形帧回退透传、`0` 块 ⇒ body 结束）；单 token 已知 `content-encoding` ⇒ 剥帧后接
+ * 解压器（#1067）；chunked 径背压 ⇒ 暂停上游源 / 排空恢复（#1087）；非 chunked 无 CE 径零动。
+ * opts.signal 全程有效：abort 即 destroy socket 并 reject/终止流。
+ * absoluteForm: 请求行发绝对 URI（http:// 目标的经典代理转发用），默认发 origin-form。
+ * 2026-08-31 会诊 #4：timeout 只覆盖"响应头阶段"；settle 后 body 空闲 > bodyIdleMs 即
+ * 断流（原实现头部 timer 到齐即清，流式中途停摆会无限挂起直到用户 Ctrl+C）。
+ * bodyIdleMs 默认 120s（provider 长生成用 0 即禁用，由调用方决定）。
+ * 导出供测试（裸 socket，无需 TLS/CONNECT）；生产路径走 tunnelHttps / proxyFetch。
+ */
+export function streamHttpResponse(sock, urlStr, opts = {}, timeout = FETCH_TIMEOUT, absoluteForm = false, bodyIdleMs = 120_000) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(urlStr)
+    const method = opts.method ?? "GET"
+    const headers = opts.headers ?? {}
+    const signal = opts.signal
+
+    if (signal?.aborted) { sock.destroy(); return reject(abortError(signal, "provider", "proxy")) }
+
+    const body = new PassThrough()
+    let settled = false
+    let headerBuf = Buffer.alloc(0) // 头阶段按字节累积（#1065 K5——替代 utf8 往返）
+    let idleTimer = null
+    let sink = null            // body 前解压器（单 token 已知 content-encoding 时建立——#1067；无则 null）
+    let sawInput = false       // 解压器输入门（#1067）：零输入（空体）+ CE 在场 ⇒ 不解压（零误报）
+    let pausedUpstream = false // 背压旗（#1087）：sock.pause() 在场，幂等守卫
+
+    const timer = setTimeout(() => fail(timeoutError("Response timeout", "provider", "proxy-header")), timeout)
+    const onAbort = () => { sock.destroy(); fail(abortError(signal, "provider", "proxy")) }
+    signal?.addEventListener("abort", onAbort, { once: true })
+
+    function cleanup() {
+      clearTimeout(timer)
+      clearTimeout(idleTimer)
+      signal?.removeEventListener("abort", onAbort)
+    }
+    /** 头部阶段失败 reject；resolve 后失败则终止 body 流（for-await 抛出，不挂起） */
+    function fail(err) {
+      cleanup()
+      if (!settled) { settled = true; reject(err) }
+      else destroyBody(body, err)
+    }
+    /** 背压暂停上游源（#1087——幂等：排空前只暂停一次） */
+    function pauseUpstream() {
+      if (!pausedUpstream) { pausedUpstream = true; sock.pause() }
+    }
+    /** 排空恢复上游源（#1087——暂停态对偶分支，幂等） */
+    function resumeUpstream() {
+      if (pausedUpstream) { pausedUpstream = false; sock.resume() }
+    }
+    /** body 结束（幂等——`0` 块 ∥ 对端 close 两径都会到达；#1065）：带 CE 且已收输入 ⇒ 先结解压器
+     *  （flush 后经 pipe 结 body）；零输入（空体 + CE 在场）⇒ 直结 body（sawInput 门——#1067，零误报）。 */
+    function endBody() {
+      if (sink && sawInput) {
+        if (!sink.destroyed && !sink.writableEnded) sink.end()
+        return
+      }
+      if (!body.destroyed && !body.writableEnded) body.end()
+    }
+    /** 推入 body 前最后一级可写流（带 CE = 解压器 ∥ 无 CE = body——#1087 暂停触发级）；
+     *  `write()` 返 false ⇒ 暂停上游源（排空后 'drain' 恢复）；终止后不再写（watchdog ∥ abort ∥
+     *  `0` 块后余包，与非 chunked 径 pipe 自摘语义齐）。 */
+    function pushDownstream(chunk) {
+      const target = sink ?? body
+      if (target.destroyed || target.writableEnded) return
+      if (sink) sawInput = true
+      if (target.write(chunk) === false) pauseUpstream()
+    }
+    /** body 阶段空闲看门狗：每次数据到达重置；无数据超时 → 断流（流式消费方抛错） */
+    function armIdle() {
+      clearTimeout(idleTimer)
+      if (bodyIdleMs > 0) idleTimer = setTimeout(() => destroyBody(body, timeoutError("Response body timeout (idle)", "provider", "proxy-body-idle")), bodyIdleMs)
+    }
+
+    sock.on("data", (d) => {
+      if (settled) return // 理论上不会发生（settle 后摘掉本监听器），防御
+      headerBuf = headerBuf.length > 0 ? Buffer.concat([headerBuf, d]) : d
+      const idx = headerBuf.indexOf(HEADER_END)
+      if (idx < 0) return
+
+      const headerText = headerBuf.subarray(0, idx).toString("utf8")
+      const statusMatch = headerText.match(/^HTTP\/\d\.\d (\d+)/)
+      const status = statusMatch ? Number(statusMatch[1]) : 502
+      const respHeaders = {}
+      for (const line of headerText.split("\r\n").slice(1)) {
+        const ci = line.indexOf(":")
+        if (ci > 0) respHeaders[line.slice(0, ci).trim().toLowerCase()] = line.slice(ci + 1).trim()
+      }
+
+      // 头到齐：摘掉头阶段监听；剩余字节（字节副本）按 TE 分径交接
+      sock.removeAllListeners("data")
+      settled = true
+      cleanup()
+      armIdle()
+      const remaining = Buffer.from(headerBuf.subarray(idx + 4))
+      // 判定按 Transfer-Encoding 末段 token（大小写不敏感）；头缺席而帧在场（协议违规）不解码
+      const chunked = (respHeaders["transfer-encoding"] ?? "").split(",").pop().trim().toLowerCase() === "chunked"
+      // 内容编码解压阶段（#1067——TE 剥帧后接，chunked ∥ 非 chunked 两径同点）：单 token 且已列编码
+      // 建解压器；identity ∥ 头缺席 ∥ 未知编码 ∥ 多 token 列表 ⇒ 透传零动。请求头零改（不发
+      // Accept-Encoding——上游自发压缩才走本阶段）。
+      const ceTokens = (respHeaders["content-encoding"] ?? "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)
+      const ceFactory = ceTokens.length === 1 ? CE_DECODERS[ceTokens[0]] : undefined
+      if (ceFactory) {
+        sink = ceFactory()
+        // 解压失败 ⇒ body 以明错误终止（部分解码已发生——无「原字节」可回退）；解压器 ⇒ body 走 pipe
+        // （自带背压：body 慢 ⇒ 解压器停 ⇒ 其可写侧涨满 ⇒ 推送分支暂停源）。
+        sink.on("error", (e) => fail(new Error(`Response body decompression failed (content-encoding: ${ceTokens[0]}): ${e.message}`)))
+        sink.pipe(body)
+      }
+      if (chunked) {
+        // chunked 径：解码器剥帧 ⇒ 逐段推入 body 前最后一级（带 CE = 解压器；函数式改写——body 本体零替换）；
+        // 不再 pipe——body 由解码器 onData/onEnd 驱动
+        const decoder = createChunkedDecoder({ onData: pushDownstream, onEnd: endBody })
+        sock.on("data", (c) => decoder.push(c)) // 推送分支 = 背压暂停点（#1087：write() 返 false ⇒ sock.pause()）
+        decoder.push(remaining)
+      } else if (sink) {
+        // 非 chunked 径 · 带 CE：源 ⇒ 解压器（推送分支同形——背压暂停点同判）
+        if (remaining.length > 0) pushDownstream(remaining)
+        sock.on("data", pushDownstream)
+      } else {
+        // 非 chunked 径 · 无 CE：原样直写 + pipe（现状语义，零动）
+        if (remaining.length > 0) body.write(remaining)
+        sock.pipe(body)
+      }
+      // 空闲看门狗随数据到达重置。注意必须用 'readable' 而非 'data'：
+      // 'data' 监听把流切成 flowing 模式，会抢走 readSSE/for-await 未来得及认领的
+      // 已写缓冲（2026-08-31 实测：分包响应头的 remaining 首段被吞，readSSE 等不到 ack）。
+      // 'readable' 不改变流模式，数据仍由消费方按需拉取。
+      body.on("readable", armIdle)
+      // 背压排空 = 消费进度信号（#1087——防「暂停期无数据到达」把慢而健康的消费者误杀）。
+      body.on("drain", armIdle)
+      // 背压对偶分支：排空 ⇒ 恢复上游源。带 CE 时恢复信号在解压器（body 经 pipe 先恢复解压器——链传导）；
+      // 无 CE 时 body 即最后一级 ⇒ 其 drain 即恢复点。
+      if (sink) sink.on("drain", resumeUpstream)
+      else body.on("drain", resumeUpstream)
+      // body 结束后才移除 abort 监听（流式中途 abort 要能终止流）；空闲看门狗一并清
+      body.on("close", () => {
+        clearTimeout(idleTimer)
+        signal?.removeEventListener("abort", onAbort)
+        // 停止门（#1087 评审 F3）：body 终止时上游仍在背压暂停态 ⇒ 先恢复再销毁源——
+        // 被暂停的 sock 不因 body 消亡自行关闭（悬挂口）。
+        if (pausedUpstream) { pausedUpstream = false; sock.resume(); sock.destroy() }
+      })
+      signal?.addEventListener("abort", onAbort, { once: true })
+
+      resolve({
+        ok: status >= 200 && status < 400,
+        status,
+        headers: new Headers(respHeaders),
+        body,
+        text: async () => {
+          const chunks = []
+          for await (const c of body) chunks.push(c)
+          return Buffer.concat(chunks).toString("utf8")
+        },
+      })
+    })
+    sock.on("close", () => {
+      if (!settled) fail(new Error("Connection closed before response"))
+      else endBody()
+    })
+    // 头部阶段的传输错误统一包装为稳定契约（对端 RST 会抛原生 ECONNRESET，调用方难判别）；
+    // resolve 后的 body 阶段保留原始错误终止流
+    sock.on("error", (e) => {
+      if (!settled) fail(new Error(`Connection closed before response (${e.code ?? e.message})`))
+      else fail(e)
+    })
+
+    // 写请求（absoluteForm：代理转发时请求行为绝对 URI）
+    const requestTarget = absoluteForm ? urlStr : `${target.pathname}${target.search}`
+    const lines = [`${method} ${requestTarget} HTTP/1.1`]
+    for (const [k, v] of Object.entries({ ...headers, Host: target.hostname })) lines.push(`${k}: ${v}`)
+    lines.push("Connection: close", "", "")
+    sock.write(lines.join("\r\n"))
+    if (opts.body) sock.write(opts.body)
+  })
+}
+
+/**
+ * HTTPS request through HTTP CONNECT proxy tunnel.
+ * CONNECT + TLS 建立后交给 streamHttpResponse — 响应头到齐即 resolve，body 为流式。
+ * 2026-08-31 会诊 #1/#4：
+ *  - TLS 默认全量证书校验（rejectUnauthorized: true）——走代理的流量（含 API key）
+ *    不得在未验证链路上传输；确需自签/内网代理时 opts.insecureTls=true 显式放行。
+ *  - CONNECT/TLS 阶段用 timeout（默认 15s，建隧道快）；**响应头超时**用
+ *    opts._headerTimeoutMs（默认 60s）——原实现共用 15s，DeepSeek 排队 TTFB>15s
+ *    即误报 "Response timeout"，与直连 600s 语义割裂。
+ */
+export function tunnelHttps(urlStr, opts, proxyUri, timeout = FETCH_TIMEOUT) {
+  return new Promise((resolve, reject) => {
+    let target, proxy
+    try {
+      target = new URL(urlStr)
+      proxy = new URL(proxyUri)
+    } catch {
+      // 融合（§2.5 #74——取双侧并集）：VSC 侧的**坏代理串友好报错**并入核内——
+      // 原生 `Invalid URL` 不解释期望形态，调用方拿到的可观测文案退化。
+      return reject(new Error(`Invalid proxy URI: "${proxyUri}" — expected http://host:port`))
+    }
+    const signal = opts?.signal
+    const headerTimeoutMs = Number.isFinite(opts?._headerTimeoutMs) ? opts._headerTimeoutMs : 60_000
+    const bodyIdleMs = opts?._bodyIdleMs ?? 120_000
+
+    if (signal?.aborted) return reject(abortError(signal, "provider", "proxy"))
+
+    const sock = connect({ host: proxy.hostname, port: Number(proxy.port) || 3128 })
+    const timer = setTimeout(() => { sock.destroy(); reject(new Error("Proxy CONNECT timeout")) }, timeout)
+    const onAbort = () => { sock.destroy(); reject(abortError(signal, "provider", "proxy")) }
+    signal?.addEventListener("abort", onAbort, { once: true })
+    sock.on("connect", () => sock.write(`CONNECT ${target.hostname}:${target.port || 443} HTTP/1.1\r\nHost: ${target.hostname}\r\n\r\n`))
+
+    let buf = ""
+    sock.on("data", d => {
+      buf += d.toString()
+      const end = buf.indexOf("\r\n\r\n")
+      if (end < 0) return
+      const statusLine = buf.slice(0, end).split("\r\n")[0]
+      buf = buf.slice(end + 4)
+      if (!statusLine.includes("200")) { sock.destroy(); clearTimeout(timer); return reject(new Error(`Proxy CONNECT: ${statusLine}`)) }
+      sock.removeAllListeners("data"); clearTimeout(timer)
+
+      // 安全默认：TLS 全量校验。企业中间人代理场景显式 opts.insecureTls=true 才放行。
+      const tlsSock = tlsConnect({ socket: sock, servername: target.hostname, rejectUnauthorized: opts?.insecureTls !== true })
+      if (buf) tlsSock.unshift(Buffer.from(buf))
+      tlsSock.on("secureConnect", () => {
+        // TLS 之后的请求/响应阶段：abort 交由 streamHttpResponse 接管
+        signal?.removeEventListener("abort", onAbort)
+        streamHttpResponse(tlsSock, urlStr, opts, headerTimeoutMs, false, bodyIdleMs).then(resolve, reject)
+      })
+      tlsSock.on("error", e => { sock.destroy(); reject(e) })
+    })
+    sock.on("error", e => { clearTimeout(timer); reject(new Error(`Proxy CONNECT failed (${e.code ?? e.message})`)) })
+    // 代理干净 FIN 关闭（无 error）时也要 reject，不能卡满超时
+    sock.on("close", () => { clearTimeout(timer); reject(new Error("Proxy connection closed before tunnel established")) })
+  })
+}
+
+/** TCP 直连代理（http:// 目标的经典转发用）：超时/abort/对端关闭都有稳定 reject */
+export function tcpConnectProxy(proxyUri, signal, timeout) {
+  return new Promise((resolve, reject) => {
+    let proxy
+    try {
+      proxy = new URL(proxyUri)
+    } catch {
+      // 融合（§2.5 #74）：同 tunnelHttps——坏代理串友好报错。
+      return reject(new Error(`Invalid proxy URI: "${proxyUri}" — expected http://host:port`))
+    }
+    const sock = connect({ host: proxy.hostname, port: Number(proxy.port) || 3128 })
+    if (signal?.aborted) { sock.destroy(); return reject(abortError(signal, "provider", "proxy")) }
+    const onAbort = () => sock.destroy()
+    signal?.addEventListener("abort", onAbort, { once: true })
+    const timer = setTimeout(() => { sock.destroy(); reject(new Error("Proxy CONNECT timeout")) }, timeout)
+    const onError = (e) => { clearTimeout(timer); reject(new Error(`Proxy CONNECT failed (${e.code ?? e.message})`)) }
+    const onClose = () => {
+      clearTimeout(timer)
+      reject(signal?.aborted ? abortError(signal, "provider", "proxy") : new Error("Proxy connection closed before tunnel established"))
+    }
+    sock.once("connect", () => {
+      clearTimeout(timer)
+      signal?.removeEventListener("abort", onAbort)
+      sock.removeListener("error", onError)
+      sock.removeListener("close", onClose)
+      resolve(sock)
+    })
+    sock.once("error", onError)
+    sock.once("close", onClose)
+  })
+}