dsh-compact-relay 0.0.0-stage → 0.3.2

package/lib/config.js

@@ -0,0 +1,167 @@
+/**
+ * 配置合并与校验。
+ *
+ * 字段清单、默认值、中文校验文案都在 core/config-schema.js（A4：单表派生）。
+ * 这里只负责：cordis 基础配置 + 用户覆盖层的深合并、旧写法兼容（绝对阈值/扁平颜色）、
+ * 颜色派生前的归一化。
+ */
+import path from 'node:path';
+import {
+  DEFAULT_CONFIG,
+  expandHome,
+  failConfig,
+  fieldAt,
+  validateConfig,
+} from './core/config-schema.js';
+
+// 兼容旧导入：其它模块/文档仍可从 config.js 拿默认配置与路径工具。
+export { CONFIG_FIELDS, DEFAULT_CONFIG, defaultDshHome, expandHome } from './core/config-schema.js';
+
+const COLOR_KEYS = ['idle', 'stage', 'pin', 'compact', 'handoff'];
+const COLOR_MODES = fieldAt(['colors', 'mode']).values;
+const BASE_COLOR_DEFAULTS = {
+  idle: fieldAt(['colors', 'base', 'idle']).default,
+  stage: fieldAt(['colors', 'base', 'stage']).default,
+  pin: fieldAt(['colors', 'base', 'pin']).default,
+  compact: fieldAt(['colors', 'base', 'compact']).default,
+  handoff: fieldAt(['colors', 'base', 'handoff']).default,
+};
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function objectOf(raw, key) {
+  return isPlainObject(raw[key]) ? raw[key] : {};
+}
+
+/**
+ * 颜色配置归一化：
+ * - 新结构 `{ mode, autoAdapt, base:{idle,compact,handoff,pin,stage} }`；
+ * - 兼容旧结构 `{ idle, stage, compact, handoff }`：当作 base，且默认关掉自动适配
+ *   （旧版本来就是一套颜色用到底，保持原样）；
+ * - 逐字段校验：给了就必须是非空字符串（合法 CSS 颜色）。
+ * @param {object} raw
+ * @returns {{mode:string, autoAdapt:boolean, base:object}}
+ */
+function normalizeColors(raw) {
+  const input = isPlainObject(raw) ? raw : {};
+  const mode = input.mode ?? DEFAULT_CONFIG.colors.mode;
+  if (!COLOR_MODES.includes(mode)) failConfig(['colors', 'mode'], `只能是 ${COLOR_MODES.join(' / ')}`, mode);
+  if (input.autoAdapt !== undefined && typeof input.autoAdapt !== 'boolean') {
+    failConfig(['colors', 'autoAdapt'], '必须是开/关（true/false）', input.autoAdapt);
+  }
+
+  const take = (source) => {
+    const out = {};
+    for (const key of COLOR_KEYS) {
+      const value = isPlainObject(source) ? source[key] : undefined;
+      if (value === undefined) continue;
+      if (typeof value !== 'string' || value.trim().length === 0) {
+        failConfig(['colors', 'base', key], '不能为空，必须是颜色值（如 #6F7680）', value);
+      }
+      out[key] = value.trim();
+    }
+    return out;
+  };
+  const legacy = take(input);
+  const hasLegacy = Object.keys(legacy).length > 0;
+  const base = { ...BASE_COLOR_DEFAULTS, ...legacy, ...take(input.base) };
+  // 旧扁平结构默认关自动适配（保持旧观感）；新结构默认开。
+  const autoAdapt = typeof input.autoAdapt === 'boolean' ? input.autoAdapt : !hasLegacy;
+  return { mode, autoAdapt, base };
+}
+
+/**
+ * 合并默认配置并做校验。未知键忽略（cordis 可能塞别的字段进来）。
+ *
+ * 阈值按**窗口比例**配置（compactRatio / handoffRatio）：换 1M / 200k / 128k
+ * 窗口的模型都自动按比例缩放，不会出现「绝对阈值超过窗口、提示永不触发」。
+ * 兼容旧版绝对写法（thresholds.compactAt/handoffAt 或顶层同名字段）：
+ * 用 contextWindowFallback 折算成比例；新旧同时给时以比例为准。
+ *
+ * @param {object} [raw]
+ * @returns {object}
+ */
+export function resolveConfig(raw = {}) {
+  const input = isPlainObject(raw) ? raw : {};
+  const thresholds = objectOf(input, 'thresholds');
+  const retention = objectOf(input, 'retention');
+  const summary = objectOf(input, 'summary');
+  const handoff = objectOf(input, 'handoff');
+  const timeouts = objectOf(input, 'timeouts');
+  const dev = objectOf(input, 'dev');
+  const colors = objectOf(input, 'colors');
+
+  const windowFallback = input.contextWindowFallback ?? DEFAULT_CONFIG.contextWindowFallback;
+  const legacyCompactAt = thresholds.compactAt ?? input.compactAt;
+  const legacyHandoffAt = thresholds.handoffAt ?? input.handoffAt;
+  const ratioFromLegacy = (value, pathParts) => {
+    if (value === undefined) return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+      failConfig(pathParts, '旧版绝对阈值必须是正数（或改用窗口比例 0~1）', value);
+    }
+    return value / windowFallback;
+  };
+
+  const merged = {
+    thresholds: {
+      compactRatio:
+        thresholds.compactRatio ??
+        ratioFromLegacy(legacyCompactAt, ['thresholds', 'compactRatio']) ??
+        DEFAULT_CONFIG.thresholds.compactRatio,
+      handoffRatio:
+        thresholds.handoffRatio ??
+        ratioFromLegacy(legacyHandoffAt, ['thresholds', 'handoffRatio']) ??
+        DEFAULT_CONFIG.thresholds.handoffRatio,
+      maxSummaries: thresholds.maxSummaries ?? DEFAULT_CONFIG.thresholds.maxSummaries,
+      minRatio: thresholds.minRatio ?? DEFAULT_CONFIG.thresholds.minRatio,
+    },
+    contextWindowFallback: windowFallback,
+    retention: {
+      recentTailTokens: retention.recentTailTokens ?? DEFAULT_CONFIG.retention.recentTailTokens,
+    },
+    summary: {
+      maxTokens: summary.maxTokens ?? DEFAULT_CONFIG.summary.maxTokens,
+    },
+    handoff: {
+      maxTokens: handoff.maxTokens ?? DEFAULT_CONFIG.handoff.maxTokens,
+    },
+    timeouts: {
+      llmMs: timeouts.llmMs ?? DEFAULT_CONFIG.timeouts.llmMs,
+    },
+    dev: {
+      testRangeNodes: dev.testRangeNodes ?? DEFAULT_CONFIG.dev.testRangeNodes,
+    },
+    // 配置里允许写 `~/...`：统一展开成绝对路径，别在 cwd 下建字面 `~` 目录。
+    handoffDir: path.resolve(
+      typeof input.handoffDir === 'string' && input.handoffDir.length > 0
+        ? expandHome(input.handoffDir)
+        : DEFAULT_CONFIG.handoffDir,
+    ),
+    colors: normalizeColors(colors),
+    links: {
+      tutorial: input.links?.tutorial ?? DEFAULT_CONFIG.links.tutorial,
+      feedback: input.links?.feedback ?? DEFAULT_CONFIG.links.feedback,
+    },
+  };
+
+  // schema 里的所有非颜色字段统一校验（中文文案由 schema 提供）。
+  validateConfig(merged);
+
+  const { compactRatio, handoffRatio, minRatio } = merged.thresholds;
+  if (minRatio >= compactRatio) {
+    failConfig(
+      ['thresholds', 'minRatio'],
+      '必须小于「压缩提醒线」；最小压缩线是「值得压缩」的门槛，要在压缩线之前',
+      minRatio,
+    );
+  }
+  if (compactRatio >= handoffRatio) {
+    failConfig(
+      ['thresholds', 'compactRatio'],
+      '必须小于「交接提醒线」；压缩线要在交接线之前，否则会先建议换会话',
+      compactRatio,
+    );
+  }
+
+  return merged;
+}

package/lib/core/colors.js

@@ -0,0 +1,150 @@
+export const DEFAULT_BASE = { idle: '#6F7680', compact: '#C26A00', handoff: '#D92D20', stage: '#2563EB', pin: '#C026D3' };
+
+/** DSH 原生自动压缩线的标记色：刻意不用五级配色里的任何颜色，保证一眼和环上的红/琥珀分开。 */
+export const NATIVE_LINE_COLOR = '#7C3AED';
+export const SCHEME_BG = { light: '#ffffff', dark: '#1c1c22' };
+
+export function normalizeHex(value, fallback) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (/^#[0-9a-f]{6}$/i.test(text)) return text.toLowerCase();
+  if (/^#[0-9a-f]{3}$/i.test(text)) {
+    return `#${text[1]}${text[1]}${text[2]}${text[2]}${text[3]}${text[3]}`.toLowerCase();
+  }
+  return fallback;
+}
+
+export function hexToHsl(hex) {
+  const n = parseInt(normalizeHex(hex, '#888888').slice(1), 16);
+  const r = ((n >> 16) & 255) / 255;
+  const g = ((n >> 8) & 255) / 255;
+  const b = (n & 255) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return { h: 0, s: 0, l };
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+  else if (max === g) h = (b - r) / d + 2;
+  else h = (r - g) / d + 4;
+  return { h: h * 60, s, l };
+}
+
+export function hslToHex(h, s, l) {
+  const hue = ((h % 360) + 360) % 360 / 360;
+  const sat = Math.min(1, Math.max(0, s));
+  const lig = Math.min(1, Math.max(0, l));
+  const q = lig < 0.5 ? lig * (1 + sat) : lig + sat - lig * sat;
+  const p = 2 * lig - q;
+  const channel = (t) => {
+    const x = ((t % 1) + 1) % 1;
+    if (x < 1 / 6) return p + (q - p) * 6 * x;
+    if (x < 1 / 2) return q;
+    if (x < 2 / 3) return p + (q - p) * (2 / 3 - x) * 6;
+    return p;
+  };
+  const to = (value) => Math.round(value * 255).toString(16).padStart(2, '0');
+  return `#${to(channel(hue + 1 / 3))}${to(channel(hue))}${to(channel(hue - 1 / 3))}`;
+}
+
+export function luminance(hex) {
+  const n = parseInt(normalizeHex(hex, '#888888').slice(1), 16);
+  const channel = (v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel((n >> 16) & 255) + 0.7152 * channel((n >> 8) & 255) + 0.0722 * channel(n & 255);
+}
+
+export function contrastRatio(a, b) {
+  const la = luminance(a);
+  const lb = luminance(b);
+  const hi = Math.max(la, lb);
+  const lo = Math.min(la, lb);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+export function deriveColor(baseHex, scheme) {
+  const { h, s, l } = hexToHsl(normalizeHex(baseHex, '#888888'));
+  const neutral = s < 0.15;
+  let lig = scheme === 'dark' ? Math.max(l, 0.62) : Math.min(l, 0.46);
+  const sat = neutral ? s : Math.min(0.92, Math.max(0.4, s));
+  const bg = SCHEME_BG[scheme];
+  let out = hslToHex(h, sat, lig);
+  for (let i = 0; i < 60 && contrastRatio(out, bg) < 3; i += 1) {
+    lig = scheme === 'dark' ? Math.min(0.94, lig + 0.01) : Math.max(0.06, lig - 0.01);
+    out = hslToHex(h, sat, lig);
+  }
+  return out;
+}
+
+/** 取用户选的基准色（兼容旧版直接下发一套颜色）。 */
+export function basePalette(colors) {
+  if (colors !== null && typeof colors === 'object' && colors.base !== null && typeof colors.base === 'object') {
+    const base = {};
+    for (const key of ['idle', 'stage', 'pin', 'compact', 'handoff']) {
+      base[key] = normalizeHex(colors.base[key], DEFAULT_BASE[key]);
+    }
+    return base;
+  }
+  if (colors !== null && typeof colors === 'object' && typeof colors.idle === 'string') {
+    return {
+      idle: normalizeHex(colors.idle, DEFAULT_BASE.idle),
+      stage: normalizeHex(colors.stage, DEFAULT_BASE.stage),
+      pin: normalizeHex(colors.pin, DEFAULT_BASE.pin),
+      compact: normalizeHex(colors.compact, DEFAULT_BASE.compact),
+      handoff: normalizeHex(colors.handoff, DEFAULT_BASE.handoff),
+    };
+  }
+  return { ...DEFAULT_BASE };
+}
+
+/** 按指定明暗方案生成一套颜色（关闭自动适配时原样返回基准色）。 */
+export function paletteForScheme(colors, scheme) {
+  const base = basePalette(colors);
+  const auto = !(colors !== null && typeof colors === 'object' && colors.autoAdapt === false);
+  if (!auto) return base;
+  return {
+    idle: deriveColor(base.idle, scheme),
+    stage: deriveColor(base.stage, scheme),
+    pin: deriveColor(base.pin, scheme),
+    compact: deriveColor(base.compact, scheme),
+    handoff: deriveColor(base.handoff, scheme),
+  };
+}
+
+/** 决定当前用浅色还是深色方案：设置里强制优先，否则跟随界面实际明暗。 */
+export function effectiveScheme(colors, detectedDark) {
+  if (colors !== null && typeof colors === 'object' && (colors.mode === 'light' || colors.mode === 'dark')) return colors.mode;
+  return detectedDark ? 'dark' : 'light';
+}
+
+/**
+ * 选当前生效的一套颜色。
+ *
+ * A8：优先用 host 在 state/settings view 里下发的 colors.palette[scheme]
+ * （两套都算好，浏览器半只挑一套，不必每帧重算派生）；没有下发时按基准色
+ * 本地派生 —— 兼容旧 payload，也覆盖设置页「改了还没保存」的即时预览。
+ */
+export function resolvePalette(colors, detectedDark) {
+  const scheme = effectiveScheme(colors, detectedDark);
+  const palette = colors !== null && typeof colors === 'object' ? colors.palette : undefined;
+  if (palette !== null && typeof palette === 'object') {
+    const selected = palette[scheme];
+    if (selected !== null && typeof selected === 'object') {
+      const base = basePalette(colors);
+      const out = {};
+      for (const key of ['idle', 'stage', 'pin', 'compact', 'handoff']) {
+        out[key] = normalizeHex(selected[key], base[key]);
+      }
+      return out;
+    }
+  }
+  return paletteForScheme(colors, scheme);
+}
+
+/** 浅/深两套派生色板（host 下发给浏览器半；纯函数，可单测）。 */
+export function paletteForBothSchemes(colors) {
+  return { light: paletteForScheme(colors, 'light'), dark: paletteForScheme(colors, 'dark') };
+}

package/lib/core/compress-hint.js

@@ -0,0 +1,52 @@
+/**
+ * 「这里适合压缩」判断记录（0.3.1）—— 纯数据与纯判定，不依赖 DSH。
+ *
+ * 模型判断：最小线 < 当前 < 压缩线，且工作到了自然节点 → 调用工具记一条：
+ *   plugin:compact-relay/compress-hint   data: { ratio, at }
+ *
+ * 环上把它画成「断点1」（正常区/压缩区的分界）；压缩或交接改变历史后自动失效
+ * （和 checkpoint 比较 seq，跟旧阶段标记一个套路）。
+ */
+
+/** 记录类型（DSH 语法：`plugin:` + 小写段；只认精确匹配）。 */
+export const COMPRESS_HINT_RECORD_TYPE = 'plugin:compact-relay/compress-hint';
+
+/** 判断记录的判定 = ignorable + 类型精确匹配。 */
+export function isCompressHintEvent(event) {
+  return event !== null && typeof event === 'object' && event.ignorable === true && event.type === COMPRESS_HINT_RECORD_TYPE;
+}
+
+/**
+ * 从会话事件流里取最近一条「适合压缩」判断；没有或不合法返回 null。
+ * @param {object[]} events
+ * @returns {{ratio:number, at:number, seq:number}|null}
+ */
+export function latestCompressHint(events) {
+  if (!Array.isArray(events)) return null;
+  let hint = null;
+  for (const event of events) {
+    if (!isCompressHintEvent(event)) continue;
+    const data = event.data;
+    if (data === null || typeof data !== 'object') continue;
+    const ratio =
+      typeof data.ratio === 'number' && Number.isFinite(data.ratio)
+        ? Math.max(0, Math.min(1, data.ratio))
+        : null;
+    if (ratio === null) continue;
+    const at = typeof data.at === 'number' && Number.isFinite(data.at) ? data.at : 0;
+    hint = { ratio, at, seq: event.seq };
+  }
+  return hint;
+}
+
+/**
+ * 判断记录是否仍然有效：要比最后一次压缩/交接 checkpoint 新才算数。
+ * @param {{seq:number}|null} hint
+ * @param {number|undefined} checkpointSeq 最后一次 checkpoint 消息的 event seq
+ * @returns {boolean}
+ */
+export function compressHintIsActive(hint, checkpointSeq) {
+  if (hint === null || hint === undefined) return false;
+  if (!Number.isInteger(checkpointSeq)) return true;
+  return hint.seq > checkpointSeq;
+}

package/lib/core/config-schema.js

@@ -0,0 +1,285 @@
+/**
+ * 配置 schema —— 所有配置项的唯一清单。
+ *
+ * 加一个设置项只改这里：默认值、类型/范围校验、中文文案、设置页白名单、
+ * 公开视图（publicConfig）全部由这张表派生。config.js 只负责合并兼容写法与颜色归一。
+ *
+ * 字段标志：
+ * - `editable`: 允许从设置栏写入 `compact-relay.json`（filterPatch 白名单）
+ * - `view`:     出现在设置栏读取的公开视图里（publicConfig）
+ * - `internal`: 内部配置（不出现在设置页，也不允许设置页写）
+ */
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * 展开开头的 `~`（只认 `~` 或 `~/`；`~user` 形式不猜）。
+ * @param {string} value
+ * @returns {string}
+ */
+export function expandHome(value) {
+  if (value === '~') return os.homedir();
+  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+/**
+ * 默认 DSH home：优先环境变量 DSH_HOME（隔离复刻/测试会用），否则 ~/.dsh。
+ * @returns {string}
+ */
+export function defaultDshHome() {
+  const fromEnv = process.env.DSH_HOME;
+  if (typeof fromEnv === 'string' && fromEnv.trim().length > 0) {
+    return path.resolve(expandHome(fromEnv));
+  }
+  return path.join(os.homedir(), '.dsh');
+}
+
+function field(pathParts, options) {
+  return Object.freeze({
+    path: Object.freeze(pathParts),
+    label: options.label,
+    kind: options.kind,
+    values: options.values === undefined ? undefined : Object.freeze(options.values),
+    max: options.max,
+    default: options.default,
+    editable: options.editable === true,
+    view: options.view === true,
+  });
+}
+
+/**
+ * 单表：路径 / 类型 / 默认值 / 中文标签 / 是否设置页可改。
+ * 顺序即设置页展示顺序（settings 面板里仍按自己的分组渲染，这里只管数据）。
+ */
+export const CONFIG_FIELDS = Object.freeze([
+  // 0.3.1：「值得压缩」的最小线——低于它压缩不划算（摘要可能比原文还大），模型不会建议压缩。
+  field(['thresholds', 'minRatio'], { label: '最小压缩线', kind: 'ratio', default: 0.05, editable: true, view: true }),
+  field(['thresholds', 'compactRatio'], { label: '压缩提醒线', kind: 'ratio', default: 0.4, editable: true, view: true }),
+  field(['thresholds', 'handoffRatio'], { label: '交接提醒线', kind: 'ratio', default: 0.6, editable: true, view: true }),
+  // P3-02：必须 ≥1。0 在策略层会同时触发「恒交接 + 恒合并旧摘要」，没有可用语义，
+  // 以前允许 0 会让指示灯永远停在交接状态；现在保存 0 直接给中文校验错误。
+  field(['thresholds', 'maxSummaries'], { label: '摘要份数上限', kind: 'positiveInt', default: 6, editable: true, view: true }),
+  field(['contextWindowFallback'], { label: '兜底窗口', kind: 'positiveInt', default: 1_000_000 }),
+  field(['retention', 'recentTailTokens'], { label: '保留近期原文', kind: 'nonNegativeInt', default: 40_000, editable: true, view: true }),
+  field(['summary', 'maxTokens'], { label: '摘要输出上限', kind: 'positiveInt', default: 8_192 }),
+  field(['handoff', 'maxTokens'], { label: '交接单输出上限', kind: 'positiveInt', default: 8_192 }),
+  field(['timeouts', 'llmMs'], { label: '模型调用超时', kind: 'positiveInt', default: 180_000 }),
+  field(['dev', 'testRangeNodes'], { label: '测试取段条数', kind: 'positiveInt', default: 4 }),
+  field(['handoffDir'], {
+    label: '交接单目录',
+    kind: 'path',
+    default: () => path.join(defaultDshHome(), 'handoffs'),
+    editable: true,
+    view: true,
+  }),
+  field(['colors', 'mode'], { label: '颜色模式', kind: 'enum', values: ['auto', 'light', 'dark'], default: 'auto', editable: true, view: true }),
+  field(['colors', 'autoAdapt'], { label: '自动适配颜色', kind: 'boolean', default: true, editable: true, view: true }),
+  field(['colors', 'base', 'idle'], { label: '默认颜色', kind: 'color', default: '#6F7680', editable: true, view: true }),
+  field(['colors', 'base', 'stage'], { label: '填满颜色', kind: 'color', default: '#2563EB', editable: true, view: true }),
+  field(['colors', 'base', 'pin'], { label: '锁定颜色', kind: 'color', default: '#C026D3', editable: true, view: true }),
+  field(['colors', 'base', 'compact'], { label: '调整颜色', kind: 'color', default: '#C26A00', editable: true, view: true }),
+  field(['colors', 'base', 'handoff'], { label: '上限颜色', kind: 'color', default: '#D92D20', editable: true, view: true }),
+  // 0.3.1：仓库已建（cfanzx/dsh-compact-relay），默认指向仓库内的教程与 Issues；
+  // 用户仍可在设置文件里覆盖 links.tutorial / links.feedback。
+  field(['links', 'tutorial'], { label: '使用教程链接', kind: 'urlOrEmpty', default: 'https://github.com/cfanzx/dsh-compact-relay/blob/main/TUTORIAL.md', view: true }),
+  field(['links', 'feedback'], { label: '反馈链接', kind: 'urlOrEmpty', default: 'https://github.com/cfanzx/dsh-compact-relay/issues', view: true }),
+]);
+
+/** 路径 → 字段 的索引。 */
+const FIELD_BY_PATH = new Map(CONFIG_FIELDS.map((item) => [item.path.join('.'), item]));
+
+/**
+ * @param {string[]} pathParts
+ * @returns {object|undefined}
+ */
+export function fieldAt(pathParts) {
+  return FIELD_BY_PATH.get(pathParts.join('.'));
+}
+
+/**
+ * 合并后的配置对象里取一个路径的值。
+ * @param {object} object
+ * @param {readonly string[]} pathParts
+ * @returns {unknown}
+ */
+export function getAt(object, pathParts) {
+  let cursor = object;
+  for (const key of pathParts) {
+    if (cursor === null || typeof cursor !== 'object') return undefined;
+    cursor = cursor[key];
+  }
+  return cursor;
+}
+
+/**
+ * 往对象里写一个路径（就地写；调用方负责保证起点是新对象）。
+ * @param {object} object
+ * @param {readonly string[]} pathParts
+ * @param {unknown} value
+ */
+export function setAt(object, pathParts, value) {
+  let cursor = object;
+  for (let index = 0; index < pathParts.length - 1; index += 1) {
+    const key = pathParts[index];
+    if (cursor[key] === null || typeof cursor[key] !== 'object') cursor[key] = {};
+    cursor = cursor[key];
+  }
+  cursor[pathParts[pathParts.length - 1]] = value;
+}
+
+/**
+ * 递归冻结普通对象/数组（默认配置只读）。
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+function deepFreeze(value) {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/**
+ * 按 schema 生成一份默认配置。
+ * @returns {object}
+ */
+export function buildDefaultConfig() {
+  const out = {};
+  for (const item of CONFIG_FIELDS) {
+    const value = typeof item.default === 'function' ? item.default() : item.default;
+    setAt(out, item.path, value);
+  }
+  return out;
+}
+
+/** 默认配置（由 schema 派生；模块加载时冻结一次）。 */
+export const DEFAULT_CONFIG = deepFreeze(buildDefaultConfig());
+
+/** 配置错误：带字段路径与中文文案，设置页/日志可定位到具体项。 */
+export class ConfigError extends Error {
+  /**
+   * @param {object} item schema 字段
+   * @param {string} message 中文说明（不含字段名）
+   * @param {unknown} [value] 实际值（只用于文案，不写进设置文件）
+   */
+  constructor(item, message, value) {
+    const suffix = value === undefined ? '' : `（当前值：${formatValue(value)}）`;
+    super(`「${item.label}」${message}${suffix}`);
+    this.name = 'ConfigError';
+    this.field = item.path.join('.');
+    this.fieldLabel = item.label;
+    this.value = value;
+  }
+}
+
+/**
+ * 抛一个带字段路径的配置错误。
+ * @param {string[]} pathParts
+ * @param {string} message
+ * @param {unknown} [value]
+ * @returns {never}
+ */
+export function failConfig(pathParts, message, value) {
+  const item = fieldAt(pathParts);
+  if (item === undefined) throw new Error(`compact-relay: 未知配置字段 ${pathParts.join('.')}`);
+  throw new ConfigError(item, message, value);
+}
+
+function formatValue(value) {
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (value === null) return 'null';
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+const INTEGER_HINT = '必须是正整数';
+
+/**
+ * 校验一个字段值；合法返回 null，不合法返回中文原因（不含字段名）。
+ * @param {object} item
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function validateFieldValue(item, value) {
+  switch (item.kind) {
+    case 'ratio':
+      if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value >= 1) {
+        return '必须是 0 到 1 之间的小数（例如 0.4 表示 40%）';
+      }
+      return null;
+    case 'positiveInt': {
+      if (!Number.isInteger(value) || value <= 0) return INTEGER_HINT;
+      if (typeof item.max === 'number' && value > item.max) return `不能超过 ${item.max}`;
+      return null;
+    }
+    case 'nonNegativeInt':
+      return Number.isInteger(value) && value >= 0 ? null : '必须是非负整数';
+    case 'boolean':
+      return typeof value === 'boolean' ? null : '必须是开/关（true/false）';
+    case 'enum':
+      return item.values.includes(value) ? null : `只能是 ${item.values.join(' / ')}`;
+    case 'color':
+      return typeof value === 'string' && value.trim().length > 0 ? null : '不能为空，必须是颜色值（如 #6F7680）';
+    case 'path':
+      return typeof value === 'string' && value.length > 0 ? null : '不能为空';
+    case 'urlOrEmpty':
+      if (typeof value !== 'string') return '必须是字符串';
+      if (value.length > 0 && !/^https?:\/\//i.test(value)) return '必须是 http(s) 链接，或留空';
+      return null;
+    default:
+      return `未知类型 ${item.kind}`;
+  }
+}
+
+/**
+ * 校验完整配置里的所有非颜色字段（颜色由 config.js 的颜色归一逻辑校验，
+ * 以保留旧扁平颜色结构的兼容）。
+ * @param {object} cfg
+ */
+export function validateConfig(cfg) {
+  for (const item of CONFIG_FIELDS) {
+    if (item.path[0] === 'colors') continue;
+    const value = getAt(cfg, item.path);
+    const problem = validateFieldValue(item, value);
+    if (problem !== null) throw new ConfigError(item, problem, value);
+  }
+}
+
+/**
+ * 只保留设置栏允许写入的字段（派生自 schema.editable）。
+ * @param {object} patch
+ * @returns {object}
+ */
+export function filterSettingsPatch(patch) {
+  if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) {
+    throw new Error('设置必须是 JSON 对象');
+  }
+  const out = {};
+  for (const item of CONFIG_FIELDS) {
+    if (!item.editable) continue;
+    const value = getAt(patch, item.path);
+    if (value !== undefined) setAt(out, item.path, value);
+  }
+  return out;
+}
+
+/**
+ * 设置栏读取用的公开视图（派生自 schema.view）。
+ * @param {object} cfg
+ * @returns {object}
+ */
+export function publicConfigOf(cfg) {
+  const out = {};
+  for (const item of CONFIG_FIELDS) {
+    if (!item.view) continue;
+    setAt(out, item.path, getAt(cfg, item.path));
+  }
+  return out;
+}