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

package/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * @zhushanwen/pi-network-proxy 入口：配置驱动的 undici 全局分流分发器安装与事件接线。
+ *
+ * 行为序列（设计 .tmp/tech-design/llm-network-proxy.md §3.1）：
+ * - 加载时：读配置校验，enabled 且校验过 → 捕获原分发器（pi 启动已自装 EnvHttpProxyAgent，
+ *   setGlobalDispatcher 是接管而非向空闲槽安装——pi dist/core/http-dispatcher.js:73 构造、
+ *   :85 装入全局槽，首次安装 dist/main.js:468 早于 extension 加载）→ 构造分流器安装；
+ *   校验失败 / 构造失败 →
+ *   extension error（文案含恢复动作：配置文件路径），不安装不阻断 pi（全部直连）。
+ * - 每 turn 开始：重读配置（llm-shared 读时刷新热重载），指纹变化才重建；enabled true→false
+ *   恢复原分发器（installer.ts 状态机）。
+ * - 每 turn 结束：计数增量 flush 追加写入 stats JSONL（stats.ts）；进程退出兜底 flush。
+ *
+ * 覆盖面含 subagent 的 pi 进程（subagent 的 LLM 请求同样分流计数，设计前提 P4）——不设
+ * subagent 排除门。配置写入侧 = taiji runtime RMW（settings 页 RPC）或 pi CLI 用户手编。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getGlobalDispatcher, setGlobalDispatcher } from "undici";
+
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
+import { getConfigPath } from "@zhushanwen/pi-llm-shared";
+
+import { loadNetworkProxyConfig } from "./config.js";
+import { buildProxyDispatcher } from "./dispatcher.js";
+import {
+	applyNetworkProxyConfig,
+	detachResidualDispatcher,
+	type InstalledState,
+} from "./installer.js";
+import { ensureExitFlush, flushStats } from "./stats.js";
+
+const logger = getLogger("network-proxy");
+
+/** 进程级安装状态（模块级——全局分发器槽跨 session 存续，session 替换重跑 factory 不丢引用）。 */
+let installed: InstalledState | null = null;
+
+/** 恢复动作文案：所有 error 形态共用的收尾指引（指向配置文件）。 */
+function recoveryHint(): string {
+	return `配置文件: ${getConfigPath("network-proxy")}，修正该文件后自下一轮对话起生效，或删除该文件恢复默认禁用态。`;
+}
+
+/** 读配置并推进安装状态机（加载时与每 turn 开始共用同一入口）；推进前先摘除 reload 残留。 */
+function refreshFromConfig(): void {
+	const config = loadNetworkProxyConfig((warning) => {
+		// 非法配置 / 坏 JSON：loadConfig 已回落 defaults（enabled=false → 不安装，全部直连），
+		// 这里把具体错误记录到 extension 日志通道（appendEntry 持久化 + <agentDir>/logs/
+		// network-proxy-<day>.log 文件日志；验收场景 10 以文件日志为归因口径）。
+		logger.error(`${warning} ${recoveryHint()}`);
+	});
+	try {
+		detachResidualDispatcher(installed, { getGlobalDispatcher, setGlobalDispatcher });
+		installed = applyNetworkProxyConfig(config, installed, {
+			getGlobalDispatcher,
+			setGlobalDispatcher,
+			buildProxy: buildProxyDispatcher,
+			onError: (message) => logger.error(`${message} ${recoveryHint()}`),
+		});
+	} catch (error) {
+		// 辅助功能降级契约（本扩展为 P2 辅助功能，故障不得拖垮 pi 主流程）：状态机推进的
+		// 意外异常不外抛——外抛会升为 pi 用户可见 extension error 且每 turn 重复出现；
+		// 此处保持未安装态（全部直连），错误归因到本扩展日志。
+		logger.error(`network-proxy installer failed: ${toErrorMessage(error)} ${recoveryHint()}`);
+		installed = null;
+	}
+}
+
+/** pi-network-proxy extension 工厂函数。 */
+export default function networkProxyExtension(pi: ExtensionAPI): void {
+	// 日志通道注入（extension-logger 两阶段初始化：工厂拿 pi → setPiHandle，最早期调用）。
+	setPiHandle(pi);
+
+	ensureExitFlush();
+	refreshFromConfig();
+
+	// turn 粒度热生效：turn 开始重读配置（mtime+size 未变时零 IO），指纹变化重建 / 禁用恢复。
+	pi.on("turn_start", () => {
+		refreshFromConfig();
+	});
+
+	// turn 结束 flush 计数增量（单行 JSONL 追加，写失败 log 不阻断）。
+	pi.on("turn_end", () => {
+		flushStats();
+	});
+}

package/src/installer.ts

@@ -0,0 +1,165 @@
+/**
+ * 分流器安装状态机（设计 §3.1 行为序列 1/2 + §3.3 决策 5/8）。
+ *
+ * 进程级单一安装状态（全局分发器槽是进程级资源，状态必须模块级持有——session 替换重跑
+ * factory 时不因闭包重建丢失 originalDispatcher 引用）。转移表：
+ *
+ * | 当前态           | 事件（新配置）      | 动作                                   | 次态 |
+ * |-----------------|--------------------|----------------------------------------|------|
+ * | 任意            | enabled=false      | 槽上仍是分流器则恢复 original（仅限槽位归属核查通过） | null |
+ * | null            | enabled+新指纹     | 捕获 original → 构造 → 安装             | 装载 |
+ * | 装载            | enabled+同指纹+槽位仍归本扩展 | 无动作（不重建不重复安装）        | 装载 |
+ * | 装载            | enabled+同指纹+槽位被外部覆盖 | 撤旧装新（pi 启动重装覆盖形态，original=覆盖者） | 装载 |
+ * | 锁定            | enabled+同指纹     | 无动作（首败即停不重试）                 | 锁定 |
+ * | 任意            | enabled+新指纹     | 构造成功 → 撤旧装新                     | 装载 |
+ * | 任意            | enabled+构造失败   | error 上报 + 撤旧（全部直连），记指纹锁定 | 锁定 |
+ *
+ * 锁定态（current=null）：同指纹不重试构造（fail-fast 首败即停，AGENTS.md 事实驱动原则⑧）；
+ * 用户修正配置 → 指纹变化 → 自然重试。依赖注入（get/setGlobalDispatcher、buildProxy、
+ * onError）使状态机在单测中以 fake 依赖驱动，不 mock undici 全局槽。
+ *
+ * 状态机前置伴随入口 = detachResidualDispatcher：jiti 全量 reload 后 installed=null 但槽上
+ * 仍挂着旧环境残留分流器，状态机自身无法区分「真无状态」与「reload 残留」，由它在推进前
+ * 摘除（转移表各分支才从干净基线成立；pi reload 链实装锚点见该函数注释）。
+ */
+
+import type { Dispatcher as IDispatcher } from "undici";
+
+import { networkProxyFingerprint, type NetworkProxyConfig } from "./config.js";
+import { isRuleDispatchDispatcher, RuleDispatchDispatcher } from "./dispatcher.js";
+import { recordDispatch } from "./stats.js";
+
+/** 当前安装状态；null = 未安装（槽上是 pi 原生分发器）。 */
+export interface InstalledState { // oe-exempt:20261019:framework:安装状态机载体形状（状态机唯一状态类型，单实现为常态）
+
+	/** 安装前捕获的原分发器引用（首次捕获后跨重建保留——恢复与 fallback 都用它）。 */
+	originalDispatcher: IDispatcher;
+	/** 已安装（或已锁定失败）配置的指纹。 */
+	fingerprint: string;
+	/** 槽上的分流器；null = 构造失败锁定态（未安装）。 */
+	current: IDispatcher | null;
+}
+
+export interface InstallerDeps { // oe-exempt:20261019:framework:安装状态机依赖注入接缝（单测注入 get/setGlobalDispatcher 与可抛 buildProxy）
+
+	getGlobalDispatcher: () => IDispatcher;
+	setGlobalDispatcher: (dispatcher: IDispatcher) => void;
+	/** 代理分发器构造（可注入抛错——「构造失败 → 不安装 → 全直连」单测入口）。 */
+	buildProxy: (config: NetworkProxyConfig) => IDispatcher;
+	/** extension error 呈现（logger.error；文案含恢复动作）。 */
+	onError: (message: string) => void;
+}
+
+/**
+ * reload 残留摘除（设计 §3.1 行为序列 2 在 reload 窗口的兑现）：jiti 全量 reload 后本扩展
+ * 换了新模块环境，installed=null 但全局槽仍挂着旧环境安装的 RuleDispatchDispatcher——
+ * 不摘除则 enabled=false 状态机判「无状态」零动作（旧分流器继续生效，禁用失效），或
+ * enabled=true 时旧分流器被捕获为 original 嵌套（同一请求经新旧两层各计一次，统计双计）。
+ * 摘除 = 恢复残留分流器安装时捕获的原分发器（fallback 引用），状态机从干净基线推进。
+ * installed 非 null（同环境 factory 重跑）早退：槽上就是 state.current，摘掉会与
+ * 「指纹未变无动作」分支冲突（分流器被摘而状态机不重装）。
+ *
+ * pi reload 链实装锚点（@earendil-works/pi-coding-agent 1.0.0 dist，逐文件读码核实）：
+ * agent-session.js:2899 reload() → :2903 oldRunner.invalidate()（extensions/loader.js:141-149
+ * 退订旧 runtime 的全部 eventBus 订阅）→ :2908 resourceLoader.reload()（resource-loader.js:350，
+ * :353 clearExtensionCache() 清空 jiti 模块缓存并递增缓存代际）→ loader.js:456-484 缓存代际
+ * 失效后 :472-476 新建 jiti 实例（moduleCache: false）重新 import 本扩展、:505-509 重跑工厂
+ * ——新环境模块级 installed 重置为 null，旧环境分流器滞留全局槽无人恢复，即本函数的前提。
+ */
+export function detachResidualDispatcher(
+	installed: InstalledState | null,
+	deps: Pick<InstallerDeps, "getGlobalDispatcher" | "setGlobalDispatcher">,
+): void {
+	if (installed !== null) return;
+	const current = deps.getGlobalDispatcher();
+	if (!isRuleDispatchDispatcher(current)) return;
+	deps.setGlobalDispatcher(current.fallback);
+}
+
+/**
+ * 禁用态收口（转移表首行）：恢复仅限槽位仍归本扩展时执行——槽位已被外部覆盖（pi 启动重装，
+ * 见下）时槽上已是 pi 原生分发器，回写 state.originalDispatcher 会把它挤掉（无害但多余），
+ * 语义上禁用 = 摘除自己的安装，不是改写别人的。
+ */
+function restoreOriginalIfOwned(
+	state: InstalledState | null,
+	deps: Pick<InstallerDeps, "getGlobalDispatcher" | "setGlobalDispatcher">,
+): void {
+	if (state?.current && deps.getGlobalDispatcher() === state.current) {
+		deps.setGlobalDispatcher(state.originalDispatcher);
+	}
+}
+
+/**
+ * 槽位归属核查（pi 启动时序缺陷的根因修复）：pi 1.0.0 启动序列在 extension 安装之后
+ * 仍会重跑 configureHttpDispatcher() 整槽覆盖（dist main.js:707 实证）——指纹未变但槽上
+ * 已非本扩展分发器时按「撤旧装新」重装。original 统一取槽上现持有者：覆盖场景下
+ * state.originalDispatcher 是上一代 pi 原生分发器，fallback 必须指向当前覆盖者才是
+ * 「未命中委托 = 未安装本扩展时 pi 的确切行为」。
+ */
+function resolveOriginal(state: InstalledState | null, slotNow: IDispatcher): IDispatcher {
+	return state && state.current !== null && slotNow === state.current
+		? state.originalDispatcher
+		: slotNow;
+}
+
+/** 构造失败收口（转移表末行）：error 上报 + 撤旧（全部直连），返回记指纹的锁定态。 */
+function lockOnBuildFailure(
+	config: NetworkProxyConfig,
+	state: InstalledState | null,
+	original: IDispatcher,
+	fingerprint: string,
+	deps: InstallerDeps,
+	error: unknown,
+): InstalledState {
+	deps.onError(
+		`网络代理分流器构造失败（协议 ${config.proxy.protocol}），已保持全部直连，不影响 pi 运行；` +
+			`可核对代理配置后保存重试，或关闭网络代理开关。构造错误: ${error instanceof Error ? error.message : String(error)}`,
+	);
+	if (state?.current) {
+		deps.setGlobalDispatcher(original);
+	}
+	return { originalDispatcher: original, fingerprint, current: null };
+}
+
+/**
+ * 按新配置推进安装状态机（见模块头转移表）。config 契约 = loadNetworkProxyConfig 产物
+ * （normalize 已校验合法——非法配置在读取层回落 defaults+error，构造性到达本函数恒合法）。
+ */
+export function applyNetworkProxyConfig(
+	config: NetworkProxyConfig,
+	state: InstalledState | null,
+	deps: InstallerDeps,
+): InstalledState | null {
+	if (!config.enabled) {
+		restoreOriginalIfOwned(state, deps);
+		return null;
+	}
+
+	const fingerprint = networkProxyFingerprint(config);
+	if (state && state.fingerprint === fingerprint && state.current === null) {
+		return state; // 锁定态：同指纹不重试构造（首败即停，决策 8）
+	}
+	const slotNow = deps.getGlobalDispatcher();
+	if (state && state.fingerprint === fingerprint && slotNow === state.current) {
+		return state; // 同指纹且槽位仍归本扩展：无动作（不重建不重复安装）
+	}
+	const original = resolveOriginal(state, slotNow);
+
+	let proxy: IDispatcher;
+	try {
+		proxy = deps.buildProxy(config);
+	} catch (error) {
+		return lockOnBuildFailure(config, state, original, fingerprint, deps, error);
+	}
+
+	const dispatcher = new RuleDispatchDispatcher({
+		fallback: original,
+		proxy,
+		noProxy: config.noProxy,
+		rules: config.rules,
+		onCount: recordDispatch,
+	});
+	deps.setGlobalDispatcher(dispatcher);
+	return { originalDispatcher: original, fingerprint, current: dispatcher };
+}

package/src/match.ts

@@ -0,0 +1,33 @@
+/**
+ * 主机名匹配语义（normalizeHostname + suffix 点边界）。
+ *
+ * 语义 SSOT = packages/shared/src/network-proxy.ts 的同名函数——extension bundle 自包含
+ * 不 import shared 运行时代码（extensions 对 shared 的既有惯例：结构类型本地声明 + 行为
+ * 真值表镜像锁定，见 rename-session RENAME_INSTRUCTION_MAX_LENGTH 先例），本文件是复制体；
+ * 漂移时以 shared 为准，__tests__/match.test.ts 的真值表锁两侧行为一致。
+ *
+ * 匹配语义（设计 .tmp/tech-design/llm-network-proxy.md §3.1 配置 schema）：
+ * suffix = 主机名等于或以 `.pattern` 结尾；点边界必须对齐——`xapi.anthropic.com` 不命中
+ * `api.anthropic.com`（无点前缀拼接），`api-anthropic.com.evil.com` 不命中（恶意后缀）。
+ */
+
+/**
+ * 主机名归一化：转小写、去末尾点（FQDN 根点形态与裸主机名同义）。
+ * 刻意不 trim 首尾空白（语义镜像 shared normalizeHostname）：带空白的条目由校验层
+ * 显式拒绝（config.ts collectHostEntryErrors，失败显式上报优于静默容忍），
+ * 匹配层保持严格、带空白 pattern 恒不命中。
+ */
+export function normalizeHostname(host: string): string {
+	return host.toLowerCase().replace(/\.+$/, "");
+}
+
+/**
+ * suffix 语义匹配（noProxy 与 rules 条目同一匹配函数）：
+ * 主机名等于 pattern 或以 `.pattern` 结尾。空主机名 / 空 pattern 不命中任何条目。
+ */
+export function matchesHostPattern(host: string, pattern: string): boolean {
+	const h = normalizeHostname(host);
+	const p = normalizeHostname(pattern);
+	if (h === "" || p === "") return false;
+	return h === p || h.endsWith(`.${p}`);
+}

package/src/stats.ts

@@ -0,0 +1,127 @@
+/**
+ * 请求计数与落盘（设计 .tmp/tech-design/llm-network-proxy.md §3.1 行为序列 4 + §3.3 决策 4）。
+ *
+ * 形态 = 进程内内存增量计数 + turn_end / 进程退出时追加式 JSONL flush：
+ * - 计数按主机名聚合，进程级（分流分发器是全局槽资源，与 session 无关）；
+ * - 每行一个完整 JSON 片段 `{ ts, host, proxied, direct }`，ts = flush 时刻——增量行代表
+ *   「自上次 flush 以来的计数」，跨统计范围边界的微小归属偏差可接受（观测辅助非计费依据）；
+ * - 落点 `<getAgentDir()>/network-proxy-stats.jsonl`（agentDir 根，与 runtime 读侧
+ *   getPiAgentDir() 单一推导同源）；runtime 侧负责聚合与重置水位/截断，本侧纯追加；
+ * - 单行 = 单次 appendFileSync 调用（O_APPEND 单次 write，行内容完整 JSON——并发原子性
+ *   前提，多 pi 进程并发追加不交错；实现改为分片 write 会静默交错，单测锁定）；
+ * - 写失败 log 不阻断：失败行的增量保留在内存，下次 turn_end flush 重试（统计宁重试不丢，
+ *   连续失败不逐行刷 warn）。
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { withFileLockSync } from "@zhushanwen/pi-file-lock";
+
+const logger = getLogger("network-proxy");
+
+interface HostCounter { // oe-exempt:20261019:framework:进程内计数行形状（Map 值类型，聚合输出 NetworkProxyStats 的内存态）
+
+	proxied: number;
+	direct: number;
+}
+
+/** 进程内增量计数：host → 自上次 flush 以来的次数。 */
+const counters = new Map<string, HostCounter>();
+
+/** stats 文件完整路径（每次现算——getAgentDir 尊重 PI_CODING_AGENT_DIR，测试注入 tmp）。 */
+export function statsFilePath(): string {
+	return join(getAgentDir(), "network-proxy-stats.jsonl");
+}
+
+/** dispatch 拦截点的计数回调（请求发起时点）。 */
+export function recordDispatch(host: string, proxied: boolean): void {
+	const entry = counters.get(host) ?? { proxied: 0, direct: 0 };
+	if (proxied) {
+		entry.proxied += 1;
+	} else {
+		entry.direct += 1;
+	}
+	counters.set(host, entry);
+}
+
+/** 测试用：清空内存增量（不落盘）。 */
+export function resetCounters(): void {
+	counters.clear();
+}
+
+/** 测试用：当前增量快照（只读拷贝）。 */
+export function snapshotCounters(): Map<string, HostCounter> {
+	return new Map([...counters].map(([host, c]) => [host, { ...c }]));
+}
+
+let exitFlushInstalled = false;
+
+/**
+ * 进程退出 flush（turn 进行中被退出时 turn_end 未到，增量在此兜住）。exit handler 内只允许
+ * 同步操作——appendFileSync 同步写满足；模块级 once flag 防工厂重跑（多 session）重复注册。
+ * jiti 全量 reload 产生的新模块环境会再注册一个 listener，但旧环境的计数 Map 已停更，旧
+ * listener flush 空增量为 no-op，无重复行（新环境再注册 = extensions/loader.js:472-476 重新
+ * import 重置模块级 once flag 后重跑工厂；旧计数停更 = 旧 runtime 的 turn 订阅被 invalidate
+ * 退订（extensions/loader.js:147-149）+ 旧分流器摘除后旧 recordDispatch 不再触发；pi reload
+ * 链总锚点见 installer.ts detachResidualDispatcher 注释）。
+ */
+export function ensureExitFlush(): void {
+	if (exitFlushInstalled) return;
+	exitFlushInstalled = true;
+	process.on("exit", () => {
+		try {
+			flushStats();
+		} catch (error) {
+			// flushStats 内部已逐行 try/catch + warn——能到这里的外层抛错只有 mkdir/logger 自身
+			// 故障；exit 通道内不能阻断退出，留文件日志痕即可。
+			logger.error(`exit flush failed: ${toErrorMessage(error)}`);
+		}
+	});
+}
+
+/**
+ * 把内存增量逐行追加写入 stats 文件；写成功的条目从内存清零，失败条目保留待下次重试。
+ * 增量为空时零 IO 直接返回（turn_end 空转不碰磁盘）。
+ * 持与 runtime 截断/重置同一把 <stats> 跨进程文件锁（设计 §3.1「截断不丢在途增量」）：
+ * runtime 保尾截断临界区内并发追加的行会被 rename 整文件替换吞掉，无锁单侧互斥不成立。
+ * ts = epoch ms（Date.now()，与 runtime 读侧 parseStatsLine number 契约、reset 水位行
+ * 及读侧时间范围过滤一致；ISO 字符串形态产生的行会被读侧判坏行丢弃）。
+ */
+export function flushStats(): void {
+	if (counters.size === 0) return;
+	const ts = Date.now();
+	const filePath = statsFilePath();
+	try {
+		withFileLockSync(filePath, () => {
+			try {
+				mkdirSync(dirname(filePath), { recursive: true });
+			} catch (error) {
+				logger.warn("stats mkdir failed, keeping counters for retry", {
+					detail: { err: toErrorMessage(error) },
+				});
+				return;
+			}
+			for (const [host, counter] of counters) {
+				// 单次 appendFileSync 调用写一行完整 JSON——并发原子性前提，禁止分片 write
+				const line = `${JSON.stringify({ ts, host, proxied: counter.proxied, direct: counter.direct })}\n`;
+				try {
+					appendFileSync(filePath, line);
+					counters.delete(host);
+				} catch (error) {
+					logger.warn("stats flush failed, keeping counters for retry", {
+						detail: { err: toErrorMessage(error), path: filePath },
+					});
+					return;
+				}
+			}
+		}, {});
+	} catch (error) {
+		logger.warn("stats flush lock failed, keeping counters for retry", {
+			detail: { err: toErrorMessage(error), path: filePath },
+		});
+	}
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { taijiTestConfig } from "../../../test-guard/factory.ts"
+
+export default taijiTestConfig({
+  test: {
+    include: ["src/__tests__/**/*.test.ts"],
+  },
+});