@buyi1net/pi-toolkit 0.0.1

package/modules/tui/plugin/package-order.ts

@@ -0,0 +1,169 @@
+// 包顺序自调：Pi 的 packages 按数组顺序串行加载，且 pi install 固定 append 到
+// 末尾——本包含 TUI 外观类扩展，需要尽早加载（闸门/看门狗越早挂，宿主与其
+// 它扩展的初始化输出越少暴露）。检测到不在首位时调整一次并写回 + 通知。
+// 幂等且可退出：已在首位零动作；settings 里 piToolkitKeepPackageOrder=true 或
+// 环境变量 PI_TOOLKIT_KEEP_PACKAGE_ORDER=1 时永不调整；写回失败静默放弃。
+//
+// 迁入 pi-toolkit 后按新包名适配（保留行为，只换标识）：原 pi-tui 的
+// `piTuiKeepPackageOrder` / `PI_TUI_KEEP_PACKAGE_ORDER` 不再识别；识别目标
+// 也从 pi-tui 包换成声明 `pi.extensions` 的本包（pi-toolkit）。
+
+import { readFileSync, writeFileSync, renameSync, existsSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize } from "node:path";
+import { fileURLToPath } from "node:url";
+
+interface GitRepositoryIdentity {
+	host: string;
+	path: string;
+}
+
+interface SelfPackageIdentity {
+	dir: string;
+	name: string;
+	repository?: GitRepositoryIdentity;
+}
+
+function entrySource(entry: unknown): string | undefined {
+	if (typeof entry === "string") return entry;
+	if (!entry || typeof entry !== "object" || !("source" in entry)) return undefined;
+	const source = (entry as { source: unknown }).source;
+	return typeof source === "string" ? source : undefined;
+}
+
+function npmPackageName(source: string): string | undefined {
+	if (!source.startsWith("npm:")) return undefined;
+	const spec = source.slice(4).trim();
+	if (!spec) return undefined;
+	if (!spec.startsWith("@")) return spec.split("@", 1)[0] || undefined;
+	const slash = spec.indexOf("/");
+	if (slash < 0) return undefined;
+	const version = spec.indexOf("@", slash);
+	return version < 0 ? spec : spec.slice(0, version);
+}
+
+function gitRepositoryIdentity(source: string): GitRepositoryIdentity | undefined {
+	let value = source.trim();
+	const prefixed = value.startsWith("git:") && !value.startsWith("git://");
+	if (prefixed) value = value.slice(4).trim();
+	value = value.replace(/^git\+/, "");
+
+	let host: string;
+	let path: string;
+	const scp = value.match(/^git@([^:]+):(.+)$/);
+	if (scp) {
+		if (!prefixed) return undefined;
+		host = scp[1]!;
+		path = scp[2]!;
+	} else if (/^(?:https?|ssh|git):\/\//i.test(value)) {
+		try {
+			const parsed = new URL(value);
+			host = parsed.hostname;
+			path = parsed.pathname.replace(/^\/+/, "");
+		} catch {
+			return undefined;
+		}
+	} else if (prefixed) {
+		const slash = value.indexOf("/");
+		if (slash < 0) return undefined;
+		host = value.slice(0, slash);
+		path = value.slice(slash + 1);
+	} else {
+		return undefined;
+	}
+
+	path = path.split(/[?#]/, 1)[0]!.split("@", 1)[0]!.replace(/\/+$/, "").replace(/\.git$/i, "");
+	if (!host || !path || !path.includes("/")) return undefined;
+	return { host: host.toLowerCase(), path };
+}
+
+/** 判断 packages 项是否指向本插件（本地路径、npm 名称或 Git 仓库）。 */
+function isSelfEntry(entry: unknown, self: SelfPackageIdentity, baseDir: string): boolean {
+	const source = entrySource(entry);
+	if (!source) return false;
+
+	const npmName = npmPackageName(source);
+	if (npmName) return npmName === self.name;
+
+	const repository = gitRepositoryIdentity(source);
+	if (repository) {
+		return repository.host === self.repository?.host && repository.path === self.repository.path;
+	}
+	if (/^(?:git:|https?:|ssh:)/i.test(source)) return false;
+
+	try {
+		// isAbsolute 同时认 POSIX 与 Windows 盘符两种形态（win32 join 不会用
+		// 绝对路径替换前缀，直接 join 会拼出畸形路径）；normalize 统一斜杠方向。
+		const resolved = normalize(isAbsolute(source) ? source : join(baseDir, source));
+		return resolved === self.dir;
+	} catch {
+		return false;
+	}
+}
+
+function resolveSelfPackage(): SelfPackageIdentity | undefined {
+	// 从本文件位置逐级向上找声明了 pi.extensions 的 package.json。
+	// 源码场景下本文件在包根的 modules/tui/plugin/ 里（四层深），组装后的产物
+	// 可能在更浅的位置，因此向上多探几层而不是写死深度。
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 8; i += 1) {
+		const manifest = join(dir, "package.json");
+		if (existsSync(manifest)) {
+			try {
+				const parsed = JSON.parse(readFileSync(manifest, "utf8")) as {
+					name?: unknown;
+					pi?: { extensions?: unknown[] };
+					repository?: string | { url?: unknown };
+				};
+				if (parsed.pi?.extensions && typeof parsed.name === "string") {
+					const repositoryUrl = typeof parsed.repository === "string"
+						? parsed.repository
+						: (typeof parsed.repository?.url === "string" ? parsed.repository.url : undefined);
+					return {
+						dir: normalize(dir),
+						name: parsed.name,
+						repository: repositoryUrl ? gitRepositoryIdentity(repositoryUrl) : undefined,
+					};
+				}
+			} catch { /* 继续向上 */ }
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return undefined;
+		dir = parent;
+	}
+	return undefined;
+}
+
+export interface PackageOrderResult {
+	adjusted: boolean;
+	reason?: string;
+}
+
+/** 检查并调整本插件在 packages 中的位置到首位；任何失败都不抛出。 */
+export function ensureFirstPackage(agentDir: string, env: Readonly<Record<string, string | undefined>> = process.env): PackageOrderResult {
+	if (env.PI_TOOLKIT_KEEP_PACKAGE_ORDER === "1") return { adjusted: false, reason: "disabled-env" };
+	const settingsPath = join(agentDir, "settings.json");
+	try {
+		const raw = readFileSync(settingsPath, "utf8");
+		const settings = JSON.parse(raw) as {
+			packages?: unknown[];
+			piToolkitKeepPackageOrder?: boolean;
+		};
+		if (settings.piToolkitKeepPackageOrder === true) return { adjusted: false, reason: "disabled-settings" };
+		const packages = settings.packages;
+		if (!Array.isArray(packages) || packages.length < 2) return { adjusted: false };
+		const self = resolveSelfPackage();
+		if (!self) return { adjusted: false, reason: "self-not-found" };
+		const index = packages.findIndex((entry) => isSelfEntry(entry, self, agentDir));
+		if (index <= 0) return { adjusted: false };
+		const next = [...packages];
+		const [selfEntry] = next.splice(index, 1);
+		next.unshift(selfEntry);
+		settings.packages = next;
+		const tmpPath = `${settingsPath}.pi-toolkit.tmp`;
+		writeFileSync(tmpPath, JSON.stringify(settings, null, "\t") + "\n");
+		renameSync(tmpPath, settingsPath);
+		return { adjusted: true };
+	} catch {
+		return { adjusted: false, reason: "error" };
+	}
+}

package/modules/tui/plugin/screen-transition.ts

@@ -0,0 +1,203 @@
+import type {
+	TUI,
+	TuiMainScreenRenderState,
+} from "@earendil-works/pi-tui";
+
+/** 终端输出抽象：测试可注入伪 TTY。 */
+export type VisibleScreenOutput = {
+	isTTY?: boolean;
+};
+
+export const CLEAR_VISIBLE_SCREEN = "\x1b[2J\x1b[H";
+export const DIRTY_RENDER_SUFFIX = "\x00";
+/** 过渡揭示的稳定等待：超过该时长没有新 Editor 帧即视为结构稳定。 */
+export const TRANSITION_SETTLE_MS = 32;
+
+export function isInteractiveLaunch(): boolean {
+	if (!process.stdout.isTTY) return false;
+	const nonInteractiveFlags = new Set([
+		"-p",
+		"--print",
+		"--help",
+		"-h",
+		"--version",
+		"-v",
+		"--list-models",
+		"--export",
+	]);
+	return process.argv.slice(2).every((arg) => !nonInteractiveFlags.has(arg) && !arg.startsWith("--mode"));
+}
+
+type MainScreenTui = TUI & {
+	captureRenderState(): TuiMainScreenRenderState;
+	restoreRenderState(state: TuiMainScreenRenderState): void;
+};
+
+export function isMainScreenTui(tui: TUI): tui is MainScreenTui {
+	return (
+		tui.mode === "regular" &&
+		typeof (tui as Partial<MainScreenTui>).captureRenderState === "function" &&
+		typeof (tui as Partial<MainScreenTui>).restoreRenderState === "function"
+	);
+}
+
+function hasImageLine(lines: readonly string[]): boolean {
+	return lines.some((line) => line.includes("\x1b_G") || line.includes("\x1b]1337;File="));
+}
+
+export function isSafeRenderState(tui: TUI, state: TuiMainScreenRenderState): boolean {
+	const width = tui.terminal.columns;
+	const height = tui.terminal.rows;
+	if (!Number.isSafeInteger(width) || width <= 0 || !Number.isSafeInteger(height) || height <= 0) {
+		return false;
+	}
+	if (state.previousWidth !== width || state.previousHeight !== height) return false;
+	if (!Array.isArray(state.previousLines) || state.previousLines.length === 0) return false;
+	if (hasImageLine(state.previousLines)) return false;
+	if (!Number.isSafeInteger(state.previousViewportTop) || state.previousViewportTop < 0) return false;
+	return state.previousViewportTop === Math.max(0, state.previousLines.length - height);
+}
+
+function isPristineRenderState(state: TuiMainScreenRenderState): boolean {
+	return (
+		Array.isArray(state.previousLines) &&
+		state.previousLines.length === 0 &&
+		state.previousWidth === 0 &&
+		state.previousHeight === 0 &&
+		state.previousViewportTop === 0 &&
+		state.cursorRow === 0 &&
+		state.hardwareCursorRow === 0 &&
+		state.maxLinesRendered === 0
+	);
+}
+
+function hasStableRenderState(
+	left: TuiMainScreenRenderState,
+	right: TuiMainScreenRenderState,
+): boolean {
+	if (
+		left.previousWidth !== right.previousWidth ||
+		left.previousHeight !== right.previousHeight ||
+		left.previousViewportTop !== right.previousViewportTop ||
+		left.previousLines.length !== right.previousLines.length
+	) {
+		return false;
+	}
+	return left.previousLines.every((line, index) => line === right.previousLines[index]);
+}
+
+export function flashVisibleScreen(
+	tui: TUI,
+	output: VisibleScreenOutput = process.stdout,
+): TuiMainScreenRenderState | undefined {
+	if (!output.isTTY || !isMainScreenTui(tui) || tui.hasOverlay()) return undefined;
+	let state: TuiMainScreenRenderState;
+	try {
+		state = tui.captureRenderState();
+	} catch {
+		return undefined;
+	}
+	if (!isPristineRenderState(state) && !isSafeRenderState(tui, state)) return undefined;
+
+	try {
+		tui.terminal.write(CLEAR_VISIBLE_SCREEN);
+		return state;
+	} catch {
+		forceRestoreClearedScreen(tui);
+		return undefined;
+	}
+}
+
+function forceRestoreClearedScreen(tui: TUI): void {
+	try {
+		tui.renderNow(true);
+	} catch {
+		// 强制重画已经是闪屏后的最后恢复路径。
+	}
+}
+
+function captureStableMainScreenState(tui: TUI): TuiMainScreenRenderState | undefined {
+	try {
+		tui.renderNow(false);
+		if (!isMainScreenTui(tui) || tui.hasOverlay()) return undefined;
+		const firstState = tui.captureRenderState();
+		if (!isSafeRenderState(tui, firstState)) return undefined;
+
+		// 连续两次同步渲染必须完全稳定，否则不能保证恢复范围。
+		tui.renderNow(false);
+		const state = tui.captureRenderState();
+		if (!isSafeRenderState(tui, state) || !hasStableRenderState(firstState, state)) {
+			return undefined;
+		}
+		return state;
+	} catch {
+		return undefined;
+	}
+}
+
+function revealPreparedMainScreen(
+	tui: TUI,
+	deferred: boolean,
+	screenAlreadyCleared: boolean,
+): boolean {
+	try {
+		if (deferred) tui.requestRender(false);
+		else tui.renderNow(false);
+		return true;
+	} catch {
+		if (screenAlreadyCleared) forceRestoreClearedScreen(tui);
+		return false;
+	}
+}
+
+export function restoreVisibleMainScreen(
+	tui: TUI,
+	preClearState?: TuiMainScreenRenderState,
+	deferred = false,
+): boolean {
+	const screenAlreadyCleared = preClearState !== undefined;
+	const state = preClearState ?? captureStableMainScreenState(tui);
+	if (!state) {
+		if (screenAlreadyCleared) forceRestoreClearedScreen(tui);
+		return false;
+	}
+	if (!isMainScreenTui(tui)) {
+		if (screenAlreadyCleared) forceRestoreClearedScreen(tui);
+		return false;
+	}
+	if (screenAlreadyCleared && isPristineRenderState(state)) {
+		return revealPreparedMainScreen(tui, deferred, true);
+	}
+
+	const top = state.previousViewportTop;
+	const bottom = Math.min(state.previousLines.length, top + state.previousHeight);
+	if (bottom <= top) {
+		if (screenAlreadyCleared) forceRestoreClearedScreen(tui);
+		return false;
+	}
+	const previousLines = state.previousLines.map((line, index) =>
+		index >= top && index < bottom ? `${line}${DIRTY_RENDER_SUFFIX}` : line,
+	);
+
+	try {
+		tui.restoreRenderState({
+			...state,
+			previousLines,
+			cursorRow: top,
+			hardwareCursorRow: top,
+			maxLinesRendered: 0,
+		});
+	} catch {
+		try {
+			tui.restoreRenderState(state);
+		} catch {
+			// renderer 状态未改变时无需继续恢复。
+		}
+		if (screenAlreadyCleared) forceRestoreClearedScreen(tui);
+		else tui.renderNow(false);
+		return false;
+	}
+
+	if (!screenAlreadyCleared) tui.terminal.write(CLEAR_VISIBLE_SCREEN);
+	return revealPreparedMainScreen(tui, deferred, screenAlreadyCleared);
+}

package/modules/tui/plugin/settings-config.ts

@@ -0,0 +1,297 @@
+// pi-tui 迁入 pi-toolkit 后的配置层（只解析，不写盘）。
+//
+// 两块来源：
+// 1. 外观 / 状态 / 数据 / 高级四个子节来自 pi-toolkit.json 的 `modules.tui` 节。
+//    写盘统一走 modules/tui/config.ts（骨架的深合并 + 剥敏感键 + 0600 原子写），
+//    本文件只负责把这些子节规范化成 lifecycle 认识的结构。
+// 2. 供应商查询凭据（queries[].apiKey、credentials 里的 AK/SK、githubDomain）
+//    按用户裁决留在独立文件 <agentDir>/pi-tui.json：本模块只读，toolkit 永不写，
+//    因此凭据永远不会进入 pi-toolkit.json。外观等其余键即使写在 pi-tui.json 里
+//    也不再被读取（合并决策 8：不做旧配置迁移）。
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { PiProviderAccessConfig } from "../adapter/provider-usage.ts";
+import {
+	parseProviderCredentials,
+	parseProviderQueries,
+	ProviderConfigValidationError,
+} from "../kernel/usage-core.ts";
+import {
+	STATUS_PRESET_NAMES,
+	STATUS_SEGMENT_IDS,
+	type StatusPresetName,
+	type StatusSegmentId,
+} from "../status/status-config.ts";
+
+/** 供应商凭据独立文件名（相对 pi 的 agentDir） */
+export const PI_TUI_CONFIG_FILENAME = "pi-tui.json";
+export const PROVIDER_REFRESH_INTERVALS = [30_000, 60_000, 120_000, 300_000] as const;
+
+export type ProviderRefreshMs = (typeof PROVIDER_REFRESH_INTERVALS)[number];
+export type SpinnerMode = "default" | "static" | "hidden";
+
+export interface PiTuiConfig {
+	appearance: {
+		editor: boolean;
+		header: boolean;
+		/** 底部状态栏总开关（原版无条件安装，迁入后补上） */
+		footer: boolean;
+	};
+	status: {
+		preset: StatusPresetName;
+		segments: StatusSegmentId[] | null;
+	};
+	data: {
+		providerRefreshMs: ProviderRefreshMs;
+		telemetry: boolean;
+		/** 只从独立文件 pi-tui.json 读取，不从 pi-toolkit.json 读取 */
+		providerAccess?: PiProviderAccessConfig;
+	};
+	advanced: {
+		spinner: SpinnerMode;
+	};
+}
+
+export interface LoadedPiTuiConfig {
+	config: PiTuiConfig;
+	warnings: string[];
+}
+
+export const DEFAULT_PI_TUI_CONFIG: Readonly<PiTuiConfig> = Object.freeze({
+	appearance: Object.freeze({ editor: true, header: true, footer: true }),
+	status: Object.freeze({ preset: "default", segments: null }),
+	data: Object.freeze({ providerRefreshMs: 60_000, telemetry: true }),
+	advanced: Object.freeze({ spinner: "default" }),
+});
+
+const PRESETS = new Set<StatusPresetName>(STATUS_PRESET_NAMES);
+const SEGMENTS = new Set<StatusSegmentId>(STATUS_SEGMENT_IDS);
+const REFRESH_INTERVALS = new Set<number>(PROVIDER_REFRESH_INTERVALS);
+const SPINNER_MODES = new Set<SpinnerMode>(["default", "static", "hidden"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function optionalRecord(value: unknown, field: string, warnings: string[]): Record<string, unknown> {
+	if (value === undefined) return {};
+	if (!isRecord(value)) {
+		warnings.push(`${field} 必须是对象，已忽略`);
+		return {};
+	}
+	return value;
+}
+
+function readBoolean(value: unknown, fallback: boolean, field: string, warnings: string[]): boolean {
+	if (value === undefined) return fallback;
+	if (typeof value !== "boolean") {
+		warnings.push(`${field} 必须是布尔值，已使用默认值`);
+		return fallback;
+	}
+	return value;
+}
+
+function readChoice<T extends string>(
+	value: unknown,
+	choices: ReadonlySet<T>,
+	fallback: T,
+	field: string,
+	warnings: string[],
+): T {
+	if (value === undefined) return fallback;
+	if (typeof value !== "string" || !choices.has(value as T)) {
+		warnings.push(`${field} 的值无效，已使用默认值`);
+		return fallback;
+	}
+	return value as T;
+}
+
+function readSegments(value: unknown, warnings: string[]): StatusSegmentId[] | null {
+	if (value === undefined || value === null) return null;
+	if (!Array.isArray(value)) {
+		warnings.push("status.segments 必须是数组或 null，已使用默认值");
+		return null;
+	}
+	const seen = new Set<StatusSegmentId>();
+	for (const segment of value) {
+		if (typeof segment !== "string" || !SEGMENTS.has(segment as StatusSegmentId)) {
+			warnings.push(`status.segments 包含无效值: ${String(segment)}，已忽略`);
+			continue;
+		}
+		seen.add(segment as StatusSegmentId);
+	}
+	return [...seen];
+}
+
+function readStatusPresetValue(value: unknown, warnings: string[]): StatusPresetName {
+	if (value === "ascii") return "default";
+	return readChoice(value, PRESETS, "default", "status.preset", warnings);
+}
+
+function readRefreshMs(value: unknown, warnings: string[]): ProviderRefreshMs {
+	if (value === undefined) return DEFAULT_PI_TUI_CONFIG.data.providerRefreshMs;
+	if (typeof value !== "number" || !REFRESH_INTERVALS.has(value)) {
+		warnings.push("data.providerRefreshMs 的值无效，已使用默认值");
+		return DEFAULT_PI_TUI_CONFIG.data.providerRefreshMs;
+	}
+	return value as ProviderRefreshMs;
+}
+
+/**
+ * 把 pi-toolkit.json 的 `modules.tui` 节规范化成 PiTuiConfig。
+ * 逐字段校验：非法项记 warning 并回退默认值，绝不因单点配置错误拖垮整个模块。
+ */
+export function parseTuiSection(section: Record<string, unknown> | undefined): LoadedPiTuiConfig {
+	const warnings: string[] = [];
+	const source = isRecord(section) ? section : {};
+	const appearance = optionalRecord(source.appearance, "appearance", warnings);
+	const status = optionalRecord(source.status, "status", warnings);
+	const data = optionalRecord(source.data, "data", warnings);
+	const advanced = optionalRecord(source.advanced, "advanced", warnings);
+	const defaults = DEFAULT_PI_TUI_CONFIG;
+
+	return {
+		config: {
+			appearance: {
+				editor: readBoolean(appearance.editor, defaults.appearance.editor, "appearance.editor", warnings),
+				header: readBoolean(appearance.header, defaults.appearance.header, "appearance.header", warnings),
+				footer: readBoolean(appearance.footer, defaults.appearance.footer, "appearance.footer", warnings),
+			},
+			status: {
+				preset: readStatusPresetValue(status.preset, warnings),
+				segments: readSegments(status.segments, warnings),
+			},
+			data: {
+				providerRefreshMs: readRefreshMs(data.providerRefreshMs, warnings),
+				telemetry: readBoolean(data.telemetry, defaults.data.telemetry, "data.telemetry", warnings),
+			},
+			advanced: {
+				spinner: readChoice(advanced.spinner, SPINNER_MODES, defaults.advanced.spinner, "advanced.spinner", warnings),
+			},
+		},
+		warnings,
+	};
+}
+
+// ─────────────────────────────────────────────────────────────
+// 独立凭据文件 <agentDir>/pi-tui.json（只读）
+// ─────────────────────────────────────────────────────────────
+
+export function piTuiConfigPath(agentDir: string): string {
+	return join(agentDir, PI_TUI_CONFIG_FILENAME);
+}
+
+export interface LoadedProviderAccess {
+	/** 独立文件是否存在；菜单的"已配置/未配置"状态直接看它 */
+	readonly exists: boolean;
+	/** 解析出的供应商查询配置；文件缺失或无效时为 undefined */
+	readonly access?: PiProviderAccessConfig;
+	readonly warnings: readonly string[];
+}
+
+function readGithubDomain(value: unknown, warnings: string[]): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string" || !value.trim()) {
+		warnings.push("data.providerAccess.githubDomain 必须是非空字符串，已忽略");
+		return undefined;
+	}
+	const domain = value.trim().toLowerCase();
+	try {
+		const url = new URL(`https://${domain}`);
+		if (url.hostname !== domain || url.port || url.pathname !== "/" || url.username || url.password) {
+			throw new Error();
+		}
+		return domain;
+	} catch {
+		warnings.push("data.providerAccess.githubDomain 必须是主机名，已忽略");
+		return undefined;
+	}
+}
+
+const VALIDATION_RULES = {
+	object: "必须是对象",
+	array: "必须是数组",
+	nonEmptyArray: "必须是非空数组",
+	nonEmptyString: "必须是非空字符串",
+	choice: "的值无效",
+} as const;
+
+function readProviderAccess(value: unknown, warnings: string[]): PiProviderAccessConfig | undefined {
+	if (!isRecord(value)) {
+		warnings.push("data.providerAccess 必须是对象，已忽略");
+		return undefined;
+	}
+	try {
+		const queries = parseProviderQueries(value.queries, "data.providerAccess.queries");
+		const githubDomain = readGithubDomain(value.githubDomain, warnings);
+		const credentials = parseProviderCredentials(value.credentials, "data.providerAccess.credentials");
+		return {
+			...(queries ? { queries } : {}),
+			...(Object.keys(credentials).length > 0 ? { credentials } : {}),
+			...(githubDomain ? { githubDomain } : {}),
+		};
+	} catch (error) {
+		if (!(error instanceof ProviderConfigValidationError)) throw error;
+		warnings.push(`${error.field} ${VALIDATION_RULES[error.rule]}，已忽略`);
+		return undefined;
+	}
+}
+
+/**
+ * 读独立凭据文件的数据源部分。除 `data.providerAccess` 外的键一律忽略。
+ * 只读：本文件永不写盘（凭据由用户自行维护）。
+ */
+export function loadProviderAccessFile(agentDir: string): LoadedProviderAccess {
+	const path = piTuiConfigPath(agentDir);
+	let text: string;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return { exists: false, warnings: [] };
+		}
+		return { exists: false, warnings: [`${path}: 读取失败（${(error as Error).message}），供应商查询按未配置处理`] };
+	}
+
+	const warnings: string[] = [];
+	let root: unknown;
+	try {
+		root = JSON.parse(text);
+	} catch (error) {
+		warnings.push(`${path}: 解析失败（${(error as Error).message}），供应商查询按未配置处理`);
+		return { exists: true, warnings };
+	}
+	if (!isRecord(root)) {
+		warnings.push(`${path}: 顶层不是对象，供应商查询按未配置处理`);
+		return { exists: true, warnings };
+	}
+	const data = root.data;
+	if (!isRecord(data) || data.providerAccess === undefined) {
+		return { exists: true, warnings };
+	}
+	return { exists: true, access: readProviderAccess(data.providerAccess, warnings), warnings };
+}
+
+/** 菜单里的只读状态行：检测到独立文件即视为已配置 */
+export function providerAccessConfigured(agentDir: string): boolean {
+	return loadProviderAccessFile(agentDir).exists;
+}
+
+/** 没有模块节可用时的兜底：默认外观 + 独立文件里的供应商凭据 */
+export function loadStandaloneTuiConfig(agentDir: string): LoadedPiTuiConfig {
+	const provider = loadProviderAccessFile(agentDir);
+	const defaults = DEFAULT_PI_TUI_CONFIG;
+	return {
+		config: {
+			appearance: { ...defaults.appearance },
+			status: { preset: defaults.status.preset, segments: null },
+			data: {
+				...defaults.data,
+				...(provider.access ? { providerAccess: provider.access } : {}),
+			},
+			advanced: { ...defaults.advanced },
+		},
+		warnings: [...provider.warnings],
+	};
+}