@aalis/schema-config 0.14.0 → 0.16.0

package/dist/index.js

@@ -5,7 +5,7 @@
 // ConfigOf 从同一份 schema 推导配置值类型；
 // 函数部分是对这套词汇的**中立解释**：默认值派生（defaultsFrom）与深合并（deepMergeDefaults）、
 // 只读结构校验（validateConfig）、按 schema 键集裁未知字段（removeExtraFields）、
-// 按 schema 解析插件拿到的配置（parseConfig）。
+// 按 schema 解析插件拿到的配置（parseConfig）与单个取值的判定（readFieldValue）。
 // 它们都不属于 @aalis/core——core 只把 `PluginMeta.configSchema` 当作
 // opaque 数据透传，不解释任何字段。另有插件因配置问题无法激活时抛的错误（configError / missingConfigError）。
 //
@@ -14,8 +14,70 @@
 // - 渲染宿主（webui-server/client 等）：读取并渲染表单
 // - 宿主政策（@aalis/runtime 的 config-sync）：按 schema 裁剪未知字段、校验告警
 //
-// 本包零运行时依赖：对 @aalis/core 仅有 type-only 锚点 import（编译后擦除）。
+// 给人看的文字（表单的 label 与说明、校验原因、配置错误）是 @aalis/schema-i18n 的文字对象，由出口按读者语言渲染。
+// 运行时只依赖同样零依赖的 @aalis/schema-i18n；对 @aalis/core 仅有 type-only 锚点 import（编译后擦除）。
 // ============================================================
+import { isTextRef, withText } from '@aalis/schema-i18n';
+import { t } from './texts.js';
+/** 是不是密钥引用：只有 `$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);
+}
+/**
+ * 顶层条目是不是可按会话覆盖的字段：是字段（不是分组、数组）且 session 不为 undefined。只对 configSchema 的顶层条目问，
+ * 分组与数组元素里的字段不按它判
+ */
+export function isSessionField(entry) {
+    return isRecord(entry) && !('fields' in entry) && entry.type !== 'array' && entry.session !== undefined;
+}
 /**
  * 声明插件的配置 schema：运行时原样返回传入的对象（不冻结、不加任何属性），类型层保留字面量，
  * 供 {@link ConfigOf} 推出配置值类型。返回值可直接放进 `definePlugin({ configSchema })`。
@@ -36,14 +98,14 @@ export function defineConfig(schema) {
 export const CORE_CONFIG_SCHEMA = {
     name: {
         type: 'string',
-        label: '应用名称',
-        description: '应用显示名称，用于启动日志和界面展示；装有人设时仪表盘仍显示它，聊天显示人设名',
+        label: t('nameLabel'),
+        description: t('nameDescription'),
         default: 'Aalis',
     },
     logLevel: {
         type: 'select',
-        label: '日志等级',
-        description: '日志输出等级',
+        label: t('logLevelLabel'),
+        description: t('logLevelDescription'),
         default: 'info',
         options: [
             { label: 'debug', value: 'debug' },
@@ -54,14 +116,19 @@ export const CORE_CONFIG_SCHEMA = {
     },
     slowThresholdMs: {
         type: 'number',
-        label: '慢操作阈值（毫秒）',
-        description: '插件激活超过它仍未完成时告警并转入后台继续（它提供的服务在激活完成前不对依赖方开放），app 启动与停机阶段的单个事件监听器超过它时告警并不再等待；0 表示不设限；重启生效',
+        label: t('slowThresholdLabel'),
+        description: t('slowThresholdDescription'),
         default: 60000,
         min: 0,
     },
 };
 /**
- * 从 ConfigSchema 派生默认配置。
+ * 宿主配置里只在启动时读、改了要重启才生效的核心键：runtime 启动时读它们交给 core，WebUI 设置页据此标「重启后生效」。
+ * runtime 改了哪些键只在启动时读，同步改这一份。name 只是显示用的应用名称，保存即生效
+ */
+export const CORE_RESTART_KEYS = ['logLevel', 'slowThresholdMs'];
+/**
+ * 从 ConfigSchema 派生默认配置（密钥字段除外）。
  *
  * ConfigSchema 是插件配置的**唯一声明来源**：每个字段的 `default` 就是运行时默认值，
  * 不存在第二份手抄的默认值对象。宿主在注册插件前用本函数派生出默认配置并深合并进配置文档，
@@ -71,6 +138,8 @@ export const CORE_CONFIG_SCHEMA = {
  * - SchemaField / SchemaArray：取 `default`（没写 default 的字段不产出键，
  *   等同于「该字段无默认值」——读取方自行处理 undefined）
  * - SchemaGroup：递归 `fields`，总是产出嵌套对象（即使子字段全无默认值）
+ * - `secret: true` 的字段不产出：派生结果会被写进配置文档，密钥的默认值不进文档（map 的默认值还会被深合并进
+ *   引用对象），插件经 parseConfig 照常补上
  */
 export function defaultsFrom(schema) {
     const out = {};
@@ -83,6 +152,8 @@ export function defaultsFrom(schema) {
             out[key] = defaultsFrom(entry.fields);
             continue;
         }
+        if (entry.secret === true)
+            continue;
         if ('default' in entry)
             out[key] = cloneConfigValue(entry.default);
     }
@@ -111,8 +182,8 @@ export function deepMergeDefaults(defaults, current) {
     return result;
 }
 // 校验与解析在运行时需要一份"本包内置类型"名单：SchemaFieldTypes 是纯类型层的
-// merging 注册表，运行时不存在。外来类型（如 'llm-ref'）落在名单之外，
-// validateConfig 一律跳过放行、parseConfig 原样透传——开放词汇表要求两者同样开放。
+// merging 注册表，运行时不存在。外来类型（如 'llm-ref'）落在名单之外，不经类型判定、只过字段自己的 validate：
+// validateConfig 放行、parseConfig 原样透传——开放词汇表要求两者同样开放。
 const NEUTRAL_FIELD_TYPES = new Set([
     'string',
     'number',
@@ -123,25 +194,36 @@ const NEUTRAL_FIELD_TYPES = new Set([
     'list',
     'map',
 ]);
+/**
+ * 字段类型是不是本包内置的：内置类型的取值经 validateConfig 与 parseConfig 按类型校验，外来类型（如 'llm-ref'）的
+ * 只过字段的 validate
+ */
+export function isBuiltinFieldType(type) {
+    return NEUTRAL_FIELD_TYPES.has(type);
+}
 /**
  * 按 ConfigSchema 对配置做只读结构校验，返回问题清单（空数组 = 无问题）。
  *
  * 定位与边界：
  * - **只读**：不转换、不回填、不裁剪——回填是 defaultsFrom，裁剪是 removeExtraFields，取值是 parseConfig。
- *   逐字段判定与 parseConfig 共用同一份：这里报 invalid 的值，parseConfig 会回落、忽略或拒绝。
+ *   逐字段判定与 parseConfig 共用同一份：这里报 invalid 的值，parseConfig 会回落、忽略或拒绝（带 session 的顶层字段除外，
+ *   parseConfig 不交出它）。
  *   校验器出错的最大代价必须始终是"少一条警告"，因此它对畸形 schema 不抛错。
- * - **只解释本包的词汇**：type/required、约束键与影响取值的 dynamicOptions/allowCustom；
- *   宿主经 declaration merging 注入的呈现属性（如 secret）一概不解读。
+ * - **只解释本包的词汇**：type/required、约束键、影响取值的 dynamicOptions/allowCustom、secret 与字段自己的 validate；
+ *   宿主经 declaration merging 注入的呈现属性一概不解读。带 session 的字段照常校验（它的全局层就在配置文档里）。
+ * - **校验的是文档**：`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 提示不校验。约束只在类型
  *   检查通过后评估——类型都不对时报类型错，不叠报约束错。
+ * - **validate**：类型与约束键都过了才调，拿换算后的取值；返回原因报 invalid（code 为 `validate`），抛错同样报，不外传。
+ *   list、map、multiselect 有坏元素时只报元素、不调它：它拿到的会是剔掉坏元素的值，报的原因对不上文档里写的。
  * - **list / map**：list 须为数组、map 须为对象，逐元素 / 逐值报错，路径形如 `args[1]`、`env.KEY`。
  * - **宽容缺失**：undefined 与 null（YAML 裸键）视为"未配置"，required 字段的 `''` 也算未配置（WebUI 与脚手架
- *   用 `''` 表示未填，与 parseConfig 一致；空数组仍算已配置），仅在 required 且未声明 default 时报缺——顶层/分组的默认值在调用点已合并，数组元素的默认值
+ *   用 `''` 表示未填，与 parseConfig 一致；声明了 format 的只有空白也算；空数组仍算已配置），仅在 required 且未声明 default 时报缺——顶层/分组的默认值在调用点已合并，数组元素的默认值
  *   不参与合并（defaultsFrom 把 SchemaArray 当叶子），靠 default 声明本身放行。
  *
  * 政策留给调用方：config-sync 对启用插件打 warn（禁用插件的配置是休眠数据，不告警），
@@ -156,12 +238,17 @@ export function validateConfig(schema, config) {
  * 按 schema 解析插件拿到的配置，返回 {@link ConfigOf} 类型的新对象（不改入参）。插件在 apply 里用它读配置：
  * `const cfg = parseConfig(configSchema, caps.config, caps.logger)`，之后的夹紧、跨字段约束等核对作用于 cfg。
  *
- * - **缺失**：undefined 与 null；required 字段另把 `''` 当作缺失（WebUI 与脚手架用 `''` 表示未填），
- *   外来类型的 `''` 一律当作缺失。有 default 用 default（拷贝），无 default 且 required 不可恢复，否则省略该键。
- * - **无效**：逐字段判定与 validateConfig 共用（标量宽容、选项即取值范围、约束键）。
+ * - **缺失**：undefined 与 null；required 字段另把 `''` 当作缺失（WebUI 与脚手架用 `''` 表示未填；声明了 format 的
+ *   只有空白也算），外来类型的 `''` 一律当作缺失。有 default 用 default（拷贝），无 default 且 required 不可恢复，否则省略该键。
+ * - **无效**：逐字段判定与 validateConfig 共用（标量宽容、选项即取值范围、约束键、字段的 validate）。
+ *   list、map、multiselect 先丢坏元素，validate 判的是剩下的值。
  *   默认有 default 回落并告警；无 default 且 required 不可恢复；否则省略并告警。
  *   `onInvalid: 'error'` 的字段遇到显式无效值或坏集合成员时，即使有 default 也不可恢复。
- * - **外来类型**：除 `''` 外原样透传，不校验。
+ * - **外来类型**：除 `''` 外原样透传，只过字段的 validate。
+ * - **带 session 的顶层字段**：不交出、不补 default，配置里有这个键也不告警（插件经会话设置的读取器读）。
+ * - **密钥字段**：宿主交给插件之前已把引用解析成原值；`secret` 字段上仍是 {@link SecretRef}，说明引用的键不在
+ *   宿主的密钥存储里，一律不可恢复（不回落 default，数组元素里的也不只丢这一条），消息点名键名。owner 写了引用，
+ *   引用落空就是配置错误，回落默认值会悄悄连上别的东西（例如默认的本机数据库）。
  * - **list / map / multiselect**：默认坏元素、坏值逐个丢弃并告警；严格字段拒绝整个值。
  * - **分组**：值不是对象时默认告警并按空对象解析；含严格字段时拒绝显式无效的分组值。
  * - **数组**：值不是数组按无效处理，含严格元素字段时拒绝显式无效的数组值；元素不是对象、或元素内有不可恢复的字段时只丢这一条元素并告警；
@@ -169,7 +256,7 @@ export function validateConfig(schema, config) {
  * - **schema 外的键**：丢弃并告警。
  * - **不可恢复**（顶层或分组内）：缺失抛 {@link missingConfigError}，无效抛 {@link configError}，插件随之进 error 态。
  *
- * 告警只写路径、类型名与约束，不写原值（可能是密钥）；默认值可以写。
+ * 告警只写路径、类型名与约束，不写原值（可能是密钥）；默认值可以写。字段 validate 返回的原因原样写进去。
  */
 export function parseConfig(schema, raw, logger) {
     const warn = (message) => logger?.warn(message);
@@ -177,8 +264,8 @@ export function parseConfig(schema, raw, logger) {
     if (isRecord(raw))
         source = raw;
     else if (raw !== undefined && raw !== null) {
-        if (hasStrictField(schema))
-            throw configError('配置整体期望对象，在 WebUI 或配置文件中改正后生效');
+        if (hasStrictField(schema, true))
+            throw configError(t('notObject'));
         warn(`配置整体期望对象，得到 ${describeType(raw)}，已忽略`);
     }
     try {
@@ -189,9 +276,27 @@ export function parseConfig(schema, raw, logger) {
             throw err;
         throw err.missing
             ? missingConfigError(err.path)
-            : configError(`配置项 ${err.path} ${err.reason}，在 WebUI 或配置文件中改正后生效`);
+            : configError(t('invalid', { path: err.path, reason: err.reason }));
     }
 }
+/**
+ * 单个字段对一个值的判定，与 validateConfig 同一套（类型、约束键、字段的 validate）：合法给出换算后的取值，没配置的
+ * （undefined、null，外来类型与 required 字段的空串）给 `{ value: undefined }`；不合法给出原因，list、map、multiselect
+ * 里有元素不合法也算（取第一个）。不回落 default、不抛错，不拷贝（外来类型的值原样交出）。判的是取值本身：密钥字段上的
+ * 引用不像 validateConfig 那样按文档的写法放行
+ */
+export function readFieldValue(field, value) {
+    if (isUnset(field, value))
+        return { value: undefined };
+    const verdict = judgeField(field, value);
+    if ('invalid' in verdict)
+        return { invalid: verdict.invalid.text };
+    const [dropped] = verdict.dropped;
+    if (dropped)
+        return { invalid: dropped.reason.text };
+    const invalid = runValidate(field, verdict.value);
+    return invalid ? { invalid: invalid.text } : { value: verdict.value };
+}
 /**
  * 按 schema 键集裁掉未知字段。configSchema 是插件配置的**唯一声明来源**（默认值也从它派生），
  * 所以它的键集就是完整的白名单：不在 schema 里的字段，要么是用户手写的错别字，
@@ -230,22 +335,24 @@ export function removeExtraFields(config, schema, removed, prefix = '') {
  *
  * 实例照常转入 error 态，但这不是程序出错：core 的 DefaultLogger 对没有 stack 的错误只写「名称: 消息」，
  * 激活失败日志因此只有一行，不像程序崩溃。缺必填项用 {@link missingConfigError}。
+ * 收文字对象时挂上它（schema-i18n 的 withText，name 不变），出口按读者语言显示，message 是它的原文。
  */
 export function configError(message) {
-    const error = new Error(message);
+    const error = new Error(typeof message === 'string' ? message : message.source);
     error.name = 'ConfigError';
     // 定义成自有属性而不是 delete：有的引擎把 stack 做成原型上的访问器，删实例属性去不掉
     Object.defineProperty(error, 'stack', { value: undefined, writable: true, configurable: true });
-    return error;
+    return typeof message === 'string' ? error : withText(error, message);
 }
 /**
  * 缺少必填配置时的 {@link configError}：消息点名缺的字段（`note` 是放在字段名后括号里的补充说明），并说明
  * 填入后生效——WebUI 保存或配置文件热重载会重建实例、重试激活。
  */
 export function missingConfigError(field, note) {
-    return configError(`缺少配置项 ${field}${note ? `（${note}）` : ''}，在 WebUI 或配置文件中填入后生效`);
+    return configError(note ? t('missingFieldNote', { field, note }) : t('missingField', { field }));
 }
 function validateFields(schema, config, prefix, issues) {
+    const push = (path, kind, { code, text }) => issues.push({ path, message: text.source, kind, code, text });
     // `?? {}` 与 defaultsFrom 同款兜底：畸形 schema（array 缺 items / fields 为 null）
     // 不许把"最多少一条警告"升级成 TypeError——校验器自身永远不能成为故障源。
     for (const [key, entry] of Object.entries(schema ?? {})) {
@@ -257,7 +364,7 @@ function validateFields(schema, config, prefix, issues) {
             if (value === undefined || value === null)
                 continue;
             if (!isRecord(value)) {
-                issues.push({ path, message: `期望对象（分组），得到 ${describeType(value)}`, kind: 'invalid' });
+                push(path, 'invalid', mismatch('expectedGroup', value));
                 continue;
             }
             validateFields(entry.fields, value, `${path}.`, issues);
@@ -267,70 +374,84 @@ function validateFields(schema, config, prefix, issues) {
             if (value === undefined || value === null)
                 continue;
             if (!Array.isArray(value)) {
-                issues.push({ path, message: `期望数组，得到 ${describeType(value)}`, kind: 'invalid' });
+                push(path, 'invalid', mismatch('expectedArray', value));
                 continue;
             }
             value.forEach((item, i) => {
                 if (!isRecord(item)) {
-                    issues.push({ path: `${path}[${i}]`, message: `期望对象元素，得到 ${describeType(item)}`, kind: 'invalid' });
+                    push(`${path}[${i}]`, 'invalid', mismatch('expectedItem', item));
                     return;
                 }
                 validateFields(entry.items, item, `${path}[${i}].`, issues);
             });
             continue;
         }
-        if (value === undefined || value === null || (value === '' && entry.required)) {
+        if (isUnset(entry, value)) {
             // 声明了 default 的字段永远不算缺失：顶层/分组的默认值多已在调用点合并，但合并不覆盖
             // 显式 null（YAML 裸键），这类值照样走到这里，
             // 数组元素的默认值不参与任何合并（defaultsFrom 把 SchemaArray 当叶子），
             // 全靠这里放行——否则 required+default 的 item 字段会误报（scheduler jobs[].platform 型）。
             if (entry.required && !('default' in entry))
-                issues.push({ path, message: '必填字段缺失', kind: 'missing' });
+                push(path, 'missing', { code: 'missing', text: t('missing') });
             continue;
         }
-        if (!NEUTRAL_FIELD_TYPES.has(entry.type))
+        if (entry.secret === true && isSecretRef(value))
             continue;
         const verdict = judgeField(entry, value);
         if ('invalid' in verdict) {
-            issues.push({ path, message: verdict.invalid, kind: 'invalid' });
+            push(path, 'invalid', verdict.invalid);
             continue;
         }
         for (const d of verdict.dropped)
-            issues.push({ path: path + d.at, message: d.reason, kind: 'invalid' });
+            push(path + d.at, 'invalid', d.reason);
+        const invalid = verdict.dropped.length > 0 ? undefined : runValidate(entry, verdict.value);
+        if (invalid)
+            push(path, 'invalid', invalid);
     }
 }
+function mismatch(expected, value) {
+    return { code: 'type', text: t(expected, { got: describeType(value) }) };
+}
+/** 按类型与约束键判，外来类型不判；字段自己的 validate 由调用方处置完 dropped 之后调（runValidate） */
 function judgeField(field, value) {
     switch (field.type) {
         case 'string':
         case 'textarea': {
             const text = asText(value);
             if (text === undefined)
-                return { invalid: `期望 string，得到 ${describeType(value)}` };
+                return { invalid: mismatch('expectedString', value) };
             if (field.pattern !== undefined && !matchesPattern(field.pattern, text)) {
-                return { invalid: `不匹配模式 ${field.pattern}` };
+                return { invalid: { code: 'pattern', text: t('pattern', { pattern: field.pattern }) } };
+            }
+            if (field.format === undefined)
+                return { value: text, dropped: [] };
+            // 路径按去掉首尾空白后判定，交出去的也是这一份：带空白的原值交给插件会被当成相对路径或找不到
+            const path = text.trim();
+            if (path !== '' && !matchesFormat(field.format, path)) {
+                return { invalid: { code: 'format', text: t(field.format === 'executable' ? 'executable' : 'absolutePath') } };
             }
-            return { value: text, dropped: [] };
+            return { value: path, dropped: [] };
         }
         case 'number': {
             const num = asNumber(value);
             if (num === undefined)
-                return { invalid: `期望有限数值，得到 ${describeType(value)}` };
+                return { invalid: mismatch('expectedNumber', 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 { invalid: { code: 'integer', text: t('integer') } };
+            if (field.min !== undefined && num < field.min) {
+                return { invalid: { code: 'min', text: t('min', { min: field.min }) } };
+            }
+            if (field.max !== undefined && num > field.max) {
+                return { invalid: { code: 'max', text: t('max', { max: field.max }) } };
+            }
             return { value: num, dropped: [] };
         }
         case 'boolean':
-            return typeof value === 'boolean'
-                ? { value, dropped: [] }
-                : { invalid: `期望 boolean，得到 ${describeType(value)}` };
+            return typeof value === 'boolean' ? { value, dropped: [] } : { invalid: mismatch('expectedBoolean', value) };
         case 'select': {
             const text = asText(value);
             if (text === undefined)
-                return { invalid: `期望 string 或 number，得到 ${describeType(value)}` };
+                return { invalid: mismatch('expectedChoice', value) };
             const options = field.allowCustom === true ? undefined : choiceOptions(field);
             if (!options)
                 return { value: text, dropped: [] };
@@ -339,23 +460,27 @@ function judgeField(field, value) {
         }
         case 'multiselect': {
             if (!Array.isArray(value))
-                return { invalid: `期望数组，得到 ${describeType(value)}` };
+                return { invalid: mismatch('expectedArray', value) };
             const options = field.allowCustom === true ? undefined : choiceOptions(field);
             const kept = [];
             const dropped = [];
+            const keep = (choice) => {
+                if (field.ordered !== true || !kept.includes(choice))
+                    kept.push(choice);
+            };
             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)}` });
+                    dropped.push({ at: `[${i}]`, reason: mismatch('expectedChoiceItem', item) });
                 }
                 else if (!options) {
-                    kept.push(text);
+                    keep(text);
                 }
                 else {
                     const hit = options.find(o => String(o.value) === text);
                     if (hit)
-                        kept.push(hit.value);
+                        keep(hit.value);
                     else
                         dropped.push({ at: `[${i}]`, reason: notAnOption(options) });
                 }
@@ -364,14 +489,14 @@ function judgeField(field, value) {
         }
         case 'list': {
             if (!Array.isArray(value))
-                return { invalid: `期望数组，得到 ${describeType(value)}` };
+                return { invalid: mismatch('expectedArray', 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)}` });
+                    dropped.push({ at: `[${i}]`, reason: mismatch('expectedStringItem', item) });
                 else
                     kept.push(text);
             }
@@ -379,16 +504,16 @@ function judgeField(field, value) {
         }
         case 'map': {
             if (!isRecord(value))
-                return { invalid: `期望对象（映射），得到 ${describeType(value)}` };
+                return { invalid: mismatch('expectedMap', 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)}` });
+                    dropped.push({ at: `.${k}`, reason: mismatch('expectedStringValue', v) });
                 // 危险键不进结果对象：写 `__proto__` 会改掉结果的原型
                 else if (isUnsafeConfigKey(k))
-                    dropped.push({ at: `.${k}`, reason: '保留键不可用' });
+                    dropped.push({ at: `.${k}`, reason: { code: 'reserved-key', text: t('reservedKey') } });
                 else
                     kept[k] = text;
             }
@@ -398,6 +523,45 @@ function judgeField(field, value) {
             return { value, dropped: [] };
     }
 }
+/**
+ * 拿换算后的取值调字段自己的 validate：合法给 undefined。validate 抛错、或返回的不是非空字符串与文字对象时，原因写
+ * 「校验时出错」（抛出的错里可能带着取值，不转述）
+ */
+function runValidate(field, value) {
+    if (field.validate === undefined)
+        return undefined;
+    let reason;
+    try {
+        reason = field.validate(value);
+    }
+    catch {
+        return { code: 'validate', text: t('validateError') };
+    }
+    if (reason === undefined)
+        return undefined;
+    if (isTextRef(reason))
+        return { code: 'validate', text: reason };
+    return {
+        code: 'validate',
+        text: typeof reason === 'string' && reason !== '' ? t('validateFailed', { reason }) : t('validateError'),
+    };
+}
+/**
+ * 填的是空串（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) === '';
+}
+/** 没配置：undefined 与 null（YAML 裸键）；required 字段另把空串算进来（见 isBlank），外来类型的 `''` 一律算 */
+function isUnset(field, value) {
+    if (value === undefined || value === null)
+        return true;
+    return field.required ? isBlank(field, value) : value === '' && !NEUTRAL_FIELD_TYPES.has(field.type);
+}
 /** 期望字符串的位置：字符串原样，有限数字转成字符串（YAML 里不加引号的 QQ 号、端口照常可用） */
 function asText(value) {
     if (typeof value === 'string')
@@ -423,7 +587,7 @@ function choiceOptions(field) {
     return options.length > 0 ? options : undefined;
 }
 function notAnOption(options) {
-    return `不是可选值（${options.map(o => JSON.stringify(o.value)).join('、')}）之一`;
+    return { code: 'not-option', text: t('notOption', { options: options.map(o => JSON.stringify(o.value)) }) };
 }
 function matchesPattern(pattern, text) {
     // 模式本身非法（作者的 schema bug）时跳过该检查——判定不得因 schema
@@ -435,6 +599,16 @@ function matchesPattern(pattern, text) {
         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);
 }
@@ -447,24 +621,32 @@ function describeType(value) {
         return String(value);
     return typeof value;
 }
-/** 顶层或分组内无法恢复的字段：parseConfig 把它转成 missingConfigError / configError 抛出，数组元素内只丢这一条元素 */
+/**
+ * 顶层或分组内无法恢复的字段：parseConfig 把它转成 missingConfigError / configError 抛出，数组元素内只丢这一条元素；
+ * `fatal` 的（没解析的密钥引用）在数组元素里也让整次解析失败
+ */
 class UnrecoverableField extends Error {
     path;
     reason;
     missing;
-    constructor(path, reason, missing) {
-        super(`${path} ${reason}`);
+    fatal;
+    constructor(path, reason, missing, fatal = false) {
+        super(`${path} ${reason.source}`);
         this.path = path;
         this.reason = reason;
         this.missing = missing;
+        this.fatal = fatal;
     }
 }
-/** 只在祖先值显式无效时检查；缺省的容器仍按字段原有的缺省规则解析。 */
-function hasStrictField(schema) {
+/**
+ * 只在祖先值显式无效时检查；缺省的容器仍按字段原有的缺省规则解析。`top` 表示查的是整份配置：顶层带 session 的字段
+ * parseConfig 不解析，不算
+ */
+function hasStrictField(schema, top = false) {
     if (!isRecord(schema))
         return false;
     return Object.values(schema).some(entry => {
-        if (!isRecord(entry))
+        if (!isRecord(entry) || (top && isSessionField(entry)))
             return false;
         if (entry.onInvalid === 'error')
             return true;
@@ -482,6 +664,9 @@ function parseEntries(schema, source, prefix, warn) {
     for (const [key, entry] of Object.entries(entries)) {
         if (!isRecord(entry) || isUnsafeConfigKey(key))
             continue;
+        // 顶层（prefix 为空）带 session 的字段不交出：插件经会话设置的读取器读它。键仍在 schema 里，配置里有它也不告警
+        if (prefix === '' && isSessionField(entry))
+            continue;
         const path = prefix + key;
         // 只认自有属性：`toString` 这类键不能从原型上读到值
         const value = Object.hasOwn(source, key) ? source[key] : undefined;
@@ -507,22 +692,22 @@ function parseGroup(fields, value, path, warn) {
         source = value;
     else if (value !== undefined && value !== null) {
         if (hasStrictField(fields))
-            throw new UnrecoverableField(path, '期望对象（分组）', false);
+            throw new UnrecoverableField(path, t('notGroup'), 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 || (value === '' && (field.required || !neutral))) {
+    if (isUnset(field, value)) {
         if (field.default !== undefined)
             return cloneConfigValue(field.default);
         if (field.required)
-            throw new UnrecoverableField(path, '必填字段缺失', true);
+            throw new UnrecoverableField(path, t('missing'), true);
         return undefined;
     }
-    if (!neutral)
-        return cloneConfigValue(value);
+    if (field.secret === true && isSecretRef(value)) {
+        throw new UnrecoverableField(path, t('secretUnresolved', { key: value.$secret }), false, true);
+    }
     const verdict = judgeField(field, value);
     if ('invalid' in verdict)
         return fallBack(field, path, verdict.invalid, warn);
@@ -533,8 +718,11 @@ function parseField(field, value, path, warn) {
         throw new UnrecoverableField(memberPath, safeInvalidReason(first.reason), false);
     }
     for (const d of verdict.dropped)
-        warn(`配置项 ${path}${d.at} ${d.reason}，已忽略`);
-    return verdict.value;
+        warn(`配置项 ${path}${d.at} ${d.reason.text.source}，已忽略`);
+    const invalid = runValidate(field, verdict.value);
+    if (invalid)
+        return fallBack(field, path, invalid, warn);
+    return cloneConfigValue(verdict.value);
 }
 function parseArray(entry, value, path, warn) {
     let list = value;
@@ -543,8 +731,8 @@ function parseArray(entry, value, path, warn) {
     }
     else if (!Array.isArray(value)) {
         if (hasStrictField(entry.items))
-            throw new UnrecoverableField(path, '期望数组', false);
-        list = fallBack(entry, path, `期望数组，得到 ${describeType(value)}`, warn);
+            throw new UnrecoverableField(path, t('notArray'), false);
+        list = fallBack(entry, path, mismatch('expectedArray', value), warn);
     }
     // 默认值同样逐元素解析：元素字段的默认值要补齐；default 本身不是数组（畸形 schema）按未配置处理
     if (!Array.isArray(list))
@@ -555,7 +743,7 @@ function parseArray(entry, value, path, warn) {
         const at = `${path}[${i}]`;
         if (!isRecord(item)) {
             if (entry.onInvalid === 'error')
-                throw new UnrecoverableField(at, '期望对象元素', false);
+                throw new UnrecoverableField(at, t('notItem'), false);
             warn(`配置项 ${at} 已忽略：期望对象元素，得到 ${describeType(item)}`);
             continue;
         }
@@ -567,9 +755,9 @@ function parseArray(entry, value, path, warn) {
         catch (err) {
             if (!(err instanceof UnrecoverableField))
                 throw err;
-            if (entry.onInvalid === 'error')
+            if (entry.onInvalid === 'error' || err.fatal)
                 throw err;
-            warn(`配置项 ${at} 已忽略：${err.path.slice(at.length + 1)} ${err.reason}`);
+            warn(`配置项 ${at} 已忽略：${err.path.slice(at.length + 1)} ${err.reason.source}`);
             continue;
         }
         for (const message of pending)
@@ -582,21 +770,24 @@ 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)}`);
+        warn(`配置项 ${path} ${reason.text.source}，改用默认值 ${describeDefault(entry.default)}`);
         return cloneConfigValue(entry.default);
     }
     if (entry.required)
-        throw new UnrecoverableField(path, reason, false);
-    warn(`配置项 ${path} ${reason}，已忽略`);
+        throw new UnrecoverableField(path, reason.text, false);
+    warn(`配置项 ${path} ${reason.text.source}，已忽略`);
     return undefined;
 }
-/** 错误可说明类型与约束，但不列出用户值、静态选项值或正则文本。 */
-function safeInvalidReason(reason) {
-    if (reason.startsWith('不是可选值'))
-        return '不是可选值';
-    if (reason.startsWith('不匹配模式'))
-        return '不匹配模式';
-    return reason.replace(/得到 (?:NaN|-?Infinity)/g, '得到 number');
+/**
+ * 严格错误的原因：可说明类型与约束，但不列出静态选项值与正则文本，按 code 换成不带它们的那句。类型不符只写类型名
+ * （非有限数写成 NaN、Infinity，它们不会是密钥），本来就不带用户值
+ */
+function safeInvalidReason({ code, text }) {
+    if (code === 'not-option')
+        return t('notOptionHidden');
+    if (code === 'pattern')
+        return t('patternHidden');
+    return text;
 }
 function describeDefault(value) {
     try {
@@ -606,7 +797,7 @@ function describeDefault(value) {
         return String(value);
     }
 }
-// 与 packages/core/src/infrastructure/config-values.ts 同一规则（本包零运行时依赖，不能 import core）。
+// 与 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']);
 /** 配置层无合法含义、落到原型链的键（`__proto__` / `constructor` / `prototype`）；宿主的配置文档按它拦 */