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

package/src/__tests__/match.test.ts

@@ -0,0 +1,86 @@
+/**
+ * 匹配语义真值表（任务书验收②：suffix 点边界 / noProxy 条目语义 / 归一化）。
+ *
+ * 本包 match.ts 是 packages/shared/src/network-proxy.ts 匹配函数的复制体（bundle 自包含
+ * 不 import shared 运行时代码）——真值表即两侧行为一致性的镜像锁定，漂移时以 shared 为准。
+ */
+import { describe, expect, it } from "vitest";
+
+import { matchesHostPattern, normalizeHostname } from "../match.ts";
+
+describe("normalizeHostname（归一化）", () => {
+	it("转小写", () => {
+		expect(normalizeHostname("API.Anthropic.COM")).toBe("api.anthropic.com");
+	});
+
+	it("去末尾点（FQDN 根点与裸主机名同义）", () => {
+		expect(normalizeHostname("api.anthropic.com.")).toBe("api.anthropic.com");
+		expect(normalizeHostname("api.anthropic.com..")).toBe("api.anthropic.com");
+	});
+
+	it("组合形态：大写 + 末尾点", () => {
+		expect(normalizeHostname("API.Anthropic.COM.")).toBe("api.anthropic.com");
+	});
+
+	it("无点主机名原样（小写化）", () => {
+		expect(normalizeHostname("localhost")).toBe("localhost");
+		expect(normalizeHostname("LocalHost")).toBe("localhost");
+	});
+
+	it("不 trim 首尾空白（带空白条目由校验层显式拒绝，匹配层保持严格）", () => {
+		expect(normalizeHostname(" api.anthropic.com")).toBe(" api.anthropic.com");
+		expect(normalizeHostname("api.anthropic.com ")).toBe("api.anthropic.com ");
+	});
+});
+
+describe("matchesHostPattern 真值表（suffix 点边界）", () => {
+	const pattern = "api.anthropic.com";
+
+	it("等于命中", () => {
+		expect(matchesHostPattern("api.anthropic.com", pattern)).toBe(true);
+	});
+
+	it("子域命中（以 .pattern 结尾）", () => {
+		expect(matchesHostPattern("eu.api.anthropic.com", pattern)).toBe(true);
+		expect(matchesHostPattern("a.b.api.anthropic.com", pattern)).toBe(true);
+	});
+
+	it("前缀拼接不命中（点边界必须对齐）", () => {
+		expect(matchesHostPattern("xapi.anthropic.com", pattern)).toBe(false);
+		expect(matchesHostPattern("papi.anthropic.com", pattern)).toBe(false);
+	});
+
+	it("恶意后缀不命中（pattern 出现在中间也不命中）", () => {
+		expect(matchesHostPattern("api-anthropic.com.evil.com", pattern)).toBe(false);
+		expect(matchesHostPattern("api.anthropic.com.evil.com", pattern)).toBe(false); // evil.com 的子域，非 pattern 子域
+	});
+
+	it("完全不同的主机名不命中", () => {
+		expect(matchesHostPattern("openai.com", pattern)).toBe(false);
+		expect(matchesHostPattern("anthropic.com", pattern)).toBe(false); // pattern 本身不是其子域
+	});
+
+	it("归一化参与匹配：大小写与末尾点在 host/pattern 任一侧生效", () => {
+		expect(matchesHostPattern("API.Anthropic.COM.", "api.anthropic.com")).toBe(true);
+		expect(matchesHostPattern("api.anthropic.com", "API.ANTHROPIC.COM.")).toBe(true);
+		expect(matchesHostPattern("EU.API.Anthropic.Com", pattern)).toBe(true);
+	});
+
+	it("空主机名 / 空 pattern 不命中任何条目", () => {
+		expect(matchesHostPattern("", pattern)).toBe(false);
+		expect(matchesHostPattern("api.anthropic.com", "")).toBe(false);
+		expect(matchesHostPattern("", "")).toBe(false);
+	});
+
+	it("首尾空白不参与匹配（host/pattern 任一侧带空白恒不命中——空白条目由校验层显式拒绝，匹配层不静默 trim 容忍）", () => {
+		expect(matchesHostPattern("api.anthropic.com", " api.anthropic.com")).toBe(false);
+		expect(matchesHostPattern("api.anthropic.com", "api.anthropic.com ")).toBe(false);
+		expect(matchesHostPattern(" api.anthropic.com", pattern)).toBe(false);
+	});
+
+	it("noProxy 条目语义：localhost 同时覆盖 localhost 与 *.localhost", () => {
+		expect(matchesHostPattern("localhost", "localhost")).toBe(true);
+		expect(matchesHostPattern("foo.localhost", "localhost")).toBe(true);
+		expect(matchesHostPattern("127.0.0.1", "127.0.0.1")).toBe(true);
+	});
+});

package/src/__tests__/startup-config-declaration.test.ts

@@ -0,0 +1,38 @@
+/**
+ * startupConfig 声明守护测试：断言 package.json `taiji.startupConfig` 声明的 content
+ * 与代码 DEFAULT_NETWORK_PROXY_CONFIG 常量深相等，防止两侧任一改动未同步（漂移）。
+ * 机制：runtime 启动序列统一 ensure（extension-startup-config.ts），声明即首建内容。
+ * 范式：smart-context 同名测试。
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_NETWORK_PROXY_CONFIG } from "../config.ts";
+
+/** package.json `taiji.startupConfig` 声明条目的最小形状（守护断言用）。 */
+interface StartupConfigEntry { // oe-exempt:20261019:framework:声明守护测试的最小形状锚（测试常驻资产，非临时期限类目可承载）
+
+	path: string;
+	content: unknown;
+}
+
+const pkg = JSON.parse(
+	readFileSync(join(fileURLToPath(import.meta.url), "../../../package.json"), "utf-8"),
+) as { "taiji"?: { startupConfig?: StartupConfigEntry[] } };
+
+describe("startupConfig 声明守护", () => {
+	it("声明 content 与代码 DEFAULT_NETWORK_PROXY_CONFIG 深相等", () => {
+		const entry = pkg["taiji"]?.startupConfig?.find(
+			(e: StartupConfigEntry) => e.path === "config/network-proxy-ext-config.json",
+		);
+		expect(entry).toBeDefined();
+		expect(entry?.content).toEqual(DEFAULT_NETWORK_PROXY_CONFIG);
+	});
+
+	it("默认声明为禁用态（P2 降级契约：默认无行为变化）", () => {
+		expect(DEFAULT_NETWORK_PROXY_CONFIG.enabled).toBe(false);
+	});
+});

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,169 @@
+/**
+ * 按主机名规则分流的 undici 全局分发器。
+ *
+ * 形态依据（设计 .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 }`
+ *   （构造内部 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 默认会
+ *   终止高延迟路由有效连接尝试的动机）。
+ * - 计数时点 = 请求发起时（不等待完成——统计观测「按规则尝试的出站方式」，成败由 pi 原生
+ *   错误链路呈现）。
+ */
+
+import { EventEmitter } from "node:events";
+
+import {
+	buildConnector,
+	Dispatcher,
+	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";
+
+/** 到代理服务器连接的 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,
+};
+
+/** 代理出站计数回调：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" 特例会炸掉
+ * 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,
+		}),
+	);
+}
+
+/** 从 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 暴露，不为无已发生证据的调用方保留透传实现。
+}