@aalis/plugin-webui-server 0.12.0 → 0.14.0

package/dist/routes/plugins.js

@@ -1,14 +1,74 @@
 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';
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/**
+ * 落盘被拒后运行态怎样与文件对齐：插件配置与新建的实例随配置文件热重载（文件里没有配置段的后缀实例会被卸载）；
+ * 启停与服务偏好只在重启时按文件登记
+ */
+const RECONCILE = {
+    reload: '修好配置文件后会按文件内容重载',
+    restart: '修好配置文件后，重启时以文件内容为准',
+};
+/**
+ * 管理动作改完运行态之后落盘；失败时回 `applied: true` 并返回 false：改动已在运行态生效、只是没写进文件，
+ * 调用方别当成「没改成」去重试。宿主拒写（配置文件有尚未生效的外部修改）回 409，之后以文件为准对账；
+ * 其它失败（权限、磁盘写满等）回 500，文件没变也不会触发重载，改动留在文档里，下一次成功保存时一并写入。
+ * `outcome` 是动作之后插件没有落在预期状态的说明（如激活失败转 error、仍在激活、保持禁用）：落盘也失败时放在回执开头，
+ * 两件事一并说明。
+ */
+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: `${lead}已在运行态生效，但未写入配置文件（${errorMessage(err)}）；${RECONCILE[reconcile]}`,
+                applied: true,
+            });
+        }
+        else {
+            res.status(500).json({
+                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;
+}
 /** 注册插件管理 + 全局配置相关 REST 路由 */
 export function registerPluginRoutes(expressApp, caps, identify, gate, getAction) {
     const getApp = () => caps.app.current;
     const getPluginMgr = () => caps.plugins.current;
-    const hostConfig = () => caps.hostConfig.require();
+    /** 配置文档由宿主提供；没有时读写文档的路由一律 503，与扫描、市场路由的缺席口径一致 */
+    const docOr503 = (res) => {
+        const doc = caps.hostConfig.current;
+        if (!doc)
+            res.status(503).json({ error: '宿主未提供配置文档（host-config），无法读写配置' });
+        return doc;
+    };
     // 获取插件列表及状态
     expressApp.get('/api/plugins', gate(), (_req, res) => {
         const app = getApp();
@@ -55,6 +115,7 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
                 instanceId: p.instanceId,
                 displayName: p.displayName,
                 state: p.state,
+                slow: p.slow,
                 provides: p.provides ?? [],
                 // 完整能力声明含内置能力与 apply 别名；外部依赖闸与工具/指令可见性仍是各自独立的事实。
                 uses: p.uses,
@@ -137,8 +198,10 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
     });
     // 获取当前全局配置
     expressApp.get('/api/config', gate(), (_req, res) => {
-        const allConfig = hostConfig().getAll();
-        res.json({ ...allConfig, _schema: CORE_CONFIG_SCHEMA });
+        const doc = docOr503(res);
+        if (!doc)
+            return;
+        res.json({ ...doc.getAll(), _schema: CORE_CONFIG_SCHEMA });
     });
     // 更新全局配置字段
     expressApp.put('/api/config', gate(), async (req, res) => {
@@ -148,17 +211,22 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             return;
         }
         const app = getApp();
-        const pm = getPluginMgr();
-        if (!app || !pm) {
+        if (!app) {
             res.status(500).json({ error: 'App 不可用' });
             return;
         }
+        const doc = docOr503(res);
+        if (!doc)
+            return;
         // 可改的只有 CORE_CONFIG_SCHEMA 的键。内置前端（buildDraftFromSchema）会把 GET 到的整份配置连同
         // _schema 原样回传，其中 plugins 等还可能是过期快照（插件配置页保存后不刷新全局 config），
         // 所以不能按键报错：其余键一律不应用，但把真有改动的点名回给调用方——不静默吞掉却回复「已保存」。
         const allowed = Object.keys(CORE_CONFIG_SCHEMA);
-        const current = hostConfig().getAll();
-        const differs = (k) => !isDeepStrictEqual(updates[k], current[k]);
+        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
@@ -175,32 +243,53 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             res.status(400).json({ error: invalid.join('; ') });
             return;
         }
+        const previous = Object.fromEntries(changed.map(k => [k, current[k]]));
         for (const key of changed)
-            hostConfig().set(key, updates[key]);
-        // name / logLevel 都要重启才生效；值没变就不重启
-        const restartNeeded = changed.length > 0;
+            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(', ')}）` : '';
         try {
-            await app.saveConfig();
-            if (restartNeeded) {
-                res.json({ ok: true, message: `全局配置已更新，正在重启应用以生效…${note}`, restart: true, ignored });
-                app.restart();
-            }
-            else {
-                res.json({ ok: true, message: `全局配置已更新并保存${note}`, ignored });
-            }
+            await doc.save();
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            res.status(500).json({ error: msg });
+            // 拒写与写入失败都撤回文档里的改动，免得下一次任意保存把这次没存下的修改写进文件。
+            // logLevel / slowThresholdMs 要重启才生效，name 由状态接口读文档：撤回后都回到修改前，运行态不留改动
+            for (const key of changed)
+                doc.set(key, previous[key]);
+            res
+                .status(isConfigSaveRefused(err) ? 409 : 500)
+                .json({ error: `未写入配置文件（${errorMessage(err)}），本次修改已撤回` });
+            return;
         }
+        if (!restartNeeded) {
+            res.json({ ok: true, message: `全局配置已更新并保存${note}`, ignored });
+            return;
+        }
+        // 先发起重启再回复：宿主没注入重启策略时 restart() 同步抛错，据此回 restart:false，前端才不会进入等待重连
+        // 却永远等不到。发起之后的停机是异步的（core 先广播 app:restarting，何时停机由重启策略决定，Node 宿主延迟
+        // 500ms），这条回复来得及发出。已写进文件，重启失败不撤回：改动在下次启动时生效
+        try {
+            app.restart();
+        }
+        catch (err) {
+            const reason = `全局配置已保存，但重启失败（${errorMessage(err)}），改动在下次启动时生效`;
+            caps.logger?.error(reason);
+            res.json({ ok: true, message: `${reason}${note}`, restart: false, ignored });
+            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 = hostConfig().getPluginConfig(pluginName);
+            const pluginConfig = doc.getPluginConfig(pluginName);
             res.json({ name: pluginName, config: pluginConfig });
         }
         catch (err) {
@@ -215,34 +304,52 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             res.status(400).json({ error: 'config 字段必须是对象' });
             return;
         }
-        const app = getApp();
         const pm = getPluginMgr();
-        if (!app || !pm) {
-            res.status(500).json({ error: 'App 不可用' });
+        if (!pm) {
+            res.status(500).json({ error: '插件管理服务不可用' });
             return;
         }
+        const doc = docOr503(res);
+        if (!doc)
+            return;
         // 补默认值再交给 updateConfig：后者是**整体替换**语义（core 的 orchestration/plugin.ts 里
         // entry.config = newConfig 直接顶掉）。不补的话，PUT 一个部分对象就会把未列出的
         // 字段从内存态和 yaml 里一起抹掉。默认值从 configSchema 派生（唯一声明来源）。
-        const schema = pm.getPlugin(pluginName)?.definition?.configSchema;
+        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 = [];
         try {
-            stored = { ...defaults, ...hostConfig().getPluginConfig(pluginName) };
-            merged = { ...stored, ...newConfig };
-            // 与 runtime config-sync 同一政策：有 schema 就裁掉未知键并 warn，避免 WebUI 把
-            // 手滑字段写进 stored，而 YAML watch 路径却会裁掉——两边政策必须一致。
-            if (schema && Object.keys(schema).length > 0) {
-                const removed = [];
-                merged = removeExtraFields(merged, schema, removed);
-                if (removed.length > 0) {
-                    caps.logger?.warn(`配置同步：${pluginName} 裁掉 schema 外字段 [${removed.join(', ')}]`);
+            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(', ')}]`);
                 }
             }
         }
@@ -250,12 +357,13 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             res.status(400).json({ error: errorMessage(err) });
             return;
         }
+        const note = (ignored.length > 0 ? `（已忽略未声明的配置字段: ${ignored.join(', ')}）` : '') +
+            (removed.length > 0 ? `（已从配置文件移除未声明的字段: ${removed.join(', ')}）` : '');
         // 保存前校验，拦新不追旧：只拒绝本次编辑**新引入**的 invalid（配错了）。
         // 存量问题放行——否则带着历史脏值（或 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}`));
         if (issues.length > 0) {
@@ -265,6 +373,15 @@ 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;
         try {
             success = await pm.updateConfig(pluginName, merged);
@@ -274,34 +391,43 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             return;
         }
         if (success) {
-            await app.saveConfig();
-            res.json({ ok: true, message: `插件 ${pluginName} 配置已更新` });
+            // 管理动作只改运行态；跨重启保留要本路由写文档并落盘
+            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}` });
+                return;
+            }
+            res.json({
+                ok: true,
+                message: `插件 ${pluginName} 配置已更新${note}${aside ? `；${aside}` : ''}`,
+                ignored,
+                removed,
+            });
         }
         else {
-            // 插件被禁用时这里也会走到，但「不存在」会把用户引向错误方向——区分「禁用」与「真不存在」并给出下一步。
-            try {
-                const disabled = hostConfig().isPluginDisabled(pluginName);
-                if (disabled) {
-                    res.status(409).json({ error: `插件 ${pluginName} 已禁用，配置未写入——先启用插件再修改配置` });
-                }
-                else {
-                    res.status(404).json({ error: `插件 ${pluginName} 不存在` });
-                }
-            }
-            catch (err) {
-                res.status(400).json({ error: errorMessage(err) });
-            }
+            res.status(404).json({ error: `插件 ${pluginName} 不存在` });
         }
     });
     // 启用插件
     expressApp.post('/api/plugins/:name/enable', gate(), async (req, res) => {
         const pluginName = req.params.name;
-        const app = getApp();
         const pm = getPluginMgr();
-        if (!app || !pm) {
-            res.status(500).json({ error: 'App 不可用' });
+        if (!pm) {
+            res.status(500).json({ error: '插件管理服务不可用' });
             return;
         }
+        const doc = docOr503(res);
+        if (!doc)
+            return;
         let success;
         try {
             success = await pm.enable(pluginName);
@@ -311,8 +437,20 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             return;
         }
         if (success) {
-            await app.saveConfig();
-            res.json({ ok: true, message: `插件 ${pluginName} 已启用` });
+            doc.setPluginEnabled(pluginName, true);
+            // 激活失败、转为 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: `${failure}；配置文件已记为启用` });
+                return;
+            }
+            res.json({ ok: true, message: `插件 ${pluginName} 已启用${aside ? `；${aside}` : ''}` });
         }
         else {
             res.status(404).json({ error: `插件 ${pluginName} 不存在` });
@@ -321,12 +459,14 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
     // 禁用插件
     expressApp.post('/api/plugins/:name/disable', gate(), async (req, res) => {
         const pluginName = req.params.name;
-        const app = getApp();
         const pm = getPluginMgr();
-        if (!app || !pm) {
-            res.status(500).json({ error: 'App 不可用' });
+        if (!pm) {
+            res.status(500).json({ error: '插件管理服务不可用' });
             return;
         }
+        const doc = docOr503(res);
+        if (!doc)
+            return;
         let success;
         try {
             success = await pm.disable(pluginName);
@@ -336,23 +476,32 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             return;
         }
         if (success) {
-            await app.saveConfig();
+            // 仍在初始化、不响应 abort 的插件，宽限到期转 error 而非 disabled：照样记为禁用（重启时不再激活），但按实际状态回报
+            const stuck = pm.getPlugin(pluginName)?.state === 'error'
+                ? `插件 ${pluginName} 未在宽限内停止，已转为 error 态，详见日志`
+                : 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} 已禁用` });
         }
         else {
             res.status(404).json({ error: `插件 ${pluginName} 不在注册表或已处于终态，无法禁用` });
         }
     });
-    // 重新扫描 packages/ 并加载新插件
+    // 经宿主 plugin-source 重新扫描并加载新插件
     expressApp.post('/api/plugins/scan', gate(), async (_req, res) => {
-        const app = getApp();
-        const pm = getPluginMgr();
-        if (!app || !pm) {
-            res.status(500).json({ error: 'App 不可用' });
+        const source = caps.source.current;
+        if (!source) {
+            res.status(503).json({ error: '宿主未提供插件来源，无法扫描' });
             return;
         }
         try {
-            const loaded = await app.rescanPlugins();
+            const loaded = await source.rescan();
             res.json({ ok: true, loaded, message: loaded.length > 0 ? `新加载 ${loaded.length} 个插件` : '无新插件' });
         }
         catch (err) {
@@ -373,12 +522,14 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             res.status(400).json({ error: 'suffix 只能包含字母、数字、下划线和连字符' });
             return;
         }
-        const app = getApp();
         const pm = getPluginMgr();
-        if (!app || !pm) {
-            res.status(500).json({ error: 'App 不可用' });
+        if (!pm) {
+            res.status(500).json({ error: '插件管理服务不可用' });
             return;
         }
+        const doc = docOr503(res);
+        if (!doc)
+            return;
         // 实例创建编排（配置文件编排属管理面,内核只出 register 机制）：
         // 查同名 module → reusable/查重校验 → 合并默认配置写入 → register 激活。
         const sourceModule = pm
@@ -399,58 +550,99 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             return;
         }
         const mergedConfig = { ...defaultsFrom(sourceModule.configSchema), ...config };
+        let registered;
         try {
-            hostConfig().setPluginConfig(instanceId, mergedConfig);
-            await pm.register(sourceModule, mergedConfig, instanceId);
+            doc.setPluginConfig(instanceId, mergedConfig);
+            // 文档里残留的禁用标记（手改配置文件留下的）照旧生效：以禁用态登记
+            registered = await pm.register(sourceModule, mergedConfig, instanceId, {
+                disabled: doc.isPluginDisabled(instanceId),
+            });
         }
         catch (err) {
             res.status(400).json({ error: errorMessage(err) });
             return;
         }
-        await app.saveConfig();
-        res.json({ ok: true, instanceId, message: `已创建实例 ${instanceId}` });
+        if (!registered) {
+            // 前面已查过重名与 reusable，走到这里的实际只有停机进行中：配置不落盘，免得下次启动按文件登记
+            doc.removePluginConfig(instanceId);
+            res.status(409).json({ error: `实例 ${instanceId} 未登记（停机中或被拒，见日志），配置未写入` });
+            return;
+        }
+        // 激活失败、转为 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}；配置已写入配置文件` });
+            return;
+        }
+        res.json({ ok: true, instanceId, message: `已创建实例 ${instanceId}${aside ? `；${aside}` : ''}` });
     });
     // 删除插件多实例
     expressApp.delete('/api/plugins/:instanceId/instance', gate(), async (req, res) => {
         const instanceId = req.params.instanceId;
-        const app = getApp();
         const pm = getPluginMgr();
-        if (!app || !pm) {
-            res.status(500).json({ error: 'App 不可用' });
+        if (!pm) {
+            res.status(500).json({ error: '插件管理服务不可用' });
             return;
         }
-        // 实例删除编排：主实例保护 → unload（内部含级联重算）→ 移除配置条目。
+        const doc = docOr503(res);
+        if (!doc)
+            return;
+        // 实例删除编排：主实例保护 → 移除配置条目与禁用标记（同名重建时不再以禁用态登记）并落盘 → 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 doc.save();
+        }
+        catch (err) {
+            // 没写进文件就不卸载，并撤回文档里的改动，免得下一次任意保存把这次没删成的删除写进文件
+            if (previous)
+                doc.setPluginConfig(instanceId, previous);
+            doc.setPluginEnabled(instanceId, !wasDisabled);
+            res
+                .status(isConfigSaveRefused(err) ? 409 : 500)
+                .json({ error: `未删除实例 ${instanceId}：未写入配置文件（${errorMessage(err)}）` });
+            return;
+        }
         try {
             await pm.unload(instanceId);
-            hostConfig().removePluginConfig(instanceId);
         }
         catch (err) {
-            res.status(400).json({ error: errorMessage(err) });
+            res.status(500).json({
+                error: `已从配置文件删除实例 ${instanceId}，但卸载失败（${errorMessage(err)}）；重启后不再登记`,
+            });
             return;
         }
-        await app.saveConfig();
         res.json({ ok: true, message: `已删除实例 ${instanceId}` });
     });
-    // 保存配置到磁盘
+    // 保存配置文档：与其它落盘路由同一口径，宿主拒写回 409、其它失败回 500。宿主不持久化时 save 不写盘，
+    // 回执因此只说「已保存」，不说保存到磁盘
     expressApp.post('/api/config/save', gate(), async (_req, res) => {
-        const app = getApp();
-        const pm = getPluginMgr();
-        if (!app || !pm) {
-            res.status(500).json({ error: 'App 不可用' });
+        const doc = docOr503(res);
+        if (!doc)
             return;
-        }
         try {
-            await app.saveConfig();
-            res.json({ ok: true, message: '配置已保存到磁盘' });
+            await doc.save();
+            res.json({ ok: true, message: '配置已保存' });
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            res.status(500).json({ error: msg });
+            res.status(isConfigSaveRefused(err) ? 409 : 500).json({ error: errorMessage(err) });
         }
     });
 }