dsh-plugin-prompt-tool 0.5.0 → 0.6.0

package/lib/index.mjs

@@ -1,11 +1,11 @@
-import { C as DEFAULT_PRESET_DIR, D as LEGACY_USER_PRESETS_DIR, E as LEGACY_CONTAINER_DIR, S as userPresetsDir, T as DEFAULT_SKILLS_DIR, _ as removeUserPreset, a as asString, b as resolvePresetParams, c as duplicateUserPreset, d as listPresets, f as loadPresetContent, g as parseImportedPresetId, h as packageEngineDir, i as applyModuleConfigs, l as ensurePresetSeed, m as openPresetLocation, n as mergePromptConfigs, o as assertCompositionArray, p as loadPresetSpec, r as renderPromptConfigYaml, s as cloneBuiltinPreset, t as loadPromptConfigFiles, u as listBuiltinTemplates, v as renderComposition, w as DEFAULT_RESIDENT_AGENTS_PATH, x as savePresetParams, y as resolvePresetDir } from "./prompt-configs-k7wuZs0C.mjs";
+import { C as userPresetsDir, D as DEFAULT_SKILLS_DIR, E as DEFAULT_RESIDENT_AGENTS_PATH, O as LEGACY_CONTAINER_DIR, S as savePresetParams, T as DEFAULT_PRESET_DIR, _ as readPluginState, a as asString, b as resolvePresetDir, c as duplicateUserPreset, d as listPresets, f as loadPresetContent, g as parseImportedPresetId, h as packageEngineDir, i as applyModuleConfigs, k as LEGACY_USER_PRESETS_DIR, l as ensurePresetSeed, m as openPresetLocation, n as mergePromptConfigs, o as assertCompositionArray, p as loadPresetSpec, r as renderPromptConfigYaml, s as cloneBuiltinPreset, t as loadPromptConfigFiles, u as listBuiltinTemplates, v as removeUserPreset, w as writePluginState, x as resolvePresetParams, y as renderComposition } from "./prompt-configs-ThS4iXPg.mjs";
 import { settingsNamespace } from "@deepseek-ai/dsh-settings";
 import { appendFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { parse, parseDocument, stringify } from "yaml";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import z from "@deepseek-ai/schemastery";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region src/runtime/skills-watcher.ts
 /** 技能目录文件 watcher（多目录）：任一目录变化防抖 300ms 后触发 onRefresh；单目录不可 watch 时跳过。 */
@@ -551,13 +551,16 @@ function installSubagentModelRoute(ctx, isEnabled, provider, model) {
 	});
 }
 //#endregion
-//#region src/config.ts
-/** 插件配置、settings 数据模型与默认常量（settings 接口层）。 */
-const NS = settingsNamespace("prompt-tool");
+//#region src/shared/param-keys.ts
 /**
 * 引擎行为参数键（按预设存储：激活预设 preset.yml 的 params + promptConfigs）。
 * 不进 Config schema、不进 settings namespace——每预设一份，随预设走（官方范式：
 * Config = 部署轴，引擎行为在预设文件）。
+*
+* 这些键在 UI 有专门编辑入口（模型设置 / 工具与深度 / 开关），writePreset 把
+* 预设级 params 合并进每条 promptConfig 的 params 时排除——「params（高级参数
+* JSON）」框只保留内容变量与配置自身策略参数，避免 UI 已管理的参数冗余回写。
+* 放 shared：host（write-preset）与 config/settings-bridge 共用，单一来源。
 */
 const PARAM_KEYS = /* @__PURE__ */ new Set([
 	"firstTurnAnchor",
@@ -575,7 +578,6 @@ const PARAM_KEYS = /* @__PURE__ */ new Set([
 	"subagentReasoningEffort",
 	"subagentTemperature",
 	"subagentMaxTokens",
-	"mainPersona",
 	"subagentPersona",
 	"toolFilterAllow",
 	"toolFilterDeny",
@@ -587,6 +589,10 @@ const PARAM_KEYS = /* @__PURE__ */ new Set([
 	"injectPrompt",
 	"promptConfigs"
 ]);
+//#endregion
+//#region src/config.ts
+/** 插件配置、settings 数据模型与默认常量（settings 接口层）。 */
+const NS = settingsNamespace("prompt-tool");
 const Config = z.object({
 	injectAgentsPrompt: z.boolean().default(false),
 	writeAgents: z.boolean().default(true),
@@ -845,26 +851,42 @@ function fixSkillEntry(skillsDir, folder) {
 }
 //#endregion
 //#region src/host/sillytavern.ts
+/**
+* SillyTavern 预设 → 本项目单文件预设转换引擎（纯函数，无文件 IO）。
+*
+* 按需转换原则：只按注入层级映射 SillyTavern 实际内容，不注入本项目默认内容。
+*   - prompts[] → promptConfigs：system_prompt+role=system → system-section（可拼接）；
+*     其余 → pre-step（role/position/dedupe 按 ST 语义）；
+*   - 角色卡正文（chara_card_v3：data 内层；旧版顶层直存）→ promptConfigs：
+*     description/personality/scenario 拼接为「角色设定」system-section，
+*     system_prompt / post_history_instructions → system-section，
+*     first_mes → pre-step 开场白（dedupe=session 每会话一次）；
+*   - 采样参数（temperature/openai_max_tokens/reasoning_effort）**不转译**：
+*     模型参数由「模型设置」UI 统一管理（预设级 params.model*，writePreset 渲染
+*     agent-request patch），ST 卡固化值会覆盖用户在模型设置里的设置，故剥离；
+*   - modules 按需组装：prompt-config-engine 始终，system-section 注入需要
+*     persona（complete: false 允许 system-section 生效）。
+*/
 /** ST 运行时指令（渲染时执行、不发送给模型）：setvar/getvar/ERA/trim/注释 → 剥离。 */
 const ST_DIRECTIVE = /\{\{(setvar|getvar|ERA|trim|\/\/)[^}]*\}\}/gi;
 /**
 * 处理 SillyTavern 文本，ST 变量语义 → 本项目 params fallback 插值：
 *   {{setvar::k::v}}        → 收集 k=v 进 params（会话变量初始值 = fallback 基准），指令剥离；
 *   {{getvar::k}}           → 改写为 {{k}}（引擎按 params 插值，无值保留原样）；
-*   {{getvar::k::default}}  → 改写为 {{k}} 且 params 缺 k 时写入 default（fallback 落 params）；
+*   {{getvar::k::default}}  → 改写为 {{k}} 且 variables 缺 k 时写入 default（fallback 落顶层 variables）；
 *   {{trim}}/{{//注释}}/{{ERA:...}} → 剥离（格式化/注释/第三方运行时）；
 *   {{user}}/{{char}}       → 替换占位符。
 */
-function processStText(text, cardName, params) {
-	let cleaned = text.replace(/\{\{getvar::([A-Za-z0-9_.\u4e00-\u9fff-]+)::([^}]*)\}\}/g, (_whole, key, fallback) => {
-		if (!(key in params) && fallback.length > 0) params[key] = fallback;
-		return `{{${key}}}`;
-	});
-	cleaned = cleaned.replace(/\{\{getvar::([A-Za-z0-9_.\u4e00-\u9fff-]+)\}\}/g, (_whole, key) => `{{${key}}}`);
-	cleaned = cleaned.replace(/\{\{setvar::([A-Za-z0-9_.\u4e00-\u9fff-]+)::([^}]*)\}\}/g, (_whole, key, value) => {
-		params[key] = value;
+function processStText(text, cardName, variables) {
+	let cleaned = text.replace(/\{\{setvar::([A-Za-z0-9_.\u4e00-\u9fff-]+)::([^}]*)\}\}/g, (_whole, key, value) => {
+		variables[key] = value;
 		return "";
 	});
+	cleaned = cleaned.replace(/\{\{getvar::([A-Za-z0-9_.\u4e00-\u9fff-]+)::([^}]*)\}\}/g, (_whole, key, fallback) => {
+		if (!Object.prototype.hasOwnProperty.call(variables, key) && fallback.length > 0) variables[key] = fallback;
+		return `{{${key}}}`;
+	});
+	cleaned = cleaned.replace(/\{\{getvar::([A-Za-z0-9_.\u4e00-\u9fff-]+)\}\}/g, (_whole, key) => Object.prototype.hasOwnProperty.call(variables, key) ? `{{${key}}}` : "");
 	cleaned = cleaned.replace(ST_DIRECTIVE, "");
 	cleaned = cleaned.replace(/\{\{char\}\}/gi, cardName.trim().length > 0 ? cardName.trim() : "角色").replace(/\{\{user\}\}/gi, "用户").replace(/\n{3,}/g, "\n\n").trim();
 	return cleaned;
@@ -877,6 +899,7 @@ function mergeStPresets(specs) {
 		if (config === null || typeof config !== "object" || Array.isArray(config)) continue;
 		const entry = config;
 		const base = String(entry.id ?? "");
+		if (base.length === 0) continue;
 		let id = base;
 		for (let suffix = 2; seen.has(id); suffix++) id = `${base}-${suffix}`;
 		seen.add(id);
@@ -933,8 +956,8 @@ function convertStToPreset(card, baseName) {
 	}
 	const bodyText = (key) => typeof body[key] === "string" ? body[key].trim() : "";
 	const cardName = typeof record.name === "string" && record.name.trim().length > 0 ? record.name.trim() : typeof body.name === "string" && body.name.trim().length > 0 ? body.name.trim() : "";
-	const params = {};
-	const clean = (text) => processStText(text, cardName, params);
+	const variables = {};
+	const clean = (text) => processStText(text, cardName, variables);
 	const characterDefinitionClean = clean([
 		bodyText("description"),
 		bodyText("personality"),
@@ -979,32 +1002,40 @@ function convertStToPreset(card, baseName) {
 		systemSectionCount += 1;
 	}
 	const book = body.character_book;
-	if (book !== null && typeof book === "object" && !Array.isArray(book) && Array.isArray(book.entries)) for (const [index, entry] of book.entries.entries()) {
-		if (entry === null || typeof entry !== "object") continue;
-		const content = clean(typeof entry.content === "string" ? entry.content : "");
-		if (content.length === 0) continue;
-		const comment = typeof entry.comment === "string" && entry.comment.trim().length > 0 ? entry.comment.trim() : `世界书 ${String(entry.id ?? index)}`;
-		const keys = Array.isArray(entry.keys) ? entry.keys.map(String).filter((key) => key.trim().length > 0) : [];
-		const secondaryKeys = Array.isArray(entry.secondary_keys) ? entry.secondary_keys.map(String).filter((key) => key.trim().length > 0) : [];
-		const constant = entry.constant === true;
-		configs.push({
-			id: `lore-${String(entry.id ?? index)}`,
-			name: comment,
-			enabled: entry.enabled !== false,
-			strategy: "world-book",
-			order: typeof entry.insertion_order === "number" ? entry.insertion_order : 100,
-			text: content,
-			layer: "pre-step",
-			position: "before-all",
-			params: {
-				constant,
-				...keys.length > 0 ? { keys } : {},
-				...secondaryKeys.length > 0 ? { secondaryKeys } : {},
-				...entry.case_sensitive === true ? { caseSensitive: true } : {},
-				...entry.match_whole_words === true ? { wholeWords: true } : {},
-				...entry.use_regex === true ? { useRegex: true } : {}
-			}
-		});
+	if (book !== null && typeof book === "object" && !Array.isArray(book)) {
+		const rawEntries = book.entries;
+		const entryList = Array.isArray(rawEntries) ? rawEntries : rawEntries !== null && typeof rawEntries === "object" ? Object.values(rawEntries).filter((e) => e !== null && typeof e === "object" && !Array.isArray(e)) : [];
+		for (const [index, entry] of entryList.entries()) {
+			if (entry === null || typeof entry !== "object") continue;
+			const content = clean(typeof entry.content === "string" ? entry.content : "");
+			if (content.length === 0) continue;
+			const comment = typeof entry.comment === "string" && entry.comment.trim().length > 0 ? entry.comment.trim() : `世界书 ${String(entry.id ?? entry.uid ?? index)}`;
+			const rawKeys = entry.keys ?? entry.key;
+			const keys = Array.isArray(rawKeys) ? rawKeys.map(String).filter((key) => key.trim().length > 0) : [];
+			const rawSecondary = entry.secondary_keys ?? entry.keysecondary;
+			const secondaryKeys = Array.isArray(rawSecondary) ? rawSecondary.map(String).filter((key) => key.trim().length > 0) : [];
+			const constant = entry.constant === true || entry.add_always === true;
+			const enabled = entry.disable !== void 0 ? entry.disable !== true : entry.enabled !== false;
+			configs.push({
+				id: `lore-${String(entry.id ?? entry.uid ?? index)}`,
+				name: comment,
+				enabled,
+				strategy: "world-book",
+				order: typeof entry.insertion_order === "number" ? entry.insertion_order : typeof entry.order === "number" ? entry.order : 100,
+				text: content,
+				layer: "pre-step",
+				position: "before-all",
+				params: {
+					constant,
+					...keys.length > 0 ? { keys } : {},
+					...secondaryKeys.length > 0 ? { secondaryKeys } : {},
+					...(entry.case_sensitive ?? entry.caseSensitive) === true ? { caseSensitive: true } : {},
+					...(entry.match_whole_words ?? entry.matchWholeWords) === true ? { wholeWords: true } : {},
+					...(entry.use_regex ?? entry.useRegex) === true ? { useRegex: true } : {},
+					...typeof entry.selectiveLogic === "number" ? { selectiveLogic: entry.selectiveLogic } : typeof entry.selective_logic === "number" ? { selectiveLogic: entry.selective_logic } : {}
+				}
+			});
+		}
 	}
 	const firstMes = clean(bodyText("first_mes"));
 	if (firstMes.length > 0) configs.push({
@@ -1042,9 +1073,9 @@ function convertStToPreset(card, baseName) {
 		const base = {
 			id,
 			name: typeof prompt.name === "string" && prompt.name.length > 0 ? prompt.name : id,
-			enabled: orderDisabled.has(id) ? false : prompt.enabled !== false,
+			enabled: orderDisabled.has(rawId) ? false : prompt.enabled !== false,
 			strategy: "static",
-			order: (orderIndex.get(id) ?? index) * 10,
+			order: ((rawId.length > 0 ? orderIndex.get(rawId) : void 0) ?? index) * 10,
 			text: content
 		};
 		if (role === "system") {
@@ -1063,9 +1094,6 @@ function convertStToPreset(card, baseName) {
 			dedupe: "none"
 		});
 	}
-	if (typeof record.temperature === "number") params.modelTemperature = String(record.temperature);
-	if (typeof record.openai_max_tokens === "number" && record.openai_max_tokens > 0) params.modelMaxTokens = String(record.openai_max_tokens);
-	if (typeof record.reasoning_effort === "string" && record.reasoning_effort.trim().length > 0) params.modelReasoningEffort = record.reasoning_effort.trim();
 	const modules = ["prompt-config-engine"];
 	const moduleConfigs = {};
 	if (systemSectionCount > 0) {
@@ -1082,18 +1110,57 @@ function convertStToPreset(card, baseName) {
 			deny: ["web_search", "web_fetch"]
 		};
 	}
+	const presetId = stPresetId(baseName);
+	const RUNTIME_MACROS = /* @__PURE__ */ new Set([
+		"lastusermessage",
+		"lastcharmessage",
+		"charifnotgroup"
+	]);
+	const BUILTIN_KEYS = /* @__PURE__ */ new Set([
+		"DSH_HOME",
+		"WORKSPACE",
+		"CWD"
+	]);
+	const MACRO_RE = /\{\{([A-Za-z0-9_.\u4e00-\u9fff-]+)\}\}/g;
+	const knownKeys = new Set(Object.keys(variables).map((key) => key.toLowerCase()));
+	for (const config of configs) {
+		const configRecord = config;
+		const texts = [
+			...typeof config.text === "string" && config.text.length > 0 ? [config.text] : [],
+			...Array.isArray(config.texts) ? config.texts : [],
+			...typeof configRecord.params?.text === "string" ? [configRecord.params.text] : []
+		];
+		for (const raw of texts) {
+			const text = String(raw);
+			MACRO_RE.lastIndex = 0;
+			for (const match of text.matchAll(MACRO_RE)) {
+				const key = match[1];
+				const lower = key.toLowerCase();
+				if (knownKeys.has(lower) || RUNTIME_MACROS.has(lower) || BUILTIN_KEYS.has(key)) continue;
+				knownKeys.add(lower);
+				variables[key] = "";
+			}
+		}
+	}
 	return {
-		id: baseName.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff]+/g, "-").replace(/^-+|-+$/g, "") || "sillytavern",
+		id: presetId,
 		name: `${cardName || baseName}（SillyTavern 转换）`,
 		version: "1.0.0",
 		engineCompat: ">=0.4.2",
 		meta: { source: "sillytavern" },
-		...Object.keys(params).length > 0 ? { params } : {},
+		...Object.keys(variables).length > 0 ? { variables } : {},
 		modules,
 		moduleConfigs,
 		promptConfigs: configs
 	};
 }
+/** ST 导入预设 id：必须是官方 agent-presets 可发现的目录名（PRESET_ID =
+*  /^[a-z0-9][a-z0-9-]*$/——含中文的目录会被宿主 discovery 静默跳过，会话
+*  resume 报 preset not found）。文件名 slug 化（去中文）；纯中文名退化为
+*  st-<文件名短哈希>（唯一且合法）；显示名 name 仍保留中文原名。 */
+function stPresetId(baseName) {
+	return baseName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || `st-${createHash("sha1").update(baseName).digest("hex").slice(0, 6)}`;
+}
 //#endregion
 //#region src/host/characters.ts
 /** 角色卡库：独立于预设根的素材+参数存储（预设根下点前缀目录，官方 discovery 跳过）。
@@ -1326,7 +1393,7 @@ function removeCharacterFromPreset(presetRoot, templateName, cardId) {
 				return !isCard;
 			});
 			doc.setIn(["promptConfigs"], kept);
-			for (const key of Object.keys(spec?.params ?? {})) doc.deleteIn(["params", key]);
+			for (const [key, value] of Object.entries(spec?.params ?? {})) if (doc.getIn(["params", key]) === value) doc.deleteIn(["params", key]);
 			const list = Array.isArray(current.meta?.importedCharacters) ? current.meta.importedCharacters : [];
 			doc.setIn(["meta", "importedCharacters"], list.filter((entry) => String(entry) !== cardId));
 		});
@@ -1363,6 +1430,7 @@ const BRIDGE_ENDPOINTS = {
 	presetContent: "/preset-content",
 	importPreset: "/import-preset",
 	paramOverrides: "/param-overrides",
+	presetVariables: "/preset-variables",
 	importPresetPackage: "/import-preset-package",
 	exportPreset: "/export-preset",
 	presetDelete: "/preset-delete",
@@ -1898,6 +1966,64 @@ function registerSettingsBridge(ctx, ns, getModelsState, getSkillsState, getEngi
 						}
 					}
 				}),
+				sctx.webServer.register({
+					kind: "exact",
+					path: SETTINGS_BRIDGE_PREFIX + BRIDGE_ENDPOINTS.presetVariables,
+					handler: async (req, res) => {
+						if (!guard(req, res)) return;
+						const dir = getPresetConfigsDir?.() ?? "";
+						if (dir.length === 0) {
+							writeBridgeJson(res, 400, {
+								ok: false,
+								code: "preset-dir-unavailable",
+								message: "presetDir 未配置"
+							});
+							return;
+						}
+						const presetRoot = dirname(dir);
+						const templateName = basename(dir);
+						const { body } = await readBridgeBody(req);
+						const record = body ?? {};
+						if (record.variables === void 0 && record.enabled === void 0) {
+							try {
+								const spec = loadPresetSpec(dir);
+								const variables = {};
+								for (const [key, value] of Object.entries(spec.params ?? {})) if (!PARAM_KEYS.has(key) && typeof value === "string") variables[key] = value;
+								for (const [key, value] of Object.entries(spec.variables ?? {})) if (typeof value === "string") variables[key] = value;
+								writeBridgeJson(res, 200, {
+									ok: true,
+									value: {
+										variables,
+										enabled: spec.variablesEnabled !== false
+									}
+								});
+							} catch {
+								writeBridgeJson(res, 200, {
+									ok: true,
+									value: {
+										variables: {},
+										enabled: true
+									}
+								});
+							}
+							return;
+						}
+						try {
+							savePresetParams(presetRoot, templateName, void 0, void 0, record.variables !== null && typeof record.variables === "object" && !Array.isArray(record.variables) ? record.variables : void 0, typeof record.enabled === "boolean" ? record.enabled : void 0);
+							afterOverridesChange?.();
+							writeBridgeJson(res, 200, {
+								ok: true,
+								value: { variables: record.variables }
+							});
+						} catch (error) {
+							writeBridgeJson(res, 409, {
+								ok: false,
+								code: "preset-variables-rejected",
+								message: `模板变量保存失败：${error instanceof Error ? error.message : String(error)}`
+							});
+						}
+					}
+				}),
 				sctx.webServer.register({
 					kind: "exact",
 					path: SETTINGS_BRIDGE_PREFIX + BRIDGE_ENDPOINTS.importPresetPackage,
@@ -2270,7 +2396,8 @@ function registerSettingsBridge(ctx, ns, getModelsState, getSkillsState, getEngi
 							const path = typeof f.path === "string" && f.path.length > 0 ? f.path : "";
 							const content = typeof f.content === "string" ? f.content : "";
 							if (path.length === 0) return [];
-							if (path.includes("..") || /^[a-zA-Z]:/.test(path) || path.startsWith("/") || path.startsWith("\\")) return [];
+							if (/^[a-zA-Z]:/.test(path) || path.startsWith("/") || path.startsWith("\\")) return [];
+							if (path.split(/[\\/]/).some((segment) => segment === "..")) return [];
 							return [{
 								path,
 								content
@@ -2459,7 +2586,7 @@ function registerSettingsBridge(ctx, ns, getModelsState, getSkillsState, getEngi
 }
 //#endregion
 //#region src/runtime/character-tools.ts
-const text$1 = (text) => [{
+const text$2 = (text) => [{
 	type: "text",
 	text
 }];
@@ -2497,7 +2624,7 @@ function registerCharacterTools(ctx, host) {
 						}
 					} }
 				},
-				render: (_args, value) => text$1(JSON.stringify(value.characters))
+				render: (_args, value) => text$2(JSON.stringify(value.characters))
 			},
 			execute: async () => ({ characters: listCharacterCards(host.presetRoot(), host.templateName()) })
 		}));
@@ -2531,7 +2658,7 @@ function registerCharacterTools(ctx, host) {
 						}
 					}
 				},
-				render: (_args, value) => text$1(`角色卡已入库：${value.name}（id=${value.id}）。调用 character_apply 可应用到当前预设。`)
+				render: (_args, value) => text$2(`角色卡已入库：${value.name}（id=${value.id}）。调用 character_apply 可应用到当前预设。`)
 			},
 			execute: async (args) => {
 				const result = importCharacterCard(host.presetRoot(), [{
@@ -2568,7 +2695,7 @@ function registerCharacterTools(ctx, host) {
 						}
 					}
 				},
-				render: (_args, value) => text$1(`已导入到当前预设（${value.count} 条配置），生成目录已重建。`)
+				render: (_args, value) => text$2(`已导入到当前预设（${value.count} 条配置），生成目录已重建。`)
 			},
 			execute: async (args) => {
 				const result = applyCharacterToPreset(host.presetRoot(), host.templateName(), args.id);
@@ -2603,7 +2730,7 @@ function registerCharacterTools(ctx, host) {
 						}
 					}
 				},
-				render: (_args, value) => text$1(`已从当前预设移除（${value.count} 条配置），生成目录已重建。`)
+				render: (_args, value) => text$2(`已从当前预设移除（${value.count} 条配置），生成目录已重建。`)
 			},
 			execute: async (args) => {
 				const result = removeCharacterFromPreset(host.presetRoot(), host.templateName(), args.id);
@@ -2632,7 +2759,7 @@ function registerCharacterTools(ctx, host) {
 						required: true
 					} }
 				},
-				render: (_args, value) => text$1(`角色卡 ${value.id} 已从库中删除。`)
+				render: (_args, value) => text$2(`角色卡 ${value.id} 已从库中删除。`)
 			},
 			execute: async (args) => {
 				const result = deleteCharacterCard(host.presetRoot(), args.id);
@@ -2644,7 +2771,7 @@ function registerCharacterTools(ctx, host) {
 }
 //#endregion
 //#region src/runtime/world-book-tools.ts
-const text = (text) => [{
+const text$1 = (text) => [{
 	type: "text",
 	text
 }];
@@ -2723,7 +2850,7 @@ function registerWorldBookTools(ctx, host) {
 						}
 					} }
 				},
-				render: (_args, value) => text(JSON.stringify(value.entries))
+				render: (_args, value) => text$1(JSON.stringify(value.entries))
 			},
 			execute: async () => {
 				return { entries: readConfigs(host.activeDir()).filter((config) => config.strategy === "world-book").map((config) => ({
@@ -2737,7 +2864,7 @@ function registerWorldBookTools(ctx, host) {
 		}));
 		toolsCtx.tools.register(defineTool({
 			name: "world_book_upsert",
-			description: "新增或更新当前预设的一条世界书条目（world-book 策略配置）：按 id 更新（不存在则新增，id 自动生成 lore-<n>）。constant=true 常驻注入；否则命中 keys（或 secondaryKeys）任一关键字注入；无 keys 条目按全局每次注入。note 可选：写入来源角色卡的本地记忆（memory.md，条目 id 带 chara-<卡>- 前缀时）或预设记忆。写盘后立即重建生成目录。",
+			description: "新增或更新当前预设的一条世界书条目（world-book 策略配置）：按 id 更新（不存在则新增，id 自动生成 lore-<n>）。constant=true 常驻注入；否则命中 keys（或 secondaryKeys）任一关键字注入；无 keys 条目按全局每次注入。note 可选：写入来源角色卡的持久记忆（memory.md，条目 id 带 chara-<卡>- 前缀时）或预设记忆——持久记忆跨会话跟随角色卡（与 session_var 会话变量的临时状态不同，适合长期关系记录）。写盘后立即重建生成目录。",
 			parameters: {
 				id: {
 					type: "string",
@@ -2777,7 +2904,7 @@ function registerWorldBookTools(ctx, host) {
 				},
 				note: {
 					type: "string",
-					description: "可选：操作笔记，写入来源角色卡记忆或预设记忆。"
+					description: "可选：操作笔记，写入来源角色卡持久记忆（memory.md，跨会话跟随角色卡）或预设记忆。"
 				}
 			},
 			output: {
@@ -2795,7 +2922,7 @@ function registerWorldBookTools(ctx, host) {
 						}
 					}
 				},
-				render: (_args, value) => text(`世界书条目 ${value.id} 已保存（当前共 ${value.count} 条），生成目录已重建。`)
+				render: (_args, value) => text$1(`世界书条目 ${value.id} 已保存（当前共 ${value.count} 条），生成目录已重建。`)
 			},
 			execute: async (args) => {
 				const dir = host.activeDir();
@@ -2831,7 +2958,7 @@ function registerWorldBookTools(ctx, host) {
 		}));
 		toolsCtx.tools.register(defineTool({
 			name: "world_book_delete",
-			description: "删除当前预设的一条世界书条目（world_book_list 获取 id）。note 可选：写入来源角色卡记忆或预设记忆。删除后立即重建生成目录。",
+			description: "删除当前预设的一条世界书条目（world_book_list 获取 id）。note 可选：写入来源角色卡持久记忆（memory.md，跨会话跟随角色卡）或预设记忆。删除后立即重建生成目录。",
 			parameters: {
 				id: {
 					type: "string",
@@ -2840,7 +2967,7 @@ function registerWorldBookTools(ctx, host) {
 				},
 				note: {
 					type: "string",
-					description: "可选：操作笔记。"
+					description: "可选：操作笔记，写入来源角色卡持久记忆（memory.md）或预设记忆。"
 				}
 			},
 			output: {
@@ -2858,7 +2985,7 @@ function registerWorldBookTools(ctx, host) {
 						}
 					}
 				},
-				render: (_args, value) => text(`世界书条目 ${value.id} 已删除（剩余 ${value.count} 条），生成目录已重建。`)
+				render: (_args, value) => text$1(`世界书条目 ${value.id} 已删除（剩余 ${value.count} 条），生成目录已重建。`)
 			},
 			execute: async (args) => {
 				const dir = host.activeDir();
@@ -2877,6 +3004,112 @@ function registerWorldBookTools(ctx, host) {
 	});
 }
 //#endregion
+//#region src/runtime/session-var-tools.ts
+const text = (value) => [{
+	type: "text",
+	text: value
+}];
+function registerSessionVarTools(ctx) {
+	ctx.inject(["tools"], (toolsCtx) => {
+		toolsCtx.tools.register(defineTool({
+			name: "session_var",
+			description: "会话变量管理（SillyTavern setvar/getvar 语义）：list 查看当前会话全部变量、get 读取、set 设置、clear 清除。提示词/世界书文本中的 {{变量名}} 会在注入时替换为会话变量值（会话级覆盖预设默认值）；适合维护角色状态（如 {{心情}}、{{接受度}} 等）。注意：会话变量仅存于当前会话（结束即失）；跨会话长期记忆请用 world_book 工具的 note 参数写入角色卡记忆（持久，跟随角色卡）。",
+			parameters: {
+				action: {
+					type: "string",
+					enum: [
+						"list",
+						"get",
+						"set",
+						"clear"
+					],
+					required: true,
+					description: "操作：list / get / set / clear"
+				},
+				key: {
+					type: "string",
+					description: "变量名（get / set / clear 时必填；支持中文与下划线）"
+				},
+				value: {
+					type: "string",
+					description: "变量值（set 时必填；空串表示清除该变量）"
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						ok: {
+							type: "boolean",
+							required: true
+						},
+						error: { type: "string" },
+						variables: {
+							type: "object",
+							additionalProperties: true
+						},
+						key: { type: "string" },
+						value: { type: "string" }
+					}
+				},
+				render: (_args, value) => text(JSON.stringify(value))
+			},
+			execute: async (args, exec) => {
+				const session = exec.agent?.session;
+				if (session === void 0) return {
+					ok: false,
+					error: "no active session"
+				};
+				const { sessionVarsSnapshot, getSessionVar, setSessionVar, clearSessionVars } = await import(new URL("../engine/session-vars.mjs", import.meta.url).href);
+				const record = args ?? {};
+				const action = typeof record.action === "string" ? record.action : "";
+				const key = typeof record.key === "string" ? record.key : "";
+				if (action === "list") return {
+					ok: true,
+					variables: sessionVarsSnapshot(session)
+				};
+				if (action === "get") {
+					if (key.length === 0) return {
+						ok: false,
+						error: "get 需要 key"
+					};
+					return {
+						ok: true,
+						key,
+						value: getSessionVar(session, key) ?? ""
+					};
+				}
+				if (action === "set") {
+					if (key.length === 0) return {
+						ok: false,
+						error: "set 需要 key"
+					};
+					const value = typeof record.value === "string" ? record.value : "";
+					if (value.length === 0) clearSessionVars(session, key);
+					else setSessionVar(session, key, value);
+					return {
+						ok: true,
+						key,
+						value
+					};
+				}
+				if (action === "clear") {
+					clearSessionVars(session, key.length > 0 ? key : void 0);
+					return {
+						ok: true,
+						key
+					};
+				}
+				return {
+					ok: false,
+					error: `未知 action: ${action}`
+				};
+			}
+		}));
+	});
+}
+//#endregion
 //#region src/runtime/tui.ts
 /** dsh-tui 全局开关：键名与 settings 路径一致（settings mutate）。 */
 const TUI_GLOBAL_SWITCHES = [
@@ -3292,6 +3525,11 @@ function engineFingerprint() {
 	return parts.sort().join("|");
 }
 const ENGINE_FINGERPRINT_MARKER = ".pt-engine-fingerprint";
+/** 剥离文本中的预设级变量引用（{{key}} → 空串）；内置变量（{{DSH_HOME}} 等）保留。
+*  模板变量插值停用时由 writePreset 调用，避免 {{key}} 残留导致官方渲染 unknown variable。 */
+function stripVariableRefs(text, keys) {
+	return text.replace(/\{\{([A-Za-z0-9_.\u4e00-\u9fff-]+)\}\}/g, (whole, key) => keys.has(key) ? "" : whole);
+}
 /** Windows 瞬时文件锁（杀软/宿主短读）下的重试：rename/写文件失败最多重试 3 次、间隔 400ms。 */
 function withLockRetry(action, retries = 3) {
 	for (let attempt = 0;; attempt++) try {
@@ -3326,7 +3564,6 @@ function runtimeOf(options, prompt) {
 		toolFilterAllow: options.toolFilterAllow !== void 0 && (Array.isArray(options.toolFilterAllow) ? options.toolFilterAllow.length > 0 : String(options.toolFilterAllow).trim().length > 0) ? options.toolFilterAllow : void 0,
 		toolFilterDeny: options.toolFilterDeny !== void 0 && (Array.isArray(options.toolFilterDeny) ? options.toolFilterDeny.length > 0 : String(options.toolFilterDeny).trim().length > 0) ? options.toolFilterDeny : void 0,
 		maxDepth: options.maxDepth,
-		mainPersona: typeof options.mainPersona === "string" && options.mainPersona.trim().length > 0 ? options.mainPersona : void 0,
 		allowKinds: options.allowKinds,
 		firstTurnWord: typeof options.firstTurnWord === "string" && options.firstTurnWord.length > 0 ? options.firstTurnWord : void 0
 	};
@@ -3371,7 +3608,7 @@ function modelRequestConfigs(params) {
 function writePreset(prompt, options) {
 	const presetDir = options.presetDir.trim().length > 0 ? options.presetDir : DEFAULT_PRESET_DIR;
 	const templateName = typeof options.presetTemplate === "string" && options.presetTemplate.trim().length > 0 ? options.presetTemplate.trim() : "anchored";
-	if (!/^[a-zA-Z0-9\u4e00-\u9fff_-]+$/.test(templateName)) throw new Error(`invalid presetTemplate ${JSON.stringify(templateName)}: must be a bare directory name`);
+	if (!/^[a-z0-9][a-z0-9-]*$/.test(templateName)) throw new Error(`invalid presetTemplate ${JSON.stringify(templateName)}: must match official agent-presets id /^[a-z0-9][a-z0-9-]*$/`);
 	const templateDir = resolvePresetDir(templateName);
 	const spec = loadPresetSpec(templateDir);
 	const worldBook = spec.worldBook;
@@ -3529,11 +3766,17 @@ function writePreset(prompt, options) {
 		});
 		else templateDefaults = [];
 		const merged = mergePromptConfigs(modelRequestConfigs(params), templateDefaults, options.promptConfigs);
+		const presetVariables = {};
+		for (const [key, value] of Object.entries(spec.params ?? {})) {
+			if (PARAM_KEYS.has(key)) continue;
+			const text = String(value);
+			if (text.length > 0) presetVariables[key] = text;
+		}
+		for (const [key, value] of Object.entries(spec.variables ?? {})) if (typeof value === "string" && value.length > 0) presetVariables[key] = value;
+		const variablesEnabled = spec.variablesEnabled !== false;
+		const presetVariableKeys = new Set(Object.keys(presetVariables));
+		if (variablesEnabled && presetVariableKeys.size > 0) writeFileSync(join(promptConfigsDir, "variables.yml"), stringify(presetVariables), "utf8");
 		for (const [index, config] of merged.entries()) {
-			config.params = {
-				...params,
-				...config.params
-			};
 			if (config.id === "prompt-injector") {
 				delete config.text;
 				config.texts = [];
@@ -3549,6 +3792,15 @@ function writePreset(prompt, options) {
 				agentsInstructionPath: `../${templateName}/agents-instruction.md`,
 				...options.injectAgentsPrompt === true ? { text: asString(options.agentsInstructionText) } : {}
 			};
+			if (!variablesEnabled && presetVariableKeys.size > 0) {
+				const strip = (item) => stripVariableRefs(item, presetVariableKeys);
+				config.texts = (config.texts ?? []).map(strip);
+				if (typeof config.text === "string") config.text = strip(config.text);
+				if (typeof config.params?.text === "string") config.params = {
+					...config.params,
+					text: strip(config.params.text)
+				};
+			}
 			writeFileSync(join(promptConfigsDir, `${String(index * 10).padStart(2, "0")}-${config.id}.yml`), renderPromptConfigYaml(config), "utf8");
 		}
 		for (const legacy of spec.legacyCleanup ?? []) rmSync(join(outDir, legacy), { force: true });
@@ -3733,7 +3985,6 @@ function apply(ctx, configIn) {
 		runtime.bootstrapMaxTokens = Number.isSafeInteger(params.bootstrapMaxTokens) && params.bootstrapMaxTokens >= 0 ? params.bootstrapMaxTokens : 0;
 		runtime.usePtcMode = params.usePtcMode !== false;
 		runtime.injectPrompt = params.injectPrompt !== false;
-		runtime.mainPersona = asString(params.mainPersona) || void 0;
 		runtime.subagentPersona = asString(params.subagentPersona) || void 0;
 		runtime.toolFilterAllow = params.toolFilterAllow;
 		runtime.toolFilterDeny = params.toolFilterDeny;
@@ -3765,7 +4016,6 @@ function apply(ctx, configIn) {
 				subagentReasoningEffort: runtime.subagentReasoningEffort,
 				subagentTemperature: runtime.subagentTemperature,
 				subagentMaxTokens: runtime.subagentMaxTokens,
-				mainPersona: runtime.mainPersona,
 				subagentPersona: runtime.subagentPersona,
 				toolFilterAllow: runtime.toolFilterAllow,
 				toolFilterDeny: runtime.toolFilterDeny,
@@ -3797,13 +4047,26 @@ function apply(ctx, configIn) {
 				}
 			}
 			writePreset(presetPrompt, options);
-		} else try {
-			rmSync(runtime.presetDir, {
-				recursive: true,
-				force: true
-			});
-		} catch (error) {
-			warn(ctx, "prompt-tool: failed to remove " + runtime.presetDir + ": " + String(error));
+		} else {
+			let cleaned = 0;
+			for (const preset of listPresets()) {
+				const dir = join(runtime.presetDir, preset.id);
+				for (const name of [
+					"agent.cordis.yml",
+					"prompt-configs",
+					"preset.md",
+					"agents.md",
+					"agents-instruction.md",
+					"engine"
+				]) try {
+					rmSync(join(dir, name), {
+						recursive: true,
+						force: true
+					});
+				} catch {}
+				cleaned += 1;
+			}
+			warn(ctx, `prompt-tool: writePreset 已关闭，清理 ${cleaned} 个预设目录的生成物（preset.yml 参数保留）`);
 		}
 	};
 	/** 激活预设目录（内容按预设根 presetDir/<template>/ 隔离；非法名回退 anchored）。 */
@@ -3845,7 +4108,6 @@ function apply(ctx, configIn) {
 		if (typeof overrides.subagentReasoningEffort === "string") runtime.subagentReasoningEffort = overrides.subagentReasoningEffort;
 		if (typeof overrides.subagentTemperature === "string") runtime.subagentTemperature = overrides.subagentTemperature;
 		if (typeof overrides.subagentMaxTokens === "string") runtime.subagentMaxTokens = overrides.subagentMaxTokens;
-		if (typeof overrides.mainPersona === "string" && overrides.mainPersona.trim().length > 0) runtime.mainPersona = overrides.mainPersona;
 		if (typeof overrides.subagentPersona === "string") runtime.subagentPersona = overrides.subagentPersona;
 		if (typeof overrides.firstTurnWord === "string") runtime.firstTurnWord = overrides.firstTurnWord;
 		if (typeof overrides.bootstrapMaxTokens === "number") runtime.bootstrapMaxTokens = overrides.bootstrapMaxTokens;
@@ -4034,7 +4296,6 @@ function apply(ctx, configIn) {
 		subagentMaxTokens: asString(initialParams.subagentMaxTokens),
 		bootstrapMaxTokens: Number.isSafeInteger(initialParams.bootstrapMaxTokens) && initialParams.bootstrapMaxTokens >= 0 ? initialParams.bootstrapMaxTokens : 0,
 		usePtcMode: initialParams.usePtcMode !== false,
-		mainPersona: asString(initialParams.mainPersona) || void 0,
 		subagentPersona: asString(initialParams.subagentPersona) || void 0,
 		toolFilterAllow: initialParams.toolFilterAllow,
 		toolFilterDeny: initialParams.toolFilterDeny,
@@ -4054,6 +4315,10 @@ function apply(ctx, configIn) {
 		const s = hostSettingsService;
 		if (s === void 0) return;
 		const template = runtime.presetTemplate;
+		if (!/^[a-z0-9][a-z0-9-]*$/.test(template)) {
+			warn(ctx, `prompt-tool: 预设 id ${JSON.stringify(template)} 不符合官方 agent-presets 命名（^[a-z0-9][a-z0-9-]*$），跳过宿主 default 同步；请将预设目录改名为合法 id`);
+			return;
+		}
 		if (reason === "switch" && lastSyncedHostDefault === template) return;
 		lastSyncedHostDefault = template;
 		try {
@@ -4116,7 +4381,6 @@ function apply(ctx, configIn) {
 			modelName: "",
 			subagentModelProvider: "",
 			subagentModelName: "",
-			mainPersona: "",
 			subagentPersona: "",
 			injectAgentsPrompt: false,
 			bootstrapMaxTokens: 0,
@@ -4214,6 +4478,7 @@ function apply(ctx, configIn) {
 			}
 		}
 	});
+	registerSessionVarTools(ctx);
 	const settingsEntry = currentSource();
 	const ensureRegistered = (sctx) => ensureSettingsRegistered(sctx, NS, PromptSettingsSchema, {
 		base: () => settingsEntry,
@@ -4234,11 +4499,21 @@ function apply(ctx, configIn) {
 		},
 		onError: (message) => warn(ctx, `prompt-tool: settings register failed: ${message}`)
 	});
-	/** 阶段 2 迁移：旧全局 settings 引擎参数 → 激活预设 preset.yml（一次性，标记后跳过）。 */
-	const PARAMS_MIGRATED_MARK = ".pt-params-migrated";
+	/** 阶段 2 迁移：旧全局 settings 引擎参数 → 激活预设 preset.yml（一次性，state.paramsMigrated 后跳过）。
+	*  兼容旧版预设根内 .pt-params-migrated 标记：存在即视为已迁移，并迁入状态文件后删除。 */
 	const migrateSettingsParamsToPreset = (sctx) => {
-		const mark = join(runtime.presetDir, PARAMS_MIGRATED_MARK);
-		if (existsSync(mark)) return;
+		const legacyMark = join(runtime.presetDir, ".pt-params-migrated");
+		const state = readPluginState();
+		if (state.paramsMigrated === true || existsSync(legacyMark)) {
+			if (existsSync(legacyMark)) try {
+				writePluginState({
+					...state,
+					paramsMigrated: true
+				});
+				rmSync(legacyMark, { force: true });
+			} catch {}
+			return;
+		}
 		let userSection = {};
 		try {
 			const descriptor = sctx.settings.describe({ redactSecrets: true }).find((entry) => String(entry.ns) === String(NS));
@@ -4252,7 +4527,10 @@ function apply(ctx, configIn) {
 		if (Object.keys(params).length === 0 && promptConfigs === void 0) {
 			try {
 				mkdirSync(runtime.presetDir, { recursive: true });
-				writeFileSync(mark, "", "utf8");
+				writePluginState({
+					...readPluginState(),
+					paramsMigrated: true
+				});
 			} catch {}
 			return;
 		}
@@ -4265,12 +4543,18 @@ function apply(ctx, configIn) {
 				written++;
 			} catch {}
 			if (written === 0) {
-				writeFileSync(mark, "", "utf8");
+				writePluginState({
+					...readPluginState(),
+					paramsMigrated: true
+				});
 				return;
 			}
 			reloadPresetParams();
 			rebuildPreset();
-			writeFileSync(mark, "", "utf8");
+			writePluginState({
+				...readPluginState(),
+				paramsMigrated: true
+			});
 			warn(ctx, `prompt-tool: 已把旧全局 settings 参数迁移到 ${written} 个预设 preset.yml（每预设独立存储）`);
 		} catch (error) {
 			warn(ctx, `prompt-tool: settings 参数迁移失败（下次启动重试）：${error instanceof Error ? error.message : String(error)}`);
@@ -4292,4 +4576,4 @@ function apply(ctx, configIn) {
 	});
 }
 //#endregion
-export { BRIDGE_ENDPOINTS, Config, PARAM_KEYS, PromptSettingsSchema, SETTINGS_BRIDGE_PREFIX, SKILL_NAME_RE, apply, applyModuleConfigs, cloneBuiltinPreset, createCachedSkillsReader, detectModels, ensurePresetSeed, ensureSettingsRegistered, ensureWebSurface, fixSkillEntry, inject, installDefaultModelRoute, isValidSkill, listAdvertisedModels, listBuiltinTemplates, listPresets, listSkillFolders, loadPresetSpec, loadPromptTemplates, mergeSkillDirs, migrateLegacyLayout, name, normalizePresetRootDir, parseFrontmatter, readSkills, registerCharacterTools, registerSettingsBridge, registerTuiCommand, registerWorldBookTools, removeUserPreset, resolvePresetDir, resolvePresetParams, resolveProfileDir, resolveProfileSkillsDir, savePresetParams, toKebabName, userPresetsDir, validSkills, validatePromptConfigs, writePreset };
+export { BRIDGE_ENDPOINTS, Config, PARAM_KEYS, PromptSettingsSchema, SETTINGS_BRIDGE_PREFIX, SKILL_NAME_RE, apply, applyModuleConfigs, cloneBuiltinPreset, createCachedSkillsReader, detectModels, ensurePresetSeed, ensureSettingsRegistered, ensureWebSurface, fixSkillEntry, inject, installDefaultModelRoute, isValidSkill, listAdvertisedModels, listBuiltinTemplates, listPresets, listSkillFolders, loadPresetSpec, loadPromptTemplates, mergeSkillDirs, migrateLegacyLayout, name, normalizePresetRootDir, parseFrontmatter, readPluginState, readSkills, registerCharacterTools, registerSettingsBridge, registerTuiCommand, registerWorldBookTools, removeUserPreset, resolvePresetDir, resolvePresetParams, resolveProfileDir, resolveProfileSkillsDir, savePresetParams, stPresetId, toKebabName, userPresetsDir, validSkills, validatePromptConfigs, writePluginState, writePreset };