@aalis/plugin-webui-server 0.11.11 → 0.13.0

package/dist/routes/plugins.js

@@ -1,8 +1,55 @@
 import { isDeepStrictEqual } from 'node:util';
+import { isConfigSaveRefused } from '@aalis/api-host-config';
 import { parseInstanceId } from '@aalis/core';
-import { CORE_CONFIG_SCHEMA, defaultsFrom, validateConfig } from '@aalis/schema-config';
+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，文件没变也不会触发重载，改动留在文档里，下一次成功保存时一并写入。
+ */
+export async function saveAfterApply(doc, res, reconcile) {
+    try {
+        await doc.save();
+        return true;
+    }
+    catch (err) {
+        if (isConfigSaveRefused(err)) {
+            res.status(409).json({
+                error: `已在运行态生效，但未写入配置文件（${errorMessage(err)}）；${RECONCILE[reconcile]}`,
+                applied: true,
+            });
+        }
+        else {
+            res.status(500).json({
+                error: `已在运行态生效，但写入配置文件失败（${errorMessage(err)}）；改动保留在文档里，下次保存成功时一并写入`,
+                applied: true,
+            });
+        }
+        return false;
+    }
+}
 /** 注册插件管理 + 全局配置相关 REST 路由 */
-export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, identify, gate) {
+export function registerPluginRoutes(expressApp, caps, identify, gate, getAction) {
+    const getApp = () => caps.app.current;
+    const getPluginMgr = () => caps.plugins.current;
+    /** 配置文档由宿主提供；没有时读写文档的路由一律 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();
@@ -11,8 +58,9 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             res.json({ plugins: [] });
             return;
         }
-        // 反向索引：pluginName -> tools / commands（名字列表 + 聚合敏感能力）。
-        // 方便 UI 搜索框命中工具名/指令名时定位到注册插件；能力披露用聚合 capability。
+        // 反向索引：instanceId -> tools / commands（名字列表 + 聚合敏感能力）。
+        // 生产登记的 pluginName 就是 contextId（= instanceId）；按 definition.name 索引
+        // 会让 name:suffix 误挂主实例的工具。能力披露用聚合 capability。
         const toolsByPlugin = new Map();
         const capsByPlugin = new Map();
         const addCaps = (plugin, visibility) => {
@@ -22,7 +70,7 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             set.add('visibility:restricted');
             capsByPlugin.set(plugin, set);
         };
-        const tools = ctx.getService('tools')?.getAll() ?? [];
+        const tools = caps.tools.current?.getAll() ?? [];
         for (const t of tools) {
             const list = toolsByPlugin.get(t.pluginName) ?? [];
             list.push(t.name);
@@ -30,7 +78,7 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             addCaps(t.pluginName, t.visibility);
         }
         const commandsByPlugin = new Map();
-        const cmds = ctx.getService('commands')?.getAll() ?? [];
+        const cmds = caps.commands.current?.getAll() ?? [];
         for (const c of cmds) {
             const owner = c.pluginName ?? 'unknown';
             const list = commandsByPlugin.get(owner) ?? [];
@@ -38,31 +86,38 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             commandsByPlugin.set(owner, list);
             addCaps(owner, c.visibility);
         }
-        const plugins = pm.getStatus().map(p => ({
-            name: p.name,
-            instanceId: p.instanceId,
-            displayName: p.displayName,
-            state: p.state,
-            provides: p.provides ?? [],
-            // 能力披露：该插件「要调用哪些子系统」（inject 依赖）+「是否含 restricted 工具/指令」，供安装后知情查看。
-            requiredServices: p.requiredServices ?? [],
-            optionalServices: p.optionalServices ?? [],
-            capabilities: [...(capsByPlugin.get(p.name) ?? [])],
-            tools: toolsByPlugin.get(p.name) ?? [],
-            commands: commandsByPlugin.get(p.name) ?? [],
-            core: p.core ?? false,
-            reusable: p.reusable ?? false,
-            // extends / config / configSchema / defaultConfig 非内核状态摘要字段
-            // （getStatus 只含内核事实）：从 entry.config / entry.module 补齐给前端。
-            extends: pm.getPlugin(p.instanceId)?.module?.extends,
-            config: pm.getPlugin(p.instanceId)?.config ?? {},
-            configSchema: pm.getPlugin(p.instanceId)?.module?.configSchema,
-            defaultConfig: defaultsFrom(pm.getPlugin(p.instanceId)?.module?.configSchema),
-            error: p.error,
-        }));
+        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,
+                displayName: p.displayName,
+                state: p.state,
+                slow: p.slow,
+                provides: p.provides ?? [],
+                // 完整能力声明含内置能力与 apply 别名；外部依赖闸与工具/指令可见性仍是各自独立的事实。
+                uses: p.uses,
+                requiredServices: p.requiredServices ?? [],
+                optionalServices: p.optionalServices ?? [],
+                capabilities: [...(capsByPlugin.get(p.instanceId) ?? [])],
+                tools: toolsByPlugin.get(p.instanceId) ?? [],
+                commands: commandsByPlugin.get(p.instanceId) ?? [],
+                reusable: p.reusable ?? false,
+                // extends / config / configSchema / defaultConfig 非内核状态摘要字段
+                // （getStatus 只含内核事实）：从 entry.config / entry.definition 补齐给前端。
+                extends: entry?.definition?.extends,
+                config,
+                configSchema: entry?.definition?.configSchema,
+                defaultConfig: defaultsFrom(entry?.definition?.configSchema),
+                error: p.error,
+            };
+        });
         res.json({ plugins });
     });
-    // 获取可用的 WebUI 页面（由活跃插件通过 useWebuiService.registerPage 注册）
+    // 获取可用的 WebUI 页面（由活跃插件经 webui-server 的绑定接口 registerPage 登记）
     expressApp.get('/api/pages', gate(), (_req, res) => {
         const app = getApp();
         const pm = getPluginMgr();
@@ -70,14 +125,14 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             res.json([]);
             return;
         }
-        const webuiSvc = ctx.getService('webui-server');
+        const webuiSvc = caps.webui();
         if (!webuiSvc) {
             res.json([]);
             return;
         }
         const displayNameByPlugin = new Map();
         for (const p of pm.getStatus())
-            displayNameByPlugin.set(p.name, p.displayName);
+            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) });
@@ -85,7 +140,7 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
         pages.sort((a, b) => (a.order ?? 99) - (b.order ?? 99));
         res.json(pages);
     });
-    // 通用声明式页面操作：调用插件的 actions
+    // 通用声明式页面操作：调用插件经 webuiServer.registerAction 登记的处理函数
     expressApp.post('/api/page-action/:plugin/:method', async (req, res) => {
         const { plugin: pluginName, method } = req.params;
         const args = req.body ?? {};
@@ -100,15 +155,11 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             res.status(404).json({ error: `插件 ${pluginName} 不存在或未激活` });
             return;
         }
-        const handler = entry.module.actions?.[method];
-        if (typeof handler !== 'function') {
+        const handler = getAction(pluginName, method);
+        if (!handler) {
             res.status(404).json({ error: `处理器 ${method} 不存在` });
             return;
         }
-        if (!entry.context) {
-            res.status(500).json({ error: `插件 ${pluginName} 上下文不可用` });
-            return;
-        }
         // ===== owner 闸 + 调用者身份（单 owner 终态）=====
         // 单 token ⟺ webui:console ⟺ owner；auth.middleware 已校 token，这里复核身份并把
         // caller 传给 action。各 action 自身对敏感操作再做 owner 自检（如 setUserTier）。
@@ -119,8 +170,7 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             return;
         }
         try {
-            const result = await handler(entry.context, args, caller);
-            res.json({ ok: true, data: result });
+            res.json({ ok: true, data: await handler(args, caller) });
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -129,8 +179,10 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
     });
     // 获取当前全局配置
     expressApp.get('/api/config', gate(), (_req, res) => {
-        const allConfig = ctx.config.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) => {
@@ -140,17 +192,22 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             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 = ctx.config.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
@@ -167,31 +224,57 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             res.status(400).json({ error: invalid.join('; ') });
             return;
         }
+        const previous = Object.fromEntries(changed.map(k => [k, current[k]]));
         for (const key of changed)
-            ctx.config.set(key, updates[key]);
-        // name / logLevel 都要重启才生效；值没变就不重启
-        const restartNeeded = changed.length > 0;
+            doc.set(key, updates[key]);
+        // logLevel 与 slowThresholdMs 只在启动时读取，改了才重启；name 由 /api/status 每次实时读文档，保存即生效
+        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 pluginConfig = ctx.config.getPluginConfig(pluginName);
-        res.json({ name: pluginName, config: pluginConfig });
+        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) });
+        }
     });
     // 更新插件配置
     expressApp.put('/api/plugins/:name/config', gate(), async (req, res) => {
@@ -201,24 +284,61 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             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)?.module?.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 一起消失。
         // 叠上已存值后语义才是真正的部分更新：没提交的字段保持原样，要清空得显式传空串。
-        const stored = { ...defaults, ...ctx.config.getPluginConfig(pluginName) };
-        const merged = { ...stored, ...newConfig };
+        let docConfig;
+        let stored;
+        let merged;
+        const ignored = [];
+        const 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(', ')}]`);
+                }
+            }
+        }
+        catch (err) {
+            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
@@ -234,34 +354,79 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             });
             return;
         }
-        const success = await pm.updateConfig(pluginName, merged);
+        // 运行态与文档都已是这份配置：不重建插件（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);
+        }
+        catch (err) {
+            res.status(400).json({ error: errorMessage(err) });
+            return;
+        }
         if (success) {
-            await app.saveConfig();
-            res.json({ ok: true, message: `插件 ${pluginName} 配置已更新` });
+            // 按新配置重新激活失败、转为 error：照样写入配置（原样再存即重试激活），但按实际状态回报
+            const after = pm.getPlugin(pluginName);
+            const failure = after?.state === 'error' ? (after.error ?? '详见日志') : undefined;
+            // 管理动作只改运行态；跨重启保留要本路由写文档并落盘
+            doc.setPluginConfig(pluginName, merged);
+            if (!(await saveAfterApply(doc, res, 'reload')))
+                return;
+            if (failure !== undefined) {
+                res.status(500).json({
+                    error: `插件 ${pluginName} 按新配置重新激活失败，已转为 error 态（${failure}）；配置已写入配置文件${note}`,
+                });
+                return;
+            }
+            res.json({ ok: true, message: `插件 ${pluginName} 配置已更新${note}`, ignored, removed });
         }
-        else {
+        else if (pm.getPlugin(pluginName)?.state === 'disabled') {
             // 插件被禁用时这里也会走到，但「不存在」会把用户引向错误方向——区分「禁用」与「真不存在」并给出下一步。
-            const disabled = ctx.config.isPluginDisabled(pluginName);
-            if (disabled) {
-                res.status(409).json({ error: `插件 ${pluginName} 已禁用，配置未写入——先启用插件再修改配置` });
-            }
-            else {
-                res.status(404).json({ error: `插件 ${pluginName} 不存在` });
-            }
+            res.status(409).json({ error: `插件 ${pluginName} 已禁用，配置未写入——先启用插件再修改配置` });
+        }
+        else {
+            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);
+        }
+        catch (err) {
+            res.status(400).json({ error: errorMessage(err) });
             return;
         }
-        const success = await pm.enable(pluginName);
         if (success) {
-            await app.saveConfig();
+            // 激活失败、转为 error：照样记为启用（重启时再激活），但按实际状态回报
+            const after = pm.getPlugin(pluginName);
+            const failure = after?.state === 'error' ? (after.error ?? '详见日志') : undefined;
+            doc.setPluginEnabled(pluginName, true);
+            if (!(await saveAfterApply(doc, res, 'restart')))
+                return;
+            if (failure !== undefined) {
+                res
+                    .status(500)
+                    .json({ error: `插件 ${pluginName} 激活失败，已转为 error 态（${failure}）；配置文件已记为启用` });
+                return;
+            }
             res.json({ ok: true, message: `插件 ${pluginName} 已启用` });
         }
         else {
@@ -271,31 +436,49 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
     // 禁用插件
     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);
+        }
+        catch (err) {
+            res.status(400).json({ error: errorMessage(err) });
             return;
         }
-        const success = await pm.disable(pluginName);
         if (success) {
-            await app.saveConfig();
+            // 仍在初始化、不响应 abort 的插件，宽限到期转 error 而非 disabled：照样记为禁用（重启时不再激活），但按实际状态回报
+            const stuck = pm.getPlugin(pluginName)?.state === 'error';
+            doc.setPluginEnabled(pluginName, false);
+            if (!(await saveAfterApply(doc, res, 'restart')))
+                return;
+            if (stuck) {
+                res
+                    .status(500)
+                    .json({ error: `插件 ${pluginName} 未在宽限内停止，已转为 error 态，详见日志；配置文件已记为禁用` });
+                return;
+            }
             res.json({ ok: true, message: `插件 ${pluginName} 已禁用` });
         }
         else {
-            res.status(400).json({ error: `核心插件不能被禁用` });
+            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) {
@@ -316,17 +499,19 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             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
             .getStatus()
-            .map(p => pm.getPlugin(p.instanceId)?.module)
+            .map(p => pm.getPlugin(p.instanceId)?.definition)
             .find(m => m?.name === moduleName);
         if (!sourceModule) {
             res.status(400).json({ error: `无法创建实例：模块 "${moduleName}" 未找到` });
@@ -342,47 +527,108 @@ export function registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, iden
             return;
         }
         const mergedConfig = { ...defaultsFrom(sourceModule.configSchema), ...config };
-        ctx.config.setPluginConfig(instanceId, mergedConfig);
-        await pm.register(sourceModule, mergedConfig, instanceId);
-        await app.saveConfig();
+        let registered;
+        try {
+            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;
+        }
+        if (!registered) {
+            // 前面已查过重名与 reusable，走到这里的实际只有停机进行中：配置不落盘，免得下次启动按文件登记
+            doc.removePluginConfig(instanceId);
+            res.status(409).json({ error: `实例 ${instanceId} 未登记（停机中或被拒，见日志），配置未写入` });
+            return;
+        }
+        if (!(await saveAfterApply(doc, res, 'reload')))
+            return;
         res.json({ ok: true, instanceId, message: `已创建实例 ${instanceId}` });
     });
     // 删除插件多实例
     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;
         }
-        await pm.unload(instanceId);
-        ctx.config.removePluginConfig(instanceId);
-        await app.saveConfig();
+        try {
+            await pm.unload(instanceId);
+            doc.removePluginConfig(instanceId);
+            doc.setPluginEnabled(instanceId, true);
+        }
+        catch (err) {
+            res.status(400).json({ error: errorMessage(err) });
+            return;
+        }
+        if (!(await saveAfterApply(doc, res, 'restart')))
+            return;
         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) });
         }
     });
 }
+/** 列表 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