@lyogvce/dsh-codex-subscription 0.2.3 → 0.2.5

package/README.md

@@ -11,8 +11,10 @@
 1. **与本机 Codex CLI / Desktop 100% 共享登录态**
    - 直接读取 `$CODEX_HOME/auth.json`（默认 `~/.codex/auth.json`）。
    - 每次请求前检查 `access_token` 的 JWT `exp`：距离过期不足 5 分钟时自动通过单飞锁（Single-flight）向 `https://auth.openai.com/oauth/token` 刷新，并通过 `realpathSync` + 临时文件 `rename` 原子写回 `auth.json`，保证与 Codex CLI 永不互踢下线。
-2. **零网络轮询的本地模型目录发现**
-   - 直接读取 `~/.codex/models_cache.json`（按文件 `mtime` 与大小自动感知更新），提取 `visibility === "list"` 的模型及其 `context_window`、`supported_reasoning_levels`（自动将 `ultra` 映射为 DSH 的 `max` 档位）与 `default_verbosity`。
+2. **零网络轮询的本地模型目录发现、防降级保护与可观测性日志**
+   - 直接读取 `~/.codex/models_cache.json`（每次按文件 `mtime` 与大小做微秒级 `stat` 校验，仅在文件变化时重读解析），提取 `visibility === "list"` 的模型及其 `context_window`、`supported_reasoning_levels`（自动将 `ultra` 映射为 DSH 的 `max` 档位）与 `default_verbosity`。
+   - **防旧版客户端降级污染**：自动将高版本 `models_cache.json` 备份至 `~/.codex/.dsh-models-cache-backup.json`；当外部旧版进程（如 `dsh-subagent-codex` 内置的 `0.153.4`）将 `models_cache.json` 降级覆写为不含新模型的旧缓存时，自动拦截降级并保留高版本模型目录。
+   - **可观测性日志**：自动在 `~/.codex/dsh-codex-subscription.log`（带 512KB 自动滚动截断）记录目录加载（`catalog.load` / `catalog.snapshot`）、降级拦截（`catalog.downgrade_rejected`）、备份恢复（`catalog.backup_restored`）与凭证续期（`auth.refreshed`）事件。
 3. **支持按配置屏蔽模型（`disabledModels`）与自定义上下文窗口（`contextWindows`）**
    - 在插件配置中通过 `disabledModels` 屏蔽指定模型 `slug`，保持模型选择器干净清爽。
    - 通过 `contextWindows` 按模型 `slug` 自定义向 DSH 会话与自动压缩器暴露的预算窗口（例如设为 `400000`）；未配置时默认使用模型物理上限 `max_context_window`（`872000`）。同时底层 `PiCodexModel.contextWindow` 始终保持物理上限 `872000`，彻底防止 `dsh-llm-pi-ai` 在预算窗口与物理上限之间误判 `CONTEXT_WINDOW_EXCEEDED`。

package/lib/index.d.ts

@@ -1,4 +1,27 @@
 import { PiCodexModel } from "@earendil-works/pi-ai/providers/openai-codex";
+//#region src/host-types.d.ts
+interface LlmServiceLike {
+  registerAdapter: (providers: string[], adapter: unknown) => (() => void) & {
+    replace?: (next: string[]) => void;
+  };
+  emitAdaptersUpdated?: () => void;
+}
+type PluginLogLevel = 'INFO' | 'WARN' | 'ERROR';
+type PluginLogFn = (level: PluginLogLevel, event: string, detail: Record<string, unknown>) => void;
+interface LoggerLike {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+  error?: (message: string) => void;
+}
+interface PluginContextLike {
+  llm: LlmServiceLike;
+  logger?: LoggerLike | undefined;
+  get?: (name: string) => unknown;
+  on?: (event: string, listener: () => void) => () => void;
+  effect?: (factory: () => void | (() => void), label?: string) => () => void;
+  inject?: (services: readonly string[], callback: (ctx: PluginContextLike) => void) => () => void;
+}
+//#endregion
 //#region src/auth.d.ts
 interface CodexAuthTokens {
   access_token?: string;
@@ -19,6 +42,7 @@ interface JwtClaims {
 interface AuthManagerOptions {
   getCodexHome: () => string;
   getClientVersion?: (() => string) | undefined;
+  onLog?: PluginLogFn | undefined;
   fetchImpl?: typeof fetch | undefined;
   now?: (() => number) | undefined;
 }
@@ -35,6 +59,7 @@ declare function createAuthManager(options: AuthManagerOptions): {
 };
 //#endregion
 //#region src/catalog.d.ts
+export declare const BACKUP_CACHE_FILE_NAME = ".dsh-models-cache-backup.json";
 interface RawReasoningLevel {
   effort?: string;
   description?: string;
@@ -54,9 +79,12 @@ interface RawCodexModelEntry {
   default_verbosity?: string;
 }
 interface RawModelsCache {
+  fetched_at?: string;
   client_version?: string;
   models?: RawCodexModelEntry[];
 }
+declare function parseRawModelsCache(rawText: string): RawModelsCache;
+declare function compareClientVersions(a: string | undefined, b: string | undefined): number;
 interface CodexModelMetadata {
   readonly contextWindow: number;
   readonly supportVerbosity: boolean;
@@ -112,24 +140,10 @@ declare function createUsageFetcher(options: UsageFetcherOptions): {
   invalidate: () => void;
 };
 //#endregion
-//#region src/host-types.d.ts
-interface LlmServiceLike {
-  registerAdapter: (providers: string[], adapter: unknown) => (() => void) & {
-    replace?: (next: string[]) => void;
-  };
-  emitAdaptersUpdated?: () => void;
-}
-interface PluginContextLike {
-  llm: LlmServiceLike;
-  get?: (name: string) => unknown;
-  on?: (event: string, listener: () => void) => () => void;
-  effect?: (factory: () => void | (() => void), label?: string) => () => void;
-  inject?: (services: readonly string[], callback: (ctx: PluginContextLike) => void) => () => void;
-}
-//#endregion
 //#region src/index.d.ts
 export declare const name = "codex-subscription";
 export declare const inject: string[];
+export declare const LOG_FILE_NAME = "dsh-codex-subscription.log";
 export declare const Config: any;
 export declare function apply(ctx: PluginContextLike, config?: Record<string, unknown>): void;
 export declare const __test: Readonly<{
@@ -146,7 +160,9 @@ export declare const __test: Readonly<{
   safeErrorMessage: typeof safeErrorMessage;
   createAuthManager: typeof createAuthManager;
   buildThinkingLevelMap: typeof buildThinkingLevelMap;
+  compareClientVersions: typeof compareClientVersions;
   parseModelsCache: typeof parseModelsCache;
+  parseRawModelsCache: typeof parseRawModelsCache;
   sanitizeCodexPayload: typeof sanitizeCodexPayload;
   buildCodexHeaders: typeof buildCodexHeaders;
   buildCodexUserAgent: typeof buildCodexUserAgent;
@@ -155,4 +171,4 @@ export declare const __test: Readonly<{
   createUsageFetcher: typeof createUsageFetcher;
 }>;
 //#endregion
-export type { CodexModelMetadata, CodexQuotaResponse, CodexQuotaSnapshot, CodexQuotaWindow, CodexResolvedCredentials, ParsedModelsCatalog, PluginContextLike, RawModelsCache };
+export type { CodexModelMetadata, CodexQuotaResponse, CodexQuotaSnapshot, CodexQuotaWindow, CodexResolvedCredentials, ParsedModelsCatalog, PluginContextLike, PluginLogLevel, RawModelsCache };

package/lib/index.js

@@ -1,5 +1,5 @@
-import { chmodSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { appendFileSync, chmodSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { LlmError, resolveImageAttachmentAccess, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
@@ -13,6 +13,7 @@ const PROVIDER = "openai-codex";
 const DISPLAY_NAME = "Codex";
 const DEFAULT_CLIENT_VERSION = "0.163.0";
 const DEFAULT_CONTEXT_WINDOW = 872e3;
+const BACKUP_CACHE_FILE_NAME = ".dsh-models-cache-backup.json";
 const THINKING_LEVELS = [
 	"off",
 	"minimal",
@@ -29,6 +30,23 @@ const DEFAULT_DISABLED_MODELS = Object.freeze([
 	"gpt-5.6-terra",
 	"gpt-5.6-luna"
 ]);
+function parseRawModelsCache(rawText) {
+	const parsed = JSON.parse(rawText);
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new SyntaxError("models_cache.json root must be a JSON object");
+	return parsed;
+}
+function compareClientVersions(a, b) {
+	const parseParts = (ver) => typeof ver === "string" && ver.trim() !== "" ? ver.trim().split(/[^0-9]+/u).filter(Boolean).map((n) => Number.parseInt(n, 10)) : [];
+	const pa = parseParts(a);
+	const pb = parseParts(b);
+	const len = Math.max(pa.length, pb.length);
+	for (let i = 0; i < len; i += 1) {
+		const va = pa[i] ?? 0;
+		const vb = pb[i] ?? 0;
+		if (va !== vb) return va > vb ? 1 : -1;
+	}
+	return 0;
+}
 function buildThinkingLevelMap(supportedLevels) {
 	const efforts = new Set((Array.isArray(supportedLevels) ? supportedLevels : []).map((item) => {
 		if (typeof item === "string") return item;
@@ -350,11 +368,35 @@ function extractAccountId(parsed, accessToken) {
 		if (typeof jwtAccountId === "string" && jwtAccountId.trim() !== "") return jwtAccountId.trim();
 	}
 }
-async function writeJsonAtomic(filePath, data) {
-	let targetPath = filePath;
+function resolveRealTargetPath(filePath) {
 	try {
-		targetPath = realpathSync(filePath);
-	} catch {}
+		return realpathSync(filePath);
+	} catch {
+		try {
+			return join(realpathSync(dirname(filePath)), basename(filePath));
+		} catch {
+			return filePath;
+		}
+	}
+}
+function writeFileAtomicSync(filePath, content) {
+	const targetPath = resolveRealTargetPath(filePath);
+	const tempPath = join(dirname(targetPath), `.${basename(targetPath)}.tmp-${process.pid}-${randomUUID()}`);
+	try {
+		writeFileSync(tempPath, content, { mode: 384 });
+		try {
+			chmodSync(tempPath, 384);
+		} catch {}
+		renameSync(tempPath, targetPath);
+	} catch (error) {
+		try {
+			unlinkSync(tempPath);
+		} catch {}
+		throw error;
+	}
+}
+async function writeJsonAtomic(filePath, data) {
+	const targetPath = resolveRealTargetPath(filePath);
 	const tempPath = join(dirname(targetPath), `.auth.json.tmp-${process.pid}-${randomUUID()}`);
 	const content = `${JSON.stringify(data, null, 2)}\n`;
 	await writeFile(tempPath, content, {
@@ -419,25 +461,34 @@ function createAuthManager(options) {
 		return exp * 1e3 - nowFn() > TOKEN_REFRESH_LEAD_MS;
 	}
 	async function refreshToken(authPath, rawAuth) {
-		const refreshTok = rawAuth?.tokens?.refresh_token;
-		if (typeof refreshTok !== "string" || refreshTok.trim() === "") throw new LlmError("Codex 凭证已过期且缺少 refresh_token，请重新运行 codex login", "AUTH_FAILED");
-		const response = await fetchFn(CODEX_TOKEN_URL, {
-			method: "POST",
-			headers: buildCodexHeaders({
-				"Content-Type": "application/json",
-				Accept: "application/json"
-			}, options.getClientVersion?.()),
-			body: JSON.stringify({
-				client_id: CODEX_CLIENT_ID,
-				grant_type: "refresh_token",
-				refresh_token: refreshTok,
-				scope: "openid profile email"
-			}),
-			signal: AbortSignal.timeout(TOKEN_REFRESH_TIMEOUT_MS)
-		});
-		if (!response.ok) throw new LlmError(`Codex Token 刷新失败 (HTTP ${response.status})，请重新运行 codex login`, "AUTH_FAILED");
-		const fresh = await response.json();
-		if (typeof fresh?.access_token !== "string" || fresh.access_token.trim() === "") throw new LlmError("Codex Token 刷新响应缺少 access_token", "AUTH_FAILED");
+		let fresh;
+		try {
+			const refreshTok = rawAuth?.tokens?.refresh_token;
+			if (typeof refreshTok !== "string" || refreshTok.trim() === "") throw new LlmError("Codex 凭证已过期且缺少 refresh_token，请重新运行 codex login", "AUTH_FAILED");
+			const response = await fetchFn(CODEX_TOKEN_URL, {
+				method: "POST",
+				headers: buildCodexHeaders({
+					"Content-Type": "application/json",
+					Accept: "application/json"
+				}, options.getClientVersion?.()),
+				body: JSON.stringify({
+					client_id: CODEX_CLIENT_ID,
+					grant_type: "refresh_token",
+					refresh_token: refreshTok,
+					scope: "openid profile email"
+				}),
+				signal: AbortSignal.timeout(TOKEN_REFRESH_TIMEOUT_MS)
+			});
+			if (!response.ok) throw new LlmError(`Codex Token 刷新失败 (HTTP ${response.status})，请重新运行 codex login`, "AUTH_FAILED");
+			fresh = await response.json();
+			if (typeof fresh?.access_token !== "string" || fresh.access_token.trim() === "") throw new LlmError("Codex Token 刷新响应缺少 access_token", "AUTH_FAILED");
+		} catch (error) {
+			options.onLog?.("ERROR", "auth.refresh_failed", {
+				authPath,
+				error: safeErrorMessage(error)
+			});
+			throw error;
+		}
 		const nextAuth = {
 			...rawAuth,
 			tokens: {
@@ -455,8 +506,17 @@ function createAuthManager(options) {
 		};
 		try {
 			await writeJsonAtomic(authPath, nextAuth);
+			options.onLog?.("INFO", "auth.refreshed", {
+				authPath,
+				accountId: extractAccountId(nextAuth, fresh.access_token) ?? null
+			});
 		} catch (error) {
-			console.error(`[dsh-codex-subscription] 写回刷新后的 Codex auth.json 失败 (${authPath}): ${safeErrorMessage(error)}`);
+			const errMsg = safeErrorMessage(error);
+			options.onLog?.("WARN", "auth.writeback_failed", {
+				authPath,
+				error: errMsg
+			});
+			console.error(`[dsh-codex-subscription] 写回刷新后的 Codex auth.json 失败 (${authPath}): ${errMsg}`);
 		}
 		return {
 			accessToken: fresh.access_token,
@@ -492,10 +552,48 @@ function createAuthManager(options) {
 //#region src/index.ts
 const name = "codex-subscription";
 const inject = ["llm"];
+const LOG_FILE_NAME = "dsh-codex-subscription.log";
 const STREAM_IDLE_TIMEOUT_MS = 3e5;
 const MAX_REQUEST_IMAGE_BYTES = 20971520;
 const REQUEST_IMAGE_PIXEL_BUDGET = 4194304;
 const REQUEST_IMAGE_MAX_BYTES = 1048576;
+const MAX_LOG_FILE_BYTES = 524288;
+function appendPluginLog(codexHome, ctx, level, event, detail) {
+	const line = `[${new Date().toISOString()}] [${level}] ${event} ${JSON.stringify(detail)}\n`;
+	if (level === "ERROR") {
+		if (typeof ctx.logger?.error === "function") ctx.logger.error(`[dsh-codex-subscription] ${event}: ${JSON.stringify(detail)}`);
+		else console.error(`[dsh-codex-subscription] ${event}: ${JSON.stringify(detail)}`);
+	} else if (level === "WARN") {
+		if (typeof ctx.logger?.warn === "function") ctx.logger.warn(`[dsh-codex-subscription] ${event}: ${JSON.stringify(detail)}`);
+	}
+	try {
+		const logPath = join(codexHome, LOG_FILE_NAME);
+		try {
+			if (statSync(logPath).size > MAX_LOG_FILE_BYTES) {
+				const buf = readFileSync(logPath);
+				const halfOffset = Math.max(0, buf.length - Math.floor(MAX_LOG_FILE_BYTES / 2));
+				const newlineIdx = buf.indexOf(10, halfOffset);
+				writeFileAtomicSync(logPath, buf.subarray(newlineIdx >= 0 && newlineIdx + 1 < buf.length ? newlineIdx + 1 : halfOffset));
+			}
+		} catch {}
+		appendFileSync(logPath, line, {
+			encoding: "utf8",
+			mode: 384
+		});
+	} catch {}
+}
+function readBackupCache(codexHome) {
+	try {
+		return parseRawModelsCache(readFileSync(join(codexHome, BACKUP_CACHE_FILE_NAME), "utf8"));
+	} catch {
+		return;
+	}
+}
+function writeBackupCache(codexHome, raw) {
+	try {
+		writeFileAtomicSync(join(codexHome, BACKUP_CACHE_FILE_NAME), `${JSON.stringify(raw, null, 2)}\n`);
+	} catch {}
+}
 const Config = z.object({
 	disabledModels: z.array(z.string()).default([...DEFAULT_DISABLED_MODELS]).description("在模型选择器中屏蔽的模型 slug 列表").volatile(),
 	contextWindows: z.dict(z.number()).default({}).description("按模型 slug 覆盖上下文窗口大小（tokens），未配置时默认使用 872000").volatile()
@@ -538,11 +636,12 @@ function apply(ctx, config = {}) {
 	const getContextWindows = () => readVolatile(config.contextWindows, {});
 	const authManager = createAuthManager({
 		getCodexHome,
-		getClientVersion: () => ensureSnapshot().catalog.clientVersion
+		getClientVersion: () => ensureSnapshot().catalog.clientVersion,
+		onLog: (level, event, detail) => appendPluginLog(getCodexHome(), ctx, level, event, detail)
 	});
 	let fileSignature;
 	let cachedRaw;
-	let warnedMissingFile = false;
+	let rawRevision = 0;
 	let snapshotSignature;
 	let currentCatalog = {
 		clientVersion: DEFAULT_CLIENT_VERSION,
@@ -599,25 +698,73 @@ function apply(ctx, config = {}) {
 		}
 	});
 	function ensureSnapshot() {
-		const cachePath = join(getCodexHome(), "models_cache.json");
+		const codexHome = getCodexHome();
+		const cachePath = join(codexHome, "models_cache.json");
 		const disabled = getDisabledModels();
 		const contextWindows = getContextWindows();
+		const setActiveRaw = (next) => {
+			cachedRaw = next;
+			rawRevision += 1;
+		};
+		const tryRestoreFromBackup = (extra, minVersion) => {
+			const backupRaw = readBackupCache(codexHome);
+			if (backupRaw === void 0 || minVersion !== void 0 && compareClientVersions(backupRaw.client_version, minVersion) <= 0) return false;
+			setActiveRaw(backupRaw);
+			appendPluginLog(codexHome, ctx, "WARN", "catalog.backup_restored", {
+				cachePath,
+				...extra,
+				restoredVersion: backupRaw.client_version ?? "0.163.0",
+				restoredFetchedAt: backupRaw.fetched_at ?? null
+			});
+			return true;
+		};
+		const handleReadError = (error) => {
+			if (cachedRaw === void 0) tryRestoreFromBackup({ reason: safeErrorMessage(error) });
+			appendPluginLog(codexHome, ctx, cachedRaw === void 0 ? "ERROR" : "WARN", "catalog.read_error", {
+				cachePath,
+				hasFallbackSnapshot: cachedRaw !== void 0,
+				error: safeErrorMessage(error)
+			});
+		};
+		let stat;
 		try {
-			const stat = statSync(cachePath);
+			stat = statSync(cachePath);
+		} catch (error) {
+			const missingSig = `missing:${cachePath}:${error?.code ?? "ERR"}`;
+			if (missingSig !== fileSignature) {
+				fileSignature = missingSig;
+				handleReadError(error);
+			}
+		}
+		if (stat !== void 0) {
 			const nextFileSig = `${cachePath}:${stat.mtimeMs}:${stat.size}`;
 			if (nextFileSig !== fileSignature) {
-				cachedRaw = JSON.parse(readFileSync(cachePath, "utf8"));
 				fileSignature = nextFileSig;
-				warnedMissingFile = false;
-			}
-		} catch (error) {
-			if (!warnedMissingFile) {
-				warnedMissingFile = true;
-				console.error(`[dsh-codex-subscription] 读取 Codex models_cache.json 失败 (${cachePath}): ${safeErrorMessage(error)}`);
+				try {
+					const incomingRaw = parseRawModelsCache(readFileSync(cachePath, "utf8"));
+					if (cachedRaw !== void 0 && compareClientVersions(incomingRaw.client_version, cachedRaw.client_version) < 0) appendPluginLog(codexHome, ctx, "WARN", "catalog.downgrade_rejected", {
+						cachePath,
+						keptVersion: cachedRaw.client_version ?? "0.163.0",
+						rejectedVersion: incomingRaw.client_version ?? "unknown",
+						incomingFetchedAt: incomingRaw.fetched_at ?? null
+					});
+					else if (cachedRaw !== void 0 || !tryRestoreFromBackup({ diskVersion: incomingRaw.client_version ?? "unknown" }, incomingRaw.client_version)) {
+						setActiveRaw(incomingRaw);
+						writeBackupCache(codexHome, incomingRaw);
+						appendPluginLog(codexHome, ctx, "INFO", "catalog.load", {
+							cachePath,
+							clientVersion: incomingRaw.client_version ?? "0.163.0",
+							fetchedAt: incomingRaw.fetched_at ?? null,
+							rawModelCount: Array.isArray(incomingRaw.models) ? incomingRaw.models.length : 0
+						});
+					}
+				} catch (error) {
+					handleReadError(error);
+				}
 			}
 		}
 		const nextSnapshotSig = JSON.stringify([
-			fileSignature ?? "none",
+			rawRevision,
 			disabled,
 			contextWindows
 		]);
@@ -627,6 +774,12 @@ function apply(ctx, config = {}) {
 				models: [],
 				metadataById: new Map()
 			};
+			appendPluginLog(codexHome, ctx, currentCatalog.models.length === 0 ? "WARN" : "INFO", "catalog.snapshot", {
+				clientVersion: currentCatalog.clientVersion,
+				models: currentCatalog.models.map((m) => m.id),
+				disabledModels: disabled,
+				contextWindows
+			});
 			currentProfilesMap = new Map([[PROVIDER, Object.freeze({
 				provider: PROVIDER,
 				displayName: DISPLAY_NAME,
@@ -715,7 +868,9 @@ const __test = Object.freeze({
 	safeErrorMessage,
 	createAuthManager,
 	buildThinkingLevelMap,
+	compareClientVersions,
 	parseModelsCache,
+	parseRawModelsCache,
 	sanitizeCodexPayload,
 	buildCodexHeaders,
 	buildCodexUserAgent,
@@ -724,4 +879,4 @@ const __test = Object.freeze({
 	createUsageFetcher
 });
 //#endregion
-export { Config, __test, apply, inject, name };
+export { BACKUP_CACHE_FILE_NAME, Config, LOG_FILE_NAME, __test, apply, inject, name };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyogvce/dsh-codex-subscription",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "复用本机 ~/.codex 订阅凭证与 models_cache.json 模型缓存，在 DSH 中通过 SSE 直连调用 Codex 模型。",
   "type": "module",
   "main": "./lib/index.js",