@zhushanwen/pi-network-proxy 0.0.0-stage → 0.2.0

package/src/__tests__/dispatcher.test.ts

@@ -0,0 +1,156 @@
+/**
+ * 分流分发器行为 + 代理 URL 构造（dispatch 拦截点 / noProxy 优先 / 计数时点 / 委托语义）。
+ * 两协议构造形态冒烟在 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 { buildProxyUrl, RuleDispatchDispatcher } 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",
+		host: "127.0.0.1",
+		port: 7890,
+		username: "",
+		password: "",
+	};
+
+	it("无凭据形态", () => {
+		expect(buildProxyUrl(base)).toBe("http://127.0.0.1:7890");
+	});
+
+	it("凭据 percent-encode 拼入（特殊字符被编码，undici 构造内部 decodeURIComponent 还原）", () => {
+		expect(buildProxyUrl({ ...base, username: "user@example.com", password: "p@ss:word" })).toBe(
+			"http://user%40example.com:p%40ss%3Aword@127.0.0.1:7890",
+		);
+	});
+
+	it("socks5 协议形态（Socks5ProxyAgent 校验 socks5: 协议头）", () => {
+		expect(buildProxyUrl({ ...base, protocol: "socks5", port: 1080 })).toBe("socks5://127.0.0.1:1080");
+	});
+
+	it("https 协议形态", () => {
+		expect(buildProxyUrl({ ...base, protocol: "https", port: 443 })).toBe("https://127.0.0.1:443");
+	});
+});

package/src/__tests__/index.test.ts

@@ -0,0 +1,157 @@
+/**
+ * extension 入口行为单测（真实组件 + tmp agentDir，不 mock undici 全局槽与配置读取链）：
+ * 工厂加载序列（校验过 → 安装分流器 / 非法 → error + 全直连）、turn 粒度热生效
+ * （turn_start 重读配置、turn_end flush 计数）。vi.resetModules 隔离模块级 installed 状态。
+ * fs-guard 白名单：写入目标 = PI_CODING_AGENT_DIR 注入的 mkdtemp tmp 目录。
+ */
+import { mkdtempSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { getGlobalDispatcher, setGlobalDispatcher, type Dispatcher } from "undici";
+
+const { loggerMock } = vi.hoisted(() => ({
+	loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+	createLogger: () => loggerMock,
+	setPiHandle: vi.fn(),
+}));
+
+import { isRuleDispatchDispatcher, RuleDispatchDispatcher } from "../dispatcher.ts";
+
+/** fake pi ExtensionAPI：收集 on 注册的 handler，emit 触发。 */
+function createFakePi() {
+	const handlers = new Map<string, Array<() => void>>();
+	const pi = {
+		on: (event: string, handler: () => void) => {
+			const list = handlers.get(event) ?? [];
+			list.push(handler);
+			handlers.set(event, list);
+		},
+	} as unknown as import("@earendil-works/pi-coding-agent").ExtensionAPI;
+	return {
+		pi,
+		emit: (event: "turn_start" | "turn_end") => {
+			for (const h of handlers.get(event) ?? []) h();
+		},
+	};
+}
+
+const ENABLED_CONFIG = {
+	enabled: true,
+	proxy: { protocol: "http", host: "127.0.0.1", port: 7890, username: "", password: "" },
+	noProxy: ["localhost"],
+	rules: ["api.anthropic.com"],
+};
+
+let agentDir: string;
+let savedDispatcher: Dispatcher;
+
+function writeConfigFile(content: string): void {
+	mkdirSync(join(agentDir, "config"), { recursive: true });
+	writeFileSync(join(agentDir, "config", "network-proxy-ext-config.json"), content);
+}
+
+beforeEach(() => {
+	agentDir = mkdtempSync(join(tmpdir(), "network-proxy-index-"));
+	vi.stubEnv("PI_CODING_AGENT_DIR", agentDir);
+	// 保存 undici 全局槽，afterEach 恢复（工厂安装/摘除都改写这个槽）
+	savedDispatcher = getGlobalDispatcher();
+	loggerMock.error.mockClear();
+});
+
+afterEach(() => {
+	setGlobalDispatcher(savedDispatcher);
+	vi.unstubAllEnvs();
+	vi.resetModules();
+});
+
+describe("networkProxyExtension 工厂加载序列", () => {
+	it("enabled 且校验过：安装分流器到全局槽（识别走 RuleDispatchDispatcher）", async () => {
+		writeConfigFile(JSON.stringify(ENABLED_CONFIG));
+		const { default: networkProxyExtension } = await import("../index.ts");
+		networkProxyExtension(createFakePi().pi);
+		expect(isRuleDispatchDispatcher(getGlobalDispatcher())).toBe(true);
+		expect(getGlobalDispatcher()).toBeInstanceOf(RuleDispatchDispatcher);
+		expect(loggerMock.error).not.toHaveBeenCalled();
+	});
+
+	it("enabled=false：不安装（槽保持 pi 原生分发器），零 error", async () => {
+		writeConfigFile(JSON.stringify({ ...ENABLED_CONFIG, enabled: false }));
+		const { default: networkProxyExtension } = await import("../index.ts");
+		networkProxyExtension(createFakePi().pi);
+		expect(getGlobalDispatcher()).toBe(savedDispatcher);
+		expect(loggerMock.error).not.toHaveBeenCalled();
+	});
+
+	it("非法配置（坏 JSON）：不抛、不安装（全部直连），error 含恢复动作（配置文件路径）", async () => {
+		writeConfigFile("{ not valid json");
+		const { default: networkProxyExtension } = await import("../index.ts");
+		expect(() => networkProxyExtension(createFakePi().pi)).not.toThrow();
+		expect(getGlobalDispatcher()).toBe(savedDispatcher);
+		const messages = loggerMock.error.mock.calls.map((c) => String(c[0]));
+		expect(messages.some((m) => m.includes("network-proxy-ext-config.json"))).toBe(true);
+	});
+
+	it("非法字段（端口越界）：loadConfig 回落 defaults（enabled=false → 不安装）+ error 可归因", async () => {
+		writeConfigFile(JSON.stringify({ ...ENABLED_CONFIG, proxy: { ...ENABLED_CONFIG.proxy, port: 99999 } }));
+		const { default: networkProxyExtension } = await import("../index.ts");
+		expect(() => networkProxyExtension(createFakePi().pi)).not.toThrow();
+		expect(getGlobalDispatcher()).toBe(savedDispatcher);
+		expect(loggerMock.error.mock.calls.length).toBeGreaterThan(0);
+	});
+});
+
+describe("turn 粒度热生效", () => {
+	it("turn_start 重读配置：指纹变化重建（槽上换新分流器），未变零动作", async () => {
+		writeConfigFile(JSON.stringify(ENABLED_CONFIG));
+		const { default: networkProxyExtension } = await import("../index.ts");
+		const { pi, emit } = createFakePi();
+		networkProxyExtension(pi);
+		const first = getGlobalDispatcher();
+
+		// 未变配置：同分发器（不重建）
+		emit("turn_start");
+		expect(getGlobalDispatcher()).toBe(first);
+
+		// 改写配置（size 变化 → mtime+size 缓存失效）：指纹变化重建
+		writeConfigFile(JSON.stringify({ ...ENABLED_CONFIG, rules: ["api.openai.com"] }));
+		emit("turn_start");
+		const second = getGlobalDispatcher();
+		expect(second).not.toBe(first);
+		expect(isRuleDispatchDispatcher(second)).toBe(true);
+	});
+
+	it("turn_end flush 计数增量到 stats JSONL（recordDispatch → turn_end → 落盘行）", async () => {
+		writeConfigFile(JSON.stringify(ENABLED_CONFIG));
+		const { default: networkProxyExtension } = await import("../index.ts");
+		// resetModules 后 index.ts 与此处 import 的 stats.ts 是同一模块图刷新的同一实例
+		const { recordDispatch } = await import("../stats.ts");
+		const { statsFilePath } = await import("../stats.ts");
+		const { pi, emit } = createFakePi();
+		networkProxyExtension(pi);
+
+		recordDispatch("api.anthropic.com", true);
+		recordDispatch("open.bigmodel.cn", false);
+		emit("turn_end");
+
+		const lines = readFileSync(statsFilePath(), "utf-8").split("\n").filter((l) => l !== "");
+		expect(lines).toHaveLength(2);
+		const hosts = lines.map((l) => (JSON.parse(l) as { host: string }).host).sort();
+		expect(hosts).toEqual(["api.anthropic.com", "open.bigmodel.cn"]);
+	});
+
+	it("enabled true→false：turn_start 后恢复 pi 原生分发器（禁用生效）", async () => {
+		writeConfigFile(JSON.stringify(ENABLED_CONFIG));
+		const { default: networkProxyExtension } = await import("../index.ts");
+		const { pi, emit } = createFakePi();
+		networkProxyExtension(pi);
+		expect(isRuleDispatchDispatcher(getGlobalDispatcher())).toBe(true);
+
+		writeConfigFile(JSON.stringify({ ...ENABLED_CONFIG, enabled: false }));
+		emit("turn_start");
+		expect(getGlobalDispatcher()).toBe(savedDispatcher);
+	});
+});

package/src/__tests__/installer.test.ts

@@ -0,0 +1,313 @@
+/**
+ * 安装状态机单测（fake 依赖注入，不 mock undici 全局槽）：
+ * 指纹比对重建 / 禁用恢复原分发器 / 「构造失败 → 不安装 → 全直连」mock 注入（任务书验收②）。
+ * 转移表见 installer.ts 文件头。
+ */
+import { describe, expect, it, vi } from "vitest";
+import { Dispatcher } from "undici";
+
+import type { NetworkProxyConfig } from "../config.ts";
+import { RuleDispatchDispatcher } from "../dispatcher.ts";
+import {
+	applyNetworkProxyConfig,
+	detachResidualDispatcher,
+	type InstalledState,
+	type InstallerDeps,
+} from "../installer.ts";
+
+class FakeDispatcher extends Dispatcher {
+	readonly label: string;
+	constructor(label: string) {
+		super();
+		this.label = label;
+	}
+}
+
+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,
+	};
+}
+
+/** proxy 字段深覆盖辅助（overrides 是浅合并——protocol/port 必须写进 proxy 对象才进指纹）。 */
+function withProxy(patch: Partial<NetworkProxyConfig["proxy"]>): Partial<NetworkProxyConfig> {
+	return { proxy: { ...config().proxy, ...patch } };
+}
+
+/** fake 依赖装配：original 捕获、set 调用记录、可注入的构造器（默认成功）。
+ * original 可注入共享（真实场景进程内只有一个原分发器——跨 deps 实例传状态时恢复的是
+ * 首装 deps 捕获的同一实例）。 */
+function createDeps(
+	buildProxy: (c: NetworkProxyConfig) => FakeDispatcher = () => new FakeDispatcher("proxy"),
+	sharedOriginal = new FakeDispatcher("original"),
+) {
+	const original = sharedOriginal;
+	// get/set 连通同一槽变量（与真实全局槽语义一致：set 改写 get 的返回）——
+	// 槽位归属核查（installer 同指纹分支）依赖该语义判「槽上是谁」。
+	let slot: FakeDispatcher = original;
+	const setCalls: FakeDispatcher[] = [];
+	const errors: string[] = [];
+	const deps: InstallerDeps & { original: FakeDispatcher; setCalls: FakeDispatcher[]; errors: string[] } = {
+		getGlobalDispatcher: () => slot,
+		setGlobalDispatcher: (d) => {
+			slot = d as FakeDispatcher;
+			setCalls.push(d as FakeDispatcher);
+		},
+		buildProxy,
+		onError: (message) => errors.push(message),
+		original,
+		setCalls,
+		errors,
+	};
+	return deps;
+}
+
+describe("applyNetworkProxyConfig 状态机", () => {
+	it("首装 enabled：捕获 original → 构造 → 安装，状态装载", () => {
+		const deps = createDeps();
+		const state = applyNetworkProxyConfig(config(), null, deps);
+		expect(state).not.toBeNull();
+		expect(state?.current).toBeInstanceOf(RuleDispatchDispatcher);
+		expect(state?.originalDispatcher).toBe(deps.original);
+		expect(deps.setCalls).toHaveLength(1);
+		expect(deps.errors).toHaveLength(0);
+	});
+
+	it("指纹未变：不重建不重复安装（setGlobalDispatcher 零调用）", () => {
+		const deps = createDeps();
+		const state = applyNetworkProxyConfig(config(), null, deps);
+		expect(deps.setCalls).toHaveLength(1);
+		const again = applyNetworkProxyConfig(config(), state, deps);
+		expect(again).toBe(state);
+		expect(deps.setCalls).toHaveLength(1);
+	});
+
+	it("指纹变化：撤旧装新，original 引用跨重建保留", () => {
+		const deps = createDeps();
+		const first = applyNetworkProxyConfig(config(), null, deps);
+		const changed = applyNetworkProxyConfig(
+			config({ rules: ["api.openai.com"] }),
+			first,
+			deps,
+		);
+		expect(changed?.current).not.toBe(first?.current);
+		expect(changed?.originalDispatcher).toBe(deps.original);
+		expect(deps.setCalls).toHaveLength(2);
+	});
+
+	it("enabled true→false：恢复原分发器（槽上回到 original）+ 状态清空", () => {
+		const deps = createDeps();
+		const installed = applyNetworkProxyConfig(config(), null, deps);
+		const after = applyNetworkProxyConfig(config({ enabled: false }), installed, deps);
+		expect(after).toBeNull();
+		expect(deps.setCalls).toHaveLength(2);
+		expect(deps.setCalls[1]).toBe(deps.original);
+	});
+
+	it("首装即禁用（enabled=false + 无状态）：零动作", () => {
+		const deps = createDeps();
+		expect(applyNetworkProxyConfig(config({ enabled: false }), null, deps)).toBeNull();
+		expect(deps.setCalls).toHaveLength(0);
+		expect(deps.errors).toHaveLength(0);
+	});
+
+	it("构造失败（mock 注入抛错）：onError 上报 + 不安装（setGlobalDispatcher 零调用）——全直连", () => {
+		const deps = createDeps(() => {
+			throw new TypeError("this[kConnector] is not a function");
+		});
+		const state = applyNetworkProxyConfig(config(), null, deps);
+		expect(state?.current).toBeNull();
+		expect(deps.setCalls).toHaveLength(0); // 槽上仍是 pi 原生分发器 = 全部直连
+		expect(deps.errors).toHaveLength(1);
+		expect(deps.errors[0]).toContain("构造失败");
+		expect(deps.errors[0]).toContain("直连");
+	});
+
+	it("锁定态同指纹不重试构造；指纹变化后重试（用户修正配置自然恢复）", () => {
+		let shouldThrow = true;
+		const deps = createDeps(() => {
+			if (shouldThrow) throw new Error("boom");
+			return new FakeDispatcher("proxy");
+		});
+		const locked = applyNetworkProxyConfig(config(), null, deps);
+		expect(locked?.current).toBeNull();
+
+		// 同指纹：不重试（fail-fast 首败即停）
+		const stillLocked = applyNetworkProxyConfig(config(), locked, deps);
+		expect(stillLocked?.current).toBeNull();
+		expect(deps.errors).toHaveLength(1);
+
+		// 用户修正（端口变化 → 指纹变化）：重试成功并安装
+		shouldThrow = false;
+		const recovered = applyNetworkProxyConfig(config(withProxy({ port: 7891 })), stillLocked, deps);
+		expect(recovered?.current).toBeInstanceOf(RuleDispatchDispatcher);
+		expect(deps.setCalls).toHaveLength(1);
+	});
+
+	it("运行中重建遇构造失败：撤下旧分流器恢复原分发器（全部直连），记指纹锁定", () => {
+		const sharedOriginal = new FakeDispatcher("original");
+		const deps = createDeps(() => new FakeDispatcher("proxy"), sharedOriginal);
+		const installed = applyNetworkProxyConfig(config(), null, deps);
+		expect(deps.setCalls).toHaveLength(1);
+
+		const failing = createDeps(() => {
+			throw new Error("socks5 experimental API changed");
+		}, sharedOriginal);
+		const locked = applyNetworkProxyConfig(config(withProxy({ protocol: "socks5" })), installed, failing);
+		expect(locked?.current).toBeNull();
+		// 撤旧：set 收到 original（回 pi 原生行为 = 全部直连/env 代理路由）
+		expect(failing.setCalls).toHaveLength(1);
+		expect(failing.setCalls[0]).toBe(sharedOriginal);
+		expect(failing.errors[0]).toContain("socks5");
+	});
+
+	it("锁定态再遇禁用：无槽操作、状态清空（构造失败后关开关 = 干净退出）", () => {
+		const deps = createDeps(() => {
+			throw new Error("boom");
+		});
+		const locked = applyNetworkProxyConfig(config(), null, deps);
+		const after = applyNetworkProxyConfig(config({ enabled: false }), locked, deps);
+		expect(after).toBeNull();
+		expect(deps.setCalls).toHaveLength(0);
+	});
+
+	it("安装状态的 current 即 setGlobalDispatcher 收到的实例（槽与状态一致）", () => {
+		const deps = createDeps();
+		const state: InstalledState | null = applyNetworkProxyConfig(config(), null, deps);
+		expect(deps.setCalls[0]).toBe(state?.current);
+		expect(vi.isMockFunction(deps.onError)).toBe(false);
+	});
+
+	// ── 槽位归属核查（pi 启动序列在 extension 安装后重跑 configureHttpDispatcher 整槽覆盖，
+	// dist main.js:707 实证——指纹未变也必须重装，否则会话整段生命周期不走代理）──
+
+	/** 可变槽 deps：getGlobalDispatcher 返回当前槽变量（覆盖测试用，createDeps 槽固定）。 */
+	function createMutableSlotDeps(initialSlot: FakeDispatcher) {
+		let slot: FakeDispatcher = initialSlot;
+		const setCalls: FakeDispatcher[] = [];
+		const errors: string[] = [];
+		const deps: InstallerDeps & { setCalls: FakeDispatcher[]; errors: string[]; setSlot: (d: FakeDispatcher) => void } = {
+			getGlobalDispatcher: () => slot,
+			setGlobalDispatcher: (d) => {
+				slot = d as FakeDispatcher;
+				setCalls.push(d as FakeDispatcher);
+			},
+			buildProxy: () => new FakeDispatcher("proxy"),
+			onError: (message) => errors.push(message),
+			setCalls,
+			errors,
+			setSlot: (d) => {
+				slot = d;
+			},
+		};
+		return deps;
+	}
+
+	it("同指纹但槽位被外部覆盖（pi 启动重装形态）：撤旧装新，fallback = 覆盖者", () => {
+		const piNative = new FakeDispatcher("pi-native");
+		const deps = createMutableSlotDeps(piNative);
+		const first = applyNetworkProxyConfig(config(), null, deps);
+		expect(first?.current).not.toBeNull();
+		// pi 启动序列整槽覆盖：槽上换成 pi 原生分发器，本扩展状态未感知
+		const overwritten = new FakeDispatcher("pi-native-after-reconfigure");
+		deps.setSlot(overwritten);
+		// 同一配置（指纹未变）下一 turn 推进：必须重装
+		const again = applyNetworkProxyConfig(config(), first, deps);
+		expect(again?.current).not.toBeNull();
+		expect(again?.current).not.toBe(first?.current);
+		expect(again?.fingerprint).toBe(first?.fingerprint);
+		// 新分流器 fallback = 槽上覆盖者（未命中委托 = 覆盖者的行为）
+		expect((again?.current as RuleDispatchDispatcher).fallback).toBe(overwritten);
+		// 槽上回到本扩展分发器
+		expect(deps.getGlobalDispatcher()).toBe(again?.current);
+	});
+
+	it("同指纹且槽位仍归本扩展：零动作（覆盖核查不误伤既有无动作分支）", () => {
+		const deps = createMutableSlotDeps(new FakeDispatcher("pi-native"));
+		const first = applyNetworkProxyConfig(config(), null, deps);
+		const setCallsAfterInstall = deps.setCalls.length;
+		const again = applyNetworkProxyConfig(config(), first, deps);
+		expect(again).toBe(first);
+		expect(deps.setCalls).toHaveLength(setCallsAfterInstall);
+	});
+
+	it("禁用时槽位已被外部覆盖：不回写（槽保持覆盖者）、状态清空", () => {
+		const deps = createMutableSlotDeps(new FakeDispatcher("pi-native"));
+		const installed = applyNetworkProxyConfig(config(), null, deps);
+		const overwritten = new FakeDispatcher("pi-native-after-reconfigure");
+		deps.setSlot(overwritten);
+		const setCallsAfterInstall = deps.setCalls.length;
+		const after = applyNetworkProxyConfig(config({ enabled: false }), installed, deps);
+		expect(after).toBeNull();
+		expect(deps.setCalls).toHaveLength(setCallsAfterInstall);
+		expect(deps.getGlobalDispatcher()).toBe(overwritten);
+	});
+});
+
+describe("detachResidualDispatcher（reload 残留摘除）", () => {
+	/** 模拟旧模块环境残留在全局槽上的分流器（跨环境识别走 Symbol.for 标记，不走 instanceof）。 */
+	function residualDispatcher(original: FakeDispatcher): RuleDispatchDispatcher {
+		return new RuleDispatchDispatcher({
+			fallback: original,
+			proxy: new FakeDispatcher("proxy"),
+			noProxy: [],
+			rules: [],
+			onCount: () => {},
+		});
+	}
+
+	it("installed=null 且槽上是残留分流器：恢复其 fallback（旧环境安装时捕获的原分发器）", () => {
+		const sharedOriginal = new FakeDispatcher("original");
+		const deps = createDeps(() => new FakeDispatcher("proxy"), sharedOriginal);
+		const residual = residualDispatcher(sharedOriginal);
+		detachResidualDispatcher(null, { ...deps, getGlobalDispatcher: () => residual });
+		expect(deps.setCalls).toEqual([sharedOriginal]);
+	});
+
+	it("installed=null 且槽上是 pi 原生分发器（非本扩展）：零动作", () => {
+		const deps = createDeps();
+		detachResidualDispatcher(null, deps);
+		expect(deps.setCalls).toHaveLength(0);
+	});
+
+	it("installed 非 null（同环境 factory 重跑）：早退零动作——槽上 current 不被误摘", () => {
+		const deps = createDeps();
+		const state = applyNetworkProxyConfig(config(), null, deps);
+		expect(state).not.toBeNull();
+		detachResidualDispatcher(state, deps);
+		expect(deps.setCalls).toHaveLength(1); // 仅首装那一次，摘除未触发
+	});
+
+	it("reload 后推进状态机：enabled=false 恢复直连（摘除 + 零动作，无旧分流器残留）", () => {
+		const sharedOriginal = new FakeDispatcher("original");
+		const deps = createDeps(() => new FakeDispatcher("proxy"), sharedOriginal);
+		const residual = residualDispatcher(sharedOriginal);
+		// reload 形态：新环境 installed=null、槽上是旧环境残留
+		detachResidualDispatcher(null, { ...deps, getGlobalDispatcher: () => residual });
+		const after = applyNetworkProxyConfig(config({ enabled: false }), null, {
+			...deps,
+			getGlobalDispatcher: () => sharedOriginal,
+		});
+		expect(after).toBeNull();
+		expect(deps.setCalls).toEqual([sharedOriginal]); // 摘除那一次；禁用分支零动作
+	});
+
+	it("reload 后推进状态机：enabled=true 捕获的 original 是原分发器（无嵌套双计）", () => {
+		const sharedOriginal = new FakeDispatcher("original");
+		const deps = createDeps(() => new FakeDispatcher("proxy"), sharedOriginal);
+		const residual = residualDispatcher(sharedOriginal);
+		detachResidualDispatcher(null, { ...deps, getGlobalDispatcher: () => residual });
+		const state = applyNetworkProxyConfig(config(), null, {
+			...deps,
+			getGlobalDispatcher: () => sharedOriginal,
+		});
+		expect(state?.originalDispatcher).toBe(sharedOriginal);
+		expect(state?.current).toBeInstanceOf(RuleDispatchDispatcher);
+		// 新分流器的 fallback 是原分发器而非旧残留——同一请求只经一层计数
+		expect((state?.current as RuleDispatchDispatcher).fallback).toBe(sharedOriginal);
+	});
+});