@zhushanwen/pi-network-proxy 0.2.0 → 0.2.1

package/README.md

@@ -1,14 +1,24 @@
 # @zhushanwen/pi-network-proxy
 
-LLM 网络代理分流：在 pi 进程内安装按主机名规则分流的 undici 全局分发器——命中规则的请求经代理出站（http/https/socks5），未命中的委托 pi 原生分发器（直连或 env 代理路由），并按主机名计数（经代理 / 直连）。
+LLM 网络代理分流：包装 pi 进程的 `globalThis.fetch`，按主机名规则把命中请求交给代理 dispatcher（http/https/socks5），未命中的原样委托包装前的 fetch（直连或 pi 原生 env 代理路由），并按主机名计数（经代理 / 直连）。
 
 ## 行为摘要
 
-- **安装点**：extension 加载时读配置，`enabled` 且校验通过 → 捕获 pi 已装的 `EnvHttpProxyAgent`（接管而非向空闲槽安装）→ 构造 `RuleDispatchDispatcher` 并 `setGlobalDispatcher`；校验/构造失败 → extension error（含配置文件恢复指引），不安装不阻断 pi（全部直连）
-- **热生效**：turn 粒度——每 turn 开始重读配置（mtime+size 读时刷新），指纹变化才重建；`enabled` true→false 恢复原分发器
-- **匹配语义**：主机名归一化（小写、去末尾点）后 suffix 匹配（等于或以 `.条目` 结尾，点边界对齐）；noProxy 优先于 rules；覆盖一切走全局分发器的出站（含 WebSocket 升级请求）
+- **拦截点**：`globalThis.fetch`。pi-ai 的 OpenAI 兼容请求在每次构造 client 时经 `Shims.getDefaultFetch()` 动态取当前全局 fetch，包装它不依赖 pi 与扩展共享 undici 模块实例
+- **安装/卸载**：extension 加载时读配置，`enabled` 且校验通过 → 包装并构造代理 dispatcher；`enabled` false → 恢复原 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
+- **覆盖面**：经 `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）→ 记错误、不安装、全部直连，切回 http 协议恢复；同指纹不重试构造，配置修正（指纹变化）后自然重试
+- **降级契约**：socks5 构造失败（undici 实验性 API）→ 记错误、恢复原 fetch、全部直连，切回 http 协议恢复；同指纹不重试构造，配置修正（指纹变化）后自然重试
+
+## 为什么包装 fetch 而不是 undici 全局 dispatcher
+
+undici 的 `setGlobalDispatcher` 槽是模块级变量，只有「pi 与扩展加载同一份 undici 模块实例」时才生效：
+
+- 独立 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 时动态读取），因此拦截点定在这里
 
 ## 配置
 
@@ -31,4 +41,4 @@ taiji 桌面端经设置页「网络代理」读写（runtime RMW 写侧）；
 - socks5：`Socks5ProxyAgent` 调优经 `connect: buildConnector({ autoSelectFamilyAttemptTimeout: 2000 })` 的 **connector 函数形态**（对象形态首个请求建隧道时 TypeError）；`proxyTls` 是「代理连接走 TLS」开关，不可当调优参数袋
 - 两协议 agent 均挂防崩溃 error listener（对齐 pi `withUndiciErrorListener` 形态）
 
-上述契约由 `src/__tests__/dispatcher-construction.test.ts` 构造形态冒烟测试锁定；undici 升级时该测试是第一道回归防线。
+上述契约由 `src/__tests__/dispatcher-construction.test.ts` 构造形态冒烟测试锁定；分流/计数/状态机行为由 `src/__tests__/fetch-wrapper.test.ts` 锁定。undici 升级时这两处是第一道回归防线。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-network-proxy",
-  "version": "0.2.0",
-  "description": "LLM network proxy: rule-based per-hostname traffic splitting via an undici global dispatcher (proxied vs direct), with request counters.",
+  "version": "0.2.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",
   "taiji": {

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

@@ -5,7 +5,7 @@ description: "配置 @zhushanwen/pi-network-proxy（LLM 网络代理分流）时
 
 # network-proxy 配置指南
 
-> @zhushanwen/pi-network-proxy：在 pi 进程内安装按主机名规则分流的 undici 全局分发器——命中规则的 LLM 请求经代理出站，未命中的保持 pi 原生行为（直连或 env 代理），并按主机名计数（经代理 / 直连）。
+> @zhushanwen/pi-network-proxy：包装 pi 进程的 `globalThis.fetch`，按主机名规则分流——命中规则的请求经代理出站，未命中的保持 pi 原生行为（直连或 env 代理），并按主机名计数（经代理 / 直连）。打包版与独立 pi 都生效（不依赖 pi 与扩展共享 undici 模块实例）。
 
 ## 配置文件位置
 
@@ -20,7 +20,7 @@ description: "配置 @zhushanwen/pi-network-proxy（LLM 网络代理分流）时
 
 ```ts
 interface NetworkProxyConfig {
-  enabled: boolean;      // 总开关，默认 false（禁用 = 不安装分流器，全部按 pi 原生行为出站）
+  enabled: boolean;      // 总开关，默认 false（禁用 = 不包装 fetch，全部按 pi 原生行为出站）
   proxy: {
     protocol: "http" | "https" | "socks5";  // http/https 走 undici ProxyAgent，socks5 走 Socks5ProxyAgent
     host: string;        // 代理服务器地址，如 127.0.0.1
@@ -42,13 +42,14 @@ interface NetworkProxyConfig {
   - `xapi.anthropic.com` 不命中（无点前缀拼接）；`api-anthropic.com.evil.com` 不命中（恶意后缀）
 - 匹配对象 = 请求目标 URL 的主机名（服务商 baseURL 的主机名；端口不参与匹配）
 - noProxy 先于 rules 判定（先排除再匹配）；`localhost` 条目同时覆盖 `localhost` 与 `*.localhost`
-- 不支持 `*` 通配（无已发生需求）；分流覆盖 pi 进程内一切走全局分发器的出站（含 WebSocket 升级请求）
+- 不支持 `*` 通配（无已发生需求）；分流覆盖经 `globalThis.fetch` 发出的请求（pi LLM 调用与 OAuth/目录请求）；直接使用 `undici.request` / `Client` 的调用不经过本包装
 
 ## 生效时机（turn 粒度热重载）
 
-- 每个 turn 开始重读配置，指纹（enabled+proxy+noProxy+rules）变化才重建分发器——**运行中会话自下一轮对话起生效，无需重启**；turn 进行中（工具循环连续请求）保存的配置对该 turn 内后续请求不生效
-- `enabled` 从 true → false：立即恢复 pi 原生分发器（全部直连/env 代理路由）
-- 未命中规则的流量委托 pi 原生分发器——独立 pi 用户设了 `HTTPS_PROXY` 环境变量时，未命中流量仍走 env 代理，语义不丢失
+- 每个 turn 开始重读配置，指纹（enabled+proxy+noProxy+rules）变化才重建包装——**运行中会话自下一轮对话起生效，无需重启**；turn 进行中（工具循环连续请求）保存的配置对该 turn 内后续请求不生效
+- `enabled` 从 true → false：立即恢复包装前的 fetch（全部直连/env 代理路由）
+- 未命中规则的流量委托包装前的 fetch——独立 pi 用户设了 `HTTPS_PROXY` 环境变量时，未命中流量仍走 env 代理，语义不丢失
+- pi 的 `configureHttpDispatcher` 带 shouldInstallGlobals 守卫（pi dist/core/http-dispatcher.js:88-99）：检测到 `globalThis.fetch` 已被第三方覆盖即保留不重装，本扩展的包装在同进程内持续生效；槽位被其他第三方整体覆盖时，下一 turn 开始自动以覆盖者为新 original 重新包装（防御路径）
 
 ## 统计文件
 

package/src/__tests__/dispatcher.test.ts

@@ -1,132 +1,13 @@
 /**
- * 分流分发器行为 + 代理 URL 构造（dispatch 拦截点 / noProxy 优先 / 计数时点 / 委托语义）。
- * 两协议构造形态冒烟在 dispatcher-construction.test.ts（vi.mock undici 隔离）。
+ * 代理 URL 构造（凭据 percent-encode 拼入）。
+ * 分流行为与计数已随拦截点迁移到 fetch-wrapper.test.ts；两协议构造形态冒烟在
+ * dispatcher-construction.test.ts（vi.mock undici 隔离）。
  */
-import { describe, expect, it, vi } from "vitest";
-import { Dispatcher } from "undici";
-import type { Dispatcher as IDispatcher } from "undici";
+import { describe, expect, it } from "vitest";
 
-import { buildProxyUrl, RuleDispatchDispatcher } from "../dispatcher.ts";
+import { buildProxyUrl } from "../dispatcher.ts";
 import type { NetworkProxyServer } from "../config.ts";
 
-class RecordingDispatcher extends Dispatcher {
-	calls: Array<{ origin: string | URL | undefined }> = [];
-	dispatch(opts: IDispatcher.DispatchOptions, _handler: IDispatcher.DispatchHandler): boolean {
-		this.calls.push({ origin: opts.origin });
-		return true;
-	}
-}
-
-function configLists(noProxy: string[], rules: string[]) {
-	return { noProxy, rules };
-}
-
-function dispatchVia(
-	dispatcher: RuleDispatchDispatcher,
-	origin: string | URL | undefined,
-): { toProxy: boolean; toFallback: boolean } {
-	proxyDispatcher.calls = [];
-	fallbackDispatcher.calls = [];
-	dispatcher.dispatch({ origin, path: "/", method: "GET" }, {});
-	return {
-		toProxy: proxyDispatcher.calls.length > 0,
-		toFallback: fallbackDispatcher.calls.length > 0,
-	};
-}
-
-let fallbackDispatcher: RecordingDispatcher;
-let proxyDispatcher: RecordingDispatcher;
-let counted: Array<{ host: string; proxied: boolean }>;
-
-function createDispatcher(noProxy: string[], rules: string[]): RuleDispatchDispatcher {
-	fallbackDispatcher = new RecordingDispatcher();
-	proxyDispatcher = new RecordingDispatcher();
-	counted = [];
-	return new RuleDispatchDispatcher({
-		fallback: fallbackDispatcher,
-		proxy: proxyDispatcher,
-		...configLists(noProxy, rules),
-		onCount: (host, proxied) => counted.push({ host, proxied }),
-	});
-}
-
-describe("RuleDispatchDispatcher 分流行为", () => {
-	it("规则命中 → 代理 dispatch + proxied 计数（计数时点 = 发起时，同步完成）", () => {
-		const dispatcher = createDispatcher(["localhost"], ["api.anthropic.com"]);
-		const result = dispatchVia(dispatcher, "https://api.anthropic.com/v1/messages");
-		expect(result).toEqual({ toProxy: true, toFallback: false });
-		expect(counted).toEqual([{ host: "api.anthropic.com", proxied: true }]);
-	});
-
-	it("规则未命中 → 委托原分发器（fallback）+ direct 计数", () => {
-		const dispatcher = createDispatcher(["localhost"], ["api.anthropic.com"]);
-		const result = dispatchVia(dispatcher, "https://open.bigmodel.cn/api");
-		expect(result).toEqual({ toProxy: false, toFallback: true });
-		expect(counted).toEqual([{ host: "open.bigmodel.cn", proxied: false }]);
-	});
-
-	it("noProxy 优先于 rules：同主机名两侧都出现时直连（决策 7）", () => {
-		const dispatcher = createDispatcher(["api.anthropic.com"], ["api.anthropic.com"]);
-		const result = dispatchVia(dispatcher, "https://api.anthropic.com/v1/messages");
-		expect(result).toEqual({ toProxy: false, toFallback: true });
-		expect(counted).toEqual([{ host: "api.anthropic.com", proxied: false }]);
-	});
-
-	it("子域命中 + 点边界：子域走代理，前缀拼接不命中走 fallback", () => {
-		const dispatcher = createDispatcher([], ["api.anthropic.com"]);
-		expect(dispatchVia(dispatcher, "https://eu.api.anthropic.com/v1").toProxy).toBe(true);
-		expect(dispatchVia(dispatcher, "https://xapi.anthropic.com/v1").toFallback).toBe(true);
-	});
-
-	it("归一化参与分流：大写 / 末尾点 origin 命中规则", () => {
-		const dispatcher = createDispatcher([], ["api.anthropic.com"]);
-		expect(dispatchVia(dispatcher, "https://API.Anthropic.COM./v1").toProxy).toBe(true);
-	});
-
-	it("URL 对象形态的 origin 同样处理", () => {
-		const dispatcher = createDispatcher([], ["api.anthropic.com"]);
-		expect(dispatchVia(dispatcher, new URL("https://api.anthropic.com/v1")).toProxy).toBe(true);
-	});
-
-	it("origin 缺失（无已发生证据的异常路径）→ 委托 fallback + direct 计数，不抛", () => {
-		const dispatcher = createDispatcher([], ["api.anthropic.com"]);
-		expect(() => dispatchVia(dispatcher, undefined)).not.toThrow();
-		expect(counted).toEqual([{ host: "", proxied: false }]);
-	});
-
-	it("计数按主机名聚合可累计（多次请求同主机名同键累加）", () => {
-		const dispatcher = createDispatcher([], ["api.anthropic.com"]);
-		dispatchVia(dispatcher, "https://api.anthropic.com/a");
-		dispatchVia(dispatcher, "https://eu.api.anthropic.com/b");
-		expect(counted).toEqual([
-			{ host: "api.anthropic.com", proxied: true },
-			{ host: "eu.api.anthropic.com", proxied: true },
-		]);
-	});
-
-	it("handler 原样透传给目标分发器（未命中委托语义 = pi 原生行为不变）", () => {
-		const dispatcher = createDispatcher([], []);
-		const handler = { onHeaders: vi.fn() } as unknown as IDispatcher.DispatchHandler;
-		const opts = { origin: "https://any.test", path: "/", method: "GET" } as IDispatcher.DispatchOptions;
-		const seen: Array<unknown> = [];
-		fallbackDispatcher = new RecordingDispatcher();
-		vi.spyOn(fallbackDispatcher, "dispatch").mockImplementation((o, h) => {
-			seen.push({ o, h });
-			return true;
-		});
-		const relay = new RuleDispatchDispatcher({
-			fallback: fallbackDispatcher,
-			proxy: new RecordingDispatcher(),
-			noProxy: [],
-			rules: [],
-			onCount: () => {},
-		});
-		relay.dispatch(opts, handler);
-		expect(seen).toHaveLength(1);
-		expect((seen[0] as { h: unknown }).h).toBe(handler);
-	});
-});
-
 describe("buildProxyUrl（凭据 percent-encode 拼入）", () => {
 	const base: NetworkProxyServer = {
 		protocol: "http",

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

@@ -0,0 +1,324 @@
+/**
+ * fetch 包装状态机单测（fake 依赖注入，不触真实网络）：
+ * 命中/未命中分流、计数、noProxy 优先、禁用恢复、外部覆盖重装、构造失败锁定、
+ * reload 残留摘除、入参形态覆盖。转移表见 fetch-wrapper.ts 文件头。
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Dispatcher } from "undici";
+
+import type { NetworkProxyConfig } from "../config.ts";
+import {
+	applyNetworkProxyConfig,
+	detachResidualFetchWrapper,
+	type FetchLike,
+	type FetchWrapperDeps,
+	type ProxyFetchInit,
+} from "../fetch-wrapper.ts";
+import { resetCounters, snapshotCounters } from "../stats.ts";
+
+class FakeDispatcher extends Dispatcher {}
+
+interface FetchCall { // oe-exempt:20261020:test:测试观测记录形状别名，仅本测试文件消费
+	input: string | URL | Request;
+	init?: RequestInit;
+}
+
+interface ProxyCall { // oe-exempt:20261020:test:测试观测记录形状别名，仅本测试文件消费
+	input: string | URL | Request;
+	init: ProxyFetchInit;
+}
+
+function config(overrides?: Partial<NetworkProxyConfig>): NetworkProxyConfig {
+	return {
+		enabled: true,
+		proxy: { protocol: "http", host: "127.0.0.1", port: 7890, username: "", password: "" },
+		noProxy: ["localhost"],
+		rules: ["api.anthropic.com"],
+		...overrides,
+	};
+}
+
+function withProxy(patch: Partial<NetworkProxyConfig["proxy"]>): Partial<NetworkProxyConfig> {
+	return { proxy: { ...config().proxy, ...patch } };
+}
+
+/** fake 依赖装配：original fetch / 代理 fetch / 构造器全部可观测、可注入失败。 */
+function createHarness() {
+	const originalCalls: FetchCall[] = [];
+	const originalFetch: FetchLike = async (input, init) => {
+		originalCalls.push({ input, init });
+		return new Response("original");
+	};
+	let currentFetch: FetchLike = originalFetch;
+
+	const proxyCalls: ProxyCall[] = [];
+	const proxy = 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;
+	const buildCalls: NetworkProxyConfig[] = [];
+	const errors: string[] = [];
+
+	const deps: FetchWrapperDeps = {
+		getFetch: () => currentFetch,
+		setFetch: (fetch) => {
+			currentFetch = fetch;
+		},
+		buildProxy: (next) => {
+			buildCalls.push(next);
+			return buildProxy(next);
+		},
+		proxyFetch,
+		onError: (message) => errors.push(message),
+	};
+
+	return {
+		deps,
+		originalFetch,
+		originalCalls,
+		proxyCalls,
+		proxy,
+		buildCalls,
+		errors,
+		getCurrent: () => currentFetch,
+		setCurrent: (fetch: FetchLike) => {
+			currentFetch = fetch;
+		},
+		setBuildProxy: (next: (config: NetworkProxyConfig) => Dispatcher) => {
+			buildProxy = next;
+		},
+	};
+}
+
+beforeEach(() => {
+	resetCounters();
+});
+
+describe("applyNetworkProxyConfig 包装状态机", () => {
+	it("首装 enabled：包装 globalThis.fetch 槽位（fake 槽），返回包装状态", () => {
+		const h = createHarness();
+		const state = applyNetworkProxyConfig(config(), null, h.deps);
+		expect(state).not.toBeNull();
+		expect(state?.wrapper).not.toBeNull();
+		expect(h.getCurrent()).toBe(state?.wrapper);
+		expect(h.errors).toHaveLength(0);
+	});
+
+	it("规则命中：走代理 fetch + proxied 计数，init 保留并注入 dispatcher", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config(), null, h.deps);
+		const response = await h.getCurrent()("https://api.anthropic.com/v1/messages", {
+			method: "POST",
+			headers: { "x-test": "1" },
+			body: "{}",
+		});
+		expect(await response.text()).toBe("proxy");
+		expect(h.proxyCalls).toHaveLength(1);
+		expect(h.originalCalls).toHaveLength(0);
+		expect(h.proxyCalls[0]?.init.dispatcher).toBe(h.proxy);
+		expect(h.proxyCalls[0]?.init.method).toBe("POST");
+		expect(h.proxyCalls[0]?.init.headers).toEqual({ "x-test": "1" });
+		expect(h.proxyCalls[0]?.init.body).toBe("{}");
+		expect(snapshotCounters().get("api.anthropic.com")).toEqual({ proxied: 1, direct: 0 });
+	});
+
+	it("规则未命中：原样委托原 fetch + direct 计数", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config(), null, h.deps);
+		const init: RequestInit = { method: "GET" };
+		const response = await h.getCurrent()("https://open.bigmodel.cn/api", init);
+		expect(await response.text()).toBe("original");
+		expect(h.originalCalls).toHaveLength(1);
+		expect(h.originalCalls[0]?.init).toBe(init);
+		expect(h.proxyCalls).toHaveLength(0);
+		expect(snapshotCounters().get("open.bigmodel.cn")).toEqual({ proxied: 0, direct: 1 });
+	});
+
+	it("noProxy 优先于 rules：同主机名两侧都出现时直连", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(
+			config({ noProxy: ["api.anthropic.com"], rules: ["api.anthropic.com"] }),
+			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("子域命中 + 点边界：子域走代理，前缀拼接不命中", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config({ noProxy: [], rules: ["api.anthropic.com"] }), null, h.deps);
+		await h.getCurrent()("https://eu.api.anthropic.com/v1");
+		await h.getCurrent()("https://xapi.anthropic.com/v1");
+		expect(h.proxyCalls).toHaveLength(1);
+		expect(h.originalCalls).toHaveLength(1);
+	});
+
+	it("入参形态：string / URL / Request 都能识别主机名", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config({ noProxy: [], rules: ["api.anthropic.com"] }), null, h.deps);
+		await h.getCurrent()("https://api.anthropic.com/a");
+		await h.getCurrent()(new URL("https://api.anthropic.com/b"));
+		await h.getCurrent()(new Request("https://api.anthropic.com/c"));
+		expect(h.proxyCalls).toHaveLength(3);
+		expect(snapshotCounters().get("api.anthropic.com")).toEqual({ proxied: 3, direct: 0 });
+	});
+
+	it("无法解析目标（相对 URL / 空 host）：原样放行且不计数", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config(), null, h.deps);
+		await h.getCurrent()("/relative/path");
+		await h.getCurrent()(new URL("file:///tmp/a"));
+		expect(h.originalCalls).toHaveLength(2);
+		expect(h.proxyCalls).toHaveLength(0);
+		expect(snapshotCounters().size).toBe(0);
+	});
+
+	it("指纹未变且包装仍在槽位：零动作（状态对象复用，不重建）", () => {
+		const h = createHarness();
+		const state = applyNetworkProxyConfig(config(), null, h.deps);
+		const again = applyNetworkProxyConfig(config(), state, h.deps);
+		expect(again).toBe(state);
+		expect(h.buildCalls).toHaveLength(1);
+	});
+
+	it("指纹变化：重建代理分发器并换新包装", async () => {
+		const h = createHarness();
+		const first = applyNetworkProxyConfig(config(), null, h.deps);
+		const second = applyNetworkProxyConfig(
+			config({ rules: ["api.openai.com"] }),
+			first,
+			h.deps,
+		);
+		expect(second?.wrapper).not.toBe(first?.wrapper);
+		expect(h.buildCalls).toHaveLength(2);
+		await h.getCurrent()("https://api.openai.com/v1");
+		expect(h.proxyCalls).toHaveLength(1);
+	});
+
+	it("槽位被外部覆盖（pi 重跑 configureHttpDispatcher → undici.install）：同指纹也以覆盖者为 original 重新包装", async () => {
+		const h = createHarness();
+		const first = applyNetworkProxyConfig(config(), null, h.deps);
+		// 模拟 pi 设置变更：globalThis.fetch 被 pi 原生实现整体替换，本扩展状态未感知
+		const piReinstalled: FetchLike = async () => new Response("pi-native");
+		h.setCurrent(piReinstalled);
+
+		const again = applyNetworkProxyConfig(config(), first, h.deps);
+		expect(again).not.toBe(first);
+		expect(again?.wrapper).not.toBeNull();
+		expect(h.getCurrent()).toBe(again?.wrapper);
+		// 未命中流量走覆盖者（pi 当前实现），不是旧 original
+		await h.getCurrent()("https://open.bigmodel.cn/api");
+		expect(h.originalCalls).toHaveLength(0);
+		// 命中流量仍走代理
+		await h.getCurrent()("https://api.anthropic.com/v1");
+		expect(h.proxyCalls).toHaveLength(1);
+	});
+
+	it("enabled true→false：恢复原 fetch + 状态清空", () => {
+		const h = createHarness();
+		const state = applyNetworkProxyConfig(config(), null, h.deps);
+		const after = applyNetworkProxyConfig(config({ enabled: false }), state, h.deps);
+		expect(after).toBeNull();
+		expect(h.getCurrent()).toBe(h.originalFetch);
+	});
+
+	it("首装即禁用：零动作", () => {
+		const h = createHarness();
+		expect(applyNetworkProxyConfig(config({ enabled: false }), null, h.deps)).toBeNull();
+		expect(h.buildCalls).toHaveLength(0);
+		expect(h.errors).toHaveLength(0);
+	});
+
+	it("构造失败：onError + 不包装（全直连），同指纹锁定不重试；指纹变化后重试", () => {
+		const h = createHarness();
+		h.setBuildProxy(() => {
+			throw new TypeError("this[kConnector] is not a function");
+		});
+		const locked = applyNetworkProxyConfig(config(), null, h.deps);
+		expect(locked?.wrapper).toBeNull();
+		expect(h.getCurrent()).toBe(h.originalFetch);
+		expect(h.errors).toHaveLength(1);
+		expect(h.errors[0]).toContain("构造失败");
+		expect(h.errors[0]).toContain("直连");
+
+		const stillLocked = applyNetworkProxyConfig(config(), locked, h.deps);
+		expect(stillLocked?.wrapper).toBeNull();
+		expect(h.buildCalls).toHaveLength(1); // 同指纹不重试
+
+		h.setBuildProxy(() => new FakeDispatcher());
+		const recovered = applyNetworkProxyConfig(config(withProxy({ port: 7891 })), stillLocked, h.deps);
+		expect(recovered?.wrapper).not.toBeNull();
+		expect(h.getCurrent()).toBe(recovered?.wrapper);
+	});
+
+	it("运行中重建遇构造失败：撤下旧包装恢复原 fetch，记指纹锁定", () => {
+		const h = createHarness();
+		const installed = applyNetworkProxyConfig(config(), null, h.deps);
+		h.setBuildProxy(() => {
+			throw new Error("socks5 experimental API changed");
+		});
+		const locked = applyNetworkProxyConfig(
+			config(withProxy({ protocol: "socks5" })),
+			installed,
+			h.deps,
+		);
+		expect(locked?.wrapper).toBeNull();
+		expect(h.getCurrent()).toBe(h.originalFetch);
+		expect(h.errors[0]).toContain("socks5");
+	});
+
+	it("锁定态再遇禁用：状态清空、零槽位操作", () => {
+		const h = createHarness();
+		h.setBuildProxy(() => {
+			throw new Error("boom");
+		});
+		const locked = applyNetworkProxyConfig(config(), null, h.deps);
+		const after = applyNetworkProxyConfig(config({ enabled: false }), locked, h.deps);
+		expect(after).toBeNull();
+		expect(h.getCurrent()).toBe(h.originalFetch);
+	});
+});
+
+describe("detachResidualFetchWrapper（reload 残留摘除）", () => {
+	it("installed=null 且槽上是本扩展旧包装：恢复其 original fetch", () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config(), null, h.deps);
+		expect(h.getCurrent()).not.toBe(h.originalFetch);
+
+		// 模拟 reload 后新模块环境：installed=null，槽上仍是旧环境包装
+		detachResidualFetchWrapper(null, h.deps);
+		expect(h.getCurrent()).toBe(h.originalFetch);
+	});
+
+	it("installed=null 且槽上是非本扩展函数：零动作", () => {
+		const h = createHarness();
+		const foreignFetch: FetchLike = async () => new Response("foreign");
+		h.setCurrent(foreignFetch);
+		detachResidualFetchWrapper(null, h.deps);
+		expect(h.getCurrent()).toBe(foreignFetch);
+	});
+
+	it("installed 非 null（同环境 factory 重跑）：早退，不误摘当前包装", () => {
+		const h = createHarness();
+		const state = applyNetworkProxyConfig(config(), null, h.deps);
+		detachResidualFetchWrapper(state, h.deps);
+		expect(h.getCurrent()).toBe(state?.wrapper);
+	});
+
+	it("reload 后重新推进：摘除旧包装后再包新层（不嵌套双计）", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config(), null, h.deps);
+		detachResidualFetchWrapper(null, h.deps);
+		const state = applyNetworkProxyConfig(config(), null, h.deps);
+		expect(state?.originalFetch).toBe(h.originalFetch);
+		await h.getCurrent()("https://api.anthropic.com/v1");
+		expect(h.proxyCalls).toHaveLength(1);
+		expect(snapshotCounters().get("api.anthropic.com")).toEqual({ proxied: 1, direct: 0 });
+	});
+});