llm-api-gateway-cli 1.0.0

package/lib/settings.js

@@ -0,0 +1,517 @@
+/**
+ * 配置持久化与校验（R2）
+ *
+ * 在这之前，「用户想改的东西」散在三处：命令行 flag、环境变量、以及浏览器 localStorage。
+ * 清一次缓存就丢，换台机器就没了，而且用户说不清「我到底改的是哪一个、为什么没生效」。
+ *
+ * 这个模块定三件事，且只此一份：
+ *   1. **唯一白名单** —— 哪些键能改、取值范围是什么；未知键明确报错并列出可用键；
+ *   2. **唯一优先级** —— `--flag` > 环境变量 > `config.json` > 内置默认（沿用 lib/config.js 的既有口径，不引入第二个真相）；
+ *   3. **唯一实现** —— Web 的 `/api/settings` 与 CLI 的 `gateway-agent config` 共用它，
+ *      不会出现「页面能改、命令行改不了」或者两边校验规则不一致。
+ *
+ * 红线：**密钥永远不落盘**。这里没有 `key` 这个字段，并且会拒绝任何像密钥的键或值。
+ * 密钥来源仍然是 `lib/config.js` 的 resolveKey（--key > SK / GATEWAY_KEY / OPENAI_API_KEY / … > .env）。
+ *
+ * 默认值一律等于现状代码里的常量 —— 加配置不改变默认行为。
+ */
+
+import path from 'node:path';
+import os from 'node:os';
+import { readFileSync, mkdirSync } from 'node:fs';
+
+import { DEFAULT_BASE_URL } from './common.js';
+import { MODES, AGENT_LIMITS } from './agent.js';
+import { TTL_DAYS, MAX_TASKS, defaultStoreRoot } from './taskstore.js';
+import { TASK_SESSION_MAX_BYTES, HISTORY_MAX_CHARS, HISTORY_KEEP_RECENT_TURNS } from './tasksession.js';
+import { writeJsonAtomic } from './jsonstore.js';
+
+export const SETTINGS_VERSION = 1;
+
+/** 配置文件路径的环境变量覆盖（便携安装、多环境并存、测试都要用） */
+export const CONFIG_ENV = 'LLM_GATEWAY_CONFIG';
+
+/** 配置文件放哪：数据根目录（`~/.llm-api-gateway-cli`）下的 config.json，可用 LLM_GATEWAY_CONFIG 改 */
+export function settingsFilePath(env = process.env, home = os.homedir()) {
+  const explicit = String(env?.[CONFIG_ENV] ?? '').trim();
+  if (explicit) return path.resolve(explicit);
+  return path.join(defaultStoreRoot(env, home), 'config.json');
+}
+
+/* ---------- 类型校验 ---------- */
+
+const isHttpUrl = (v) => /^https?:\/\/[^\s]+$/i.test(v);
+
+/**
+ * 配置白名单。字段含义：
+ *   type  取值类型（string / string? / path / path? / int / int? / num? / bool / enum）
+ *   def   内置默认；函数表示「每次解析时才算」（如 lastWorkDir = 进程 cwd）
+ *   env   对应的环境变量
+ *   flag  对应的命令行选项（只用于展示与来源判定，解析仍在各 CLI 的 parseArgs）
+ *   arg   parseArgs 产物里的键名
+ *   min/max 取值范围（int）
+ */
+export const SETTINGS_SCHEMA = [
+  { key: 'model', type: 'string', def: 'qwen3:8b', env: 'GATEWAY_MODEL', flag: '-m/--model', arg: 'model', min: 1, max: 200, desc: '默认模型名' },
+  {
+    key: 'baseUrl',
+    type: 'string',
+    def: DEFAULT_BASE_URL,
+    env: 'GATEWAY_BASE_URL',
+    flag: '--base-url',
+    arg: 'base-url',
+    min: 1,
+    max: 500,
+    validate: (v) => (isHttpUrl(v) ? null : '需要 http:// 或 https:// 开头的地址'),
+    desc: '网关地址',
+  },
+  { key: 'temperature', type: 'num?', def: null, flag: '--temperature', arg: 'temperature', min: 0, max: 2, desc: '采样温度（不设则由上游定）' },
+  { key: 'maxTokens', type: 'int?', def: null, flag: '--max-tokens', arg: 'max-tokens', min: 1, max: 1000000, desc: '最大生成 token 数（不设则由上游定）' },
+  { key: 'system', type: 'string', def: '', flag: '-s/--system', arg: 'system', max: 20000, desc: '附加系统提示词' },
+  { key: 'mode', type: 'enum', values: MODES, def: 'manual', env: 'TASK_MODE', flag: '--mode', arg: 'mode', desc: '新任务的默认审批模式' },
+  {
+    key: 'maxSteps',
+    type: 'int',
+    def: AGENT_LIMITS.MAX_STEPS,
+    env: 'TASK_MAX_STEPS',
+    flag: '--max-steps',
+    arg: 'max-steps',
+    min: 1,
+    max: 1000,
+    desc: '单个任务最多几轮模型调用',
+  },
+  { key: 'lastWorkDir', type: 'string', def: () => process.cwd(), flag: '-C/--cwd', arg: 'cwd', max: 4096, desc: '下次启动的默认工作目录' },
+  { key: 'store.dir', type: 'path?', def: null, env: 'TASK_STORE_DIR', flag: '--store', arg: 'store', desc: '任务存储目录', restart: true },
+  { key: 'store.sessionDir', type: 'path?', def: null, flag: '--session-dir', arg: 'session-dir', desc: 'CLI 会话落盘目录', restart: true },
+  { key: 'retention.days', type: 'int', def: TTL_DAYS, min: 1, max: 3650, desc: '任务保留天数（滑动 TTL）', restart: true },
+  { key: 'retention.maxTasks', type: 'int', def: MAX_TASKS, min: 1, max: 10000, desc: '最多保留多少条任务', restart: true },
+  {
+    key: 'session.maxBytes',
+    type: 'int',
+    def: TASK_SESSION_MAX_BYTES,
+    env: 'TASK_SESSION_MAX_BYTES',
+    min: 64 * 1024,
+    max: 512 * 1024 * 1024,
+    desc: '单个任务会话文件的落盘硬闸（字节）',
+  },
+  {
+    key: 'history.maxChars',
+    type: 'int',
+    def: HISTORY_MAX_CHARS,
+    env: 'TASK_HISTORY_MAX_CHARS',
+    min: 1000,
+    max: 2000000,
+    desc: '发给模型的工具历史预算（字符）',
+  },
+  { key: 'history.keepRecentTurns', type: 'int', def: HISTORY_KEEP_RECENT_TURNS, min: 0, max: 50, desc: '保全文的最近轮数，永不压缩' },
+  { key: 'history.readFileDigest', type: 'bool', def: true, desc: '是否注入「已读文件清单」' },
+  {
+    key: 'ui.persist',
+    type: 'enum',
+    values: ['server', 'browser'],
+    def: 'server',
+    desc: '界面偏好存哪儿：server（清缓存不丢）/ browser（每个浏览器各自）',
+  },
+  { key: 'compat.legacyTaskApi', type: 'bool', def: true, desc: '是否继续接受旧的无状态 /api/task（已废弃）' },
+];
+
+/**
+ * 界面状态（不是「偏好」，是页面自己的记忆）。
+ * 允许读写，但**不由 `config` 命令管理** —— 用户手改 activeId 没有意义。
+ */
+export const UI_STATE_SCHEMA = [
+  { key: 'ui.showReasoning', type: 'bool', def: true, desc: '是否显示思维链' },
+  { key: 'ui.activeId', type: 'id?', def: null, desc: '最后打开的任务 id' },
+  { key: 'ui.collapsedDirs', type: 'strList', def: [], max: 500, desc: '侧边栏折叠的工作目录' },
+  { key: 'ui.collapsedTasks', type: 'strList', def: [], max: 2000, desc: '侧边栏折叠的子任务' },
+];
+
+const BY_KEY = new Map([...SETTINGS_SCHEMA, ...UI_STATE_SCHEMA].map((e) => [e.key, e]));
+const SETTING_KEYS = SETTINGS_SCHEMA.map((e) => e.key);
+const UI_KEYS = new Set(UI_STATE_SCHEMA.map((e) => e.key));
+const SECRET_KEY_RE = /(^|[._-])(api[_-]?key|key|token|secret|password|passwd|credential|auth)([._-]|$)/;
+
+/**
+ * 键名归一化后再判密钥：`authToken` 这种驼峰要有边界，
+ * 但又不能把 `maxTokens` 误判成密钥 —— 所以先把驼峰拆成下划线再按词边界匹配。
+ */
+const normalizeKeyName = (key) => String(key).replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+/** 值也要看：`config set system sk-xxxx` 同样是在把密钥写进磁盘 */
+const SECRET_VALUE_RE = /sk-[A-Za-z0-9_-]{16,}/;
+
+/** 这个键名看起来像密钥吗（config set key … 会被它拦下） */
+export function isSecretKey(key) {
+  return SECRET_KEY_RE.test(normalizeKeyName(key));
+}
+
+/** 是「用户可配」的键吗（界面状态不算：它由页面维护，config 命令不该碰） */
+export function isSettingKey(key) {
+  return SETTING_KEYS.includes(key);
+}
+
+/** 是界面状态键吗（PUT /api/settings 收，`config set` 不收） */
+export function isUiStateKey(key) {
+  return UI_KEYS.has(key);
+}
+
+/** 拼一份「可用键」清单，用于报错时告诉用户到底能写什么 */
+export function availableKeysText() {
+  return SETTINGS_SCHEMA.map((e) => e.key).join('、');
+}
+
+/** 按点号路径取值/赋值/删除（'session.maxBytes' → { session: { maxBytes } }） */
+export function getByPath(obj, key) {
+  let cur = obj;
+  for (const part of String(key).split('.')) {
+    if (cur === null || typeof cur !== 'object') return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+export function setByPath(obj, key, value) {
+  const parts = String(key).split('.');
+  let cur = obj;
+  for (const part of parts.slice(0, -1)) {
+    if (cur[part] === null || typeof cur[part] !== 'object' || Array.isArray(cur[part])) cur[part] = {};
+    cur = cur[part];
+  }
+  cur[parts[parts.length - 1]] = value;
+  return obj;
+}
+
+export function delByPath(obj, key) {
+  const parts = String(key).split('.');
+  const chain = [];
+  let cur = obj;
+  for (const part of parts.slice(0, -1)) {
+    if (cur === null || typeof cur !== 'object') return false;
+    chain.push([cur, part]);
+    cur = cur[part];
+  }
+  if (cur === null || typeof cur !== 'object') return false;
+  const last = parts[parts.length - 1];
+  if (!(last in cur)) return false;
+  delete cur[last];
+  // 顺手把因此变空的父对象也删掉：否则文件里会留下一串 "history": {}，
+  // 用户手看配置文件时容易以为那里还有东西
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const [parent, name] = chain[i];
+    const child = parent[name];
+    if (child && typeof child === 'object' && !Array.isArray(child) && Object.keys(child).length === 0) delete parent[name];
+    else break;
+  }
+  return true;
+}
+
+/** 内置默认值（函数形式的现算） */
+export function defaultValueOf(entry) {
+  return typeof entry.def === 'function' ? entry.def() : entry.def;
+}
+
+const NULLABLE = new Set(['string?', 'int?', 'num?', 'path?', 'id?']);
+
+/**
+ * 把「一个键 + 原始值」转成落盘值，顺便做范围与形状校验。
+ * raw 可能是 CLI 传来的字符串，也可能是 JSON 里的数字/布尔/数组。
+ *
+ * @returns {{ok:true, value:*}|{ok:false, error:string}}
+ */
+export function parseSettingValue(key, raw) {
+  if (isSecretKey(key)) {
+    return {
+      ok: false,
+      error: `「${key}」看起来是密钥类配置：密钥不写进 config.json（它有单独的 credentials.json，仅本用户可读）。请用 Web 界面「设置」或 gateway-agent config set key sk-xxx，也可以用 --key、环境变量 SK / GATEWAY_KEY / OPENAI_API_KEY，或 .env 文件。`,
+    };
+  }
+  const entry = BY_KEY.get(key);
+  if (!entry) return { ok: false, error: unknownKeyError(key) };
+
+  const type = entry.type;
+  const nullable = NULLABLE.has(type);
+  const isStringy = type === 'string' || type === 'string?' || type === 'path' || type === 'path?' || type === 'id?';
+
+  // 空 / null 的统一处理（string 类型上 min 表示「最短长度」，给了 min 就不许空）
+  if (raw === null || raw === undefined || (typeof raw === 'string' && raw.trim() === '')) {
+    if (nullable) return { ok: true, value: type === 'strList' ? [] : null };
+    if (type === 'strList') return { ok: true, value: [] };
+    if (type === 'string' && !entry.min) return { ok: true, value: '' };
+    return { ok: false, error: `${key} 不能为空（内置默认是 ${JSON.stringify(defaultValueOf(entry))}）` };
+  }
+  if (typeof raw === 'string' && /^(null|none)$/i.test(raw.trim()) && nullable) return { ok: true, value: null };
+
+  if (isStringy) {
+    const v = String(raw).trim();
+    if (entry.max && v.length > entry.max) return { ok: false, error: `${key} 太长（${v.length} 字符，上限 ${entry.max}）` };
+    if (entry.min && v.length < entry.min) return { ok: false, error: `${key} 太短（${v.length} 字符，至少 ${entry.min}）` };
+    if (SECRET_VALUE_RE.test(v)) return { ok: false, error: `${key} 的取值看起来是 sk- 密钥 —— 密钥不写进 config.json，请用 Web 界面「设置」或 gateway-agent config set key。` };
+    if (type === 'id?' && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v)) {
+      return { ok: false, error: `${key} 需要是 UUID，收到 ${v}` };
+    }
+    const bad = entry.validate ? entry.validate(v) : null;
+    if (bad) return { ok: false, error: `${key} 取值非法：${bad}（收到 ${v}）` };
+    return { ok: true, value: v };
+  }
+
+  if (type === 'bool') {
+    if (typeof raw === 'boolean') return { ok: true, value: raw };
+    const s = String(raw).trim().toLowerCase();
+    if (['true', '1', 'yes', 'on'].includes(s)) return { ok: true, value: true };
+    if (['false', '0', 'no', 'off'].includes(s)) return { ok: true, value: false };
+    return { ok: false, error: `${key} 只接受 true / false，收到 ${raw}` };
+  }
+
+  if (type === 'int' || type === 'int?' || type === 'num?') {
+    const n = Number(typeof raw === 'string' ? raw.trim() : raw);
+    if (!Number.isFinite(n)) return { ok: false, error: `${key} 需要数字，收到 ${raw}` };
+    if (type !== 'num?' && !Number.isInteger(n)) return { ok: false, error: `${key} 需要整数，收到 ${raw}` };
+    if (entry.min !== undefined && n < entry.min) return { ok: false, error: `${key} 不能小于 ${entry.min}（收到 ${n}）` };
+    if (entry.max !== undefined && n > entry.max) return { ok: false, error: `${key} 不能大于 ${entry.max}（收到 ${n}）` };
+    return { ok: true, value: n };
+  }
+
+  if (type === 'enum') {
+    const v = String(raw).trim();
+    if (!entry.values.includes(v)) return { ok: false, error: `${key} 只能是 ${entry.values.join(' / ')}，收到 ${v}` };
+    return { ok: true, value: v };
+  }
+
+  if (type === 'strList') {
+    const arr = Array.isArray(raw) ? raw : String(raw).split(',');
+    const out = arr.map((x) => String(x).trim()).filter(Boolean);
+    if (out.length > (entry.max || 500)) return { ok: false, error: `${key} 最多 ${entry.max} 项，收到 ${out.length} 项` };
+    return { ok: true, value: out };
+  }
+
+  return { ok: false, error: `内部错误：${key} 的类型 ${type} 没有处理分支` };
+}
+
+/** 编辑距离：用来给拼错的键名提个「你是不是想写 X」。超过 max 就提前返回 */
+function editDistance(a, b, max = 3) {
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    if (Math.min(...cur) > max) return max + 1;
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+/** 未知键的报错：除了列清单，还尽量给个「你是不是想写 X」 */
+export function unknownKeyError(key) {
+  const want = normalizeKeyName(key);
+  const scored = SETTINGS_SCHEMA.map((e) => {
+    const full = normalizeKeyName(e.key);
+    const wantLeaf = want.split('.').pop();
+    const leaf = full.split('.').pop();
+    // 整串像、或者「前缀一致 + 叶子名像」都算 —— 后者才能认出 session.mxBytes → session.maxBytes
+    const sameParent = want.split('.').slice(0, -1).join('.') === full.split('.').slice(0, -1).join('.');
+    const d = Math.min(editDistance(want, full, 3), sameParent ? editDistance(wantLeaf, leaf, 3) : 9);
+    return { key: e.key, d };
+  })
+    .filter((x) => x.d <= 2)
+    .sort((a, b) => a.d - b.d)
+    .slice(0, 3);
+
+  const hint = scored.length ? `你是不是想写：${scored.map((x) => x.key).join('、')}？` : '';
+  return `未知配置项「${key}」。可用配置项：${availableKeysText()}。${hint}`.trim();
+}
+
+/* ---------- 读 ---------- */
+
+/**
+ * 读配置文件。**坏文件不抛异常**：用户手改错了不该让服务起不来，
+ * 返回 error 让调用方打一条警告然后照常跑。
+ */
+export function readSettingsFile(file = settingsFilePath()) {
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return { file, exists: false, data: {}, error: null };
+    return { file, exists: false, data: {}, error: `读不到配置文件 ${file}：${e.message}` };
+  }
+  try {
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('顶层必须是对象');
+    return { file, exists: true, data, error: null };
+  } catch (e) {
+    return {
+      file,
+      exists: true,
+      data: {},
+      error: `配置文件不是合法 JSON（${file}）：${e.message}。已忽略它并沿用默认值，修好后重启即可。`,
+    };
+  }
+}
+
+/**
+ * 按 `--flag > 环境变量 > config.json > 默认` 解析出最终值与**每一项的来源**。
+ * 来源是关键：用户改了没生效时，一眼看出是被环境变量还是 flag 覆盖了。
+ *
+ * @returns {{values:object, sources:object, warnings:string[], file:string, exists:boolean}}
+ */
+export function resolveSettings({ file = settingsFilePath(), env = process.env, args = null } = {}) {
+  const read = readSettingsFile(file);
+  const values = {};
+  const sources = {};
+  const warnings = [];
+  if (read.error) warnings.push(read.error);
+
+  for (const entry of SETTINGS_SCHEMA) {
+    const flagRaw = args && entry.arg ? args[entry.arg] : undefined;
+    const envRaw = entry.env ? env?.[entry.env] : undefined;
+    const fileRaw = read.data ? getByPath(read.data, entry.key) : undefined;
+
+    let raw;
+    let source;
+    if (flagRaw !== undefined && flagRaw !== true && String(flagRaw).trim() !== '') {
+      raw = flagRaw;
+      source = 'flag';
+    } else if (envRaw !== undefined && String(envRaw).trim() !== '') {
+      raw = envRaw;
+      source = 'env';
+    } else if (fileRaw !== undefined) {
+      raw = fileRaw;
+      source = 'file';
+    } else {
+      raw = defaultValueOf(entry);
+      source = 'default';
+    }
+
+    const parsed = parseSettingValue(entry.key, raw);
+    if (parsed.ok) {
+      setByPath(values, entry.key, parsed.value);
+      sources[entry.key] = source;
+      continue;
+    }
+    // 坏值降级到默认：宁可用默认值跑起来，也不要因为一个手滑的字符让整个服务起不来
+    const fallback = defaultValueOf(entry);
+    warnings.push(`${entry.key} 的取值非法（${JSON.stringify(raw)}）：${parsed.error} 已改用默认值 ${JSON.stringify(fallback)}。`);
+    setByPath(values, entry.key, fallback);
+    sources[entry.key] = 'default';
+  }
+
+  return { values, sources, warnings, file: read.file, exists: read.exists };
+}
+
+/**
+ * `config list` 与 Web 设置面板共用的行：键、当前值、来源、默认、说明，
+ * 外加**渲染所需的类型信息**（type / 枚举取值 / 范围）。
+ *
+ * 类型必须带上：页面要按类型决定给复选框、下拉还是数字框，而它不该再抄一份白名单
+ * （见 lib/hub.js 的 settingsPayload 注释）。少这几个字段，页面就只能靠猜值类型，
+ * 枚举与字符串根本分不出来。
+ */
+export function listSettings(resolved) {
+  return SETTINGS_SCHEMA.map((entry) => ({
+    key: entry.key,
+    value: getByPath(resolved.values, entry.key),
+    source: resolved.sources[entry.key],
+    def: defaultValueOf(entry),
+    env: entry.env || '',
+    flag: entry.flag || '',
+    desc: entry.desc,
+    restart: Boolean(entry.restart),
+    // ↓ 渲染用：type 决定控件形状，values 是枚举候选，min/max 是数字范围（string 的 min 是长度）
+    type: entry.type,
+    values: entry.values || null,
+    min: entry.min ?? null,
+    max: entry.max ?? null,
+  }));
+}
+
+/* ---------- 写 ---------- */
+
+/**
+ * 写入若干项（键为点号路径）。**原子写**（tmp → rename）。
+ *
+ * 文件已损坏时**拒绝覆盖**：那份内容再错也是用户手写的，直接盖掉等于替他删了东西。
+ * 报错里给出路径，让他自己修或删。
+ *
+ * `allowUiState` 只给 Web 侧开：界面状态（activeId / 折叠项）本来就是页面在写；
+ * CLI 的 `config` 命令不该让用户手改这些东西。
+ */
+export function writeSettings(changes, { file = settingsFilePath(), allowUiState = false } = {}) {
+  const read = readSettingsFile(file);
+  if (read.error) {
+    throw new Error(`${read.error}\n请先修好或删除该文件再执行（不会自动覆盖你的内容）。`);
+  }
+  const data = read.exists ? JSON.parse(JSON.stringify(read.data)) : {};
+  const applied = [];
+  const errors = [];
+
+  // 先全部校验再落盘：一半成功一半失败最难排查
+  const parsedList = [];
+  for (const [key, raw] of Object.entries(changes || {})) {
+    if (!allowUiState && isUiStateKey(key)) {
+      errors.push(`${key} 是界面状态（页面自己维护的），不由 config 命令管理。`);
+      continue;
+    }
+    const parsed = parseSettingValue(key, raw);
+    if (!parsed.ok) errors.push(parsed.error);
+    else parsedList.push([key, parsed.value]);
+  }
+  if (errors.length) {
+    const err = new Error(errors.join('\n'));
+    err.validation = true;
+    throw err;
+  }
+
+  for (const [key, value] of parsedList) {
+    setByPath(data, key, value);
+    applied.push(key);
+  }
+  data.version = SETTINGS_VERSION;
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeJsonAtomic(file, data, { pretty: true });
+  return { file, data, applied };
+}
+
+/** 删掉若干项（回到「用默认值」） */
+export function unsetSettings(keys, { file = settingsFilePath(), allowUiState = false } = {}) {
+  const list = Array.isArray(keys) ? keys : [keys];
+  const read = readSettingsFile(file);
+  if (read.error) throw new Error(`${read.error}\n请先修好或删除该文件再执行。`);
+  const data = read.exists ? JSON.parse(JSON.stringify(read.data)) : {};
+  const removed = [];
+  const errors = [];
+  for (const key of list) {
+    if (isSecretKey(key)) {
+      errors.push(`「${key}」不在配置文件里（密钥本来就不落盘），无需删除。`);
+      continue;
+    }
+    if (!allowUiState && isUiStateKey(key)) {
+      errors.push(`${key} 是界面状态（页面自己维护的），不由 config 命令管理。`);
+      continue;
+    }
+    if (!BY_KEY.has(key)) {
+      errors.push(unknownKeyError(key));
+      continue;
+    }
+    if (delByPath(data, key)) removed.push(key);
+  }
+  if (errors.length) {
+    const err = new Error(errors.join('\n'));
+    err.validation = true;
+    throw err;
+  }
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeJsonAtomic(file, data, { pretty: true });
+  return { file, data, removed };
+}
+
+/**
+ * 一次 PUT 里哪些键改了要重启才生效（store.dir / retention.* 这类在启动时就被读走了）。
+ * 明说比让用户反复试要省事。
+ */
+export function restartKeysIn(appliedKeys) {
+  return appliedKeys.filter((k) => {
+    const entry = BY_KEY.get(k);
+    return Boolean(entry?.restart);
+  });
+}