@aalis/plugin-webui-server 0.14.0 → 0.15.0

package/dist/routes/plugins.js

@@ -1,17 +1,20 @@
 import { isDeepStrictEqual } from 'node:util';
+import { describeUnmet, unmetDependencies } from '@aalis/api-doctor';
 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, isSecretRef, mapSecretFields, parseConfig, removeExtraFields, validateConfig, } from '@aalis/schema-config';
+import { blockedStatus } from '../attention.js';
+import { route } from '../route.js';
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
 /**
- * 落盘被拒后运行态怎样与文件对齐：插件配置与新建的实例随配置文件热重载（文件里没有配置段的后缀实例会被卸载）；
- * 启停与服务偏好只在重启时按文件登记
+ * 落盘被拒后运行态怎样与文件对齐：插件配置、新建的实例与服务偏好随配置文件热重载（文件里没有配置段的后缀实例会被卸载）；
+ * 启停只在重启时按文件登记。被拒的可能是配置文件，也可能是密钥文件，拒写原因里点了名，这里不指具体哪个文件
  */
 const RECONCILE = {
-    reload: '修好配置文件后会按文件内容重载',
-    restart: '修好配置文件后，重启时以文件内容为准',
+    reload: '修好该文件后会按文件内容重载',
+    restart: '修好该文件后，重启时以文件内容为准',
 };
 /**
  * 管理动作改完运行态之后落盘；失败时回 `applied: true` 并返回 false：改动已在运行态生效、只是没写进文件，
@@ -26,22 +29,40 @@ export async function saveAfterApply(doc, res, reconcile, outcome) {
         return true;
     }
     catch (err) {
-        const lead = outcome ? `${outcome}；` : '';
-        if (isConfigSaveRefused(err)) {
-            res.status(409).json({
-                error: `${lead}已在运行态生效，但未写入配置文件（${errorMessage(err)}）；${RECONCILE[reconcile]}`,
-                applied: true,
-            });
-        }
-        else {
-            res.status(500).json({
-                error: `${lead}已在运行态生效，但写入配置文件失败（${errorMessage(err)}）；改动保留在文档里，下次保存成功时一并写入`,
-                applied: true,
-            });
-        }
+        reportSaveFailure(res, err, reconcile, outcome);
         return false;
     }
 }
+/** 落盘失败的回执，口径见 {@link saveAfterApply}；applyPluginConfig 带回的 saveError 同样用它 */
+function reportSaveFailure(res, err, reconcile, outcome) {
+    const lead = outcome ? `${outcome}；` : '';
+    if (isConfigSaveRefused(err)) {
+        res.status(409).json({
+            error: `${lead}已在运行态生效，但未写入配置文件（${errorMessage(err)}）；${RECONCILE[reconcile]}`,
+            applied: true,
+        });
+    }
+    else {
+        res.status(500).json({
+            error: `${lead}已在运行态生效，但写入配置文件失败（${errorMessage(err)}）；改动保留在文档里，下次保存成功时一并写入`,
+            applied: true,
+        });
+    }
+}
+/** 宿主配置里要重启才生效的键：runtime 与 core 只在启动时读它们。name 只是显示用的应用名称，保存即生效 */
+const RESTART_KEYS = ['logLevel', 'slowThresholdMs'];
+/** 文档里每个密钥键被引用的处数：表单据此提示「替换会同时改到另外 N 处」 */
+function countSecretRefs(value, into = {}) {
+    if (isSecretRef(value))
+        into[value.$secret] = (into[value.$secret] ?? 0) + 1;
+    else if (Array.isArray(value))
+        for (const item of value)
+            countSecretRefs(item, into);
+    else if (value !== null && typeof value === 'object')
+        for (const v of Object.values(value))
+            countSecretRefs(v, into);
+    return into;
+}
 /**
  * 管理动作受理后等重算落定，再读实例状态写回执：动作撞上在飞的重算时只排队、立即返回，立即读到的还是 pending，
  * 之后的激活失败就漏报了。idle 不等转入后台的慢激活：重算对单个激活至多等到慢激活阈值。
@@ -50,212 +71,211 @@ async function settledEntry(pm, instanceId) {
     await pm.idle();
     return pm.getPlugin(instanceId);
 }
-/** 落定后既没激活也没失败的说明：慢激活转入后台仍在进行，或在等 required 依赖满足；其余状态由各路由自己说明 */
-function notYetActive(state) {
+/**
+ * 落定后既没激活也没失败的说明：慢激活转入后台仍在进行，或 required 依赖没满足（缺什么、在等谁，按 api-doctor 的共享判据
+ * 沿链追到根，与插件列表同一说法），不缺服务时在等自己的旧实例停下（同插件列表，说法同依赖链的 lingering 根）；依赖都在、
+ * 只是提供者正在关停换代时没有可说的；其余状态由各路由自己说明
+ */
+function notYetActive(pm, services, instanceId, state) {
     if (state === 'activating')
         return '仍在激活（超过慢激活阈值，已转入后台），结果以插件列表为准';
-    if (state === 'pending')
-        return '尚未激活，正在等待 required 依赖满足';
-    return undefined;
+    if (state !== 'pending')
+        return undefined;
+    const status = pm.getStatus();
+    const unmet = unmetDependencies(status, services.names()).get(instanceId);
+    const lingering = !unmet?.lacking.length && status.find(entry => entry.instanceId === instanceId)?.lingering;
+    const why = lingering ? `等待 ${instanceId} 的旧实例停下` : unmet && describeUnmet(unmet);
+    return why ? `尚未激活：${why}` : '尚未激活，结果以插件列表为准';
+}
+/**
+ * 管理动作返回 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;
-    const getPluginMgr = () => caps.plugins.current;
+export function registerPluginRoutes(expressApp, caps, gate) {
     /** 配置文档由宿主提供；没有时读写文档的路由一律 503，与扫描、市场路由的缺席口径一致 */
     const docOr503 = (res) => {
-        const doc = caps.hostConfig.current;
+        const doc = caps.hostConfig.present ? caps.hostConfig.use : undefined;
         if (!doc)
             res.status(503).json({ error: '宿主未提供配置文档（host-config），无法读写配置' });
         return doc;
     };
+    /** 提供这个界面的插件经界面停掉就回不来了：拒绝停用它 */
+    const refuseSelf = (res, name) => {
+        if (name !== caps.self)
+            return false;
+        res.status(409).json({ error: `插件 ${name} 提供这个界面，不能从界面停用` });
+        return true;
+    };
+    /**
+     * 把提交的插件配置合进基线（改配置时是配置文档里的原配置，建实例时是空对象），改配置与建实例同一套：
+     * 提交里的顶层键整键替换基线的同名键（分组、数组整块替换），没提交的保持原值；值为 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();
-        const pm = getPluginMgr();
+    route(expressApp, 'GET /api/plugins', gate(), (_req, res) => {
+        const app = caps.app.present ? caps.app.use : undefined;
+        const pm = caps.plugins.present ? caps.plugins.use : undefined;
         if (!app || !pm) {
-            res.json({ plugins: [] });
+            res.json({ plugins: [], secretRefCounts: {} });
             return;
         }
-        // 反向索引：instanceId -> tools / commands（名字列表 + 聚合敏感能力）。
-        // 生产登记的 pluginName 就是 contextId（= instanceId）；按 definition.name 索引
-        // 会让 name:suffix 误挂主实例的工具。能力披露用聚合 capability。
+        // 反向索引：instanceId -> tools / commands。生产登记的 pluginName 就是 contextId（= instanceId）；
+        // 按 definition.name 索引会让 name:suffix 误挂主实例的工具
         const toolsByPlugin = new Map();
-        const capsByPlugin = new Map();
-        const addCaps = (plugin, visibility) => {
-            if (visibility !== 'restricted')
-                return;
-            const set = capsByPlugin.get(plugin) ?? new Set();
-            set.add('visibility:restricted');
-            capsByPlugin.set(plugin, set);
-        };
-        const tools = caps.tools.current?.getAll() ?? [];
-        for (const t of tools) {
-            const list = toolsByPlugin.get(t.pluginName) ?? [];
-            list.push(t.name);
-            toolsByPlugin.set(t.pluginName, list);
-            addCaps(t.pluginName, t.visibility);
+        for (const t of caps.tools.present ? caps.tools.use.getAll() : []) {
+            toolsByPlugin.set(t.pluginName, [...(toolsByPlugin.get(t.pluginName) ?? []), t.name]);
         }
         const commandsByPlugin = new Map();
-        const cmds = caps.commands.current?.getAll() ?? [];
-        for (const c of cmds) {
+        for (const c of caps.commands.present ? caps.commands.use.getAll() : []) {
             const owner = c.pluginName ?? 'unknown';
-            const list = commandsByPlugin.get(owner) ?? [];
-            list.push(c.name);
-            commandsByPlugin.set(owner, list);
-            addCaps(owner, c.visibility);
+            commandsByPlugin.set(owner, [...(commandsByPlugin.get(owner) ?? []), c.name]);
         }
-        const plugins = pm.getStatus().map(p => {
+        const doc = caps.hostConfig.present ? caps.hostConfig.use : undefined;
+        const sections = doc?.getAll().plugins ?? {};
+        const versionOf = caps.versions();
+        const plugins = blockedStatus({ plugins: pm, services: caps.services, doc }).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);
+            // 线上格式照旧给 requiredServices / optionalServices：从 core 状态里唯一的依赖信息 uses 派生
+            const requiredServices = p.uses.filter(use => use.kind === 'required').map(use => use.service);
+            const optionalServices = p.uses.filter(use => use.kind === 'optional').map(use => use.service);
+            const declared = [...requiredServices, ...optionalServices];
             return {
                 name: p.name,
                 instanceId: p.instanceId,
                 displayName: p.displayName,
+                // 展示元数据：子系统按插件声明原样给，归哪组、组名与顺序由界面定；版本取已装的包
+                subsystem: entry?.definition?.subsystem,
+                version: versionOf(p.name),
                 state: p.state,
                 slow: p.slow,
+                lingering: p.lingering,
+                self: p.instanceId === caps.self || undefined,
                 provides: p.provides ?? [],
-                // 完整能力声明含内置能力与 apply 别名；外部依赖闸与工具/指令可见性仍是各自独立的事实。
-                uses: p.uses,
-                requiredServices: p.requiredServices ?? [],
-                optionalServices: p.optionalServices ?? [],
-                capabilities: [...(capsByPlugin.get(p.instanceId) ?? [])],
+                requiredServices,
+                optionalServices,
+                servicePreferences: Object.fromEntries(declared.flatMap(name => {
+                    const preferred = caps.services.preferred(name, { for: p.instanceId });
+                    return preferred === undefined ? [] : [[name, preferred]];
+                })),
+                serviceSelections: Object.fromEntries(declared.flatMap(name => {
+                    const [selected] = caps.services.inspect(name, { for: p.instanceId });
+                    return selected ? [[name, { contextId: selected.contextId, basis: selected.basis }]] : [];
+                })),
+                lacking: p.lacking,
+                waiting: p.waiting,
+                unconfigured: p.unconfigured,
                 tools: toolsByPlugin.get(p.instanceId) ?? [],
                 commands: commandsByPlugin.get(p.instanceId) ?? [],
                 reusable: p.reusable ?? false,
                 // extends / config / configSchema / defaultConfig 非内核状态摘要字段
-                // （getStatus 只含内核事实）：从 entry.config / entry.definition 补齐给前端。
+                // （getStatus 只含内核事实）：从配置文档与 entry.definition 补齐给前端。
+                // 配置给文档形态：密钥字段上是引用，不是原值；前端据它建编辑草稿，引用原样发回即保持原值。
+                // 宿主不提供配置文档时给运行态，去掉密钥字段（运行态里是原值）
                 extends: entry?.definition?.extends,
-                config,
-                configSchema: entry?.definition?.configSchema,
-                defaultConfig: defaultsFrom(entry?.definition?.configSchema),
+                configSection: Object.hasOwn(sections, p.instanceId),
+                config: doc ? doc.getPluginConfig(p.instanceId) : mapSecretFields(schema, entry?.config ?? {}, () => undefined),
+                configSchema: schema,
+                defaultConfig: defaultsFrom(schema),
                 error: p.error,
             };
         });
-        res.json({ plugins });
+        res.json({ plugins, secretRefCounts: doc ? countSecretRefs(doc.getAll().plugins) : {} });
     });
-    // 获取可用的 WebUI 页面（由活跃插件经 webui-server 的绑定接口 registerPage 登记）
-    expressApp.get('/api/pages', gate(), (_req, res) => {
-        const app = getApp();
-        const pm = getPluginMgr();
-        if (!app || !pm) {
-            res.json([]);
-            return;
-        }
-        const webuiSvc = caps.webui();
-        if (!webuiSvc) {
-            res.json([]);
-            return;
-        }
-        const displayNameByPlugin = new Map();
-        for (const p of pm.getStatus())
-            displayNameByPlugin.set(p.instanceId, p.displayName);
-        const pages = [];
-        for (const page of webuiSvc.getPages()) {
-            pages.push({ ...page, plugin: page.pluginName, pluginDisplayName: displayNameByPlugin.get(page.pluginName) });
-        }
-        pages.sort((a, b) => (a.order ?? 99) - (b.order ?? 99));
-        res.json(pages);
-    });
-    // 通用声明式页面操作：调用插件经 webuiServer.registerAction 登记的处理函数
-    expressApp.post('/api/page-action/:plugin/:method', async (req, res) => {
-        const { plugin: pluginName, method } = req.params;
-        const args = req.body ?? {};
-        const app = getApp();
-        const pm = getPluginMgr();
-        if (!app || !pm) {
-            res.status(500).json({ error: 'App 不可用' });
-            return;
-        }
-        const entry = pm.getPlugin(pluginName);
-        if (!entry || entry.state !== 'active') {
-            res.status(404).json({ error: `插件 ${pluginName} 不存在或未激活` });
-            return;
-        }
-        const handler = getAction(pluginName, method);
-        if (!handler) {
-            res.status(404).json({ error: `处理器 ${method} 不存在` });
-            return;
-        }
-        // ===== owner 闸 + 调用者身份（单 owner 终态）=====
-        // 单 token ⟺ webui:console ⟺ owner；auth.middleware 已校 token，这里复核身份并把
-        // caller 传给 action。各 action 自身对敏感操作再做 owner 自检（如 setUserTier）。
-        // 多账户的 action: 能力委托（per-user grant/deny / actionsMeta 可见性）已剥离。
-        const caller = identify(req);
-        if (!caller) {
-            res.status(403).json({ error: `操作 ${pluginName}/${method} 需要 owner 权限` });
-            return;
-        }
-        try {
-            res.json({ ok: true, data: await handler(args, caller) });
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            res.status(500).json({ error: msg });
-        }
-    });
-    // 获取当前全局配置
-    expressApp.get('/api/config', gate(), (_req, res) => {
+    // 宿主配置：文档里写了的核心键、它们的 schema、要重启才生效的键与家目录
+    route(expressApp, 'GET /api/config', gate(), (_req, res) => {
         const doc = docOr503(res);
         if (!doc)
             return;
-        res.json({ ...doc.getAll(), _schema: CORE_CONFIG_SCHEMA });
+        const all = doc.getAll();
+        const config = Object.fromEntries(Object.keys(CORE_CONFIG_SCHEMA)
+            .filter(key => all[key] !== undefined)
+            .map(key => [key, all[key]]));
+        res.json({ config, schema: CORE_CONFIG_SCHEMA, restartKeys: [...RESTART_KEYS], home: caps.home });
     });
-    // 更新全局配置字段
-    expressApp.put('/api/config', gate(), async (req, res) => {
+    // 改宿主配置的核心键：只保存，要重启才生效的键改了时回执写明，由界面出「重启以生效」，重启走 POST /api/restart
+    route(expressApp, 'PUT /api/config', gate(), async (req, res) => {
         const updates = req.body;
         if (!updates || typeof updates !== 'object') {
             res.status(400).json({ error: '请求体必须是对象' });
             return;
         }
-        const app = getApp();
-        if (!app) {
-            res.status(500).json({ error: 'App 不可用' });
-            return;
-        }
         const doc = docOr503(res);
         if (!doc)
             return;
-        // 可改的只有 CORE_CONFIG_SCHEMA 的键。内置前端（buildDraftFromSchema）会把 GET 到的整份配置连同
-        // _schema 原样回传，其中 plugins 等还可能是过期快照（插件配置页保存后不刷新全局 config），
-        // 所以不能按键报错：其余键一律不应用，但把真有改动的点名回给调用方——不静默吞掉却回复「已保存」。
+        // 只收 CORE_CONFIG_SCHEMA 的键：别的顶层键（插件配置、禁用名单等）各有自己的路由，写在这里的一律拒收
         const allowed = Object.keys(CORE_CONFIG_SCHEMA);
+        const foreign = Object.keys(updates).filter(k => !allowed.includes(k));
+        if (foreign.length > 0) {
+            res.status(400).json({ error: `只能改核心键（${allowed.join('、')}），不收：${foreign.join('、')}` });
+            return;
+        }
         const current = doc.getAll();
-        // 文档里没写的核心键按 schema 默认值比较：内置前端把默认值回填进草稿后整份回传，不能据此判成改动（否则只改
-        // 名字也会把默认值写进文件并触发重启）
-        const currentOf = (k) => current[k] ?? CORE_CONFIG_SCHEMA[k]?.default;
-        const differs = (k) => !isDeepStrictEqual(updates[k], currentOf(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 defaultOf = (k) => CORE_CONFIG_SCHEMA[k]?.default;
+        // 文档里没写的核心键按 schema 默认值比较：回传的默认值不算改动，不写进文件
+        const currentOf = (k) => current[k] ?? defaultOf(k);
+        // 核心键提交 null 表示清空（恢复默认）：回到默认值，并从文档里删掉这个键，不把默认值写死进文件
+        const submittedOf = (k) => (updates[k] === null ? defaultOf(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 每次实时读文档（appName），保存即生效。
-        // 装有人设时聊天显示人设名，应用名称只在仪表盘上看得到
-        const restartNeeded = changed.some(k => k === 'logLevel' || k === 'slowThresholdMs');
-        const note = ignored.length > 0 ? `（已忽略不可修改的字段: ${ignored.join(', ')}）` : '';
+            doc.set(key, updates[key] === null ? undefined : values[key]);
+        const restartNeeded = changed.some(k => RESTART_KEYS.includes(k));
         try {
             await doc.save();
         }
         catch (err) {
-            // 拒写与写入失败都撤回文档里的改动，免得下一次任意保存把这次没存下的修改写进文件。
-            // logLevel / slowThresholdMs 要重启才生效，name 由状态接口读文档：撤回后都回到修改前，运行态不留改动
+            // 拒写与写入失败都撤回文档里的改动，免得下一次任意保存把这次没存下的修改写进文件
             for (const key of changed)
                 doc.set(key, previous[key]);
             res
@@ -263,48 +283,40 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
                 .json({ error: `未写入配置文件（${errorMessage(err)}），本次修改已撤回` });
             return;
         }
-        if (!restartNeeded) {
-            res.json({ ok: true, message: `全局配置已更新并保存${note}`, ignored });
+        res.json({
+            ok: true,
+            message: restartNeeded ? '全局配置已保存，重启后生效' : '全局配置已更新并保存',
+            restartNeeded,
+        });
+    });
+    // 重启应用。发起之后的停机是异步的（core 先广播 app:restarting，何时停机由重启策略决定），这条回复来得及发出；
+    // 宿主没注入重启策略时 restart() 同步抛错，回 500，界面据此不去等待重连
+    route(expressApp, 'POST /api/restart', gate(), (_req, res) => {
+        const app = caps.app.present ? caps.app.use : undefined;
+        if (!app) {
+            res.status(500).json({ error: 'App 不可用' });
             return;
         }
-        // 先发起重启再回复：宿主没注入重启策略时 restart() 同步抛错，据此回 restart:false，前端才不会进入等待重连
-        // 却永远等不到。发起之后的停机是异步的（core 先广播 app:restarting，何时停机由重启策略决定，Node 宿主延迟
-        // 500ms），这条回复来得及发出。已写进文件，重启失败不撤回：改动在下次启动时生效
         try {
             app.restart();
         }
         catch (err) {
-            const reason = `全局配置已保存，但重启失败（${errorMessage(err)}），改动在下次启动时生效`;
+            const reason = `重启失败（${errorMessage(err)}），改动在下次启动时生效`;
             caps.logger?.error(reason);
-            res.json({ ok: true, message: `${reason}${note}`, restart: false, ignored });
+            res.status(500).json({ error: reason });
             return;
         }
-        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);
-        if (!doc)
-            return;
-        try {
-            const pluginConfig = doc.getPluginConfig(pluginName);
-            res.json({ name: pluginName, config: pluginConfig });
-        }
-        catch (err) {
-            res.status(400).json({ error: errorMessage(err) });
-        }
+        res.json({ ok: true, message: '正在重启应用' });
     });
     // 更新插件配置
-    expressApp.put('/api/plugins/:name/config', gate(), async (req, res) => {
+    route(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;
         }
-        const pm = getPluginMgr();
+        const pm = caps.plugins.present ? caps.plugins.use : undefined;
         if (!pm) {
             res.status(500).json({ error: '插件管理服务不可用' });
             return;
@@ -312,60 +324,56 @@ 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 派生（唯一声明来源）。
+        // 合进原配置再交给宿主的 applyPluginConfig：配置是**整体替换**语义（core 的 orchestration/plugin.ts 里
+        // entry.config = newConfig 直接顶掉）。基线取配置文档里的原配置而非裸默认值：defaultsFrom 只收录声明了
+        // default 的键，而 apiKey / accessToken 这类 secret 多数**没有** default，以裸默认值打底时请求里没带 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) });
             return;
         }
+        // 没登记的实例不经这里新建（宿主的 applyPluginConfig 会按同模块定义登记它），建实例走 POST instances
+        if (!entry) {
+            res.status(404).json({ error: `插件 ${pluginName} 不存在` });
+            return;
+        }
         const note = (ignored.length > 0 ? `（已忽略未声明的配置字段: ${ignored.join(', ')}）` : '') +
             (removed.length > 0 ? `（已从配置文件移除未声明的字段: ${removed.join(', ')}）` : '');
         // 保存前校验，拦新不追旧：只拒绝本次编辑**新引入**的 invalid（配错了）。
-        // 存量问题放行——否则带着历史脏值（或 schema 表达不了的多态字段，如 mcp-client
-        // 的 args 数组形态）的插件会在 WebUI 永久存不了任何字段；启动侧 config-sync
+        // 存量问题放行——否则带着历史脏值（或 schema 表达不了的多态字段，如字符串与数组两种写法都收的
+        // 字段）的插件会在 WebUI 永久存不了任何字段；启动侧 config-sync
         // 对它们已有告警。missing（没配全）也放行：半成品配置是启用插件配到一半的
         // 正常中间态。
-        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('；')}`,
@@ -373,54 +381,58 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             });
             return;
         }
-        // 运行态与文档都已是这份配置：不重建插件（updateConfig 即 bounce，会连带重启依赖它所提供服务的下游）。
-        // 仍照常落盘：上一次保存可能写文件失败（500），文档与运行态已是新配置而文件没变，原样重试要能补写；
-        // 自写回不会触发 watch 重载。只认 active：error 态插件靠原样保存来重试激活，照旧走 updateConfig
-        if (entry?.state === 'active' && isDeepStrictEqual(merged, entry.config) && isDeepStrictEqual(merged, docConfig)) {
-            if (!(await saveAfterApply(doc, res, 'reload')))
-                return;
-            res.json({ ok: true, message: `插件 ${pluginName} 配置无改动，已写回配置文件${note}`, ignored, removed });
-            return;
-        }
-        let success;
+        // 运行态、文档、密钥与落盘由宿主一步完成：解析出的配置与运行态相同、实例在 active 时不重建插件
+        // （updateConfig 即 bounce，会连带重启依赖它所提供服务的下游），照常写回文档并落盘：上一次保存可能写文件失败（500），
+        // 原样重试要能补写；自写回不会触发 watch 重载。error 态插件靠原样保存来重试激活
+        let result;
         try {
-            success = await pm.updateConfig(pluginName, merged);
+            result = await doc.applyPluginConfig(pluginName, merged);
         }
         catch (err) {
             res.status(400).json({ error: errorMessage(err) });
             return;
         }
-        if (success) {
-            // 管理动作只改运行态；跨重启保留要本路由写文档并落盘
-            doc.setPluginConfig(pluginName, merged);
-            // 按新配置重新激活失败、转为 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: `${failure}；配置已写入配置文件${note}` });
+        if (result.status === 'refused') {
+            refuse(pm, res, pluginName, '配置更新');
+            return;
+        }
+        // 运行态与文档都没变：回「无改动」。只有运行态没变（例如文档里补了配置段）照常按已更新回报，插件没有重建
+        if (!result.reloaded && isDeepStrictEqual(merged, docConfig)) {
+            if (result.saveError !== undefined) {
+                reportSaveFailure(res, result.saveError, 'reload');
                 return;
             }
-            res.json({
-                ok: true,
-                message: `插件 ${pluginName} 配置已更新${note}${aside ? `；${aside}` : ''}`,
-                ignored,
-                removed,
-            });
-        }
-        else {
-            res.status(404).json({ error: `插件 ${pluginName} 不存在` });
+            res.json({ ok: true, message: `插件 ${pluginName} 配置无改动，已写回配置文件${note}`, ignored, removed });
+            return;
         }
+        // 按新配置重新激活失败、转为 error：照样写入配置（原样再存即重试激活），回执按实际状态说明。
+        // 禁用态只换上新配置、保持禁用，启用时按它激活
+        const after = await settledEntry(pm, pluginName);
+        const failure = after?.state === 'error'
+            ? `插件 ${pluginName} 按新配置重新激活失败，已转为 error 态（${after.error ?? '详见日志'}）`
+            : undefined;
+        const aside = after?.state === 'disabled'
+            ? '插件已禁用，启用时按新配置激活'
+            : notYetActive(pm, caps.services, pluginName, after?.state);
+        if (result.saveError !== undefined) {
+            reportSaveFailure(res, result.saveError, 'reload', failure ?? aside);
+            return;
+        }
+        // 写进了配置文件就回 2xx，激活失败也一样：表单据状态码区分「没写成」（留着改）与「写成了」（收起、刷新）。
+        // 写成之后草稿已经过时，例如清除的密钥键已随这次保存从 secrets.yaml 删掉，再「撤销」只会引用不存在的键
+        res.json({
+            ok: true,
+            message: failure !== undefined
+                ? `${failure}；配置已写入配置文件${note}`
+                : `插件 ${pluginName} 配置已更新${note}${aside ? `；${aside}` : ''}`,
+            ignored,
+            removed,
+        });
     });
     // 启用插件
-    expressApp.post('/api/plugins/:name/enable', gate(), async (req, res) => {
+    route(expressApp, 'POST /api/plugins/:name/enable', gate(), async (req, res) => {
         const pluginName = req.params.name;
-        const pm = getPluginMgr();
+        const pm = caps.plugins.present ? caps.plugins.use : undefined;
         if (!pm) {
             res.status(500).json({ error: '插件管理服务不可用' });
             return;
@@ -438,28 +450,31 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         }
         if (success) {
             doc.setPluginEnabled(pluginName, true);
-            // 激活失败、转为 error：照样记为启用（重启时再激活），但按实际状态回报
+            // 激活失败、转为 error：照样记为启用（重启时再激活），回执按实际状态说明。写进了配置文件就回 2xx，口径同改配置
             const after = await settledEntry(pm, pluginName);
             const failure = after?.state === 'error'
                 ? `插件 ${pluginName} 激活失败，已转为 error 态（${after.error ?? '详见日志'}）`
                 : undefined;
-            const aside = notYetActive(after?.state);
+            const aside = notYetActive(pm, caps.services, pluginName, after?.state);
             if (!(await saveAfterApply(doc, res, 'restart', failure ?? aside)))
                 return;
-            if (failure !== undefined) {
-                res.status(500).json({ error: `${failure}；配置文件已记为启用` });
-                return;
-            }
-            res.json({ ok: true, message: `插件 ${pluginName} 已启用${aside ? `；${aside}` : ''}` });
+            res.json({
+                ok: true,
+                message: failure !== undefined
+                    ? `${failure}；配置文件已记为启用`
+                    : `插件 ${pluginName} 已启用${aside ? `；${aside}` : ''}`,
+            });
         }
         else {
-            res.status(404).json({ error: `插件 ${pluginName} 不存在` });
+            refuse(pm, res, pluginName, '启用');
         }
     });
     // 禁用插件
-    expressApp.post('/api/plugins/:name/disable', gate(), async (req, res) => {
+    route(expressApp, 'POST /api/plugins/:name/disable', gate(), async (req, res) => {
         const pluginName = req.params.name;
-        const pm = getPluginMgr();
+        if (refuseSelf(res, pluginName))
+            return;
+        const pm = caps.plugins.present ? caps.plugins.use : undefined;
         if (!pm) {
             res.status(500).json({ error: '插件管理服务不可用' });
             return;
@@ -476,30 +491,62 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             return;
         }
         if (success) {
-            // 仍在初始化、不响应 abort 的插件，宽限到期转 error 而非 disabled：照样记为禁用（重启时不再激活），但按实际状态回报
-            const stuck = pm.getPlugin(pluginName)?.state === 'error'
-                ? `插件 ${pluginName} 未在宽限内停止，已转为 error 态，详见日志`
+            // 已禁用，但旧实例（如不响应 abort 的初始化）超过宽限仍没停下：回执说明这一点。写进了配置文件就回 2xx，口径同改配置
+            const stuck = pm.getStatus().find(entry => entry.instanceId === pluginName)?.lingering
+                ? `插件 ${pluginName} 已禁用，但超过宽限仍未停下，详见日志`
                 : undefined;
             doc.setPluginEnabled(pluginName, false);
             if (!(await saveAfterApply(doc, res, 'restart', stuck)))
                 return;
-            if (stuck !== undefined) {
-                res.status(500).json({ error: `${stuck}；配置文件已记为禁用` });
-                return;
-            }
-            res.json({ ok: true, message: `插件 ${pluginName} 已禁用` });
+            res.json({
+                ok: true,
+                message: stuck !== undefined ? `${stuck}；配置文件已记为禁用` : `插件 ${pluginName} 已禁用`,
+            });
         }
         else {
-            res.status(404).json({ error: `插件 ${pluginName} 不在注册表或已处于终态，无法禁用` });
+            refuse(pm, res, pluginName, '禁用');
+        }
+    });
+    // 重载：拆掉当前激活再按原配置重新激活，不写配置文件；失败的插件重载即重试
+    route(expressApp, 'POST /api/plugins/:name/reload', gate(), async (req, res) => {
+        const pluginName = req.params.name;
+        const pm = caps.plugins.present ? caps.plugins.use : undefined;
+        if (!pm) {
+            res.status(500).json({ error: '插件管理服务不可用' });
+            return;
         }
+        if (pm.getPlugin(pluginName)?.state === 'disabled') {
+            res.status(409).json({ error: `插件 ${pluginName} 已停用，启用后才能重载` });
+            return;
+        }
+        let success;
+        try {
+            success = await pm.bounce(pluginName);
+        }
+        catch (err) {
+            res.status(400).json({ error: errorMessage(err) });
+            return;
+        }
+        if (!success) {
+            refuse(pm, res, pluginName, '重载');
+            return;
+        }
+        const after = await settledEntry(pm, pluginName);
+        const aside = notYetActive(pm, caps.services, pluginName, after?.state);
+        res.json({
+            ok: true,
+            message: after?.state === 'error'
+                ? `插件 ${pluginName} 重新激活失败，已转为 error 态（${after.error ?? '详见日志'}）`
+                : `插件 ${pluginName} 已重载${aside ? `；${aside}` : ''}`,
+        });
     });
     // 经宿主 plugin-source 重新扫描并加载新插件
-    expressApp.post('/api/plugins/scan', gate(), async (_req, res) => {
-        const source = caps.source.current;
-        if (!source) {
+    route(expressApp, 'POST /api/plugins/scan', gate(), async (_req, res) => {
+        if (!caps.source.present) {
             res.status(503).json({ error: '宿主未提供插件来源，无法扫描' });
             return;
         }
+        const source = caps.source.use;
         try {
             const loaded = await source.rescan();
             res.json({ ok: true, loaded, message: loaded.length > 0 ? `新加载 ${loaded.length} 个插件` : '无新插件' });
@@ -510,7 +557,7 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         }
     });
     // 创建插件多实例
-    expressApp.post('/api/plugins/:name/instances', gate(), async (req, res) => {
+    route(expressApp, 'POST /api/plugins/:name/instances', gate(), async (req, res) => {
         const moduleName = req.params.name;
         const suffix = req.body?.suffix;
         const config = req.body?.config ?? {};
@@ -522,7 +569,11 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             res.status(400).json({ error: 'suffix 只能包含字母、数字、下划线和连字符' });
             return;
         }
-        const pm = getPluginMgr();
+        if (typeof config !== 'object' || Array.isArray(config)) {
+            res.status(400).json({ error: 'config 字段必须是对象' });
+            return;
+        }
+        const pm = caps.plugins.present ? caps.plugins.use : undefined;
         if (!pm) {
             res.status(500).json({ error: '插件管理服务不可用' });
             return;
@@ -531,11 +582,14 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         if (!doc)
             return;
         // 实例创建编排（配置文件编排属管理面,内核只出 register 机制）：
-        // 查同名 module → reusable/查重校验 → 合并默认配置写入 → register 激活。
-        const sourceModule = pm
-            .getStatus()
-            .map(p => pm.getPlugin(p.instanceId)?.definition)
-            .find(m => m?.name === moduleName);
+        // 查同名 module → reusable/查重校验 → 合并默认配置、裁剪与校验 → 写入 → register 激活。
+        // 模块定义主实例优先、否则取任一在册实例的，与宿主登记新实例时取定义的规则一致：合并、裁剪与校验所用的 schema
+        // 就是登记时的那一份
+        const sourceModule = pm.getPlugin(moduleName)?.definition ??
+            pm
+                .getStatus()
+                .map(p => pm.getPlugin(p.instanceId)?.definition)
+                .find(m => m?.name === moduleName);
         if (!sourceModule) {
             res.status(400).json({ error: `无法创建实例：模块 "${moduleName}" 未找到` });
             return;
@@ -549,45 +603,59 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             res.status(400).json({ error: `无法创建实例："${instanceId}" 已存在` });
             return;
         }
-        const mergedConfig = { ...defaultsFrom(sourceModule.configSchema), ...config };
-        let registered;
-        try {
-            doc.setPluginConfig(instanceId, mergedConfig);
-            // 文档里残留的禁用标记（手改配置文件留下的）照旧生效：以禁用态登记
-            registered = await pm.register(sourceModule, mergedConfig, instanceId, {
-                disabled: doc.isPluginDisabled(instanceId),
+        // 与改配置同一套合并与裁剪，基线是空对象。校验不分存量：新实例没有历史配置，类型不符的值一律拒绝，
+        // 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 result;
+        try {
+            result = await doc.applyPluginConfig(instanceId, mergedConfig);
         }
         catch (err) {
             res.status(400).json({ error: errorMessage(err) });
             return;
         }
-        if (!registered) {
+        if (result.status === 'refused') {
             // 前面已查过重名与 reusable，走到这里的实际只有停机进行中：配置不落盘，免得下次启动按文件登记
-            doc.removePluginConfig(instanceId);
             res.status(409).json({ error: `实例 ${instanceId} 未登记（停机中或被拒，见日志），配置未写入` });
             return;
         }
-        // 激活失败、转为 error：实例与配置照样保留并落盘（改配置保存即重试激活），但按实际状态回报
+        // 激活失败、转为 error：实例与配置照样保留并落盘（改配置保存即重试激活），回执按实际状态说明。
+        // 写进了配置文件就回 2xx，口径同改配置：实例已登记，表单该收起，留着再点「创建」只会得到「已存在」
         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}；配置已写入配置文件` });
-            return;
-        }
-        res.json({ ok: true, instanceId, message: `已创建实例 ${instanceId}${aside ? `；${aside}` : ''}` });
+            : notYetActive(pm, caps.services, instanceId, after?.state);
+        if (result.saveError !== undefined) {
+            reportSaveFailure(res, result.saveError, 'reload', failure ?? aside);
+            return;
+        }
+        res.json({
+            ok: true,
+            instanceId,
+            message: failure !== undefined
+                ? `${failure}；配置已写入配置文件${note}`
+                : `已创建实例 ${instanceId}${note}${aside ? `；${aside}` : ''}`,
+            ignored,
+        });
     });
     // 删除插件多实例
-    expressApp.delete('/api/plugins/:instanceId/instance', gate(), async (req, res) => {
+    route(expressApp, 'DELETE /api/plugins/:instanceId/instance', gate(), async (req, res) => {
         const instanceId = req.params.instanceId;
-        const pm = getPluginMgr();
+        const pm = caps.plugins.present ? caps.plugins.use : undefined;
         if (!pm) {
             res.status(500).json({ error: '插件管理服务不可用' });
             return;
@@ -620,8 +688,9 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
                 .json({ error: `未删除实例 ${instanceId}：未写入配置文件（${errorMessage(err)}）` });
             return;
         }
+        let unloaded;
         try {
-            await pm.unload(instanceId);
+            unloaded = await pm.unload(instanceId);
         }
         catch (err) {
             res.status(500).json({
@@ -629,58 +698,12 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             });
             return;
         }
-        res.json({ ok: true, message: `已删除实例 ${instanceId}` });
-    });
-    // 保存配置文档：与其它落盘路由同一口径，宿主拒写回 409、其它失败回 500。宿主不持久化时 save 不写盘，
-    // 回执因此只说「已保存」，不说保存到磁盘
-    expressApp.post('/api/config/save', gate(), async (_req, res) => {
-        const doc = docOr503(res);
-        if (!doc)
+        // 返回 false 而条目还在：停机中拒绝了卸载，配置段已删、实例仍在跑到停机为止。条目已不在的是别处先卸掉了，照常回已删除
+        if (!unloaded && pm.getPlugin(instanceId)) {
+            res.json({ ok: true, message: `已从配置文件删除实例 ${instanceId}；停机中，未卸载运行中的实例` });
             return;
-        try {
-            await doc.save();
-            res.json({ ok: true, message: '配置已保存' });
-        }
-        catch (err) {
-            res.status(isConfigSaveRefused(err) ? 409 : 500).json({ error: errorMessage(err) });
         }
+        res.json({ ok: true, message: `已删除实例 ${instanceId}` });
     });
 }
-/** 列表 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