@aalis/schema-config 0.13.1 → 0.15.0

package/dist/index.js

@@ -1,19 +1,84 @@
 // ============================================================
 // @aalis/schema-config — 配置 Schema 词汇契约 + 词汇的中立解释
 //
-// 类型部分描述"配置如何呈现为表单"（label / options / textarea …）；
-// 函数部分是对这套词汇的**中立解释**：默认值派生（defaultsFrom）、只读
-// 结构校验（validateConfig）、按 schema 键集裁未知字段（removeExtraFields）。
-// 三者都不属于 @aalis/core——core 只把 `PluginMeta.configSchema` 当作
+// 类型部分描述"配置如何呈现为表单"（label / options / textarea …），并由
+// ConfigOf 从同一份 schema 推导配置值类型；
+// 函数部分是对这套词汇的**中立解释**：默认值派生（defaultsFrom）与深合并（deepMergeDefaults）、
+// 只读结构校验（validateConfig）、按 schema 键集裁未知字段（removeExtraFields）、
+// 按 schema 解析插件拿到的配置（parseConfig）。
+// 它们都不属于 @aalis/core——core 只把 `PluginMeta.configSchema` 当作
 // opaque 数据透传，不解释任何字段。另有插件因配置问题无法激活时抛的错误（configError / missingConfigError）。
 //
 // 消费方：
-// - 插件：在 `definePlugin({ configSchema })` 的定义对象里声明
+// - 插件：用 defineConfig 声明 schema、放进 `definePlugin({ configSchema })`，apply 里用 parseConfig 读配置
 // - 渲染宿主（webui-server/client 等）：读取并渲染表单
 // - 宿主政策（@aalis/runtime 的 config-sync）：按 schema 裁剪未知字段、校验告警
 //
 // 本包零运行时依赖：对 @aalis/core 仅有 type-only 锚点 import（编译后擦除）。
 // ============================================================
+/** 是不是密钥引用：只有 `$secret` 一个自有键、值为非空字符串的纯对象 */
+export function isSecretRef(value) {
+    if (!isRecord(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && keys[0] === '$secret' && typeof value.$secret === 'string' && value.$secret !== '';
+}
+/**
+ * 逐个处理配置里密钥字段上的值（顶层、分组内、数组元素内；值为 undefined 的不处理），不改入参：有改动时返回浅拷贝
+ * （没动到的部分与入参共享），没有改动时返回入参本身，调用方要改写结果请先复制。回调返回 undefined 时删掉这个键。
+ * 宿主拆出、解析密钥与给呈现方去掉密钥都用它，密钥字段的位置只在这里认。
+ */
+export function mapSecretFields(schema, config, fn) {
+    const visit = (fields, source, prefix, inArray) => {
+        let out = source;
+        const put = (key, value) => {
+            if (out === source)
+                out = { ...source };
+            if (value === undefined)
+                delete out[key];
+            else
+                out[key] = value;
+        };
+        for (const [key, entry] of Object.entries(fields)) {
+            if (!isRecord(entry) || isUnsafeConfigKey(key) || !Object.hasOwn(source, key))
+                continue;
+            const value = source[key];
+            if ('fields' in entry) {
+                if (isRecord(value) && isRecord(entry.fields)) {
+                    const next = visit(entry.fields, value, `${prefix}${key}.`, inArray);
+                    if (next !== value)
+                        put(key, next);
+                }
+            }
+            else if (entry.type === 'array') {
+                if (Array.isArray(value) && isRecord(entry.items)) {
+                    const items = entry.items;
+                    const next = value.map(item => (isRecord(item) ? visit(items, item, `${prefix}${key}.`, true) : item));
+                    if (next.some((item, i) => item !== value[i]))
+                        put(key, next);
+                }
+            }
+            else if (entry.secret === true && value !== undefined) {
+                const next = fn(value, { path: prefix + key, inArray });
+                if (next !== value)
+                    put(key, next);
+            }
+        }
+        return out;
+    };
+    return visit(isRecord(schema) ? schema : {}, config, '', false);
+}
+/**
+ * 声明插件的配置 schema：运行时原样返回传入的对象（不冻结、不加任何属性），类型层保留字面量，
+ * 供 {@link ConfigOf} 推出配置值类型。返回值可直接放进 `definePlugin({ configSchema })`。
+ *
+ * 别给变量标 `ConfigSchema` 类型注解：注解会把字面量拓宽掉，ConfigOf 只能推出宽类型。
+ * 推出的类型里各属性是只读的、options 是字面量元组；要在运行时改写 schema（WebUI 读的是这个活对象），
+ * 经 `ConfigSchema` 类型的引用改写（如 `const live: ConfigSchema = configSchema`）。
+ */
+export function defineConfig(schema) {
+    return schema;
+}
 /**
  * core 基础设施配置（name / logLevel / slowThresholdMs）的表单描述。
  *
@@ -24,7 +89,7 @@ export const CORE_CONFIG_SCHEMA = {
     name: {
         type: 'string',
         label: '应用名称',
-        description: '应用显示名称，用于启动日志和界面展示；装有人设时仪表盘仍显示它，聊天显示人设名',
+        description: '应用显示名称，用于启动日志和界面展示',
         default: 'Aalis',
     },
     logLevel: {
@@ -48,7 +113,7 @@ export const CORE_CONFIG_SCHEMA = {
     },
 };
 /**
- * 从 ConfigSchema 派生默认配置。
+ * 从 ConfigSchema 派生默认配置（密钥字段除外）。
  *
  * ConfigSchema 是插件配置的**唯一声明来源**：每个字段的 `default` 就是运行时默认值，
  * 不存在第二份手抄的默认值对象。宿主在注册插件前用本函数派生出默认配置并深合并进配置文档，
@@ -58,6 +123,8 @@ export const CORE_CONFIG_SCHEMA = {
  * - SchemaField / SchemaArray：取 `default`（没写 default 的字段不产出键，
  *   等同于「该字段无默认值」——读取方自行处理 undefined）
  * - SchemaGroup：递归 `fields`，总是产出嵌套对象（即使子字段全无默认值）
+ * - `secret: true` 的字段不产出：派生结果会被写进配置文档，密钥的默认值不进文档（map 的默认值还会被深合并进
+ *   引用对象），插件经 parseConfig 照常补上
  */
 export function defaultsFrom(schema) {
     const out = {};
@@ -70,14 +137,38 @@ export function defaultsFrom(schema) {
             out[key] = defaultsFrom(entry.fields);
             continue;
         }
+        if (entry.secret === true)
+            continue;
         if ('default' in entry)
             out[key] = cloneConfigValue(entry.default);
     }
     return out;
 }
-// 校验器在运行时需要一份"本包内置类型"名单：SchemaFieldTypes 是纯类型层的
+/**
+ * 把默认值（通常是 {@link defaultsFrom} 的结果）深合并进配置：只填充缺失的键，已有的值（含显式 null）不覆盖。
+ * 嵌套对象递归合并，只写了半块的分组照样补齐其余默认子键；数组与基础类型按「已存在则保留」处理。
+ * 宿主的配置同步与 WebUI 保存插件配置用同一个合并，两条路径写出的配置形状一致。
+ */
+export function deepMergeDefaults(defaults, current) {
+    const result = { ...current };
+    for (const [key, defaultValue] of Object.entries(defaults)) {
+        if (!Object.hasOwn(result, key)) {
+            result[key] = defaultValue;
+        }
+        else if (defaultValue !== null &&
+            typeof defaultValue === 'object' &&
+            !Array.isArray(defaultValue) &&
+            result[key] !== null &&
+            typeof result[key] === 'object' &&
+            !Array.isArray(result[key])) {
+            result[key] = deepMergeDefaults(defaultValue, result[key]);
+        }
+    }
+    return result;
+}
+// 校验与解析在运行时需要一份"本包内置类型"名单：SchemaFieldTypes 是纯类型层的
 // merging 注册表，运行时不存在。外来类型（如 'llm-ref'）落在名单之外，
-// 校验器一律跳过放行——开放词汇表要求校验器同样开放。
+// validateConfig 一律跳过放行、parseConfig 原样透传——开放词汇表要求两者同样开放。
 const NEUTRAL_FIELD_TYPES = new Set([
     'string',
     'number',
@@ -88,47 +179,96 @@ const NEUTRAL_FIELD_TYPES = new Set([
     'list',
     'map',
 ]);
+/** 字段类型是不是本包内置的：内置类型的取值经 validateConfig 与 parseConfig 校验，外来类型（如 'llm-ref'）的不经 */
+export function isBuiltinFieldType(type) {
+    return NEUTRAL_FIELD_TYPES.has(type);
+}
 /**
  * 按 ConfigSchema 对配置做只读结构校验，返回问题清单（空数组 = 无问题）。
  *
  * 定位与边界：
- * - **只读**：不转换、不回填、不裁剪——回填是 defaultsFrom，裁剪是 removeExtraFields。
- *   校验器出错的最大代价必须始终是"少一条警告"，因此它绝不参与配置取值链路。
- * - **只解释中立词汇**：type/required 之外的语义（含宿主经 declaration merging
- *   注入的呈现属性，如 secret/allowCustom）一概不解读。
- * - **options 不作为取值白名单**：中立契约里 options 只是"静态选项"（呈现语义），
- *   是否允许选项外的值由宿主属性（allowCustom）决定，而本包看不见宿主属性，
- *   故 select/multiselect 只查原始类型不查成员资格。
+ * - **只读**：不转换、不回填、不裁剪——回填是 defaultsFrom，裁剪是 removeExtraFields，取值是 parseConfig。
+ *   逐字段判定与 parseConfig 共用同一份：这里报 invalid 的值，parseConfig 会回落、忽略或拒绝。
+ *   校验器出错的最大代价必须始终是"少一条警告"，因此它对畸形 schema 不抛错。
+ * - **只解释本包的词汇**：type/required、约束键、影响取值的 dynamicOptions/allowCustom 与 secret；
+ *   宿主经 declaration merging 注入的呈现属性一概不解读。
+ * - **校验的是文档**：`secret` 字段上的 {@link SecretRef} 算合法（值在宿主的密钥存储里），不查引用的键在不在。
+ * - **标量宽容**：期望字符串的位置（string/textarea、list 元素、map 值、选项比较）接受有限数字；
+ *   期望数字的位置接受去掉首尾空白后能完整解析为有限数的字符串。boolean 不做转换。
+ * - **options 即取值范围**：select 有静态 options、没有 dynamicOptions 且 allowCustom 不为 true 时，值须是
+ *   某个选项值（按字符串比较）；multiselect 同样逐元素判定。
  * - **约束键**：number 强制 min/max（含边界）与 integer，string/textarea 强制
- *   pattern（模式非法则跳过该检查）；step 是纯 UI 提示不校验。约束只在类型
+ *   pattern（模式非法则跳过该检查）与 format（空串与只有空白不查）；step 是纯 UI 提示不校验。约束只在类型
  *   检查通过后评估——类型都不对时报类型错，不叠报约束错。
- * - **list / map**：list 须为数组且每个元素是 string（保序、重复合法）；map 须为
- *   对象且每个值是 string，逐值报错的路径形如 `env.KEY`。
- * - **宽容缺失**：undefined 与 null（YAML 裸键）视为"未配置"，仅在 required 且
- *   未声明 default 时报缺——顶层/分组的默认值在调用点已合并，数组元素的默认值
+ * - **list / map**：list 须为数组、map 须为对象，逐元素 / 逐值报错，路径形如 `args[1]`、`env.KEY`。
+ * - **宽容缺失**：undefined 与 null（YAML 裸键）视为"未配置"，required 字段的 `''` 也算未配置（WebUI 与脚手架
+ *   用 `''` 表示未填，与 parseConfig 一致；声明了 format 的只有空白也算；空数组仍算已配置），仅在 required 且未声明 default 时报缺——顶层/分组的默认值在调用点已合并，数组元素的默认值
  *   不参与合并（defaultsFrom 把 SchemaArray 当叶子），靠 default 声明本身放行。
  *
- * 政策留给调用方：config-sync 对启用插件打 warn（不拒载，存量脏值不打死实例；
- * 禁用插件的配置是休眠数据，不告警），webui 的 PUT 只拦**新增**的 `invalid`
- * （存量问题与 `missing` 放行——拦新不追旧，半成品配置允许落盘）。
+ * 政策留给调用方：config-sync 对启用插件打 warn（禁用插件的配置是休眠数据，不告警），
+ * webui 的 PUT 只拦**新增**的 `invalid`（存量问题与 `missing` 放行——拦新不追旧，半成品配置允许落盘）。
  */
 export function validateConfig(schema, config) {
     const issues = [];
     validateFields(schema ?? {}, config, '', issues);
     return issues;
 }
+/**
+ * 按 schema 解析插件拿到的配置，返回 {@link ConfigOf} 类型的新对象（不改入参）。插件在 apply 里用它读配置：
+ * `const cfg = parseConfig(configSchema, caps.config, caps.logger)`，之后的夹紧、跨字段约束等核对作用于 cfg。
+ *
+ * - **缺失**：undefined 与 null；required 字段另把 `''` 当作缺失（WebUI 与脚手架用 `''` 表示未填；声明了 format 的
+ *   只有空白也算），外来类型的 `''` 一律当作缺失。有 default 用 default（拷贝），无 default 且 required 不可恢复，否则省略该键。
+ * - **无效**：逐字段判定与 validateConfig 共用（标量宽容、选项即取值范围、约束键）。
+ *   默认有 default 回落并告警；无 default 且 required 不可恢复；否则省略并告警。
+ *   `onInvalid: 'error'` 的字段遇到显式无效值或坏集合成员时，即使有 default 也不可恢复。
+ * - **外来类型**：除 `''` 外原样透传，不校验。
+ * - **密钥字段**：宿主交给插件之前已把引用解析成原值；`secret` 字段上仍是 {@link SecretRef}，说明引用的键不在
+ *   宿主的密钥存储里，一律不可恢复（不回落 default，数组元素里的也不只丢这一条），消息点名键名。owner 写了引用，
+ *   引用落空就是配置错误，回落默认值会悄悄连上别的东西（例如默认的本机数据库）。
+ * - **list / map / multiselect**：默认坏元素、坏值逐个丢弃并告警；严格字段拒绝整个值。
+ * - **分组**：值不是对象时默认告警并按空对象解析；含严格字段时拒绝显式无效的分组值。
+ * - **数组**：值不是数组按无效处理，含严格元素字段时拒绝显式无效的数组值；元素不是对象、或元素内有不可恢复的字段时只丢这一条元素并告警；
+ *   数组自身声明 `onInvalid: 'error'` 时不丢元素而是拒绝整个数组。元素字段的默认值逐元素补齐。
+ * - **schema 外的键**：丢弃并告警。
+ * - **不可恢复**（顶层或分组内）：缺失抛 {@link missingConfigError}，无效抛 {@link configError}，插件随之进 error 态。
+ *
+ * 告警只写路径、类型名与约束，不写原值（可能是密钥）；默认值可以写。
+ */
+export function parseConfig(schema, raw, logger) {
+    const warn = (message) => logger?.warn(message);
+    let source = {};
+    if (isRecord(raw))
+        source = raw;
+    else if (raw !== undefined && raw !== null) {
+        if (hasStrictField(schema))
+            throw configError('配置整体期望对象，在 WebUI 或配置文件中改正后生效');
+        warn(`配置整体期望对象，得到 ${describeType(raw)}，已忽略`);
+    }
+    try {
+        return parseEntries(schema, source, '', warn);
+    }
+    catch (err) {
+        if (!(err instanceof UnrecoverableField))
+            throw err;
+        throw err.missing
+            ? missingConfigError(err.path)
+            : configError(`配置项 ${err.path} ${err.reason}，在 WebUI 或配置文件中改正后生效`);
+    }
+}
 /**
  * 按 schema 键集裁掉未知字段。configSchema 是插件配置的**唯一声明来源**（默认值也从它派生），
  * 所以它的键集就是完整的白名单：不在 schema 里的字段，要么是用户手写的错别字，
  * 要么是已废弃的旧字段，裁掉即归位。无 schema 的插件不裁（见调用方守卫）。
  *
  * 被裁的键写入 `removed`（带点号前缀）——静默裁剪会让「字段被吃掉」与「用户没配」不可分辨。
- * `type: 'array'` 的值整段保留（数组元素结构由 validateConfig 解释，不在这里拆）。
+ * `type: 'array'` 的值整段保留（数组元素结构由 validateConfig / parseConfig 解释，不在这里拆）。
  */
 export function removeExtraFields(config, schema, removed, prefix = '') {
     const result = {};
     for (const [key, value] of Object.entries(config)) {
-        if (!(key in schema)) {
+        // 只认 schema 的自有键：配置里的 toString、valueOf 这类键不能靠原型上的同名属性逃过裁剪
+        if (!Object.hasOwn(schema, key)) {
             removed?.push(prefix + key);
             continue;
         }
@@ -180,7 +320,7 @@ function validateFields(schema, config, prefix, issues) {
         if ('fields' in entry) {
             if (value === undefined || value === null)
                 continue;
-            if (typeof value !== 'object' || Array.isArray(value)) {
+            if (!isRecord(value)) {
                 issues.push({ path, message: `期望对象（分组），得到 ${describeType(value)}`, kind: 'invalid' });
                 continue;
             }
@@ -195,7 +335,7 @@ function validateFields(schema, config, prefix, issues) {
                 continue;
             }
             value.forEach((item, i) => {
-                if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+                if (!isRecord(item)) {
                     issues.push({ path: `${path}[${i}]`, message: `期望对象元素，得到 ${describeType(item)}`, kind: 'invalid' });
                     return;
                 }
@@ -203,7 +343,7 @@ function validateFields(schema, config, prefix, issues) {
             });
             continue;
         }
-        if (value === undefined || value === null) {
+        if (value === undefined || value === null || (entry.required && isBlank(entry, value))) {
             // 声明了 default 的字段永远不算缺失：顶层/分组的默认值多已在调用点合并，但合并不覆盖
             // 显式 null（YAML 裸键），这类值照样走到这里，
             // 数组元素的默认值不参与任何合并（defaultsFrom 把 SchemaArray 当叶子），
@@ -212,101 +352,185 @@ function validateFields(schema, config, prefix, issues) {
                 issues.push({ path, message: '必填字段缺失', kind: 'missing' });
             continue;
         }
+        if (entry.secret === true && isSecretRef(value))
+            continue;
         if (!NEUTRAL_FIELD_TYPES.has(entry.type))
             continue;
-        switch (entry.type) {
-            case 'string':
-            case 'textarea':
-                if (typeof value !== 'string') {
-                    issues.push({ path, message: `期望 string，得到 ${describeType(value)}`, kind: 'invalid' });
-                }
-                else if (entry.pattern !== undefined) {
-                    // 模式本身非法（作者的 schema bug）时跳过该检查——校验器不得因 schema
-                    // 缺陷抛错或误伤值；作者侧问题由类型检查与测试兜。
-                    try {
-                        if (!new RegExp(entry.pattern).test(value)) {
-                            issues.push({ path, message: `不匹配模式 ${entry.pattern}`, kind: 'invalid' });
-                        }
-                    }
-                    catch {
-                        /* 非法 pattern：跳过 */
-                    }
-                }
-                break;
-            case 'number':
-                if (typeof value !== 'number' || !Number.isFinite(value)) {
-                    issues.push({ path, message: `期望有限数值，得到 ${describeType(value)}`, kind: 'invalid' });
-                }
-                else if (entry.integer && !Number.isInteger(value)) {
-                    issues.push({ path, message: '期望整数', kind: 'invalid' });
-                }
-                else if (entry.min !== undefined && value < entry.min) {
-                    issues.push({ path, message: `小于下限 ${entry.min}`, kind: 'invalid' });
-                }
-                else if (entry.max !== undefined && value > entry.max) {
-                    issues.push({ path, message: `大于上限 ${entry.max}`, kind: 'invalid' });
-                }
-                break;
-            case 'boolean':
-                if (typeof value !== 'boolean')
-                    issues.push({ path, message: `期望 boolean，得到 ${describeType(value)}`, kind: 'invalid' });
-                break;
-            case 'select':
-                if (typeof value !== 'string' && typeof value !== 'number') {
-                    issues.push({ path, message: `期望 string 或 number，得到 ${describeType(value)}`, kind: 'invalid' });
-                }
-                break;
-            case 'multiselect':
-                if (!Array.isArray(value)) {
-                    issues.push({ path, message: `期望数组，得到 ${describeType(value)}`, kind: 'invalid' });
-                }
-                else {
-                    value.forEach((item, i) => {
-                        if (typeof item !== 'string' && typeof item !== 'number') {
-                            issues.push({
-                                path: `${path}[${i}]`,
-                                message: `期望 string 或 number 元素，得到 ${describeType(item)}`,
-                                kind: 'invalid',
-                            });
-                        }
-                    });
-                }
-                break;
-            case 'list':
-                if (!Array.isArray(value)) {
-                    issues.push({ path, message: `期望数组，得到 ${describeType(value)}`, kind: 'invalid' });
-                }
-                else {
-                    value.forEach((item, i) => {
-                        if (typeof item !== 'string') {
-                            issues.push({
-                                path: `${path}[${i}]`,
-                                message: `期望 string 元素，得到 ${describeType(item)}`,
-                                kind: 'invalid',
-                            });
-                        }
-                    });
+        const verdict = judgeField(entry, value);
+        if ('invalid' in verdict) {
+            issues.push({ path, message: verdict.invalid, kind: 'invalid' });
+            continue;
+        }
+        for (const d of verdict.dropped)
+            issues.push({ path: path + d.at, message: d.reason, kind: 'invalid' });
+    }
+}
+function judgeField(field, value) {
+    switch (field.type) {
+        case 'string':
+        case 'textarea': {
+            const text = asText(value);
+            if (text === undefined)
+                return { invalid: `期望 string，得到 ${describeType(value)}` };
+            if (field.pattern !== undefined && !matchesPattern(field.pattern, text)) {
+                return { invalid: `不匹配模式 ${field.pattern}` };
+            }
+            if (field.format === undefined)
+                return { value: text, dropped: [] };
+            // 路径按去掉首尾空白后判定，交出去的也是这一份：带空白的原值交给插件会被当成相对路径或找不到
+            const path = text.trim();
+            if (path !== '' && !matchesFormat(field.format, path)) {
+                return { invalid: field.format === 'executable' ? '须为绝对路径或命令名（不含路径分隔符）' : '须为绝对路径' };
+            }
+            return { value: path, dropped: [] };
+        }
+        case 'number': {
+            const num = asNumber(value);
+            if (num === undefined)
+                return { invalid: `期望有限数值，得到 ${describeType(value)}` };
+            if (field.integer && !Number.isInteger(num))
+                return { invalid: '期望整数' };
+            if (field.min !== undefined && num < field.min)
+                return { invalid: `小于下限 ${field.min}` };
+            if (field.max !== undefined && num > field.max)
+                return { invalid: `大于上限 ${field.max}` };
+            return { value: num, dropped: [] };
+        }
+        case 'boolean':
+            return typeof value === 'boolean'
+                ? { value, dropped: [] }
+                : { invalid: `期望 boolean，得到 ${describeType(value)}` };
+        case 'select': {
+            const text = asText(value);
+            if (text === undefined)
+                return { invalid: `期望 string 或 number，得到 ${describeType(value)}` };
+            const options = field.allowCustom === true ? undefined : choiceOptions(field);
+            if (!options)
+                return { value: text, dropped: [] };
+            const hit = options.find(o => String(o.value) === text);
+            return hit ? { value: hit.value, dropped: [] } : { invalid: notAnOption(options) };
+        }
+        case 'multiselect': {
+            if (!Array.isArray(value))
+                return { invalid: `期望数组，得到 ${describeType(value)}` };
+            const options = field.allowCustom === true ? undefined : choiceOptions(field);
+            const kept = [];
+            const dropped = [];
+            for (let i = 0; i < value.length; i++) {
+                const item = value[i];
+                const text = asText(item);
+                if (text === undefined) {
+                    dropped.push({ at: `[${i}]`, reason: `期望 string 或 number 元素，得到 ${describeType(item)}` });
                 }
-                break;
-            case 'map':
-                if (typeof value !== 'object' || Array.isArray(value)) {
-                    issues.push({ path, message: `期望对象（映射），得到 ${describeType(value)}`, kind: 'invalid' });
+                else if (!options) {
+                    kept.push(text);
                 }
                 else {
-                    for (const [k, v] of Object.entries(value)) {
-                        if (typeof v !== 'string') {
-                            issues.push({
-                                path: `${path}.${k}`,
-                                message: `期望 string 值，得到 ${describeType(v)}`,
-                                kind: 'invalid',
-                            });
-                        }
-                    }
+                    const hit = options.find(o => String(o.value) === text);
+                    if (hit)
+                        kept.push(hit.value);
+                    else
+                        dropped.push({ at: `[${i}]`, reason: notAnOption(options) });
                 }
-                break;
+            }
+            return { value: kept, dropped };
         }
+        case 'list': {
+            if (!Array.isArray(value))
+                return { invalid: `期望数组，得到 ${describeType(value)}` };
+            const kept = [];
+            const dropped = [];
+            for (let i = 0; i < value.length; i++) {
+                const item = value[i];
+                const text = asText(item);
+                if (text === undefined)
+                    dropped.push({ at: `[${i}]`, reason: `期望 string 元素，得到 ${describeType(item)}` });
+                else
+                    kept.push(text);
+            }
+            return { value: kept, dropped };
+        }
+        case 'map': {
+            if (!isRecord(value))
+                return { invalid: `期望对象（映射），得到 ${describeType(value)}` };
+            const kept = {};
+            const dropped = [];
+            for (const [k, v] of Object.entries(value)) {
+                const text = asText(v);
+                if (text === undefined)
+                    dropped.push({ at: `.${k}`, reason: `期望 string 值，得到 ${describeType(v)}` });
+                // 危险键不进结果对象：写 `__proto__` 会改掉结果的原型
+                else if (isUnsafeConfigKey(k))
+                    dropped.push({ at: `.${k}`, reason: '保留键不可用' });
+                else
+                    kept[k] = text;
+            }
+            return { value: kept, dropped };
+        }
+        default:
+            return { value, dropped: [] };
+    }
+}
+/**
+ * 填的是空串（WebUI 与脚手架用 `''` 表示未填）。声明了 format 的 string / textarea 交给插件的是去掉首尾空白的那份
+ * （见 judgeField），只有空白同样算空串
+ */
+function isBlank(field, value) {
+    if (typeof value !== 'string')
+        return false;
+    const trims = field.format !== undefined && (field.type === 'string' || field.type === 'textarea');
+    return (trims ? value.trim() : value) === '';
+}
+/** 期望字符串的位置：字符串原样，有限数字转成字符串（YAML 里不加引号的 QQ 号、端口照常可用） */
+function asText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+/** 期望数字的位置：有限数字原样，去掉首尾空白后非空、能完整解析为有限数的字符串转成数字（YAML 里加了引号的数字照常可用） */
+function asNumber(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== 'string' || value.trim() === '')
+        return undefined;
+    const num = Number(value);
+    return Number.isFinite(num) ? num : undefined;
+}
+/** 构成取值范围的静态选项：有非空 options 且没有 dynamicOptions（动态来源的选项在运行时才知道，静态列表不完整） */
+function choiceOptions(field) {
+    if (field.dynamicOptions !== undefined || !Array.isArray(field.options))
+        return undefined;
+    const options = field.options.filter(o => o !== null && typeof o === 'object');
+    return options.length > 0 ? options : undefined;
+}
+function notAnOption(options) {
+    return `不是可选值（${options.map(o => JSON.stringify(o.value)).join('、')}）之一`;
+}
+function matchesPattern(pattern, text) {
+    // 模式本身非法（作者的 schema bug）时跳过该检查——判定不得因 schema
+    // 缺陷抛错或误伤值；作者侧问题由类型检查与测试兜。
+    try {
+        return new RegExp(pattern).test(text);
+    }
+    catch {
+        return true;
     }
 }
+/** POSIX 绝对路径、Windows 盘符路径或 UNC 路径 */
+const ABSOLUTE_PATH = /^(?:\/|[A-Za-z]:[\\/]|\\\\)/;
+function matchesFormat(format, text) {
+    if (ABSOLUTE_PATH.test(text))
+        return true;
+    if (format === 'executable')
+        return !/[\\/]/.test(text) && !/^[A-Za-z]:/.test(text);
+    // 不认识的写法（作者的 schema bug）同 pattern 一样跳过
+    return format !== 'absolute-path';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 function describeType(value) {
     if (value === null)
         return 'null';
@@ -316,6 +540,173 @@ function describeType(value) {
         return String(value);
     return typeof value;
 }
+/**
+ * 顶层或分组内无法恢复的字段：parseConfig 把它转成 missingConfigError / configError 抛出，数组元素内只丢这一条元素；
+ * `fatal` 的（没解析的密钥引用）在数组元素里也让整次解析失败
+ */
+class UnrecoverableField extends Error {
+    path;
+    reason;
+    missing;
+    fatal;
+    constructor(path, reason, missing, fatal = false) {
+        super(`${path} ${reason}`);
+        this.path = path;
+        this.reason = reason;
+        this.missing = missing;
+        this.fatal = fatal;
+    }
+}
+/** 只在祖先值显式无效时检查；缺省的容器仍按字段原有的缺省规则解析。 */
+function hasStrictField(schema) {
+    if (!isRecord(schema))
+        return false;
+    return Object.values(schema).some(entry => {
+        if (!isRecord(entry))
+            return false;
+        if (entry.onInvalid === 'error')
+            return true;
+        if ('fields' in entry)
+            return hasStrictField(entry.fields);
+        if (entry.type === 'array')
+            return hasStrictField(entry.items);
+        return false;
+    });
+}
+function parseEntries(schema, source, prefix, warn) {
+    // 畸形 schema（分组 fields 为 null、数组缺 items、条目为原始值）按空处理，不抛错
+    const entries = isRecord(schema) ? schema : {};
+    const out = {};
+    for (const [key, entry] of Object.entries(entries)) {
+        if (!isRecord(entry) || isUnsafeConfigKey(key))
+            continue;
+        const path = prefix + key;
+        // 只认自有属性：`toString` 这类键不能从原型上读到值
+        const value = Object.hasOwn(source, key) ? source[key] : undefined;
+        let parsed;
+        if ('fields' in entry)
+            parsed = parseGroup(entry.fields, value, path, warn);
+        else if (entry.type === 'array')
+            parsed = parseArray(entry, value, path, warn);
+        else
+            parsed = parseField(entry, value, path, warn);
+        if (parsed !== undefined)
+            out[key] = parsed;
+    }
+    for (const key of Object.keys(source)) {
+        if (!Object.hasOwn(entries, key))
+            warn(`配置项 ${prefix + key} 不在 schema 中，已忽略`);
+    }
+    return out;
+}
+function parseGroup(fields, value, path, warn) {
+    let source = {};
+    if (isRecord(value))
+        source = value;
+    else if (value !== undefined && value !== null) {
+        if (hasStrictField(fields))
+            throw new UnrecoverableField(path, '期望对象（分组）', false);
+        warn(`配置项 ${path} 期望对象（分组），得到 ${describeType(value)}，已忽略`);
+    }
+    return parseEntries(fields, source, `${path}.`, warn);
+}
+function parseField(field, value, path, warn) {
+    const neutral = NEUTRAL_FIELD_TYPES.has(field.type);
+    if (value === undefined || value === null || (field.required ? isBlank(field, value) : value === '' && !neutral)) {
+        if (field.default !== undefined)
+            return cloneConfigValue(field.default);
+        if (field.required)
+            throw new UnrecoverableField(path, '必填字段缺失', true);
+        return undefined;
+    }
+    if (field.secret === true && isSecretRef(value)) {
+        throw new UnrecoverableField(path, `引用的密钥 ${value.$secret} 不在宿主的密钥存储里`, false, true);
+    }
+    if (!neutral)
+        return cloneConfigValue(value);
+    const verdict = judgeField(field, value);
+    if ('invalid' in verdict)
+        return fallBack(field, path, verdict.invalid, warn);
+    if (field.onInvalid === 'error' && verdict.dropped.length > 0) {
+        const first = verdict.dropped[0];
+        // map 键来自配置，可能本身是密钥；集合下标则可安全指出。
+        const memberPath = field.type === 'map' ? path : path + first.at;
+        throw new UnrecoverableField(memberPath, safeInvalidReason(first.reason), false);
+    }
+    for (const d of verdict.dropped)
+        warn(`配置项 ${path}${d.at} ${d.reason}，已忽略`);
+    return verdict.value;
+}
+function parseArray(entry, value, path, warn) {
+    let list = value;
+    if (value === undefined || value === null) {
+        list = entry.default;
+    }
+    else if (!Array.isArray(value)) {
+        if (hasStrictField(entry.items))
+            throw new UnrecoverableField(path, '期望数组', false);
+        list = fallBack(entry, path, `期望数组，得到 ${describeType(value)}`, warn);
+    }
+    // 默认值同样逐元素解析：元素字段的默认值要补齐；default 本身不是数组（畸形 schema）按未配置处理
+    if (!Array.isArray(list))
+        return undefined;
+    const out = [];
+    for (let i = 0; i < list.length; i++) {
+        const item = list[i];
+        const at = `${path}[${i}]`;
+        if (!isRecord(item)) {
+            if (entry.onInvalid === 'error')
+                throw new UnrecoverableField(at, '期望对象元素', false);
+            warn(`配置项 ${at} 已忽略：期望对象元素，得到 ${describeType(item)}`);
+            continue;
+        }
+        // 元素内的告警先攒着：这条元素整条丢弃时只报丢弃原因
+        const pending = [];
+        try {
+            out.push(parseEntries(entry.items, item, `${at}.`, message => pending.push(message)));
+        }
+        catch (err) {
+            if (!(err instanceof UnrecoverableField))
+                throw err;
+            if (entry.onInvalid === 'error' || err.fatal)
+                throw err;
+            warn(`配置项 ${at} 已忽略：${err.path.slice(at.length + 1)} ${err.reason}`);
+            continue;
+        }
+        for (const message of pending)
+            warn(message);
+    }
+    return out;
+}
+/** 无效值的处置：有 default 回落并告警；无 default 且 required 不可恢复；否则省略并告警 */
+function fallBack(entry, path, reason, warn) {
+    if (entry.onInvalid === 'error')
+        throw new UnrecoverableField(path, safeInvalidReason(reason), false);
+    if (entry.default !== undefined) {
+        warn(`配置项 ${path} ${reason}，改用默认值 ${describeDefault(entry.default)}`);
+        return cloneConfigValue(entry.default);
+    }
+    if (entry.required)
+        throw new UnrecoverableField(path, reason, false);
+    warn(`配置项 ${path} ${reason}，已忽略`);
+    return undefined;
+}
+/** 错误可说明类型与约束，但不列出用户值、静态选项值或正则文本。 */
+function safeInvalidReason(reason) {
+    if (reason.startsWith('不是可选值'))
+        return '不是可选值';
+    if (reason.startsWith('不匹配模式'))
+        return '不匹配模式';
+    return reason.replace(/得到 (?:NaN|-?Infinity)/g, '得到 number');
+}
+function describeDefault(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
 // 与 packages/core/src/infrastructure/config-values.ts 同一规则（本包零运行时依赖，不能 import core）。
 // 防漂移：test/architecture/config-copy-parity.test.ts
 const UNSAFE_CONFIG_KEYS = new Set(['__proto__', 'constructor', 'prototype']);