@zhushanwen/pi-network-proxy 0.2.2 → 0.3.1

package/README.md

@@ -5,9 +5,9 @@ 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 协议恢复；同指纹不重试构造，配置修正（指纹变化）后自然重试

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-network-proxy",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "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",
@@ -22,7 +22,8 @@
             "localhost",
             "127.0.0.1"
           ],
-          "rules": []
+          "rules": [],
+          "ipv4Only": []
         }
       }
     ]
@@ -40,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）、suffix 主机名匹配语义、noProxy 优先级、凭据成对约束、默认值、示例、生效时机（turn 粒度热重载）、统计文件、故障恢复。触发词：配置网络代理、network-proxy 配置、代理规则、走代理、socks5、noProxy、network-proxy config、代理不生效、代理报错、直连排除、强制 IPv4、ipv4Only。"
 ---
 
 # network-proxy 配置指南
@@ -20,7 +20,8 @@ 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
     host: string;        // 代理服务器地址，如 127.0.0.1
@@ -29,11 +30,14 @@ interface NetworkProxyConfig {
     password: string;    // 认证密码（可空，但必须与 username 成对）
   };
   noProxy: string[];     // 直连排除清单（主机名条目），优先级高于 rules——本地网关地址必须加在这里
-  rules: string[];       // 代理规则（主机名条目），命中即经代理
+  rules: string[];       // 代理规则（主机名条目），enabled 开启时命中即经代理
+  ipv4Only: string[];    // 直连 + 强制 IPv4 清单（主机名条目）：命中不走代理，DNS 解析锁定 A 记录直连
+                         // （URL / Host 头 / TLS SNI 保持原样，只干预「选哪个 IP」）；用于「IPv6 可达但握手抖动」的服务商。
+                         // 独立于 enabled 开关：代理关闭时本清单照常生效（清单非空即安装分流包装层）
 }
 ```
 
-校验规则（违反即回落禁用态并报错，错误文案含修复动作）：协议白名单、端口 1-65535 整数、凭据成对（同空或同非空）、noProxy/rules 每条非空且不含空白字符（含空白的条目对真实主机名恒不匹配，校验层显式拒绝，错误文案提示删除空白）。
+校验规则（违反即回落禁用态并报错，错误文案含修复动作）：协议白名单、端口 1-65535 整数、凭据成对（同空或同非空）、noProxy/rules/ipv4Only 每条非空且不含空白字符（含空白的条目对真实主机名恒不匹配，校验层显式拒绝，错误文案提示删除空白）。`ipv4Only` 是后加字段，旧配置文件缺省 = 空清单。
 
 ## 匹配语义
 
@@ -41,13 +45,15 @@ interface NetworkProxyConfig {
   - 条目 `api.anthropic.com` 命中 `api.anthropic.com` 与 `eu.api.anthropic.com`
   - `xapi.anthropic.com` 不命中（无点前缀拼接）；`api-anthropic.com.evil.com` 不命中（恶意后缀）
 - 匹配对象 = 请求目标 URL 的主机名（服务商 baseURL 的主机名；端口不参与匹配）
-- noProxy 先于 rules 判定（先排除再匹配）；`localhost` 条目同时覆盖 `localhost` 与 `*.localhost`
+- 分流优先级：**noProxy > ipv4Only > rules**（noProxy 命中即原样直连，连 IPv4 锁定都不做）
+- ipv4Only 命中：不走代理，请求 URL 原样保留，经 `connect.lookup` 把 DNS 解析强制到 A 记录（family:4）后直连——URL / Host 头 / TLS SNI 全部不动（把 URL 换成 IP 字面量的做法会被 Cloudflare 按 SNI/Host 不一致拒 403，实测证伪）；无 A 记录时解析报错上抛，**不回退 IPv6**（避免「要求锁 v4」的意图被静默丢弃）
+- `localhost` 条目同时覆盖 `localhost` 与 `*.localhost`
 - 不支持 `*` 通配（无已发生需求）；分流覆盖经 `globalThis.fetch` 发出的请求（pi LLM 调用与 OAuth/目录请求）；直接使用 `undici.request` / `Client` 的调用不经过本包装
 
 ## 生效时机（turn 粒度热重载）
 
-- 每个 turn 开始重读配置，指纹（enabled+proxy+noProxy+rules）变化才重建包装——**运行中会话自下一轮对话起生效，无需重启**；turn 进行中（工具循环连续请求）保存的配置对该 turn 内后续请求不生效
-- `enabled` 从 true → false：立即恢复包装前的 fetch（全部直连/env 代理路由）
+- 每个 turn 开始重读配置，指纹（enabled+proxy+noProxy+rules+ipv4Only）变化才重建包装——**运行中会话自下一轮对话起生效，无需重启**；turn 进行中（工具循环连续请求）保存的配置对该 turn 内后续请求不生效
+- `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 重新包装（防御路径）
 
@@ -66,11 +72,26 @@ interface NetworkProxyConfig {
 
 ## 配置示例
 
+代理分流 + 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__/config.test.ts

@@ -58,6 +58,7 @@ function validConfig(overrides?: Partial<NetworkProxyConfig>): NetworkProxyConfi
 		proxy: { protocol: "http", host: "127.0.0.1", port: 7890, username: "", password: "" },
 		noProxy: ["localhost"],
 		rules: ["api.anthropic.com"],
+		ipv4Only: [],
 		...overrides,
 	};
 }

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

@@ -1,9 +1,12 @@
 /**
  * fetch 包装状态机单测（fake 依赖注入，不触真实网络）：
- * 命中/未命中分流、计数、noProxy 优先、禁用恢复、外部覆盖重装、构造失败锁定、
- * reload 残留摘除、入参形态覆盖。转移表见 fetch-wrapper.ts 文件头。
+ * 命中/未命中分流、计数、noProxy/ipv4Only 优先级、ipv4 与代理构造的差异化降级
+ * （ipv4 失败只丢 v4 锁定、proxy 失败锁整层；rules 为空不构造代理）、禁用恢复、
+ * ipv4Only 独立于 enabled 代理开关（开关关闭时清单照常生效、rules 不参与分流）、
+ * 外部覆盖重装、构造失败锁定、reload 残留摘除、入参形态覆盖。
+ * 转移表见 fetch-wrapper.ts 文件头。
  */
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it } from "vitest";
 import { Dispatcher } from "undici";
 
 import type { NetworkProxyConfig } from "../config.ts";
@@ -34,6 +37,7 @@ function config(overrides?: Partial<NetworkProxyConfig>): NetworkProxyConfig {
 		proxy: { protocol: "http", host: "127.0.0.1", port: 7890, username: "", password: "" },
 		noProxy: ["localhost"],
 		rules: ["api.anthropic.com"],
+		ipv4Only: [],
 		...overrides,
 	};
 }
@@ -42,7 +46,7 @@ function withProxy(patch: Partial<NetworkProxyConfig["proxy"]>): Partial<Network
 	return { proxy: { ...config().proxy, ...patch } };
 }
 
-/** fake 依赖装配：original fetch / 代理 fetch / 构造器全部可观测、可注入失败。 */
+/** fake 依赖装配：original fetch / 代理 fetch / 两个构造器全部可观测、可注入失败。 */
 function createHarness() {
 	const originalCalls: FetchCall[] = [];
 	const originalFetch: FetchLike = async (input, init) => {
@@ -53,13 +57,16 @@ function createHarness() {
 
 	const proxyCalls: ProxyCall[] = [];
 	const proxy = new FakeDispatcher();
+	const ipv4 = new FakeDispatcher();
 	const proxyFetch = async (input: string | URL | Request, init: ProxyFetchInit): Promise<Response> => {
 		proxyCalls.push({ input, init });
 		return new Response("proxy");
 	};
 
 	let buildProxy = (_config: NetworkProxyConfig): Dispatcher => proxy;
+	let buildIpv4 = (): Dispatcher => ipv4;
 	const buildCalls: NetworkProxyConfig[] = [];
+	const buildIpv4Calls: number[] = [];
 	const errors: string[] = [];
 
 	const deps: FetchWrapperDeps = {
@@ -71,6 +78,10 @@ function createHarness() {
 			buildCalls.push(next);
 			return buildProxy(next);
 		},
+		buildIpv4: () => {
+			buildIpv4Calls.push(1);
+			return buildIpv4();
+		},
 		proxyFetch,
 		onError: (message) => errors.push(message),
 	};
@@ -81,7 +92,9 @@ function createHarness() {
 		originalCalls,
 		proxyCalls,
 		proxy,
+		ipv4,
 		buildCalls,
+		buildIpv4Calls,
 		errors,
 		getCurrent: () => currentFetch,
 		setCurrent: (fetch: FetchLike) => {
@@ -90,6 +103,9 @@ function createHarness() {
 		setBuildProxy: (next: (config: NetworkProxyConfig) => Dispatcher) => {
 			buildProxy = next;
 		},
+		setBuildIpv4: (next: () => Dispatcher) => {
+			buildIpv4 = next;
+		},
 	};
 }
 
@@ -150,6 +166,91 @@ describe("applyNetworkProxyConfig 包装状态机", () => {
 		expect(snapshotCounters().get("api.anthropic.com")).toEqual({ proxied: 0, direct: 1 });
 	});
 
+	it("ipv4Only 命中：URL 原样、经 ipv4 分发器直连（不走代理，DNS 锁定交给 connect.lookup）", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(
+			config({ ipv4Only: ["open-design.ai"], rules: ["open-design.ai"] }),
+			null,
+			h.deps,
+		);
+		const response = await h.getCurrent()("https://amr-link.open-design.ai/v1/chat", {
+			method: "POST",
+			headers: { "x-test": "1" },
+		});
+		expect(await response.text()).toBe("proxy"); // 经 proxyFetch 通道（注入 ipv4 分发器）
+		expect(h.originalCalls).toHaveLength(0);
+		expect(h.proxyCalls).toHaveLength(1);
+		const call = h.proxyCalls[0];
+		// URL 不改写：域名保持原样（改 URL 会被 Cloudflare 按 SNI/Host 不一致拒 403，见 ipv4.ts 选型）
+		expect(call.input).toBe("https://amr-link.open-design.ai/v1/chat");
+		expect(call.init.dispatcher).toBe(h.ipv4); // 注入 ipv4 分发器而非代理
+		expect(call.init.method).toBe("POST");
+		expect(call.init.headers).toEqual({ "x-test": "1" });
+		expect(snapshotCounters().get("amr-link.open-design.ai")).toEqual({ proxied: 0, direct: 1 });
+	});
+
+	it("noProxy 优先于 ipv4Only：同时命中时不做任何干预（原样直连）", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(
+			config({ noProxy: ["open-design.ai"], ipv4Only: ["open-design.ai"] }),
+			null,
+			h.deps,
+		);
+		await h.getCurrent()("https://amr-link.open-design.ai/v1/chat");
+		expect(h.proxyCalls).toHaveLength(0);
+		expect(h.originalCalls).toHaveLength(1);
+		expect(h.originalCalls[0].input).toBe("https://amr-link.open-design.ai/v1/chat");
+	});
+
+	it("rules 为空：不构造代理分发器（代理配置不可用不锁死整层，ipv4Only 照常生效）", () => {
+		const h = createHarness();
+		h.setBuildProxy(() => {
+			throw new Error("rules 为空不应构造代理分发器");
+		});
+		const state = applyNetworkProxyConfig(
+			config({ rules: [], ipv4Only: ["open-design.ai"] }),
+			null,
+			h.deps,
+		);
+		expect(state?.wrapper).not.toBeNull();
+		expect(h.buildCalls).toHaveLength(0);
+		expect(h.buildIpv4Calls).toHaveLength(1);
+		expect(h.errors).toHaveLength(0);
+	});
+
+	it("ipv4Only 为空：不构造 IPv4 分发器", () => {
+		const h = createHarness();
+		h.setBuildIpv4(() => {
+			throw new Error("ipv4Only 为空不应构造 IPv4 分发器");
+		});
+		applyNetworkProxyConfig(config(), null, h.deps);
+		expect(h.buildIpv4Calls).toHaveLength(0);
+		expect(h.errors).toHaveLength(0);
+	});
+
+	it("ipv4 构造失败：仅降级 v4 锁定为普通直连，不撤整层包装（代理分流不受影响）", async () => {
+		const h = createHarness();
+		h.setBuildIpv4(() => {
+			throw new Error("ipv4 boom");
+		});
+		const state = applyNetworkProxyConfig(
+			config({ ipv4Only: ["open-design.ai"] }),
+			null,
+			h.deps,
+		);
+		expect(state?.wrapper).not.toBeNull();
+		expect(h.errors).toHaveLength(1);
+		expect(h.errors[0]).toContain("IPv4 锁定分发器构造失败");
+
+		await h.getCurrent()("https://amr-link.open-design.ai/v1/chat");
+		expect(h.originalCalls).toHaveLength(1); // 降级为普通直连（原样 URL）
+		expect(h.proxyCalls).toHaveLength(0);
+
+		// 代理分流不受 ipv4 失败影响（同一包装下 rules 命中仍走代理）
+		await h.getCurrent()("https://api.anthropic.com/v1/messages");
+		expect(h.proxyCalls).toHaveLength(1);
+	});
+
 	it("子域命中 + 点边界：子域走代理，前缀拼接不命中", async () => {
 		const h = createHarness();
 		applyNetworkProxyConfig(config({ noProxy: [], rules: ["api.anthropic.com"] }), null, h.deps);
@@ -235,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__/ipv4-live.test.ts

@@ -0,0 +1,92 @@
+/**
+ * ipv4Only 真机行为（真实 DNS + 真实网络 + 真实 dispatcher，标记为集成用例）。
+ *
+ * 默认跳过（需要外网 + 真实域名）；显式开：
+ *   NETWORK_PROXY_LIVE_IPV4=1 npx vitest run src/__tests__/ipv4-live.test.ts
+ *
+ * 验证点（connect.lookup 方案，与旧「URL 改写」方案的区别见 ipv4.ts 头注选型表）：
+ * - 请求成功（200/401）：TLS SNI / Host / 证书校验全按原域名，未被 IP 形态破坏；
+ * - 输入 URL 原样未被改写（域名保持原域名，只干预「选哪个 IP」）；
+ * - 请求确实经本扩展构造的 IPv4 锁定分发器发出；
+ * - net.connect 层实测：用该 lookup 建连，remoteAddress 是 IPv4 点分形态（锁 v4 生效）。
+ */
+
+import dns from "node:dns";
+import net from "node:net";
+import { fetch as undiciFetch } from "undici";
+
+import { describe, expect, it } from "vitest";
+
+import type { NetworkProxyConfig } from "../config.js";
+import { buildIpv4Dispatcher } from "../dispatcher.js";
+import {
+	applyNetworkProxyConfig,
+	type FetchLike,
+	type FetchWrapperDeps,
+	type ProxyFetchInit,
+} from "../fetch-wrapper.js";
+import { createIpv4Lookup } from "../ipv4.js";
+
+const LIVE = process.env.NETWORK_PROXY_LIVE_IPV4 === "1";
+const HOST = "amr-link.open-design.ai";
+
+function config(overrides: Partial<NetworkProxyConfig> = {}): NetworkProxyConfig {
+	return {
+		enabled: true,
+		proxy: { protocol: "http", host: "127.0.0.1", port: 7890, username: "", password: "" },
+		noProxy: ["localhost"],
+		rules: [],
+		ipv4Only: [HOST],
+		...overrides,
+	};
+}
+
+describe.skipIf(!LIVE)("ipv4Only 真机行为", () => {
+	it("锁 v4 后请求成功且 URL 未被改写（经本扩展 ipv4 分发器发出）", async () => {
+		// 前提：该域名确有 A 记录（锁 v4 才有地址可用，纯 IPv6 域名是配置错误）
+		const aRecords = await new Promise<dns.LookupAddress[]>((resolve, reject) =>
+			dns.lookup(HOST, { family: 4, all: true }, (e, a) => (e ? reject(e) : resolve(a))),
+		);
+		expect(aRecords.length).toBeGreaterThan(0);
+
+		const ipv4Dispatcher = buildIpv4Dispatcher();
+		let currentFetch: FetchLike = async () => new Response("unset");
+		const captured: { input?: string | URL | Request; dispatcher?: unknown } = {};
+		const deps: FetchWrapperDeps = {
+			getFetch: () => currentFetch,
+			setFetch: (f) => {
+				currentFetch = f;
+			},
+			buildProxy: () => {
+				throw new Error("rules 为空不应构造代理分发器");
+			},
+			buildIpv4: () => ipv4Dispatcher,
+			proxyFetch: (input, init: ProxyFetchInit) => {
+				captured.input = input;
+				captured.dispatcher = init.dispatcher;
+				return undiciFetch(input as never, init as never);
+			},
+			onError: () => {},
+		};
+
+		applyNetworkProxyConfig(config(), null, deps);
+
+		const res = await currentFetch(`https://${HOST}/v1/models`);
+		// 无 bearer token → 401 是预期（证明 TLS + Host 正确到达服务端，而非连接/证书失败）
+		expect([200, 401]).toContain(res.status);
+		await res.body?.cancel();
+
+		expect(captured.input).toBe(`https://${HOST}/v1/models`); // URL 不改写
+		expect(captured.dispatcher).toBe(ipv4Dispatcher); // 经本扩展的 ipv4 分发器
+	}, 30_000);
+
+	it("createIpv4Lookup 在 net.connect 层锁住地址族（remoteAddress 为 IPv4 点分形态）", async () => {
+		const socket = await new Promise<net.Socket>((resolve, reject) => {
+			const s = net.connect({ host: HOST, port: 443, lookup: createIpv4Lookup() }, () => resolve(s));
+			s.once("error", reject);
+		});
+		// 点分十进制 = IPv4；IPv6 会是冒号十六进制（含或不含 ::ffff: 前缀）
+		expect(socket.remoteAddress ?? "").toMatch(/^\d+\.\d+\.\d+\.\d+$/);
+		socket.destroy();
+	}, 15_000);
+});

package/src/__tests__/ipv4.test.ts

@@ -0,0 +1,139 @@
+/**
+ * createIpv4Lookup 单测：DNS 解析族强制（锁 v4，非偏好）、回调双形态、options 透传、
+ * 错误上抛不回退 IPv6。用 fake dns.lookup 注入（不碰真实解析器；fake 按 dns.lookup 真实
+ * 语义回调——all:true 给地址数组，all:false 给首个地址字符串）。
+ *
+ * lookup 是纯地址族选择层——URL / Host / TLS 不在本层（connect.lookup 方案的设计边界，
+ * 见 ipv4.ts 头注），端到端行为由 fetch-wrapper.test.ts（分流）与 ipv4-live.test.ts
+ * （真机）覆盖。
+ */
+
+import dns from "node:dns";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createIpv4Lookup } from "../ipv4.js";
+
+/** fake dns.lookup 收到的调用参数（host, options）。 */
+const resolverCalls: Array<{ host: string; opts: Record<string, unknown> }> = [];
+
+/**
+ * 注入 fake 解析器：记录调用参数，按 dns.lookup 真实回调语义回应
+ * （all:true → (null, addrs[])；all:false → (null, 首地址, family)；err 非空 → (err, "", 4)）。
+ */
+function mockResolver(
+	respond: (host: string, opts: Record<string, unknown>) => {
+		err?: NodeJS.ErrnoException;
+		addrs: dns.LookupAddress[];
+	},
+): void {
+	vi.spyOn(dns, "lookup").mockImplementation(((
+		host: string,
+		opts: unknown,
+		cb: unknown,
+	) => {
+		const options = (opts ?? {}) as Record<string, unknown>;
+		resolverCalls.push({ host, opts: options });
+		const callback = cb as (
+			e: NodeJS.ErrnoException | null,
+			a: string | dns.LookupAddress[],
+			f?: number,
+		) => void;
+		const { err, addrs } = respond(host, options);
+		if (err !== undefined) {
+			callback(err, "", 4);
+			return;
+		}
+		if (options.all === true) {
+			callback(null, addrs);
+			return;
+		}
+		const first = addrs[0];
+		callback(null, first?.address ?? "", first?.family ?? 4);
+	}) as unknown as typeof dns.lookup);
+}
+
+afterEach(() => {
+	vi.restoreAllMocks();
+	resolverCalls.length = 0;
+});
+
+describe("createIpv4Lookup", () => {
+	it("all:false 形态：回调 (err, address, family)，解析族强制为 4", async () => {
+		mockResolver(() => ({ addrs: [{ address: "162.159.129.1", family: 4 }] }));
+		const lookup = createIpv4Lookup();
+		const result = await new Promise<{ address: string; family: number }>((resolve, reject) => {
+			lookup("api.example.com", { all: false }, (err, address, family) => {
+				if (err !== null || typeof address !== "string") {
+					reject(err ?? new Error("expected single-address form"));
+					return;
+				}
+				resolve({ address, family: family ?? 0 });
+			});
+		});
+		expect(result.address).toBe("162.159.129.1");
+		expect(result.family).toBe(4);
+	});
+
+	it("all:true 形态：回调 (err, addresses[])，条目 family 均为 4", async () => {
+		mockResolver(() => ({
+			addrs: [
+				{ address: "162.159.129.1", family: 4 },
+				{ address: "162.159.129.2", family: 4 },
+			],
+		}));
+		const lookup = createIpv4Lookup();
+		const addrs = await new Promise<dns.LookupAddress[]>((resolve, reject) => {
+			lookup("api.example.com", { all: true }, (err, address) => {
+				if (err !== null || !Array.isArray(address)) {
+					reject(err ?? new Error("expected all-addresses form"));
+					return;
+				}
+				resolve(address);
+			});
+		});
+		expect(addrs).toEqual([
+			{ address: "162.159.129.1", family: 4 },
+			{ address: "162.159.129.2", family: 4 },
+		]);
+	});
+
+	it("调用方传 family:6 仍被覆写为 4（锁 v4 而非偏好 v4）", async () => {
+		mockResolver(() => ({ addrs: [{ address: "10.0.0.1", family: 4 }] }));
+		const lookup = createIpv4Lookup();
+		await new Promise<void>((resolve, reject) => {
+			lookup("forced.example.com", { family: 6 }, (err) => {
+				if (err !== null) reject(err);
+				else resolve();
+			});
+		});
+		expect(resolverCalls[0]?.opts.family).toBe(4);
+	});
+
+	it("委托系统 dns.lookup（hostname 与其余 options 透传，保留 /etc/hosts 等语义）", async () => {
+		mockResolver(() => ({ addrs: [{ address: "10.0.0.2", family: 4 }] }));
+		const lookup = createIpv4Lookup();
+		await new Promise<void>((resolve, reject) => {
+			lookup("passthrough.example.com", { all: false, hints: 1, verbatim: true }, (err) => {
+				if (err !== null) reject(err);
+				else resolve();
+			});
+		});
+		expect(resolverCalls[0]?.host).toBe("passthrough.example.com");
+		expect(resolverCalls[0]?.opts.hints).toBe(1);
+		expect(resolverCalls[0]?.opts.verbatim).toBe(true);
+	});
+
+	it("解析器报错：err 原样透传（不回退 IPv6）", async () => {
+		mockResolver(() => {
+			const err: NodeJS.ErrnoException = new Error("getaddrinfo ENOTFOUND no-a.example.com");
+			err.code = "ENOTFOUND";
+			return { err, addrs: [] };
+		});
+		const lookup = createIpv4Lookup();
+		const err = await new Promise<NodeJS.ErrnoException | null>((resolve) => {
+			lookup("no-a.example.com", { all: false }, (e) => resolve(e));
+		});
+		expect(err?.code).toBe("ENOTFOUND");
+	});
+});

package/src/config.ts

@@ -38,6 +38,22 @@ export interface NetworkProxyConfig { // oe-exempt:20261019:framework:ext-config
 	noProxy: string[];
 	/** 代理规则（主机名条目），命中即经代理 */
 	rules: string[];
+	/**
+	 * 直连 + 强制 IPv4 清单（主机名条目）：命中即不走代理，DNS 解析锁定 A 记录后直连
+	 * （`connect.lookup` 强制 family:4；URL / Host 头 / TLS SNI 保持原样——选型依据见
+	 * ipv4.ts 头注）。
+	 *
+	 * 存在理由：双栈域名在「IPv6 可达但握手抖动」时，pi 的 fetch 走 happy-eyeballs
+	 * （autoSelectFamilyAttemptTimeout=2000）反复试 IPv6，把 connect 预算耗在坏路径上，
+	 * 最终表现为 `Request timed out.`——实为连接层超时，不是 provider 故障。
+	 *
+	 * 独立于 `enabled` 代理开关：`enabled=false` 时本清单照常生效（IPv4 锁定是直连的
+	 * 地址族修正，不是代理能力；清单非空即安装包装层）。
+	 *
+	 * 优先级：noProxy > ipv4Only > rules（rules 另受 enabled 门控——开关关闭时规则
+	 * 不参与分流）。
+	 */
+	ipv4Only: string[];
 }
 
 /** 默认配置：禁用态 + 常见本地代理地址占位 + 保护本地回环（与 shared DEFAULT 深相等，镜像锁定测试锁两侧）。 */
@@ -46,6 +62,7 @@ export const DEFAULT_NETWORK_PROXY_CONFIG: NetworkProxyConfig = {
 	proxy: { protocol: "http", host: "127.0.0.1", port: 7890, username: "", password: "" },
 	noProxy: ["localhost", "127.0.0.1"],
 	rules: [],
+	ipv4Only: [],
 };
 
 /** llm-shared loadConfig 的包名（决定文件名 network-proxy-ext-config.json）。 */
@@ -114,7 +131,7 @@ export function validateNetworkProxyConfig(config: unknown): NetworkProxyValidat
 		return { ok: false, errors: [`网络代理配置必须是对象: ${String(config)}`] };
 	}
 	const errors: string[] = [];
-	const { enabled, proxy, noProxy, rules } = config as Record<string, unknown>;
+	const { enabled, proxy, noProxy, rules, ipv4Only } = config as Record<string, unknown>;
 	if (typeof enabled !== "boolean") {
 		errors.push(
 			`网络代理开关必须是开或关: ${JSON.stringify(enabled) ?? String(enabled)}，请重新切换一次开关后保存`,
@@ -123,6 +140,11 @@ export function validateNetworkProxyConfig(config: unknown): NetworkProxyValidat
 	errors.push(...collectProxyServerErrors(proxy));
 	errors.push(...collectHostEntryErrors(noProxy, "直连排除清单（noProxy）"));
 	errors.push(...collectHostEntryErrors(rules, "代理规则（rules）"));
+	// ipv4Only 是后加字段：缺省（undefined）= 空清单，向后兼容旧配置文件；
+	// 只有显式声明了非数组形态才报错。
+	if (ipv4Only !== undefined) {
+		errors.push(...collectHostEntryErrors(ipv4Only, "强制 IPv4 直连清单（ipv4Only）"));
+	}
 	return errors.length > 0 ? { ok: false, errors } : { ok: true };
 }
 
@@ -131,13 +153,17 @@ export function validateNetworkProxyConfig(config: unknown): NetworkProxyValidat
  * 非法配置 throw（含逐项错误清单）→ loadConfig 回落 defaults 并把消息交给 onWarning——
  * 非法配置不静默修正（设计验收场景 10：坏配置不装分流器且 error 可归因），回落 defaults
  * 即「全部直连」的安全态。
+ *
+ * `ipv4Only` 向后兼容：旧配置文件无此键时补空数组（校验层已容忍 undefined，此处补全
+ * 让下游 `hitsIpv4Only(config.ipv4Only)` 无需再判 undefined）。
  */
 export function normalizeNetworkProxyConfig(raw: unknown): NetworkProxyConfig {
 	const result = validateNetworkProxyConfig(raw);
 	if (!result.ok) {
 		throw new Error(result.errors.join("；"));
 	}
-	return raw as NetworkProxyConfig;
+	const config = raw as NetworkProxyConfig;
+	return { ...config, ipv4Only: config.ipv4Only ?? [] };
 }
 
 /** 条目去重 + 归一化视图（分流匹配用：匹配函数自带归一化，这里只去重保序）。 */
@@ -162,8 +188,13 @@ export function hitsRules(host: string, rules: string[]): boolean {
 	return dedupeEntries(rules).some((pattern) => matchesHostPattern(host, pattern));
 }
 
+/** 强制 IPv4 直连命中判定（去重视图 + suffix 匹配，与 rules / noProxy 同一匹配语义）。 */
+export function hitsIpv4Only(host: string, ipv4Only: string[]): boolean {
+	return dedupeEntries(ipv4Only).some((pattern) => matchesHostPattern(host, pattern));
+}
+
 /**
- * 配置指纹：enabled+proxy+noProxy+rules 序列化比对（行为序列 2——指纹变化才重建分发器）。
+ * 配置指纹：enabled+proxy+noProxy+rules+ipv4Only 序列化比对（行为序列 2——指纹变化才重建分发器）。
  * normalize 后结构固定，JSON.stringify 字段序稳定（字面量构造序）。
  */
 export function networkProxyFingerprint(config: NetworkProxyConfig): string {
@@ -172,5 +203,6 @@ export function networkProxyFingerprint(config: NetworkProxyConfig): string {
 		proxy: config.proxy,
 		noProxy: dedupeEntries(config.noProxy),
 		rules: dedupeEntries(config.rules),
+		ipv4Only: dedupeEntries(config.ipv4Only),
 	});
 }

package/src/dispatcher.ts

@@ -1,9 +1,10 @@
 /**
- * 代理分发器构造（供 fetch-wrapper 在规则命中时按请求注入）。
+ * 分发器构造（供 fetch-wrapper 按请求注入）。
  *
  * 拦截点已从 undici 全局分发器改为 `globalThis.fetch` 包装（见 fetch-wrapper.ts 头注：
  * 打包版 pi 内置 undici 与扩展 bundle 内联的 undici 是两套副本，全局槽互不相通）。本模块
- * 只负责按协议构造代理分发器，规则判定 / 计数 / 直连委托都在 fetch-wrapper 完成。
+ * 负责构造两类分发器——代理分发器（rules 命中时）与 IPv4 锁定分发器（ipv4Only 命中时），
+ * 规则判定 / 计数 / 直连委托都在 fetch-wrapper 完成。
  *
  * 两协议构造契约（undici 7.28.0 源码读码核实，单测冒烟防回归）：
  * - http/https 走 ProxyAgent，调优经 `proxyTls: { autoSelectFamilyAttemptTimeout: 2000 }`
@@ -20,10 +21,11 @@
 
 import { EventEmitter } from "node:events";
 
-import { buildConnector, ProxyAgent, Socks5ProxyAgent } from "undici";
+import { Agent, buildConnector, ProxyAgent, Socks5ProxyAgent } from "undici";
 import type { Dispatcher as IDispatcher } from "undici";
 
 import type { NetworkProxyConfig, NetworkProxyServer } from "./config.js";
+import { createIpv4Lookup } from "./ipv4.js";
 
 /** 到代理服务器连接的 autoSelectFamilyAttemptTimeout（对齐 pi 原生调优同值）。 */
 export const PROXY_CONNECT_ATTEMPT_TIMEOUT_MS = 2000;
@@ -77,3 +79,18 @@ 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 全部保持原样。
+ *
+ * 刻意不设 `connect.timeout`：保持 undici 默认语义（pi 原生 dispatcher 亦未设）——锁 v4
+ * 后 happy-eyeballs 没有坏路径可耗预算，不需要也不应该改连接预算（调大 timeout 只是把
+ * 失败推迟，2026-10-22 用户裁决）。
+ */
+export function buildIpv4Dispatcher(): IDispatcher {
+	return withUndiciErrorListener(
+		new Agent({ connect: { lookup: createIpv4Lookup() } }),
+	);
+}

package/src/fetch-wrapper.ts

@@ -12,11 +12,12 @@
  * 稳定接缝 = `globalThis.fetch`：pi-ai 的 OpenAI 兼容请求在每次构造 client 时经
  * `Shims.getDefaultFetch()` 动态取当前全局 fetch（node_modules/openai/internal/shims.js），
  * 包装它不依赖 pi 与扩展是否共享 undici 副本。命中规则的请求用扩展自己的 undici fetch +
- * 代理分发器发出；未命中的请求原样调用包装前的 fetch，保留 pi 原生 EnvHttpProxyAgent /
- * 连接调优 / 错误处理语义。
+ * 分发器发出（代理或 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
@@ -31,6 +32,7 @@
 import type { Dispatcher } from "undici";
 
 import {
+	hitsIpv4Only,
 	hitsNoProxy,
 	hitsRules,
 	networkProxyFingerprint,
@@ -43,10 +45,9 @@ import { recordDispatch } from "./stats.js";
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
 type FetchInput = Parameters<FetchLike>[0];
-type FetchInit = Parameters<FetchLike>[1];
 
 /**
- * 经代理发出时的 init：保留调用方全部选项，附上本次请求的代理分发器。
+ * 经分发器发出时的 init：保留调用方全部选项，附上本次请求的分发器（代理或 IPv4 锁定）。
  * Omit 掉 Node 全局 RequestInit 自带的 dispatcher（undici-types 类型身份），避免与 npm
  * undici 的 Dispatcher 形成 `Dispatcher & Dispatcher` 冲突；运行时由本字段整体覆盖。
  * 签名自包含（不引用文件内私有别名 FetchInit）——导出签名的被引用类型必须可命名。
@@ -84,6 +85,11 @@ export interface FetchWrapperDeps { // oe-exempt:20261020:framework:状态机依
 	setFetch: (fetch: FetchLike) => void;
 	/** 代理分发器构造（可注入抛错——「构造失败 → 不包装 → 全直连」单测入口）。 */
 	buildProxy: (config: NetworkProxyConfig) => Dispatcher;
+	/**
+	 * IPv4 锁定分发器构造（`connect.lookup` 强制 family:4）。
+	 * 只在 `ipv4Only` 非空时调用；可注入抛错（回退到「不做 v4 锁定」）。
+	 */
+	buildIpv4: () => Dispatcher;
 	proxyFetch: ProxyFetch;
 	/** extension error 呈现（logger.error；文案含恢复动作）。 */
 	onError: (message: string) => void;
@@ -138,34 +144,77 @@ function wrapperMarkOf(fetch: FetchLike): FetchWrapperMark | null {
 }
 
 /**
- * 构造包装函数：每次调用现算 host → 计数 → 命中规则走代理 fetch，未命中委托原 fetch。
+ * 构造包装函数：每次调用现算 host → 计数 → 三态分流，全部未命中则委托原 fetch。
+ *
+ * 分流优先级（单一源在这里，config.ts 的 hits* 只提供匹配，不重复排序）：
+ * 1. `noProxy` 命中 → 原样直连（用户显式排除，连 IPv4 锁定也不做）；
+ * 2. `ipv4Only` 命中 → IPv4 锁定直连（**不走代理**，本扩展只做地址族选择；独立于
+ *    `enabled` 代理开关——开关关闭时本分支照常生效）；
+ * 3. `enabled` 且 `rules` 命中 → 经代理 fetch（开关关闭时 rules 不参与分流，落入直连）；
+ * 4. 其余 → 原样直连。
+ *
  * 计数时点 = 请求发起时（与旧分流器一致；不等待完成，成败由 pi 原生错误链路呈现）。
+ * ipv4 锁定计入 `direct`（语义上确实是直连，与经代理区分）。
  */
 function createWrappedFetch(
 	originalFetch: FetchLike,
 	config: NetworkProxyConfig,
-	proxy: Dispatcher,
+	proxy: Dispatcher | null,
+	ipv4: Dispatcher | null,
 	proxyFetch: ProxyFetch,
 ): FetchLike {
 	const wrapped: FetchLike = async (input, init) => {
 		const host = hostnameOfInput(input);
 		if (host === "") return originalFetch(input, init);
-		const proxied = !hitsNoProxy(host, config.noProxy) && hitsRules(host, config.rules);
-		recordDispatch(host, proxied);
-		if (!proxied) return originalFetch(input, init);
-		const rest: Omit<NonNullable<FetchInit>, "dispatcher"> = { ...(init ?? {}) };
-		return proxyFetch(input, { ...rest, dispatcher: proxy });
+
+		if (hitsNoProxy(host, config.noProxy)) {
+			recordDispatch(host, false);
+			return originalFetch(input, init);
+		}
+
+		if (hitsIpv4Only(host, config.ipv4Only)) {
+			recordDispatch(host, false);
+			// URL / Host 头 / TLS 全部保持原样，只把 DNS 族锁到 IPv4（connect.lookup）。
+			// 构造失败（ipv4 === null）= 降级为普通直连（不阻断请求）。
+			if (ipv4 === null) return originalFetch(input, init);
+			return proxyFetch(input, { ...(init ?? {}), dispatcher: ipv4 });
+		}
+
+		if (config.enabled && hitsRules(host, config.rules)) {
+			recordDispatch(host, true);
+			// proxy 非空由 applyNetworkProxyConfig 保证（rules 非空才会构造）。
+			if (proxy === null) return originalFetch(input, init);
+			return proxyFetch(input, { ...(init ?? {}), dispatcher: proxy });
+		}
+
+		recordDispatch(host, false);
+		return originalFetch(input, init);
 	};
 	markWrapper(wrapped, originalFetch);
 	return wrapped;
 }
 
+/**
+ * 槽位归属判定：state 记录的包装当前是否仍挂在 globalThis.fetch 上。
+ * 三处共用（禁用恢复 / 构造失败恢复 / 重建前 original 推导）——槽位被第三方
+ * 整体覆盖时不再改写别人的实现，也不把覆盖者误当自己的 original。
+ */
+function wrapperStillInstalled(
+	state: FetchWrapperState | null,
+	currentFetch: FetchLike,
+): boolean {
+	return (
+		state?.wrapper !== null && state?.wrapper !== undefined && currentFetch === state.wrapper
+	);
+}
+
 /** 禁用态收口：仅当槽位仍归本扩展时恢复原 fetch（槽位被外部覆盖时不改写别人的实现）。 */
 function restoreOriginalIfOwned(
 	state: FetchWrapperState | null,
 	deps: Pick<FetchWrapperDeps, "getFetch" | "setFetch">,
 ): void {
-	if (state?.wrapper !== null && state?.wrapper !== undefined && deps.getFetch() === state.wrapper) {
+	// state !== null 前置（谓词函数不向调用方传播 narrowing；state 为 null 时谓词恒 false，语义等价）
+	if (state !== null && wrapperStillInstalled(state, deps.getFetch())) {
 		deps.setFetch(state.originalFetch);
 	}
 }
@@ -198,12 +247,31 @@ function lockOnBuildFailure(
 		`网络代理转发器构造失败（协议 ${config.proxy.protocol}），已保持全部直连，不影响 pi 运行；` +
 			`可核对代理配置后保存重试，或关闭网络代理开关。构造错误: ${error instanceof Error ? error.message : String(error)}`,
 	);
-	if (state?.wrapper !== null && state?.wrapper !== undefined && deps.getFetch() === state.wrapper) {
-		deps.setFetch(state.originalFetch);
-	}
+	restoreOriginalIfOwned(state, deps);
 	return { originalFetch, fingerprint, wrapper: null };
 }
 
+/**
+ * IPv4 锁定分发器构造（失败只降级「不锁 v4」，不撤整层包装——代理分流仍应生效）。
+ * 独立成函数：构造失败是设计内降级路径（error 上报后返回 null），不与主状态机转移混排。
+ */
+function buildIpv4Dispatcher(
+	config: NetworkProxyConfig,
+	deps: FetchWrapperDeps,
+): Dispatcher | null {
+	if (config.ipv4Only.length === 0) return null;
+	try {
+		return deps.buildIpv4();
+	} catch (error) {
+		deps.onError(
+			`IPv4 锁定分发器构造失败，ipv4Only 规则降级为普通直连（其余分流不受影响）：${
+				error instanceof Error ? error.message : String(error)
+			}`,
+		);
+		return null;
+	}
+}
+
 /**
  * 按新配置推进包装状态机（转移表见模块头）。config 契约 = loadNetworkProxyConfig 产物
  * （normalize 已校验合法——非法配置在读取层回落 defaults+error，构造性到达本函数恒合法）。
@@ -213,33 +281,39 @@ 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;
 	}
 
 	const fingerprint = networkProxyFingerprint(config);
-	if (state && state.fingerprint === fingerprint && state.wrapper === null) {
-		return state; // 锁定态：同指纹不重试构造（首败即停）
-	}
 	const currentFetch = deps.getFetch();
-	const owned =
-		state?.wrapper !== null &&
-		state?.wrapper !== undefined &&
-		currentFetch === state.wrapper;
-	if (state && state.fingerprint === fingerprint && owned) {
-		return state; // 同指纹且包装仍在槽位：零动作
+	const installed = wrapperStillInstalled(state, currentFetch);
+	// 同指纹短路：锁定态不重试构造（首败即停）；包装仍在槽位零动作。
+	if (state && state.fingerprint === fingerprint && (state.wrapper === null || installed)) {
+		return state;
 	}
-	const originalFetch = owned && state ? state.originalFetch : currentFetch;
+	const originalFetch = installed && state ? state.originalFetch : currentFetch;
 
-	let proxy: Dispatcher;
-	try {
-		proxy = deps.buildProxy(config);
-	} catch (error) {
-		return lockOnBuildFailure(config, state, originalFetch, fingerprint, deps, error);
+	// 代理分发器只在「确实可能用到代理」时构造：开关关闭或 rules 为空 = 无任何主机走
+	// 代理，此时不应因代理配置不可用而锁死整个包装（含 ipv4Only 直连改写）。
+	// 依据：一次事故（2026-10-22 真机验证）——仅配 ipv4Only、rules=[] 时仍构造
+	// ProxyAgent 并失败，lockOnBuildFailure 把包装整层撤下，ipv4Only 静默失效。
+	let proxy: Dispatcher | null = null;
+	if (config.enabled && config.rules.length > 0) {
+		try {
+			proxy = deps.buildProxy(config);
+		} catch (error) {
+			return lockOnBuildFailure(config, state, originalFetch, fingerprint, deps, error);
+		}
 	}
 
-	const wrapper = createWrappedFetch(originalFetch, config, proxy, deps.proxyFetch);
+	const ipv4 = buildIpv4Dispatcher(config, deps);
+	const wrapper = createWrappedFetch(originalFetch, config, proxy, ipv4, deps.proxyFetch);
 	deps.setFetch(wrapper);
 	return { originalFetch, fingerprint, wrapper };
 }

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）——不设
@@ -21,7 +23,7 @@ import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 import { getConfigPath } from "@zhushanwen/pi-llm-shared";
 
 import { loadNetworkProxyConfig } from "./config.js";
-import { buildProxyDispatcher } from "./dispatcher.js";
+import { buildIpv4Dispatcher, buildProxyDispatcher } from "./dispatcher.js";
 import {
 	applyNetworkProxyConfig,
 	detachResidualFetchWrapper,
@@ -57,6 +59,7 @@ const deps: FetchWrapperDeps = {
 		globalThis.fetch = fetch;
 	},
 	buildProxy: buildProxyDispatcher,
+	buildIpv4: buildIpv4Dispatcher,
 	proxyFetch,
 	onError: (message) => logger.error(`${message} ${recoveryHint()}`),
 };
@@ -94,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();
 	});

package/src/ipv4.ts

@@ -0,0 +1,77 @@
+/**
+ * 直连 + 强制 IPv4 执行层（`ipv4Only` 规则的执行体）。
+ *
+ * 存在理由（实测定因，非推测）：
+ * 双栈域名（如 `amr-link.open-design.ai`）在「IPv6 连通但 TLS 握手抖动」时，
+ * pi 的 fetch 走 happy-eyeballs——`autoSelectFamilyAttemptTimeout=2000` 会在 2s 后
+ * 换下一个地址，而整个 socket 的 connect 预算由 undici dispatcher 决定（未显式配置时
+ * 为 undici 默认 10s，实测复现 10.5s 报 `Request timed out.`）。结果是连接层把预算
+ * 耗在坏路径上，最终报错文案看起来像 provider 故障。
+ *
+ * ## 实现选型：改 DNS 解析，不改 URL
+ *
+ * 早期实现（参考已废弃的外挂扩展）是「把 URL 主机名替换成 IPv4 字面量 + 保留 Host 头 +
+ * 显式 TLS serverName」。**实测证伪**（2026-10-22，同一 provider / 同一 IP）：
+ *
+ * | 方式 | curl/node-undici 结果 |
+ * |---|---|
+ * | 域名 URL + `--resolve` 到 IPv4（SNI = 域名） | 200 |
+ * | IP URL + `Host: 域名` 头（SNI = IP） | TLS 握手失败 / 经 `connect.servername` 补 SNI 后 403 |
+ * | 域名 URL + `connect.lookup` 强制 family:4 | 200 |
+ *
+ * 根因：Cloudflare 侧按 **SNI + Host 一致**路由；IP 字面量形态即便补了 SNI 也进不了
+ * 正确的 host 路由（403）。而「URL 保持域名 + 只改 DNS family」让 SNI / Host / 证书
+ * 校验 / 路由全部自然正确——我们唯一要干预的就是「选哪个 IP」。
+ *
+ * 因此本层的产出 = 一个 `lookup` 实现（Node `net.connect` / `tls.connect` 的 `lookup`
+ * 选项签名，见 dispatcher.ts 的接线），直接委托系统 `dns.lookup` 并覆写 `family: 4`——
+ * /etc/hosts、resolver 配置、OS 级 DNS 缓存等语义全部保留，连接池化后每个 origin 的
+ * 解析频次本就低，不另建应用层缓存。
+ *
+ * ## 边界（刻意不做的事）
+ *
+ * - 不缓存 Response、不重试、不改超时——只做地址族选择；
+ * - 不回退 IPv6：`family: 4` 下系统解析器无 A 记录即报错（ENOTFOUND / ENODATA），
+ *   错误沿连接层上抛——命中 ipv4Only 却解不到 A 记录是显式失败，「我要求锁 v4」的
+ *   意图静默失效比失败更难归因；
+ * - 纯 IPv6 服务命中 ipv4Only 会连接失败——这是配置错误的显式暴露，不是本层的兜底责任。
+ */
+
+import dns from "node:dns";
+import type { LookupFunction } from "node:net";
+
+/** 地址族标识：IPv4（Node dns/net 的 family 数字语义）。 */
+const IPV4_FAMILY = 4;
+
+/**
+ * 构造 `connect.lookup` 实现：把任意 host 的解析强制到 IPv4（family: 4）。
+ *
+ * 两种回调形态都要支持（Node net / tls 的不同调用路径）：
+ * - `all: true` → `(err, [{address, family}])`
+ * - `all: false`（缺省）→ `(err, address, family)`
+ *
+ * 调用方传入的 `family`（含 6）一律覆写为 4——本函数的语义是「锁 v4」，不是「偏好 v4」。
+ */
+export function createIpv4Lookup(): LookupFunction {
+	return (hostname, options, callback) => {
+		const wantsAll = options?.all === true;
+		dns.lookup(
+			hostname,
+			{ ...options, family: IPV4_FAMILY, all: wantsAll },
+			(err, address, family) => {
+				if (err) {
+					callback(err, "", IPV4_FAMILY);
+					return;
+				}
+				if (wantsAll) {
+					callback(
+						null,
+						Array.isArray(address) ? address : [{ address, family: IPV4_FAMILY }],
+					);
+					return;
+				}
+				callback(null, address, family);
+			},
+		);
+	};
+}