[Bug 修复] web_fetch 加载 undici 污染全局 dispatcher，导致代理环境下"模型不可用"

[cambrianlee]

Environment

• OS：Linux（国产发行版，x86_64，需经公司 HTTP 代理访问外网）
• Node：v24.13.1（nvm 管理）
• dsh：0.1.2-alpha.1（本地源码 checkout，pnpm dsh web 启动）
• 网络：必须经 HTTP 代理访问 LLM API 与外部站点；curl / npm / pip 均可正常走代理
• 代理环境变量：NODE_USE_ENV_PROXY=1，http_proxy / https_proxy 已设置（指向公司代理），no_proxy 覆盖内网网段与内网域名

一、问题现象

在必须通过 HTTP 代理访问外网的环境下（NODE_USE_ENV_PROXY=1 + http_proxy/https_proxy），出现如下可复现的故障链：

1. 启动 dsh web 后一切正常（模型对话、web_search 均可用）；
2. 一旦 web_fetch 抓取外部 URL 失败（报 TypeError: fetch failed），之后模型就不可用了（LLM 调用不再走代理，全部失败）；
3. Ctrl+C 重启 dsh web 后临时恢复；
4. 再次触发 web 搜索失败，又故障。

即：一次失败的 web 抓取会"污染"整个进程，直到重启。

二、根因分析（以下是dsh协助分析结论）

问题出在 packages/web/web-fetch-http/src/network.ts 的 requestPinned，由两个叠加的 bug 构成。

根因 1（主因）：await import('undici') 覆盖了 Node 内置 fetch 的全局 dispatcher

requestPinned 通过 await import('undici') 动态加载 undici@8。undici@8 的 lib/global.js 在模块顶层会执行：

if (getGlobalDispatcher() === undefined) {
  setGlobalDispatcher(new Agent())  // 不带代理的普通 Agent！
}

它读取的是 Symbol.for('undici.globalDispatcher.2')（undici@8 自己的符号，初始为 undefined），于是安装了一个不走代理的普通 Agent，并连带把 Symbol.for('undici.globalDispatcher.1')（Node 内置 fetch 依赖的符号）覆盖成 Dispatcher1Wrapper(Agent)。

实验证据（Node v24.13.1，代理环境）：

[0] 初始          : sym1 = EnvHttpProxyAgent  | sym2 = undefined   ← 全局 fetch 走代理，正常
[1] 全局 fetch    : OK 200
[2] 加载 undici 后 : sym1 = Dispatcher1Wrapper | sym2 = Agent      ← 被覆盖！
[3] 全局 fetch    : FAIL This operation was aborted                 ← 不走代理，直连超时

globalThis.fetch 是 LLM 调用（llm-deepseek adapter）和 web_search（web-search-deepseek provider）共同的传输通道。因此 undici 一旦被加载，进程内所有后续 globalThis.fetch 都失去代理支持 → "模型不可用"，直到进程重启重置全局状态。

根因 2（次因）：requestPinned 自建 Agent 不走代理

原代码用 new Agent({ autoSelectFamily: true, connect: { lookup } }) 直连目标，完全无视代理环境变量。在代理网络里直连被防火墙丢弃，导致 web_fetch 本身必然失败（实测 6 秒超时后 TypeError: fetch failed）。

三、修复方案

全部修改在 packages/web/web-fetch-http/src/network.ts：

1. importUndiciWithoutGlobalPollution()：在 import('undici') 前后保存/恢复 Symbol.for('undici.globalDispatcher.1'/.2') 两个符号，消除模块加载副作用，使 import 成为"纯缓存填充"——Node 内置 fetch 保持其代理感知的 dispatcher。

2. proxyEnvironment()：解析 http_proxy/https_proxy/NODE_*_PROXY/NO_PROXY 等别名（含 Node 的 NODE_HTTP(S)_PROXY，undici@8 的类本身不读这些）：

   • 有代理 → 改用 EnvHttpProxyAgent（与 globalThis.fetch 走同一条代理通道）；
   • 无代理 → 保持原有 pinned-lookup 直连（SSRF 防护不降级）。

关键代码：

const undici = await importUndiciWithoutGlobalPollution()
const proxy = proxyEnvironment()
const dispatcher = proxy === undefined
  ? new Agent({
      autoSelectFamily: true,
      connect: { lookup: createPinnedLookup(addresses) },
    })
  : new undici.EnvHttpProxyAgent({ autoSelectFamily: true, ...proxy })

四、验证结果

检查项	结果
单元测试 fetch-http.spec.ts	62/62 通过（新增 2 个测试：代理分支选择、全局 dispatcher 隔离）
tsc -b 类型检查	通过
oxlint	0 warnings 0 errors
端到端（真实代理环境）	修复后 requestPinned 抓取 patents.google.com 返回 200，随后全局 fetch（LLM 路径）仍 200

修复前，上述两条路径在代理环境下均必然失败。

五、改动文件

• packages/web/web-fetch-http/src/network.ts（+87/-7）
• packages/web/web-fetch-http/tests/fetch-http.spec.ts（+68）

六、备注

• 修复只改了 web-fetch-http 包，不影响 web_search（其本身一直走 globalThis.fetch，只是会被根因 1 的全局污染连带拖垮）。
• 无代理环境下行为完全不变（仍走 pinned-lookup 直连，SSRF 防护保持）。
• 该 bug 的影响面不仅限于代理环境：任何"先加载 undici、后使用 globalThis.fetch 且依赖 Node 内置代理配置"的场景都会踩中根因

[weijiafu14]

代理环境这族坑 +1，你定位的"全局 dispatcher 被污染"和我们撞过的兄弟坑可以拼成完整地图，给后来人：

• 坑 A（你这个）：web_fetch 加载 undici 时覆盖了全局 dispatcher，把本来配好的代理设置冲掉 → "模型不可用"。
• 坑 B（[BUG] 代理环境下 LLM API 请求全部失败：Node fetch (undici) 不读取 HTTP_PROXY/HTTPS_PROXY 环境变量 #3985/[feat request] 主进程launch时自注入NODE_USE_ENV_PROXY,使得llm-pi-ai可以走代理端口 #1171）：undici 的 fetch 默认就不读 HTTP_PROXY/HTTPS_PROXY——不开 NODE_USE_ENV_PROXY=1 时，代理环境下 LLM 调用从一开始就不通。我们的端到端装置在代理网络上全灭过一轮，最后把这个开关永久烤进了 harness（尸检注释）。

两坑叠加的判据：设了 NODE_USE_ENV_PROXY=1 仍然在用过 web_fetch 之后才断的，就是你这个 dispatcher 污染；从头就不通的，是坑 B。修复方向也一致：别动全局 dispatcher（web_fetch 用自己的 client 实例），代理配置在启动层统一注入——你的补丁打的正是对的位置。

[argszero]

独立复现验证了根因 1 的机制（Node 26.5.0 + undici 8.10.0，npm 包从零安装），给你补两个实验证据 + 一个版本 nuance，并交叉映射 #5124：

实验 1：import() 本身就有全局副作用（不需要任何 API 调用）

const sym1 = Symbol.for('undici.globalDispatcher.1')
const sym2 = Symbol.for('undici.globalDispatcher.2')
// 初始（未触发任何 fetch、未加载 undici）
//   sym1 = undefined | sym2 = undefined
await import('undici')
//   sym1 = Dispatcher1Wrapper | sym2 = Agent
//   getGlobalDispatcher() = Agent   ← 已被 npm undici 的默认 Agent 顶替

纯模块加载即写入共享符号——你说的「import 有副作用」成立，且与你修复方案的恢复点（保存/恢复这两个符号）精确对应。

实验 2：Node 内置 fetch 与 npm undici 共用同一符号命名空间

NODE_USE_ENV_PROXY=1 node ...   （先触发一次 global fetch 再 import）
[0] 首次 fetch 后 : sym1 = Dispatcher1Wrapper | sym2 = Agent
[2] import 后     : sym1 = Dispatcher1Wrapper | sym2 = Agent
getGlobalDispatcher() = Agent

注意这里与你在 Node v24.13.1 的观测差异：v24 首次 fetch 后 sym1 = EnvHttpProxyAgent（Node 直接装代理感知 dispatcher），v26.5.0 首次 fetch 后 sym1 已是 Dispatcher1Wrapper——Node 26 的内置 fetch 实现本身就把自己的 wrapper 写进了同一个符号。结论：共享符号机制跨版本一致（这就是污染面），但「初始态长什么样」随 Node 版本而变——代理环境的用户可以用 undici.getGlobalDispatcher().constructor.name 自查当前在哪个状态。

对你修复方案的验证：保存/恢复 Symbol.for('undici.globalDispatcher.1'/.2') 两个符号正是正确的恢复点——实验证明 import 写的就是这两个。你的 importUndiciWithoutGlobalPollution() 方向成立。

交叉映射 #5124：d3vmeh 的 dsh-fetch-timeouts 插件也在模块顶 import { getGlobalDispatcher, setGlobalDispatcher } from 'undici'（同属「加载即触发全局副作用」这一类），且其 unload 的 no-clobber 守卫（getGlobalDispatcher() === agent 才恢复）正好可能被 import 副作用击败——你的修复让「import 变纯缓存填充」后，这类插件的守卫也变得更可靠。两条线（bug 修复 + 社区插件）拼在同一点上，值得互见。