mioku-service-webui 4.13.0 → 4.15.0

package/config-page-loader.ts

@@ -51,7 +51,7 @@ export function loadAdapterConfigPage(adapterName: string): ConfigPageManifest |
 }
 
 /** 从机器人根目录按 node_modules 依赖解析包真实目录（pnpm / 提升安装等布局） */
-function resolvePackageDir(root: string, packageName: string): string | null {
+export function resolvePackageDir(root: string, packageName: string): string | null {
   const require = createRequire(path.join(root, "package.json"));
   try {
     return path.dirname(require.resolve(`${packageName}/package.json`));

package/database.ts

@@ -1,3 +1,4 @@
+import { getConfigDefaults, withConfigDefaults } from "mioku";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { Database } from "bun:sqlite";
@@ -359,7 +360,12 @@ export function getPluginConfigs(pluginName: string): Record<string, any> {
 
   for (const file of files) {
     const filePath = path.join(pluginDir, file);
-    result[path.basename(file, ".json")] = readJsonFile(filePath, {});
+    const configName = path.basename(file, ".json");
+    // 磁盘值覆盖插件登记的默认值，缺字段时页面也能拿到完整配置
+    result[configName] = withConfigDefaults(
+      readJsonFile(filePath, {}),
+      getConfigDefaults("plugin", pluginName, configName),
+    );
   }
 
   return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-service-webui",
-  "version": "4.13.0",
+  "version": "4.15.0",
   "description": "Mioku WebUI 服务",
   "main": "index.ts",
   "type": "module",

package/routes/agent.ts

@@ -31,78 +31,44 @@ function sanitizeAccess(input: any): any {
   };
 }
 
+/**
+ * 保存时只做「不该写进这个文件」的剔除，不补默认值。
+ *
+ * 默认值由 agent 插件在 `registerConfig` 时登记、读取时深合并
+ * （`mergeAgentConfig`）——这里再抄一份，加字段时就会两边漂移。
+ */
 function sanitizeBaseForSave(body: any): any {
   if (!body || typeof body !== "object") return body;
   const next = { ...body };
   delete next.persona;
   delete next.roleBindings;
-  next.access = sanitizeAccess(next.access);
-  next.workspaceDir = String(next.workspaceDir ?? "").trim();
-  next.permissionLevel = PERMISSION_LEVELS.has(next.permissionLevel)
-    ? next.permissionLevel
-    : "workspace-write";
-  next.model = String(next.model ?? "").trim();
+  if (next.access !== undefined) next.access = sanitizeAccess(next.access);
+  if (typeof next.workspaceDir === "string") {
+    next.workspaceDir = next.workspaceDir.trim();
+  }
+  if (typeof next.model === "string") next.model = next.model.trim();
+  if (!PERMISSION_LEVELS.has(next.permissionLevel)) delete next.permissionLevel;
   return next;
 }
 
 function sanitizeSettingsForSave(body: any): any {
   if (!body || typeof body !== "object") return body;
   const next = { ...body };
-  const positive = (value: unknown, fallback: number) => {
-    const num = Math.floor(Number(value));
-    return Number.isFinite(num) && num > 0 ? num : fallback;
-  };
-  const nonNegative = (value: unknown, fallback: number) => {
-    const num = Math.floor(Number(value));
-    return Number.isFinite(num) && num >= 0 ? num : fallback;
-  };
+  // 这两个属于 chat 插件的 base 配置，老版本 UI 可能还会带上来
   delete next.temperature;
   delete next.enableMediaRecognition;
-  next.maxIterations = positive(next.maxIterations, 500);
-  next.maxContextTokens = positive(next.maxContextTokens, 524288);
-  next.stream = next.stream !== false;
-  next.enableMarkdownScreenshot = next.enableMarkdownScreenshot !== false;
-  next.compaction = {
-    enabled: next.compaction?.enabled !== false,
-    keepRecentMessages: positive(next.compaction?.keepRecentMessages, 20),
-  };
-  next.webSearch = {
-    enabled: next.webSearch?.enabled !== false,
-    baseUrl: String(next.webSearch?.baseUrl ?? "").trim(),
-    timeoutMs: positive(next.webSearch?.timeoutMs, 8000),
-    defaultLimit: positive(next.webSearch?.defaultLimit, 5),
-    maxLimit: positive(next.webSearch?.maxLimit, 8),
-    maxSearchCount: positive(next.webSearch?.maxSearchCount, 50),
-  };
-  next.webFetch = {
-    enabled: next.webFetch?.enabled !== false,
-    timeoutMs: positive(next.webFetch?.timeoutMs, 15000),
-    maxChars: positive(next.webFetch?.maxChars, 12000),
-  };
-  next.bash = {
-    enabled: next.bash?.enabled !== false,
-    timeoutMs: positive(next.bash?.timeoutMs, 120000),
-    approvalTimeoutMs: positive(next.bash?.approvalTimeoutMs, 300000),
-  };
-  next.skills = {
-    enabled: next.skills?.enabled !== false,
-    extraRoots: Array.isArray(next.skills?.extraRoots)
-      ? next.skills.extraRoots
-          .map((item: unknown) => String(item ?? "").trim())
-          .filter(Boolean)
-      : [],
-    maxInPrompt: positive(next.skills?.maxInPrompt, 50),
-    descriptionMaxLength: positive(next.skills?.descriptionMaxLength, 500),
-    activationTtlMs: positive(next.skills?.activationTtlMs, 3_600_000),
-    rescanIntervalMs: nonNegative(next.skills?.rescanIntervalMs, 2000),
-    maxResourceFiles: positive(next.skills?.maxResourceFiles, 200),
-  };
-  next.dataCollection = { enabled: next.dataCollection?.enabled !== false };
-  next.mcp = {
-    enabled: next.mcp?.enabled !== false,
-    maxTools: nonNegative(next.mcp?.maxTools, 48),
-  };
-  next.debug = Boolean(next.debug);
+  if (
+    next.skills &&
+    typeof next.skills === "object" &&
+    Array.isArray(next.skills.extraRoots)
+  ) {
+    next.skills = {
+      ...next.skills,
+      extraRoots: next.skills.extraRoots
+        .map((item: unknown) => String(item ?? "").trim())
+        .filter(Boolean),
+    };
+  }
   return next;
 }
 
@@ -127,6 +93,20 @@ export function createAgentRoutes() {
     return c.json({ ok: true, data: updateAgentConfig("base.json", body) });
   });
 
+  // 记忆配置由 agent 插件自己归一化，这里只做读写
+  app.get("/memory", (c) =>
+    c.json({ ok: true, data: getAgentConfig("memory.json") }),
+  );
+
+  app.put("/memory", async (c) => {
+    const body = await c.req.json();
+    logger.info(`[webui-action] agent.memory.update`, {
+      enabled: body?.enabled,
+      retentionMonths: body?.retentionMonths,
+    });
+    return c.json({ ok: true, data: updateAgentConfig("memory.json", body) });
+  });
+
   app.get("/settings", (c) =>
     c.json({ ok: true, data: getAgentConfig("settings.json") }),
   );

package/routes/ai.ts

@@ -2,15 +2,14 @@ import { Hono } from "hono";
 import { logger } from "mioku";
 import { getChatConfig, updateChatConfig } from "../system";
 import { listStickerCatalog } from "../database";
+import {
+  readThemeCatalog,
+  updateThemeSelection,
+  writeCustomThemes,
+} from "../theme-packs";
 import aiService from "mioku-service-ai";
 import type { AIModelRole, AIProtocol, AIUsageRange } from "mioku";
 
-const DEFAULT_MEMORY_GROUP_HISTORY_LIMIT = 300;
-const DEFAULT_MEMORY_USER_HISTORY_LIMIT = 100;
-const DEFAULT_TOPIC_WINDOW_HOURS = 5;
-const DEFAULT_TOPIC_HISTORY_WINDOW_COUNT = 3;
-const DEFAULT_EXPRESSION_LEARN_AFTER_MESSAGES = 100;
-const DEFAULT_EXPRESSION_SAMPLE_SIZE = 8;
 const usageRanges = new Set<AIUsageRange>(["today", "7d", "30d"]);
 const protocols = new Set<AIProtocol>([
   "openai-chat",
@@ -24,111 +23,50 @@ function getAIApi() {
   return aiService?.api as any;
 }
 
-function normalizePersonalizationConfig(input: any): any {
-  const data =
-    input && typeof input === "object" && !Array.isArray(input)
-      ? { ...input }
-      : {};
-
-  const rawMemory =
-    data.memory && typeof data.memory === "object" && !Array.isArray(data.memory)
-      ? { ...data.memory }
-      : {};
-
-  delete rawMemory.maxIterations;
-  delete rawMemory.timeoutMs;
-
-  const groupHistoryLimit = Number(rawMemory.groupHistoryLimit);
-  const userHistoryLimit = Number(rawMemory.userHistoryLimit);
-
-  rawMemory.groupHistoryLimit =
-    Number.isFinite(groupHistoryLimit) && groupHistoryLimit > 0
-      ? Math.floor(groupHistoryLimit)
-      : DEFAULT_MEMORY_GROUP_HISTORY_LIMIT;
-  rawMemory.userHistoryLimit =
-    Number.isFinite(userHistoryLimit) && userHistoryLimit > 0
-      ? Math.floor(userHistoryLimit)
-      : DEFAULT_MEMORY_USER_HISTORY_LIMIT;
-  rawMemory.enabled =
-    typeof rawMemory.enabled === "boolean" ? rawMemory.enabled : true;
-
-  data.memory = rawMemory;
-
-  const rawTopic =
-    data.topic && typeof data.topic === "object" && !Array.isArray(data.topic)
-      ? { ...data.topic }
-      : {};
-
-  const windowHours = Number(rawTopic.windowHours);
-  const legacyTimeThresholdMs = Number(rawTopic.timeThresholdMs);
-  const historyWindowCount = Number(rawTopic.historyWindowCount);
-
-  rawTopic.enabled =
-    typeof rawTopic.enabled === "boolean" ? rawTopic.enabled : true;
-  rawTopic.windowHours =
-    Number.isFinite(windowHours) && windowHours > 0
-      ? Math.floor(windowHours)
-      : Number.isFinite(legacyTimeThresholdMs) && legacyTimeThresholdMs > 0
-        ? Math.max(1, Math.floor(legacyTimeThresholdMs / 3600_000))
-        : DEFAULT_TOPIC_WINDOW_HOURS;
-  rawTopic.historyWindowCount =
-    Number.isFinite(historyWindowCount) && historyWindowCount > 0
-      ? Math.floor(historyWindowCount)
-      : DEFAULT_TOPIC_HISTORY_WINDOW_COUNT;
-
-  delete rawTopic.messageThreshold;
-  delete rawTopic.timeThresholdMs;
-  delete rawTopic.maxTopicsPerSession;
-
-  data.topic = rawTopic;
-
-  const rawExpression =
+function stripDeadPersonalizationKeys(input: any): any {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
+  const data: Record<string, any> = { ...input };
+
+  delete data.memory;
+  delete data.planner;
+
+  if (
+    data.topic &&
+    typeof data.topic === "object" &&
+    !Array.isArray(data.topic)
+  ) {
+    const topic = { ...data.topic };
+    delete topic.timeThresholdMs;
+    delete topic.messageThreshold;
+    delete topic.maxTopicsPerSession;
+    data.topic = topic;
+  }
+
+  if (
     data.expression &&
     typeof data.expression === "object" &&
     !Array.isArray(data.expression)
-      ? { ...data.expression }
-      : {};
-
-  const learnAfterMessages = Number(rawExpression.learnAfterMessages);
-  const legacyMaxExpressions = Number(rawExpression.maxExpressions);
-  const sampleSize = Number(rawExpression.sampleSize);
-
-  rawExpression.enabled =
-    typeof rawExpression.enabled === "boolean" ? rawExpression.enabled : true;
-  rawExpression.learnAfterMessages =
-    Number.isFinite(learnAfterMessages) && learnAfterMessages > 0
-      ? Math.floor(learnAfterMessages)
-      : Number.isFinite(legacyMaxExpressions) && legacyMaxExpressions > 0
-        ? Math.floor(legacyMaxExpressions)
-        : DEFAULT_EXPRESSION_LEARN_AFTER_MESSAGES;
-  rawExpression.sampleSize =
-    Number.isFinite(sampleSize) && sampleSize > 0
-      ? Math.floor(sampleSize)
-      : DEFAULT_EXPRESSION_SAMPLE_SIZE;
-  delete rawExpression.maxExpressions;
-
-  data.expression = rawExpression;
-
-  const rawEmoji =
-    data.emoji && typeof data.emoji === "object" && !Array.isArray(data.emoji)
-      ? { ...data.emoji }
-      : {};
-  rawEmoji.enabled =
-    typeof rawEmoji.enabled === "boolean" ? rawEmoji.enabled : true;
-  rawEmoji.characters = Array.isArray(rawEmoji.characters)
-    ? rawEmoji.characters
-        .map(String)
-        .map((value: string) => value.trim())
-        .filter(Boolean)
-    : [];
-  rawEmoji.stickers = Array.isArray(rawEmoji.stickers)
-    ? rawEmoji.stickers
-        .map(String)
-        .map((value: string) => value.trim())
-        .filter(Boolean)
-    : [];
-  delete rawEmoji.useAISelection;
-  data.emoji = rawEmoji;
+  ) {
+    const expression = { ...data.expression };
+    delete expression.maxExpressions;
+    data.expression = expression;
+  }
+
+  if (
+    data.emoji &&
+    typeof data.emoji === "object" &&
+    !Array.isArray(data.emoji)
+  ) {
+    const emoji = { ...data.emoji };
+    delete emoji.useAISelection;
+    for (const key of ["characters", "stickers"] as const) {
+      if (!Array.isArray(emoji[key])) continue;
+      emoji[key] = emoji[key]
+        .map((item: unknown) => String(item ?? "").trim())
+        .filter(Boolean);
+    }
+    data.emoji = emoji;
+  }
 
   return data;
 }
@@ -180,14 +118,31 @@ export function createAIRoutes() {
     return c.json({ ok: true, data: updateChatConfig("base.json", body) });
   });
 
+  app.get("/themes", (c) => {
+    return c.json({ ok: true, data: readThemeCatalog() });
+  });
+
+  app.put("/themes", async (c) => {
+    logger.info(`[webui-action] ai.themes.update`);
+    return c.json({ ok: true, data: writeCustomThemes(await c.req.json()) });
+  });
+
+  app.put("/themes/selection", async (c) => {
+    logger.info(`[webui-action] ai.themes.select`);
+    return c.json({
+      ok: true,
+      data: updateThemeSelection(await c.req.json()),
+    });
+  });
+
   app.get("/personalization", (c) => {
-    const data = normalizePersonalizationConfig(
+    const data = stripDeadPersonalizationKeys(
       getChatConfig("personalization.json"),
     );
     return c.json({ ok: true, data });
   });
   app.put("/personalization", async (c) => {
-    const body = normalizePersonalizationConfig(await c.req.json());
+    const body = stripDeadPersonalizationKeys(await c.req.json());
     logger.info(`[webui-action] ai.personalization.update`);
     return c.json({
       ok: true,
@@ -195,6 +150,19 @@ export function createAIRoutes() {
     });
   });
 
+  // 记忆配置由 chat 插件自己归一化（缺字段/坏值在读取时兜底），这里只做读写
+  app.get("/memory", (c) =>
+    c.json({ ok: true, data: getChatConfig("memory.json") }),
+  );
+  app.put("/memory", async (c) => {
+    const body = await c.req.json();
+    logger.info(`[webui-action] ai.memory.update`, {
+      enabled: body?.enabled,
+      retentionMonths: body?.retentionMonths,
+    });
+    return c.json({ ok: true, data: updateChatConfig("memory.json", body) });
+  });
+
   app.get("/settings", (c) =>
     c.json({ ok: true, data: getChatConfig("settings.json") }),
   );
@@ -405,7 +373,9 @@ export function createAIRoutes() {
           .filter((id: string) => id.includes("/") && id.length > 1),
       ),
     );
-    logger.info(`[webui-action] ai.fallback.update`, { count: fallback.length });
+    logger.info(`[webui-action] ai.fallback.update`, {
+      count: fallback.length,
+    });
     api.setMainFallbackChain(fallback);
     const live = api.getMainFallbackChain?.() ?? fallback;
     return c.json({ ok: true, data: { fallback: live, liveFallback: live } });
@@ -496,9 +466,7 @@ export function createAIRoutes() {
     });
   });
 
-  app.get("/stickers", (c) =>
-    c.json({ ok: true, data: listStickerCatalog() }),
-  );
+  app.get("/stickers", (c) => c.json({ ok: true, data: listStickerCatalog() }));
 
   app.get("/usage", (c) => {
     const api = getAIApi();
@@ -512,8 +480,7 @@ export function createAIRoutes() {
         ? (rawRange as AIUsageRange)
         : "today";
     const rawBotId = c.req.query("botId");
-    const botId =
-      rawBotId && rawBotId !== "all" ? Number(rawBotId) : undefined;
+    const botId = rawBotId && rawBotId !== "all" ? Number(rawBotId) : undefined;
 
     if (botId !== undefined && !Number.isFinite(botId)) {
       return c.json({ ok: false, error: "INVALID_BOT_ID" }, 400);

package/system.ts

@@ -4,7 +4,13 @@ import * as path from "node:path";
 import process from "node:process";
 import AdmZip from "adm-zip";
 import systemInfo from "systeminformation";
-import { buildAdapterReport, connectedBots, logger } from "mioku";
+import {
+  buildAdapterReport,
+  connectedBots,
+  getConfigDefaults,
+  logger,
+  withConfigDefaults,
+} from "mioku";
 import type { AdapterInstanceStatus, Bot } from "mioku";
 import type {
   InstallRequest,
@@ -2389,9 +2395,21 @@ export async function getSaying(): Promise<{ text: string }> {
   return fetchYiyan();
 }
 
+/**
+ * 读插件配置：磁盘值覆盖默认值。
+ *
+ * 默认值只由插件在 `registerConfig` 时登记一次（见 mioku 的 config-defaults），
+ * WebUI 这边不再手抄字段——以前每加一个配置项，要在这里和插件各改一遍。
+ */
+function readPluginConfig(dir: string, owner: string, fileName: string): any {
+  const stored = readJsonFile(path.join(dir, fileName), {});
+  const name = fileName.replace(/\.json$/, "");
+  const defaults = getConfigDefaults("plugin", owner, name);
+  return withConfigDefaults(stored, defaults);
+}
+
 export function getChatConfig(fileName: string): any {
-  const filePath = path.join(CHAT_CONFIG_DIR, fileName);
-  return readJsonFile(filePath, {});
+  return readPluginConfig(CHAT_CONFIG_DIR, "chat", fileName);
 }
 
 export function updateChatConfig(fileName: string, data: any): any {
@@ -2401,8 +2419,7 @@ export function updateChatConfig(fileName: string, data: any): any {
 }
 
 export function getAgentConfig(fileName: string): any {
-  const filePath = path.join(AGENT_CONFIG_DIR, fileName);
-  return readJsonFile(filePath, {});
+  return readPluginConfig(AGENT_CONFIG_DIR, "agent", fileName);
 }
 
 export function updateAgentConfig(fileName: string, data: any): any {

package/theme-packs.ts

@@ -0,0 +1,311 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolvePackageDir } from "./config-page-loader";
+import { getChatConfig, updateChatConfig } from "./system";
+import { projectRoot } from "./utils";
+
+const BUILTIN_PREFIX = "builtin:";
+const CUSTOM_PREFIX = "custom:";
+const MAX_THEMES_PER_KIND = 100;
+const MAX_NAME = 40;
+const MAX_TEXT = 20_000;
+const MAX_STYLES = 40;
+const MAX_EXAMPLES = 200;
+const MAX_EXAMPLE = 500;
+
+export interface ReplyStyleTheme {
+  id: string;
+  name: string;
+  persona: string;
+  baseStyle: string;
+  multipleStyles: string[];
+  multipleProbability: number;
+  builtin: boolean;
+}
+
+export interface EmotionTheme {
+  id: string;
+  name: string;
+  defaultEmotion: string;
+  updateIntervalMs: number;
+  emotions: Record<string, { examples: string[] }>;
+  builtin: boolean;
+}
+
+export interface ThemeCatalog {
+  reply: ReplyStyleTheme[];
+  emotion: EmotionTheme[];
+}
+
+export interface ThemeSelection {
+  replyStyleTheme: string;
+  emotionTheme: string;
+}
+
+interface RawReplyTheme {
+  id: string;
+  name: string;
+  persona: string;
+  baseStyle: string;
+  multipleStyles: string[];
+  multipleProbability: number;
+}
+
+interface RawEmotionTheme {
+  id: string;
+  name: string;
+  defaultEmotion: string;
+  updateIntervalMs: number;
+  emotions: Record<string, { examples: string[] }>;
+}
+
+function resolveChatPluginDir(): string | null {
+  const root = projectRoot();
+  const local = path.join(root, "plugins", "chat");
+  if (fs.existsSync(path.join(local, "themes", "builtin.json"))) return local;
+  return resolvePackageDir(root, "mioku-plugin-chat");
+}
+
+let builtinCache: {
+  key: string;
+  reply: RawReplyTheme[];
+  emotion: RawEmotionTheme[];
+} | null = null;
+
+function emptyBuiltin(): {
+  reply: RawReplyTheme[];
+  emotion: RawEmotionTheme[];
+} {
+  return { reply: [], emotion: [] };
+}
+
+function readBuiltinPacks(): {
+  reply: RawReplyTheme[];
+  emotion: RawEmotionTheme[];
+} {
+  const dir = resolveChatPluginDir();
+  if (!dir) return emptyBuiltin();
+  const file = path.join(dir, "themes", "builtin.json");
+  if (!fs.existsSync(file)) return emptyBuiltin();
+
+  try {
+    const stat = fs.statSync(file);
+    const key = `${file}:${stat.mtimeMs}:${stat.size}`;
+    if (builtinCache?.key === key) {
+      return builtinCache;
+    }
+    const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+    const stats = {
+      key,
+      reply: normalizeReplyList(parsed?.reply, { allowBuiltin: true }),
+      emotion: normalizeEmotionList(parsed?.emotion, { allowBuiltin: true }),
+    };
+    builtinCache = stats;
+    return stats;
+  } catch {
+    return emptyBuiltin();
+  }
+}
+
+export function readThemeCatalog(): ThemeCatalog {
+  const builtin = readBuiltinPacks();
+  const custom = getChatConfig("themes.json") || {};
+  return {
+    reply: [
+      ...builtin.reply.map((theme) => ({ ...theme, builtin: true })),
+      ...normalizeReplyList(custom.reply, { allowBuiltin: false }).map(
+        (theme) => ({ ...theme, builtin: false }),
+      ),
+    ],
+    emotion: [
+      ...builtin.emotion.map((theme) => ({ ...theme, builtin: true })),
+      ...normalizeEmotionList(custom.emotion, { allowBuiltin: false }).map(
+        (theme) => ({ ...theme, builtin: false }),
+      ),
+    ],
+  };
+}
+
+/** 只写用户主题包；内置主题永远来自插件代码 */
+export function writeCustomThemes(body: unknown): ThemeCatalog {
+  const source = isRecord(body) ? body : {};
+  const next = {
+    reply: normalizeReplyList(source.reply, { allowBuiltin: false }),
+    emotion: normalizeEmotionList(source.emotion, { allowBuiltin: false }),
+  };
+  updateChatConfig("themes.json", next);
+  return readThemeCatalog();
+}
+
+export function updateThemeSelection(body: unknown): ThemeSelection {
+  const source = isRecord(body) ? body : {};
+  const catalog = readThemeCatalog();
+  const current = getChatConfig("personalization.json") || {};
+
+  const next: Record<string, unknown> = { ...current };
+  if ("replyStyleTheme" in source) {
+    next.replyStyleTheme = resolveSelection(
+      source.replyStyleTheme,
+      catalog.reply,
+    );
+  }
+  if ("emotionTheme" in source) {
+    next.emotionTheme = resolveSelection(source.emotionTheme, catalog.emotion);
+  }
+  updateChatConfig("personalization.json", next);
+
+  return {
+    replyStyleTheme: normalizeId(next.replyStyleTheme),
+    emotionTheme: normalizeId(next.emotionTheme),
+  };
+}
+
+function resolveSelection(
+  value: unknown,
+  themes: Array<{ id: string }>,
+): string {
+  const id = normalizeId(value);
+  if (!id) return "";
+  return themes.some((theme) => theme.id === id) ? id : "";
+}
+
+function normalizeId(value: unknown): string {
+  if (typeof value !== "string") return "";
+  const id = value.trim();
+  if (!id || id.length > 100) return "";
+  if (!id.startsWith(BUILTIN_PREFIX) && !id.startsWith(CUSTOM_PREFIX))
+    return "";
+  return id;
+}
+
+function normalizeReplyList(
+  raw: unknown,
+  options: { allowBuiltin: boolean },
+): RawReplyTheme[] {
+  if (!Array.isArray(raw)) return [];
+  const result: RawReplyTheme[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    if (!isRecord(item)) continue;
+    const id = normalizeId(item.id);
+    if (!isThemeIdAllowed(id, options.allowBuiltin) || seen.has(id)) continue;
+    const name = readText(item.name, MAX_NAME);
+    if (!name) continue;
+    seen.add(id);
+    result.push({
+      id,
+      name,
+      persona: readText(item.persona, MAX_TEXT),
+      baseStyle: readText(item.baseStyle, MAX_TEXT),
+      multipleStyles: readTextList(item.multipleStyles, MAX_STYLES, MAX_TEXT),
+      multipleProbability: readProbability(item.multipleProbability),
+    });
+    if (result.length >= MAX_THEMES_PER_KIND) break;
+  }
+  return result;
+}
+
+function normalizeEmotionList(
+  raw: unknown,
+  options: { allowBuiltin: boolean },
+): RawEmotionTheme[] {
+  if (!Array.isArray(raw)) return [];
+  const result: RawEmotionTheme[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    if (!isRecord(item)) continue;
+    const id = normalizeId(item.id);
+    if (!isThemeIdAllowed(id, options.allowBuiltin) || seen.has(id)) continue;
+    const name = readText(item.name, MAX_NAME);
+    if (!name) continue;
+    const emotions = normalizeEmotions(item.emotions);
+    seen.add(id);
+    result.push({
+      id,
+      name,
+      emotions,
+      defaultEmotion: pickDefaultEmotion(item.defaultEmotion, emotions),
+      updateIntervalMs: readInterval(item.updateIntervalMs),
+    });
+    if (result.length >= MAX_THEMES_PER_KIND) break;
+  }
+  return result;
+}
+
+function isThemeIdAllowed(id: string, allowBuiltin: boolean): boolean {
+  if (!id) return false;
+  return allowBuiltin || !id.startsWith(BUILTIN_PREFIX);
+}
+
+function normalizeEmotions(
+  raw: unknown,
+): Record<string, { examples: string[] }> {
+  const emotions: Record<string, { examples: string[] }> = {};
+  if (isRecord(raw)) {
+    for (const [rawName, value] of Object.entries(raw)) {
+      const name = readEmotionName(rawName);
+      if (!name || emotions[name]) continue;
+      emotions[name] = {
+        examples: readTextList(
+          isRecord(value) ? value.examples : undefined,
+          MAX_EXAMPLES,
+          MAX_EXAMPLE,
+        ),
+      };
+    }
+  }
+  if (!emotions.default) emotions.default = { examples: [] };
+  return emotions;
+}
+
+function readEmotionName(value: unknown): string {
+  if (typeof value !== "string") return "";
+  return value.trim().toLowerCase().slice(0, 20);
+}
+
+function pickDefaultEmotion(
+  raw: unknown,
+  emotions: Record<string, { examples: string[] }>,
+): string {
+  const name = readEmotionName(raw);
+  return name && emotions[name] ? name : "default";
+}
+
+function readInterval(value: unknown): number {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return 60 * 60_000;
+  return Math.min(30 * 24 * 60 * 60_000, Math.max(60_000, Math.round(num)));
+}
+
+function readProbability(value: unknown): number {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return 0.2;
+  return Math.min(1, Math.max(0, num));
+}
+
+function readText(value: unknown, maxLength: number): string {
+  return typeof value === "string" ? value.slice(0, maxLength) : "";
+}
+
+function readTextList(
+  value: unknown,
+  maxItems: number,
+  maxLength: number,
+): string[] {
+  if (!Array.isArray(value)) return [];
+  const result: string[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== "string") continue;
+    const text = item.trim();
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    result.push(text.slice(0, maxLength));
+    if (result.length >= maxItems) break;
+  }
+  return result;
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}