@aalis/plugin-webui-server 0.11.11 → 0.13.0

package/dist/index.js

@@ -6,12 +6,22 @@ import { createServer } from 'node:http';
 import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { listLLMModels } from '@aalis/api-llm';
-import { aggregatePlatformDetails, getPlatformAdapters, getPlatformNames, } from '@aalis/api-platform';
-import { createProcessGateway } from '@aalis/api-process';
-import { createStorageGateway, readTailLines } from '@aalis/api-storage';
-import { DEFAULT_SUBSYSTEM_METADATA } from '@aalis/api-webui';
-import { LogHub, parseLogLine } from '@aalis/core';
+import { agent } from '@aalis/api-agent';
+import { authority } from '@aalis/api-authority';
+import { commands } from '@aalis/api-commands';
+import { hostConfig } from '@aalis/api-host-config';
+import { listLLMModels, llm } from '@aalis/api-llm';
+import { packageManager } from '@aalis/api-package-manager';
+import { persona } from '@aalis/api-persona';
+import { aggregatePlatformDetails, getPlatformAdapters, getPlatformNames, platform, } from '@aalis/api-platform';
+import { pluginSource } from '@aalis/api-plugin-source';
+import { createProcessGateway, processService } from '@aalis/api-process';
+import { sessionConfirm } from '@aalis/api-session-confirm';
+import { createStorageGateway, readTailLines, storage } from '@aalis/api-storage';
+import { tools } from '@aalis/api-tools';
+import { DEFAULT_SUBSYSTEM_METADATA, webuiClient, webuiServer } from '@aalis/api-webui';
+import { appService, config, definePlugin, events, LogHub, lifecycle, logger, optional, pluginsService, provide, services, } from '@aalis/core';
+import { parseLogLine } from '@aalis/schema-log';
 import express from 'express';
 import { WebSocket, WebSocketServer } from 'ws';
 import { createAuthSystem, openBrowser } from './auth.js';
@@ -20,7 +30,7 @@ import { renderClientSwitchPage } from './client-switch-page.js';
 import { createRouteGate } from './gate.js';
 import { registerFileRoutes } from './routes/files.js';
 import { registerMarketplaceRoutes } from './routes/marketplace.js';
-import { registerPluginRoutes } from './routes/plugins.js';
+import { registerPluginRoutes, saveAfterApply } from './routes/plugins.js';
 import { registerProxyRoutes } from './routes/proxy.js';
 import { registerUploadedFilesRoutes } from './routes/uploaded-files.js';
 import { createWsHeartbeat } from './ws-heartbeat.js';
@@ -35,17 +45,7 @@ function descSummary(d) {
     return s.length > 200 ? `${s.slice(0, 200)}…` : s;
 }
 // ===== 插件元数据 =====
-export const name = '@aalis/plugin-webui-server';
-export const displayName = 'WebUI 服务端';
-export const subsystem = 'platform';
-export const provides = ['webui-server', 'platform'];
-export const inject = {
-    // storage 改为 optional：避免 plugin-storage-local bounce 时级联重启 webui-server
-    // （若 required，存储服务暂时消失会让 webui-server 进入 pending，导致 registeredPages
-    // 被清空，其他插件的 sidebar 页面在 webui-server 重新激活后无法恢复）。
-    // storage gateway 的各操作已有 try-catch，暂时不可用时仅个别文件操作失败，不影响主功能。
-    optional: ['storage', 'authority', 'commands', 'platform', 'process', 'session-confirm'],
-};
+const name = '@aalis/plugin-webui-server';
 const webuiPages = [
     { key: 'dashboard', label: '仪表盘', icon: 'dashboard', order: 10, renderer: 'dashboard' },
     { key: 'marketplace', label: '插件市场', icon: 'marketplace', order: 20, renderer: 'marketplace' },
@@ -54,7 +54,7 @@ const webuiPages = [
     { key: 'files', label: '文件管理', icon: 'files', order: 50, renderer: 'files' },
     { key: 'logs', label: '日志', icon: 'logs', order: 60, renderer: 'logs' },
 ];
-export const configSchema = {
+const configSchema = {
     port: { type: 'number', label: '端口', default: 3000, description: 'Web 管理界面的 HTTP 端口' },
     host: { type: 'string', label: '监听地址', default: '127.0.0.1', description: '绑定的 IP 地址，0.0.0.0 可对外访问' },
     fileRoot: {
@@ -96,7 +96,7 @@ export const configSchema = {
         type: 'string',
         label: '插件市场 npm 源',
         default: 'https://registry.npmjs.org',
-        description: '插件市场检索用的 npm registry 基址。注意 npm 的 search API 并非所有镜像都支持（淘宝等国内源不支持），默认官方源；国内可填支持 search 的镜像或代理。安装走 package-manager（遵循本机 npm 配置）。',
+        description: '插件市场检索用的 npm registry 基址。注意 npm 的 search API 并非所有镜像都支持（淘宝等国内源不支持），默认官方源；国内可填支持 search 的镜像或代理。安装走 package-manager（遵循本机 npm 配置），卡片上的最新版与可更新也按安装使用的源查。',
     },
     // 活跃前端不在此配置：前端即 `webui-client` 服务的多 provider，活跃者由「服务偏好」
     // （servicePreferences['webui-client']）决定——在 WebUI「服务」页的下拉框切换。
@@ -104,9 +104,8 @@ export const configSchema = {
 // ===== WebSocket 消息协议 =====
 // 入站消息类型 + 校验 schema 见 ./protocol.ts（zod 强校验）
 import { WSIncomingSchema } from './protocol.js';
-export { WSIncomingSchema } from './protocol.js';
 // ===== 日志文件读取（与 @aalis/runtime 的 file-logger 格式对偶）=====
-// 行格式契约（format ↔ parse）由 @aalis/core 的 parseLogLine 唯一持有，此处只负责
+// 行格式契约（format ↔ parse）由 @aalis/schema-log 的 parseLogLine 唯一持有，此处只负责
 // 读取「持久化日志单一数据源」并按 cursor 尾读分页。
 //
 // 路径（宿主目录布局）是「环境知识」，归 storage 的 logs 根所有；本插件只用 storage
@@ -152,7 +151,7 @@ const LOCAL_SCAN_DIRS = [resolve(process.cwd(), 'packages'), resolve(process.cwd
  * 快照算进错的上下文窗口。前缀不认识时才落回 `'webui'`——CLI 的 `cli-default` 这类不带
  * 前缀的会话，以及 webui 自己的会话，都归在这一档。
  *
- * 纯函数：平台名集合由调用方从 `getPlatformNames(ctx)` 取（adapter 可热插拔，每次现取）。
+ * 纯函数：平台名集合由调用方从 `getPlatformNames(platform)` 取（adapter 可热插拔，每次现取）。
  */
 export function resolveSessionPlatform(sessionId, known) {
     const idx = sessionId.indexOf(':');
@@ -161,7 +160,45 @@ export function resolveSessionPlatform(sessionId, known) {
     const prefix = sessionId.slice(0, idx);
     return known.has(prefix) ? prefix : 'webui';
 }
-export async function apply(ctx, config) {
+// storage 等一律 optional：webui 是管理面，任何被管对象缺席都只该让对应页面降级，不该把
+// 整个控制台拖进 pending。storage 尤其不能 required——plugin-storage-local bounce 会让它
+// 暂时消失，webui-server 跟着重启就清空 registeredPages，其他插件的侧边栏页面再也回不来。
+const uses = {
+    events,
+    logger,
+    lifecycle,
+    config,
+    provide,
+    services,
+    hostConfig: optional(hostConfig),
+    app: optional(appService),
+    plugins: optional(pluginsService),
+    source: optional(pluginSource),
+    packageManager: optional(packageManager),
+    storage: optional(storage),
+    authority: optional(authority),
+    commands: optional(commands),
+    // platform 既被本插件提供又被平台页枚举：required 会让激活等一个由自己提供的服务
+    platform: optional(platform),
+    process: optional(processService),
+    sessionConfirm: optional(sessionConfirm),
+    tools: optional(tools),
+    llm: optional(llm),
+    persona: optional(persona),
+    agent: optional(agent),
+};
+export default definePlugin({
+    name,
+    displayName: 'WebUI 服务端',
+    subsystem: 'platform',
+    configSchema,
+    provides: [webuiServer, platform],
+    uses,
+    apply: startWebuiServer,
+});
+async function startWebuiServer(caps) {
+    const { events, logger, lifecycle, provide, services } = caps;
+    const config = caps.config;
     const uiConfig = {
         port: config.port ?? 3000,
         host: config.host ?? '127.0.0.1',
@@ -171,14 +208,10 @@ export async function apply(ctx, config) {
             ? config.tokenMode
             : 'persist',
         fixedToken: config.fixedToken ?? '',
-        relationGraphDefaultSpacing: (() => {
-            const v = Number(config.relationGraphDefaultSpacing);
-            return Number.isFinite(v) && v > 0 ? v : 120;
-        })(),
         marketplaceRegistry: config.marketplaceRegistry?.trim() || 'https://registry.npmjs.org',
     };
     // 创建 storage gateway；所有文件读写（token、access、文件管理）都走这里
-    const storage = createStorageGateway(ctx);
+    const storage = createStorageGateway(caps.storage);
     // ---- Token 解析 ----
     // - ephemeral：每次启动随机生成（旧行为）
     // - persist：首次生成后写入 storage data:/webui/token，重启复用（默认）
@@ -186,32 +219,10 @@ export async function apply(ctx, config) {
     // 所有模式都会写出 data:/webui/access.txt 便于查找访问 URL
     const tokenFileUri = 'data:/webui/token';
     const accessFileUri = 'data:/webui/access.txt';
-    async function resolveAuthToken() {
-        if (uiConfig.tokenMode === 'fixed' && uiConfig.fixedToken.trim()) {
-            return uiConfig.fixedToken.trim();
-        }
-        if (uiConfig.tokenMode === 'persist' || uiConfig.tokenMode === 'fixed') {
-            try {
-                const raw = await storage.readFile(tokenFileUri, 'utf-8');
-                const existing = (typeof raw === 'string' ? raw : raw.toString('utf-8')).trim();
-                if (existing)
-                    return existing;
-            }
-            catch {
-                /* not exists or unreadable */
-            }
-            const fresh = Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString('hex');
-            try {
-                await storage.writeFile(tokenFileUri, fresh);
-            }
-            catch (err) {
-                ctx.logger.warn(`持久化 token 失败，本次仍可使用但重启会再生成: ${err.message}`);
-            }
-            return fresh;
-        }
-        // ephemeral
-        return Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString('hex');
-    }
+    const fixedToken = uiConfig.tokenMode === 'fixed' ? uiConfig.fixedToken.trim() : '';
+    let authToken = fixedToken || Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString('hex');
+    /** 监听成功后的访问 URL；持久化 token 晚于监听读回时，据此重写 access.txt */
+    let listeningUrl;
     /** 返回是否真的写成了：调用方据此决定能不能宣称「凭据已写入」 */
     async function writeAccessFile(url, token) {
         const lines = [
@@ -230,12 +241,50 @@ export async function apply(ctx, config) {
             return true;
         }
         catch (err) {
-            ctx.logger.warn(`写入访问文件失败: ${err.message}`);
+            logger.warn(`写入访问文件失败: ${err.message}`);
             return false;
         }
     }
-    const authToken = await resolveAuthToken();
-    const auth = createAuthSystem(authToken, ctx.logger.child('auth'));
+    // persist 的读回跟随 storage：storage 是 optional、不参与激活拓扑，可能晚于本插件上线
+    // （加载顺序、启动时配置出错后修好、运行时才启用）。只在 apply 里读一次会读空：内存里是新随机
+    // token，持久化的那份不生效，已登录的浏览器全部被登出；没有 token 文件时也永远建不起来。
+    // follow 对已在线的 storage 同步首挂，晚上线时补读。持久化的那份优先（浏览器里 30 天的 cookie
+    // 就是它）；只认第一次成功，之后 storage 换人不再换 token。
+    let tokenSettled = uiConfig.tokenMode === 'ephemeral' || fixedToken !== '';
+    let tokenLoading;
+    caps.storage.follow(() => {
+        if (tokenSettled)
+            return;
+        tokenLoading = (async () => {
+            try {
+                const raw = await storage.readFile(tokenFileUri, 'utf-8');
+                const existing = (typeof raw === 'string' ? raw : raw.toString('utf-8')).trim();
+                if (existing) {
+                    tokenSettled = true;
+                    if (existing !== authToken) {
+                        authToken = existing;
+                        if (listeningUrl)
+                            void writeAccessFile(listeningUrl, authToken);
+                    }
+                    return;
+                }
+            }
+            catch {
+                /* 不存在或读不了 */
+            }
+            try {
+                await storage.writeFile(tokenFileUri, authToken);
+                tokenSettled = true;
+            }
+            catch (err) {
+                logger.warn(`持久化 token 失败，本次仍可使用但重启会再生成: ${err.message}`);
+            }
+        })();
+    });
+    // storage 已在线时 follow 是同步首挂：等读回完成再继续，认证从第一个请求起就用持久化的 token
+    if (tokenLoading)
+        await tokenLoading;
+    const auth = createAuthSystem(() => authToken);
     const expressApp = express();
     expressApp.use(express.json({ limit: '10mb' }));
     expressApp.use(auth.middleware);
@@ -259,8 +308,8 @@ export async function apply(ctx, config) {
     // 半开连接回收：清理只挂 'close' 时，睡眠/断网的客户端永远等不到事件，
     // 日志广播持续往死连接的发送缓冲堆数据。详见 ws-heartbeat.ts。
     const heartbeat = createWsHeartbeat({
-        onStale: ws => ctx.logger.debug(`WebUI 客户端心跳超时，回收半开连接 (bufferedAmount=${ws.bufferedAmount})`),
-        onError: (_ws, err) => ctx.logger.warn(`WebUI 客户端连接错误: ${err.message}`),
+        onStale: ws => logger.debug(`WebUI 客户端心跳超时，回收半开连接 (bufferedAmount=${ws.bufferedAmount})`),
+        onError: (_ws, err) => logger.warn(`WebUI 客户端连接错误: ${err.message}`),
     });
     const streamBuffers = new Map();
     // 延迟清理 streamBuffers：捕获要删的 buf 引用，10s 后仅当 (a) 该 session 仍是
@@ -274,9 +323,6 @@ export async function apply(ctx, config) {
     };
     // Token 用量缓存：记录每个 session 最近一次的 token 用量，用于刷新/切换会话后立即展示
     const tokenUsageCache = new Map();
-    // 获取核心服务（通过服务注册获取）
-    const getApp = () => ctx.getService('app');
-    const getPluginMgr = () => ctx.getService('plugins');
     // 前端静态文件托管：前端包不是插件（无 apply，纯静态资源），托管权在本插件——
     // app:ready 时由 client-discovery 按 `aalis.client` 标记发现候选，本插件把每个候选注册成
     // 一条 webui-client 服务 provider，再由服务解析（偏好 > 优先级 > 注册顺序）定出活跃前端。
@@ -285,11 +331,11 @@ export async function apply(ctx, config) {
     function mountStaticDir(dir) {
         if (existsSync(dir)) {
             staticMiddleware = express.static(dir);
-            ctx.logger.info(`前端静态目录: ${dir}`);
+            logger.info(`前端静态目录: ${dir}`);
         }
         else {
             staticMiddleware = null;
-            ctx.logger.warn(`前端目录不存在: ${dir}`);
+            logger.warn(`前端目录不存在: ${dir}`);
         }
     }
     // 已发现的前端候选（app:ready 时填充，逐个注册为 webui-client 服务 provider）。
@@ -304,7 +350,7 @@ export async function apply(ctx, config) {
     const clientProviderDisposers = new Map();
     /** 当前活跃前端目录 = 解析后的 webui-client 服务（servicePreferences 偏好 > 优先级 > 注册顺序）。 */
     function currentClientDir() {
-        return ctx.getService('webui-client')?.getClientDir?.();
+        return services.get(webuiClient)?.getClientDir?.();
     }
     /**
      * 切换 webui-client 服务偏好后调用：重挂当前活跃前端 + 广播 'reload'——所有客户端进入
@@ -334,21 +380,14 @@ export async function apply(ctx, config) {
     // ---------- REST API ----------
     // 获取系统状态
     expressApp.get('/api/status', gate(), (_req, res) => {
-        const persona = ctx.getService('persona');
-        // 判断上传能力
-        const hasMedia = ctx.getService('media') !== undefined;
-        const llmHasVision = listLLMModels(ctx).some(e => e.instance.capabilities.includes('vision'));
-        const hasFileReader = ctx.getService('file-reader') !== undefined;
+        const personaSvc = caps.persona.current;
+        // 判断上传能力。media / file-reader 在本插件里只做在场探测，为一个布尔值反向依赖
+        // 它们的包不值当（file-reader 还是插件包），故按名动态查——动态查到的不算声明依赖。
+        const hasMedia = services.get('media') !== undefined;
+        const llmHasVision = listLLMModels(caps.llm).some(e => e.instance.capabilities.includes('vision'));
+        const hasFileReader = services.get('file-reader') !== undefined;
         res.json({
-            name: persona?.getPersonaName() ?? ctx.config.get('name'),
-            services: {
-                'webui-server': ctx.getService('webui-server') !== undefined,
-                cli: ctx.getService('cli') !== undefined,
-                llm: ctx.getService('llm') !== undefined,
-                agent: ctx.getService('agent') !== undefined,
-                memory: ctx.getService('memory') !== undefined,
-                persona: ctx.getService('persona') !== undefined,
-            },
+            name: personaSvc?.getPersonaName() ?? caps.hostConfig.current?.get('name') ?? 'Aalis',
             /** 上传能力：客户端据此决定显示哪些上传按钮 */
             uploadCapabilities: {
                 /** 是否支持图片上传（media 可用 或 LLM 声明了 vision） */
@@ -356,14 +395,8 @@ export async function apply(ctx, config) {
                 /** 是否支持文件上传（file-reader 可用） */
                 file: hasFileReader,
             },
-            tools: ctx
-                .getService('tools')
-                ?.getAll()
-                .map(t => t.name) ?? [],
-            commands: ctx
-                .getService('commands')
-                ?.getAll()
-                .map(c => ({
+            tools: caps.tools.current?.getAll().map(t => t.name) ?? [],
+            commands: caps.commands.current?.getAll().map(c => ({
                 name: c.name,
                 description: descSummary(c.description),
                 visibility: c.visibility,
@@ -392,22 +425,29 @@ export async function apply(ctx, config) {
         },
         join: (...parts) => resolve(...parts),
     };
-    registerPluginRoutes(expressApp, ctx, getApp, getPluginMgr, auth.identify, gate);
+    // 页面动作登记表：插件经 webui-server 的绑定接口登记，路由层按「插件 id + 方法名」查
+    const registeredActions = new Map();
+    registerPluginRoutes(expressApp, {
+        app: caps.app,
+        plugins: caps.plugins,
+        source: caps.source,
+        hostConfig: caps.hostConfig,
+        tools: caps.tools,
+        commands: caps.commands,
+        webui: () => services.get(webuiServer),
+        logger,
+    }, auth.identify, gate, (plugin, method) => registeredActions.get(plugin)?.get(method));
     // 市场「已装」判定、依赖图、前端候选发现共用这一份扫描目录（pnpm 工作区下 require.resolve
     // 从仓库根解析不到工作区包，只能扫盘）。每请求懒扫，量小。
     const localScanDirs = LOCAL_SCAN_DIRS;
-    registerMarketplaceRoutes(expressApp, ctx, getPluginMgr, gate, uiConfig.marketplaceRegistry, () => collectLocalPackageDeps(localScanDirs, fsScanEnv), () => discoverAndProvideClients());
-    // 获取历史日志：从 data/latest.log 读尾部 N 条（lazy load）。
+    registerMarketplaceRoutes(expressApp, {
+        logger,
+        plugins: caps.plugins,
+        services,
+        packageManager: caps.packageManager,
+    }, gate, uiConfig.marketplaceRegistry, () => collectLocalPackageDeps(localScanDirs, fsScanEnv), () => discoverAndProvideClients());
+    // 历史日志从 data/latest.log 读（lazy load）。
     // 单进程内 LogHub 不再缓存 buffer——历史以文件为单一数据源。
-    expressApp.get('/api/logs', gate(), async (_req, res) => {
-        try {
-            const entries = await readLogFileTail(storage, 200);
-            res.json(entries);
-        }
-        catch (err) {
-            res.status(500).json({ error: err.message });
-        }
-    });
     // 尾部 N 条（首屏 / 显式刷新）
     expressApp.get('/api/logs/tail', gate(), async (req, res) => {
         const limit = Math.min(Math.max(Number(req.query.limit) || 200, 1), 5000);
@@ -435,7 +475,7 @@ export async function apply(ctx, config) {
     });
     // 获取服务列表（含提供者信息）
     expressApp.get('/api/services', gate(), async (_req, res) => {
-        const pluginMgr = getPluginMgr();
+        const pluginMgr = caps.plugins.current;
         const pluginStatus = pluginMgr ? pluginMgr.getStatus() : [];
         const displayNameMap = new Map();
         for (const p of pluginStatus) {
@@ -444,24 +484,26 @@ export async function apply(ctx, config) {
                 displayNameMap.set(p.instanceId, p.displayName);
             }
         }
-        // root context 即内核自身（app / plugins 两个服务由它 provide）——显示包名，别把内部 id 'root' 裸露给用户
-        displayNameMap.set('root', '@aalis/core');
-        const serviceNames = ctx.getServiceNames();
-        const services = {};
+        // 根激活归宿主：core 的内置服务与宿主登记的 host-config / plugin-source 都在这里（与市场依赖图同一标签）。
+        // 别把内部 id 'root' 裸露给用户。
+        displayNameMap.set('root', '宿主');
+        const serviceNames = services.names();
+        const detail = {};
         for (const svcName of serviceNames) {
-            // getAllServices 已按「偏好 > 优先级 > 注册顺序」排序，附带 priority 字段
-            const entries = ctx.getAllServices(svcName);
-            services[svcName] = {
+            // 枚举已按「偏好 > 优先级 > 注册顺序」排序，附带 priority 字段；只取登记元数据，不取实例
+            const entries = services.inspect(svcName);
+            detail[svcName] = {
                 providers: entries.map(e => ({
                     contextId: e.contextId,
                     displayName: displayNameMap.get(e.contextId),
                     label: e.label,
                     priority: e.priority,
+                    exclusive: e.exclusive,
                 })),
-                preferred: ctx.getPreferredService(svcName) ?? null,
+                preferred: services.preferred(svcName) ?? null,
             };
         }
-        res.json({ services });
+        res.json({ services: detail });
     });
     /**
      * 设置服务偏好。body: { contextId: string }
@@ -475,28 +517,44 @@ export async function apply(ctx, config) {
             return;
         }
         // 校验 entry 存在
-        const entries = ctx.getAllServices(svcName);
+        const entries = services.inspect(svcName);
         if (!entries.some(e => e.contextId === contextId)) {
             res.status(404).json({ ok: false, error: `service "${svcName}" has no provider with contextId "${contextId}"` });
             return;
         }
-        ctx.preferService(svcName, contextId);
-        ctx.config.setServicePreference(svcName, contextId);
+        // 偏好要跨重启保留就得写进文档：宿主没提供文档时不动运行态
+        const host = caps.hostConfig.current;
+        if (!host) {
+            res.status(503).json({ ok: false, error: '宿主未提供配置文档（host-config），无法保存偏好' });
+            return;
+        }
+        if (!services.prefer(svcName, contextId)) {
+            res.status(409).json({ ok: false, error: `service "${svcName}" rejected provider preference "${contextId}"` });
+            return;
+        }
+        host.setServicePreference(svcName, contextId);
         // 切换前端：webui-client 是「前端」服务，偏好变更需重挂静态目录 + 通知客户端刷新。
         // 重挂与偏好同属内存态，必须在等落盘之前一起生效：save 拒绝时才不会留下「解析选 B、静态挂 A」。
         if (svcName === 'webui-client')
             remountActiveClient();
-        await ctx.config.save();
+        if (!(await saveAfterApply(host, res, 'restart')))
+            return;
         res.json({ ok: true });
     });
     /** 清除服务偏好 */
     expressApp.delete('/api/services/:name/prefer', gate(), async (req, res) => {
         const svcName = String(req.params.name);
-        ctx.unpreferService(svcName);
-        ctx.config.removeServicePreference(svcName);
+        const host = caps.hostConfig.current;
+        if (!host) {
+            res.status(503).json({ ok: false, error: '宿主未提供配置文档（host-config），无法保存偏好' });
+            return;
+        }
+        services.unprefer(svcName);
+        host.removeServicePreference(svcName);
         if (svcName === 'webui-client')
             remountActiveClient();
-        await ctx.config.save();
+        if (!(await saveAfterApply(host, res, 'restart')))
+            return;
         res.json({ ok: true });
     });
     // 前端切换已统一到「服务偏好」：前端是 webui-client 服务的多 provider，切换走
@@ -504,12 +562,13 @@ export async function apply(ctx, config) {
     // 故不再有独立的 /api/clients* 路由。
     // 获取所有平台适配器及其连接状态
     expressApp.get('/api/platforms', gate(), (_req, res) => {
-        res.json({ platforms: aggregatePlatformDetails(ctx) });
+        res.json({ platforms: aggregatePlatformDetails(caps.platform) });
     });
     // 获取已注册的工具分组（含元数据 + 各组工具数量 + 贡献插件列表）
     expressApp.get('/api/tool-groups', gate(), (_req, res) => {
-        const groups = ctx.getService('tools')?.getGroups() ?? [];
-        const allTools = ctx.getService('tools')?.getAll() ?? [];
+        const toolService = caps.tools.current;
+        const groups = toolService?.getGroups() ?? [];
+        const allTools = toolService?.getAll() ?? [];
         const knownNames = new Set(groups.map(g => g.name));
         const result = groups.map(g => {
             const toolsInGroup = allTools.filter(t => t.groups?.includes(g.name));
@@ -537,13 +596,13 @@ export async function apply(ctx, config) {
     });
     // 获取服务分组（manifest 驱动：每个插件自己声明 subsystem，本路由仅聚合）
     expressApp.get('/api/service-groups', gate(), (_req, res) => {
-        const pluginMgr = getPluginMgr();
+        const pluginMgr = caps.plugins.current;
         const pluginStatus = pluginMgr ? pluginMgr.getStatus() : [];
-        // 按插件 subsystem 归组（未声明 → 'external'）。subsystem 是 WebUI 展示概念、
-        // 由 @aalis/api-webui 声明合并到 PluginModule，core 状态契约不含——从 module 直接读。
+        // 按插件 subsystem 归组（未声明 → 'external'）。subsystem 是插件定义上的展示标签，
+        // core 状态契约不含——从定义直接读。
         const groupsMap = new Map();
         for (const p of pluginStatus) {
-            const sub = pluginMgr?.getPlugin(p.instanceId)?.module?.subsystem ?? 'external';
+            const sub = pluginMgr?.getPlugin(p.instanceId)?.definition?.subsystem ?? 'external';
             if (!groupsMap.has(sub))
                 groupsMap.set(sub, []);
             groupsMap.get(sub).push({ name: p.name, provides: p.provides ?? [] });
@@ -560,16 +619,16 @@ export async function apply(ctx, config) {
         const servicesClaimed = new Set();
         const groups = sorted.map(({ id, label }) => {
             const plugins = groupsMap.get(id);
-            const services = [...new Set(plugins.flatMap(p => p.provides))].filter(s => {
+            const owned = [...new Set(plugins.flatMap(p => p.provides))].filter(s => {
                 if (servicesClaimed.has(s))
                     return false;
                 servicesClaimed.add(s);
                 return true;
             });
-            return { id, label, plugins, services };
+            return { id, label, plugins, services: owned };
         });
         // 系统内建服务（app、plugins 等由 core 直接 provide，不属于任何插件）
-        const systemServices = ctx.getServiceNames().filter(n => !servicesClaimed.has(n));
+        const systemServices = services.names().filter(n => !servicesClaimed.has(n));
         if (systemServices.length > 0) {
             const sysLabel = meta.get('system')?.label ?? '系统';
             groups.unshift({ id: 'system', label: sysLabel, plugins: [], services: systemServices });
@@ -579,7 +638,7 @@ export async function apply(ctx, config) {
     // 获取所有 LLM 模型（枚举所有注册的 per-model entry）
     expressApp.get('/api/llm-models', gate(), async (_req, res) => {
         try {
-            const entries = ctx.getAllServices('llm');
+            const entries = caps.llm.all();
             const models = entries.map(e => ({
                 id: e.instance.id,
                 capabilities: [...e.instance.capabilities],
@@ -595,7 +654,7 @@ export async function apply(ctx, config) {
     // LLM providers + per-provider models（供 schema type='llm-ref' 联动 select 使用）
     expressApp.get('/api/llm-providers', gate(), async (_req, res) => {
         try {
-            const entries = ctx.getAllServices('llm');
+            const entries = caps.llm.all();
             const byProvider = new Map();
             // entry.label 形如 "Ollama (localhost:11434) / qwen3.6:35b-mlx"；
             // 取第一个 " / " 之前的部分作为 providerLabel（避免把 model id 也带进去）。
@@ -632,12 +691,8 @@ export async function apply(ctx, config) {
     // 同 provider 下所有 model entries 共享同一份 refresh 闭包，调任一个 entry 即可。
     expressApp.post('/api/llm-providers/:contextId/refresh', gate(), async (req, res) => {
         const contextId = req.params.contextId;
-        if (!contextId) {
-            res.status(400).json({ error: 'contextId is required' });
-            return;
-        }
         try {
-            const llmEntries = ctx.getAllServices('llm');
+            const llmEntries = caps.llm.all();
             const target = llmEntries.find(e => e.contextId === contextId && typeof e.instance.refresh === 'function');
             if (!target) {
                 res.status(404).json({
@@ -657,13 +712,13 @@ export async function apply(ctx, config) {
         const serviceName = req.params.service;
         // 特殊处理 platform：通过 helper 获取已注册的平台名称
         if (serviceName === 'platform') {
-            res.json({ models: getPlatformNames(ctx) });
+            res.json({ models: getPlatformNames(caps.platform) });
             return;
         }
         // 特殊处理 gateway-scopes：基于已注册 adapter.sessionTypes 真实声明生成
         // platform×sessionType 的笛卡尔积。无声明的 adapter 视为单会话（不展开 sessionType）。
         if (serviceName === 'gateway-scopes') {
-            const adapters = getPlatformAdapters(ctx);
+            const adapters = getPlatformAdapters(caps.platform);
             const platformTypes = new Map();
             const allTypes = new Set();
             for (const a of adapters) {
@@ -693,7 +748,7 @@ export async function apply(ctx, config) {
         }
         // 特殊处理 toolGroups：优先从工具分组注册表获取，回退到扫描工具
         if (serviceName === 'toolGroups') {
-            const groups = ctx.getService('tools')?.getGroups() ?? [];
+            const groups = caps.tools.current?.getGroups() ?? [];
             // '*' = 全部分组（plugin-tools 的分组过滤认它），与会话范围选项的「* （全部平台）」同一写法
             if (groups.length > 0) {
                 res.json({
@@ -711,9 +766,9 @@ export async function apply(ctx, config) {
             }
             else {
                 // 回退：从已注册工具中提取分组名称
-                const tools = ctx.getService('tools')?.getAll() ?? [];
+                const allTools = caps.tools.current?.getAll() ?? [];
                 const groupSet = new Set();
-                for (const t of tools) {
+                for (const t of allTools) {
                     t.groups?.forEach((g) => {
                         groupSet.add(g);
                     });
@@ -725,7 +780,7 @@ export async function apply(ctx, config) {
         // LLM 走 per-model entry 枚举（每个 entry 已对应一个具体 model，不再依赖 provider.listModels）
         if (serviceName === 'llm') {
             try {
-                const entries = ctx.getAllServices('llm');
+                const entries = caps.llm.all();
                 const aggregated = entries.map(e => ({
                     value: `${e.contextId}::${e.instance.id}`,
                     model: e.instance.id,
@@ -740,14 +795,14 @@ export async function apply(ctx, config) {
             }
             return;
         }
-        const service = ctx.getService(serviceName);
+        const service = services.get(serviceName);
         if (!service || typeof service.listModels !== 'function') {
             res.json({ models: [] });
             return;
         }
         try {
             // 聚合所有提供者的模型列表（embedding 等服务仍走 listModels()）。
-            const allProviders = ctx.getAllServices(serviceName);
+            const allProviders = services.all(serviceName);
             const aggregated = [];
             const flatValues = [];
             for (const provider of allProviders) {
@@ -756,15 +811,13 @@ export async function apply(ctx, config) {
                 try {
                     const models = await provider.instance.listModels();
                     for (const m of models) {
-                        const isModelInfo = typeof m === 'object' && m !== null && 'id' in m;
-                        const modelId = isModelInfo ? m.id : String(m);
-                        const modelCaps = isModelInfo ? m.capabilities : [];
+                        const modelId = String(m);
                         aggregated.push({
                             value: modelId,
                             model: modelId,
                             provider: provider.label ?? provider.contextId,
                             contextId: provider.contextId,
-                            capabilities: modelCaps,
+                            capabilities: [],
                         });
                         flatValues.push(modelId);
                     }
@@ -783,7 +836,7 @@ export async function apply(ctx, config) {
     // 协调器逻辑（待确认/超时/解析/文案）由 session-confirm 服务统一实现；WebUI 只注入自己的 WS 投递，
     // 并保留 type:'confirm'（前端「确认模式」信号，抑制富客户端的「打字即打断」）。回复在 WS-onmessage 调 feed（下方）。
     let confirmChannel;
-    ctx.whenService('session-confirm', confirmSvc => {
+    caps.sessionConfirm.follow(confirmSvc => {
         const channel = confirmSvc.createChannel((request, text) => {
             const payload = { type: 'confirm', content: text, sessionId: request.sessionId };
             const json = JSON.stringify(payload);
@@ -794,10 +847,10 @@ export async function apply(ctx, config) {
                     ws.send(json);
             }
         });
-        // 挂到 authority 上要跟着它的胜者走（bounce 后重挂），所以嵌套一层 whenService；
-        // 外层 cleanup 即内层订阅的 dispose：session-confirm 换胜者或本插件 dispose 时一并注销
+        // 挂到 authority 上要跟着它的胜者走（bounce 后重挂），所以嵌套一层跟随；
+        // 外层 cleanup 即内层订阅的退订：session-confirm 换胜者或本插件拆卸时一并注销
         confirmChannel = channel;
-        const offAuthority = ctx.whenService('authority', authority => authority.setConfirmHandler('webui', channel.handler));
+        const offAuthority = caps.authority.follow(authoritySvc => authoritySvc.setConfirmHandler('webui', channel.handler));
         // cleanup：摘 handler、dispose 旧通道（在飞确认按取消结算，不留到 60s 超时）、清引用
         return () => {
             offAuthority();
@@ -807,21 +860,34 @@ export async function apply(ctx, config) {
         };
     });
     // ---------- 文件管理 API ----------
-    registerFileRoutes(expressApp, ctx, { storage, fileRoot: uiConfig.fileRoot }, gate);
-    registerUploadedFilesRoutes(expressApp, ctx, { storage }, gate);
-    registerProxyRoutes(expressApp, ctx, gate);
+    registerFileRoutes(expressApp, { storage, fileRoot: uiConfig.fileRoot }, gate);
+    registerUploadedFilesRoutes(expressApp, {
+        storage,
+        logger,
+        fileIndex: () => services.get('file-reader'),
+    }, gate);
+    registerProxyRoutes(expressApp, logger, gate);
     // ---------- WebSocket ----------
     wss.on('connection', (ws, req) => {
         // 连接建立时解析一次调用者身份（cookie 在升级请求里；verifyClient 已保证已认证）
         const wsIdentity = auth.identify(req) ?? { platform: 'webui', userId: 'console' };
-        ctx.logger.debug(`WebUI 客户端已连接: ${wsIdentity.platform}:${wsIdentity.userId}`);
+        logger.debug(`WebUI 客户端已连接: ${wsIdentity.platform}:${wsIdentity.userId}`);
         allClients.add(ws);
         heartbeat.track(ws);
         ws.on('message', async (data) => {
+            // 非 JSON 帧与形状不对的帧同属协议违规：都只记一行告警，外层 catch 留给真正的处理失败
+            let raw;
+            try {
+                raw = JSON.parse(data.toString());
+            }
+            catch {
+                logger.warn('WebUI 收到协议违规消息: 非 JSON 帧');
+                return;
+            }
             try {
-                const parseResult = WSIncomingSchema.safeParse(JSON.parse(data.toString()));
+                const parseResult = WSIncomingSchema.safeParse(raw);
                 if (!parseResult.success) {
-                    ctx.logger.warn(`WebUI 收到协议违规消息: ${parseResult.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
+                    logger.warn(`WebUI 收到协议违规消息: ${parseResult.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
                     return;
                 }
                 const msg = parseResult.data;
@@ -867,10 +933,10 @@ export async function apply(ctx, config) {
                     }
                     else {
                         // 无缓存（服务重启后），请求 agent 重新计算
-                        ctx
+                        events
                             .emit('token:request', {
                             sessionId: sid,
-                            platform: resolveSessionPlatform(sid, new Set(getPlatformNames(ctx))),
+                            platform: resolveSessionPlatform(sid, new Set(getPlatformNames(caps.platform))),
                         })
                             .catch(() => { });
                     }
@@ -883,23 +949,23 @@ export async function apply(ctx, config) {
                 }
                 if (msg.type === 'abort') {
                     const sessionId = msg.sessionId || 'webui-default';
-                    const agent = ctx.getService('agent');
-                    if (agent?.abort)
-                        agent.abort(sessionId);
+                    const agentSvc = caps.agent.current;
+                    if (agentSvc?.abort)
+                        agentSvc.abort(sessionId);
                     return;
                 }
                 if (msg.type === 'compress') {
                     const sessionId = msg.sessionId || 'webui-default';
-                    ctx.logger.info(`收到手动压缩请求: session=${sessionId}`);
+                    logger.info(`收到手动压缩请求: session=${sessionId}`);
                     // 触发压缩事件（memory-summary 监听此事件，并发出 session:compressing 通知）
-                    ctx
+                    events
                         .emit('session:compress', { sessionId, reason: 'manual' })
                         .then(() => {
                         // 压缩完成后重新计算 token 用量并推送给客户端
-                        ctx
+                        events
                             .emit('token:request', {
                             sessionId,
-                            platform: resolveSessionPlatform(sessionId, new Set(getPlatformNames(ctx))),
+                            platform: resolveSessionPlatform(sessionId, new Set(getPlatformNames(caps.platform))),
                         })
                             .catch(() => { });
                     })
@@ -924,7 +990,7 @@ export async function apply(ctx, config) {
                 // 适配器不再内联解析命令——未注册的命令会被该相位放行为普通消息进入
                 // agent，命中的命令由该相位执行并经 outbound:message 回送，与 onebot
                 // 平台行为完全一致。客户端只通过 attachments 发送多模态内容。
-                await ctx.emit('inbound:message', {
+                await events.emit('inbound:message', {
                     content: trimmed,
                     sessionId,
                     platform: wsIdentity.platform,
@@ -934,7 +1000,7 @@ export async function apply(ctx, config) {
                 });
             }
             catch (err) {
-                ctx.logger.warn('WebUI 消息处理失败:', err);
+                logger.warn('WebUI 消息处理失败:', err);
             }
         });
         ws.on('close', () => {
@@ -959,7 +1025,7 @@ export async function apply(ctx, config) {
         }
     });
     // 插件状态级联变更后，广播通知所有前端刷新
-    ctx.on('plugins:changed', () => {
+    events.on('plugins:changed', () => {
         const payload = { type: 'state_changed' };
         const json = JSON.stringify(payload);
         for (const ws of allClients) {
@@ -969,7 +1035,7 @@ export async function apply(ctx, config) {
         }
     });
     // 重启通知：广播给所有客户端。WS 报文的 type 是前端协议，与 core 事件名无关，保持 'restarting'。
-    ctx.on('app:restarting', () => {
+    events.on('app:restarting', () => {
         const payload = { type: 'restarting' };
         const json = JSON.stringify(payload);
         for (const ws of allClients) {
@@ -989,9 +1055,7 @@ export async function apply(ctx, config) {
         }
     };
     // Todo 列表变更：推送给订阅了该会话的客户端
-    ctx.on('todo:updated', (...args) => {
-        const sessionId = args[0];
-        const items = args[1];
+    events.on('todo:updated', (sessionId, items) => {
         const sockets = sessions.get(sessionId);
         if (!sockets)
             return;
@@ -1003,10 +1067,10 @@ export async function apply(ctx, config) {
             }
         }
     });
-    ctx.on('session:created', broadcastSessionsChanged);
-    ctx.on('session:updated', broadcastSessionsChanged);
-    ctx.on('session:deleted', broadcastSessionsChanged);
-    ctx.on('session:completed', broadcastSessionsChanged);
+    events.on('session:created', broadcastSessionsChanged);
+    events.on('session:updated', broadcastSessionsChanged);
+    events.on('session:deleted', broadcastSessionsChanged);
+    events.on('session:completed', broadcastSessionsChanged);
     // 动态页面刷新通知：插件可通过广播 'page_refresh' 让前端无感刷新对应页面数据
     // 当前已知发射方：plugin-doctor（'doctor:updated'）。新增同类需求时按相同模式订阅即可。
     const broadcastPageRefresh = (pluginName) => {
@@ -1017,11 +1081,10 @@ export async function apply(ctx, config) {
                 ws.send(json);
         }
     };
-    ctx.on('doctor:updated', () => broadcastPageRefresh('@aalis/plugin-doctor'));
+    events.on('doctor:updated', () => broadcastPageRefresh('@aalis/plugin-doctor'));
     // 会话历史变更（如 checkpoint 回滚整轮对话）：推送给订阅该会话的客户端，让前端重新拉取历史
-    ctx.on('history:changed', (...args) => {
-        const data = args[0];
-        const sessionId = data?.sessionId;
+    events.on('history:changed', change => {
+        const sessionId = change?.sessionId;
         if (!sessionId)
             return;
         const sockets = sessions.get(sessionId);
@@ -1036,12 +1099,11 @@ export async function apply(ctx, config) {
         }
     });
     // 压缩状态通知：memory-summary 发出 session:compressing 事件，广播给订阅该会话的客户端
-    ctx.on('session:compressing', (...args) => {
-        const data = args[0];
-        const sockets = sessions.get(data.sessionId);
+    events.on('session:compressing', info => {
+        const sockets = sessions.get(info.sessionId);
         if (!sockets)
             return;
-        const payload = { type: 'compressing', sessionId: data.sessionId, content: data.status };
+        const payload = { type: 'compressing', sessionId: info.sessionId, content: info.status };
         const json = JSON.stringify(payload);
         for (const ws of sockets) {
             if (ws.readyState === WebSocket.OPEN) {
@@ -1053,7 +1115,7 @@ export async function apply(ctx, config) {
     // 持久化 + 每条消息自带 sessionId），互不干扰。全局 activeSessionId 退化为 CLI 概念，
     // 不再驱动 webui。这样多人同时使用时，他人新建/切换会话不会把你的窗口切走。
     // 监听 AI 回复
-    ctx.on('outbound:message', (msg) => {
+    events.on('outbound:message', (msg) => {
         // 生成完成，延迟清理缓冲区（给客户端重连拉取历史留出时间窗口）
         const buf = streamBuffers.get(msg.sessionId);
         if (buf) {
@@ -1096,7 +1158,7 @@ export async function apply(ctx, config) {
         }
     });
     // 监听流式增量推送
-    ctx.on('outbound:stream', (chunk) => {
+    events.on('outbound:stream', (chunk) => {
         // 累积到缓冲区
         if (!chunk.done) {
             let buf = streamBuffers.get(chunk.sessionId);
@@ -1172,7 +1234,7 @@ export async function apply(ctx, config) {
         }
     });
     // 监听工具调用事件
-    ctx.on('tool:execute', (info) => {
+    events.on('tool:execute', (info) => {
         // 缓存工具调用到 segments
         let buf = streamBuffers.get(info.sessionId);
         if (!buf) {
@@ -1214,8 +1276,7 @@ export async function apply(ctx, config) {
         }
     });
     // 监听 token 使用量统计事件
-    ctx.on('token:usage', (...args) => {
-        const usage = args[0];
+    events.on('token:usage', usage => {
         const sockets = sessions.get(usage.sessionId);
         if (!sockets)
             return;
@@ -1265,7 +1326,7 @@ export async function apply(ctx, config) {
     });
     /**
      * 全动态发现前端：按 `aalis.client:true` 标记扫描，**不硬编码任何前端包名**
-     * （与 runtime 加载器的 marker 驱动一致；忒修斯之船——任意第三方前端带标记+dist 即被发现）。
+     * （忒修斯之船——任意第三方前端带标记+dist 即被发现）。
      * 覆盖三种拓扑：monorepo（扫 packages 同级目录）/ 独立项目（扫 node_modules/@aalis + 根 deps）。
      *
      * **幂等**，可重复调用：装完一个 `aalis-interface` 包后要立刻重跑，否则它不会出现在服务页
@@ -1274,8 +1335,6 @@ export async function apply(ctx, config) {
      *
      * 只登记新候选，**不切换活跃前端**：换前端是用户在服务页的显式选择，装了个新的不该把
      * 他正在用的顶掉。
-     *
-     * @returns 本次新发现的候选数
      */
     function discoverAndProvideClients() {
         const projectRequire = createRequire(pathToFileURL(resolve(process.cwd(), 'package.json')));
@@ -1314,7 +1373,7 @@ export async function apply(ctx, config) {
             clientProviderDisposers.delete(stale.id);
             clientCandidates.splice(i, 1);
             removed++;
-            ctx.logger.info(`前端已消失，摘除候选: ${stale.label} (${stale.dir})`);
+            logger.info(`前端已消失，摘除候选: ${stale.label} (${stale.dir})`);
         }
         // 摘掉 provider 只改了「服务解析结果」，**真正服务 HTTP 的是 clientDist / staticMiddleware**，
         // 它们在 app:ready 时绑定、之后只由 remountActiveClient 更新。不重挂的话，被摘掉的正好是当前
@@ -1325,27 +1384,31 @@ export async function apply(ctx, config) {
         const fresh = pickFreshClients(clientCandidates.map(c => c.id), scanned);
         clientCandidates.push(...fresh);
         // 把每个新发现的前端注册为 webui-client 服务的一个 provider（带 label，供「服务」页下拉切换）。
-        // 外部插件在 apply 里主动 provide('webui-client') 的也已在服务池中（注册更早 → 默认胜出，仍可被偏好切换）。
+        // 外部插件在 apply 里主动提供 webui-client 的也已在服务池中（注册更早 → 默认胜出，仍可被偏好切换）。
+        //
+        // 代前端包登记：条目身份是前端**包名本身**——它是服务页展示的 contextId，也是
+        // servicePreferences['webui-client'] 里持久化的键，还是装卸闸按包名比对的对象。
         for (const candidate of fresh) {
-            clientProviderDisposers.set(candidate.id, ctx
-                .fork(candidate.id)
-                .provide('webui-client', { getClientDir: () => candidate.dir }, { label: candidate.label }));
-            ctx.logger.info(`发现前端: ${candidate.label} (${candidate.dir})`);
+            clientProviderDisposers.set(candidate.id, provide(webuiClient, { getClientDir: () => candidate.dir }, { label: candidate.label, onBehalfOf: candidate.id }));
+            logger.info(`发现前端: ${candidate.label} (${candidate.dir})`);
         }
-        return fresh.length;
     }
     // 启动服务器
-    ctx.on('app:ready', () => {
+    events.on('app:ready', async () => {
+        // 冷启动时 storage 的激活在 app:ready 之前收敛；等晚到的读回落定，listen / autoOpen /
+        // access.txt 用的就是持久化的 token
+        if (tokenLoading)
+            await tokenLoading;
         discoverAndProvideClients();
         // 活跃前端 = 解析后的 webui-client 服务（servicePreferences 偏好 > 优先级 > 注册顺序）；零前端则 404。
         const activeDir = currentClientDir();
         if (activeDir) {
             clientDist = activeDir;
             mountStaticDir(activeDir);
-            ctx.logger.info(`活跃前端: ${activeDir}`);
+            logger.info(`活跃前端: ${activeDir}`);
         }
         else {
-            ctx.logger.warn('未发现任何前端（webui-client provider）；前端路由将 404，请安装一个 aalis.client 包');
+            logger.warn('未发现任何前端（webui-client provider）；前端路由将 404，请安装一个 aalis.client 包');
         }
         // 监听失败（典型 EADDRINUSE：3000 被别的 dev server 占了）是 bind 之后**异步 emit** 的，
         // 不在任何调用栈内，外层 try/catch 接不住 —— 无人处理即 uncaughtException →
@@ -1357,7 +1420,7 @@ export async function apply(ctx, config) {
         // wss）并排在最前；EventEmitter 按注册顺序调用，它 emit 到无监听器的 wss 上会同步抛出、
         // 中断 emit 循环，后注册在 server 上的 handler 因此永远轮不到。
         wss.on('error', (err) => {
-            ctx.logger.error(`WebUI 监听 ${uiConfig.host}:${uiConfig.port} 失败: ${err.message}；WebUI 不可用，其余功能照常运行`);
+            logger.error(`WebUI 监听 ${uiConfig.host}:${uiConfig.port} 失败: ${err.message}；WebUI 不可用，其余功能照常运行`);
         });
         server.listen(uiConfig.port, uiConfig.host, () => {
             // 通配绑定地址（0.0.0.0 / ::）是"听在哪"，不是"从哪访问"——直接拼进 URL 会让
@@ -1365,27 +1428,28 @@ export async function apply(ctx, config) {
             // 展示/打开一律用回环；局域网访问地址由用户按本机 IP 自行替换。
             const displayHost = uiConfig.host === '0.0.0.0' || uiConfig.host === '::' ? '127.0.0.1' : uiConfig.host;
             const url = `http://${displayHost}:${uiConfig.port}/`;
+            listeningUrl = url;
             const accessUrl = `${url}?token=${authToken}`;
-            ctx.logger.info(`WebUI 已启动: ${url}`);
+            logger.info(`WebUI 已启动: ${url}`);
             // 多前端时提示恢复页 URL：万一切到无切换 UI 的前端被卡住，可在此切回（详见 client-switch-page.ts）。
             if (clientCandidates.length > 1) {
-                ctx.logger.info(`检测到多个前端；若卡在某前端无切换入口，可访问恢复页切回: ${url}__clients`);
+                logger.info(`检测到多个前端；若卡在某前端无切换入口，可访问恢复页切回: ${url}__clients`);
             }
             const tokenHint = uiConfig.tokenMode === 'ephemeral'
                 ? 'token 仅本次启动有效，重启轮换'
                 : uiConfig.tokenMode === 'fixed'
                     ? 'token 来自配置 fixedToken，固定不变'
                     : 'token 已持久化到 storage data:/webui/token，重启沿用';
-            // 不把 token 打进日志（会落 latest.log / 被 /api/logs 回放 / 贴日志求助时外泄）。
+            // 不把 token 打进日志（会落 latest.log / 被 /api/logs/* 回放 / 贴日志求助时外泄）。
             // 仅打不带 token 的 URL，完整一键登录链接见 access.txt（该文件应 0o600，见 token 落盘）。
-            ctx.logger.info(`首次访问 URL（${tokenHint}）: ${url} —— 完整一键登录链接见 ${accessFileUri}`);
+            logger.info(`首次访问 URL（${tokenHint}）: ${url} —— 完整一键登录链接见 ${accessFileUri}`);
             void (async () => {
                 // 先把文件写出来，再解析它的绝对路径：resolveLocalPath 走 realpath，文件尚未落盘会抛
                 // ENOENT 被吞掉，于是「绝对路径」退化成原样重复一遍 URI——偏偏首启（新用户唯一需要
                 // 这行的时刻）必然命中，二次启动因文件已在反而正常。两者原先都是 void，谁先到看调度。
                 if (!(await writeAccessFile(url, authToken))) {
                     // 写失败上面已 warn 过；再打一条「已写入」只会让人去找一个不存在的文件
-                    ctx.logger.warn(`访问凭据未能写入 ${accessFileUri}；请用 WebUI 登录页手工粘贴 token`);
+                    logger.warn(`访问凭据未能写入 ${accessFileUri}；请用 WebUI 登录页手工粘贴 token`);
                     return;
                 }
                 let absHint = accessFileUri;
@@ -1395,22 +1459,22 @@ export async function apply(ctx, config) {
                     }
                 }
                 catch (err) {
-                    ctx.logger.debug(`解析访问凭据文件绝对路径失败: ${err.message}`);
+                    logger.debug(`解析访问凭据文件绝对路径失败: ${err.message}`);
                 }
-                ctx.logger.info(`访问凭据已写入: ${accessFileUri}（绝对路径: ${absHint}）`);
+                logger.info(`访问凭据已写入: ${accessFileUri}（绝对路径: ${absHint}）`);
             })();
             if (uiConfig.autoOpen)
-                openBrowser(accessUrl, createProcessGateway(ctx));
+                openBrowser(accessUrl, createProcessGateway(caps.process));
         });
     });
-    ctx.onDispose(() => {
+    lifecycle.onDispose(() => {
         confirmChannel?.dispose(); // 清 WebUI 确认通道里挂起的待确认（安全拒），避免 Promise 永挂
         heartbeat.dispose();
         removeLogListener();
         // 先把已建立的连接收口再关服务端：ws 的 close() 在 {server} 模式下只摘监听器、对
         // this.clients 一个都不动，server.close() 也只停止 accept。不主动关的话，旧 socket 上
-        // 注册的 message 闭包在插件卸载后仍然活着，照常 ctx.emit('inbound:message')——而
-        // Context.emit 不设关闭守卫（同文件 on/provide/fork 都有）。
+        // 注册的 message 闭包在插件卸载后仍然活着，照常发 'inbound:message'——而事件发射
+        // 不设关闭守卫（订阅与发布两侧不对称）。
         // 发 1001 触发前端既有的 onclose 重连路径，bounce 之后自动接回新实例。
         for (const ws of allClients) {
             try {
@@ -1460,7 +1524,7 @@ export async function apply(ctx, config) {
             }
         },
     };
-    ctx.provide('platform', adapter);
+    provide(platform, adapter);
     // === 注册 WebUI 服务 ===
     const registeredPages = new Map();
     // 内建页面归属为 webui-server 本身
@@ -1472,11 +1536,6 @@ export async function apply(ctx, config) {
     const webuiService = {
         getPort: () => uiConfig.port,
         getHost: () => uiConfig.host,
-        setClientDir(dir) {
-            clientDist = dir;
-            mountStaticDir(dir);
-            ctx.logger.info(`前端已切换: ${dir}`);
-        },
         registerPage(page, contextId) {
             const list = registeredPages.get(contextId) ?? [];
             const entry = { ...page, pluginName: contextId };
@@ -1500,10 +1559,20 @@ export async function apply(ctx, config) {
                 out.push(...list);
             return out;
         },
-        unregisterByPlugin(contextId) {
-            registeredPages.delete(contextId);
+        registerAction(method, handler, contextId) {
+            const actions = registeredActions.get(contextId) ?? new Map();
+            actions.set(method, handler);
+            registeredActions.set(contextId, actions);
+            // 退订按这一次登记比对：同名替换后旧退订闭包不得摘掉新登记
+            return () => {
+                if (actions.get(method) !== handler)
+                    return;
+                actions.delete(method);
+                if (actions.size === 0 && registeredActions.get(contextId) === actions)
+                    registeredActions.delete(contextId);
+            };
         },
     };
-    ctx.provide('webui-server', webuiService);
+    provide(webuiServer, webuiService);
 }
 //# sourceMappingURL=index.js.map