@zhushanwen/pi-network-proxy 0.2.0 → 0.2.2

package/src/__tests__/index.test.ts

@@ -1,6 +1,6 @@
 /**
- * extension 入口行为单测（真实组件 + tmp agentDir，不 mock undici 全局槽与配置读取链）：
- * 工厂加载序列（校验过 → 安装分流器 / 非法 → error + 全直连）、turn 粒度热生效
+ * extension 入口行为单测（真实组件 + tmp agentDir，不 mock 配置读取链）：
+ * 工厂加载序列（校验过 → 包装 globalThis.fetch / 非法 → error + 全直连）、turn 粒度热生效
  * （turn_start 重读配置、turn_end flush 计数）。vi.resetModules 隔离模块级 installed 状态。
  * fs-guard 白名单：写入目标 = PI_CODING_AGENT_DIR 注入的 mkdtemp tmp 目录。
  */
@@ -8,19 +8,17 @@ 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";
 
+// mock 只覆盖本包模块图实际消费的导出（getLogger / setPiHandle；createLogger 无消费方，
+// 推测性 mock 会在 logger 包改表面时静默失配——缺导出是显式 undefined， loud fail）
 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>>();
@@ -46,92 +44,117 @@ const ENABLED_CONFIG = {
 	rules: ["api.anthropic.com"],
 };
 
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
 let agentDir: string;
-let savedDispatcher: Dispatcher;
+let savedFetch: FetchLike;
+let fakeFetch: FetchLike;
+let fakeCalls: number;
 
 function writeConfigFile(content: string): void {
 	mkdirSync(join(agentDir, "config"), { recursive: true });
 	writeFileSync(join(agentDir, "config", "network-proxy-ext-config.json"), content);
 }
 
+/**
+ * 标准前导：写配置文件 → 加载 extension（afterEach 的 resetModules 后每次 import
+ * 都是新模块图实例）→ 装配 fake pi 并执行工厂。config = 配置文件内容（默认 enabled）。
+ * 工厂在 helper 内执行：非法配置用例的「不抛」契约由 await 拒绝等价保证（抛即用例红）。
+ */
+async function loadExtension(content = JSON.stringify(ENABLED_CONFIG)): Promise<{ emit: (event: "turn_start" | "turn_end") => void }> {
+	writeConfigFile(content);
+	const { default: networkProxyExtension } = await import("../index.ts");
+	const { pi, emit } = createFakePi();
+	networkProxyExtension(pi);
+	return { emit };
+}
+
 beforeEach(() => {
 	agentDir = mkdtempSync(join(tmpdir(), "network-proxy-index-"));
 	vi.stubEnv("PI_CODING_AGENT_DIR", agentDir);
-	// 保存 undici 全局槽，afterEach 恢复（工厂安装/摘除都改写这个槽）
-	savedDispatcher = getGlobalDispatcher();
+	savedFetch = globalThis.fetch;
+	fakeCalls = 0;
+	fakeFetch = async () => {
+		fakeCalls += 1;
+		return new Response("fake-original");
+	};
+	globalThis.fetch = fakeFetch;
 	loggerMock.error.mockClear();
 });
 
 afterEach(() => {
-	setGlobalDispatcher(savedDispatcher);
+	globalThis.fetch = savedFetch;
 	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);
+	it("enabled 且校验过：包装 globalThis.fetch（未命中规则时委托 fake 原 fetch）", async () => {
+		await loadExtension();
+		expect(globalThis.fetch).not.toBe(fakeFetch);
+		const response = await globalThis.fetch("https://open.bigmodel.cn/api");
+		expect(await response.text()).toBe("fake-original");
+		expect(fakeCalls).toBe(1);
 		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);
+	it("enabled=false：不包装（globalThis.fetch 保持原实现），零 error", async () => {
+		await loadExtension(JSON.stringify({ ...ENABLED_CONFIG, enabled: false }));
+		expect(globalThis.fetch).toBe(fakeFetch);
 		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);
+	it("非法配置（坏 JSON）：不抛、不包装（全部直连），error 含恢复动作（配置文件路径）", async () => {
+		// 不抛契约由 loadExtension 的 await 保证（工厂抛错即本用例红）
+		await loadExtension("{ not valid json");
+		expect(globalThis.fetch).toBe(fakeFetch);
 		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);
+	it("非法字段（端口越界）：loadConfig 回落 defaults（enabled=false → 不包装）+ error 可归因", async () => {
+		await loadExtension(JSON.stringify({ ...ENABLED_CONFIG, proxy: { ...ENABLED_CONFIG.proxy, port: 99999 } }));
+		expect(globalThis.fetch).toBe(fakeFetch);
 		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();
-
-		// 未变配置：同分发器（不重建）
+	it("turn_start 重读配置：指纹变化换新包装，未变零动作", async () => {
+		const { emit } = await loadExtension();
+		const first = globalThis.fetch;
+
+		// 未变配置：同包装函数（不重建）
 		emit("turn_start");
-		expect(getGlobalDispatcher()).toBe(first);
+		expect(globalThis.fetch).toBe(first);
 
-		// 改写配置（size 变化 → mtime+size 缓存失效）：指纹变化重建
+		// 改写配置（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);
+		expect(globalThis.fetch).not.toBe(first);
+	});
+
+	it("pi 重装 globalThis.fetch（configureHttpDispatcher）后 turn_start 重新包装覆盖者", async () => {
+		const { emit } = await loadExtension();
+
+		let piReinstalledCalls = 0;
+		const piReinstalled: FetchLike = async () => {
+			piReinstalledCalls += 1;
+			return new Response("pi-native");
+		};
+		globalThis.fetch = piReinstalled;
+		emit("turn_start");
+
+		expect(globalThis.fetch).not.toBe(piReinstalled);
+		const response = await globalThis.fetch("https://open.bigmodel.cn/api");
+		expect(await response.text()).toBe("pi-native");
+		expect(piReinstalledCalls).toBe(1);
 	});
 
 	it("turn_end flush 计数增量到 stats JSONL（recordDispatch → turn_end → 落盘行）", async () => {
-		writeConfigFile(JSON.stringify(ENABLED_CONFIG));
-		const { default: networkProxyExtension } = await import("../index.ts");
+		const { emit } = await loadExtension();
 		// resetModules 后 index.ts 与此处 import 的 stats.ts 是同一模块图刷新的同一实例
-		const { recordDispatch } = await import("../stats.ts");
-		const { statsFilePath } = await import("../stats.ts");
-		const { pi, emit } = createFakePi();
-		networkProxyExtension(pi);
+		const { recordDispatch, statsFilePath } = await import("../stats.ts");
 
 		recordDispatch("api.anthropic.com", true);
 		recordDispatch("open.bigmodel.cn", false);
@@ -143,15 +166,12 @@ describe("turn 粒度热生效", () => {
 		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);
+	it("enabled true→false：turn_start 后恢复原 fetch（禁用生效）", async () => {
+		const { emit } = await loadExtension();
+		expect(globalThis.fetch).not.toBe(fakeFetch);
 
 		writeConfigFile(JSON.stringify({ ...ENABLED_CONFIG, enabled: false }));
 		emit("turn_start");
-		expect(getGlobalDispatcher()).toBe(savedDispatcher);
+		expect(globalThis.fetch).toBe(fakeFetch);
 	});
 });

package/src/dispatcher.ts

@@ -1,40 +1,29 @@
 /**
- * 按主机名规则分流的 undici 全局分发器。
+ * 代理分发器构造（供 fetch-wrapper 在规则命中时按请求注入）。
  *
- * 形态依据（设计 .tmp/tech-design/llm-network-proxy.md §3.1 行为序列 3 + §3.3 决策 1/7/8）：
- * - 拦截点 = 公开 `dispatch(opts, handler)`：参照 pi 自装 EnvHttpProxyAgent（pi 内部继承
- *   undici 非公开 DispatcherBase override [kDispatch] symbol 方法）；undici 7.28 未公开
- *   导出 DispatcherBase（运行时 require 返回 undefined、类型层无声明，✅ 本会话读码核实
- *   undici types/index.d.ts 导出清单与 lib/dispatcher/dispatcher-base.js），照抄内部形态
- *   需 any/深路径 import，故继承公开导出的 `Dispatcher` override 公开 dispatch（close/
- *   destroy 不 override，见类尾注释）。
- * - 两协议构造契约（✅ undici 7.28.0 源码读码核实，单测冒烟防回归）：
- *   http/https 走 ProxyAgent，调优经 `proxyTls: { autoSelectFamilyAttemptTimeout: 2000 }`
+ * 拦截点已从 undici 全局分发器改为 `globalThis.fetch` 包装（见 fetch-wrapper.ts 头注：
+ * 打包版 pi 内置 undici 与扩展 bundle 内联的 undici 是两套副本，全局槽互不相通）。本模块
+ * 只负责按协议构造代理分发器，规则判定 / 计数 / 直连委托都在 fetch-wrapper 完成。
+ *
+ * 两协议构造契约（undici 7.28.0 源码读码核实，单测冒烟防回归）：
+ * - http/https 走 ProxyAgent，调优经 `proxyTls: { autoSelectFamilyAttemptTimeout: 2000 }`
  *   （构造内部 buildConnector({...opts.proxyTls}) 透传到「到代理」连接）；禁传 connect 选项
  *   ——ProxyAgent 不消费该字段，传入被静默忽略、调优失效且不报错。
- *   socks5 走 Socks5ProxyAgent（实验性 API），调优经 `connect: buildConnector({...})` 的
+ * - socks5 走 Socks5ProxyAgent（实验性 API），调优经 `connect: buildConnector({...})` 的
  *   connector 函数形态——该构造选项只收函数，对象形态首个请求建隧道时 TypeError；
  *   `proxyTls` 是「代理连接走 TLS」开关（truthy 即按 TLS 连代理），不可当调优参数袋。
  * - 高延迟路由语义：到代理服务器的连接不回落 autoSelectFamilyAttemptTimeout 默认 250ms，
  *   对齐 pi 原生调优同值 2000（pi dist/core/http-dispatcher.js:5
  *   DEFAULT_AUTO_SELECT_FAMILY_ATTEMPT_TIMEOUT_MS = 2_000；其 :4 注释即 250ms 默认会
  *   终止高延迟路由有效连接尝试的动机）。
- * - 计数时点 = 请求发起时（不等待完成——统计观测「按规则尝试的出站方式」，成败由 pi 原生
- *   错误链路呈现）。
  */
 
 import { EventEmitter } from "node:events";
 
-import {
-	buildConnector,
-	Dispatcher,
-	ProxyAgent,
-	Socks5ProxyAgent,
-} from "undici";
+import { buildConnector, ProxyAgent, Socks5ProxyAgent } from "undici";
 import type { Dispatcher as IDispatcher } from "undici";
 
-import { hitsNoProxy, hitsRules, type NetworkProxyConfig, type NetworkProxyServer } from "./config.js";
-import { normalizeHostname } from "./match.js";
+import type { NetworkProxyConfig, NetworkProxyServer } from "./config.js";
 
 /** 到代理服务器连接的 autoSelectFamilyAttemptTimeout（对齐 pi 原生调优同值）。 */
 export const PROXY_CONNECT_ATTEMPT_TIMEOUT_MS = 2000;
@@ -50,26 +39,6 @@ const PROXY_TLS_TUNING: buildConnector.BuildOptions = {
 	autoSelectFamilyAttemptTimeout: PROXY_CONNECT_ATTEMPT_TIMEOUT_MS,
 };
 
-/** 代理出站计数回调：host = 归一化目标主机名；proxied = true 经代理 / false 直连。 */
-export type DispatchCounter = (host: string, proxied: boolean) => void;
-
-/**
- * 跨模块环境身份标记：jiti 全量 reload 产生的新模块环境与旧环境的类对象互异（instanceof
- * 失效；根因 = reload 后 extensions/loader.js:472-476 新建 jiti 实例（moduleCache: false）
- * 重新 import 本扩展，两环境各持一份类构造函数——pi reload 链总锚点见 installer.ts
- * detachResidualDispatcher 注释），而 Symbol.for 全局注册表是进程级注册表、跨模块环境
- * 共享——以它识别全局槽上本扩展旧环境残留的
- * 分流器实例（残留不摘除则禁用失效 / 重装嵌套双计，见 installer.ts detachResidualDispatcher）。
- */
-const RULE_DISPATCH_MARK = Symbol.for("@zhushanwen/pi-network-proxy:rule-dispatch");
-
-/** 类型守卫：目标分发器是否本扩展的 RuleDispatchDispatcher（跨模块环境可辨，见 RULE_DISPATCH_MARK）。 */
-export function isRuleDispatchDispatcher(
-	dispatcher: IDispatcher,
-): dispatcher is RuleDispatchDispatcher {
-	return RULE_DISPATCH_MARK in dispatcher;
-}
-
 /**
  * 防崩溃 error listener（对齐 pi withUndiciErrorListener 形态）：undici 内部 Client 在
  * 中途终止 fetch body 时可能 emit "error"——EventEmitter 的 unhandled "error" 特例会炸掉
@@ -108,62 +77,3 @@ export function buildProxyDispatcher(config: NetworkProxyConfig): IDispatcher {
 		}),
 	);
 }
-
-/** 从 dispatch opts.origin 取归一化主机名；origin 缺失/非法（无已发生证据的异常路径）返回空串。 */
-function hostnameOf(origin: string | URL | undefined): string {
-	if (origin === undefined) return "";
-	try {
-		const url = origin instanceof URL ? origin : new URL(origin);
-		return normalizeHostname(url.hostname);
-	} catch {
-		return "";
-	}
-}
-
-export interface RuleDispatchDeps { // oe-exempt:20261019:framework:分流器依赖注入接缝（单测以 fake 分发器驱动，不 mock undici 全局槽）
-
-	/** 安装前捕获的原分发器：noProxy 命中与规则未命中流量委托——保留 pi 原生 EnvHttpProxyAgent 的 env 代理路由/连接调优/防崩溃语义（构造性等价：未命中 = 未安装本扩展时 pi 的确切行为）。 */
-	fallback: IDispatcher;
-	/** 规则命中流量的代理分发器（buildProxyDispatcher 产物）。 */
-	proxy: IDispatcher;
-	noProxy: string[];
-	rules: string[];
-	/** 分流计数回调（发起时点，本类不落盘）。 */
-	onCount: DispatchCounter;
-}
-
-/**
- * 规则分流分发器：dispatch 内 noProxy（排除，优先）→ rules（命中走代理）→ 委托 fallback。
- * 分流覆盖一切经全局分发器的请求（含 WebSocket 升级请求——Node 全局 WebSocket 建连默认取
- * 全局分发器，设计 §3.1 行为序列 3）。
- */
-export class RuleDispatchDispatcher extends Dispatcher {
-	readonly [RULE_DISPATCH_MARK] = true;
-	readonly fallback: IDispatcher;
-	readonly proxy: IDispatcher;
-	readonly noProxy: string[];
-	readonly rules: string[];
-	readonly onCount: DispatchCounter;
-
-	constructor(deps: RuleDispatchDeps) {
-		super();
-		this.fallback = deps.fallback;
-		this.proxy = deps.proxy;
-		this.noProxy = deps.noProxy;
-		this.rules = deps.rules;
-		this.onCount = deps.onCount;
-	}
-
-	dispatch(opts: IDispatcher.DispatchOptions, handler: IDispatcher.DispatchHandler): boolean {
-		const host = hostnameOf(opts.origin);
-		const useProxy = !hitsNoProxy(host, this.noProxy) && hitsRules(host, this.rules);
-		this.onCount(host, useProxy);
-		return useProxy ? this.proxy.dispatch(opts, handler) : this.fallback.dispatch(opts, handler);
-	}
-
-	// 不 override close/destroy：①全链路无全局分发器 close/destroy 调用方（✅ 本会话读码
-	// 核实——undici fetch 链路、pi http-dispatcher.js（只构造与 setGlobalDispatcher）、本包
-	// 代码均不调用）；②undici 父类 close/destroy 是 void 与 Promise<void> 返回互斥的重载集，
-	// 单一实现签名无法通过 TS override 兼容检查（实测 TS2322）；父类默认抛 not implemented
-	// = 若未来出现调用方则 fail-fast 暴露，不为无已发生证据的调用方保留透传实现。
-}

package/src/fetch-wrapper.ts

@@ -0,0 +1,245 @@
+/**
+ * 网络代理请求拦截层：包装 pi 进程的 `globalThis.fetch`（打包版兼容设计）。
+ *
+ * 为什么不是 undici 全局分发器：打包版 pi 是 Bun 单文件二进制，HTTP 栈用二进制内置的
+ * undici（`builtin://thirdparty/undici`）；扩展 bundle 由 esbuild 内联自己的 undici 副本
+ * （`scripts/bundle-extensions.mjs` 的 EXTERNAL 不含 undici）。undici 的
+ * `setGlobalDispatcher` 槽是模块级变量，两套副本互不相通——扩展改的全局槽 pi 根本不用，
+ * LLM 请求照常直连（2026-10-20 打包版实测：请求直连 Cloudflare，统计文件零行）。
+ * dev 用 `node_modules/.bin/pi`，pi 与扩展源码解析到同一份 undici，所以旧方案在 dev 正常、
+ * 打包版静默失效。
+ *
+ * 稳定接缝 = `globalThis.fetch`：pi-ai 的 OpenAI 兼容请求在每次构造 client 时经
+ * `Shims.getDefaultFetch()` 动态取当前全局 fetch（node_modules/openai/internal/shims.js），
+ * 包装它不依赖 pi 与扩展是否共享 undici 副本。命中规则的请求用扩展自己的 undici fetch +
+ * 代理分发器发出；未命中的请求原样调用包装前的 fetch，保留 pi 原生 EnvHttpProxyAgent /
+ * 连接调优 / 错误处理语义。
+ *
+ * 生命周期与旧安装状态机同构：
+ * - 加载 / 每 turn 开始：重读配置推进状态（禁用 = 摘除包装恢复原 fetch）；
+ * - 指纹未变且包装仍在进程槽位：零动作（不重建）；
+  * - 槽位被第三方整体覆盖（其他 extension 包装 / 手动改写；pi 的 configureHttpDispatcher
+  *   有 shouldInstallGlobals 守卫（pi dist/core/http-dispatcher.js:88-99）——检测到 fetch
+  *   已被第三方覆盖即保留不重装，本扩展的包装在同进程内持续生效）→ 以覆盖者为新 original
+  *   重新包装（防御路径）；
+ * - 构造失败：onError + 恢复原 fetch（全部直连），同指纹锁定不重试（首败即停）。
+ *
+ * reload 残留：jiti 全量 reload 后旧模块环境的包装可能仍挂在 globalThis.fetch 上；包装函数
+ * 带 `Symbol.for` 标记（跨模块环境共享），新环境推进前先摘除，防嵌套双计。
+ */
+
+import type { Dispatcher } from "undici";
+
+import {
+	hitsNoProxy,
+	hitsRules,
+	networkProxyFingerprint,
+	type NetworkProxyConfig,
+} from "./config.js";
+import { normalizeHostname } from "./match.js";
+import { recordDispatch } from "./stats.js";
+
+/** pi 进程的全局 fetch 形态（Node 类型由 @types/node 的 web-globals 提供）。 */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+type FetchInput = Parameters<FetchLike>[0];
+type FetchInit = Parameters<FetchLike>[1];
+
+/**
+ * 经代理发出时的 init：保留调用方全部选项，附上本次请求的代理分发器。
+ * Omit 掉 Node 全局 RequestInit 自带的 dispatcher（undici-types 类型身份），避免与 npm
+ * undici 的 Dispatcher 形成 `Dispatcher & Dispatcher` 冲突；运行时由本字段整体覆盖。
+ * 签名自包含（不引用文件内私有别名 FetchInit）——导出签名的被引用类型必须可命名。
+ */
+export type ProxyFetchInit = Omit<NonNullable<Parameters<FetchLike>[1]>, "dispatcher"> & { dispatcher: Dispatcher };
+
+/** 代理 fetch 注入接缝：生产环境 = undici.fetch；单测用 fake 避免真实网络。 */
+export type ProxyFetch = (input: Parameters<FetchLike>[0], init: ProxyFetchInit) => Promise<Response>;
+
+/**
+ * 跨模块环境身份标记（Symbol.for 进程级注册表，jiti reload 后新旧环境共享）：
+ * 记录包装前捕获的 original fetch，供新环境摘除旧包装。
+ */
+const FETCH_WRAPPER_MARK = Symbol.for("@zhushanwen/pi-network-proxy:fetch-wrapper");
+
+interface FetchWrapperMark { // oe-exempt:20261020:framework:包装函数标记形状（跨模块环境身份契约，单实现为常态）
+
+	originalFetch: FetchLike;
+}
+
+/** 当前包装状态；null = 未包装（globalThis.fetch 是 pi 原生实现）。 */
+export interface FetchWrapperState { // oe-exempt:20261020:framework:包装状态机载体形状（状态机唯一状态类型，单实现为常态）
+
+	/** 包装前捕获的原 fetch（首次捕获后跨重建保留——恢复与直连委托都用它）。 */
+	originalFetch: FetchLike;
+	/** 已应用（或已锁定失败）配置的指纹。 */
+	fingerprint: string;
+	/** 当前包装函数；null = 构造失败锁定态（未包装）。 */
+	wrapper: FetchLike | null;
+}
+
+export interface FetchWrapperDeps { // oe-exempt:20261020:framework:状态机依赖注入接缝（单测注入 fake fetch / buildProxy / proxyFetch）
+
+	getFetch: () => FetchLike;
+	setFetch: (fetch: FetchLike) => void;
+	/** 代理分发器构造（可注入抛错——「构造失败 → 不包装 → 全直连」单测入口）。 */
+	buildProxy: (config: NetworkProxyConfig) => Dispatcher;
+	proxyFetch: ProxyFetch;
+	/** extension error 呈现（logger.error；文案含恢复动作）。 */
+	onError: (message: string) => void;
+}
+
+/** 从 URL 字符串取归一化主机名；非法 URL 返回空串（不计数、原样放行）。 */
+function hostnameOfUrl(raw: string): string {
+	try {
+		return normalizeHostname(new URL(raw).hostname);
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * 从 fetch 入参取主机名：string / URL / Request（含 url 属性的对象）。
+ * 空串 = 无法判定目标（相对 URL / 非法入参），调用方原样放行且不计数。
+ */
+function hostnameOfInput(input: FetchInput): string {
+	if (typeof input === "string") return hostnameOfUrl(input);
+	if (input instanceof URL) return normalizeHostname(input.hostname);
+	if (typeof input === "object" && input !== null && "url" in input) {
+		const url: unknown = input.url;
+		if (typeof url === "string") return hostnameOfUrl(url);
+	}
+	return "";
+}
+
+/** 给包装函数打标记（不可枚举，避免暴露给业务代码的序列化/枚举）。 */
+function markWrapper(wrapper: FetchLike, originalFetch: FetchLike): void {
+	Object.defineProperty(wrapper, FETCH_WRAPPER_MARK, {
+		value: { originalFetch } satisfies FetchWrapperMark,
+		enumerable: false,
+		configurable: false,
+		writable: false,
+	});
+}
+
+/** 函数形态守卫（标记值的 originalFetch 校验，避免断言到 FetchLike）。 */
+function isFetchLike(value: unknown): value is FetchLike {
+	return typeof value === "function";
+}
+
+/** 读取包装标记；非本扩展包装返回 null。 */
+function wrapperMarkOf(fetch: FetchLike): FetchWrapperMark | null {
+	const descriptor = Object.getOwnPropertyDescriptor(fetch, FETCH_WRAPPER_MARK);
+	if (descriptor === undefined || !("value" in descriptor)) return null;
+	const value: unknown = descriptor.value;
+	if (value === null || typeof value !== "object") return null;
+	const original: unknown = Reflect.get(value, "originalFetch");
+	return isFetchLike(original) ? { originalFetch: original } : null;
+}
+
+/**
+ * 构造包装函数：每次调用现算 host → 计数 → 命中规则走代理 fetch，未命中委托原 fetch。
+ * 计数时点 = 请求发起时（与旧分流器一致；不等待完成，成败由 pi 原生错误链路呈现）。
+ */
+function createWrappedFetch(
+	originalFetch: FetchLike,
+	config: NetworkProxyConfig,
+	proxy: Dispatcher,
+	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 });
+	};
+	markWrapper(wrapped, originalFetch);
+	return wrapped;
+}
+
+/** 禁用态收口：仅当槽位仍归本扩展时恢复原 fetch（槽位被外部覆盖时不改写别人的实现）。 */
+function restoreOriginalIfOwned(
+	state: FetchWrapperState | null,
+	deps: Pick<FetchWrapperDeps, "getFetch" | "setFetch">,
+): void {
+	if (state?.wrapper !== null && state?.wrapper !== undefined && deps.getFetch() === state.wrapper) {
+		deps.setFetch(state.originalFetch);
+	}
+}
+
+/**
+ * jiti reload 残留摘除：新模块环境 installed=null 但旧环境的包装仍挂在 globalThis.fetch 上。
+ * 不摘除则 enabled=false 时判「未包装」零动作（旧包装继续生效），或 enabled=true 时把旧包装
+ * 当作 original 再包一层（同一请求两次计数、两级代理判定）。
+ */
+export function detachResidualFetchWrapper(
+	state: FetchWrapperState | null,
+	deps: Pick<FetchWrapperDeps, "getFetch" | "setFetch">,
+): void {
+	if (state !== null) return;
+	const current = deps.getFetch();
+	const mark = wrapperMarkOf(current);
+	if (mark !== null) deps.setFetch(mark.originalFetch);
+}
+
+/** 构造失败收口：error 上报 + 恢复原 fetch（全部直连），返回记指纹的锁定态。 */
+function lockOnBuildFailure(
+	config: NetworkProxyConfig,
+	state: FetchWrapperState | null,
+	originalFetch: FetchLike,
+	fingerprint: string,
+	deps: FetchWrapperDeps,
+	error: unknown,
+): FetchWrapperState {
+	deps.onError(
+		`网络代理转发器构造失败（协议 ${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);
+	}
+	return { originalFetch, fingerprint, wrapper: null };
+}
+
+/**
+ * 按新配置推进包装状态机（转移表见模块头）。config 契约 = loadNetworkProxyConfig 产物
+ * （normalize 已校验合法——非法配置在读取层回落 defaults+error，构造性到达本函数恒合法）。
+ */
+export function applyNetworkProxyConfig(
+	config: NetworkProxyConfig,
+	state: FetchWrapperState | null,
+	deps: FetchWrapperDeps,
+): FetchWrapperState | null {
+	if (!config.enabled) {
+		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 originalFetch = owned && state ? state.originalFetch : currentFetch;
+
+	let proxy: Dispatcher;
+	try {
+		proxy = deps.buildProxy(config);
+	} catch (error) {
+		return lockOnBuildFailure(config, state, originalFetch, fingerprint, deps, error);
+	}
+
+	const wrapper = createWrappedFetch(originalFetch, config, proxy, deps.proxyFetch);
+	deps.setFetch(wrapper);
+	return { originalFetch, fingerprint, wrapper };
+}