@zhushanwen/pi-network-proxy 0.2.0 → 0.2.1

package/src/index.ts

@@ -1,14 +1,12 @@
 /**
- * @zhushanwen/pi-network-proxy 入口：配置驱动的 undici 全局分流分发器安装与事件接线。
+ * @zhushanwen/pi-network-proxy 入口：配置驱动的 globalThis.fetch 包装与事件接线。
  *
- * 行为序列（设计 .tmp/tech-design/llm-network-proxy.md §3.1）：
- * - 加载时：读配置校验，enabled 且校验过 → 捕获原分发器（pi 启动已自装 EnvHttpProxyAgent，
- *   setGlobalDispatcher 是接管而非向空闲槽安装——pi dist/core/http-dispatcher.js:73 构造、
- *   :85 装入全局槽，首次安装 dist/main.js:468 早于 extension 加载）→ 构造分流器安装；
- *   校验失败 / 构造失败 →
- *   extension error（文案含恢复动作：配置文件路径），不安装不阻断 pi（全部直连）。
+ * 行为序列（fetch-wrapper.ts 头注有完整设计依据）：
+ * - 加载时：读配置校验，enabled 且校验过 → 包装 globalThis.fetch（命中规则走代理，
+ *   未命中委托原 fetch）；校验失败 / 构造失败 → extension error（文案含恢复动作：
+ *   配置文件路径），不包装不阻断 pi（全部直连）。
  * - 每 turn 开始：重读配置（llm-shared 读时刷新热重载），指纹变化才重建；enabled true→false
- *   恢复原分发器（installer.ts 状态机）。
+ *   恢复原 fetch（fetch-wrapper.ts 状态机）。
  * - 每 turn 结束：计数增量 flush 追加写入 stats JSONL（stats.ts）；进程退出兜底 flush。
  *
  * 覆盖面含 subagent 的 pi 进程（subagent 的 LLM 请求同样分流计数，设计前提 P4）——不设
@@ -16,7 +14,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { getGlobalDispatcher, setGlobalDispatcher } from "undici";
+import { fetch as undiciFetch } from "undici";
 
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
@@ -26,42 +24,64 @@ import { loadNetworkProxyConfig } from "./config.js";
 import { buildProxyDispatcher } from "./dispatcher.js";
 import {
 	applyNetworkProxyConfig,
-	detachResidualDispatcher,
-	type InstalledState,
-} from "./installer.js";
+	detachResidualFetchWrapper,
+	type FetchWrapperDeps,
+	type FetchWrapperState,
+	type ProxyFetch,
+} from "./fetch-wrapper.js";
 import { ensureExitFlush, flushStats } from "./stats.js";
 
 const logger = getLogger("network-proxy");
 
-/** 进程级安装状态（模块级——全局分发器槽跨 session 存续，session 替换重跑 factory 不丢引用）。 */
-let installed: InstalledState | null = null;
+/** 进程级包装状态（模块级——globalThis.fetch 是进程级资源，session 替换重跑 factory 不丢引用）。 */
+let installed: FetchWrapperState | null = null;
 
 /** 恢复动作文案：所有 error 形态共用的收尾指引（指向配置文件）。 */
 function recoveryHint(): string {
 	return `配置文件: ${getConfigPath("network-proxy")}，修正该文件后自下一轮对话起生效，或删除该文件恢复默认禁用态。`;
 }
 
-/** 读配置并推进安装状态机（加载时与每 turn 开始共用同一入口）；推进前先摘除 reload 残留。 */
+/**
+ * 代理 fetch 适配：pi-ai 的 global Request/Response 与 undici.fetch 的 web 标准类型同构，
+ * 运行时直接透传；dispatcher 由 fetch-wrapper 注入到 init。
+ */
+const proxyFetch: ProxyFetch = (input, init) =>
+	undiciFetch(
+		input as Parameters<typeof undiciFetch>[0],
+		init as Parameters<typeof undiciFetch>[1],
+	);
+
+const deps: FetchWrapperDeps = {
+	getFetch: () => globalThis.fetch,
+	setFetch: (fetch) => {
+		globalThis.fetch = fetch;
+	},
+	buildProxy: buildProxyDispatcher,
+	proxyFetch,
+	onError: (message) => logger.error(`${message} ${recoveryHint()}`),
+};
+
+/** 读配置并推进包装状态机（加载时与每 turn 开始共用同一入口）；推进前先摘除 reload 残留。 */
 function refreshFromConfig(): void {
 	const config = loadNetworkProxyConfig((warning) => {
-		// 非法配置 / 坏 JSON：loadConfig 已回落 defaults（enabled=false → 不安装，全部直连），
+		// 非法配置 / 坏 JSON：loadConfig 已回落 defaults（enabled=false → 不包装，全部直连），
 		// 这里把具体错误记录到 extension 日志通道（appendEntry 持久化 + <agentDir>/logs/
 		// network-proxy-<day>.log 文件日志；验收场景 10 以文件日志为归因口径）。
 		logger.error(`${warning} ${recoveryHint()}`);
 	});
 	try {
-		detachResidualDispatcher(installed, { getGlobalDispatcher, setGlobalDispatcher });
-		installed = applyNetworkProxyConfig(config, installed, {
-			getGlobalDispatcher,
-			setGlobalDispatcher,
-			buildProxy: buildProxyDispatcher,
-			onError: (message) => logger.error(`${message} ${recoveryHint()}`),
-		});
+		if (typeof globalThis.fetch !== "function") {
+			logger.error(`globalThis.fetch 不可用，网络代理不生效（全部直连）。${recoveryHint()}`);
+			installed = null;
+			return;
+		}
+		detachResidualFetchWrapper(installed, deps);
+		installed = applyNetworkProxyConfig(config, installed, deps);
 	} catch (error) {
 		// 辅助功能降级契约（本扩展为 P2 辅助功能，故障不得拖垮 pi 主流程）：状态机推进的
 		// 意外异常不外抛——外抛会升为 pi 用户可见 extension error 且每 turn 重复出现；
-		// 此处保持未安装态（全部直连），错误归因到本扩展日志。
-		logger.error(`network-proxy installer failed: ${toErrorMessage(error)} ${recoveryHint()}`);
+		// 此处保持未包装态（全部直连），错误归因到本扩展日志。
+		logger.error(`network-proxy state update failed: ${toErrorMessage(error)} ${recoveryHint()}`);
 		installed = null;
 	}
 }

package/src/stats.ts

@@ -66,8 +66,8 @@ let exitFlushInstalled = false;
  * jiti 全量 reload 产生的新模块环境会再注册一个 listener，但旧环境的计数 Map 已停更，旧
  * listener flush 空增量为 no-op，无重复行（新环境再注册 = extensions/loader.js:472-476 重新
  * import 重置模块级 once flag 后重跑工厂；旧计数停更 = 旧 runtime 的 turn 订阅被 invalidate
- * 退订（extensions/loader.js:147-149）+ 旧分流器摘除后旧 recordDispatch 不再触发；pi reload
- * 链总锚点见 installer.ts detachResidualDispatcher 注释）。
+ * 退订（extensions/loader.js:147-149）+ 旧 fetch 包装摘除后旧 recordDispatch 不再触发；pi reload
+ * 链总锚点见 fetch-wrapper.ts detachResidualFetchWrapper 注释）。
  */
 export function ensureExitFlush(): void {
 	if (exitFlushInstalled) return;

package/src/__tests__/installer.test.ts

@@ -1,313 +0,0 @@
-/**
- * 安装状态机单测（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);
-	});
-});

package/src/installer.ts

@@ -1,165 +0,0 @@
-/**
- * 分流器安装状态机（设计 §3.1 行为序列 1/2 + §3.3 决策 5/8）。
- *
- * 进程级单一安装状态（全局分发器槽是进程级资源，状态必须模块级持有——session 替换重跑
- * factory 时不因闭包重建丢失 originalDispatcher 引用）。转移表：
- *
- * | 当前态           | 事件（新配置）      | 动作                                   | 次态 |
- * |-----------------|--------------------|----------------------------------------|------|
- * | 任意            | enabled=false      | 槽上仍是分流器则恢复 original（仅限槽位归属核查通过） | null |
- * | null            | enabled+新指纹     | 捕获 original → 构造 → 安装             | 装载 |
- * | 装载            | enabled+同指纹+槽位仍归本扩展 | 无动作（不重建不重复安装）        | 装载 |
- * | 装载            | enabled+同指纹+槽位被外部覆盖 | 撤旧装新（pi 启动重装覆盖形态，original=覆盖者） | 装载 |
- * | 锁定            | enabled+同指纹     | 无动作（首败即停不重试）                 | 锁定 |
- * | 任意            | enabled+新指纹     | 构造成功 → 撤旧装新                     | 装载 |
- * | 任意            | enabled+构造失败   | error 上报 + 撤旧（全部直连），记指纹锁定 | 锁定 |
- *
- * 锁定态（current=null）：同指纹不重试构造（fail-fast 首败即停，AGENTS.md 事实驱动原则⑧）；
- * 用户修正配置 → 指纹变化 → 自然重试。依赖注入（get/setGlobalDispatcher、buildProxy、
- * onError）使状态机在单测中以 fake 依赖驱动，不 mock undici 全局槽。
- *
- * 状态机前置伴随入口 = detachResidualDispatcher：jiti 全量 reload 后 installed=null 但槽上
- * 仍挂着旧环境残留分流器，状态机自身无法区分「真无状态」与「reload 残留」，由它在推进前
- * 摘除（转移表各分支才从干净基线成立；pi reload 链实装锚点见该函数注释）。
- */
-
-import type { Dispatcher as IDispatcher } from "undici";
-
-import { networkProxyFingerprint, type NetworkProxyConfig } from "./config.js";
-import { isRuleDispatchDispatcher, RuleDispatchDispatcher } from "./dispatcher.js";
-import { recordDispatch } from "./stats.js";
-
-/** 当前安装状态；null = 未安装（槽上是 pi 原生分发器）。 */
-export interface InstalledState { // oe-exempt:20261019:framework:安装状态机载体形状（状态机唯一状态类型，单实现为常态）
-
-	/** 安装前捕获的原分发器引用（首次捕获后跨重建保留——恢复与 fallback 都用它）。 */
-	originalDispatcher: IDispatcher;
-	/** 已安装（或已锁定失败）配置的指纹。 */
-	fingerprint: string;
-	/** 槽上的分流器；null = 构造失败锁定态（未安装）。 */
-	current: IDispatcher | null;
-}
-
-export interface InstallerDeps { // oe-exempt:20261019:framework:安装状态机依赖注入接缝（单测注入 get/setGlobalDispatcher 与可抛 buildProxy）
-
-	getGlobalDispatcher: () => IDispatcher;
-	setGlobalDispatcher: (dispatcher: IDispatcher) => void;
-	/** 代理分发器构造（可注入抛错——「构造失败 → 不安装 → 全直连」单测入口）。 */
-	buildProxy: (config: NetworkProxyConfig) => IDispatcher;
-	/** extension error 呈现（logger.error；文案含恢复动作）。 */
-	onError: (message: string) => void;
-}
-
-/**
- * reload 残留摘除（设计 §3.1 行为序列 2 在 reload 窗口的兑现）：jiti 全量 reload 后本扩展
- * 换了新模块环境，installed=null 但全局槽仍挂着旧环境安装的 RuleDispatchDispatcher——
- * 不摘除则 enabled=false 状态机判「无状态」零动作（旧分流器继续生效，禁用失效），或
- * enabled=true 时旧分流器被捕获为 original 嵌套（同一请求经新旧两层各计一次，统计双计）。
- * 摘除 = 恢复残留分流器安装时捕获的原分发器（fallback 引用），状态机从干净基线推进。
- * installed 非 null（同环境 factory 重跑）早退：槽上就是 state.current，摘掉会与
- * 「指纹未变无动作」分支冲突（分流器被摘而状态机不重装）。
- *
- * pi reload 链实装锚点（@earendil-works/pi-coding-agent 1.0.0 dist，逐文件读码核实）：
- * agent-session.js:2899 reload() → :2903 oldRunner.invalidate()（extensions/loader.js:141-149
- * 退订旧 runtime 的全部 eventBus 订阅）→ :2908 resourceLoader.reload()（resource-loader.js:350，
- * :353 clearExtensionCache() 清空 jiti 模块缓存并递增缓存代际）→ loader.js:456-484 缓存代际
- * 失效后 :472-476 新建 jiti 实例（moduleCache: false）重新 import 本扩展、:505-509 重跑工厂
- * ——新环境模块级 installed 重置为 null，旧环境分流器滞留全局槽无人恢复，即本函数的前提。
- */
-export function detachResidualDispatcher(
-	installed: InstalledState | null,
-	deps: Pick<InstallerDeps, "getGlobalDispatcher" | "setGlobalDispatcher">,
-): void {
-	if (installed !== null) return;
-	const current = deps.getGlobalDispatcher();
-	if (!isRuleDispatchDispatcher(current)) return;
-	deps.setGlobalDispatcher(current.fallback);
-}
-
-/**
- * 禁用态收口（转移表首行）：恢复仅限槽位仍归本扩展时执行——槽位已被外部覆盖（pi 启动重装，
- * 见下）时槽上已是 pi 原生分发器，回写 state.originalDispatcher 会把它挤掉（无害但多余），
- * 语义上禁用 = 摘除自己的安装，不是改写别人的。
- */
-function restoreOriginalIfOwned(
-	state: InstalledState | null,
-	deps: Pick<InstallerDeps, "getGlobalDispatcher" | "setGlobalDispatcher">,
-): void {
-	if (state?.current && deps.getGlobalDispatcher() === state.current) {
-		deps.setGlobalDispatcher(state.originalDispatcher);
-	}
-}
-
-/**
- * 槽位归属核查（pi 启动时序缺陷的根因修复）：pi 1.0.0 启动序列在 extension 安装之后
- * 仍会重跑 configureHttpDispatcher() 整槽覆盖（dist main.js:707 实证）——指纹未变但槽上
- * 已非本扩展分发器时按「撤旧装新」重装。original 统一取槽上现持有者：覆盖场景下
- * state.originalDispatcher 是上一代 pi 原生分发器，fallback 必须指向当前覆盖者才是
- * 「未命中委托 = 未安装本扩展时 pi 的确切行为」。
- */
-function resolveOriginal(state: InstalledState | null, slotNow: IDispatcher): IDispatcher {
-	return state && state.current !== null && slotNow === state.current
-		? state.originalDispatcher
-		: slotNow;
-}
-
-/** 构造失败收口（转移表末行）：error 上报 + 撤旧（全部直连），返回记指纹的锁定态。 */
-function lockOnBuildFailure(
-	config: NetworkProxyConfig,
-	state: InstalledState | null,
-	original: IDispatcher,
-	fingerprint: string,
-	deps: InstallerDeps,
-	error: unknown,
-): InstalledState {
-	deps.onError(
-		`网络代理分流器构造失败（协议 ${config.proxy.protocol}），已保持全部直连，不影响 pi 运行；` +
-			`可核对代理配置后保存重试，或关闭网络代理开关。构造错误: ${error instanceof Error ? error.message : String(error)}`,
-	);
-	if (state?.current) {
-		deps.setGlobalDispatcher(original);
-	}
-	return { originalDispatcher: original, fingerprint, current: null };
-}
-
-/**
- * 按新配置推进安装状态机（见模块头转移表）。config 契约 = loadNetworkProxyConfig 产物
- * （normalize 已校验合法——非法配置在读取层回落 defaults+error，构造性到达本函数恒合法）。
- */
-export function applyNetworkProxyConfig(
-	config: NetworkProxyConfig,
-	state: InstalledState | null,
-	deps: InstallerDeps,
-): InstalledState | null {
-	if (!config.enabled) {
-		restoreOriginalIfOwned(state, deps);
-		return null;
-	}
-
-	const fingerprint = networkProxyFingerprint(config);
-	if (state && state.fingerprint === fingerprint && state.current === null) {
-		return state; // 锁定态：同指纹不重试构造（首败即停，决策 8）
-	}
-	const slotNow = deps.getGlobalDispatcher();
-	if (state && state.fingerprint === fingerprint && slotNow === state.current) {
-		return state; // 同指纹且槽位仍归本扩展：无动作（不重建不重复安装）
-	}
-	const original = resolveOriginal(state, slotNow);
-
-	let proxy: IDispatcher;
-	try {
-		proxy = deps.buildProxy(config);
-	} catch (error) {
-		return lockOnBuildFailure(config, state, original, fingerprint, deps, error);
-	}
-
-	const dispatcher = new RuleDispatchDispatcher({
-		fallback: original,
-		proxy,
-		noProxy: config.noProxy,
-		rules: config.rules,
-		onCount: recordDispatch,
-	});
-	deps.setGlobalDispatcher(dispatcher);
-	return { originalDispatcher: original, fingerprint, current: dispatcher };
-}