@zhushanwen/pi-network-proxy 0.3.0 → 0.3.1

package/README.md

@@ -5,9 +5,9 @@ LLM 网络代理分流：包装 pi 进程的 `globalThis.fetch`，按主机名
 ## 行为摘要
 
 - **拦截点**：`globalThis.fetch`。pi-ai 的 OpenAI 兼容请求在每次构造 client 时经 `Shims.getDefaultFetch()` 动态取当前全局 fetch，包装它不依赖 pi 与扩展共享 undici 模块实例
-- **安装/卸载**：extension 加载时读配置，`enabled` 且校验通过 → 包装并构造代理 dispatcher；`enabled` false → 恢复原 fetch；校验/构造失败 → extension error（含配置文件恢复指引），不包装不阻断 pi（全部直连）
+- **安装/卸载**：extension 加载时读配置，`enabled` 开启或 `ipv4Only` 非空且校验通过 → 包装（`enabled` 且命中规则走代理 dispatcher，`ipv4Only` 命中锁 IPv4 直连，后者不受开关影响）；`enabled` false 且 `ipv4Only` 空 → 恢复原 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
+- **匹配语义**：主机名归一化（小写、去末尾点）后 suffix 匹配（等于或以 `.条目` 结尾，点边界对齐）；优先级 noProxy > ipv4Only > rules（rules 另受 `enabled` 门控）
 - **覆盖面**：经 `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 协议恢复；同指纹不重试构造，配置修正（指纹变化）后自然重试

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-network-proxy",
-  "version": "0.3.0",
+  "version": "0.3.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",
@@ -41,10 +41,10 @@
   ],
   "dependencies": {
     "undici": "^7.28.0",
+    "@zhushanwen/pi-llm-shared": "0.12.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.12.0"
+    "@zhushanwen/pi-file-lock": "0.4.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",

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

@@ -1,6 +1,6 @@
 ---
 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、代理不生效、代理报错、直连排除。"
+description: "配置 @zhushanwen/pi-network-proxy（LLM 网络代理分流）时加载。含配置文件路径、NetworkProxyConfig schema（enabled/proxy/noProxy/rules/ipv4Only）、协议三选一（http/https/socks5）、suffix 主机名匹配语义、noProxy 优先级、凭据成对约束、默认值、示例、生效时机（turn 粒度热重载）、统计文件、故障恢复。触发词：配置网络代理、network-proxy 配置、代理规则、走代理、socks5、noProxy、network-proxy config、代理不生效、代理报错、直连排除、强制 IPv4、ipv4Only。"
 ---
 
 # network-proxy 配置指南
@@ -20,7 +20,8 @@ description: "配置 @zhushanwen/pi-network-proxy（LLM 网络代理分流）时
 
 ```ts
 interface NetworkProxyConfig {
-  enabled: boolean;      // 总开关，默认 false（禁用 = 不包装 fetch，全部按 pi 原生行为出站）
+  enabled: boolean;      // 代理分流总开关，默认 false（关闭 = rules 不参与分流，全部直连/env 代理；
+                         // 不影响 ipv4Only——见下）
   proxy: {
     protocol: "http" | "https" | "socks5";  // http/https 走 undici ProxyAgent，socks5 走 Socks5ProxyAgent
     host: string;        // 代理服务器地址，如 127.0.0.1
@@ -29,9 +30,10 @@ interface NetworkProxyConfig {
     password: string;    // 认证密码（可空，但必须与 username 成对）
   };
   noProxy: string[];     // 直连排除清单（主机名条目），优先级高于 rules——本地网关地址必须加在这里
-  rules: string[];       // 代理规则（主机名条目），命中即经代理
+  rules: string[];       // 代理规则（主机名条目），enabled 开启时命中即经代理
   ipv4Only: string[];    // 直连 + 强制 IPv4 清单（主机名条目）：命中不走代理，DNS 解析锁定 A 记录直连
-                         // （URL / Host 头 / TLS SNI 保持原样，只干预「选哪个 IP」）；用于「IPv6 可达但握手抖动」的服务商
+                         // （URL / Host 头 / TLS SNI 保持原样，只干预「选哪个 IP」）；用于「IPv6 可达但握手抖动」的服务商。
+                         // 独立于 enabled 开关：代理关闭时本清单照常生效（清单非空即安装分流包装层）
 }
 ```
 
@@ -51,7 +53,7 @@ interface NetworkProxyConfig {
 ## 生效时机（turn 粒度热重载）
 
 - 每个 turn 开始重读配置，指纹（enabled+proxy+noProxy+rules+ipv4Only）变化才重建包装——**运行中会话自下一轮对话起生效，无需重启**；turn 进行中（工具循环连续请求）保存的配置对该 turn 内后续请求不生效
-- `enabled` 从 true → false：立即恢复包装前的 fetch（全部直连/env 代理路由）
+- `enabled` 从 true → false 且 `ipv4Only` 为空：立即恢复包装前的 fetch（全部直连/env 代理路由）；`ipv4Only` 非空时包装保留（IPv4 锁定不随代理开关关闭而失效，仅代理分流停用）
 - 未命中规则的流量委托包装前的 fetch——独立 pi 用户设了 `HTTPS_PROXY` 环境变量时，未命中流量仍走 env 代理，语义不丢失
 - pi 的 `configureHttpDispatcher` 带 shouldInstallGlobals 守卫（pi dist/core/http-dispatcher.js:88-99）：检测到 `globalThis.fetch` 已被第三方覆盖即保留不重装，本扩展的包装在同进程内持续生效；槽位被其他第三方整体覆盖时，下一 turn 开始自动以覆盖者为新 original 重新包装（防御路径）
 
@@ -70,11 +72,26 @@ interface NetworkProxyConfig {
 
 ## 配置示例
 
+代理分流 + IPv4 锁定并用：
+
 ```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"]
+  "rules": ["api.anthropic.com"],
+  "ipv4Only": ["open-design.ai"]
+}
+```
+
+仅 IPv4 锁定、不走代理（`enabled=false` 时 `rules` 不参与分流，`ipv4Only` 照常生效）：
+
+```json
+{
+  "enabled": false,
+  "proxy": { "protocol": "http", "host": "127.0.0.1", "port": 7890, "username": "", "password": "" },
+  "noProxy": ["localhost", "127.0.0.1"],
+  "rules": [],
+  "ipv4Only": ["open-design.ai"]
 }
 ```

package/src/__tests__/fetch-wrapper.test.ts

@@ -2,6 +2,7 @@
  * fetch 包装状态机单测（fake 依赖注入，不触真实网络）：
  * 命中/未命中分流、计数、noProxy/ipv4Only 优先级、ipv4 与代理构造的差异化降级
  * （ipv4 失败只丢 v4 锁定、proxy 失败锁整层；rules 为空不构造代理）、禁用恢复、
+ * ipv4Only 独立于 enabled 代理开关（开关关闭时清单照常生效、rules 不参与分流）、
  * 外部覆盖重装、构造失败锁定、reload 残留摘除、入参形态覆盖。
  * 转移表见 fetch-wrapper.ts 文件头。
  */
@@ -335,6 +336,62 @@ describe("applyNetworkProxyConfig 包装状态机", () => {
 		expect(h.errors).toHaveLength(0);
 	});
 
+	it("enabled=false 且 ipv4Only 非空：包装保留，ipv4Only 命中照常锁 v4 直连", async () => {
+		const h = createHarness();
+		h.setBuildProxy(() => {
+			throw new Error("开关关闭不应构造代理分发器");
+		});
+		const state = applyNetworkProxyConfig(
+			config({ enabled: false, rules: [], ipv4Only: ["open-design.ai"] }),
+			null,
+			h.deps,
+		);
+		expect(state?.wrapper).not.toBeNull();
+		expect(h.getCurrent()).toBe(state?.wrapper);
+		expect(h.buildCalls).toHaveLength(0); // 代理分流不构建
+		expect(h.buildIpv4Calls).toHaveLength(1);
+
+		const response = await h.getCurrent()("https://amr-link.open-design.ai/v1/chat");
+		expect(h.proxyCalls).toHaveLength(1);
+		expect(h.proxyCalls[0]?.init.dispatcher).toBe(h.ipv4);
+		expect(await response.text()).toBe("proxy");
+		expect(snapshotCounters().get("amr-link.open-design.ai")).toEqual({ proxied: 0, direct: 1 });
+	});
+
+	it("enabled=false 时 rules 不参与分流：规则主机直连计数，不走代理", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(
+			config({ enabled: false, rules: ["api.anthropic.com"], ipv4Only: ["open-design.ai"] }),
+			null,
+			h.deps,
+		);
+		await h.getCurrent()("https://api.anthropic.com/v1/messages");
+		expect(h.proxyCalls).toHaveLength(0);
+		expect(h.originalCalls).toHaveLength(1);
+		expect(snapshotCounters().get("api.anthropic.com")).toEqual({ proxied: 0, direct: 1 });
+	});
+
+	it("enabled true→false 且 ipv4Only 非空：包装保持（重建不摘除），ipv4 分流继续生效", async () => {
+		const h = createHarness();
+		const first = applyNetworkProxyConfig(
+			config({ rules: [], ipv4Only: ["open-design.ai"] }),
+			null,
+			h.deps,
+		);
+		const after = applyNetworkProxyConfig(
+			config({ enabled: false, rules: [], ipv4Only: ["open-design.ai"] }),
+			first,
+			h.deps,
+		);
+		expect(after).not.toBeNull();
+		expect(h.getCurrent()).toBe(after?.wrapper);
+		expect(h.getCurrent()).not.toBe(h.originalFetch);
+
+		await h.getCurrent()("https://amr-link.open-design.ai/v1/chat");
+		expect(h.proxyCalls).toHaveLength(1);
+		expect(h.proxyCalls[0]?.init.dispatcher).toBe(h.ipv4);
+	});
+
 	it("构造失败：onError + 不包装（全直连），同指纹锁定不重试；指纹变化后重试", () => {
 		const h = createHarness();
 		h.setBuildProxy(() => {

package/src/config.ts

@@ -47,7 +47,11 @@ export interface NetworkProxyConfig { // oe-exempt:20261019:framework:ext-config
 	 * （autoSelectFamilyAttemptTimeout=2000）反复试 IPv6，把 connect 预算耗在坏路径上，
 	 * 最终表现为 `Request timed out.`——实为连接层超时，不是 provider 故障。
 	 *
-	 * 优先级：noProxy > ipv4Only > rules。
+	 * 独立于 `enabled` 代理开关：`enabled=false` 时本清单照常生效（IPv4 锁定是直连的
+	 * 地址族修正，不是代理能力；清单非空即安装包装层）。
+	 *
+	 * 优先级：noProxy > ipv4Only > rules（rules 另受 enabled 门控——开关关闭时规则
+	 * 不参与分流）。
 	 */
 	ipv4Only: string[];
 }

package/src/fetch-wrapper.ts

@@ -16,7 +16,8 @@
  * 保留 pi 原生 EnvHttpProxyAgent / 连接调优 / 错误处理语义。
  *
  * 生命周期与旧安装状态机同构：
- * - 加载 / 每 turn 开始：重读配置推进状态（禁用 = 摘除包装恢复原 fetch）；
+ * - 加载 / 每 turn 开始：重读配置推进状态（`enabled` 关且 `ipv4Only` 空 = 摘除包装恢复原
+ *   fetch；`ipv4Only` 非空时包装保留——IPv4 锁定是直连地址族修正，独立于代理开关）；
  * - 指纹未变且包装仍在进程槽位：零动作（不重建）；
   * - 槽位被第三方整体覆盖（其他 extension 包装 / 手动改写；pi 的 configureHttpDispatcher
   *   有 shouldInstallGlobals 守卫（pi dist/core/http-dispatcher.js:88-99）——检测到 fetch
@@ -147,8 +148,9 @@ function wrapperMarkOf(fetch: FetchLike): FetchWrapperMark | null {
  *
  * 分流优先级（单一源在这里，config.ts 的 hits* 只提供匹配，不重复排序）：
  * 1. `noProxy` 命中 → 原样直连（用户显式排除，连 IPv4 锁定也不做）；
- * 2. `ipv4Only` 命中 → IPv4 锁定直连（**不走代理**，本扩展只做地址族选择）；
- * 3. `rules` 命中 → 经代理 fetch；
+ * 2. `ipv4Only` 命中 → IPv4 锁定直连（**不走代理**，本扩展只做地址族选择；独立于
+ *    `enabled` 代理开关——开关关闭时本分支照常生效）；
+ * 3. `enabled` 且 `rules` 命中 → 经代理 fetch（开关关闭时 rules 不参与分流，落入直连）；
  * 4. 其余 → 原样直连。
  *
  * 计数时点 = 请求发起时（与旧分流器一致；不等待完成，成败由 pi 原生错误链路呈现）。
@@ -178,7 +180,7 @@ function createWrappedFetch(
 			return proxyFetch(input, { ...(init ?? {}), dispatcher: ipv4 });
 		}
 
-		if (hitsRules(host, config.rules)) {
+		if (config.enabled && hitsRules(host, config.rules)) {
 			recordDispatch(host, true);
 			// proxy 非空由 applyNetworkProxyConfig 保证（rules 非空才会构造）。
 			if (proxy === null) return originalFetch(input, init);
@@ -279,7 +281,11 @@ export function applyNetworkProxyConfig(
 	state: FetchWrapperState | null,
 	deps: FetchWrapperDeps,
 ): FetchWrapperState | null {
-	if (!config.enabled) {
+	// 包装层的存在条件 = 代理开关开（rules 分流可用）或 ipv4Only 非空（IPv4 锁定直连）。
+	// 两者全无才摘除包装——ipv4Only 是直连地址族修正，语义上不依赖代理开关；
+	// 依据：2026-10-22 真机事故，用户仅配 ipv4Only（enabled=false）时整层被摘，
+	// subagent 的 LLM 请求全部 Connection error（双栈域名的 IPv6 路径抖动）。
+	if (!config.enabled && config.ipv4Only.length === 0) {
 		restoreOriginalIfOwned(state, deps);
 		return null;
 	}
@@ -293,12 +299,12 @@ export function applyNetworkProxyConfig(
 	}
 	const originalFetch = installed && state ? state.originalFetch : currentFetch;
 
-	// 代理分发器只在「确实可能用到代理」时构造：rules 为空 = 无任何主机走代理，
-	// 此时不应因代理配置不可用而锁死整个包装（含 ipv4Only 直连改写）。
+	// 代理分发器只在「确实可能用到代理」时构造：开关关闭或 rules 为空 = 无任何主机走
+	// 代理，此时不应因代理配置不可用而锁死整个包装（含 ipv4Only 直连改写）。
 	// 依据：一次事故（2026-10-22 真机验证）——仅配 ipv4Only、rules=[] 时仍构造
 	// ProxyAgent 并失败，lockOnBuildFailure 把包装整层撤下，ipv4Only 静默失效。
 	let proxy: Dispatcher | null = null;
-	if (config.rules.length > 0) {
+	if (config.enabled && config.rules.length > 0) {
 		try {
 			proxy = deps.buildProxy(config);
 		} catch (error) {

package/src/index.ts

@@ -2,11 +2,13 @@
  * @zhushanwen/pi-network-proxy 入口：配置驱动的 globalThis.fetch 包装与事件接线。
  *
  * 行为序列（fetch-wrapper.ts 头注有完整设计依据）：
- * - 加载时：读配置校验，enabled 且校验过 → 包装 globalThis.fetch（命中规则走代理，
- *   未命中委托原 fetch）；校验失败 / 构造失败 → extension error（文案含恢复动作：
- *   配置文件路径），不包装不阻断 pi（全部直连）。
+ * - 加载时：读配置校验，enabled 或 ipv4Only 非空且校验过 → 包装 globalThis.fetch
+ *   （ipv4Only 命中锁 IPv4 直连、enabled 且命中规则走代理，未命中委托原 fetch）；
+ *   校验失败 / 构造失败 → extension error（文案含恢复动作：配置文件路径），不包装
+ *   不阻断 pi（全部直连）。
  * - 每 turn 开始：重读配置（llm-shared 读时刷新热重载），指纹变化才重建；enabled true→false
- *   恢复原 fetch（fetch-wrapper.ts 状态机）。
+ *   且 ipv4Only 空时恢复原 fetch（fetch-wrapper.ts 状态机；ipv4Only 非空则包装保留，
+ *   IPv4 锁定不随代理开关关闭而失效）。
  * - 每 turn 结束：计数增量 flush 追加写入 stats JSONL（stats.ts）；进程退出兜底 flush。
  *
  * 覆盖面含 subagent 的 pi 进程（subagent 的 LLM 请求同样分流计数，设计前提 P4）——不设
@@ -95,7 +97,8 @@ export default function networkProxyExtension(pi: ExtensionAPI): void {
 	ensureExitFlush();
 	refreshFromConfig();
 
-	// turn 粒度热生效：turn 开始重读配置（mtime+size 未变时零 IO），指纹变化重建 / 禁用恢复。
+	// turn 粒度热生效：turn 开始重读配置（mtime+size 未变时零 IO），指纹变化重建 /
+	// 代理关且 ipv4Only 空时恢复直连。
 	pi.on("turn_start", () => {
 		refreshFromConfig();
 	});