@aalis/plugin-webui-server 0.13.0 → 0.14.1

package/dist/routes/plugins.js

@@ -1,13 +1,13 @@
 import { isDeepStrictEqual } from 'node:util';
 import { isConfigSaveRefused } from '@aalis/api-host-config';
 import { parseInstanceId } from '@aalis/core';
-import { CORE_CONFIG_SCHEMA, cloneConfigObject, defaultsFrom, removeExtraFields, validateConfig, } from '@aalis/schema-config';
+import { CORE_CONFIG_SCHEMA, deepMergeDefaults, defaultsFrom, parseConfig, removeExtraFields, validateConfig, } from '@aalis/schema-config';
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
 /**
  * 落盘被拒后运行态怎样与文件对齐：插件配置与新建的实例随配置文件热重载（文件里没有配置段的后缀实例会被卸载）；
- * 启停、实例删除与服务偏好只在重启时按文件登记
+ * 启停与服务偏好只在重启时按文件登记
  */
 const RECONCILE = {
     reload: '修好配置文件后会按文件内容重载',
@@ -17,28 +17,59 @@ const RECONCILE = {
  * 管理动作改完运行态之后落盘；失败时回 `applied: true` 并返回 false：改动已在运行态生效、只是没写进文件，
  * 调用方别当成「没改成」去重试。宿主拒写（配置文件有尚未生效的外部修改）回 409，之后以文件为准对账；
  * 其它失败（权限、磁盘写满等）回 500，文件没变也不会触发重载，改动留在文档里，下一次成功保存时一并写入。
+ * `outcome` 是动作之后插件没有落在预期状态的说明（如激活失败转 error、仍在激活、保持禁用）：落盘也失败时放在回执开头，
+ * 两件事一并说明。
  */
-export async function saveAfterApply(doc, res, reconcile) {
+export async function saveAfterApply(doc, res, reconcile, outcome) {
     try {
         await doc.save();
         return true;
     }
     catch (err) {
+        const lead = outcome ? `${outcome}；` : '';
         if (isConfigSaveRefused(err)) {
             res.status(409).json({
-                error: `已在运行态生效，但未写入配置文件（${errorMessage(err)}）；${RECONCILE[reconcile]}`,
+                error: `${lead}已在运行态生效，但未写入配置文件（${errorMessage(err)}）；${RECONCILE[reconcile]}`,
                 applied: true,
             });
         }
         else {
             res.status(500).json({
-                error: `已在运行态生效，但写入配置文件失败（${errorMessage(err)}）；改动保留在文档里，下次保存成功时一并写入`,
+                error: `${lead}已在运行态生效，但写入配置文件失败（${errorMessage(err)}）；改动保留在文档里，下次保存成功时一并写入`,
                 applied: true,
             });
         }
         return false;
     }
 }
+/**
+ * 管理动作受理后等重算落定，再读实例状态写回执：动作撞上在飞的重算时只排队、立即返回，立即读到的还是 pending，
+ * 之后的激活失败就漏报了。idle 不等转入后台的慢激活：重算对单个激活至多等到慢激活阈值。
+ */
+async function settledEntry(pm, instanceId) {
+    await pm.idle();
+    return pm.getPlugin(instanceId);
+}
+/** 落定后既没激活也没失败的说明：慢激活转入后台仍在进行，或在等 required 依赖满足；其余状态由各路由自己说明 */
+function notYetActive(state) {
+    if (state === 'activating')
+        return '仍在激活（超过慢激活阈值，已转入后台），结果以插件列表为准';
+    if (state === 'pending')
+        return '尚未激活，正在等待 required 依赖满足';
+    return undefined;
+}
+/**
+ * 管理动作返回 false 时的回执。条目还在注册表里，说明是停机中或正在卸载拒绝了这次操作，回 409；
+ * 只有条目确实不存在才回 404。两种情况都没有写配置文档。
+ */
+function refuse(pm, res, instanceId, action) {
+    if (pm.getPlugin(instanceId)) {
+        res.status(409).json({ error: `插件 ${instanceId} 当前不接受${action}（停机中或正在卸载），配置未更改` });
+    }
+    else {
+        res.status(404).json({ error: `插件 ${instanceId} 不存在` });
+    }
+}
 /** 注册插件管理 + 全局配置相关 REST 路由 */
 export function registerPluginRoutes(expressApp, caps, identify, gate, getAction) {
     const getApp = () => caps.app.current;
@@ -50,6 +81,41 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             res.status(503).json({ error: '宿主未提供配置文档（host-config），无法读写配置' });
         return doc;
     };
+    /**
+     * 把提交的插件配置合进基线（改配置时是配置文档里的原配置，建实例时是空对象），改配置与建实例同一套：
+     * 提交里的顶层键整键替换基线的同名键（分组、数组整块替换），没提交的保持原值；值为 null 的顶层键视为删除，
+     * 有默认值的回到默认值、没有的不写（前端清空数字、llm-ref 选「继承默认」时发 null，JSON 丢掉的键只是没提交）。
+     * 之后按 schema 默认值深合并补齐缺的键，只写了半块的分组也补齐其余默认子键。基线的键在前、缺的默认键追加到末尾，
+     * 写回时保留配置文件里原有的键序。
+     * 宿主裁剪且有 schema 时再裁掉未知键并 warn（与宿主的配置同步同一政策，host-config 的 trimUnknownFields）：
+     * 本次提交里的记 ignored，基线里原有、本次没提交的记 removed，由调用方回给请求方，不静默吞掉却回复成功
+     */
+    const mergeSubmittedConfig = (doc, instanceId, schema, base, submitted) => {
+        const defaults = defaultsFrom(schema);
+        const replaced = { ...base, ...submitted };
+        for (const [key, value] of Object.entries(submitted)) {
+            if (value !== null)
+                continue;
+            if (Object.hasOwn(defaults, key))
+                replaced[key] = defaults[key];
+            else
+                delete replaced[key];
+        }
+        let merged = deepMergeDefaults(defaults, replaced);
+        const ignored = [];
+        const removed = [];
+        if (doc.trimUnknownFields !== false && schema && Object.keys(schema).length > 0) {
+            const shape = schema;
+            for (const [key, value] of Object.entries(merged)) {
+                removeExtraFields({ [key]: value }, shape, Object.hasOwn(submitted, key) ? ignored : removed);
+            }
+            merged = removeExtraFields(merged, shape);
+            if (ignored.length + removed.length > 0) {
+                caps.logger?.warn(`配置同步：${instanceId} 裁掉 schema 外字段 [${[...ignored, ...removed].join(', ')}]`);
+            }
+        }
+        return { merged, ignored, removed };
+    };
     // 获取插件列表及状态
     expressApp.get('/api/plugins', gate(), (_req, res) => {
         const app = getApp();
@@ -88,9 +154,6 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         }
         const plugins = pm.getStatus().map(p => {
             const entry = pm.getPlugin(p.instanceId);
-            const schema = entry?.definition?.configSchema;
-            // 列表给概览用：schema.secret 字段换成固定掩码。编辑器走 GET /api/plugins/:name/config，那条不脱敏。
-            const config = maskSecretFields(cloneConfigObject((entry?.config ?? {})), schema);
             return {
                 name: p.name,
                 instanceId: p.instanceId,
@@ -108,8 +171,9 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
                 reusable: p.reusable ?? false,
                 // extends / config / configSchema / defaultConfig 非内核状态摘要字段
                 // （getStatus 只含内核事实）：从 entry.config / entry.definition 补齐给前端。
+                // 配置按原值给出：前端据它建编辑草稿、整份保存，secret 字段只在显示时遮蔽
                 extends: entry?.definition?.extends,
-                config,
+                config: entry?.config ?? {},
                 configSchema: entry?.definition?.configSchema,
                 defaultConfig: defaultsFrom(entry?.definition?.configSchema),
                 error: p.error,
@@ -204,30 +268,31 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         // 所以不能按键报错：其余键一律不应用，但把真有改动的点名回给调用方——不静默吞掉却回复「已保存」。
         const allowed = Object.keys(CORE_CONFIG_SCHEMA);
         const current = doc.getAll();
+        const defaultOf = (k) => CORE_CONFIG_SCHEMA[k]?.default;
         // 文档里没写的核心键按 schema 默认值比较：内置前端把默认值回填进草稿后整份回传，不能据此判成改动（否则只改
         // 名字也会把默认值写进文件并触发重启）
-        const currentOf = (k) => current[k] ?? CORE_CONFIG_SCHEMA[k]?.default;
+        const currentOf = (k) => current[k] ?? defaultOf(k);
         const differs = (k) => !isDeepStrictEqual(updates[k], currentOf(k));
+        // 核心键提交 null 表示清空（前端清空数字框时发 null）：回到默认值，并从文档里删掉这个键，不把默认值写死进文件
+        const submittedOf = (k) => (updates[k] === null ? defaultOf(k) : updates[k]);
         const ignored = Object.keys(updates).filter(k => k !== '_schema' && !allowed.includes(k) && differs(k));
-        const changed = allowed.filter(k => k in updates && differs(k));
-        // 与插件配置路径同一把尺子：类型不符的值（如 name 传数字）不落盘。select 的取值范围 validateConfig
-        // 刻意不管（它看不见宿主属性 allowCustom），核心字段没有 allowCustom，在这里按 options 补校验。
-        const picked = Object.fromEntries(changed.map(k => [k, updates[k]]));
+        const changed = allowed.filter(k => k in updates && !isDeepStrictEqual(submittedOf(k), currentOf(k)));
+        // 与插件配置路径同一把尺子：类型不符、越界或不在选项里的值（如 logLevel 传 nope）不落盘。
+        const picked = Object.fromEntries(changed.map(k => [k, submittedOf(k)]));
         const invalid = validateConfig(CORE_CONFIG_SCHEMA, picked).map(i => `${i.path}: ${i.message}`);
-        for (const k of changed) {
-            const field = CORE_CONFIG_SCHEMA[k];
-            if (field.type === 'select' && field.options && !field.options.some(o => o.value === updates[k])) {
-                invalid.push(`${k}: 取值不在可选范围`);
-            }
-        }
         if (invalid.length > 0) {
             res.status(400).json({ error: invalid.join('; ') });
             return;
         }
+        // 写进文档的是按词汇换算后的值（加了引号的数字转成数字、写成数字的名称转成字符串）：runtime 启动时
+        // 直接读这几个键，不经 parseConfig
+        const values = parseConfig(CORE_CONFIG_SCHEMA, picked);
         const previous = Object.fromEntries(changed.map(k => [k, current[k]]));
+        // 提交 null 的键置为 undefined，写文件时省略
         for (const key of changed)
-            doc.set(key, updates[key]);
-        // logLevel 与 slowThresholdMs 只在启动时读取，改了才重启；name 由 /api/status 每次实时读文档，保存即生效
+            doc.set(key, updates[key] === null ? undefined : values[key]);
+        // logLevel 与 slowThresholdMs 只在启动时读取，改了才重启；name 由 /api/status 每次实时读文档（appName），保存即生效。
+        // 装有人设时聊天显示人设名，应用名称只在仪表盘上看得到
         const restartNeeded = changed.some(k => k === 'logLevel' || k === 'slowThresholdMs');
         const note = ignored.length > 0 ? `（已忽略不可修改的字段: ${ignored.join(', ')}）` : '';
         try {
@@ -261,8 +326,7 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         }
         res.json({ ok: true, message: `全局配置已更新，正在重启应用以生效…${note}`, restart: true, ignored });
     });
-    // 获取单个插件的原始配置（未脱敏，给编辑器回写用）。
-    // 列表 GET /api/plugins 已把 schema.secret 换成固定掩码；本接口必须是原文，否则保存会把掩码写回。
+    // 获取单个插件在配置文档里的配置
     expressApp.get('/api/plugins/:name/config', gate(), (req, res) => {
         const pluginName = req.params.name;
         const doc = docOr503(res);
@@ -280,7 +344,7 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
     expressApp.put('/api/plugins/:name/config', gate(), async (req, res) => {
         const pluginName = req.params.name;
         const newConfig = req.body?.config;
-        if (!newConfig || typeof newConfig !== 'object') {
+        if (!newConfig || typeof newConfig !== 'object' || Array.isArray(newConfig)) {
             res.status(400).json({ error: 'config 字段必须是对象' });
             return;
         }
@@ -292,46 +356,22 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         const doc = docOr503(res);
         if (!doc)
             return;
-        // 补默认值再交给 updateConfig：后者是**整体替换**语义（core 的 orchestration/plugin.ts 里
-        // entry.config = newConfig 直接顶掉）。不补的话，PUT 一个部分对象就会把未列出的
-        // 字段从内存态和 yaml 里一起抹掉。默认值从 configSchema 派生（唯一声明来源）。
+        // 合进原配置再交给 updateConfig：后者是**整体替换**语义（core 的 orchestration/plugin.ts 里
+        // entry.config = newConfig 直接顶掉）。基线取配置文档里的原配置而非裸默认值：defaultsFrom 只收录声明了
+        // default 的键，而 apiKey / accessToken 这类 secret 多数**没有** default（deepseek、embedding-openai、
+        // llm-openai、serper、onebot 皆是），以裸默认值打底时请求里没带 apiKey，整体替换后用户的密钥就从内存态与
+        // yaml 一起消失。叠上原配置后语义才是真正的部分更新：没提交的字段保持原样，要清空得显式提交。
         const entry = pm.getPlugin(pluginName);
         const schema = entry?.definition?.configSchema;
-        const defaults = defaultsFrom(schema);
-        // 基线取「默认值叠已存值」而非裸默认值：defaultsFrom 只收录声明了 default 的键，
-        // 而 apiKey / accessToken 这类 secret 多数**没有** default（deepseek、embedding-openai、
-        // llm-openai、serper、onebot 皆是）。用裸 defaults 打底时，请求里没带 apiKey 就等于
-        // merged 里根本没有这个键，整体替换后用户的密钥从内存态与 yaml 一起消失。
-        // 叠上已存值后语义才是真正的部分更新：没提交的字段保持原样，要清空得显式传空串。
         let docConfig;
         let stored;
         let merged;
-        const ignored = [];
-        const removed = [];
+        let ignored;
+        let removed;
         try {
             docConfig = doc.getPluginConfig(pluginName);
-            // 先铺文档里的原配置、缺的默认键追加到末尾：写回时保留配置文件里原有的键序
-            stored = { ...docConfig };
-            for (const [key, value] of Object.entries(defaults)) {
-                if (!Object.hasOwn(stored, key))
-                    stored[key] = value;
-            }
-            const submitted = newConfig;
-            merged = { ...stored, ...submitted };
-            // 与宿主的配置同步同一政策（host-config 的 trimUnknownFields）：宿主裁剪且有 schema 时裁掉未知键并 warn，
-            // 避免 WebUI 把手滑字段写进 stored，而 YAML watch 路径却会裁掉；宿主保留未知字段时这里也不裁。
-            // 被裁的字段按来源回给调用方，不静默吞掉却回复「已更新」：本次提交里的记 ignored（与 PUT /api/config
-            // 同一口径）；文档里原有、本次没提交的不是用户这次写的，随整份写回从配置文件删掉，记 removed
-            if (doc.trimUnknownFields !== false && schema && Object.keys(schema).length > 0) {
-                const shape = schema;
-                for (const [key, value] of Object.entries(merged)) {
-                    removeExtraFields({ [key]: value }, shape, Object.hasOwn(submitted, key) ? ignored : removed);
-                }
-                merged = removeExtraFields(merged, shape);
-                if (ignored.length + removed.length > 0) {
-                    caps.logger?.warn(`配置同步：${pluginName} 裁掉 schema 外字段 [${[...ignored, ...removed].join(', ')}]`);
-                }
-            }
+            stored = deepMergeDefaults(defaultsFrom(schema), docConfig);
+            ({ merged, ignored, removed } = mergeSubmittedConfig(doc, pluginName, schema, docConfig, newConfig));
         }
         catch (err) {
             res.status(400).json({ error: errorMessage(err) });
@@ -343,10 +383,23 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         // 存量问题放行——否则带着历史脏值（或 schema 表达不了的多态字段，如 mcp-client
         // 的 args 数组形态）的插件会在 WebUI 永久存不了任何字段；启动侧 config-sync
         // 对它们已有告警。missing（没配全）也放行：半成品配置是启用插件配到一半的
-        // 正常中间态。禁用插件的 PUT 走下方 updateConfig 失败分支，在那里区分
-        // 「已禁用」（409，提示先启用）与「真不存在」（404）。
-        const preExisting = new Set(validateConfig(schema, stored).map(i => `${i.path}|${i.message}`));
-        const issues = validateConfig(schema, merged).filter(i => i.kind === 'invalid' && !preExisting.has(`${i.path}|${i.message}`));
+        // 正常中间态。
+        // 存量按「去掉下标的路径 + 原因」计数，新配置里同类问题的条数超出存量才算新增：list / multiselect /
+        // 数组删掉前面的元素后，存量坏元素的下标会前移，按原路径比会把它误判成新增
+        const issueKey = (i) => `${i.path.replace(/\[\d+\]/g, '[]')}|${i.message}`;
+        const preExisting = new Map();
+        for (const i of validateConfig(schema, stored)) {
+            const key = issueKey(i);
+            preExisting.set(key, (preExisting.get(key) ?? 0) + 1);
+        }
+        const issues = validateConfig(schema, merged).filter(i => {
+            if (i.kind !== 'invalid')
+                return false;
+            const key = issueKey(i);
+            const left = preExisting.get(key) ?? 0;
+            preExisting.set(key, left - 1);
+            return left <= 0;
+        });
         if (issues.length > 0) {
             res.status(400).json({
                 error: `配置校验未通过：${issues.map(i => `${i.path}: ${i.message}`).join('；')}`,
@@ -372,27 +425,30 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             return;
         }
         if (success) {
-            // 按新配置重新激活失败、转为 error：照样写入配置（原样再存即重试激活），但按实际状态回报
-            const after = pm.getPlugin(pluginName);
-            const failure = after?.state === 'error' ? (after.error ?? '详见日志') : undefined;
             // 管理动作只改运行态；跨重启保留要本路由写文档并落盘
             doc.setPluginConfig(pluginName, merged);
-            if (!(await saveAfterApply(doc, res, 'reload')))
+            // 按新配置重新激活失败、转为 error：照样写入配置（原样再存即重试激活），但按实际状态回报。
+            // 禁用态只换上新配置、保持禁用，启用时按它激活
+            const after = await settledEntry(pm, pluginName);
+            const failure = after?.state === 'error'
+                ? `插件 ${pluginName} 按新配置重新激活失败，已转为 error 态（${after.error ?? '详见日志'}）`
+                : undefined;
+            const aside = after?.state === 'disabled' ? '插件已禁用，启用时按新配置激活' : notYetActive(after?.state);
+            if (!(await saveAfterApply(doc, res, 'reload', failure ?? aside)))
                 return;
             if (failure !== undefined) {
-                res.status(500).json({
-                    error: `插件 ${pluginName} 按新配置重新激活失败，已转为 error 态（${failure}）；配置已写入配置文件${note}`,
-                });
+                res.status(500).json({ error: `${failure}；配置已写入配置文件${note}` });
                 return;
             }
-            res.json({ ok: true, message: `插件 ${pluginName} 配置已更新${note}`, ignored, removed });
-        }
-        else if (pm.getPlugin(pluginName)?.state === 'disabled') {
-            // 插件被禁用时这里也会走到，但「不存在」会把用户引向错误方向——区分「禁用」与「真不存在」并给出下一步。
-            res.status(409).json({ error: `插件 ${pluginName} 已禁用，配置未写入——先启用插件再修改配置` });
+            res.json({
+                ok: true,
+                message: `插件 ${pluginName} 配置已更新${note}${aside ? `；${aside}` : ''}`,
+                ignored,
+                removed,
+            });
         }
         else {
-            res.status(404).json({ error: `插件 ${pluginName} 不存在` });
+            refuse(pm, res, pluginName, '配置更新');
         }
     });
     // 启用插件
@@ -415,22 +471,23 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             return;
         }
         if (success) {
-            // 激活失败、转为 error：照样记为启用（重启时再激活），但按实际状态回报
-            const after = pm.getPlugin(pluginName);
-            const failure = after?.state === 'error' ? (after.error ?? '详见日志') : undefined;
             doc.setPluginEnabled(pluginName, true);
-            if (!(await saveAfterApply(doc, res, 'restart')))
+            // 激活失败、转为 error：照样记为启用（重启时再激活），但按实际状态回报
+            const after = await settledEntry(pm, pluginName);
+            const failure = after?.state === 'error'
+                ? `插件 ${pluginName} 激活失败，已转为 error 态（${after.error ?? '详见日志'}）`
+                : undefined;
+            const aside = notYetActive(after?.state);
+            if (!(await saveAfterApply(doc, res, 'restart', failure ?? aside)))
                 return;
             if (failure !== undefined) {
-                res
-                    .status(500)
-                    .json({ error: `插件 ${pluginName} 激活失败，已转为 error 态（${failure}）；配置文件已记为启用` });
+                res.status(500).json({ error: `${failure}；配置文件已记为启用` });
                 return;
             }
-            res.json({ ok: true, message: `插件 ${pluginName} 已启用` });
+            res.json({ ok: true, message: `插件 ${pluginName} 已启用${aside ? `；${aside}` : ''}` });
         }
         else {
-            res.status(404).json({ error: `插件 ${pluginName} 不存在` });
+            refuse(pm, res, pluginName, '启用');
         }
     });
     // 禁用插件
@@ -454,20 +511,20 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         }
         if (success) {
             // 仍在初始化、不响应 abort 的插件，宽限到期转 error 而非 disabled：照样记为禁用（重启时不再激活），但按实际状态回报
-            const stuck = pm.getPlugin(pluginName)?.state === 'error';
+            const stuck = pm.getPlugin(pluginName)?.state === 'error'
+                ? `插件 ${pluginName} 未在宽限内停止，已转为 error 态，详见日志`
+                : undefined;
             doc.setPluginEnabled(pluginName, false);
-            if (!(await saveAfterApply(doc, res, 'restart')))
+            if (!(await saveAfterApply(doc, res, 'restart', stuck)))
                 return;
-            if (stuck) {
-                res
-                    .status(500)
-                    .json({ error: `插件 ${pluginName} 未在宽限内停止，已转为 error 态，详见日志；配置文件已记为禁用` });
+            if (stuck !== undefined) {
+                res.status(500).json({ error: `${stuck}；配置文件已记为禁用` });
                 return;
             }
             res.json({ ok: true, message: `插件 ${pluginName} 已禁用` });
         }
         else {
-            res.status(404).json({ error: `插件 ${pluginName} 不在注册表或已处于终态，无法禁用` });
+            refuse(pm, res, pluginName, '禁用');
         }
     });
     // 经宿主 plugin-source 重新扫描并加载新插件
@@ -499,6 +556,10 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             res.status(400).json({ error: 'suffix 只能包含字母、数字、下划线和连字符' });
             return;
         }
+        if (typeof config !== 'object' || Array.isArray(config)) {
+            res.status(400).json({ error: 'config 字段必须是对象' });
+            return;
+        }
         const pm = getPluginMgr();
         if (!pm) {
             res.status(500).json({ error: '插件管理服务不可用' });
@@ -508,7 +569,7 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         if (!doc)
             return;
         // 实例创建编排（配置文件编排属管理面,内核只出 register 机制）：
-        // 查同名 module → reusable/查重校验 → 合并默认配置写入 → register 激活。
+        // 查同名 module → reusable/查重校验 → 合并默认配置、裁剪与校验 → 写入 → register 激活。
         const sourceModule = pm
             .getStatus()
             .map(p => pm.getPlugin(p.instanceId)?.definition)
@@ -526,7 +587,19 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             res.status(400).json({ error: `无法创建实例："${instanceId}" 已存在` });
             return;
         }
-        const mergedConfig = { ...defaultsFrom(sourceModule.configSchema), ...config };
+        // 与改配置同一套合并与裁剪，基线是空对象。校验不分存量：新实例没有历史配置，类型不符的值一律拒绝，
+        // missing 照样放行（半成品配置是配到一半的正常中间态）
+        const schema = sourceModule.configSchema;
+        const { merged: mergedConfig, ignored } = mergeSubmittedConfig(doc, instanceId, schema, {}, config);
+        const issues = validateConfig(schema, mergedConfig).filter(i => i.kind === 'invalid');
+        if (issues.length > 0) {
+            res.status(400).json({
+                error: `配置校验未通过：${issues.map(i => `${i.path}: ${i.message}`).join('；')}`,
+                issues,
+            });
+            return;
+        }
+        const note = ignored.length > 0 ? `（已忽略未声明的配置字段: ${ignored.join(', ')}）` : '';
         let registered;
         try {
             doc.setPluginConfig(instanceId, mergedConfig);
@@ -545,9 +618,21 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             res.status(409).json({ error: `实例 ${instanceId} 未登记（停机中或被拒，见日志），配置未写入` });
             return;
         }
-        if (!(await saveAfterApply(doc, res, 'reload')))
+        // 激活失败、转为 error：实例与配置照样保留并落盘（改配置保存即重试激活），但按实际状态回报
+        const after = await settledEntry(pm, instanceId);
+        const failure = after?.state === 'error'
+            ? `已创建实例 ${instanceId}，但激活失败，已转为 error 态（${after.error ?? '详见日志'}）`
+            : undefined;
+        const aside = after?.state === 'disabled'
+            ? '配置文件的 disabledPlugins 里有它，已按禁用态登记，启用后激活'
+            : notYetActive(after?.state);
+        if (!(await saveAfterApply(doc, res, 'reload', failure ?? aside)))
+            return;
+        if (failure !== undefined) {
+            res.status(500).json({ error: `${failure}；配置已写入配置文件${note}` });
             return;
-        res.json({ ok: true, instanceId, message: `已创建实例 ${instanceId}` });
+        }
+        res.json({ ok: true, instanceId, message: `已创建实例 ${instanceId}${note}${aside ? `；${aside}` : ''}`, ignored });
     });
     // 删除插件多实例
     expressApp.delete('/api/plugins/:instanceId/instance', gate(), async (req, res) => {
@@ -560,23 +645,40 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         const doc = docOr503(res);
         if (!doc)
             return;
-        // 实例删除编排：主实例保护 → unload（内部含级联重算）→ 移除配置条目与禁用标记（同名重建时不再以禁用态登记）。
+        // 实例删除编排：主实例保护 → 移除配置条目与禁用标记（同名重建时不再以禁用态登记）并落盘 → unload（内部含级联重算）。
+        // 与其它管理路由「先生效后落盘」相反：后缀实例由配置段定义，热重载也按文件登记。先卸载后落盘时，卸载途中外部改动
+        // 触发的热重载会按仍带配置段的文件把实例重新登记，落盘随后删掉配置段，留下文件里没有的在跑实例
         const { suffix } = parseInstanceId(instanceId);
         if (!suffix || !pm.getPlugin(instanceId)) {
             res.status(400).json({ error: `无法删除（实例不存在或不允许删除主实例）` });
             return;
         }
+        const previous = Object.hasOwn(doc.getAll().plugins, instanceId) ? doc.getPluginConfig(instanceId) : undefined;
+        const wasDisabled = doc.isPluginDisabled(instanceId);
+        doc.removePluginConfig(instanceId);
+        doc.setPluginEnabled(instanceId, true);
         try {
-            await pm.unload(instanceId);
-            doc.removePluginConfig(instanceId);
-            doc.setPluginEnabled(instanceId, true);
+            await doc.save();
         }
         catch (err) {
-            res.status(400).json({ error: errorMessage(err) });
+            // 没写进文件就不卸载，并撤回文档里的改动，免得下一次任意保存把这次没删成的删除写进文件
+            if (previous)
+                doc.setPluginConfig(instanceId, previous);
+            doc.setPluginEnabled(instanceId, !wasDisabled);
+            res
+                .status(isConfigSaveRefused(err) ? 409 : 500)
+                .json({ error: `未删除实例 ${instanceId}：未写入配置文件（${errorMessage(err)}）` });
             return;
         }
-        if (!(await saveAfterApply(doc, res, 'restart')))
+        try {
+            await pm.unload(instanceId);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: `已从配置文件删除实例 ${instanceId}，但卸载失败（${errorMessage(err)}）；重启后不再登记`,
+            });
             return;
+        }
         res.json({ ok: true, message: `已删除实例 ${instanceId}` });
     });
     // 保存配置文档：与其它落盘路由同一口径，宿主拒写回 409、其它失败回 500。宿主不持久化时 save 不写盘，
@@ -594,41 +696,4 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         }
     });
 }
-/** 列表 payload 用的固定掩码。与 PUT 响应「不回显密钥」同一政策：概览面看不到明文。 */
-const SECRET_MASK = '••••••';
-/**
- * 把 schema.secret === true 的字段换成固定掩码。入参须已是拷贝——就地改，避免写穿现场 config。
- * 分组递归；数组元素若是对象则按 items 再走一遍。缺席的键不补掩码。
- */
-function maskSecretFields(config, schema) {
-    if (!schema)
-        return config;
-    for (const [key, raw] of Object.entries(schema)) {
-        if (!raw || typeof raw !== 'object')
-            continue;
-        const def = raw;
-        if (def.secret === true) {
-            if (Object.hasOwn(config, key))
-                config[key] = SECRET_MASK;
-            continue;
-        }
-        const nested = config[key];
-        if (def.fields &&
-            typeof def.fields === 'object' &&
-            nested &&
-            typeof nested === 'object' &&
-            !Array.isArray(nested)) {
-            maskSecretFields(nested, def.fields);
-            continue;
-        }
-        if (def.type === 'array' && Array.isArray(nested) && def.items && typeof def.items === 'object') {
-            for (const item of nested) {
-                if (item && typeof item === 'object' && !Array.isArray(item)) {
-                    maskSecretFields(item, def.items);
-                }
-            }
-        }
-    }
-    return config;
-}
 //# sourceMappingURL=plugins.js.map