@aalis/plugin-webui-server 0.14.1 → 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, deepMergeDefaults, defaultsFrom, parseConfig, 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,13 +71,21 @@ 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；
@@ -71,16 +100,21 @@ function refuse(pm, res, instanceId, action) {
     }
 }
 /** 注册插件管理 + 全局配置相关 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 的顶层键视为删除，
@@ -117,165 +151,110 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         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;
+            // 线上格式照旧给 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 补齐给前端。
-                // 配置按原值给出：前端据它建编辑草稿、整份保存，secret 字段只在显示时遮蔽
+                // （getStatus 只含内核事实）：从配置文档与 entry.definition 补齐给前端。
+                // 配置给文档形态：密钥字段上是引用，不是原值；前端据它建编辑草稿，引用原样发回即保持原值。
+                // 宿主不提供配置文档时给运行态，去掉密钥字段（运行态里是原值）
                 extends: entry?.definition?.extends,
-                config: entry?.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();
         const defaultOf = (k) => CORE_CONFIG_SCHEMA[k]?.default;
-        // 文档里没写的核心键按 schema 默认值比较：内置前端把默认值回填进草稿后整份回传，不能据此判成改动（否则只改
-        // 名字也会把默认值写进文件并触发重启）
+        // 文档里没写的核心键按 schema 默认值比较：回传的默认值不算改动，不写进文件
         const currentOf = (k) => current[k] ?? defaultOf(k);
-        const differs = (k) => !isDeepStrictEqual(updates[k], currentOf(k));
-        // 核心键提交 null 表示清空（前端清空数字框时发 null）：回到默认值，并从文档里删掉这个键，不把默认值写死进文件
+        // 核心键提交 null 表示清空（恢复默认）：回到默认值，并从文档里删掉这个键，不把默认值写死进文件
         const submittedOf = (k) => (updates[k] === null ? defaultOf(k) : updates[k]);
-        const ignored = Object.keys(updates).filter(k => k !== '_schema' && !allowed.includes(k) && differs(k));
         const changed = allowed.filter(k => k in updates && !isDeepStrictEqual(submittedOf(k), currentOf(k)));
         // 与插件配置路径同一把尺子：类型不符、越界或不在选项里的值（如 logLevel 传 nope）不落盘。
         const picked = Object.fromEntries(changed.map(k => [k, submittedOf(k)]));
@@ -291,16 +270,12 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         // 提交 null 的键置为 undefined，写文件时省略
         for (const key of changed)
             doc.set(key, updates[key] === null ? undefined : values[key]);
-        // logLevel 与 slowThresholdMs 只在启动时读取，改了才重启；name 由 /api/status 每次实时读文档（appName），保存即生效。
-        // 装有人设时聊天显示人设名，应用名称只在仪表盘上看得到
-        const restartNeeded = changed.some(k => k === 'logLevel' || k === 'slowThresholdMs');
-        const note = ignored.length > 0 ? `（已忽略不可修改的字段: ${ignored.join(', ')}）` : '';
+        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
@@ -308,47 +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 });
-            return;
-        }
-        res.json({ ok: true, message: `全局配置已更新，正在重启应用以生效…${note}`, restart: true, ignored });
-    });
-    // 获取单个插件在配置文档里的配置
-    expressApp.get('/api/plugins/:name/config', gate(), (req, res) => {
-        const pluginName = req.params.name;
-        const doc = docOr503(res);
-        if (!doc)
+            res.status(500).json({ error: reason });
             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' || 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;
@@ -356,11 +324,12 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
         const doc = docOr503(res);
         if (!doc)
             return;
-        // 合进原配置再交给 updateConfig：后者是**整体替换**语义（core 的 orchestration/plugin.ts 里
+        // 合进原配置再交给宿主的 applyPluginConfig：配置是**整体替换**语义（core 的 orchestration/plugin.ts 里
         // entry.config = newConfig 直接顶掉）。基线取配置文档里的原配置而非裸默认值：defaultsFrom 只收录声明了
-        // default 的键，而 apiKey / accessToken 这类 secret 多数**没有** default（deepseek、embedding-openai、
-        // llm-openai、serper、onebot 皆是），以裸默认值打底时请求里没带 apiKey，整体替换后用户的密钥就从内存态与
-        // yaml 一起消失。叠上原配置后语义才是真正的部分更新：没提交的字段保持原样，要清空得显式提交。
+        // default 的键，而 apiKey / accessToken 这类 secret 多数**没有** default，以裸默认值打底时请求里没带 apiKey，
+        // 整体替换后用户的密钥就从内存态与 yaml 一起消失。叠上原配置后语义才是真正的部分更新：没提交的字段保持原样，
+        // 要清空得显式提交。
+        // 原配置是文档形态，密钥字段上是引用；前端原样发回引用即保持原值，发明文即替换（由宿主拆进密钥存储）。
         const entry = pm.getPlugin(pluginName);
         const schema = entry?.definition?.configSchema;
         let docConfig;
@@ -377,11 +346,16 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             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（没配全）也放行：半成品配置是启用插件配到一半的
         // 正常中间态。
         // 存量按「去掉下标的路径 + 原因」计数，新配置里同类问题的条数超出存量才算新增：list / multiselect /
@@ -407,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 {
-            refuse(pm, res, 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;
@@ -472,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 {
             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;
@@ -510,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 {
             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} 个插件` : '无新插件' });
@@ -544,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 ?? {};
@@ -560,7 +573,7 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             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;
@@ -570,10 +583,13 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             return;
         // 实例创建编排（配置文件编排属管理面,内核只出 register 机制）：
         // 查同名 module → reusable/查重校验 → 合并默认配置、裁剪与校验 → 写入 → register 激活。
-        const sourceModule = pm
-            .getStatus()
-            .map(p => pm.getPlugin(p.instanceId)?.definition)
-            .find(m => m?.name === moduleName);
+        // 模块定义主实例优先、否则取任一在册实例的，与宿主登记新实例时取定义的规则一致：合并、裁剪与校验所用的 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;
@@ -600,44 +616,46 @@ export function registerPluginRoutes(expressApp, caps, identify, gate, getAction
             return;
         }
         const note = ignored.length > 0 ? `（已忽略未声明的配置字段: ${ignored.join(', ')}）` : '';
-        let registered;
+        // 宿主先写文档再登记（文档里残留的禁用标记照旧生效，以禁用态登记），没登记上时撤回文档与密钥
+        let result;
         try {
-            doc.setPluginConfig(instanceId, mergedConfig);
-            // 文档里残留的禁用标记（手改配置文件留下的）照旧生效：以禁用态登记
-            registered = await pm.register(sourceModule, mergedConfig, instanceId, {
-                disabled: doc.isPluginDisabled(instanceId),
-            });
+            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}；配置已写入配置文件${note}` });
-            return;
-        }
-        res.json({ ok: true, instanceId, message: `已创建实例 ${instanceId}${note}${aside ? `；${aside}` : ''}`, ignored });
+            : 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;
@@ -670,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({
@@ -679,21 +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}` });
     });
 }
 //# sourceMappingURL=plugins.js.map