@aalis/plugin-webui-server 0.14.0 → 0.15.0

package/dist/index.js

@@ -4,35 +4,49 @@ import { Buffer } from 'node:buffer';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { createRequire } from 'node:module';
-import { dirname, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { agent } from '@aalis/api-agent';
-import { authority } from '@aalis/api-authority';
+import { approvals } from '@aalis/api-approval';
 import { commands } from '@aalis/api-commands';
+import { contributions } from '@aalis/api-contributions';
 import { hostConfig } from '@aalis/api-host-config';
-import { listLLMModels, llm } from '@aalis/api-llm';
+import { hostLogs } from '@aalis/api-host-logs';
+import { hostPaths } from '@aalis/api-host-paths';
+import { llm, resolveLLMModel } from '@aalis/api-llm';
+import { messageArchive } from '@aalis/api-message-archive';
 import { packageManager } from '@aalis/api-package-manager';
-import { persona } from '@aalis/api-persona';
-import { aggregatePlatformDetails, getPlatformAdapters, getPlatformNames, platform, } from '@aalis/api-platform';
+import { aggregatePlatformDetails, getPlatformAdapters, getPlatformNames, platform, sessionTypesOf, } 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 { processService } from '@aalis/api-process';
+import { rootSessionOf, sessionManager } from '@aalis/api-session-manager';
+import { sessionProtocol } from '@aalis/api-session-protocol';
+import { isStorageUri, 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 { parseTheme, webuiClient, webuiServer, } from '@aalis/api-webui';
+import { appService, config, definePlugin, events, lifecycle, logger, optional, pluginsService, provide, services, } from '@aalis/core';
+import { configError, defineConfig, parseConfig } from '@aalis/schema-config';
+import { outboundMediaMessage, WellKnownKinds, WellKnownMetadataKeys, } from '@aalis/schema-message';
 import express from 'express';
-import { WebSocket, WebSocketServer } from 'ws';
-import { createAuthSystem, openBrowser } from './auth.js';
+import { WebSocketServer } from 'ws';
+import { ADMIN_PATH, createAdminChannel } from './admin-channel.js';
+import { blockedStatus, createAttention } from './attention.js';
+import { createAuthSystem, openBrowser, originAllowed } from './auth.js';
 import { collectLocalPackageDeps, discoverClients, pickFreshClients } from './client-discovery.js';
-import { renderClientSwitchPage } from './client-switch-page.js';
+import { CLIENT_SWITCH_SCRIPT, renderClientSwitchPage } from './client-switch-page.js';
 import { createRouteGate } from './gate.js';
+import { createLayoutStore } from './layout.js';
+import { logMatcher, parseLogFilter } from './logs.js';
+import { createPageFiles } from './page-files.js';
+import { createPageRegistry } from './pages.js';
+import { route } from './route.js';
 import { registerFileRoutes } from './routes/files.js';
-import { registerMarketplaceRoutes } from './routes/marketplace.js';
+import { registerFrameRoutes } from './routes/frames.js';
+import { localPackageLookup, registerMarketplaceRoutes } from './routes/marketplace.js';
+import { registerMediaRoutes } from './routes/media.js';
+import { registerPageRoutes } from './routes/pages.js';
 import { registerPluginRoutes, saveAfterApply } from './routes/plugins.js';
 import { registerProxyRoutes } from './routes/proxy.js';
-import { registerUploadedFilesRoutes } from './routes/uploaded-files.js';
+import { acceptSessionSocket, SESSION_PATH } from './session-transport.js';
 import { createWsHeartbeat } from './ws-heartbeat.js';
 /**
  * 工具 / 指令 / 工具组 description 约定：首行 = 人类可读摘要，其余 = 给 agent 的长使用指南。
@@ -44,35 +58,76 @@ function descSummary(d) {
     const s = d.split('\n')[0].trim();
     return s.length > 200 ? `${s.slice(0, 200)}…` : s;
 }
+/** 可选项接口的 dependency 查询参数当模型引用读（llm-ref 的取值，JSON）：没带为 undefined，写法不对为 null */
+function modelRefOf(raw) {
+    if (raw === undefined)
+        return undefined;
+    let value;
+    try {
+        value = typeof raw === 'string' ? JSON.parse(raw) : undefined;
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const { provider, model } = value;
+    return (provider === undefined || typeof provider === 'string') && (model === undefined || typeof model === 'string')
+        ? { provider, model }
+        : null;
+}
 // ===== 插件元数据 =====
 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' },
-    { key: 'plugin-config', label: '插件配置', icon: 'plugin-config', order: 30, renderer: 'plugin-config' },
-    { key: 'platforms', label: '平台接入', icon: 'platforms', order: 40, renderer: 'platforms' },
-    { key: 'files', label: '文件管理', icon: 'files', order: 50, renderer: 'files' },
-    { key: 'logs', label: '日志', icon: 'logs', order: 60, renderer: 'logs' },
-];
-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: {
+// 按宿主身份记打开记录：插件 bounce 保留，新 App 独立；弱引用不延长宿主寿命。
+const browserOpenedFor = new WeakSet();
+/**
+ * fixed 模式的 token 最短长度。持有 token 就是 owner，带 cookie 的请求又不限速（见 auth.ts 的登录限速），
+ * 防猜靠的是 token 本身够长：32 个十六进制字符是 128 位
+ */
+const FIXED_TOKEN_MIN_LENGTH = 32;
+/** 文档级 CSP */
+const DOCUMENT_CSP = [
+    "default-src 'self'",
+    "script-src 'self'",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' blob: data:",
+    "connect-src 'self'",
+    "object-src 'none'",
+    "base-uri 'self'",
+    "frame-ancestors 'none'",
+].join('; ');
+const configSchema = defineConfig({
+    port: {
+        type: 'number',
+        label: '端口',
+        default: 3000,
+        integer: true,
+        min: 0,
+        max: 65535,
+        onInvalid: 'error',
+        description: 'Web 管理界面的 HTTP 端口',
+    },
+    host: {
         type: 'string',
-        label: '文件浏览根',
-        default: 'workspace',
-        description: '文件管理页面使用的 storage 根 ID，默认 workspace',
+        label: '监听地址',
+        default: '127.0.0.1',
+        pattern: '\\S',
+        onInvalid: 'error',
+        description: '绑定的 IP 地址，0.0.0.0 可对外访问',
     },
     autoOpen: {
         type: 'boolean',
         label: '启动时自动打开浏览器',
         default: true,
-        description: '访问 token 为新生成时（persist 模式首次生成、ephemeral 模式每次生成）以含 token 的 URL 自动开启默认浏览器；沿用已有 token（persist 读回已持久化的 token、fixed 用配置的 fixedToken）时不打开；fixed 模式 fixedToken 为空时按 persist 处理。SSH/headless 环境建议关闭',
+        onInvalid: 'error',
+        description: '每次应用启动后首次监听成功时打开默认浏览器；同一应用内沿用 token 的插件重载不重复打开，重新生成 token 时再次打开以便登录。SSH/headless 环境建议关闭',
     },
     tokenMode: {
         type: 'select',
         label: 'Token 策略',
         default: 'persist',
+        onInvalid: 'error',
+        secret: false,
         options: [
             { label: '每次启动随机生成（重启即轮换）', value: 'ephemeral' },
             { label: '首次生成后持久化（重启不掉登录）', value: 'persist' },
@@ -84,57 +139,77 @@ const configSchema = {
         type: 'string',
         label: '固定 Token（仅 tokenMode=fixed 生效）',
         default: '',
-        description: '请使用足够长的随机字符串；配置文件不支持环境变量插值，占位符会被原样当作字面量。',
-    },
-    relationGraphDefaultSpacing: {
-        type: 'number',
-        label: '关系图默认密度',
-        default: 120,
-        description: '关系图（RelationGraph）布局密度的服务器默认值（约等于理想边长 px，建议 60–250；越大越稀疏）。前端每个用户可在图工具栏现场覆盖并保存到本地浏览器；改完此项后，刷新关系图页面或新会话生效。',
+        onInvalid: 'error',
+        secret: true,
+        description: `至少 ${FIXED_TOKEN_MIN_LENGTH} 个字符的随机字符串（去掉首尾空白后计），短了插件不启动；留空按 persist 处理。存进 secrets.yaml，WebUI 不回显。`,
     },
     marketplaceRegistry: {
         type: 'string',
         label: '插件市场 npm 源',
         default: 'https://registry.npmjs.org',
+        onInvalid: 'error',
         description: '插件市场检索用的 npm registry 基址。注意 npm 的 search API 并非所有镜像都支持（淘宝等国内源不支持），默认官方源；国内可填支持 search 的镜像或代理。安装走 package-manager（遵循本机 npm 配置），卡片上的最新版与可更新也按安装使用的源查。',
     },
     // 活跃前端不在此配置：前端即 `webui-client` 服务的多 provider，活跃者由「服务偏好」
-    // （servicePreferences['webui-client']）决定——在 WebUI「服务」页的下拉框切换。
-};
-// ===== WebSocket 消息协议 =====
-// 入站消息类型 + 校验 schema 见 ./protocol.ts（zod 强校验）
-import { WSIncomingSchema } from './protocol.js';
-// ===== 日志文件读取（与 @aalis/runtime 的 file-logger 格式对偶）=====
-// 行格式契约（format ↔ parse）由 @aalis/schema-log 的 parseLogLine 唯一持有，此处只负责
-// 读取「持久化日志单一数据源」并按 cursor 尾读分页。
-//
-// 路径（宿主目录布局）是「环境知识」，归 storage 的 logs 根所有；本插件只用 storage
-// URI 寻址、对 cwd/落盘位置无知。写入方（runtime/file-logger）跑在 storage 起来之前，
-// 是 bootstrap 期的合法 raw-fs 例外，不在此处管辖（默认 logs 根 = data/，与之对偶）。
-const LOG_FILE_URI = 'logs:/latest.log';
-// 尾读/分页均走 readTailLines 的倒序分块读取——latest.log 可能几百 MB，
-// 旧实现每个请求整文件载入+全量解析，日志页一刷服务端就抖一次。
-async function readLogFileTail(storage, limit) {
-    const lines = await readTailLines(storage, LOG_FILE_URI, limit);
-    return lines.map(parseLogLine).filter((e) => e !== null);
-}
-async function readLogFileBefore(storage, beforeSeq, limit) {
-    // seq 随文件位置单调递增：从尾部向前扫，过滤 seq >= before 的尾段后取 limit 条。
-    // maxBytes 放宽到 16MiB 覆盖较深的向上分页；更深的考古走 data/latest.log 本体。
-    const lines = await readTailLines(storage, LOG_FILE_URI, limit, {
-        maxBytes: 16 * 1024 * 1024,
-        filter: line => {
-            const e = parseLogLine(line);
-            return e !== null && e.seq < beforeSeq;
-        },
+    // （servicePreferences['webui-client']）决定——在 WebUI 设置「系统」的服务偏好里切换。
+});
+// ===== WebUI 会话的收件箱 =====
+/**
+ * 发往 WebUI 自己会话的出站消息里，要由本插件写进会话历史的部分。WebUI 的收件箱就是会话历史，记不记全不取决于
+ * 别的插件是否在场。agent 的文字回复由 agent 存档，这里不再记，免得历史里重复。其余部分：
+ * - 不是她说的文字（系统提示、指令回复、宿主通知）记成事件标记：回看时显示成分隔条，不进模型上下文，与其他平台一致；
+ * - 图片、视频、音频用 outboundMediaMessage 记，回看时还原成附件；
+ * - 给的是存储地址的文件（插件发出的成品等）同样用 outboundMediaMessage 记，描述位记文件名，会话服务据此签发下载句柄。
+ *   metadata 另记原样的地址与文件名（登记的键 SentRef、SentName）：占位符里的地址遇到「]」会截断，描述位的「]」「|」换成了全角。这样的文件以
+ *   「[文件: 名称 | ref:…]」进模型上下文与记忆，不看全局出站归档记不记文件。不是存储地址的文件
+ *   （网址、data URL）签不出句柄，记成事件标记「[文件] 名称」，内容不进历史；
+ * - 快照里的 data 未经平台改写，就是页面上显示的那份，直接记它。带 skipArchive 的（history_ref 重发）原图已在
+ *   历史里，不再记。她发出的媒体在别的平台由全局出站归档在 outbound:delivered 上记；发往 WebUI 的由这里记，
+ *   outbound:delivered 的快照给附件标上 skipArchive，免得全局出站归档再记一份。代价是这些网址图片与视频不再由
+ *   全局出站归档在后台补视觉描述
+ */
+function inboxRecords(msg) {
+    const timestamp = Date.now();
+    const marker = (content) => ({
+        role: 'system',
+        kind: WellKnownKinds.EventMarker,
+        content,
+        timestamp,
     });
-    return lines.map(parseLogLine).filter((e) => e !== null && e.seq < beforeSeq);
+    const records = [];
+    if (msg.source !== 'agent' && msg.content.trim())
+        records.push(marker(msg.content));
+    for (const att of msg.attachments ?? []) {
+        if (att.skipArchive)
+            continue;
+        if (att.kind !== 'file') {
+            records.push({
+                ...outboundMediaMessage(att.kind, att.data, att.description),
+                timestamp,
+                metadata: { [WellKnownMetadataKeys.Source]: 'webui-server', [WellKnownMetadataKeys.SentRef]: att.data },
+            });
+        }
+        else if (isStorageUri(att.data)) {
+            records.push({
+                ...outboundMediaMessage('file', att.data, att.name),
+                timestamp,
+                metadata: {
+                    [WellKnownMetadataKeys.Source]: 'webui-server',
+                    [WellKnownMetadataKeys.SentRef]: att.data,
+                    [WellKnownMetadataKeys.SentName]: att.name,
+                },
+            });
+        }
+        else {
+            records.push(marker(`[文件] ${att.name ?? att.data.split('/').pop()}`));
+        }
+    }
+    return records;
 }
 // ===== 插件入口 =====
 /**
- * 本地包扫描目录：项目根的 `packages/` 与 `node_modules/@aalis`。
- *
- * 两者都以 **cwd（项目根）** 为基准——与 `projectRoot()`、node_modules 加载器的默认值同源。
+ * 本地包扫描目录：安装集（host-paths 的 `app`）下的 `packages/` 与 `node_modules/@aalis`，与插件加载器读的是同一处。
+ * 宿主不提供 host-paths 时没有可扫的目录。
  *
  * **不可按本文件位置推算**（如 `resolve(dirname(import.meta.url), '../../')`）：那是个位置
  * 假设，只在 webui-server 恰好躺在 `<根>/packages/<包>/dist` 时成立。装进用户项目后它解析成
@@ -142,27 +217,12 @@ async function readLogFileBefore(storage, beforeSeq, limit) {
  * `packages/` 从来不在范围内** —— 「私有插件放 packages/、第三方插件从 npm 装」这种混合
  * 形态下，本地插件在市场里将不可见。
  */
-const LOCAL_SCAN_DIRS = [resolve(process.cwd(), 'packages'), resolve(process.cwd(), 'node_modules/@aalis')];
-/**
- * 会话归属的平台名：取 sessionId 首个 `:` 前的前缀，命中**已注册平台名**才采信，否则 `'webui'`。
- *
- * WebUI 是管理面，订阅的会话可以属于任何平台（`onebot:123`）。它发 `token:request` 时若
- * 一律报 `'webui'`，消费方（plugin-agent）就按 webui 档解析模型与会话配置，把别人的预算
- * 快照算进错的上下文窗口。前缀不认识时才落回 `'webui'`——CLI 的 `cli-default` 这类不带
- * 前缀的会话，以及 webui 自己的会话，都归在这一档。
- *
- * 纯函数：平台名集合由调用方从 `getPlatformNames(platform)` 取（adapter 可热插拔，每次现取）。
- */
-export function resolveSessionPlatform(sessionId, known) {
-    const idx = sessionId.indexOf(':');
-    if (idx <= 0)
-        return 'webui';
-    const prefix = sessionId.slice(0, idx);
-    return known.has(prefix) ? prefix : 'webui';
+function localScanDirs(appDir) {
+    return appDir ? [join(appDir, 'packages'), join(appDir, 'node_modules', '@aalis')] : [];
 }
 // storage 等一律 optional：webui 是管理面，任何被管对象缺席都只该让对应页面降级，不该把
-// 整个控制台拖进 pending。storage 尤其不能 required——plugin-storage-local bounce 会让它
-// 暂时消失，webui-server 跟着重启就清空 registeredPages，其他插件的侧边栏页面再也回不来。
+// 整个控制台拖进 pending。storage 尤其不能 required——storage 的提供者 bounce 会让它
+// 暂时消失，webui-server 跟着重启会断开所有连接、清空页面登记表（登记门面随后重挂）。
 const uses = {
     events,
     logger,
@@ -171,21 +231,30 @@ const uses = {
     provide,
     services,
     hostConfig: optional(hostConfig),
+    /** 日志页的历史（/api/logs/*）与 /admin 上的实时推送 */
+    logs: optional(hostLogs),
+    paths: optional(hostPaths),
     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),
+    /** /session 的连接接到它；每条连接到达时现取，不在时关闭连接并写明原因。会话文件的下载请它核验句柄 */
+    sessionProtocol: optional(sessionProtocol),
+    /** 登记 webui 审批面：/session 连接上的在场上报与应答记在这个登记身份名下。推出未结的审批进「需要处理」 */
+    approvals: optional(approvals),
+    /** 会话面板：调用前核会话存在、按会话种类判断适用的页面 */
+    sessions: optional(sessionManager),
     tools: optional(tools),
     llm: optional(llm),
-    persona: optional(persona),
-    agent: optional(agent),
+    /** 插件经贡献点 webui:theme 提供的主题（GET /api/themes） */
+    contributions: optional(contributions),
+    // 发往 WebUI 自己会话的出站消息由本插件写进会话历史（见 inboxRecords）
+    archive: optional(messageArchive),
 };
 export default definePlugin({
     name,
@@ -198,28 +267,27 @@ export default definePlugin({
 });
 async function startWebuiServer(caps) {
     const { events, logger, lifecycle, provide, services } = caps;
-    const config = caps.config;
+    const cfg = parseConfig(configSchema, caps.config.use, logger.use);
     const uiConfig = {
-        port: config.port ?? 3000,
-        host: config.host ?? '127.0.0.1',
-        fileRoot: config.fileRoot || 'workspace',
-        autoOpen: config.autoOpen ?? true,
-        tokenMode: ['ephemeral', 'fixed'].includes(config.tokenMode)
-            ? config.tokenMode
-            : 'persist',
-        fixedToken: config.fixedToken ?? '',
-        marketplaceRegistry: config.marketplaceRegistry?.trim() || 'https://registry.npmjs.org',
+        ...cfg,
+        marketplaceRegistry: cfg.marketplaceRegistry.trim() || configSchema.marketplaceRegistry.default,
     };
-    // 创建 storage gateway；所有文件读写（token、access、文件管理）都走这里
-    const storage = createStorageGateway(caps.storage);
+    if (!URL.canParse(uiConfig.marketplaceRegistry))
+        throw configError('marketplaceRegistry 不是有效 URL');
+    // 创建 storage gateway；所有文件读写（token、访问凭据、媒体与会话文件）都走这里
+    const storage = caps.storage.use;
     // ---- Token 解析 ----
     // - ephemeral：每次启动随机生成（旧行为）
     // - persist：首次生成后写入 storage data:/webui/token，重启复用（默认）
-    // - fixed：使用 fixedToken 配置项；为空时降级为 persist
+    // - fixed：使用 fixedToken 配置项，至少 FIXED_TOKEN_MIN_LENGTH 个字符；为空时降级为 persist
     // 所有模式都会写出 data:/webui/access.txt 便于查找访问 URL
+    // 两个文件都是凭据，按凭据写（只给本机用户读，0600）
     const tokenFileUri = 'data:/webui/token';
     const accessFileUri = 'data:/webui/access.txt';
     const fixedToken = uiConfig.tokenMode === 'fixed' ? uiConfig.fixedToken.trim() : '';
+    if (fixedToken && fixedToken.length < FIXED_TOKEN_MIN_LENGTH) {
+        throw configError(`fixedToken 至少要 ${FIXED_TOKEN_MIN_LENGTH} 个字符（现在 ${fixedToken.length} 个）`);
+    }
     let authToken = fixedToken || Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString('hex');
     /** 监听成功后的访问 URL；持久化 token 晚于监听读回时，据此重写 access.txt */
     let listeningUrl;
@@ -237,11 +305,11 @@ async function startWebuiServer(caps) {
             '# 提示：将该一键登录链接粘贴到浏览器即可自动设置 cookie',
         ];
         try {
-            await storage.writeFile(accessFileUri, `${lines.join('\n')}\n`);
+            await storage.writeFile(accessFileUri, `${lines.join('\n')}\n`, { secret: true });
             return true;
         }
         catch (err) {
-            logger.warn(`写入访问文件失败: ${err.message}`);
+            logger.use.warn(`写入访问文件失败: ${err.message}`);
             return false;
         }
     }
@@ -251,8 +319,7 @@ async function startWebuiServer(caps) {
     // follow 对已在线的 storage 同步首挂，晚上线时补读。持久化的那份优先（浏览器里 30 天的 cookie
     // 就是它）；只认第一次成功，之后 storage 换人不再换 token。
     let tokenSettled = uiConfig.tokenMode === 'ephemeral' || fixedToken !== '';
-    // autoOpen 只在 token 是本次新生成时打开浏览器：沿用已有 token（fixed、persist 读回）时浏览器里的 cookie 仍有效，
-    // 再开一页只是重复。app:ready 是粘性事件，本插件每次 bounce 都会重新收到，不按此判断就每次重载多开一个标签页
+    // token 重新生成后旧页面失效，即使同一 App 已打开过，也要给出新的登录页。
     let tokenFresh = fixedToken === '';
     let tokenLoading;
     caps.storage.follow(() => {
@@ -270,6 +337,10 @@ async function startWebuiServer(caps) {
                         if (listeningUrl)
                             void writeAccessFile(listeningUrl, authToken);
                     }
+                    // 读回的照样按凭据重写一遍：文件原先的权限（别处拷来、按默认权限写下的）一律收紧
+                    await storage
+                        .writeFile(tokenFileUri, existing, { secret: true })
+                        .catch((err) => logger.use.warn(`token 文件没能按凭据重写，别的系统用户可能读得到它: ${err.message}`));
                     return;
                 }
             }
@@ -277,11 +348,11 @@ async function startWebuiServer(caps) {
                 /* 不存在或读不了 */
             }
             try {
-                await storage.writeFile(tokenFileUri, authToken);
+                await storage.writeFile(tokenFileUri, authToken, { secret: true });
                 tokenSettled = true;
             }
             catch (err) {
-                logger.warn(`持久化 token 失败，本次仍可使用但重启会再生成: ${err.message}`);
+                logger.use.warn(`持久化 token 失败，本次仍可使用但重启会再生成: ${err.message}`);
             }
         })();
     });
@@ -290,43 +361,55 @@ async function startWebuiServer(caps) {
         await tokenLoading;
     const auth = createAuthSystem(() => authToken);
     const expressApp = express();
+    // 文档级 CSP：脚本只许同源，样式放开内联（Mermaid 的输出带内联样式），图片只认同源与本地生成的；不许被别的页面嵌入。
+    // 每个响应都带上，前端的 HTML、登录页与恢复页都在其中；媒体路由另设更严的沙箱，插件前端的文件另设框架 CSP
+    expressApp.use((_req, res, next) => {
+        res.setHeader('Content-Security-Policy', DOCUMENT_CSP);
+        next();
+    });
+    // 插件前端的文件：注册在认证之前，凭页面登记时的 token 取，不看 cookie
+    registerFrameRoutes(expressApp, token => pages.frameDir(token));
     expressApp.use(express.json({ limit: '10mb' }));
-    expressApp.use(auth.middleware);
+    auth.install(expressApp);
     // REST 路由 owner 闸（连接级认证之上的显式 owner 复核，见 gate.ts）。
     // 当前身份 / 登录态查询统一走 auth.ts 的 GET /api/auth/status（含 identity）。
     const gate = createRouteGate(auth.identify);
     const server = createServer(expressApp);
+    // server.close() 只停止 accept 并关掉此刻闲着的连接；拆卸时还在处理请求的 keep-alive 连接（例如重载自己的那次）
+    // 应答完会留下来，后面的请求照样落到已拆卸的旧实例。拆卸之后每次应答完就关掉闲下来的连接，浏览器改开新连接
+    server.on('request', (_req, res) => res.on('finish', () => {
+        if (!server.listening)
+            server.closeIdleConnections();
+    }));
+    // 一个 WebSocketServer 接全部端点，连接按路径分给各自的处理，来源校验与认证对各端点一样。同一个 HTTP server 上
+    // 挂两个带 path 的 WebSocketServer 不行：先挂的那个会把别的路径的升级请求按 400 拒掉。
+    const wsPaths = new Set([SESSION_PATH, ADMIN_PATH]);
+    const wsPath = (req) => (req.url ?? '').split('?')[0];
+    const approvalSurface = caps.approvals.use.registerSurface('webui');
     const wss = new WebSocketServer({
         server,
-        path: '/ws',
         verifyClient: (info, cb) => {
-            if (auth.verifyWsClient(info.req))
-                cb(true);
-            else
+            if (!originAllowed(info.req))
+                cb(false, 403, 'origin not allowed');
+            else if (!auth.verifyWsClient(info.req))
                 cb(false, 401, 'unauthenticated');
+            else if (!wsPaths.has(wsPath(info.req)))
+                cb(false, 404);
+            else
+                cb(true);
         },
     });
-    const sessions = new Map();
-    const logSubscribers = new Set();
-    const allClients = new Set();
+    // 日志按插件筛时用登记表分开后缀实例与插件分出的子作用域
+    const matchLogs = logMatcher(instance => (caps.plugins.present ? caps.plugins.use.getPlugin(instance) : undefined) !== undefined);
+    const admin = createAdminChannel(logger.use, matchLogs);
+    /** 打开着的 /session 连接：webui 平台的连接状态按它数 */
+    const sessionSockets = new Set();
     // 半开连接回收：清理只挂 'close' 时，睡眠/断网的客户端永远等不到事件，
     // 日志广播持续往死连接的发送缓冲堆数据。详见 ws-heartbeat.ts。
     const heartbeat = createWsHeartbeat({
-        onStale: ws => logger.debug(`WebUI 客户端心跳超时，回收半开连接 (bufferedAmount=${ws.bufferedAmount})`),
-        onError: (_ws, err) => logger.warn(`WebUI 客户端连接错误: ${err.message}`),
+        onStale: ws => logger.use.debug(`WebUI 客户端心跳超时，回收半开连接 (bufferedAmount=${ws.bufferedAmount})`),
+        onError: (_ws, err) => logger.use.warn(`WebUI 客户端连接错误: ${err.message}`),
     });
-    const streamBuffers = new Map();
-    // 延迟清理 streamBuffers：捕获要删的 buf 引用，10s 后仅当 (a) 该 session 仍是
-    // 同一个 buf 且 (b) 未重新进入生成态 时才删——防止 10s 内开始的新一轮生成被旧
-    // 定时器误删（审计 HIGH #8 竞态）。
-    const scheduleBufferCleanup = (sid, captured) => {
-        setTimeout(() => {
-            if (streamBuffers.get(sid) === captured && !captured.generating)
-                streamBuffers.delete(sid);
-        }, 10_000);
-    };
-    // Token 用量缓存：记录每个 session 最近一次的 token 用量，用于刷新/切换会话后立即展示
-    const tokenUsageCache = new Map();
     // 前端静态文件托管：前端包不是插件（无 apply，纯静态资源），托管权在本插件——
     // app:ready 时由 client-discovery 按 `aalis.client` 标记发现候选，本插件把每个候选注册成
     // 一条 webui-client 服务 provider，再由服务解析（偏好 > 优先级 > 注册顺序）定出活跃前端。
@@ -335,11 +418,11 @@ async function startWebuiServer(caps) {
     function mountStaticDir(dir) {
         if (existsSync(dir)) {
             staticMiddleware = express.static(dir);
-            logger.info(`前端静态目录: ${dir}`);
+            logger.use.info(`前端静态目录: ${dir}`);
         }
         else {
             staticMiddleware = null;
-            logger.warn(`前端目录不存在: ${dir}`);
+            logger.use.warn(`前端目录不存在: ${dir}`);
         }
     }
     // 已发现的前端候选（app:ready 时填充，逐个注册为 webui-client 服务 provider）。
@@ -354,11 +437,12 @@ async function startWebuiServer(caps) {
     const clientProviderDisposers = new Map();
     /** 当前活跃前端目录 = 解析后的 webui-client 服务（servicePreferences 偏好 > 优先级 > 注册顺序）。 */
     function currentClientDir() {
-        return services.get(webuiClient)?.getClientDir?.();
+        // 动态查而不写进 uses：条目多由本插件代前端包登记，声明它会让本插件的按插件偏好也改到选择，静态目录的重挂只跟全局偏好
+        return services.use.get(webuiClient)?.getClientDir?.();
     }
     /**
-     * 切换 webui-client 服务偏好后调用：重挂当前活跃前端 + 广播 'reload'——所有客户端进入
-     * 「正在切换前端，即将刷新」遮罩后自动 reload（复用现有刷新流程，平滑换前端、不重启进程）。
+     * 活跃前端可能变了时调用（改或清除 webui-client 的服务偏好、摘掉已不在的前端包）：重挂当前活跃前端，
+     * 经 /admin 推 client.reload 让页面整页重载，换前端不重启进程。
      */
     function remountActiveClient() {
         const dir = currentClientDir();
@@ -366,11 +450,7 @@ async function startWebuiServer(caps) {
             clientDist = dir;
             mountStaticDir(dir);
         }
-        const payload = { type: 'reload' };
-        const json = JSON.stringify(payload);
-        for (const ws of allClients)
-            if (ws.readyState === WebSocket.OPEN)
-                ws.send(json);
+        admin.send({ type: 'client.reload' });
     }
     // 动态静态文件中间件（支持运行时切换前端）
     expressApp.use((req, res, next) => {
@@ -382,35 +462,6 @@ async function startWebuiServer(caps) {
         }
     });
     // ---------- REST API ----------
-    // 获取系统状态
-    expressApp.get('/api/status', gate(), (_req, res) => {
-        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;
-        const appName = caps.hostConfig.current?.get('name') ?? 'Aalis';
-        res.json({
-            /** 对话对象的显示名：装有人设时是人设名，否则同 appName */
-            name: personaSvc?.getPersonaName() ?? appName,
-            /** 全局配置里的应用名称，每次实时读配置文档 */
-            appName,
-            /** 上传能力：客户端据此决定显示哪些上传按钮 */
-            uploadCapabilities: {
-                /** 是否支持图片上传（media 可用 或 LLM 声明了 vision） */
-                image: hasMedia || llmHasVision,
-                /** 是否支持文件上传（file-reader 可用） */
-                file: hasFileReader,
-            },
-            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,
-            })),
-        });
-    });
     // ---------- 插件管理 + 全局配置 ----------
     // fs 扫描 env：discoverClients（app:ready 时）与市场「已装」兜底共用一份，避免两处重复。
     const fsScanEnv = {
@@ -433,8 +484,10 @@ async function startWebuiServer(caps) {
         },
         join: (...parts) => resolve(...parts),
     };
-    // 页面动作登记表：插件经 webui-server 的绑定接口登记，路由层按「插件 id + 方法名」查
-    const registeredActions = new Map();
+    // 市场「已装」判定、依赖图、插件列表的版本与前端候选发现共用这一份扫描目录（pnpm 工作区下 require.resolve
+    // 从仓库根解析不到工作区包，只能扫盘）。每请求懒扫，量小。host-paths 由宿主在根上提供，不会中途换。
+    const appDir = caps.paths.present ? caps.paths.use.app : undefined;
+    const scanDirs = localScanDirs(appDir);
     registerPluginRoutes(expressApp, {
         app: caps.app,
         plugins: caps.plugins,
@@ -442,48 +495,87 @@ async function startWebuiServer(caps) {
         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;
+        services: services.use,
+        self: lifecycle.use.id,
+        home: caps.paths.present ? caps.paths.use.home : undefined,
+        versions: () => {
+            if (!appDir)
+                return () => undefined;
+            const lookup = localPackageLookup(appDir, collectLocalPackageDeps(scanDirs, fsScanEnv));
+            return name => lookup(name)?.version;
+        },
+        logger: logger.use,
+    }, gate);
+    // 页面：插件经 webui-server 的绑定接口登记，页面的数据源与动作、插件前端的文件、会话面板与布局记录的路由按这张登记表分派
+    const pageFiles = createPageFiles(() => (caps.storage.present ? storage.listRoots() : []));
+    const pages = createPageRegistry({
+        logger: logger.use,
+        send: event => admin.send(event),
+        sessions: caps.sessions,
+        signFile: pageFiles.sign,
+    });
+    registerPageRoutes(expressApp, {
+        registry: pages,
+        layout: createLayoutStore(storage.own, logger.use),
+        storageReady: () => caps.storage.present,
+        send: event => admin.send(event),
+        logger: logger.use,
+    }, auth.identify, gate);
     registerMarketplaceRoutes(expressApp, {
-        logger,
+        logger: logger.use,
         plugins: caps.plugins,
-        services,
+        services: services.use,
         packageManager: caps.packageManager,
-    }, gate, uiConfig.marketplaceRegistry, () => collectLocalPackageDeps(localScanDirs, fsScanEnv), () => discoverAndProvideClients());
-    // 历史日志从 data/latest.log 读（lazy load）。
-    // 单进程内 LogHub 不再缓存 buffer——历史以文件为单一数据源。
-    // 尾部 N 条（首屏 / 显式刷新）
-    expressApp.get('/api/logs/tail', gate(), async (req, res) => {
-        const limit = Math.min(Math.max(Number(req.query.limit) || 200, 1), 5000);
-        try {
-            res.json(await readLogFileTail(storage, limit));
+        appDir,
+    }, gate, uiConfig.marketplaceRegistry, () => collectLocalPackageDeps(scanDirs, fsScanEnv), () => discoverAndProvideClients());
+    // 「需要处理」：推出未结的审批、插件故障与提示，界面的首页摘要、插件详情与标签页标题都读这一个列表
+    const attention = createAttention({
+        approvals: () => (caps.approvals.present ? caps.approvals.use.list() : []),
+        sessions: caps.sessions,
+        plugins: () => {
+            const pm = caps.plugins.present ? caps.plugins.use : undefined;
+            return pm
+                ? blockedStatus({
+                    plugins: pm,
+                    services: services.use,
+                    doc: caps.hostConfig.present ? caps.hostConfig.use : undefined,
+                })
+                : [];
+        },
+        notices: pages.notices,
+        send: event => admin.send(event),
+    });
+    route(expressApp, 'GET /api/attention', gate(), (_req, res) => {
+        res.json({ items: attention.items() });
+    });
+    /** 按查询参数里的筛选读日志的历史回给前端，给了 before 时往前翻；筛选写法不对回 400 */
+    const sendLogs = async (query, res, before) => {
+        const filter = parseLogFilter(query);
+        if (!filter) {
+            res.status(400).json({ error: '日志筛选写法不对：level 只收 debug、info、warn、error，每一项最多给一次' });
+            return;
         }
-        catch (err) {
-            res.status(500).json({ error: err.message });
+        if (!caps.logs.present) {
+            res.status(503).json({ error: '宿主未提供日志服务（host-logs），读不到日志' });
+            return;
         }
-    });
-    // 历史分页：返回 seq < before 的最近 limit 条（向上滚动加载更早）
-    expressApp.get('/api/logs/range', gate(), async (req, res) => {
+        const limit = Math.min(Math.max(Number(query.limit) || 200, 1), 5000);
+        res.json(await caps.logs.use.recent(limit, { before, match: matchLogs(filter) }));
+    };
+    // 日志的历史：最后 limit 条
+    route(expressApp, 'GET /api/logs/tail', gate(), (req, res) => sendLogs(req.query, res));
+    // 往前翻：seq 比 before 小的最后 limit 条
+    route(expressApp, 'GET /api/logs/range', gate(), (req, res) => {
         const before = Number(req.query.before);
-        const limit = Math.min(Math.max(Number(req.query.limit) || 200, 1), 5000);
         if (!Number.isFinite(before)) {
-            res.status(400).json({ error: 'before query param required' });
+            res.status(400).json({ error: '往前翻日志要给数字参数 before（取 seq 比它小的那几条）' });
             return;
         }
-        try {
-            res.json(await readLogFileBefore(storage, before, limit));
-        }
-        catch (err) {
-            res.status(500).json({ error: err.message });
-        }
+        return sendLogs(req.query, res, before);
     });
     // 获取服务列表（含提供者信息）
-    expressApp.get('/api/services', gate(), async (_req, res) => {
-        const pluginMgr = caps.plugins.current;
+    route(expressApp, 'GET /api/services', gate(), async (_req, res) => {
+        const pluginMgr = caps.plugins.present ? caps.plugins.use : undefined;
         const pluginStatus = pluginMgr ? pluginMgr.getStatus() : [];
         const displayNameMap = new Map();
         for (const p of pluginStatus) {
@@ -495,11 +587,11 @@ async function startWebuiServer(caps) {
         // 根激活归宿主：core 的内置服务与宿主登记的 host-config / plugin-source 都在这里（与市场依赖图同一标签）。
         // 别把内部 id 'root' 裸露给用户。
         displayNameMap.set('root', '宿主');
-        const serviceNames = services.names();
+        const serviceNames = services.use.names();
         const detail = {};
         for (const svcName of serviceNames) {
             // 枚举已按「偏好 > 优先级 > 注册顺序」排序，附带 priority 字段；只取登记元数据，不取实例
-            const entries = services.inspect(svcName);
+            const entries = services.use.inspect(svcName);
             detail[svcName] = {
                 providers: entries.map(e => ({
                     contextId: e.contextId,
@@ -508,210 +600,107 @@ async function startWebuiServer(caps) {
                     priority: e.priority,
                     exclusive: e.exclusive,
                 })),
-                preferred: services.preferred(svcName) ?? null,
+                preferred: services.use.preferred(svcName) ?? null,
             };
         }
         res.json({ services: detail });
     });
     /**
-     * 设置服务偏好。body: { contextId: string }
-     * 偏好语义：`preferred > priority > 注册顺序`。持久化到 aalis.config.yaml 的 servicePreferences。
+     * 改服务偏好，contextId 为 null 即清除：scope 不给 `for` 是全局偏好，给了是只对那个插件实例的本插件偏好。
+     * 挑选规则：本插件偏好 > 全局偏好 > priority > 注册顺序。偏好要跨重启保留就得写进文档（servicePreferences /
+     * pluginServicePreferences），宿主没提供文档时不动运行态
      */
-    expressApp.post('/api/services/:name/prefer', gate(), async (req, res) => {
-        const svcName = String(req.params.name);
-        const contextId = String(req.body?.contextId ?? '').trim();
-        if (!contextId) {
-            res.status(400).json({ ok: false, error: 'contextId required' });
+    const changePreference = async (svcName, contextId, scope, res) => {
+        if (contextId !== null && !services.use.inspect(svcName).some(e => e.contextId === contextId)) {
+            res.status(404).json({ error: `服务 ${svcName} 没有 id 为 ${contextId} 的提供者` });
             return;
         }
-        // 校验 entry 存在
-        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}"` });
+        if (!caps.hostConfig.present) {
+            res.status(503).json({ error: '宿主未提供配置文档（host-config），无法保存偏好' });
             return;
         }
-        // 偏好要跨重启保留就得写进文档：宿主没提供文档时不动运行态
-        const host = caps.hostConfig.current;
-        if (!host) {
-            res.status(503).json({ ok: false, error: '宿主未提供配置文档（host-config），无法保存偏好' });
-            return;
+        const host = caps.hostConfig.use;
+        if (contextId === null) {
+            services.use.unprefer(svcName, scope);
+            host.removeServicePreference(svcName, scope);
         }
-        if (!services.prefer(svcName, contextId)) {
-            res.status(409).json({ ok: false, error: `service "${svcName}" rejected provider preference "${contextId}"` });
-            return;
+        else {
+            services.use.prefer(svcName, contextId, scope);
+            host.setServicePreference(svcName, contextId, scope);
         }
-        host.setServicePreference(svcName, contextId);
-        // 切换前端：webui-client 是「前端」服务，偏好变更需重挂静态目录 + 通知客户端刷新。
+        // 切换前端：webui-client 是「前端」服务，全局偏好变更需重挂静态目录 + 通知客户端刷新。
         // 重挂与偏好同属内存态，必须在等落盘之前一起生效：save 拒绝时才不会留下「解析选 B、静态挂 A」。
-        if (svcName === 'webui-client')
+        if (svcName === 'webui-client' && scope.for === undefined)
             remountActiveClient();
-        if (!(await saveAfterApply(host, res, 'restart')))
+        if (!(await saveAfterApply(host, res, 'reload')))
             return;
         res.json({ ok: true });
+    };
+    const preferredIn = (body) => String(body?.contextId ?? '').trim();
+    route(expressApp, 'POST /api/services/:name/prefer', gate(), async (req, res) => {
+        const contextId = preferredIn(req.body);
+        if (!contextId) {
+            res.status(400).json({ error: '请求体要给 contextId：偏好的那个提供者的 id' });
+            return;
+        }
+        await changePreference(String(req.params.name), contextId, {}, res);
     });
-    /** 清除服务偏好 */
-    expressApp.delete('/api/services/:name/prefer', gate(), async (req, res) => {
-        const svcName = String(req.params.name);
-        const host = caps.hostConfig.current;
-        if (!host) {
-            res.status(503).json({ ok: false, error: '宿主未提供配置文档（host-config），无法保存偏好' });
+    route(expressApp, 'DELETE /api/services/:name/prefer', gate(), (req, res) => changePreference(String(req.params.name), null, {}, res));
+    route(expressApp, 'POST /api/plugins/:instanceId/services/:name/prefer', gate(), async (req, res) => {
+        const contextId = preferredIn(req.body);
+        if (!contextId) {
+            res.status(400).json({ error: '请求体要给 contextId：偏好的那个提供者的 id' });
             return;
         }
-        services.unprefer(svcName);
-        host.removeServicePreference(svcName);
-        if (svcName === 'webui-client')
-            remountActiveClient();
-        if (!(await saveAfterApply(host, res, 'restart')))
+        const instanceId = String(req.params.instanceId);
+        if (!caps.plugins.present || !caps.plugins.use.getPlugin(instanceId)) {
+            res.status(404).json({ error: `插件 ${instanceId} 不存在` });
             return;
-        res.json({ ok: true });
+        }
+        await changePreference(String(req.params.name), contextId, { for: instanceId }, res);
+    });
+    route(expressApp, 'DELETE /api/plugins/:instanceId/services/:name/prefer', gate(), (req, res) => changePreference(String(req.params.name), null, { for: String(req.params.instanceId) }, res));
+    // 插件经贡献点提供的主题：与导入的主题同一套校验，不合格式的不列出、每份告警一次。插件停用时贡献随之撤回，
+    // 界面收到 plugins.changed 后重取。贡献点服务不在时没有插件主题
+    const warnedThemes = new WeakSet();
+    route(expressApp, 'GET /api/themes', gate(), (_req, res) => {
+        const themes = [];
+        for (const { key, spec } of caps.contributions.present ? caps.contributions.use.collect('webui:theme') : []) {
+            const parsed = parseTheme(spec.theme);
+            if (parsed.ok)
+                themes.push({ id: key, instance: key.slice(0, key.lastIndexOf('/')), theme: parsed.theme });
+            else if (!warnedThemes.has(spec)) {
+                warnedThemes.add(spec);
+                logger.use.warn(`插件主题 ${key} 不合主题文件的格式，没有列出：${parsed.errors.join('；')}`);
+            }
+        }
+        res.json({ themes });
     });
     // 前端切换已统一到「服务偏好」：前端是 webui-client 服务的多 provider，切换走
     // POST /api/services/webui-client/prefer（见上），webui-server 在该偏好变更时重挂 + 广播刷新。
     // 故不再有独立的 /api/clients* 路由。
     // 获取所有平台适配器及其连接状态
-    expressApp.get('/api/platforms', gate(), (_req, res) => {
+    route(expressApp, 'GET /api/platforms', gate(), (_req, res) => {
         res.json({ platforms: aggregatePlatformDetails(caps.platform) });
     });
-    // 获取已注册的工具分组（含元数据 + 各组工具数量 + 贡献插件列表）
-    expressApp.get('/api/tool-groups', gate(), (_req, res) => {
-        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));
-            // 贡献插件 = 该分组下所有工具的 pluginName 去重（可能跨多个插件，
-            // 例如 'session-history' 同时被 plugin-tool-session 与 plugin-memory-history 贡献）
-            const contributingPlugins = [...new Set(toolsInGroup.map(t => t.pluginName))].sort();
-            return { ...g, description: descSummary(g.description), toolCount: toolsInGroup.length, contributingPlugins };
-        });
-        // 兜底：未声明任何 group 或 group 不在已注册集合中的工具，聚成 "other" 组
-        const orphans = allTools.filter(t => {
-            const gs = t.groups ?? [];
-            return gs.length === 0 || gs.every(n => !knownNames.has(n));
-        });
-        if (orphans.length > 0) {
-            result.push({
-                name: 'other',
-                label: '其他',
-                description: '未声明分组的工具',
-                pluginName: '(system)',
-                toolCount: orphans.length,
-                contributingPlugins: [...new Set(orphans.map(t => t.pluginName))].sort(),
-            });
-        }
-        res.json({ groups: result });
-    });
-    // 获取服务分组（manifest 驱动：每个插件自己声明 subsystem，本路由仅聚合）
-    expressApp.get('/api/service-groups', gate(), (_req, res) => {
-        const pluginMgr = caps.plugins.current;
-        const pluginStatus = pluginMgr ? pluginMgr.getStatus() : [];
-        // 按插件 subsystem 归组（未声明 → 'external'）。subsystem 是插件定义上的展示标签，
-        // core 状态契约不含——从定义直接读。
-        const groupsMap = new Map();
-        for (const p of pluginStatus) {
-            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 ?? [] });
-        }
-        // 排序：DEFAULT_SUBSYSTEM_METADATA 已知 id 优先按 order 排，未知 id 以 id 作为 label，order=9999
-        const meta = new Map(DEFAULT_SUBSYSTEM_METADATA.map(e => [e.id, e]));
-        const sorted = [...groupsMap.keys()]
-            .map(id => {
-            const m = meta.get(id);
-            return m ? { id, label: m.label, order: m.order } : { id, label: id, order: 9999 };
-        })
-            .sort((a, b) => a.order - b.order || a.id.localeCompare(b.id));
-        // First-claim-wins：服务名只归入最先（order 最小）声明它的组，避免同一服务出现在多个分组
-        const servicesClaimed = new Set();
-        const groups = sorted.map(({ id, label }) => {
-            const plugins = groupsMap.get(id);
-            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: owned };
-        });
-        // 系统内建服务（app、plugins 等由 core 直接 provide，不属于任何插件）
-        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 });
-        }
-        res.json({ groups });
-    });
-    // 获取所有 LLM 模型（枚举所有注册的 per-model entry）
-    expressApp.get('/api/llm-models', gate(), async (_req, res) => {
-        try {
-            const entries = caps.llm.all();
-            const models = entries.map(e => ({
-                id: e.instance.id,
-                capabilities: [...e.instance.capabilities],
-                provider: e.instance.providerId,
-                contextId: e.contextId,
-            }));
-            res.json({ models });
-        }
-        catch {
-            res.json({ models: [] });
-        }
-    });
-    // LLM providers + per-provider models（供 schema type='llm-ref' 联动 select 使用）
-    expressApp.get('/api/llm-providers', gate(), async (_req, res) => {
-        try {
-            const entries = caps.llm.all();
-            const byProvider = new Map();
-            // entry.label 形如 "Ollama (localhost:11434) / qwen3.6:35b-mlx"；
-            // 取第一个 " / " 之前的部分作为 providerLabel（避免把 model id 也带进去）。
-            const extractProviderLabel = (raw) => {
-                if (!raw)
-                    return undefined;
-                const slash = raw.indexOf(' / ');
-                return slash > 0 ? raw.slice(0, slash) : raw;
-            };
-            for (const e of entries) {
-                const providerId = e.instance.providerId;
-                let agg = byProvider.get(providerId);
-                if (!agg) {
-                    agg = { contextId: providerId, label: extractProviderLabel(e.label), models: [] };
-                    byProvider.set(providerId, agg);
-                }
-                else if (!agg.label) {
-                    agg.label = extractProviderLabel(e.label);
-                }
-                agg.models.push({
-                    id: e.instance.id,
-                    capabilities: [...e.instance.capabilities],
-                    contextLength: e.instance.contextLength,
-                });
-            }
-            res.json({ providers: [...byProvider.values()] });
-        }
-        catch {
-            res.json({ providers: [] });
-        }
-    });
-    // 触发指定 provider 重新探测远端模型列表（用于 webui 上的"刷新模型"按钮）
-    // 仅对在 LLMModel 上实现了 refresh() 的 provider 生效（远端动态发现型，如 Ollama / OpenAI）。
+    // 触发指定 provider 重新探测远端模型列表（插件配置里模型字段旁的「刷新」按钮）
+    // 仅对在 LLMModel 上实现了 refresh() 的 provider 生效（远端动态发现型）。
     // 同 provider 下所有 model entries 共享同一份 refresh 闭包，调任一个 entry 即可。
-    // 按 providerId 找条目，与 /api/llm-providers 的聚合同一口径：条目的 contextId 是 `<provider>/<model>`，不等于 provider
-    expressApp.post('/api/llm-providers/:contextId/refresh', gate(), async (req, res) => {
+    // 按 providerId 找条目，与 /api/models/llm 给的 contextId 同一口径：条目自己的 contextId 是 `<provider>/<model>`，不等于 provider
+    route(expressApp, 'POST /api/llm-providers/:contextId/refresh', gate(), async (req, res) => {
         const contextId = req.params.contextId;
         try {
-            const llmEntries = caps.llm.all().filter(e => e.instance.providerId === contextId);
-            const target = llmEntries.find(e => typeof e.instance.refresh === 'function');
+            const llmEntries = caps.llm.list().filter(e => e.use.providerId === contextId);
+            const target = llmEntries.find(e => typeof e.use.refresh === 'function');
             if (!target) {
                 res.status(404).json({
                     error: llmEntries.length > 0
-                        ? `提供者 ${contextId} 不支持运行时刷新模型列表（例如关闭了模型发现 discoverModels）`
+                        ? `提供者 ${contextId} 不支持运行时刷新模型列表（例如关闭了模型发现）`
                         : `提供者 ${contextId} 当前没有已注册的模型，无法刷新`,
                 });
                 return;
             }
-            const result = await target.instance.refresh();
+            const result = await target.use.refresh();
             res.json({ ok: true, ...result });
         }
         catch (err) {
@@ -719,21 +708,20 @@ async function startWebuiServer(caps) {
         }
     });
     // 获取某个服务的可用模型/选项列表
-    expressApp.get('/api/models/:service', gate(), async (req, res) => {
+    route(expressApp, 'GET /api/models/:service', gate(), async (req, res) => {
         const serviceName = req.params.service;
         // 特殊处理 platform：通过 helper 获取已注册的平台名称
         if (serviceName === 'platform') {
             res.json({ models: getPlatformNames(caps.platform) });
             return;
         }
-        // 特殊处理 gateway-scopes：基于已注册 adapter.sessionTypes 真实声明生成
-        // platform×sessionType 的笛卡尔积。无声明的 adapter 视为单会话（不展开 sessionType）。
+        // 特殊处理 gateway-scopes：已注册平台与它们的类型名（sessionTypesOf：没声明类型的平台只有一个类型 private）
+        // 的笛卡尔积
         if (serviceName === 'gateway-scopes') {
-            const adapters = getPlatformAdapters(caps.platform);
             const platformTypes = new Map();
             const allTypes = new Set();
-            for (const a of adapters) {
-                const types = a.sessionTypes ?? [];
+            for (const a of getPlatformAdapters(caps.platform)) {
+                const types = sessionTypesOf(a).map(t => t.name);
                 platformTypes.set(a.platform, types);
                 for (const t of types)
                     allTypes.add(t);
@@ -744,23 +732,42 @@ async function startWebuiServer(caps) {
                 scopes.push({ value: `*:${t}`, label: `*:${t} （所有平台的 ${t} 会话）` });
             }
             for (const [p, types] of platformTypes) {
-                if (types.length === 0) {
-                    // 单会话平台 (cli/webui)：只列 platform 通配
-                    scopes.push({ value: `${p}:*`, label: `${p}:* （${p} 单会话）` });
-                }
-                else {
-                    scopes.push({ value: `${p}:*`, label: `${p}:* （${p} 全部类型）` });
-                    for (const t of types)
-                        scopes.push({ value: `${p}:${t}`, label: `${p}:${t}` });
-                }
+                scopes.push({ value: `${p}:*`, label: `${p}:* （${p} 全部类型）` });
+                for (const t of types)
+                    scopes.push({ value: `${p}:${t}`, label: `${p}:${t}` });
             }
             res.json({ models: scopes.map(s => s.value), details: scopes });
             return;
         }
+        // 深度思考的档位：可选项依赖「模型」这一项，dependency 带它的生效值；没带时按服务偏好解析，与对话时同一种解析。
+        // 默认档标 default（没设时界面据它写按哪一档跑），模型不能调时没有可选项。labels 是各模型声明过的档位的名字
+        // （同一个 id 取先登记的）：换了模型以后存着的档位不在可选项里，界面按它写出名字
+        if (serviceName === 'llm-thinking') {
+            const ref = modelRefOf(req.query.dependency);
+            if (ref === null) {
+                res.status(400).json({ error: 'dependency 要是模型引用 { provider, model } 的 JSON' });
+                return;
+            }
+            const thinking = resolveLLMModel(caps.llm, ref, ['chat'])?.use.thinking;
+            const levels = thinking?.levels ?? [];
+            const labels = {};
+            for (const entry of caps.llm.list()) {
+                for (const level of entry.use.thinking?.levels ?? [])
+                    labels[level.id] ??= level.label;
+            }
+            res.json({
+                models: levels.map(level => level.id),
+                details: levels.map(level => level.id === thinking?.default
+                    ? { value: level.id, label: level.label, default: true }
+                    : { value: level.id, label: level.label }),
+                labels,
+            });
+            return;
+        }
         // 特殊处理 toolGroups：优先从工具分组注册表获取，回退到扫描工具
         if (serviceName === 'toolGroups') {
-            const groups = caps.tools.current?.getGroups() ?? [];
-            // '*' = 全部分组（plugin-tools 的分组过滤认它），与会话范围选项的「* （全部平台）」同一写法
+            const groups = caps.tools.present ? caps.tools.use.getGroups() : [];
+            // '*' = 全部分组（api-tools 的分组约定），与会话范围选项的「* （全部平台）」同一写法
             if (groups.length > 0) {
                 res.json({
                     models: ['*', ...groups.map(g => g.name).sort()],
@@ -777,7 +784,7 @@ async function startWebuiServer(caps) {
             }
             else {
                 // 回退：从已注册工具中提取分组名称
-                const allTools = caps.tools.current?.getAll() ?? [];
+                const allTools = caps.tools.present ? caps.tools.use.getAll() : [];
                 const groupSet = new Set();
                 for (const t of allTools) {
                     t.groups?.forEach((g) => {
@@ -788,588 +795,191 @@ async function startWebuiServer(caps) {
             }
             return;
         }
-        // LLM 走 per-model entry 枚举（每个 entry 已对应一个具体 model，不再依赖 provider.listModels）
+        // LLM 走 per-model entry 枚举（每个 entry 已对应一个具体 model，不再依赖 provider.listModels）。
+        // contextId 给提供者的实例 id（条目自己的是 `<实例 id>/<模型 id>`）：llm-ref 的取值 { provider, model } 认的是它
         if (serviceName === 'llm') {
             try {
-                const entries = caps.llm.all();
-                const aggregated = entries.map(e => ({
-                    value: `${e.contextId}::${e.instance.id}`,
-                    model: e.instance.id,
-                    provider: e.label ?? e.contextId,
-                    contextId: e.contextId,
-                    capabilities: [...e.instance.capabilities],
+                const entries = caps.llm.list();
+                const providers = entries.map(e => ({
+                    model: e.use.id,
+                    provider: e.label ?? e.id,
+                    contextId: e.use.providerId,
+                    capabilities: [...e.use.capabilities],
                 }));
-                res.json({ models: aggregated.map(a => a.value), providers: aggregated });
+                res.json({ providers });
             }
             catch {
-                res.json({ models: [] });
+                res.json({ providers: [] });
             }
             return;
         }
-        const service = services.get(serviceName);
-        if (!service || typeof service.listModels !== 'function') {
-            res.json({ models: [] });
-            return;
-        }
-        try {
-            // 聚合所有提供者的模型列表（embedding 等服务仍走 listModels()）。
-            const allProviders = services.all(serviceName);
-            const aggregated = [];
-            const flatValues = [];
-            for (const provider of allProviders) {
-                if (typeof provider.instance.listModels !== 'function')
-                    continue;
-                try {
-                    const models = await provider.instance.listModels();
-                    for (const m of models) {
-                        const modelId = String(m);
-                        aggregated.push({
-                            value: modelId,
-                            model: modelId,
-                            provider: provider.label ?? provider.contextId,
-                            contextId: provider.contextId,
-                            capabilities: [],
-                        });
-                        flatValues.push(modelId);
-                    }
-                }
-                catch {
-                    // 单个提供者获取模型失败不影响整体
-                }
+        // 合起各提供者的取值（人设卡等服务走 listModels()）
+        const allProviders = services.use.all(serviceName);
+        const models = [];
+        for (const provider of allProviders) {
+            if (typeof provider.instance.listModels !== 'function')
+                continue;
+            try {
+                models.push(...(await provider.instance.listModels()).map(String));
             }
-            res.json({ models: flatValues, providers: aggregated });
-        }
-        catch {
-            res.json({ models: [] });
-        }
-    });
-    // ---------- 受限操作交互式确认（复用 session-confirm 协调器；WebUI 传输=WS type:'confirm'，流式友好） ----------
-    // 协调器逻辑（待确认/超时/解析/文案）由 session-confirm 服务统一实现；WebUI 只注入自己的 WS 投递，
-    // 并保留 type:'confirm'（前端「确认模式」信号，抑制富客户端的「打字即打断」）。回复在 WS-onmessage 调 feed（下方）。
-    let confirmChannel;
-    caps.sessionConfirm.follow(confirmSvc => {
-        const channel = confirmSvc.createChannel((request, text) => {
-            const payload = { type: 'confirm', content: text, sessionId: request.sessionId };
-            const json = JSON.stringify(payload);
-            const sockets = sessions.get(request.sessionId);
-            const targets = sockets && sockets.size > 0 ? sockets : allClients;
-            for (const ws of targets) {
-                if (ws.readyState === WebSocket.OPEN)
-                    ws.send(json);
+            catch (err) {
+                // 单个提供者获取失败不影响整体，它的取值从下拉里消失：记下是谁、为什么
+                logger.use.warn(`取 ${serviceName} 的可选值时 ${provider.contextId} 失败，它的取值不在下拉里:`, err);
             }
-        });
-        // 挂到 authority 上要跟着它的胜者走（bounce 后重挂），所以嵌套一层跟随；
-        // 外层 cleanup 即内层订阅的退订：session-confirm 换胜者或本插件拆卸时一并注销
-        confirmChannel = channel;
-        const offAuthority = caps.authority.follow(authoritySvc => authoritySvc.setConfirmHandler('webui', channel.handler));
-        // cleanup：摘 handler、dispose 旧通道（在飞确认按取消结算，不留到 60s 超时）、清引用
-        return () => {
-            offAuthority();
-            channel.dispose();
-            if (confirmChannel === channel)
-                confirmChannel = undefined;
-        };
+        }
+        res.json({ models });
     });
-    // ---------- 文件管理 API ----------
-    registerFileRoutes(expressApp, { storage, fileRoot: uiConfig.fileRoot }, gate);
-    registerUploadedFilesRoutes(expressApp, {
-        storage,
-        logger,
-        fileIndex: () => services.get('file-reader'),
-    }, gate);
-    registerProxyRoutes(expressApp, logger, gate);
+    registerProxyRoutes(expressApp, logger.use, gate);
+    registerMediaRoutes(expressApp, storage, logger.use, gate);
+    registerFileRoutes(expressApp, storage, { sessions: caps.sessionProtocol, pages: pageFiles }, logger.use, gate);
     // ---------- WebSocket ----------
     wss.on('connection', (ws, req) => {
         // 连接建立时解析一次调用者身份（cookie 在升级请求里；verifyClient 已保证已认证）
         const wsIdentity = auth.identify(req) ?? { platform: 'webui', userId: 'console' };
-        logger.debug(`WebUI 客户端已连接: ${wsIdentity.platform}:${wsIdentity.userId}`);
-        allClients.add(ws);
+        logger.use.debug(`WebUI 客户端已连接: ${wsIdentity.platform}:${wsIdentity.userId}`);
+        // 每条连接都过心跳：回收半开连接，track 同时挂上 'error' 兜底监听（见 ws-heartbeat.ts）
         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(raw);
-                if (!parseResult.success) {
-                    logger.warn(`WebUI 收到协议违规消息: ${parseResult.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
-                    return;
-                }
-                const msg = parseResult.data;
-                if (msg.type === 'subscribe_logs') {
-                    logSubscribers.add(ws);
-                    return;
-                }
-                // 客户端连接时主动注册会话，确保 scheduler 等异步消息能推送
-                if (msg.type === 'subscribe_session') {
-                    const sid = msg.sessionId || 'webui-default';
-                    if (!sessions.has(sid)) {
-                        sessions.set(sid, new Set());
-                    }
-                    sessions.get(sid).add(ws);
-                    // 如果该会话正在生成中，发送已累积的内容供客户端恢复
-                    const buf = streamBuffers.get(sid);
-                    if (buf &&
-                        (buf.content || buf.reasoningContent || buf.segments.length > 0 || buf.toolCallsProgress.size > 0)) {
-                        const resume = {
-                            type: 'stream_resume',
-                            sessionId: sid,
-                            content: buf.content,
-                            reasoningContent: buf.reasoningContent,
-                            segments: buf.segments.length > 0 ? buf.segments : undefined,
-                            toolCallsProgress: buf.toolCallsProgress.size > 0
-                                ? [...buf.toolCallsProgress.entries()]
-                                    .sort((a, b) => a[0] - b[0])
-                                    .map(([index, v]) => ({
-                                    index,
-                                    name: v.name,
-                                    charsAccumulated: v.charsAccumulated,
-                                    startedAt: v.startedAt,
-                                }))
-                                : undefined,
-                            done: !buf.generating,
-                        };
-                        ws.send(JSON.stringify(resume));
-                    }
-                    // 发送缓存的 token 用量，刷新/切换会话后立即展示
-                    const cachedUsage = tokenUsageCache.get(sid);
-                    if (cachedUsage) {
-                        ws.send(JSON.stringify(cachedUsage));
-                    }
-                    else {
-                        // 无缓存（服务重启后），请求 agent 重新计算
-                        events
-                            .emit('token:request', {
-                            sessionId: sid,
-                            platform: resolveSessionPlatform(sid, new Set(getPlatformNames(caps.platform))),
-                        })
-                            .catch(() => { });
-                    }
-                    return;
-                }
-                if (msg.type === 'unsubscribe_session') {
-                    const sid = msg.sessionId || 'webui-default';
-                    sessions.get(sid)?.delete(ws);
-                    return;
-                }
-                if (msg.type === 'abort') {
-                    const sessionId = msg.sessionId || 'webui-default';
-                    const agentSvc = caps.agent.current;
-                    if (agentSvc?.abort)
-                        agentSvc.abort(sessionId);
-                    return;
-                }
-                if (msg.type === 'compress') {
-                    const sessionId = msg.sessionId || 'webui-default';
-                    logger.info(`收到手动压缩请求: session=${sessionId}`);
-                    // 触发压缩事件（memory-summary 监听此事件，并发出 session:compressing 通知）
-                    events
-                        .emit('session:compress', { sessionId, reason: 'manual' })
-                        .then(() => {
-                        // 压缩完成后重新计算 token 用量并推送给客户端
-                        events
-                            .emit('token:request', {
-                            sessionId,
-                            platform: resolveSessionPlatform(sessionId, new Set(getPlatformNames(caps.platform))),
-                        })
-                            .catch(() => { });
-                    })
-                        .catch(() => { });
-                    return;
-                }
-                if (msg.type !== 'message' || !msg.content)
-                    return;
-                const sessionId = msg.sessionId || 'webui-default';
-                const trimmed = msg.content.trim();
-                if (!sessions.has(sessionId)) {
-                    sessions.set(sessionId, new Set());
-                }
-                sessions.get(sessionId).add(ws);
-                // 检查待确认的受限操作（拦截输入作为确认/取消；协调器逻辑由 session-confirm 服务统一处理）
-                // 传应答者身份：仅确认的触发者本人能应答（防第三方抢答；webui 同账户天然同人）。
-                if (confirmChannel?.feed(sessionId, trimmed, wsIdentity.userId)) {
-                    // 不继续处理此消息，交给原始命令/工具执行流返回结果
-                    return;
-                }
-                // 指令解析已统一到全局 inbound:command 相位（plugin-commands 注册）。
-                // 适配器不再内联解析命令——未注册的命令会被该相位放行为普通消息进入
-                // agent，命中的命令由该相位执行并经 outbound:message 回送，与 onebot
-                // 平台行为完全一致。客户端只通过 attachments 发送多模态内容。
-                await events.emit('inbound:message', {
-                    content: trimmed,
-                    sessionId,
-                    platform: wsIdentity.platform,
-                    userId: wsIdentity.userId,
-                    nickname: undefined,
-                    ...(msg.attachments && msg.attachments.length > 0 ? { attachments: msg.attachments } : {}),
-                });
-            }
-            catch (err) {
-                logger.warn('WebUI 消息处理失败:', err);
-            }
-        });
-        ws.on('close', () => {
-            heartbeat.untrack(ws);
-            allClients.delete(ws);
-            logSubscribers.delete(ws);
-            for (const [sid, sockets] of sessions) {
-                sockets.delete(ws);
-                if (sockets.size === 0)
-                    sessions.delete(sid);
-            }
-        });
-    });
-    // 实时推送日志给订阅者
-    const removeLogListener = LogHub.default.onEntry((entry) => {
-        const payload = { type: 'log', log: entry };
-        const json = JSON.stringify(payload);
-        for (const ws of logSubscribers) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(json);
-            }
-        }
-    });
-    // 插件状态级联变更后，广播通知所有前端刷新
-    events.on('plugins:changed', () => {
-        const payload = { type: 'state_changed' };
-        const json = JSON.stringify(payload);
-        for (const ws of allClients) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(json);
-            }
-        }
-    });
-    // 重启通知：广播给所有客户端。WS 报文的 type 是前端协议，与 core 事件名无关，保持 'restarting'。
-    events.on('app:restarting', () => {
-        const payload = { type: 'restarting' };
-        const json = JSON.stringify(payload);
-        for (const ws of allClients) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(json);
-            }
-        }
-    });
-    // 会话列表变更：广播给所有客户端，让前端即时刷新
-    const broadcastSessionsChanged = () => {
-        const payload = { type: 'sessions_changed' };
-        const json = JSON.stringify(payload);
-        for (const ws of allClients) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(json);
-            }
-        }
-    };
-    // Todo 列表变更：推送给订阅了该会话的客户端
-    events.on('todo:updated', (sessionId, items) => {
-        const sockets = sessions.get(sessionId);
-        if (!sockets)
+        ws.on('close', () => heartbeat.untrack(ws));
+        if (wsPath(req) === ADMIN_PATH) {
+            admin.accept(ws);
             return;
-        const payload = { type: 'todo_updated', sessionId, todoItems: items };
-        const json = JSON.stringify(payload);
-        for (const ws of sockets) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(json);
-            }
         }
+        sessionSockets.add(ws);
+        ws.on('close', () => sessionSockets.delete(ws));
+        acceptSessionSocket(ws, { identity: wsIdentity, surface: approvalSurface }, caps.sessionProtocol.present ? caps.sessionProtocol.use : undefined);
     });
-    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) => {
-        const payload = { type: 'page_refresh', pluginName };
-        const json = JSON.stringify(payload);
-        for (const ws of allClients) {
-            if (ws.readyState === WebSocket.OPEN)
-                ws.send(json);
-        }
-    };
-    events.on('doctor:updated', () => broadcastPageRefresh('@aalis/plugin-doctor'));
-    // 会话历史变更（如 checkpoint 回滚整轮对话）：推送给订阅该会话的客户端，让前端重新拉取历史
-    events.on('history:changed', change => {
-        const sessionId = change?.sessionId;
-        if (!sessionId)
-            return;
-        const sockets = sessions.get(sessionId);
-        if (!sockets)
-            return;
-        const payload = { type: 'history_changed', sessionId };
-        const json = JSON.stringify(payload);
-        for (const ws of sockets) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(json);
-            }
-        }
+    // 管理面推送（/admin）：日志、插件状态、「需要处理」、重启。页面登记表与提示的变化、invalidate 在页面登记表（pages.ts）里推，
+    // 布局记录的变化在它的路由里推，换前端在 remountActiveClient 里推
+    caps.logs.use.subscribe(entry => admin.send({ type: 'log', entry }));
+    events.use.on('plugins:changed', () => {
+        admin.send({ type: 'plugins.changed' });
+        attention.pluginsChanged();
     });
-    // 压缩状态通知：memory-summary 发出 session:compressing 事件，广播给订阅该会话的客户端
-    events.on('session:compressing', info => {
-        const sockets = sessions.get(info.sessionId);
-        if (!sockets)
+    events.use.on('approval:created', () => attention.changed());
+    events.use.on('approval:settled', () => attention.changed());
+    events.use.on('app:restarting', () => admin.send({ type: 'app.restarting' }));
+    // 发往 WebUI 自己会话的出站消息：会话历史就是 WebUI 的收件箱，页面只是查看器，打开着的页面由会话服务推送。
+    // 回执表示这条消息已经进了会话历史，不看有没有页面在线。owner 从 WebUI 驱动的 IM 房间（根会话记下了出生平台）
+    // 由那个平台的适配器认领
+    events.use.on('outbound:message', (msg) => {
+        if (msg.delivery || msg.platform !== 'webui')
             return;
-        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) {
-                ws.send(json);
-            }
-        }
-    });
-    // 会话切换不再跨客户端广播：每个 webui 客户端独立持有自己的活跃会话（localStorage
-    // 持久化 + 每条消息自带 sessionId），互不干扰。全局 activeSessionId 退化为 CLI 概念，
-    // 不再驱动 webui。这样多人同时使用时，他人新建/切换会话不会把你的窗口切走。
-    // 监听 AI 回复
-    events.on('outbound:message', (msg) => {
-        // 生成完成，延迟清理缓冲区（给客户端重连拉取历史留出时间窗口）
-        const buf = streamBuffers.get(msg.sessionId);
-        if (buf) {
-            buf.generating = false;
-            buf.content = msg.content ?? buf.content;
-            buf.reasoningContent = msg.reasoningContent ?? buf.reasoningContent;
-            scheduleBufferCleanup(msg.sessionId, buf);
-        }
-        const sockets = sessions.get(msg.sessionId);
-        if (!sockets)
+        const sm = caps.sessions.present ? caps.sessions.use : undefined;
+        const root = sm && rootSessionOf(sm.getSession(msg.sessionId), id => sm.getSession(id));
+        if (root?.originPlatform !== undefined)
             return;
-        // 仅信任 msg 本身携带的 segments。不要回退到 buf?.segments：
-        // 工具循环中 agent tool（如 send_attachment / commands 回复）会直接 emit 'outbound:message'，
-        // 但 streamBuffers[sid].segments 累积的是当前回合的完整时间线（含本工具之前的 reasoning/tool_call）。
-        // 若回退使用 buf，会把整条时间线"借尸还魂"挂到工具消息上 → 前端 REPLACE 当前 assistant 后，
-        // 真正的 agent final outbound:message 再到达时被识别为新消息 APPEND，导致整条时间线渲染两遍。
-        // agent 的 final emit 已显式带 segments=turnSegments，不需要这个隐式 fallback。
-        const segments = msg.segments;
-        const payload = {
-            type: 'message',
-            content: msg.content,
-            sessionId: msg.sessionId,
-            reasoningContent: msg.reasoningContent,
-            segments: segments && segments.length > 0 ? segments : undefined,
-            attachments: msg.attachments?.length
-                ? msg.attachments.map(a => ({
-                    kind: a.kind,
-                    data: a.data,
-                    mimeType: a.mimeType,
-                    name: a.name,
-                }))
-                : undefined,
-            modelInfo: msg.modelInfo,
-        };
-        const json = JSON.stringify(payload);
-        for (const ws of sockets) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(json);
-            }
-        }
-    });
-    // 监听流式增量推送
-    events.on('outbound:stream', (chunk) => {
-        // 累积到缓冲区
-        if (!chunk.done) {
-            let buf = streamBuffers.get(chunk.sessionId);
-            if (!buf) {
-                buf = { content: '', reasoningContent: '', segments: [], generating: true, toolCallsProgress: new Map() };
-                streamBuffers.set(chunk.sessionId, buf);
-            }
-            if (chunk.contentDelta) {
-                // 进入文本生成阶段：清空所有 tool 进度
-                buf.toolCallsProgress.clear();
-                buf.content += chunk.contentDelta;
-                // 追加到 segments：合并连续 text
-                const last = buf.segments[buf.segments.length - 1];
-                if (last && last.type === 'text') {
-                    last.content += chunk.contentDelta;
-                }
-                else {
-                    buf.segments.push({ type: 'text', content: chunk.contentDelta });
-                }
-            }
-            if (chunk.reasoningDelta) {
-                buf.toolCallsProgress.clear();
-                buf.reasoningContent += chunk.reasoningDelta;
-                // 同样追加到统一时间线：合并连续 reasoning_text
-                const last = buf.segments[buf.segments.length - 1];
-                if (last && last.type === 'reasoning_text') {
-                    last.content += chunk.reasoningDelta;
-                }
-                else {
-                    buf.segments.push({ type: 'reasoning_text', content: chunk.reasoningDelta });
-                }
-            }
-            if (chunk.toolCallProgress) {
-                const { index, name, charsAccumulated } = chunk.toolCallProgress;
-                const prev = buf.toolCallsProgress.get(index);
-                buf.toolCallsProgress.set(index, {
-                    name,
-                    charsAccumulated,
-                    startedAt: prev?.startedAt ?? Date.now(),
-                });
-            }
-        }
-        else {
-            // done：回合终态收口。无论本回合是正常完成、空回复、还是被用户中止，
-            // agent 都会发一次 outbound:stream{done:true}（见 plugin-agent 的成功/中止/异常/未处理四条路径）。
-            // 这里必须把 generating 翻 false 并安排清理，否则刷新后 subscribe_session 仍读到
-            // generating=true 的残留 buffer → 回 stream_resume{done:false} → 前端永远显示"可停止"。
-            // （正常路径的 outbound:message 也会做同样的事；此处补全保证中止/静默路径对称。）
-            const buf = streamBuffers.get(chunk.sessionId);
-            if (buf) {
-                buf.toolCallsProgress.clear();
-                buf.generating = false;
-                scheduleBufferCleanup(chunk.sessionId, buf);
-            }
-        }
-        const sockets = sessions.get(chunk.sessionId);
-        if (!sockets)
-            return;
-        const payload = {
-            type: 'stream',
-            sessionId: chunk.sessionId,
-            contentDelta: chunk.contentDelta,
-            reasoningDelta: chunk.reasoningDelta,
-            toolCallProgress: chunk.toolCallProgress,
-            done: chunk.done,
-            toolLimitReached: chunk.toolLimitReached,
-        };
-        const json = JSON.stringify(payload);
-        for (const ws of sockets) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(json);
-            }
-        }
-    });
-    // 监听工具调用事件
-    events.on('tool:execute', (info) => {
-        // 缓存工具调用到 segments
-        let buf = streamBuffers.get(info.sessionId);
-        if (!buf) {
-            buf = { content: '', reasoningContent: '', segments: [], generating: true, toolCallsProgress: new Map() };
-            streamBuffers.set(info.sessionId, buf);
-        }
-        if (info.phase === 'start') {
-            // 工具进入实际执行阶段：清掉生成中进度（占位卡 → ToolCallBlock 切换）
-            buf.toolCallsProgress.clear();
-            buf.segments.push({ type: 'tool_call', name: info.toolName, args: info.args ?? {}, startTime: Date.now() });
-        }
-        else if (info.phase === 'end') {
-            // 找到最后一个同名且无结果的 tool_call segment，填充结果
-            for (let i = buf.segments.length - 1; i >= 0; i--) {
-                const seg = buf.segments[i];
-                if (seg.type === 'tool_call' && seg.name === info.toolName && seg.result == null) {
-                    seg.result = info.result;
-                    seg.endTime = Date.now();
-                    break;
+        // 同步挂上 Promise，始终 resolve，即使其他 outbound 监听器随后耗时，也不会产生未处理的 rejection。
+        msg.delivery = (async () => {
+            try {
+                // 保存快照：下游处理不应受生产者或其他适配器后续改写影响。
+                const snapshot = { ...msg, attachments: msg.attachments?.map(att => ({ ...att })) };
+                if (!caps.archive.present)
+                    return { ok: false, error: '消息存档服务不在场，这条消息没有存进 WebUI 会话的历史' };
+                const archive = caps.archive.use;
+                for (const record of inboxRecords(snapshot))
+                    await archive.saveMessage(msg.sessionId, record);
+                if (snapshot.attachments?.length) {
+                    // 附件已由上面记进会话历史（见 inboxRecords），标上 skipArchive，免得全局出站归档再记一份
+                    const attachments = snapshot.attachments.map(att => ({ ...att, skipArchive: true }));
+                    void events.use.emit('outbound:delivered', { ...snapshot, attachments, delivery: undefined });
                 }
+                return { ok: true };
             }
-        }
-        const sockets = sessions.get(info.sessionId);
-        if (!sockets)
-            return;
-        const payload = {
-            type: 'tool_call',
-            sessionId: info.sessionId,
-            toolName: info.toolName,
-            toolArgs: info.args,
-            toolPhase: info.phase,
-            toolResult: info.result,
-        };
-        const json = JSON.stringify(payload);
-        for (const ws of sockets) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(json);
+            catch (error) {
+                return { ok: false, error: error instanceof Error ? error.message : String(error) };
             }
-        }
-    });
-    // 监听 token 使用量统计事件
-    events.on('token:usage', usage => {
-        const sockets = sessions.get(usage.sessionId);
-        if (!sockets)
-            return;
-        const payload = {
-            type: 'token_usage',
-            sessionId: usage.sessionId,
-            tokenUsage: {
-                contextWindow: usage.contextWindow,
-                maxTokens: usage.maxTokens,
-                tokenBudget: usage.tokenBudget,
-                used: usage.used,
-                usageRatio: usage.usageRatio,
-                breakdown: usage.breakdown,
-            },
-        };
-        // 缓存最新的 token 用量
-        tokenUsageCache.set(usage.sessionId, payload);
-        const json = JSON.stringify(payload);
-        for (const ws of sockets) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(json);
-            }
-        }
+        })();
     });
     // 前端切换「逃生页」：由 webui-server 直出、独立于任何可被切换的前端，故任意前端（哪怕
     // 极简第三方前端无切换 UI）卡住时都能在此切回。受全局 auth 中间件登录保护；切换走既有 owner
     // 闸的 POST /api/services/webui-client/prefer，本页零新增后端逻辑（见 client-switch-page.ts）。
     // 注册在 SPA 兜底之前，故 `/__clients` 被本路由先接走、不落到前端 index.html。
-    expressApp.get('/__clients', (_req, res) => {
+    route(expressApp, 'GET /__clients', (_req, res) => {
         res.type('html').send(renderClientSwitchPage());
     });
-    // API 未命中：回 404 JSON，不落到 SPA 兜底（否则客户端拿到 HTML 去解析 JSON）。
-    expressApp.all('/api/{*path}', (req, res) => {
+    route(expressApp, 'GET /__clients.js', (_req, res) => {
+        res.type('application/javascript').send(CLIENT_SWITCH_SCRIPT);
+    });
+    // API 未命中：回 404 JSON，不落到 SPA 兜底（否则客户端拿到 HTML 去解析 JSON）。不是路由：任何方法都回它
+    expressApp.use((req, res, next) => {
+        if (!req.path.startsWith('/api/'))
+            return next();
         res.status(404).json({ error: `未知 API: ${req.method} ${req.path}` });
     });
-    // SPA fallback: 所有非 API 路径返回 index.html
-    expressApp.get('{*path}', (_req, res) => {
-        const indexPath = resolve(clientDist, 'index.html');
-        if (existsSync(indexPath)) {
+    // SPA fallback: 所有非 API 路径返回 index.html；/assets/ 下缺失的文件回 404（旧页面引用的资源换了构建就不在了，
+    // 回 index.html 只会让浏览器把 HTML 当脚本执行）
+    route(expressApp, 'GET /{*path}', (req, res) => {
+        if (req.path.startsWith('/assets/')) {
+            res.status(404).end();
+            return;
+        }
+        // 还没有选中的前端时 clientDist 为空：不能拼出相对 cwd 的 index.html
+        const indexPath = clientDist ? join(clientDist, 'index.html') : undefined;
+        if (indexPath && existsSync(indexPath)) {
             res.sendFile(indexPath);
         }
         else {
-            res
-                .status(404)
-                .json({ error: '前端未就绪：请安装一个带 aalis.client 标记的前端包（如 @aalis/plugin-webui-client）' });
+            res.status(404).json({ error: '前端未就绪：请安装一个带 aalis.client 标记的前端包' });
         }
     });
+    // 路由与中间件抛出的错误（请求体不是 JSON 或太大、路径参数解不开、处理函数出错）：/api/ 下回 ErrorResponse，别处回纯文本，
+    // 都不带堆栈，原因只进日志。挂在全部路由之后（插件前端的挂载另有自己的，紧跟在挂载之后）
+    expressApp.use((err, req, res, next) => {
+        if (res.headersSent)
+            return next(err);
+        const { status, expose, message } = err;
+        const code = typeof status === 'number' && status >= 400 && status < 600 ? status : 500;
+        if (code >= 500)
+            logger.use.error(`${req.method} ${req.path} 处理出错:`, err);
+        else
+            logger.use.debug(`${req.method} ${req.path} 请求被拒 (${code}): ${String(message)}`);
+        const reason = code >= 500
+            ? '处理这个请求时出错，原因见日志'
+            : expose === true && typeof message === 'string'
+                ? message
+                : '请求的写法不对';
+        if (req.path.startsWith('/api/'))
+            res.status(code).json({ error: reason });
+        else
+            res.status(code).type('text').send(reason);
+    });
     /**
      * 全动态发现前端：按 `aalis.client:true` 标记扫描，**不硬编码任何前端包名**
      * （忒修斯之船——任意第三方前端带标记+dist 即被发现）。
      * 覆盖三种拓扑：monorepo（扫 packages 同级目录）/ 独立项目（扫 node_modules/@aalis + 根 deps）。
      *
-     * **幂等**，可重复调用：装完一个 `aalis-interface` 包后要立刻重跑，否则它不会出现在服务页
+     * **幂等**，可重复调用：装完一个 `aalis-interface` 包后要立刻重跑，否则它不会出现在服务偏好
      * 的下拉里、必须重启才看得见。幂等是硬要求而非优化——重复 `fork().provide()` 会在服务
      * 容器里堆同名重复项。已登记过的 id 直接跳过。
      *
-     * 只登记新候选，**不切换活跃前端**：换前端是用户在服务页的显式选择，装了个新的不该把
+     * 只登记新候选，**不切换活跃前端**：换前端是用户在服务偏好里的显式选择，装了个新的不该把
      * 他正在用的顶掉。
      */
     function discoverAndProvideClients() {
-        const projectRequire = createRequire(pathToFileURL(resolve(process.cwd(), 'package.json')));
+        // 宿主不提供安装集目录时没有依赖表可读，只按扫描目录发现
+        const projectRequire = appDir ? createRequire(pathToFileURL(join(appDir, 'package.json'))) : undefined;
         const env = {
             ...fsScanEnv,
             dirname,
             resolvePkgJson: id => {
                 try {
-                    return projectRequire.resolve(`${id}/package.json`);
+                    return projectRequire?.resolve(`${id}/package.json`);
                 }
                 catch {
                     return undefined;
                 }
             },
         };
-        const scanDirs = LOCAL_SCAN_DIRS;
         let depIds = [];
-        try {
-            // 每次重读：装完新包后根 dependencies 已变，缓存会让新前端发现不到。
-            const rootPkg = JSON.parse(readFileSync(resolve(process.cwd(), 'package.json'), 'utf-8'));
-            depIds = Object.keys({ ...rootPkg.dependencies, ...rootPkg.optionalDependencies });
-        }
-        catch {
-            /* 无项目根 package.json（如 monorepo 直跑），跳过 deps 扫描 */
+        if (appDir) {
+            try {
+                // 每次重读：装完新包后根 dependencies 已变，缓存会让新前端发现不到。
+                const rootPkg = JSON.parse(readFileSync(join(appDir, 'package.json'), 'utf-8'));
+                depIds = Object.keys({ ...rootPkg.dependencies, ...rootPkg.optionalDependencies });
+            }
+            catch {
+                /* 安装集没有 package.json，跳过 deps 扫描 */
+            }
         }
         const scanned = discoverClients(scanDirs, depIds, env);
         // 对账：本轮扫不到的候选要摘掉，不能只增不删。卸载现在会真删 node_modules，
@@ -1384,7 +994,7 @@ async function startWebuiServer(caps) {
             clientProviderDisposers.delete(stale.id);
             clientCandidates.splice(i, 1);
             removed++;
-            logger.info(`前端已消失，摘除候选: ${stale.label} (${stale.dir})`);
+            logger.use.info(`前端已消失，摘除候选: ${stale.label} (${stale.dir})`);
         }
         // 摘掉 provider 只改了「服务解析结果」，**真正服务 HTTP 的是 clientDist / staticMiddleware**，
         // 它们在 app:ready 时绑定、之后只由 remountActiveClient 更新。不重挂的话，被摘掉的正好是当前
@@ -1394,32 +1004,41 @@ async function startWebuiServer(caps) {
             remountActiveClient();
         const fresh = pickFreshClients(clientCandidates.map(c => c.id), scanned);
         clientCandidates.push(...fresh);
-        // 把每个新发现的前端注册为 webui-client 服务的一个 provider（带 label，供「服务」页下拉切换）。
+        // 把每个新发现的前端注册为 webui-client 服务的一个 provider（带 label，供服务偏好里切换）。
         // 外部插件在 apply 里主动提供 webui-client 的也已在服务池中（注册更早 → 默认胜出，仍可被偏好切换）。
         //
-        // 代前端包登记：条目身份是前端**包名本身**——它是服务页展示的 contextId，也是
+        // 代前端包登记：条目身份是前端**包名本身**——它是服务偏好里展示的 contextId，也是
         // servicePreferences['webui-client'] 里持久化的键，还是装卸闸按包名比对的对象。
         for (const candidate of fresh) {
-            clientProviderDisposers.set(candidate.id, provide(webuiClient, { getClientDir: () => candidate.dir }, { label: candidate.label, onBehalfOf: candidate.id }));
-            logger.info(`发现前端: ${candidate.label} (${candidate.dir})`);
+            clientProviderDisposers.set(candidate.id, provide.use(webuiClient, { getClientDir: () => candidate.dir }, { label: candidate.label, entryId: candidate.id }));
+            logger.use.info(`发现前端: ${candidate.label} (${candidate.dir})`);
         }
     }
     // 启动服务器
-    events.on('app:ready', async () => {
+    events.use.on('app:ready', async () => {
         // 冷启动时 storage 的激活在 app:ready 之前收敛；等晚到的读回落定，listen / autoOpen /
         // access.txt 用的就是持久化的 token
         if (tokenLoading)
             await tokenLoading;
+        // 等插件状态机静置再登记扫描到的前端：bounce 后 sticky 的 app:ready 在本实例激活途中补发，立刻登记会落在
+        // provides 核对之前（dev 多报「未在 provides 中声明」），等过之后与冷启动一样晚于全部激活，主动覆盖仍先登记。
+        // 代价：重算一直不收敛时，前端要等它收敛后才登记与挂上
+        if (caps.plugins.present)
+            await caps.plugins.use.idle();
+        // 等待期间本实例可能已开始关闭（bounce、disable、unload）。醒来照常登记、listen 的话，它成了占着端口的旧实例：
+        // 接手的新实例 listen 报 EADDRINUSE，禁用之后端口照样应答
+        if (lifecycle.use.signal.aborted)
+            return;
         discoverAndProvideClients();
         // 活跃前端 = 解析后的 webui-client 服务（servicePreferences 偏好 > 优先级 > 注册顺序）；零前端则 404。
         const activeDir = currentClientDir();
         if (activeDir) {
             clientDist = activeDir;
             mountStaticDir(activeDir);
-            logger.info(`活跃前端: ${activeDir}`);
+            logger.use.info(`活跃前端: ${activeDir}`);
         }
         else {
-            logger.warn('未发现任何前端（webui-client provider）；前端路由将 404，请安装一个 aalis.client 包');
+            logger.use.warn('未发现任何前端（webui-client provider）；前端路由将 404，请安装一个 aalis.client 包');
         }
         // 监听失败（典型 EADDRINUSE：3000 被别的 dev server 占了）是 bind 之后**异步 emit** 的，
         // 不在任何调用栈内，外层 try/catch 接不住 —— 无人处理即 uncaughtException →
@@ -1431,7 +1050,7 @@ async function startWebuiServer(caps) {
         // wss）并排在最前；EventEmitter 按注册顺序调用，它 emit 到无监听器的 wss 上会同步抛出、
         // 中断 emit 循环，后注册在 server 上的 handler 因此永远轮不到。
         wss.on('error', (err) => {
-            logger.error(`WebUI 监听 ${uiConfig.host}:${uiConfig.port} 失败: ${err.message}；WebUI 不可用，其余功能照常运行`);
+            logger.use.error(`WebUI 监听 ${uiConfig.host}:${uiConfig.port} 失败: ${err.message}；WebUI 不可用，其余功能照常运行`);
         });
         server.listen(uiConfig.port, uiConfig.host, () => {
             // 通配绑定地址（0.0.0.0 / ::）是"听在哪"，不是"从哪访问"——直接拼进 URL 会让
@@ -1441,10 +1060,10 @@ async function startWebuiServer(caps) {
             const url = `http://${displayHost}:${uiConfig.port}/`;
             listeningUrl = url;
             const accessUrl = `${url}?token=${authToken}`;
-            logger.info(`WebUI 已启动: ${url}`);
+            logger.use.info(`WebUI 已启动: ${url}`);
             // 多前端时提示恢复页 URL：万一切到无切换 UI 的前端被卡住，可在此切回（详见 client-switch-page.ts）。
             if (clientCandidates.length > 1) {
-                logger.info(`检测到多个前端；若卡在某前端无切换入口，可访问恢复页切回: ${url}__clients`);
+                logger.use.info(`检测到多个前端；若卡在某前端无切换入口，可访问恢复页切回: ${url}__clients`);
             }
             const tokenHint = uiConfig.tokenMode === 'ephemeral'
                 ? 'token 仅本次启动有效，重启轮换'
@@ -1452,15 +1071,16 @@ async function startWebuiServer(caps) {
                     ? 'token 来自配置 fixedToken，固定不变'
                     : 'token 已持久化到 storage data:/webui/token，重启沿用';
             // 不把 token 打进日志（会落 latest.log / 被 /api/logs/* 回放 / 贴日志求助时外泄）。
-            // 仅打不带 token 的 URL，完整一键登录链接见 access.txt（该文件应 0o600，见 token 落盘）。
-            logger.info(`首次访问 URL（${tokenHint}）: ${url} —— 完整一键登录链接见 ${accessFileUri}`);
+            // 仅打不带 token 的 URL，完整一键登录链接见 access.txt（按凭据写，只给本机用户读）。
+            logger.use.info(`首次访问 URL（${tokenHint}）: ${url} —— 完整一键登录链接见 ${accessFileUri}`);
             void (async () => {
                 // 先把文件写出来，再解析它的绝对路径：resolveLocalPath 走 realpath，文件尚未落盘会抛
                 // ENOENT 被吞掉，于是「绝对路径」退化成原样重复一遍 URI——偏偏首启（新用户唯一需要
                 // 这行的时刻）必然命中，二次启动因文件已在反而正常。两者原先都是 void，谁先到看调度。
                 if (!(await writeAccessFile(url, authToken))) {
                     // 写失败上面已 warn 过；再打一条「已写入」只会让人去找一个不存在的文件
-                    logger.warn(`访问凭据未能写入 ${accessFileUri}；请用 WebUI 登录页手工粘贴 token`);
+                    logger.use.warn(`访问凭据未能写入 ${accessFileUri}：修好家目录 state/webui/ 的写权限后重启；` +
+                        `或把 tokenMode 设为 fixed、在 fixedToken 里填一个至少 ${FIXED_TOKEN_MIN_LENGTH} 个字符的 token，用它在登录页登录`);
                     return;
                 }
                 let absHint = accessFileUri;
@@ -1470,24 +1090,28 @@ async function startWebuiServer(caps) {
                     }
                 }
                 catch (err) {
-                    logger.debug(`解析访问凭据文件绝对路径失败: ${err.message}`);
+                    logger.use.debug(`解析访问凭据文件绝对路径失败: ${err.message}`);
                 }
-                logger.info(`访问凭据已写入: ${accessFileUri}（绝对路径: ${absHint}）`);
+                logger.use.info(`访问凭据已写入: ${accessFileUri}（绝对路径: ${absHint}）`);
             })();
-            if (uiConfig.autoOpen && tokenFresh)
-                openBrowser(accessUrl, createProcessGateway(caps.process));
+            // 记的是宿主实例本身（业务句柄每次激活各一个，认不出同一个宿主）
+            const host = services.use.get(appService);
+            if (uiConfig.autoOpen && (tokenFresh || !host || !browserOpenedFor.has(host))) {
+                if (host)
+                    browserOpenedFor.add(host);
+                openBrowser(accessUrl, caps.process.use);
+            }
         });
     });
-    lifecycle.onDispose(() => {
-        confirmChannel?.dispose(); // 清 WebUI 确认通道里挂起的待确认（安全拒），避免 Promise 永挂
+    lifecycle.use.onDispose(() => {
         heartbeat.dispose();
-        removeLogListener();
+        pages.dispose();
         // 先把已建立的连接收口再关服务端：ws 的 close() 在 {server} 模式下只摘监听器、对
-        // this.clients 一个都不动，server.close() 也只停止 accept。不主动关的话，旧 socket 上
-        // 注册的 message 闭包在插件卸载后仍然活着，照常发 'inbound:message'——而事件发射
-        // 不设关闭守卫（订阅与发布两侧不对称）。
-        // 发 1001 触发前端既有的 onclose 重连路径，bounce 之后自动接回新实例。
-        for (const ws of allClients) {
+        // this.clients 一个都不动，server.close() 也只停止 accept。不主动关的话，旧 socket 在插件卸载后
+        // 仍然活着，照常把帧转给会话服务，发出的消息照样进入站事件。
+        // 发 1001 触发前端既有的 onclose 重连路径，bounce 之后自动接回新实例。各端点的连接都在 wss.clients 里，
+        // /session 的连接关闭时撤掉会话服务那头的连接。
+        for (const ws of wss.clients) {
             try {
                 ws.close(1001, 'webui 正在卸载');
             }
@@ -1495,95 +1119,30 @@ async function startWebuiServer(caps) {
                 /* 单条连接关不掉不应阻塞拆卸 */
             }
         }
-        allClients.clear();
         wss.close();
         server.close();
     });
-    // 构造 PlatformAdapter 实例
-    const adapter = {
+    // 平台名 webui 标明说话的是从 WebUI 来的 owner。登记成平台，平台档、会话范围的候选与用户关系认的平台名里才有它；
+    // 连接状态数的是打开着的 /session 连接。WebUI 的会话不经适配器收发：页面走会话协议，出站消息由上面的收件箱认领
+    provide.use(platform, {
         adapterName: 'WebUI',
         platform: 'webui',
-        sessionTypes: [], // WebUI 单会话，不区分 sessionType
         getConnections() {
-            // 统计所有活跃 WebSocket 客户端
-            const activeCount = [...allClients].filter(ws => ws.readyState === WebSocket.OPEN).length;
-            if (activeCount === 0)
-                return [];
-            return [
-                {
-                    id: 'webui',
-                    platform: 'webui',
-                    status: 'online',
-                    detail: { clients: activeCount },
-                },
-            ];
+            const clients = sessionSockets.size;
+            return clients === 0 ? [] : [{ id: 'webui', platform: 'webui', status: 'online', detail: { clients } }];
         },
-        async sendMessage(sessionId, content) {
-            const sockets = sessions.get(sessionId);
-            if (!sockets)
-                return;
-            const payload = {
-                type: 'message',
-                content,
-                sessionId,
-            };
-            const json = JSON.stringify(payload);
-            for (const ws of sockets) {
-                if (ws.readyState === WebSocket.OPEN) {
-                    ws.send(json);
-                }
-            }
+        async sendMessage() {
+            throw new Error('WebUI 的会话不经平台适配器发消息：页面经会话协议收发，发往 WebUI 会话的出站消息写进会话历史');
         },
-    };
-    provide(platform, adapter);
+    });
     // === 注册 WebUI 服务 ===
-    const registeredPages = new Map();
-    // 内建页面归属为 webui-server 本身
-    for (const page of webuiPages) {
-        const list = registeredPages.get(name) ?? [];
-        list.push({ ...page, pluginName: name });
-        registeredPages.set(name, list);
-    }
     const webuiService = {
         getPort: () => uiConfig.port,
         getHost: () => uiConfig.host,
-        registerPage(page, contextId) {
-            const list = registeredPages.get(contextId) ?? [];
-            const entry = { ...page, pluginName: contextId };
-            list.push(entry);
-            registeredPages.set(contextId, list);
-            // 退订按条目引用比对：同 key 重注册后，旧退订闭包不得摘掉新登记
-            return () => {
-                const cur = registeredPages.get(contextId);
-                if (!cur)
-                    return;
-                const idx = cur.indexOf(entry);
-                if (idx >= 0)
-                    cur.splice(idx, 1);
-                if (cur.length === 0)
-                    registeredPages.delete(contextId);
-            };
-        },
-        getPages() {
-            const out = [];
-            for (const list of registeredPages.values())
-                out.push(...list);
-            return out;
-        },
-        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);
-            };
-        },
+        addPage: pages.addPage,
+        invalidate: pages.invalidate,
+        addNotice: pages.addNotice,
     };
-    provide(webuiServer, webuiService);
+    provide.use(webuiServer, webuiService);
 }
 //# sourceMappingURL=index.js.map