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

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

@@ -0,0 +1,324 @@
+/**
+ * fetch 包装状态机单测（fake 依赖注入，不触真实网络）：
+ * 命中/未命中分流、计数、noProxy 优先、禁用恢复、外部覆盖重装、构造失败锁定、
+ * reload 残留摘除、入参形态覆盖。转移表见 fetch-wrapper.ts 文件头。
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Dispatcher } from "undici";
+
+import type { NetworkProxyConfig } from "../config.ts";
+import {
+	applyNetworkProxyConfig,
+	detachResidualFetchWrapper,
+	type FetchLike,
+	type FetchWrapperDeps,
+	type ProxyFetchInit,
+} from "../fetch-wrapper.ts";
+import { resetCounters, snapshotCounters } from "../stats.ts";
+
+class FakeDispatcher extends Dispatcher {}
+
+interface FetchCall { // oe-exempt:20261020:test:测试观测记录形状别名，仅本测试文件消费
+	input: string | URL | Request;
+	init?: RequestInit;
+}
+
+interface ProxyCall { // oe-exempt:20261020:test:测试观测记录形状别名，仅本测试文件消费
+	input: string | URL | Request;
+	init: ProxyFetchInit;
+}
+
+function config(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,
+	};
+}
+
+function withProxy(patch: Partial<NetworkProxyConfig["proxy"]>): Partial<NetworkProxyConfig> {
+	return { proxy: { ...config().proxy, ...patch } };
+}
+
+/** fake 依赖装配：original fetch / 代理 fetch / 构造器全部可观测、可注入失败。 */
+function createHarness() {
+	const originalCalls: FetchCall[] = [];
+	const originalFetch: FetchLike = async (input, init) => {
+		originalCalls.push({ input, init });
+		return new Response("original");
+	};
+	let currentFetch: FetchLike = originalFetch;
+
+	const proxyCalls: ProxyCall[] = [];
+	const proxy = new FakeDispatcher();
+	const proxyFetch = async (input: string | URL | Request, init: ProxyFetchInit): Promise<Response> => {
+		proxyCalls.push({ input, init });
+		return new Response("proxy");
+	};
+
+	let buildProxy = (_config: NetworkProxyConfig): Dispatcher => proxy;
+	const buildCalls: NetworkProxyConfig[] = [];
+	const errors: string[] = [];
+
+	const deps: FetchWrapperDeps = {
+		getFetch: () => currentFetch,
+		setFetch: (fetch) => {
+			currentFetch = fetch;
+		},
+		buildProxy: (next) => {
+			buildCalls.push(next);
+			return buildProxy(next);
+		},
+		proxyFetch,
+		onError: (message) => errors.push(message),
+	};
+
+	return {
+		deps,
+		originalFetch,
+		originalCalls,
+		proxyCalls,
+		proxy,
+		buildCalls,
+		errors,
+		getCurrent: () => currentFetch,
+		setCurrent: (fetch: FetchLike) => {
+			currentFetch = fetch;
+		},
+		setBuildProxy: (next: (config: NetworkProxyConfig) => Dispatcher) => {
+			buildProxy = next;
+		},
+	};
+}
+
+beforeEach(() => {
+	resetCounters();
+});
+
+describe("applyNetworkProxyConfig 包装状态机", () => {
+	it("首装 enabled：包装 globalThis.fetch 槽位（fake 槽），返回包装状态", () => {
+		const h = createHarness();
+		const state = applyNetworkProxyConfig(config(), null, h.deps);
+		expect(state).not.toBeNull();
+		expect(state?.wrapper).not.toBeNull();
+		expect(h.getCurrent()).toBe(state?.wrapper);
+		expect(h.errors).toHaveLength(0);
+	});
+
+	it("规则命中：走代理 fetch + proxied 计数，init 保留并注入 dispatcher", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config(), null, h.deps);
+		const response = await h.getCurrent()("https://api.anthropic.com/v1/messages", {
+			method: "POST",
+			headers: { "x-test": "1" },
+			body: "{}",
+		});
+		expect(await response.text()).toBe("proxy");
+		expect(h.proxyCalls).toHaveLength(1);
+		expect(h.originalCalls).toHaveLength(0);
+		expect(h.proxyCalls[0]?.init.dispatcher).toBe(h.proxy);
+		expect(h.proxyCalls[0]?.init.method).toBe("POST");
+		expect(h.proxyCalls[0]?.init.headers).toEqual({ "x-test": "1" });
+		expect(h.proxyCalls[0]?.init.body).toBe("{}");
+		expect(snapshotCounters().get("api.anthropic.com")).toEqual({ proxied: 1, direct: 0 });
+	});
+
+	it("规则未命中：原样委托原 fetch + direct 计数", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config(), null, h.deps);
+		const init: RequestInit = { method: "GET" };
+		const response = await h.getCurrent()("https://open.bigmodel.cn/api", init);
+		expect(await response.text()).toBe("original");
+		expect(h.originalCalls).toHaveLength(1);
+		expect(h.originalCalls[0]?.init).toBe(init);
+		expect(h.proxyCalls).toHaveLength(0);
+		expect(snapshotCounters().get("open.bigmodel.cn")).toEqual({ proxied: 0, direct: 1 });
+	});
+
+	it("noProxy 优先于 rules：同主机名两侧都出现时直连", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(
+			config({ noProxy: ["api.anthropic.com"], rules: ["api.anthropic.com"] }),
+			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("子域命中 + 点边界：子域走代理，前缀拼接不命中", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config({ noProxy: [], rules: ["api.anthropic.com"] }), null, h.deps);
+		await h.getCurrent()("https://eu.api.anthropic.com/v1");
+		await h.getCurrent()("https://xapi.anthropic.com/v1");
+		expect(h.proxyCalls).toHaveLength(1);
+		expect(h.originalCalls).toHaveLength(1);
+	});
+
+	it("入参形态：string / URL / Request 都能识别主机名", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config({ noProxy: [], rules: ["api.anthropic.com"] }), null, h.deps);
+		await h.getCurrent()("https://api.anthropic.com/a");
+		await h.getCurrent()(new URL("https://api.anthropic.com/b"));
+		await h.getCurrent()(new Request("https://api.anthropic.com/c"));
+		expect(h.proxyCalls).toHaveLength(3);
+		expect(snapshotCounters().get("api.anthropic.com")).toEqual({ proxied: 3, direct: 0 });
+	});
+
+	it("无法解析目标（相对 URL / 空 host）：原样放行且不计数", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config(), null, h.deps);
+		await h.getCurrent()("/relative/path");
+		await h.getCurrent()(new URL("file:///tmp/a"));
+		expect(h.originalCalls).toHaveLength(2);
+		expect(h.proxyCalls).toHaveLength(0);
+		expect(snapshotCounters().size).toBe(0);
+	});
+
+	it("指纹未变且包装仍在槽位：零动作（状态对象复用，不重建）", () => {
+		const h = createHarness();
+		const state = applyNetworkProxyConfig(config(), null, h.deps);
+		const again = applyNetworkProxyConfig(config(), state, h.deps);
+		expect(again).toBe(state);
+		expect(h.buildCalls).toHaveLength(1);
+	});
+
+	it("指纹变化：重建代理分发器并换新包装", async () => {
+		const h = createHarness();
+		const first = applyNetworkProxyConfig(config(), null, h.deps);
+		const second = applyNetworkProxyConfig(
+			config({ rules: ["api.openai.com"] }),
+			first,
+			h.deps,
+		);
+		expect(second?.wrapper).not.toBe(first?.wrapper);
+		expect(h.buildCalls).toHaveLength(2);
+		await h.getCurrent()("https://api.openai.com/v1");
+		expect(h.proxyCalls).toHaveLength(1);
+	});
+
+	it("槽位被外部覆盖（pi 重跑 configureHttpDispatcher → undici.install）：同指纹也以覆盖者为 original 重新包装", async () => {
+		const h = createHarness();
+		const first = applyNetworkProxyConfig(config(), null, h.deps);
+		// 模拟 pi 设置变更：globalThis.fetch 被 pi 原生实现整体替换，本扩展状态未感知
+		const piReinstalled: FetchLike = async () => new Response("pi-native");
+		h.setCurrent(piReinstalled);
+
+		const again = applyNetworkProxyConfig(config(), first, h.deps);
+		expect(again).not.toBe(first);
+		expect(again?.wrapper).not.toBeNull();
+		expect(h.getCurrent()).toBe(again?.wrapper);
+		// 未命中流量走覆盖者（pi 当前实现），不是旧 original
+		await h.getCurrent()("https://open.bigmodel.cn/api");
+		expect(h.originalCalls).toHaveLength(0);
+		// 命中流量仍走代理
+		await h.getCurrent()("https://api.anthropic.com/v1");
+		expect(h.proxyCalls).toHaveLength(1);
+	});
+
+	it("enabled true→false：恢复原 fetch + 状态清空", () => {
+		const h = createHarness();
+		const state = applyNetworkProxyConfig(config(), null, h.deps);
+		const after = applyNetworkProxyConfig(config({ enabled: false }), state, h.deps);
+		expect(after).toBeNull();
+		expect(h.getCurrent()).toBe(h.originalFetch);
+	});
+
+	it("首装即禁用：零动作", () => {
+		const h = createHarness();
+		expect(applyNetworkProxyConfig(config({ enabled: false }), null, h.deps)).toBeNull();
+		expect(h.buildCalls).toHaveLength(0);
+		expect(h.errors).toHaveLength(0);
+	});
+
+	it("构造失败：onError + 不包装（全直连），同指纹锁定不重试；指纹变化后重试", () => {
+		const h = createHarness();
+		h.setBuildProxy(() => {
+			throw new TypeError("this[kConnector] is not a function");
+		});
+		const locked = applyNetworkProxyConfig(config(), null, h.deps);
+		expect(locked?.wrapper).toBeNull();
+		expect(h.getCurrent()).toBe(h.originalFetch);
+		expect(h.errors).toHaveLength(1);
+		expect(h.errors[0]).toContain("构造失败");
+		expect(h.errors[0]).toContain("直连");
+
+		const stillLocked = applyNetworkProxyConfig(config(), locked, h.deps);
+		expect(stillLocked?.wrapper).toBeNull();
+		expect(h.buildCalls).toHaveLength(1); // 同指纹不重试
+
+		h.setBuildProxy(() => new FakeDispatcher());
+		const recovered = applyNetworkProxyConfig(config(withProxy({ port: 7891 })), stillLocked, h.deps);
+		expect(recovered?.wrapper).not.toBeNull();
+		expect(h.getCurrent()).toBe(recovered?.wrapper);
+	});
+
+	it("运行中重建遇构造失败：撤下旧包装恢复原 fetch，记指纹锁定", () => {
+		const h = createHarness();
+		const installed = applyNetworkProxyConfig(config(), null, h.deps);
+		h.setBuildProxy(() => {
+			throw new Error("socks5 experimental API changed");
+		});
+		const locked = applyNetworkProxyConfig(
+			config(withProxy({ protocol: "socks5" })),
+			installed,
+			h.deps,
+		);
+		expect(locked?.wrapper).toBeNull();
+		expect(h.getCurrent()).toBe(h.originalFetch);
+		expect(h.errors[0]).toContain("socks5");
+	});
+
+	it("锁定态再遇禁用：状态清空、零槽位操作", () => {
+		const h = createHarness();
+		h.setBuildProxy(() => {
+			throw new Error("boom");
+		});
+		const locked = applyNetworkProxyConfig(config(), null, h.deps);
+		const after = applyNetworkProxyConfig(config({ enabled: false }), locked, h.deps);
+		expect(after).toBeNull();
+		expect(h.getCurrent()).toBe(h.originalFetch);
+	});
+});
+
+describe("detachResidualFetchWrapper（reload 残留摘除）", () => {
+	it("installed=null 且槽上是本扩展旧包装：恢复其 original fetch", () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config(), null, h.deps);
+		expect(h.getCurrent()).not.toBe(h.originalFetch);
+
+		// 模拟 reload 后新模块环境：installed=null，槽上仍是旧环境包装
+		detachResidualFetchWrapper(null, h.deps);
+		expect(h.getCurrent()).toBe(h.originalFetch);
+	});
+
+	it("installed=null 且槽上是非本扩展函数：零动作", () => {
+		const h = createHarness();
+		const foreignFetch: FetchLike = async () => new Response("foreign");
+		h.setCurrent(foreignFetch);
+		detachResidualFetchWrapper(null, h.deps);
+		expect(h.getCurrent()).toBe(foreignFetch);
+	});
+
+	it("installed 非 null（同环境 factory 重跑）：早退，不误摘当前包装", () => {
+		const h = createHarness();
+		const state = applyNetworkProxyConfig(config(), null, h.deps);
+		detachResidualFetchWrapper(state, h.deps);
+		expect(h.getCurrent()).toBe(state?.wrapper);
+	});
+
+	it("reload 后重新推进：摘除旧包装后再包新层（不嵌套双计）", async () => {
+		const h = createHarness();
+		applyNetworkProxyConfig(config(), null, h.deps);
+		detachResidualFetchWrapper(null, h.deps);
+		const state = applyNetworkProxyConfig(config(), null, h.deps);
+		expect(state?.originalFetch).toBe(h.originalFetch);
+		await h.getCurrent()("https://api.anthropic.com/v1");
+		expect(h.proxyCalls).toHaveLength(1);
+		expect(snapshotCounters().get("api.anthropic.com")).toEqual({ proxied: 1, direct: 0 });
+	});
+});

package/src/__tests__/index.test.ts

@@ -0,0 +1,182 @@
+/**
+ * extension 入口行为单测（真实组件 + tmp agentDir，不 mock 配置读取链）：
+ * 工厂加载序列（校验过 → 包装 globalThis.fetch / 非法 → error + 全直连）、turn 粒度热生效
+ * （turn_start 重读配置、turn_end flush 计数）。vi.resetModules 隔离模块级 installed 状态。
+ * fs-guard 白名单：写入目标 = PI_CODING_AGENT_DIR 注入的 mkdtemp tmp 目录。
+ */
+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";
+
+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(),
+}));
+
+/** fake pi ExtensionAPI：收集 on 注册的 handler，emit 触发。 */
+function createFakePi() {
+	const handlers = new Map<string, Array<() => void>>();
+	const pi = {
+		on: (event: string, handler: () => void) => {
+			const list = handlers.get(event) ?? [];
+			list.push(handler);
+			handlers.set(event, list);
+		},
+	} as unknown as import("@earendil-works/pi-coding-agent").ExtensionAPI;
+	return {
+		pi,
+		emit: (event: "turn_start" | "turn_end") => {
+			for (const h of handlers.get(event) ?? []) h();
+		},
+	};
+}
+
+const ENABLED_CONFIG = {
+	enabled: true,
+	proxy: { protocol: "http", host: "127.0.0.1", port: 7890, username: "", password: "" },
+	noProxy: ["localhost"],
+	rules: ["api.anthropic.com"],
+};
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+let agentDir: string;
+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);
+}
+
+beforeEach(() => {
+	agentDir = mkdtempSync(join(tmpdir(), "network-proxy-index-"));
+	vi.stubEnv("PI_CODING_AGENT_DIR", agentDir);
+	savedFetch = globalThis.fetch;
+	fakeCalls = 0;
+	fakeFetch = async () => {
+		fakeCalls += 1;
+		return new Response("fake-original");
+	};
+	globalThis.fetch = fakeFetch;
+	loggerMock.error.mockClear();
+});
+
+afterEach(() => {
+	globalThis.fetch = savedFetch;
+	vi.unstubAllEnvs();
+	vi.resetModules();
+});
+
+describe("networkProxyExtension 工厂加载序列", () => {
+	it("enabled 且校验过：包装 globalThis.fetch（未命中规则时委托 fake 原 fetch）", async () => {
+		writeConfigFile(JSON.stringify(ENABLED_CONFIG));
+		const { default: networkProxyExtension } = await import("../index.ts");
+		networkProxyExtension(createFakePi().pi);
+		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：不包装（globalThis.fetch 保持原实现），零 error", async () => {
+		writeConfigFile(JSON.stringify({ ...ENABLED_CONFIG, enabled: false }));
+		const { default: networkProxyExtension } = await import("../index.ts");
+		networkProxyExtension(createFakePi().pi);
+		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(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(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 = globalThis.fetch;
+
+		// 未变配置：同包装函数（不重建）
+		emit("turn_start");
+		expect(globalThis.fetch).toBe(first);
+
+		// 改写配置（size 变化 → mtime+size 缓存失效）：指纹变化换新包装
+		writeConfigFile(JSON.stringify({ ...ENABLED_CONFIG, rules: ["api.openai.com"] }));
+		emit("turn_start");
+		expect(globalThis.fetch).not.toBe(first);
+	});
+
+	it("pi 重装 globalThis.fetch（configureHttpDispatcher）后 turn_start 重新包装覆盖者", async () => {
+		writeConfigFile(JSON.stringify(ENABLED_CONFIG));
+		const { default: networkProxyExtension } = await import("../index.ts");
+		const { pi, emit } = createFakePi();
+		networkProxyExtension(pi);
+
+		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");
+		// resetModules 后 index.ts 与此处 import 的 stats.ts 是同一模块图刷新的同一实例
+		const { recordDispatch, statsFilePath } = await import("../stats.ts");
+		const { pi, emit } = createFakePi();
+		networkProxyExtension(pi);
+
+		recordDispatch("api.anthropic.com", true);
+		recordDispatch("open.bigmodel.cn", false);
+		emit("turn_end");
+
+		const lines = readFileSync(statsFilePath(), "utf-8").split("\n").filter((l) => l !== "");
+		expect(lines).toHaveLength(2);
+		const hosts = lines.map((l) => (JSON.parse(l) as { host: string }).host).sort();
+		expect(hosts).toEqual(["api.anthropic.com", "open.bigmodel.cn"]);
+	});
+
+	it("enabled true→false：turn_start 后恢复原 fetch（禁用生效）", async () => {
+		writeConfigFile(JSON.stringify(ENABLED_CONFIG));
+		const { default: networkProxyExtension } = await import("../index.ts");
+		const { pi, emit } = createFakePi();
+		networkProxyExtension(pi);
+		expect(globalThis.fetch).not.toBe(fakeFetch);
+
+		writeConfigFile(JSON.stringify({ ...ENABLED_CONFIG, enabled: false }));
+		emit("turn_start");
+		expect(globalThis.fetch).toBe(fakeFetch);
+	});
+});

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);
+	});
+});