@zhushanwen/pi-network-proxy 0.3.0 → 0.3.2

package/README.md

@@ -5,20 +5,23 @@ LLM 网络代理分流：包装 pi 进程的 `globalThis.fetch`，按主机名
 ## 行为摘要
 
 - **拦截点**：`globalThis.fetch`。pi-ai 的 OpenAI 兼容请求在每次构造 client 时经 `Shims.getDefaultFetch()` 动态取当前全局 fetch，包装它不依赖 pi 与扩展共享 undici 模块实例
-- **安装/卸载**：extension 加载时读配置，`enabled` 且校验通过 → 包装并构造代理 dispatcher；`enabled` false → 恢复原 fetch；校验/构造失败 → extension error（含配置文件恢复指引），不包装不阻断 pi（全部直连）
+- **安装/卸载**：extension 加载时读配置，`enabled` 开启或 `ipv4Only` 非空且校验通过 → 包装（`enabled` 且命中规则走代理 dispatcher，`ipv4Only` 命中锁 IPv4 直连，后者不受开关影响）；`enabled` false 且 `ipv4Only` 空 → 恢复原 fetch；校验/构造失败 → extension error（含配置文件恢复指引），不包装不阻断 pi（全部直连）
 - **热生效**：turn 粒度——每 turn 开始重读配置（mtime+size 读时刷新），指纹变化才重建；pi 的 `configureHttpDispatcher` 带 shouldInstallGlobals 守卫（pi dist/core/http-dispatcher.js:88-99：检测到 `globalThis.fetch` 已被第三方覆盖即保留不重装），本扩展的包装在同进程内持续生效；槽位被其他第三方覆盖时下一 turn 自动以覆盖者为新 original 重新包装（防御路径）
-- **匹配语义**：主机名归一化（小写、去末尾点）后 suffix 匹配（等于或以 `.条目` 结尾，点边界对齐）；noProxy 优先于 rules
+- **匹配语义**：主机名归一化（小写、去末尾点）后 suffix 匹配（等于或以 `.条目` 结尾，点边界对齐）；优先级 noProxy > ipv4Only > rules（rules 另受 `enabled` 门控）
 - **覆盖面**：经 `globalThis.fetch` 发出的请求（pi LLM 调用与 OAuth/目录请求均走 fetch）；直接使用 `undici.request` / `Client` 的调用与 WebSocket 升级请求不经过本包装
 - **计数**：请求发起时 +1（内存按主机名聚合），turn 结束 / 进程退出把增量追加写入 `<agentDir>/network-proxy-stats.jsonl`（每行完整 JSON `{ts, host, proxied, direct}`，单次 write 单行——多进程并发追加不交错）；写失败 log 不阻断
-- **降级契约**：socks5 构造失败（undici 实验性 API）→ 记错误、恢复原 fetch、全部直连，切回 http 协议恢复；同指纹不重试构造，配置修正（指纹变化）后自然重试
+- **降级契约**：socks5 构造失败（副本缺 `Socks5ProxyAgent`，见下节副本策略 / undici 实验性 API 变化）→ 记错误、恢复原 fetch、全部直连，切回 http 协议恢复；同指纹不重试构造，配置修正（指纹变化）后自然重试
 
 ## 为什么包装 fetch 而不是 undici 全局 dispatcher
 
-undici 的 `setGlobalDispatcher` 槽是模块级变量，只有「pi 与扩展加载同一份 undici 模块实例」时才生效：
+undici 的 `setGlobalDispatcher` 槽是模块级变量，只有「pi 与扩展加载同一份 undici 模块实例」时才生效。本包的 undici 按宿主运行时解析（见下节），与 pi 自己的 HTTP 栈不保证同实例——扩展安装的全局分流器 pi 可能根本不用（打包版实测：请求静默直连、统计为空）。`globalThis.fetch` 是两套实现之间稳定的接缝（pi-ai / OpenAI SDK 每次构造 client 时动态读取），因此拦截点定在这里。
 
-- 独立 pi（`node_modules/.bin/pi`）与扩展源码都从 `node_modules/undici` 解析，实例相同，旧方案可用
-- 打包版 pi 是单文件二进制，HTTP 栈用内置 undici（`builtin://thirdparty/undici`）；扩展 bundle 由 esbuild 内联自己的 undici 副本。两套全局槽互不相通——扩展安装的分流器 pi 根本不会使用，LLM 请求静默直连、统计为空
-- `globalThis.fetch` 是两套实现之间稳定的接缝（pi-ai / OpenAI SDK 每次构造 client 时动态读取），因此拦截点定在这里
+## undici 副本策略（按宿主解析）
+
+构建期不内联 undici（bundle external），运行时由宿主解析：Node 宿主（独立 pi / dev）从 `node_modules` 解析 npm 副本；Bun 宿主（打包版 pi）解析二进制内置副本（`builtin://thirdparty/undici`，Bun 团队随 Bun 版本适配）。每个宿主用自己官方维护的网络栈。
+
+- **不得回退内联**：npm undici 副本在 Bun 兼容层下 `fetch` 读 chunked 流式响应体永不产块（LLM SSE 请求挂死，2026-10-22 事故实测）
+- **能力面差异**：内置副本无 `Socks5ProxyAgent`——**打包版不支持 socks5 代理**（构造时明确报错并保持全部直连，改用 http/https 恢复）；`Agent` / `ProxyAgent` / `buildConnector` / `fetch` 两副本都有且流式行为实测正常（含 IPv4 锁定与 http 代理分支）
 
 ## 配置
 
@@ -38,7 +41,7 @@ taiji 桌面端经设置页「网络代理」读写（runtime RMW 写侧）；
 ## 两协议构造契约（防回归锚）
 
 - http/https：`ProxyAgent` 调优经 `proxyTls: { autoSelectFamilyAttemptTimeout: 2000 }`（构造内部展开透传到「到代理」连接）；禁传 `connect` 选项——主类不消费该字段，传入被静默忽略
-- socks5：`Socks5ProxyAgent` 调优经 `connect: buildConnector({ autoSelectFamilyAttemptTimeout: 2000 })` 的 **connector 函数形态**（对象形态首个请求建隧道时 TypeError）；`proxyTls` 是「代理连接走 TLS」开关，不可当调优参数袋
+- socks5（仅 Node 宿主，打包版无承载见副本策略节）：`Socks5ProxyAgent` 调优经 `connect: buildConnector({ autoSelectFamilyAttemptTimeout: 2000 })` 的 **connector 函数形态**（对象形态首个请求建隧道时 TypeError）；`proxyTls` 是「代理连接走 TLS」开关，不可当调优参数袋
 - 两协议 agent 均挂防崩溃 error listener（对齐 pi `withUndiciErrorListener` 形态）
 
 上述契约由 `src/__tests__/dispatcher-construction.test.ts` 构造形态冒烟测试锁定；分流/计数/状态机行为由 `src/__tests__/fetch-wrapper.test.ts` 锁定。undici 升级时这两处是第一道回归防线。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-network-proxy",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "LLM network proxy: rule-based per-hostname traffic splitting via a globalThis.fetch wrapper (http/https/socks5 proxy), with request counters.",
   "type": "module",
   "main": "index.ts",
@@ -41,10 +41,10 @@
   ],
   "dependencies": {
     "undici": "^7.28.0",
+    "@zhushanwen/pi-llm-shared": "0.12.0",
     "@zhushanwen/pi-ext-guards": "0.5.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/pi-file-lock": "0.4.1",
-    "@zhushanwen/pi-llm-shared": "0.12.0"
+    "@zhushanwen/pi-file-lock": "0.4.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",

package/skills/network-proxy-ext-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: network-proxy-ext-config
-description: "配置 @zhushanwen/pi-network-proxy（LLM 网络代理分流）时加载。含配置文件路径、NetworkProxyConfig schema（enabled/proxy/noProxy/rules）、协议三选一（http/https/socks5）、suffix 主机名匹配语义、noProxy 优先级、凭据成对约束、默认值、示例、生效时机（turn 粒度热重载）、统计文件、故障恢复。触发词：配置网络代理、network-proxy 配置、代理规则、走代理、socks5、noProxy、network-proxy config、代理不生效、代理报错、直连排除。"
+description: "配置 @zhushanwen/pi-network-proxy（LLM 网络代理分流）时加载。含配置文件路径、NetworkProxyConfig schema（enabled/proxy/noProxy/rules/ipv4Only）、协议三选一（http/https/socks5，socks5 仅 Node 宿主——打包版 Bun 内置 undici 副本无此 API）、suffix 主机名匹配语义、noProxy 优先级、凭据成对约束、默认值、示例、生效时机（turn 粒度热重载）、统计文件、故障恢复。触发词：配置网络代理、network-proxy 配置、代理规则、走代理、socks5、noProxy、network-proxy config、代理不生效、代理报错、直连排除、强制 IPv4、ipv4Only。"
 ---
 
 # network-proxy 配置指南
@@ -20,18 +20,22 @@ description: "配置 @zhushanwen/pi-network-proxy（LLM 网络代理分流）时
 
 ```ts
 interface NetworkProxyConfig {
-  enabled: boolean;      // 总开关，默认 false（禁用 = 不包装 fetch，全部按 pi 原生行为出站）
+  enabled: boolean;      // 代理分流总开关，默认 false（关闭 = rules 不参与分流，全部直连/env 代理；
+                         // 不影响 ipv4Only——见下）
   proxy: {
-    protocol: "http" | "https" | "socks5";  // http/https 走 undici ProxyAgent，socks5 走 Socks5ProxyAgent
+    protocol: "http" | "https" | "socks5";  // http/https 走 undici ProxyAgent；socks5 走 Socks5ProxyAgent
+                                           // （仅 Node 宿主——打包版 pi 的 Bun 内置 undici 副本无此 API，
+                                           //  构造时明确报错并保持全部直连，见「故障恢复」）
     host: string;        // 代理服务器地址，如 127.0.0.1
     port: number;        // 1-65535 整数
     username: string;    // 认证用户名（可空，但必须与 password 成对）
     password: string;    // 认证密码（可空，但必须与 username 成对）
   };
   noProxy: string[];     // 直连排除清单（主机名条目），优先级高于 rules——本地网关地址必须加在这里
-  rules: string[];       // 代理规则（主机名条目），命中即经代理
+  rules: string[];       // 代理规则（主机名条目），enabled 开启时命中即经代理
   ipv4Only: string[];    // 直连 + 强制 IPv4 清单（主机名条目）：命中不走代理，DNS 解析锁定 A 记录直连
-                         // （URL / Host 头 / TLS SNI 保持原样，只干预「选哪个 IP」）；用于「IPv6 可达但握手抖动」的服务商
+                         // （URL / Host 头 / TLS SNI 保持原样，只干预「选哪个 IP」）；用于「IPv6 可达但握手抖动」的服务商。
+                         // 独立于 enabled 开关：代理关闭时本清单照常生效（清单非空即安装分流包装层）
 }
 ```
 
@@ -51,7 +55,7 @@ interface NetworkProxyConfig {
 ## 生效时机（turn 粒度热重载）
 
 - 每个 turn 开始重读配置，指纹（enabled+proxy+noProxy+rules+ipv4Only）变化才重建包装——**运行中会话自下一轮对话起生效，无需重启**；turn 进行中（工具循环连续请求）保存的配置对该 turn 内后续请求不生效
-- `enabled` 从 true → false：立即恢复包装前的 fetch（全部直连/env 代理路由）
+- `enabled` 从 true → false 且 `ipv4Only` 为空：立即恢复包装前的 fetch（全部直连/env 代理路由）；`ipv4Only` 非空时包装保留（IPv4 锁定不随代理开关关闭而失效，仅代理分流停用）
 - 未命中规则的流量委托包装前的 fetch——独立 pi 用户设了 `HTTPS_PROXY` 环境变量时，未命中流量仍走 env 代理，语义不丢失
 - pi 的 `configureHttpDispatcher` 带 shouldInstallGlobals 守卫（pi dist/core/http-dispatcher.js:88-99）：检测到 `globalThis.fetch` 已被第三方覆盖即保留不重装，本扩展的包装在同进程内持续生效；槽位被其他第三方整体覆盖时，下一 turn 开始自动以覆盖者为新 original 重新包装（防御路径）
 
@@ -64,17 +68,32 @@ interface NetworkProxyConfig {
 | 现象 | 处置 |
 |---|---|
 | 代理不可达（请求报 `fetch failed` / `ECONNREFUSED`） | 启动代理软件；或把 `enabled` 改为 `false` 一键恢复直连 |
-| socks5 构造失败（undici 实验性 API 变化） | extension error 提示并保持全部直连；切回 `http` 协议即可恢复代理 |
+| socks5 不可用（打包版：Bun 内置 undici 副本无 Socks5ProxyAgent；或 undici 实验性 API 变化） | extension error 提示并保持全部直连；切回 `http`/`https` 协议即可恢复代理（打包版不支持 socks5 属能力边界，非配置错误） |
 | 配置校验失败（端口越界 / 凭据单边等） | 按报错文案修正配置文件，或删除该文件恢复默认禁用态 |
 | 想让某服务商不再走代理 | 从 `rules` 删除对应主机名条目，或将其加入 `noProxy` |
 
 ## 配置示例
 
+代理分流 + IPv4 锁定并用：
+
 ```json
 {
   "enabled": true,
   "proxy": { "protocol": "http", "host": "127.0.0.1", "port": 7890, "username": "", "password": "" },
   "noProxy": ["localhost", "127.0.0.1"],
-  "rules": ["api.anthropic.com"]
+  "rules": ["api.anthropic.com"],
+  "ipv4Only": ["open-design.ai"]
+}
+```
+
+仅 IPv4 锁定、不走代理（`enabled=false` 时 `rules` 不参与分流，`ipv4Only` 照常生效）：
+
+```json
+{
+  "enabled": false,
+  "proxy": { "protocol": "http", "host": "127.0.0.1", "port": 7890, "username": "", "password": "" },
+  "noProxy": ["localhost", "127.0.0.1"],
+  "rules": [],
+  "ipv4Only": ["open-design.ai"]
 }
 ```

package/src/__tests__/fetch-wrapper.test.ts

@@ -2,6 +2,7 @@
  * fetch 包装状态机单测（fake 依赖注入，不触真实网络）：
  * 命中/未命中分流、计数、noProxy/ipv4Only 优先级、ipv4 与代理构造的差异化降级
  * （ipv4 失败只丢 v4 锁定、proxy 失败锁整层；rules 为空不构造代理）、禁用恢复、
+ * ipv4Only 独立于 enabled 代理开关（开关关闭时清单照常生效、rules 不参与分流）、
  * 外部覆盖重装、构造失败锁定、reload 残留摘除、入参形态覆盖。
  * 转移表见 fetch-wrapper.ts 文件头。
  */
@@ -335,6 +336,62 @@ describe("applyNetworkProxyConfig 包装状态机", () => {
 		expect(h.errors).toHaveLength(0);
 	});
 
+	it("enabled=false 且 ipv4Only 非空：包装保留，ipv4Only 命中照常锁 v4 直连", async () => {
+		const h = createHarness();
+		h.setBuildProxy(() => {
+			throw new Error("开关关闭不应构造代理分发器");
+		});
+		const state = applyNetworkProxyConfig(
+			config({ enabled: false, rules: [], ipv4Only: ["open-design.ai"] }),
+			null,
+			h.deps,
+		);
+		expect(state?.wrapper).not.toBeNull();
+		expect(h.getCurrent()).toBe(state?.wrapper);
+		expect(h.buildCalls).toHaveLength(0); // 代理分流不构建
+		expect(h.buildIpv4Calls).toHaveLength(1);
+
+		const response = await h.getCurrent()("https://amr-link.open-design.ai/v1/chat");
+		expect(h.proxyCalls).toHaveLength(1);
+		expect(h.proxyCalls[0]?.init.dispatcher).toBe(h.ipv4);
+		expect(await response.text()).toBe("proxy");
+		expect(snapshotCounters().get("amr-link.open-design.ai")).toEqual({ proxied: 0, direct: 1 });
+	});
+
+	it("enabled=false 时 rules 不参与分流：规则主机直连计数，不走代理", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(
+			config({ enabled: false, rules: ["api.anthropic.com"], ipv4Only: ["open-design.ai"] }),
+			null,
+			h.deps,
+		);
+		await h.getCurrent()("https://api.anthropic.com/v1/messages");
+		expect(h.proxyCalls).toHaveLength(0);
+		expect(h.originalCalls).toHaveLength(1);
+		expect(snapshotCounters().get("api.anthropic.com")).toEqual({ proxied: 0, direct: 1 });
+	});
+
+	it("enabled true→false 且 ipv4Only 非空：包装保持（重建不摘除），ipv4 分流继续生效", async () => {
+		const h = createHarness();
+		const first = applyNetworkProxyConfig(
+			config({ rules: [], ipv4Only: ["open-design.ai"] }),
+			null,
+			h.deps,
+		);
+		const after = applyNetworkProxyConfig(
+			config({ enabled: false, rules: [], ipv4Only: ["open-design.ai"] }),
+			first,
+			h.deps,
+		);
+		expect(after).not.toBeNull();
+		expect(h.getCurrent()).toBe(after?.wrapper);
+		expect(h.getCurrent()).not.toBe(h.originalFetch);
+
+		await h.getCurrent()("https://amr-link.open-design.ai/v1/chat");
+		expect(h.proxyCalls).toHaveLength(1);
+		expect(h.proxyCalls[0]?.init.dispatcher).toBe(h.ipv4);
+	});
+
 	it("构造失败：onError + 不包装（全直连），同指纹锁定不重试；指纹变化后重试", () => {
 		const h = createHarness();
 		h.setBuildProxy(() => {

package/src/__tests__/socks5-guard.test.ts

@@ -0,0 +1,31 @@
+/**
+ * socks5 能力守卫单测：socks5Supported 判定「当前 undici 副本缺 Socks5ProxyAgent」
+ * （打包版 pi 的 Bun 内置副本形态，2026-10-22 真机指纹实测 49 导出无 socks）。
+ * buildProxyDispatcher 的 socks5 分支接入该判定（缺即抛可恢复错误，走
+ * lockOnBuildFailure：error 上报 + 恢复全直连）；「副本有 Socks5 时构造成功」的接入
+ * 正路径由 dispatcher-construction.test.ts 的 socks5 构造形态用例覆盖。
+ *
+ * 不用 vi.mock 造「缺导出的模块」——vitest 的 mock 层对访问 mock 未提供的原模块
+ * 导出抛自己的拦截错误（要求 mock 与原模块导出面对齐），与真实 ESM namespace
+ * 「缺失导出属性访问 = undefined」语义不一致。
+ */
+import { describe, expect, it } from "vitest";
+import * as undici from "undici";
+
+import { socks5Supported } from "../dispatcher.ts";
+
+describe("socks5Supported（副本能力判定）", () => {
+	it("缺 Socks5ProxyAgent 的副本（打包版 Bun 内置副本形态）→ false", () => {
+		expect(socks5Supported({})).toBe(false);
+		expect(socks5Supported({ Socks5ProxyAgent: undefined })).toBe(false);
+		expect(socks5Supported({ Socks5ProxyAgent: "not-a-class" })).toBe(false);
+	});
+
+	it("提供函数形态 Socks5ProxyAgent 的副本（npm undici 形态）→ true", () => {
+		expect(socks5Supported({ Socks5ProxyAgent: class {} })).toBe(true);
+	});
+
+	it("真实 npm undici 副本（Node 测试环境解析）→ true", () => {
+		expect(socks5Supported(undici)).toBe(true);
+	});
+});

package/src/config.ts

@@ -47,7 +47,11 @@ export interface NetworkProxyConfig { // oe-exempt:20261019:framework:ext-config
 	 * （autoSelectFamilyAttemptTimeout=2000）反复试 IPv6，把 connect 预算耗在坏路径上，
 	 * 最终表现为 `Request timed out.`——实为连接层超时，不是 provider 故障。
 	 *
-	 * 优先级：noProxy > ipv4Only > rules。
+	 * 独立于 `enabled` 代理开关：`enabled=false` 时本清单照常生效（IPv4 锁定是直连的
+	 * 地址族修正，不是代理能力；清单非空即安装包装层）。
+	 *
+	 * 优先级：noProxy > ipv4Only > rules（rules 另受 enabled 门控——开关关闭时规则
+	 * 不参与分流）。
 	 */
 	ipv4Only: string[];
 }

package/src/dispatcher.ts

@@ -1,12 +1,23 @@
 /**
  * 分发器构造（供 fetch-wrapper 按请求注入）。
  *
- * 拦截点已从 undici 全局分发器改为 `globalThis.fetch` 包装（见 fetch-wrapper.ts 头注：
- * 打包版 pi 内置 undici 与扩展 bundle 内联的 undici 是两套副本，全局槽互不相通）。本模块
- * 负责构造两类分发器——代理分发器（rules 命中时）与 IPv4 锁定分发器（ipv4Only 命中时），
- * 规则判定 / 计数 / 直连委托都在 fetch-wrapper 完成。
+ * ## undici 副本策略：按宿主运行时解析，不内联
+ *
+ * 本包的 undici 依赖在构建期标 external（`scripts/bundle-extensions.mjs` 的 EXTERNAL
+ * 含 undici），运行时由宿主解析：Node 宿主（独立 pi / dev）解析 `node_modules` 的
+ * npm undici；Bun 宿主（打包版 pi）解析二进制内置副本（`builtin://thirdparty/undici`，
+ * Bun 团队随 Bun 版本适配测试）。每个宿主用自己官方维护的网络栈。
+ * [HISTORICAL] 内联 npm undici 7.28.0 副本的旧形态在打包版（Bun 1.3.x 兼容层）下
+ * `fetch` 读 chunked 流式响应体永不产块（LLM SSE 请求挂死 20 分钟，2026-10-22 事故，
+ * 本地 https 分块流探针复现），不得回退内联。
+ *
+ * 两副本能力面差异（真机指纹实测，2026-10-22）：内置副本 49 导出，无
+ * `Socks5ProxyAgent`——socks5 代理在打包版无承载，下方构造时按能力探测显式报错
+ * （走 lockOnBuildFailure：error 上报 + 恢复全直连，同指纹锁定不重试）。
+ * `Agent` / `buildConnector` / `ProxyAgent` / `fetch` 两副本都有且流式行为均实测正常。
+ *
+ * ## 两协议构造契约（undici 7.28.0 源码读码核实，单测冒烟防回归）
  *
- * 两协议构造契约（undici 7.28.0 源码读码核实，单测冒烟防回归）：
  * - http/https 走 ProxyAgent，调优经 `proxyTls: { autoSelectFamilyAttemptTimeout: 2000 }`
  *   （构造内部 buildConnector({...opts.proxyTls}) 透传到「到代理」连接）；禁传 connect 选项
  *   ——ProxyAgent 不消费该字段，传入被静默忽略、调优失效且不报错。
@@ -21,8 +32,11 @@
 
 import { EventEmitter } from "node:events";
 
-import { Agent, buildConnector, ProxyAgent, Socks5ProxyAgent } from "undici";
-import type { Dispatcher as IDispatcher } from "undici";
+// namespace 导入而非命名导入：打包版 Bun 内置副本缺 Socks5ProxyAgent 命名导出，
+// 命名导入会在模块链接期整体失败；namespace 属性访问缺失导出为 undefined，
+// 供下方运行时能力探测。
+import * as undici from "undici";
+import type { buildConnector, Dispatcher as IDispatcher } from "undici";
 
 import type { NetworkProxyConfig, NetworkProxyServer } from "./config.js";
 import { createIpv4Lookup } from "./ipv4.js";
@@ -53,6 +67,19 @@ function withUndiciErrorListener<T extends IDispatcher>(dispatcher: T): T {
 	return dispatcher;
 }
 
+/**
+ * socks5 副本能力判定：当前解析到的 undici 副本是否提供 Socks5ProxyAgent。
+ * 打包版 Bun 内置副本无此导出（2026-10-22 真机指纹实测）。`in` 探测短路 + typeof
+ * 双保险——namespace 属性访问缺失导出按 ESM 语义是 undefined，但 `in` 的行为已在
+ * 打包版真机验证（false，不抛）。
+ */
+export function socks5Supported(mod: object): boolean {
+	if (!("Socks5ProxyAgent" in mod)) return false;
+	// in 已保证成员存在，断言到必填字段形态取值
+	const ctor = (mod as { Socks5ProxyAgent: unknown }).Socks5ProxyAgent;
+	return typeof ctor === "function";
+}
+
 /** 代理服务器 URL：凭据非空时 percent-encode 拼入（undici 构造内部 decodeURIComponent 还原）。 */
 export function buildProxyUrl(proxy: NetworkProxyServer): string {
 	const auth =
@@ -66,14 +93,22 @@ export function buildProxyUrl(proxy: NetworkProxyServer): string {
 export function buildProxyDispatcher(config: NetworkProxyConfig): IDispatcher {
 	const uri = buildProxyUrl(config.proxy);
 	if (config.proxy.protocol === "socks5") {
+		// 能力探测（非宿主名判断）：当前解析到的 undici 副本无 Socks5ProxyAgent 即不可用
+		// （打包版 Bun 内置副本）。抛错由 lockOnBuildFailure 收口：error 上报 + 恢复全直连。
+		if (!socks5Supported(undici)) {
+			throw new Error(
+				"当前 undici 副本（打包版 Bun 内置）不提供 Socks5ProxyAgent，socks5 代理不可用；" +
+					"请将代理协议改为 http/https 后重试",
+			);
+		}
 		return withUndiciErrorListener(
-			new Socks5ProxyAgent(uri, {
-				connect: buildConnector(PROXY_TLS_TUNING),
+			new undici.Socks5ProxyAgent(uri, {
+				connect: undici.buildConnector(PROXY_TLS_TUNING),
 			}),
 		);
 	}
 	return withUndiciErrorListener(
-		new ProxyAgent({
+		new undici.ProxyAgent({
 			uri,
 			proxyTls: PROXY_TLS_TUNING,
 		}),
@@ -83,7 +118,8 @@ export function buildProxyDispatcher(config: NetworkProxyConfig): IDispatcher {
 /**
  * IPv4 锁定分发器（`ipv4Only` 规则的执行体装配）：唯一干预 = `connect.lookup` 把 DNS
  * 解析强制到 A 记录（选型依据见 ipv4.ts 头注——改 URL 会因 SNI/Host 不一致被 Cloudflare
- * 拒为 403，只有改 DNS 族在 Node 与 Bun 下都正确）。URL / Host 头 / TLS 全部保持原样。
+ * 拒为 403，只有改 DNS 族在 Node 与 Bun 下都正确，两副本 Agent+lookup 已实测流式正常）。
+ * URL / Host 头 / TLS 全部保持原样。
  *
  * 刻意不设 `connect.timeout`：保持 undici 默认语义（pi 原生 dispatcher 亦未设）——锁 v4
  * 后 happy-eyeballs 没有坏路径可耗预算，不需要也不应该改连接预算（调大 timeout 只是把
@@ -91,6 +127,6 @@ export function buildProxyDispatcher(config: NetworkProxyConfig): IDispatcher {
  */
 export function buildIpv4Dispatcher(): IDispatcher {
 	return withUndiciErrorListener(
-		new Agent({ connect: { lookup: createIpv4Lookup() } }),
+		new undici.Agent({ connect: { lookup: createIpv4Lookup() } }),
 	);
 }

package/src/fetch-wrapper.ts

@@ -1,22 +1,23 @@
 /**
  * 网络代理请求拦截层：包装 pi 进程的 `globalThis.fetch`（打包版兼容设计）。
  *
- * 为什么不是 undici 全局分发器：打包版 pi 是 Bun 单文件二进制，HTTP 栈用二进制内置的
- * undici（`builtin://thirdparty/undici`）；扩展 bundle 由 esbuild 内联自己的 undici 副本
- * （`scripts/bundle-extensions.mjs` 的 EXTERNAL 不含 undici）。undici 的
- * `setGlobalDispatcher` 槽是模块级变量，两套副本互不相通——扩展改的全局槽 pi 根本不用，
- * LLM 请求照常直连（2026-10-20 打包版实测：请求直连 Cloudflare，统计文件零行）。
- * dev 用 `node_modules/.bin/pi`，pi 与扩展源码解析到同一份 undici，所以旧方案在 dev 正常、
- * 打包版静默失效。
+ * 为什么不是 undici 全局分发器：undici 的 `setGlobalDispatcher` 槽是模块级变量，
+ * 只在「pi 与扩展加载同一份 undici 模块实例」时生效。本包的 undici 按宿主运行时
+ * 解析（Node → node_modules npm 副本；Bun 打包版 → 二进制内置副本，副本策略与依据
+ * 见 dispatcher.ts 头注），与 pi 自己的 HTTP 栈不保证同实例。[HISTORICAL] 2026-10-20
+ * 打包版实测：setGlobalDispatcher 方案下扩展改的全局槽 pi 不用，LLM 请求照常直连、
+ * 统计文件零行——dev 下两实例恰好相同所以 dev 正常、打包版静默失效，拦截点因此
+ * 定为 `globalThis.fetch`（不依赖副本实例是否共享）。
  *
  * 稳定接缝 = `globalThis.fetch`：pi-ai 的 OpenAI 兼容请求在每次构造 client 时经
  * `Shims.getDefaultFetch()` 动态取当前全局 fetch（node_modules/openai/internal/shims.js），
- * 包装它不依赖 pi 与扩展是否共享 undici 副本。命中规则的请求用扩展自己的 undici fetch +
- * 分发器发出（代理或 IPv4 锁定，见 dispatcher.ts）；未命中的请求原样调用包装前的 fetch，
- * 保留 pi 原生 EnvHttpProxyAgent / 连接调优 / 错误处理语义。
+ * 包装它不依赖 pi 与扩展是否共享 undici 副本。命中规则的请求用扩展解析到的 undici
+ * fetch + 分发器发出（代理或 IPv4 锁定，见 dispatcher.ts）；未命中的请求原样调用包装前
+ * 的 fetch，保留 pi 原生 EnvHttpProxyAgent / 连接调优 / 错误处理语义。
  *
  * 生命周期与旧安装状态机同构：
- * - 加载 / 每 turn 开始：重读配置推进状态（禁用 = 摘除包装恢复原 fetch）；
+ * - 加载 / 每 turn 开始：重读配置推进状态（`enabled` 关且 `ipv4Only` 空 = 摘除包装恢复原
+ *   fetch；`ipv4Only` 非空时包装保留——IPv4 锁定是直连地址族修正，独立于代理开关）；
  * - 指纹未变且包装仍在进程槽位：零动作（不重建）；
   * - 槽位被第三方整体覆盖（其他 extension 包装 / 手动改写；pi 的 configureHttpDispatcher
   *   有 shouldInstallGlobals 守卫（pi dist/core/http-dispatcher.js:88-99）——检测到 fetch
@@ -147,8 +148,9 @@ function wrapperMarkOf(fetch: FetchLike): FetchWrapperMark | null {
  *
  * 分流优先级（单一源在这里，config.ts 的 hits* 只提供匹配，不重复排序）：
  * 1. `noProxy` 命中 → 原样直连（用户显式排除，连 IPv4 锁定也不做）；
- * 2. `ipv4Only` 命中 → IPv4 锁定直连（**不走代理**，本扩展只做地址族选择）；
- * 3. `rules` 命中 → 经代理 fetch；
+ * 2. `ipv4Only` 命中 → IPv4 锁定直连（**不走代理**，本扩展只做地址族选择；独立于
+ *    `enabled` 代理开关——开关关闭时本分支照常生效）；
+ * 3. `enabled` 且 `rules` 命中 → 经代理 fetch（开关关闭时 rules 不参与分流，落入直连）；
  * 4. 其余 → 原样直连。
  *
  * 计数时点 = 请求发起时（与旧分流器一致；不等待完成，成败由 pi 原生错误链路呈现）。
@@ -178,7 +180,7 @@ function createWrappedFetch(
 			return proxyFetch(input, { ...(init ?? {}), dispatcher: ipv4 });
 		}
 
-		if (hitsRules(host, config.rules)) {
+		if (config.enabled && hitsRules(host, config.rules)) {
 			recordDispatch(host, true);
 			// proxy 非空由 applyNetworkProxyConfig 保证（rules 非空才会构造）。
 			if (proxy === null) return originalFetch(input, init);
@@ -279,7 +281,11 @@ export function applyNetworkProxyConfig(
 	state: FetchWrapperState | null,
 	deps: FetchWrapperDeps,
 ): FetchWrapperState | null {
-	if (!config.enabled) {
+	// 包装层的存在条件 = 代理开关开（rules 分流可用）或 ipv4Only 非空（IPv4 锁定直连）。
+	// 两者全无才摘除包装——ipv4Only 是直连地址族修正，语义上不依赖代理开关；
+	// 依据：2026-10-22 真机事故，用户仅配 ipv4Only（enabled=false）时整层被摘，
+	// subagent 的 LLM 请求全部 Connection error（双栈域名的 IPv6 路径抖动）。
+	if (!config.enabled && config.ipv4Only.length === 0) {
 		restoreOriginalIfOwned(state, deps);
 		return null;
 	}
@@ -293,12 +299,12 @@ export function applyNetworkProxyConfig(
 	}
 	const originalFetch = installed && state ? state.originalFetch : currentFetch;
 
-	// 代理分发器只在「确实可能用到代理」时构造：rules 为空 = 无任何主机走代理，
-	// 此时不应因代理配置不可用而锁死整个包装（含 ipv4Only 直连改写）。
+	// 代理分发器只在「确实可能用到代理」时构造：开关关闭或 rules 为空 = 无任何主机走
+	// 代理，此时不应因代理配置不可用而锁死整个包装（含 ipv4Only 直连改写）。
 	// 依据：一次事故（2026-10-22 真机验证）——仅配 ipv4Only、rules=[] 时仍构造
 	// ProxyAgent 并失败，lockOnBuildFailure 把包装整层撤下，ipv4Only 静默失效。
 	let proxy: Dispatcher | null = null;
-	if (config.rules.length > 0) {
+	if (config.enabled && config.rules.length > 0) {
 		try {
 			proxy = deps.buildProxy(config);
 		} catch (error) {

package/src/index.ts

@@ -2,11 +2,13 @@
  * @zhushanwen/pi-network-proxy 入口：配置驱动的 globalThis.fetch 包装与事件接线。
  *
  * 行为序列（fetch-wrapper.ts 头注有完整设计依据）：
- * - 加载时：读配置校验，enabled 且校验过 → 包装 globalThis.fetch（命中规则走代理，
- *   未命中委托原 fetch）；校验失败 / 构造失败 → extension error（文案含恢复动作：
- *   配置文件路径），不包装不阻断 pi（全部直连）。
+ * - 加载时：读配置校验，enabled 或 ipv4Only 非空且校验过 → 包装 globalThis.fetch
+ *   （ipv4Only 命中锁 IPv4 直连、enabled 且命中规则走代理，未命中委托原 fetch）；
+ *   校验失败 / 构造失败 → extension error（文案含恢复动作：配置文件路径），不包装
+ *   不阻断 pi（全部直连）。
  * - 每 turn 开始：重读配置（llm-shared 读时刷新热重载），指纹变化才重建；enabled true→false
- *   恢复原 fetch（fetch-wrapper.ts 状态机）。
+ *   且 ipv4Only 空时恢复原 fetch（fetch-wrapper.ts 状态机；ipv4Only 非空则包装保留，
+ *   IPv4 锁定不随代理开关关闭而失效）。
  * - 每 turn 结束：计数增量 flush 追加写入 stats JSONL（stats.ts）；进程退出兜底 flush。
  *
  * 覆盖面含 subagent 的 pi 进程（subagent 的 LLM 请求同样分流计数，设计前提 P4）——不设
@@ -95,7 +97,8 @@ export default function networkProxyExtension(pi: ExtensionAPI): void {
 	ensureExitFlush();
 	refreshFromConfig();
 
-	// turn 粒度热生效：turn 开始重读配置（mtime+size 未变时零 IO），指纹变化重建 / 禁用恢复。
+	// turn 粒度热生效：turn 开始重读配置（mtime+size 未变时零 IO），指纹变化重建 /
+	// 代理关且 ipv4Only 空时恢复直连。
 	pi.on("turn_start", () => {
 		refreshFromConfig();
 	});