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

package/src/__tests__/stats.test.ts

@@ -0,0 +1,171 @@
+/**
+ * stats 增量行格式 + 单行 write 原子性（任务书验收②）。
+ * 单行原子性 = 每次 appendFileSync 调用的 payload 恰好是一行完整 JSON + \n（O_APPEND 单次
+ * write 是多 pi 进程并发追加不交错的实现前提，防改为分片 write 时静默交错）。
+ * fs-guard 白名单：写入目标 = PI_CODING_AGENT_DIR 注入的 mkdtemp tmp 目录。
+ */
+import * as fs from "node:fs";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { appendCalls } = vi.hoisted(() => ({
+	appendCalls: [] as Array<{ path: string; data: string }>,
+}));
+
+// node:fs 的 ESM namespace 不可配置，vi.spyOn 对具名导出失效（vitest 限制，llm-shared 同款）——
+// 用 vi.mock 包装 appendFileSync（默认透传原始实现并记录调用），其余 fs 操作原样透传。
+// 注意：本文件级 mock 覆盖 fs-guard 全局 mock（fs-guard 头注已登记的既有形态）——本文件
+// 写入目标全部为 mkdtemp tmp，自守白名单纪律。
+vi.mock("node:fs", async (importOriginal) => {
+	const actual = await importOriginal() as typeof import("node:fs");
+	return {
+		...actual,
+		appendFileSync: vi.fn((path: string, data: string) => {
+			appendCalls.push({ path, data });
+			return actual.appendFileSync(path, data);
+		}),
+	};
+});
+
+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 {
+	flushStats,
+	recordDispatch,
+	resetCounters,
+	snapshotCounters,
+	statsFilePath,
+} from "../stats.ts";
+
+let agentDir: string;
+
+beforeEach(() => {
+	agentDir = mkdtempSync(join(tmpdir(), "network-proxy-stats-"));
+	vi.stubEnv("PI_CODING_AGENT_DIR", agentDir);
+	resetCounters();
+	appendCalls.length = 0;
+	loggerMock.warn.mockClear();
+});
+
+afterEach(() => {
+	vi.unstubAllEnvs();
+});
+
+describe("stats 增量行格式", () => {
+	it("flush 后每行完整 JSON：字段 {ts, host, proxied, direct}，ts 为 flush 时刻 epoch ms（runtime 读侧 number 契约）", () => {
+		const before = Date.now();
+		recordDispatch("api.anthropic.com", true);
+		recordDispatch("open.bigmodel.cn", false);
+		flushStats();
+
+		const lines = readFileSync(statsFilePath(), "utf-8").split("\n").filter((l) => l !== "");
+		expect(lines).toHaveLength(2);
+		const rows = lines.map((l) => JSON.parse(l) as Record<string, unknown>);
+		expect(rows).toContainEqual({
+			ts: expect.any(Number),
+			host: "api.anthropic.com",
+			proxied: 1,
+			direct: 0,
+		});
+		expect(rows).toContainEqual({
+			ts: expect.any(Number),
+			host: "open.bigmodel.cn",
+			proxied: 0,
+			direct: 1,
+		});
+		for (const row of rows) {
+			// epoch ms 合理区间（≥ before 且 ≤ now + 1s 时钟偏移容差）——与 runtime
+			// parseStatsLine typeof ts === 'number' 契约互证
+			expect(row.ts as number).toBeGreaterThanOrEqual(before);
+			expect(row.ts as number).toBeLessThanOrEqual(Date.now() + 1000);
+		}
+	});
+
+	it("flush 清空已写增量，下次 flush 只写新增量（追加式增量行语义）", () => {
+		recordDispatch("a.test", true);
+		flushStats();
+		expect(readFileSync(statsFilePath(), "utf-8").trim().split("\n")).toHaveLength(1);
+
+		recordDispatch("b.test", false);
+		flushStats();
+		const lines = readFileSync(statsFilePath(), "utf-8").trim().split("\n");
+		expect(lines).toHaveLength(2);
+		expect(JSON.parse(lines[1]).host).toBe("b.test");
+	});
+
+	it("同主机名聚合：多次同向计数累加为一行", () => {
+		recordDispatch("api.anthropic.com", true);
+		recordDispatch("api.anthropic.com", true);
+		recordDispatch("api.anthropic.com", false);
+		flushStats();
+		const rows = readFileSync(statsFilePath(), "utf-8")
+			.trim()
+			.split("\n")
+			.map((l) => JSON.parse(l));
+		expect(rows).toEqual([
+			{ ts: expect.any(Number), host: "api.anthropic.com", proxied: 2, direct: 1 },
+		]);
+	});
+
+	it("空增量 flush 零 IO（不建目录不写文件）", () => {
+		flushStats();
+		expect(appendCalls).toHaveLength(0);
+	});
+
+	it("snapshotCounters / resetCounters（内存视图）", () => {
+		recordDispatch("a.test", true);
+		expect(snapshotCounters().get("a.test")).toEqual({ proxied: 1, direct: 0 });
+		resetCounters();
+		expect(snapshotCounters().size).toBe(0);
+	});
+});
+
+describe("单行 write 原子性", () => {
+	it("每行恰好一次 appendFileSync 调用，payload 为单行完整 JSON + \\n（禁止分片 write）", () => {
+		recordDispatch("api.anthropic.com", true);
+		recordDispatch("open.bigmodel.cn", false);
+		flushStats();
+
+		expect(appendCalls).toHaveLength(2);
+		for (const call of appendCalls) {
+			expect(call.path).toBe(statsFilePath());
+			expect(call.data.endsWith("\n")).toBe(true);
+			expect(call.data.split("\n")).toHaveLength(2); // 单行内容 + 尾换行
+			const row = JSON.parse(call.data);
+			expect(Object.keys(row).sort()).toEqual(["direct", "host", "proxied", "ts"]);
+		}
+	});
+});
+
+describe("写失败不阻断（log + 增量保留重试）", () => {
+	it("appendFileSync 抛错 → warn 留痕 + 增量保留；恢复后重试成功且不丢行", () => {
+		recordDispatch("a.test", true);
+		recordDispatch("b.test", false);
+
+		vi.mocked(fs.appendFileSync).mockImplementationOnce(() => {
+			throw Object.assign(new Error("ENOSPC"), { code: "ENOSPC" });
+		});
+		expect(() => flushStats()).not.toThrow();
+		expect(loggerMock.warn).toHaveBeenCalledTimes(1);
+		// 失败行的增量保留在内存
+		expect(snapshotCounters().size).toBe(2);
+
+		// 恢复：重试把保留的增量完整落盘
+		flushStats();
+		const hosts = readFileSync(statsFilePath(), "utf-8")
+			.trim()
+			.split("\n")
+			.map((l) => JSON.parse(l).host);
+		expect(hosts).toEqual(["a.test", "b.test"]);
+		expect(snapshotCounters().size).toBe(0);
+	});
+});

package/src/config.ts

@@ -0,0 +1,176 @@
+/**
+ * network-proxy 配置读取与指纹。
+ *
+ * 类型与校验语义 SSOT = packages/shared/src/network-proxy.ts（u-foundation 契约）——
+ * extension bundle 自包含不 import shared 运行时代码（extensions 对 shared 的既有惯例：
+ * 结构类型本地声明 + 行为镜像锁定测试），本文件是复制体；漂移时以 shared 为准，
+ * __tests__/config.test.ts 锁两侧行为一致。
+ *
+ * 配置文件 = <agentDir>/config/network-proxy-ext-config.json（llm-shared getConfigPath
+ * 推导；runtime 写侧与 settings 页经 RPC 打通，设计 .tmp/tech-design/llm-network-proxy.md
+ * §3.1 配置 schema）。热重载 = loadConfig 读时刷新（mtime+size），调用方每次直接调
+ * loadNetworkProxyConfig，禁止上层闭包缓存（llm-shared 头注热重载契约）。
+ */
+
+import { loadConfig } from "@zhushanwen/pi-llm-shared";
+
+import { matchesHostPattern } from "./match.js";
+
+/** 代理协议词表：http / https 走 undici ProxyAgent，socks5 走 Socks5ProxyAgent。 */
+export type NetworkProxyProtocol = "http" | "https" | "socks5";
+
+/** 代理服务器连接参数。username/password 成对（非空时 percent-encode 拼入代理 URL）。 */
+export interface NetworkProxyServer { // oe-exempt:20261019:framework:ext-config 契约的 bundle 自包含复制体声明（SSOT=shared，镜像锁定测试锚定）
+
+	protocol: NetworkProxyProtocol;
+	host: string;
+	port: number;
+	username: string;
+	password: string;
+}
+
+/** 网络代理配置（ext-config 文件单一权威 schema；noProxy 优先级高于 rules）。 */
+export interface NetworkProxyConfig { // oe-exempt:20261019:framework:ext-config 契约的 bundle 自包含复制体声明（SSOT=shared，镜像锁定测试锚定）
+
+	enabled: boolean;
+	proxy: NetworkProxyServer;
+	/** 直连排除清单（主机名条目），命中即不经代理 */
+	noProxy: string[];
+	/** 代理规则（主机名条目），命中即经代理 */
+	rules: string[];
+}
+
+/** 默认配置：禁用态 + 常见本地代理地址占位 + 保护本地回环（与 shared DEFAULT 深相等，镜像锁定测试锁两侧）。 */
+export const DEFAULT_NETWORK_PROXY_CONFIG: NetworkProxyConfig = {
+	enabled: false,
+	proxy: { protocol: "http", host: "127.0.0.1", port: 7890, username: "", password: "" },
+	noProxy: ["localhost", "127.0.0.1"],
+	rules: [],
+};
+
+/** llm-shared loadConfig 的包名（决定文件名 network-proxy-ext-config.json）。 */
+const CONFIG_PKG = "network-proxy";
+
+const PROTOCOLS: readonly string[] = ["http", "https", "socks5"];
+
+/** 端口合法区间（语义镜像 shared validateNetworkProxyConfig 字面量）。 */
+const PORT_MIN = 1;
+const PORT_MAX = 65535;
+
+/** 校验结果信封：ok 或面向用户的错误清单（每条含修复动作，逐项收集不短路）。 */
+export type NetworkProxyValidationResult = { ok: true } | { ok: false; errors: string[] };
+
+/** noProxy/rules 条目校验：数组 + 每条为非空且不含空白字符的主机名字符串；重复条目不报错（匹配天然幂等）。 */
+function collectHostEntryErrors(entries: unknown, label: string): string[] {
+	if (!Array.isArray(entries)) {
+		return [`${label} 必须是主机名列表（当前不是列表），请恢复为每行一个主机名的形式`];
+	}
+	const errors: string[] = [];
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		if (typeof entry !== "string" || entry.trim() === "") {
+			errors.push(`${label} 第 ${i + 1} 条为空，请填写主机名或删除该条`);
+		} else if (/\s/.test(entry)) {
+			// 归一化不 trim，含空白字符的条目（首尾或内部）对真实主机名恒不匹配（静默不生效）——校验层显式拒绝并给出修复动作
+			errors.push(`${label} 第 ${i + 1} 条含空白字符，请删除空白后保存`);
+		}
+	}
+	return errors;
+}
+
+/** proxy 对象字段校验（validateNetworkProxyConfig 的子步骤，语义镜像 shared collectProxyServerErrors）。 */
+function collectProxyServerErrors(proxy: unknown): string[] {
+	if (proxy === null || typeof proxy !== "object" || Array.isArray(proxy)) {
+		return ["代理服务器配置必须是对象（协议 + 地址 + 端口），请重新填写代理服务器信息"];
+	}
+	const errors: string[] = [];
+	const { protocol, host, port, username, password } = proxy as Record<string, unknown>;
+	if (typeof protocol !== "string" || !PROTOCOLS.includes(protocol)) {
+		errors.push(`代理协议必须是 http / https / socks5 之一: ${String(protocol)}，请重新选择协议`);
+	}
+	if (typeof host !== "string" || host.trim() === "") {
+		errors.push("代理服务器地址不能为空，请填写代理地址（如 127.0.0.1）");
+	}
+	if (typeof port !== "number" || !Number.isInteger(port) || port < PORT_MIN || port > PORT_MAX) {
+		errors.push(`代理端口必须是 ${PORT_MIN}-${PORT_MAX} 的整数: ${String(port)}，请填写正确的端口`);
+	}
+	if (typeof username !== "string" || typeof password !== "string") {
+		errors.push("认证用户名与密码必须是文本，请检查认证输入框内容");
+	} else if ((username !== "") !== (password !== "")) {
+		errors.push("认证用户名与密码必须同时填写或同时留空（代理认证要求两者成对），请补全另一项或清空两项");
+	}
+	return errors;
+}
+
+/**
+ * 网络代理配置校验（语义复制自 shared validateNetworkProxyConfig）：
+ * 协议白名单、端口 1-65535 整数、凭据成对、noProxy/rules 条目非空主机名且不含空白字符
+ * （归一化不 trim，带空白恒不匹配故显式拒绝）。
+ * 错误逐项收集（errors 复数，不短路），文案面向用户且含修复动作。
+ * 对象性守卫：null/数组解构会抛 TypeError 或静默得 undefined，读取路径须以错误信封逃逸。
+ */
+export function validateNetworkProxyConfig(config: unknown): NetworkProxyValidationResult {
+	if (config === null || typeof config !== "object" || Array.isArray(config)) {
+		return { ok: false, errors: [`网络代理配置必须是对象: ${String(config)}`] };
+	}
+	const errors: string[] = [];
+	const { enabled, proxy, noProxy, rules } = config as Record<string, unknown>;
+	if (typeof enabled !== "boolean") {
+		errors.push(
+			`网络代理开关必须是开或关: ${JSON.stringify(enabled) ?? String(enabled)}，请重新切换一次开关后保存`,
+		);
+	}
+	errors.push(...collectProxyServerErrors(proxy));
+	errors.push(...collectHostEntryErrors(noProxy, "直连排除清单（noProxy）"));
+	errors.push(...collectHostEntryErrors(rules, "代理规则（rules）"));
+	return errors.length > 0 ? { ok: false, errors } : { ok: true };
+}
+
+/**
+ * loadConfig 的 normalize：校验通过的 raw 即合法配置（校验 = 运行时 guard，断言有兜底）。
+ * 非法配置 throw（含逐项错误清单）→ loadConfig 回落 defaults 并把消息交给 onWarning——
+ * 非法配置不静默修正（设计验收场景 10：坏配置不装分流器且 error 可归因），回落 defaults
+ * 即「全部直连」的安全态。
+ */
+export function normalizeNetworkProxyConfig(raw: unknown): NetworkProxyConfig {
+	const result = validateNetworkProxyConfig(raw);
+	if (!result.ok) {
+		throw new Error(result.errors.join("；"));
+	}
+	return raw as NetworkProxyConfig;
+}
+
+/** 条目去重 + 归一化视图（分流匹配用：匹配函数自带归一化，这里只去重保序）。 */
+function dedupeEntries(entries: string[]): string[] {
+	return [...new Set(entries)];
+}
+
+/** 读取配置（llm-shared mtime+size 读时刷新热重载）。 */
+export function loadNetworkProxyConfig(onWarning?: (msg: string) => void): NetworkProxyConfig {
+	return loadConfig(CONFIG_PKG, DEFAULT_NETWORK_PROXY_CONFIG, normalizeNetworkProxyConfig, onWarning);
+}
+
+/** 保存配置入口暂无（写入侧 = taiji runtime RMW）；pi CLI 用户直接手编文件即可。 */
+
+/** noProxy 命中判定（去重视图 + suffix 匹配）。 */
+export function hitsNoProxy(host: string, noProxy: string[]): boolean {
+	return dedupeEntries(noProxy).some((pattern) => matchesHostPattern(host, pattern));
+}
+
+/** 规则命中判定（去重视图 + suffix 匹配）。 */
+export function hitsRules(host: string, rules: string[]): boolean {
+	return dedupeEntries(rules).some((pattern) => matchesHostPattern(host, pattern));
+}
+
+/**
+ * 配置指纹：enabled+proxy+noProxy+rules 序列化比对（行为序列 2——指纹变化才重建分发器）。
+ * normalize 后结构固定，JSON.stringify 字段序稳定（字面量构造序）。
+ */
+export function networkProxyFingerprint(config: NetworkProxyConfig): string {
+	return JSON.stringify({
+		enabled: config.enabled,
+		proxy: config.proxy,
+		noProxy: dedupeEntries(config.noProxy),
+		rules: dedupeEntries(config.rules),
+	});
+}

package/src/dispatcher.ts

@@ -0,0 +1,79 @@
+/**
+ * 代理分发器构造（供 fetch-wrapper 在规则命中时按请求注入）。
+ *
+ * 拦截点已从 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({...})` 的
+ *   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 默认会
+ *   终止高延迟路由有效连接尝试的动机）。
+ */
+
+import { EventEmitter } from "node:events";
+
+import { buildConnector, ProxyAgent, Socks5ProxyAgent } from "undici";
+import type { Dispatcher as IDispatcher } from "undici";
+
+import type { NetworkProxyConfig, NetworkProxyServer } from "./config.js";
+
+/** 到代理服务器连接的 autoSelectFamilyAttemptTimeout（对齐 pi 原生调优同值）。 */
+export const PROXY_CONNECT_ATTEMPT_TIMEOUT_MS = 2000;
+
+/**
+ * 调优选项（BuildOptions 类型走 TcpNetConnectOpts 分支，port 必填 → 0 占位）：
+ * 构造 connector 时的 options.port 是默认值，实际建连时被目标端口后置覆盖
+ * （undici connect.js 的 `...options` 前置展开 + connector 参数 port 后置，✅ 读码核实），
+ * 0 不会落到真实连接参数。
+ */
+const PROXY_TLS_TUNING: buildConnector.BuildOptions = {
+	port: 0,
+	autoSelectFamilyAttemptTimeout: PROXY_CONNECT_ATTEMPT_TIMEOUT_MS,
+};
+
+/**
+ * 防崩溃 error listener（对齐 pi withUndiciErrorListener 形态）：undici 内部 Client 在
+ * 中途终止 fetch body 时可能 emit "error"——EventEmitter 的 unhandled "error" 特例会炸掉
+ * pi 进程，listener 只吞事件不掩盖请求本身的错误（body 流照常经 reader.read() reject）。
+ */
+function withUndiciErrorListener<T extends IDispatcher>(dispatcher: T): T {
+	if (dispatcher instanceof EventEmitter) {
+		EventEmitter.prototype.on.call(dispatcher, "error", () => {});
+	}
+	return dispatcher;
+}
+
+/** 代理服务器 URL：凭据非空时 percent-encode 拼入（undici 构造内部 decodeURIComponent 还原）。 */
+export function buildProxyUrl(proxy: NetworkProxyServer): string {
+	const auth =
+		proxy.username !== ""
+			? `${encodeURIComponent(proxy.username)}:${encodeURIComponent(proxy.password)}@`
+			: "";
+	return `${proxy.protocol}://${auth}${proxy.host}:${proxy.port}`;
+}
+
+/** 按协议构造代理分发器（协议词表校验在配置层已完成；未知协议不可达）。 */
+export function buildProxyDispatcher(config: NetworkProxyConfig): IDispatcher {
+	const uri = buildProxyUrl(config.proxy);
+	if (config.proxy.protocol === "socks5") {
+		return withUndiciErrorListener(
+			new Socks5ProxyAgent(uri, {
+				connect: buildConnector(PROXY_TLS_TUNING),
+			}),
+		);
+	}
+	return withUndiciErrorListener(
+		new ProxyAgent({
+			uri,
+			proxyTls: PROXY_TLS_TUNING,
+		}),
+	);
+}

package/src/fetch-wrapper.ts

@@ -0,0 +1,244 @@
+/**
+ * 网络代理请求拦截层：包装 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` 冲突；运行时由本字段整体覆盖。
+ */
+export type ProxyFetchInit = Omit<NonNullable<FetchInit>, "dispatcher"> & { dispatcher: Dispatcher };
+
+/** 代理 fetch 注入接缝：生产环境 = undici.fetch；单测用 fake 避免真实网络。 */
+export type ProxyFetch = (input: FetchInput, 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 };
+}