pi-shepherd 0.1.0

package/node_modules/@pi-atelier/shared-utils/src/project-config.ts

@@ -0,0 +1,241 @@
+/**
+ * Project-level Configuration — 全局 + 项目级配置合并与冲突检测
+ *
+ * 配置解析优先级：defaults → 全局 settings.json → 项目 .pi/settings.json
+ * 支持按项目启用/禁用工具、MCP 服务器，以及覆盖任意扩展配置。
+ *
+ * 用法：
+ *   import { getEffectiveConfig, detectConfigConflicts, getEnabledTools } from "@pi-atelier/shared-utils";
+ *
+ *   const cfg = getEffectiveConfig("context", defaults, cwd);
+ *   const conflicts = detectConfigConflicts(cwd);
+ *   const tools = getEnabledTools(allTools, cwd);
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { SETTINGS_PATH } from "./paths";
+import { getSettingsSection } from "./settings";
+
+// ── 类型 ─────────────────────────────────────────────────
+
+export interface ConfigConflict {
+	section: string;
+	key: string;
+	globalValue: unknown;
+	projectValue: unknown;
+	description: string;
+}
+
+export interface EffectiveConfigResult<T extends Record<string, any>> {
+	/** 合并后的配置 */
+	config: T;
+	/** 配置来源：'default' | 'global' | 'project' */
+	sources: Record<string, "default" | "global" | "project">;
+}
+
+export interface MergeOptions {
+	/** 数组合并策略：replace（项目级替换全局，默认）、concat（项目级追加到全局） */
+	arrayMerge?: "replace" | "concat";
+}
+
+export interface SchemaError {
+	/** 配置段名 */
+	section: string;
+	/** 字段名 */
+	key: string;
+	/** 期望类型 */
+	expectedType: string;
+	/** 实际类型 */
+	actualType: string;
+	/** 人类可读描述 */
+	description: string;
+}
+
+export interface ToolFilter {
+	/** 额外启用的工具 ID 列表 */
+	enabled?: string[];
+	/** 禁用的工具 ID 列表 */
+	disabled?: string[];
+}
+
+// ── 内部工具 ─────────────────────────────────────────────
+
+/** 深度合并两个对象，source 覆盖 target */
+function deepMerge<T extends Record<string, any>>(target: T, source: Record<string, any>, options?: MergeOptions): T {
+	const result = { ...target } as Record<string, any>;
+	for (const key of Object.keys(source)) {
+		if (
+			source[key] !== null &&
+			typeof source[key] === "object" &&
+			!Array.isArray(source[key]) &&
+			result[key] !== null &&
+			typeof result[key] === "object" &&
+			!Array.isArray(result[key])
+		) {
+			result[key] = deepMerge(result[key], source[key], options);
+		} else if (Array.isArray(source[key]) && options?.arrayMerge === "concat" && Array.isArray(result[key])) {
+			// concat 策略：项目级数组追加到全局数组末尾
+			result[key] = [...result[key], ...source[key]];
+		} else {
+			result[key] = source[key];
+		}
+	}
+	return result as T;
+}
+
+/** 读取项目级 settings.json */
+export function readProjectSettings(cwd: string): Record<string, any> {
+	const projectSettingsPath = join(cwd, ".pi", "settings.json");
+	if (!existsSync(projectSettingsPath)) return {};
+	try {
+		return JSON.parse(readFileSync(projectSettingsPath, "utf-8"));
+	} catch {
+		return {};
+	}
+}
+
+/** 清除项目级配置缓存（保留接口，当前为 no-op） */
+export function clearProjectSettingsCache(): void {
+	// 预留，当前无缓存
+}
+
+/**
+ * 获取合并后的有效配置（defaults → 全局 → 项目级 deep merge）
+ *
+ * @param section - settings.json 中的顶层 key，如 "context"、"shepherd"
+ * @param defaults - 该段的默认值（完整对象）
+ * @param cwd - 当前项目目录（用于查找 .pi/settings.json）
+ * @param options - 合并选项（如 arrayMerge 策略）
+ * @returns 合并后的配置 + 各字段来源
+ */
+export function getEffectiveConfig<T extends Record<string, any>>(
+	section: string,
+	defaults: T,
+	cwd: string,
+	options?: MergeOptions,
+): EffectiveConfigResult<T> {
+	// 1. 全局配置
+	const globalConfig = getSettingsSection(section, defaults);
+
+	// 2. 项目级配置
+	const projectSettings = readProjectSettings(cwd);
+	const projectSection = projectSettings?.[section] ?? {};
+
+	// 3. Deep merge: defaults → global → project
+	const merged = deepMerge(globalConfig, projectSection, options);
+
+	// 4. 追踪来源
+	const sources: Record<string, "default" | "global" | "project"> = {};
+	for (const key of Object.keys(defaults)) {
+		if (projectSection && key in projectSection) {
+			sources[key] = "project";
+		} else {
+			const globalSec = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"))?.[section] ?? {};
+			sources[key] = key in globalSec ? "global" : "default";
+		}
+	}
+
+	return { config: merged, sources };
+}
+
+/**
+ * 检测全局配置与项目级配置之间的冲突
+ *
+ * 冲突定义：项目级配置覆盖了全局配置中可能导致行为不一致的值。
+ * 例如：全局 distillThreshold=5000，项目设为 500，可能过于激进。
+ *
+ * @param cwd - 当前项目目录
+ * @param sensitiveKeys - 需要检测冲突的 key 列表（可选，默认检查所有有差异的 key）
+ * @returns 冲突列表
+ */
+export function detectConfigConflicts(cwd: string, sensitiveKeys?: string[]): ConfigConflict[] {
+	const conflicts: ConfigConflict[] = [];
+	const projectSettings = readProjectSettings(cwd);
+	if (Object.keys(projectSettings).length === 0) return conflicts;
+
+	// 读取全局 settings
+	let globalSettings: Record<string, any> = {};
+	try {
+		globalSettings = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+	} catch {
+		return conflicts;
+	}
+
+	for (const section of Object.keys(projectSettings)) {
+		// 跳过非配置段（如 prompts、skills 等 pi 核心管理的字段）
+		if (section === "prompts" || section === "skills") continue;
+
+		const projectSection = projectSettings[section];
+		const globalSection = globalSettings[section] ?? {};
+		if (typeof projectSection !== "object" || projectSection === null) continue;
+
+		for (const key of Object.keys(projectSection)) {
+			if (sensitiveKeys && !sensitiveKeys.includes(key)) continue;
+
+			const globalVal = globalSection[key];
+			const projectVal = projectSection[key];
+
+			// 只报告项目级与全局值不同的 key
+			if (globalVal !== undefined && JSON.stringify(globalVal) !== JSON.stringify(projectVal)) {
+				conflicts.push({
+					section,
+					key,
+					globalValue: globalVal,
+					projectValue: projectVal,
+					description: `项目配置 "${section}.${key}" 覆盖了全局值`,
+				});
+			}
+		}
+	}
+
+	return conflicts;
+}
+
+/**
+ * 校验项目级配置与默认值的类型一致性
+ *
+ * 对比项目 .pi/settings.json 中指定 section 的字段类型与 defaults 定义的类型，
+ * 类型不一致时返回错误列表。
+ *
+ * @param section - settings.json 中的顶层 key
+ * @param defaults - 该段的默认值（定义了期望的类型结构）
+ * @param cwd - 当前项目目录
+ * @returns 格式错误列表
+ */
+export function validateConfigSchema(section: string, defaults: Record<string, any>, cwd: string): SchemaError[] {
+	const errors: SchemaError[] = [];
+	const projectSettings = readProjectSettings(cwd);
+	const projectSection = projectSettings?.[section];
+	if (!projectSection || typeof projectSection !== "object") return errors;
+
+	function checkTypes(defaultObj: Record<string, any>, projectObj: Record<string, any>, prefix: string) {
+		for (const key of Object.keys(projectObj)) {
+			const fullKey = prefix ? `${prefix}.${key}` : key;
+			const defaultVal = defaultObj[key];
+			const projectVal = projectObj[key];
+
+			// 只校验 defaults 中定义的字段（未知字段跳过）
+			if (defaultVal === undefined) continue;
+
+			const expectedType = Array.isArray(defaultVal) ? "array" : defaultVal === null ? "null" : typeof defaultVal;
+			const actualType = Array.isArray(projectVal) ? "array" : projectVal === null ? "null" : typeof projectVal;
+
+			if (expectedType === "object" && actualType === "object") {
+				// 递归校验嵌套对象
+				checkTypes(defaultVal, projectVal, fullKey);
+			} else if (expectedType !== actualType) {
+				errors.push({
+					section,
+					key: fullKey,
+					expectedType,
+					actualType,
+					description: `配置 "${section}.${fullKey}" 类型错误：期望 ${expectedType}，实际 ${actualType}`,
+				});
+			}
+		}
+	}
+
+	checkTypes(defaults, projectSection, "");
+	return errors;
+}

package/node_modules/@pi-atelier/shared-utils/src/project-tools.ts

@@ -0,0 +1,191 @@
+/**
+ * Tool/MCP Filtering — 三层合并的工具和 MCP 服务器过滤
+ *
+ * 配置优先级：defaults → 全局 settings.json → 项目 .pi/settings.json
+ * 数组策略：concat（项目级追加到全局，不是替换）
+ *
+ * 用法：
+ *   import { getEnabledTools, getDisabledMcpServers } from "@pi-atelier/shared-utils";
+ *
+ *   const disabledServers = getDisabledMcpServers(cwd);  // 全局 + 项目 concat
+ *   const tools = getEnabledTools(allTools, cwd);        // 三层合并后过滤
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { SETTINGS_PATH } from "./paths";
+import { readProjectSettings } from "./project-config";
+
+// ── 类型 ─────────────────────────────────────────────────
+
+export interface ToolFilter {
+	/** 额外启用的工具 ID 列表 */
+	enabled?: string[];
+	/** 禁用的工具 ID 列表 */
+	disabled?: string[];
+}
+
+// ── 内部工具 ─────────────────────────────────────────────
+
+/** 读取全局 settings.json 中的指定 section（直接读文件，不走 schema merge） */
+function readGlobalSection(section: string): Record<string, any> {
+	try {
+		if (!existsSync(SETTINGS_PATH)) return {};
+		const raw = readFileSync(SETTINGS_PATH, "utf-8");
+		const settings = JSON.parse(raw);
+		return settings?.[section] ?? {};
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * 获取有效工具过滤规则（三层合并：全局 → 项目，concat 策略）
+ */
+export function getEffectiveToolFilter(cwd: string): ToolFilter {
+	const globalFilter: ToolFilter = readGlobalSection("tools");
+	const projectSettings = readProjectSettings(cwd);
+	const projectFilter: ToolFilter = projectSettings?.tools ?? {};
+
+	// concat 策略：项目级追加到全局
+	const disabled = [...(globalFilter.disabled ?? []), ...(projectFilter.disabled ?? [])];
+	const enabled = [...(globalFilter.enabled ?? []), ...(projectFilter.enabled ?? [])];
+
+	return {
+		disabled: disabled.length > 0 ? disabled : undefined,
+		enabled: enabled.length > 0 ? enabled : undefined,
+	};
+}
+
+// ── API ─────────────────────────────────────────────────
+
+/**
+ * 获取过滤后的工具列表
+ *
+ * 三层合并全局 + 项目的 enabled/disabled 规则，对 allTools 进行过滤。
+ *
+ * @param allTools - 全部可用工具 ID 列表
+ * @param cwd - 当前项目目录
+ * @returns 过滤后的工具 ID 列表
+ */
+export function getEnabledTools(allTools: string[], cwd: string): string[] {
+	const filter = getEffectiveToolFilter(cwd);
+
+	let tools = [...allTools];
+
+	// 禁用优先
+	if (filter.disabled?.length) {
+		const disabledSet = new Set(filter.disabled);
+		tools = tools.filter((t) => !disabledSet.has(t));
+	}
+
+	// 额外启用（可能不在 allTools 里，给调用方自行处理）
+	if (filter.enabled?.length) {
+		const existingSet = new Set(tools);
+		for (const t of filter.enabled) {
+			if (!existingSet.has(t)) tools.push(t);
+		}
+	}
+
+	return tools;
+}
+
+/**
+ * 获取禁用的 MCP 服务器列表（三层合并：全局 + 项目 concat，enabled 白名单覆盖）
+ *
+ * 配置优先级：
+ *   1. 全局 settings.json 的 mcp.disabled — 全局禁用
+ *   2. 项目 .pi/settings.json 的 mcp.disabled — 项目级追加禁用
+ *   3. 项目 .pi/settings.json 的 mcp.enabled — 白名单，从 disabled 中移除
+ *
+ * 场景：全局禁用 godot/code-graph 等项目专用工具，
+ *       需要的项目在 .pi/settings.json 的 mcp.enabled 里显式启用。
+ *
+ * @param cwd - 当前项目目录
+ * @returns 去重后的禁用 MCP 服务器名称列表
+ */
+/**
+ * 将 glob 模式转为正则（只支持 * 通配符）
+ * "godot_export_*" → /^godot_export_.*$/
+ */
+function globToRegex(pattern: string): RegExp {
+	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&"); // 转义特殊字符
+	const withStar = escaped.replace(/\*/g, ".*"); // * → .*
+	return new RegExp(`^${withStar}$`);
+}
+
+/**
+ * 检查工具名是否匹配某个模式（精确匹配或 glob）
+ */
+function matchesPattern(toolName: string, patterns: string[]): boolean {
+	for (const pattern of patterns) {
+		if (pattern.includes("*")) {
+			if (globToRegex(pattern).test(toolName)) return true;
+		} else if (toolName === pattern) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * 获取禁用的 MCP 工具列表（三层合并：全局 + 项目 concat，enabled 白名单覆盖）
+ *
+ * 支持精确匹配和 glob 模式（* 通配符）：
+ *   - "godot_launch_editor" — 精确匹配
+ *   - "godot_export_*" — 匹配所有 godot_export_ 开头的工具
+ *
+ * @param cwd - 当前项目目录
+ * @returns 去重后的禁用工具名称模式列表
+ */
+export function getDisabledTools(cwd: string): string[] {
+	const globalMcp = readGlobalSection("mcp");
+	const globalTools: string[] = globalMcp?.tools?.disabled ?? [];
+
+	const projectSettings = readProjectSettings(cwd);
+	const projectMcp = projectSettings?.mcp ?? {};
+	const projectTools: string[] = projectMcp?.tools?.disabled ?? [];
+	const projectEnabled: string[] = projectMcp?.tools?.enabled ?? [];
+
+	// concat 全局 + 项目 disabled
+	const merged = [...globalTools, ...projectTools];
+
+	// 项目级 enabled 白名单覆盖
+	if (projectEnabled.length > 0) {
+		return [...new Set(merged.filter((p) => !projectEnabled.includes(p)))];
+	}
+
+	return [...new Set(merged)];
+}
+
+/**
+ * 检查工具是否应该被禁用
+ *
+ * @param toolName - 工具全名（如 "godot_launch_editor"）
+ * @param cwd - 当前项目目录
+ * @returns true 表示该工具应该被禁用
+ */
+export function isToolDisabled(toolName: string, cwd: string): boolean {
+	const patterns = getDisabledTools(cwd);
+	return matchesPattern(toolName, patterns);
+}
+
+export function getDisabledMcpServers(cwd: string): string[] {
+	const globalMcp = readGlobalSection("mcp");
+	const globalDisabled: string[] = globalMcp.disabled ?? [];
+
+	const projectSettings = readProjectSettings(cwd);
+	const projectMcp = projectSettings?.mcp ?? {};
+	const projectDisabled: string[] = projectMcp.disabled ?? [];
+	const projectEnabled: string[] = projectMcp.enabled ?? [];
+
+	// concat 全局 + 项目 disabled
+	const merged = [...globalDisabled, ...projectDisabled];
+
+	// 项目级 enabled 白名单覆盖：从 disabled 中移除
+	if (projectEnabled.length > 0) {
+		const enabledSet = new Set(projectEnabled);
+		return [...new Set(merged.filter((s) => !enabledSet.has(s)))];
+	}
+
+	return [...new Set(merged)];
+}

package/node_modules/@pi-atelier/shared-utils/src/settings-array.ts

@@ -0,0 +1,73 @@
+/**
+ * settings.json 数组 section 的 patch 操作
+ *
+ * 支持 packages / extensions / skills 等数组类型 section 的增删改。
+ * 匹配规则：对象按 source 字段匹配，字符串按精确匹配。
+ */
+
+// ── 类型 ─────────────────────────────────────────────────
+
+/** 数组元素匹配条件：对象按 source 字段匹配，字符串按精确匹配 */
+export type ArrayItemMatch = { source: string } | string;
+
+/** 数组替换操作 */
+export interface ArrayReplaceItem {
+	/** 匹配条件 */
+	match: ArrayItemMatch;
+	/** 替换后的值 */
+	replacement: any;
+}
+
+/** 数组 patch 操作（任选其一） */
+export interface ArrayPatch {
+	/** 添加元素（对象按 source 去重，字符串按精确去重） */
+	addItem?: any;
+	/** 删除元素 */
+	removeItem?: ArrayItemMatch;
+	/** 替换元素 */
+	replaceItem?: ArrayReplaceItem;
+}
+
+// ── 辅助函数 ─────────────────────────────────────────────
+
+/** 判断 patch 是否包含数组操作 */
+export function isArrayPatch(patch: any): patch is ArrayPatch {
+	return (
+		patch &&
+		typeof patch === "object" &&
+		("addItem" in patch || "removeItem" in patch || "replaceItem" in patch)
+	);
+}
+
+/** 判断两个数组元素是否匹配 */
+export function itemsMatch(a: any, b: ArrayItemMatch): boolean {
+	if (typeof b === "string") return a === b;
+	// 对象按 source 字段匹配
+	if (a && typeof a === "object" && "source" in a && "source" in b) return a.source === b.source;
+	// fallback：深度比较
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/** 对数组执行 patch 操作，返回新数组 */
+export function applyArrayPatch(arr: any[], patch: ArrayPatch): any[] {
+	const result = [...arr];
+
+	if (patch.removeItem !== undefined) {
+		const idx = result.findIndex((item) => itemsMatch(item, patch.removeItem!));
+		if (idx !== -1) result.splice(idx, 1);
+	}
+
+	if (patch.addItem !== undefined) {
+		// 去重检查
+		const exists = result.some((item) => itemsMatch(item, patch.addItem!));
+		if (!exists) result.push(patch.addItem);
+	}
+
+	if (patch.replaceItem !== undefined) {
+		const { match, replacement } = patch.replaceItem;
+		const idx = result.findIndex((item) => itemsMatch(item, match));
+		if (idx !== -1) result[idx] = replacement;
+	}
+
+	return result;
+}

package/node_modules/@pi-atelier/shared-utils/src/settings-backup-rollback.ts

@@ -0,0 +1,104 @@
+/**
+ * Settings 备份管理 — 回滚与列表
+ *
+ * 从 settings-backup.ts 拆分出的备份管理 API：
+ *   - rollbackSettings: 回滚到最近备份
+ *   - listBackups: 列出所有备份
+ *   - rotateBackups: 清理旧备份（内部函数）
+ */
+
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { withFileLock } from "./file-lock";
+import { parseTimestamp } from "./settings-backup-utils";
+
+export interface BackupEntry {
+	filename: string;
+	path: string;
+	timestamp: Date;
+	size: number;
+}
+
+export interface RollbackOptions {
+	settingsPath?: string;
+	backupDir?: string;
+}
+
+/** 清理超出 maxBackups 的旧备份 */
+export function rotateBackups(backupDir: string, maxBackups: number): void {
+	if (!existsSync(backupDir)) return;
+	const backups = listBackups({ backupDir });
+	while (backups.length > maxBackups) {
+		const oldest = backups.pop();
+		if (oldest) rmSync(oldest.path);
+	}
+}
+
+/**
+ * 回滚 settings.json 到最近一次备份
+ *
+ * @param options - 路径选项
+ * @throws 无备份时抛错
+ */
+export function rollbackSettings(options?: RollbackOptions): void {
+	const settingsPath = options?.settingsPath ?? "";
+	const backupDir = options?.backupDir ?? "";
+
+	const backups = listBackups({ backupDir });
+	if (backups.length === 0) {
+		throw new Error(`无可用备份：${backupDir}`);
+	}
+
+	const latestBackup = backups[0];
+	const content = readFileSync(latestBackup.path, "utf-8");
+
+	if (settingsPath) {
+		withFileLock(settingsPath, () => {
+			writeFileSync(settingsPath, content);
+		});
+	} else {
+		writeFileSync(settingsPath, content);
+	}
+
+	// 删除已恢复的备份
+	rmSync(latestBackup.path);
+}
+
+/**
+ * 列出所有备份（按时间倒序，最新的在前）
+ */
+export function listBackups(options?: RollbackOptions): BackupEntry[] {
+	const backupDir = options?.backupDir ?? "";
+
+	if (!existsSync(backupDir)) return [];
+
+	try {
+		const files = readdirSync(backupDir)
+			.filter((f) => f.startsWith("settings.") && f.endsWith(".json"))
+			.map((f) => {
+				const fullPath = join(backupDir, f);
+				try {
+					const { statSync } = require("node:fs");
+					const s = statSync(fullPath);
+					return {
+						filename: f,
+						path: fullPath,
+						timestamp: parseTimestamp(f) ?? new Date(0),
+						size: s.size,
+					};
+				} catch {
+					return {
+						filename: f,
+						path: fullPath,
+						timestamp: parseTimestamp(f) ?? new Date(0),
+						size: 0,
+					};
+				}
+			})
+			.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+
+		return files;
+	} catch {
+		return [];
+	}
+}

package/node_modules/@pi-atelier/shared-utils/src/settings-backup-utils.ts

@@ -0,0 +1,75 @@
+/**
+ * settings-backup 内部工具函数
+ *
+ * 备份目录管理、时间戳格式化、文件读写等。
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ── 常量 ─────────────────────────────────────────────────
+
+/** 默认备份子目录名 */
+export const DEFAULT_BACKUP_DIR_SUFFIX = "settings-backup";
+
+// ── 内部工具 ─────────────────────────────────────────────
+
+/** 格式化时间戳为文件名安全字符串（与原版行为一致） */
+export function formatTimestamp(date: Date): string {
+	return date.toISOString().replace(/[.:]/g, "-");
+}
+
+/** 从备份文件名解析时间戳 */
+export function parseTimestamp(filename: string): Date | null {
+	const match = filename.match(/^settings\.(.+)\.json$/);
+	if (!match) return null;
+	const isoStr = match[1].replace(/-/g, (m, offset) => {
+		const chars = match[1];
+		if (offset === 4 || offset === 7) return "-";
+		if (offset === 10) return "T";
+		if (offset === 13 || offset === 16) return ":";
+		if (offset === 19) return ".";
+		return "-";
+	});
+	const d = new Date(isoStr);
+	return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/** 获取默认备份目录 */
+export function getDefaultBackupDir(settingsPath: string): string {
+	return settingsPath ? join(settingsPath, "..", DEFAULT_BACKUP_DIR_SUFFIX) : "";
+}
+
+/** 创建备份 */
+export function createBackup(settingsPath: string, backupDir: string): string {
+	mkdirSync(backupDir, { recursive: true });
+	const content = readFileSync(settingsPath, "utf-8");
+	const backupPath = join(backupDir, `settings.${formatTimestamp(new Date())}.json`);
+	writeFileSync(backupPath, content);
+	return backupPath;
+}
+
+/** 清理超出 maxBackups 的旧备份 */
+export function rotateBackups(backupDir: string, maxBackups: number, listBackupsFn: (opts: any) => any[]): void {
+	if (!existsSync(backupDir)) return;
+	const backups = listBackupsFn({ backupDir });
+	while (backups.length > maxBackups) {
+		const oldest = backups.pop();
+		if (oldest) rmSync(oldest.path);
+	}
+}
+
+/** 读取完整 settings.json */
+export function readFull(settingsPath: string): Record<string, any> {
+	try {
+		if (!existsSync(settingsPath)) return {};
+		return JSON.parse(readFileSync(settingsPath, "utf-8"));
+	} catch {
+		return {};
+	}
+}
+
+/** 写入完整 settings.json */
+export function writeFull(settingsPath: string, settings: Record<string, any>): void {
+	writeFileSync(settingsPath, `${JSON.stringify(settings, null, "\t")}\n`);
+}