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

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @zhushanwen/pi-network-proxy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+LLM 网络代理分流：包装 pi 进程的 `globalThis.fetch`，按主机名规则把命中请求交给代理 dispatcher（http/https/socks5），未命中的原样委托包装前的 fetch（直连或 pi 原生 env 代理路由），并按主机名计数（经代理 / 直连）。
+
+## 行为摘要
+
+- **拦截点**：`globalThis.fetch`。pi-ai 的 OpenAI 兼容请求在每次构造 client 时经 `Shims.getDefaultFetch()` 动态取当前全局 fetch，包装它不依赖 pi 与扩展共享 undici 模块实例
+- **安装/卸载**：extension 加载时读配置，`enabled` 且校验通过 → 包装并构造代理 dispatcher；`enabled` false → 恢复原 fetch；校验/构造失败 → extension error（含配置文件恢复指引），不包装不阻断 pi（全部直连）
+- **热生效**：turn 粒度——每 turn 开始重读配置（mtime+size 读时刷新），指纹变化才重建；pi 的 `configureHttpDispatcher` 带 shouldInstallGlobals 守卫（pi dist/core/http-dispatcher.js:88-99：检测到 `globalThis.fetch` 已被第三方覆盖即保留不重装），本扩展的包装在同进程内持续生效；槽位被其他第三方覆盖时下一 turn 自动以覆盖者为新 original 重新包装（防御路径）
+- **匹配语义**：主机名归一化（小写、去末尾点）后 suffix 匹配（等于或以 `.条目` 结尾，点边界对齐）；noProxy 优先于 rules
+- **覆盖面**：经 `globalThis.fetch` 发出的请求（pi LLM 调用与 OAuth/目录请求均走 fetch）；直接使用 `undici.request` / `Client` 的调用与 WebSocket 升级请求不经过本包装
+- **计数**：请求发起时 +1（内存按主机名聚合），turn 结束 / 进程退出把增量追加写入 `<agentDir>/network-proxy-stats.jsonl`（每行完整 JSON `{ts, host, proxied, direct}`，单次 write 单行——多进程并发追加不交错）；写失败 log 不阻断
+- **降级契约**：socks5 构造失败（undici 实验性 API）→ 记错误、恢复原 fetch、全部直连，切回 http 协议恢复；同指纹不重试构造，配置修正（指纹变化）后自然重试
+
+## 为什么包装 fetch 而不是 undici 全局 dispatcher
+
+undici 的 `setGlobalDispatcher` 槽是模块级变量，只有「pi 与扩展加载同一份 undici 模块实例」时才生效：
+
+- 独立 pi（`node_modules/.bin/pi`）与扩展源码都从 `node_modules/undici` 解析，实例相同，旧方案可用
+- 打包版 pi 是单文件二进制，HTTP 栈用内置 undici（`builtin://thirdparty/undici`）；扩展 bundle 由 esbuild 内联自己的 undici 副本。两套全局槽互不相通——扩展安装的分流器 pi 根本不会使用，LLM 请求静默直连、统计为空
+- `globalThis.fetch` 是两套实现之间稳定的接缝（pi-ai / OpenAI SDK 每次构造 client 时动态读取），因此拦截点定在这里
+
+## 配置
+
+`<agentDir>/config/network-proxy-ext-config.json`（schema、匹配语义、生效时机、故障恢复见 `skills/network-proxy-ext-config/SKILL.md`）：
+
+```json
+{
+  "enabled": false,
+  "proxy": { "protocol": "http", "host": "127.0.0.1", "port": 7890, "username": "", "password": "" },
+  "noProxy": ["localhost", "127.0.0.1"],
+  "rules": ["api.anthropic.com"]
+}
+```
+
+taiji 桌面端经设置页「网络代理」读写（runtime RMW 写侧）；独立 pi 用户手编文件即可，保存后自下一轮对话起生效。
+
+## 两协议构造契约（防回归锚）
+
+- http/https：`ProxyAgent` 调优经 `proxyTls: { autoSelectFamilyAttemptTimeout: 2000 }`（构造内部展开透传到「到代理」连接）；禁传 `connect` 选项——主类不消费该字段，传入被静默忽略
+- socks5：`Socks5ProxyAgent` 调优经 `connect: buildConnector({ autoSelectFamilyAttemptTimeout: 2000 })` 的 **connector 函数形态**（对象形态首个请求建隧道时 TypeError）；`proxyTls` 是「代理连接走 TLS」开关，不可当调优参数袋
+- 两协议 agent 均挂防崩溃 error listener（对齐 pi `withUndiciErrorListener` 形态）
+
+上述契约由 `src/__tests__/dispatcher-construction.test.ts` 构造形态冒烟测试锁定；分流/计数/状态机行为由 `src/__tests__/fetch-wrapper.test.ts` 锁定。undici 升级时这两处是第一道回归防线。

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@zhushanwen/pi-network-proxy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "LLM network proxy: rule-based per-hostname traffic splitting via a globalThis.fetch wrapper (http/https/socks5 proxy), with request counters.",
+  "type": "module",
+  "main": "index.ts",
+  "taiji": {
+    "role": "universal",
+    "startupConfig": [
+      {
+        "path": "config/network-proxy-ext-config.json",
+        "content": {
+          "enabled": false,
+          "proxy": {
+            "protocol": "http",
+            "host": "127.0.0.1",
+            "port": 7890,
+            "username": "",
+            "password": ""
+          },
+          "noProxy": [
+            "localhost",
+            "127.0.0.1"
+          ],
+          "rules": []
+        }
+      }
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "dependencies": {
+    "undici": "^7.28.0",
+    "@zhushanwen/pi-ext-guards": "0.5.0",
+    "@zhushanwen/pi-extension-logger": "0.6.2",
+    "@zhushanwen/pi-file-lock": "0.4.1",
+    "@zhushanwen/pi-llm-shared": "0.11.3"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
+    "vitest": "^4.1.8"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "skills/",
+    "vitest.config.ts"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
 }

package/skills/network-proxy-ext-config/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: network-proxy-ext-config
+description: "配置 @zhushanwen/pi-network-proxy（LLM 网络代理分流）时加载。含配置文件路径、NetworkProxyConfig schema（enabled/proxy/noProxy/rules）、协议三选一（http/https/socks5）、suffix 主机名匹配语义、noProxy 优先级、凭据成对约束、默认值、示例、生效时机（turn 粒度热重载）、统计文件、故障恢复。触发词：配置网络代理、network-proxy 配置、代理规则、走代理、socks5、noProxy、network-proxy config、代理不生效、代理报错、直连排除。"
+---
+
+# network-proxy 配置指南
+
+> @zhushanwen/pi-network-proxy：包装 pi 进程的 `globalThis.fetch`，按主机名规则分流——命中规则的请求经代理出站，未命中的保持 pi 原生行为（直连或 env 代理），并按主机名计数（经代理 / 直连）。打包版与独立 pi 都生效（不依赖 pi 与扩展共享 undici 模块实例）。
+
+## 配置文件位置
+
+`<agentDir>/config/network-proxy-ext-config.json`
+
+- `<agentDir>` = pi agent 目录（`PI_CODING_AGENT_DIR` 覆盖，默认 `~/.pi/agent`；taiji 隔离环境为 `~/.taiji/agent`）
+- 走 llm-shared 泛型 config（config/ 子目录 + getAgentDir 派生 + mtime+size 缓存 + 原子写）
+- taiji 桌面端由 runtime 启动序列首建该文件（`taiji.startupConfig` 声明）；独立 pi 用户手建同样生效
+- 文件缺失/坏 JSON/字段非法：回落默认（enabled=false，全部直连）并以 extension error 呈现，不阻断 pi
+
+## Schema
+
+```ts
+interface NetworkProxyConfig {
+  enabled: boolean;      // 总开关，默认 false（禁用 = 不包装 fetch，全部按 pi 原生行为出站）
+  proxy: {
+    protocol: "http" | "https" | "socks5";  // http/https 走 undici ProxyAgent，socks5 走 Socks5ProxyAgent
+    host: string;        // 代理服务器地址，如 127.0.0.1
+    port: number;        // 1-65535 整数
+    username: string;    // 认证用户名（可空，但必须与 password 成对）
+    password: string;    // 认证密码（可空，但必须与 username 成对）
+  };
+  noProxy: string[];     // 直连排除清单（主机名条目），优先级高于 rules——本地网关地址必须加在这里
+  rules: string[];       // 代理规则（主机名条目），命中即经代理
+}
+```
+
+校验规则（违反即回落禁用态并报错，错误文案含修复动作）：协议白名单、端口 1-65535 整数、凭据成对（同空或同非空）、noProxy/rules 每条非空且不含空白字符（含空白的条目对真实主机名恒不匹配，校验层显式拒绝，错误文案提示删除空白）。
+
+## 匹配语义
+
+- 主机名与条目先归一化（转小写、去末尾点），再 suffix 匹配：**等于或以 `.条目` 结尾**
+  - 条目 `api.anthropic.com` 命中 `api.anthropic.com` 与 `eu.api.anthropic.com`
+  - `xapi.anthropic.com` 不命中（无点前缀拼接）；`api-anthropic.com.evil.com` 不命中（恶意后缀）
+- 匹配对象 = 请求目标 URL 的主机名（服务商 baseURL 的主机名；端口不参与匹配）
+- noProxy 先于 rules 判定（先排除再匹配）；`localhost` 条目同时覆盖 `localhost` 与 `*.localhost`
+- 不支持 `*` 通配（无已发生需求）；分流覆盖经 `globalThis.fetch` 发出的请求（pi LLM 调用与 OAuth/目录请求）；直接使用 `undici.request` / `Client` 的调用不经过本包装
+
+## 生效时机（turn 粒度热重载）
+
+- 每个 turn 开始重读配置，指纹（enabled+proxy+noProxy+rules）变化才重建包装——**运行中会话自下一轮对话起生效，无需重启**；turn 进行中（工具循环连续请求）保存的配置对该 turn 内后续请求不生效
+- `enabled` 从 true → false：立即恢复包装前的 fetch（全部直连/env 代理路由）
+- 未命中规则的流量委托包装前的 fetch——独立 pi 用户设了 `HTTPS_PROXY` 环境变量时，未命中流量仍走 env 代理，语义不丢失
+- pi 的 `configureHttpDispatcher` 带 shouldInstallGlobals 守卫（pi dist/core/http-dispatcher.js:88-99）：检测到 `globalThis.fetch` 已被第三方覆盖即保留不重装，本扩展的包装在同进程内持续生效；槽位被其他第三方整体覆盖时，下一 turn 开始自动以覆盖者为新 original 重新包装（防御路径）
+
+## 统计文件
+
+`<agentDir>/network-proxy-stats.jsonl`（agentDir 根）：每行一个 JSON 片段 `{ ts, host, proxied, direct }`，turn 结束 / 进程退出时把本进程增量追加落盘；计数时点 = 请求发起时。taiji 设置页「网络代理 → 请求统计」读侧聚合展示（含重置与截断），直接读文件按行求和亦可。
+
+## 故障恢复
+
+| 现象 | 处置 |
+|---|---|
+| 代理不可达（请求报 `fetch failed` / `ECONNREFUSED`） | 启动代理软件；或把 `enabled` 改为 `false` 一键恢复直连 |
+| socks5 构造失败（undici 实验性 API 变化） | extension error 提示并保持全部直连；切回 `http` 协议即可恢复代理 |
+| 配置校验失败（端口越界 / 凭据单边等） | 按报错文案修正配置文件，或删除该文件恢复默认禁用态 |
+| 想让某服务商不再走代理 | 从 `rules` 删除对应主机名条目，或将其加入 `noProxy` |
+
+## 配置示例
+
+```json
+{
+  "enabled": true,
+  "proxy": { "protocol": "http", "host": "127.0.0.1", "port": 7890, "username": "", "password": "" },
+  "noProxy": ["localhost", "127.0.0.1"],
+  "rules": ["api.anthropic.com"]
+}
+```

package/src/__tests__/config.test.ts

@@ -0,0 +1,234 @@
+/**
+ * 配置校验语义镜像 + 指纹 + 热重载读取。
+ *
+ * 校验/默认值语义 SSOT = packages/shared/src/network-proxy.ts（复制体镜像锁定——本文件
+ * 关键形态断言的字面文案与 shared validateNetworkProxyConfig 一致）；DEFAULT 与
+ * startupConfig 声明的深相等由 startup-config-declaration.test.ts 另锁。
+ */
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { clearConfigCache } from "@zhushanwen/pi-llm-shared";
+
+import {
+	DEFAULT_NETWORK_PROXY_CONFIG,
+	loadNetworkProxyConfig,
+	networkProxyFingerprint,
+	normalizeNetworkProxyConfig,
+	validateNetworkProxyConfig,
+	type NetworkProxyConfig,
+} from "../config.ts";
+
+// mock 掉共享 logger（loadConfig 的 onWarning 由本测试显式断言，logger 通道静音防噪音）
+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(),
+}));
+
+let agentDir: string;
+
+beforeEach(() => {
+	agentDir = mkdtempSync(join(tmpdir(), "network-proxy-cfg-"));
+	vi.stubEnv("PI_CODING_AGENT_DIR", agentDir);
+	clearConfigCache();
+});
+
+afterEach(() => {
+	vi.unstubAllEnvs();
+});
+
+function writeConfigFile(content: unknown): void {
+	mkdirSync(join(agentDir, "config"), { recursive: true });
+	writeFileSync(
+		join(agentDir, "config", "network-proxy-ext-config.json"),
+		JSON.stringify(content, null, 2),
+		"utf-8",
+	);
+}
+
+function validConfig(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,
+	};
+}
+
+describe("validateNetworkProxyConfig（语义镜像）", () => {
+	it("合法配置 ok", () => {
+		expect(validateNetworkProxyConfig(validConfig())).toEqual({ ok: true });
+		expect(validateNetworkProxyConfig(DEFAULT_NETWORK_PROXY_CONFIG)).toEqual({ ok: true });
+	});
+
+	it("协议白名单：非法协议报错且文案与 shared 一致", () => {
+		const result = validateNetworkProxyConfig(validConfig({
+			proxy: { protocol: "socks4" as never, host: "127.0.0.1", port: 7890, username: "", password: "" },
+		}));
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.errors[0]).toContain("http / https / socks5");
+		}
+	});
+
+	it("端口越界（70000 / 0 / 非整数）逐项报错，不短路", () => {
+		for (const port of [70000, 0, 1.5]) {
+			const result = validateNetworkProxyConfig(validConfig({
+				proxy: { protocol: "http", host: "127.0.0.1", port, username: "", password: "" },
+			}));
+			expect(result.ok).toBe(false);
+			if (!result.ok) {
+				expect(result.errors.some((e) => e.includes("1-65535"))).toBe(true);
+			}
+		}
+	});
+
+	it("凭据单边报错（成对约束）", () => {
+		const onlyUser = validateNetworkProxyConfig(validConfig({
+			proxy: { protocol: "http", host: "h", port: 1, username: "u", password: "" },
+		}));
+		const onlyPass = validateNetworkProxyConfig(validConfig({
+			proxy: { protocol: "http", host: "h", port: 1, username: "", password: "p" },
+		}));
+		expect(onlyUser.ok).toBe(false);
+		expect(onlyPass.ok).toBe(false);
+		// 成对非空合法
+		expect(validateNetworkProxyConfig(validConfig({
+			proxy: { protocol: "http", host: "h", port: 1, username: "u", password: "p" },
+		})).ok).toBe(true);
+	});
+
+	it("enabled 非布尔报错", () => {
+		const result = validateNetworkProxyConfig(validConfig({ enabled: "yes" as never }));
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.errors[0]).toContain("开或关");
+		}
+	});
+
+	it("noProxy/rules 条目空串与非列表报错", () => {
+		const emptyEntry = validateNetworkProxyConfig(validConfig({ rules: ["  "] }));
+		expect(emptyEntry.ok).toBe(false);
+		const notArray = validateNetworkProxyConfig(validConfig({ noProxy: "localhost" as never }));
+		expect(notArray.ok).toBe(false);
+	});
+
+	it("noProxy/rules 条目空白字符拒绝（首尾与内部同等拒绝——归一化不 trim，带空白恒不匹配故校验显式拒绝，文案与 shared 一致）", () => {
+		const leading = validateNetworkProxyConfig(validConfig({ rules: [" api.anthropic.com"] }));
+		expect(leading.ok).toBe(false);
+		if (!leading.ok) {
+			expect(leading.errors[0]).toContain("第 1 条含空白字符");
+		}
+		const trailingTab = validateNetworkProxyConfig(validConfig({ noProxy: ["localhost\t"] }));
+		expect(trailingTab.ok).toBe(false);
+		if (!trailingTab.ok) {
+			expect(trailingTab.errors[0]).toContain("含空白字符，请删除空白后保存");
+		}
+		// 内部空白（如「api. anthropic.com」）同样拒绝：对真实主机名恒不匹配，静默不生效
+		const inner = validateNetworkProxyConfig(validConfig({ rules: ["api. anthropic.com"] }));
+		expect(inner.ok).toBe(false);
+		if (!inner.ok) {
+			expect(inner.errors[0]).toContain("含空白字符，请删除空白后保存");
+		}
+		// 纯空白条目仍走「为空」分支，不误报为「含空白」
+		const blankOnly = validateNetworkProxyConfig(validConfig({ rules: [" "] }));
+		expect(blankOnly.ok).toBe(false);
+		if (!blankOnly.ok) {
+			expect(blankOnly.errors[0]).toContain("第 1 条为空");
+		}
+	});
+
+	it("对象性守卫：null / 数组 / 标量返回错误信封而非抛异常", () => {
+		for (const bad of [null, [validConfig()], "config", 42]) {
+			const result = validateNetworkProxyConfig(bad);
+			expect(result.ok).toBe(false);
+		}
+	});
+});
+
+describe("normalizeNetworkProxyConfig（读取路径校验闸）", () => {
+	it("合法 raw 原样返回", () => {
+		const config = validConfig();
+		expect(normalizeNetworkProxyConfig(config)).toEqual(config);
+	});
+
+	it("非法 raw throw 且消息含逐项错误（loadConfig 捕获后回落 defaults + onWarning）", () => {
+		expect(() =>
+			normalizeNetworkProxyConfig(validConfig({
+				proxy: { protocol: "http", host: "127.0.0.1", port: 70000, username: "", password: "" },
+			})),
+		).toThrow(/1-65535/);
+	});
+});
+
+describe("networkProxyFingerprint（指纹比对）", () => {
+	it("同配置同指纹", () => {
+		expect(networkProxyFingerprint(validConfig())).toBe(networkProxyFingerprint(validConfig()));
+	});
+
+	it("enabled 翻转 / proxy 变更 / noProxy 变更 / rules 变更各自产生不同指纹", () => {
+		const base = networkProxyFingerprint(validConfig());
+		expect(networkProxyFingerprint(validConfig({ enabled: false }))).not.toBe(base);
+		expect(networkProxyFingerprint(validConfig({
+			proxy: { protocol: "http", host: "10.0.0.1", port: 7890, username: "", password: "" },
+		}))).not.toBe(base);
+		expect(networkProxyFingerprint(validConfig({ noProxy: ["localhost", "internal.test"] }))).not.toBe(base);
+		expect(networkProxyFingerprint(validConfig({ rules: ["api.openai.com"] }))).not.toBe(base);
+	});
+
+	it("重复条目不影响指纹（去重语义——匹配幂等，重建判据不受条目重复干扰）", () => {
+		expect(networkProxyFingerprint(validConfig({ rules: ["a.test", "a.test"] }))).toBe(
+			networkProxyFingerprint(validConfig({ rules: ["a.test"] })),
+		);
+	});
+});
+
+describe("loadNetworkProxyConfig（llm-shared 读时刷新热重载）", () => {
+	it("文件缺失回落 defaults", () => {
+		expect(loadNetworkProxyConfig()).toEqual(DEFAULT_NETWORK_PROXY_CONFIG);
+	});
+
+	it("合法文件返回配置；改文件后同进程重读即时生效（热重载）", () => {
+		writeConfigFile(validConfig());
+		expect(loadNetworkProxyConfig()?.enabled).toBe(true);
+
+		writeConfigFile(validConfig({ enabled: false }));
+		expect(loadNetworkProxyConfig()?.enabled).toBe(false);
+	});
+
+	it("非法文件（字段非法）回落 defaults 并经 onWarning 报错（验收场景 10 的读取侧形态）", () => {
+		const warnings: string[] = [];
+		writeConfigFile(validConfig({
+			proxy: { protocol: "http", host: "127.0.0.1", port: 70000, username: "", password: "" },
+		}));
+		const config = loadNetworkProxyConfig((msg) => warnings.push(msg));
+		expect(config).toEqual(DEFAULT_NETWORK_PROXY_CONFIG);
+		expect(warnings).toHaveLength(1);
+		expect(warnings[0]).toContain("1-65535");
+	});
+
+	it("手编文件带空白字符条目（内部空白形态）回落 defaults 并经 onWarning 报错（不再静默不生效）", () => {
+		const warnings: string[] = [];
+		writeConfigFile(validConfig({ noProxy: ["api. anthropic.com"] }));
+		const config = loadNetworkProxyConfig((msg) => warnings.push(msg));
+		expect(config).toEqual(DEFAULT_NETWORK_PROXY_CONFIG);
+		expect(warnings).toHaveLength(1);
+		expect(warnings[0]).toContain("含空白字符，请删除空白后保存");
+	});
+
+	it("坏 JSON 回落 defaults 并经 onWarning 报错", () => {
+		const warnings: string[] = [];
+		mkdirSync(join(agentDir, "config"), { recursive: true });
+		writeFileSync(join(agentDir, "config", "network-proxy-ext-config.json"), "{not json", "utf-8");
+		const config = loadNetworkProxyConfig((msg) => warnings.push(msg));
+		expect(config).toEqual(DEFAULT_NETWORK_PROXY_CONFIG);
+		expect(warnings).toHaveLength(1);
+	});
+});

package/src/__tests__/dispatcher-construction.test.ts

@@ -0,0 +1,110 @@
+/**
+ * 两协议构造形态冒烟（任务书验收②，防回归锚——防实现照抄错形态）：
+ * - http/https：ProxyAgent 必须收到 proxyTls 调优（主类内部 buildConnector({...opts.proxyTls})
+ *   透传），且不得传 connect 选项（ProxyAgent 不消费该字段——传入被静默忽略、调优失效不报错）
+ * - socks5：Socks5ProxyAgent 必须收到函数形态 connect（buildConnector 产物）——构造选项只收
+ *   connector 函数，对象形态首个请求建隧道时 TypeError；proxyTls 是 TLS 开关不可当调优袋
+ * 契约来源：设计 §3.1 行为序列 3（undici 7.28.0 源码读码 + 构造探针核实）。
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { proxyAgentCalls, socks5AgentCalls, connectorResults, mockBuildConnector } = vi.hoisted(() => ({
+	proxyAgentCalls: [] as Array<Record<string, unknown>>,
+	socks5AgentCalls: [] as Array<{ url: string; options: Record<string, unknown> }>,
+	connectorResults: [] as Array<(...args: unknown[]) => unknown>,
+	mockBuildConnector: (options: Record<string, unknown>) => {
+		const connector = () => {};
+		connectorResults.push(options);
+		return connector;
+	},
+}));
+
+vi.mock("undici", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("undici")>();
+	class MockProxyAgent extends actual.Dispatcher {
+		constructor(options: Record<string, unknown>) {
+			super();
+			proxyAgentCalls.push(options);
+		}
+	}
+	class MockSocks5ProxyAgent extends actual.Dispatcher {
+		constructor(url: string, options: Record<string, unknown> = {}) {
+			super();
+			socks5AgentCalls.push({ url, options });
+		}
+	}
+	return {
+		...actual,
+		ProxyAgent: MockProxyAgent,
+		Socks5ProxyAgent: MockSocks5ProxyAgent,
+		buildConnector: mockBuildConnector,
+	};
+});
+
+import {
+	buildProxyDispatcher,
+	buildProxyUrl,
+	PROXY_CONNECT_ATTEMPT_TIMEOUT_MS,
+} from "../dispatcher.ts";
+import type { NetworkProxyConfig } from "../config.ts";
+
+function config(protocol: "http" | "https" | "socks5"): NetworkProxyConfig {
+	return {
+		enabled: true,
+		proxy: { protocol, host: "127.0.0.1", port: 7890, username: "", password: "" },
+		noProxy: [],
+		rules: [],
+	};
+}
+
+beforeEach(() => {
+	proxyAgentCalls.length = 0;
+	socks5AgentCalls.length = 0;
+	connectorResults.length = 0;
+});
+
+describe("两协议构造形态冒烟（防回归锚）", () => {
+	it("http：ProxyAgent 收到 proxyTls 调优，不传 connect 选项（传入会被静默忽略）", () => {
+		buildProxyDispatcher(config("http"));
+		expect(proxyAgentCalls).toHaveLength(1);
+		const options = proxyAgentCalls[0];
+		expect(options.uri).toBe(buildProxyUrl(config("http").proxy));
+		// port: 0 = BuildOptions 类型占位（实际建连被目标端口覆盖，见 dispatcher.ts PROXY_TLS_TUNING 注）
+		expect(options.proxyTls).toEqual({
+			port: 0,
+			autoSelectFamilyAttemptTimeout: PROXY_CONNECT_ATTEMPT_TIMEOUT_MS,
+		});
+		expect("connect" in options).toBe(false);
+	});
+
+	it("https 与 http 同走 ProxyAgent（proxyTls 形态一致）", () => {
+		buildProxyDispatcher(config("https"));
+		expect(proxyAgentCalls).toHaveLength(1);
+		expect(proxyAgentCalls[0].proxyTls).toEqual({
+			port: 0,
+			autoSelectFamilyAttemptTimeout: PROXY_CONNECT_ATTEMPT_TIMEOUT_MS,
+		});
+	});
+
+	it("socks5：Socks5ProxyAgent 收到函数形态 connect（buildConnector 产物）+ 调优值透传", () => {
+		buildProxyDispatcher(config("socks5"));
+		expect(socks5AgentCalls).toHaveLength(1);
+		const { url, options } = socks5AgentCalls[0];
+		expect(url).toBe(buildProxyUrl(config("socks5").proxy));
+		expect(typeof options.connect).toBe("function");
+		// connect 必须是本实现经 buildConnector 构造的产物（调优经函数形态生效的唯一通道）
+		expect(connectorResults).toEqual([
+			{ port: 0, autoSelectFamilyAttemptTimeout: PROXY_CONNECT_ATTEMPT_TIMEOUT_MS },
+		]);
+		// proxyTls 不得作为调优袋传给 socks5（它是 TLS 开关：truthy 即按 TLS 连代理，明文代理会被错误握手）
+		expect("proxyTls" in options).toBe(false);
+	});
+
+	it("两协议 agent 均挂防崩溃 error listener（对齐 pi withUndiciErrorListener 形态）", () => {
+		const httpDispatcher = buildProxyDispatcher(config("http"));
+		// EventEmitter "error" 无监听时 emit 会抛——挂上 noop listener 后 listenerCount > 0
+		expect(httpDispatcher.listenerCount("error")).toBeGreaterThan(0);
+		const socks5Dispatcher = buildProxyDispatcher(config("socks5"));
+		expect(socks5Dispatcher.listenerCount("error")).toBeGreaterThan(0);
+	});
+});

package/src/__tests__/dispatcher.test.ts

@@ -0,0 +1,37 @@
+/**
+ * 代理 URL 构造（凭据 percent-encode 拼入）。
+ * 分流行为与计数已随拦截点迁移到 fetch-wrapper.test.ts；两协议构造形态冒烟在
+ * dispatcher-construction.test.ts（vi.mock undici 隔离）。
+ */
+import { describe, expect, it } from "vitest";
+
+import { buildProxyUrl } from "../dispatcher.ts";
+import type { NetworkProxyServer } from "../config.ts";
+
+describe("buildProxyUrl（凭据 percent-encode 拼入）", () => {
+	const base: NetworkProxyServer = {
+		protocol: "http",
+		host: "127.0.0.1",
+		port: 7890,
+		username: "",
+		password: "",
+	};
+
+	it("无凭据形态", () => {
+		expect(buildProxyUrl(base)).toBe("http://127.0.0.1:7890");
+	});
+
+	it("凭据 percent-encode 拼入（特殊字符被编码，undici 构造内部 decodeURIComponent 还原）", () => {
+		expect(buildProxyUrl({ ...base, username: "user@example.com", password: "p@ss:word" })).toBe(
+			"http://user%40example.com:p%40ss%3Aword@127.0.0.1:7890",
+		);
+	});
+
+	it("socks5 协议形态（Socks5ProxyAgent 校验 socks5: 协议头）", () => {
+		expect(buildProxyUrl({ ...base, protocol: "socks5", port: 1080 })).toBe("socks5://127.0.0.1:1080");
+	});
+
+	it("https 协议形态", () => {
+		expect(buildProxyUrl({ ...base, protocol: "https", port: 443 })).toBe("https://127.0.0.1:443");
+	});
+});