@aalis/plugin-webui-server 0.14.1 → 0.16.0

package/dist/index.js

@@ -4,149 +4,156 @@ 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 { i18n } from '@aalis/api-i18n';
+import { llm, modelRefOf, 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, platform } from '@aalis/api-platform';
 import { pluginSource } from '@aalis/api-plugin-source';
-import { createProcessGateway, processService } from '@aalis/api-process';
-import { sessionConfirm } from '@aalis/api-session-confirm';
-import { createStorageGateway, readTailLines, storage } from '@aalis/api-storage';
+import { processService } from '@aalis/api-process';
+import { rootSessionOf, sessionManager } from '@aalis/api-session-manager';
+import { sessionProtocol } from '@aalis/api-session-protocol';
+import { 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 { CLIENT_TEXTS_FILE, 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 { parseLogLine } from '@aalis/schema-log';
+import { asText, isTextError, registerCatalogEntry, textLines, textOf, toSource, } from '@aalis/schema-i18n';
 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, isHostName, openBrowser, originAllowed } from './auth.js';
 import { collectLocalPackageDeps, discoverClients, pickFreshClients } from './client-discovery.js';
-import { renderClientSwitchPage } from './client-switch-page.js';
+import { CLIENT_SWITCH_SCRIPT, CLIENT_SWITCH_TEXTS, renderClientSwitchPage } from './client-switch-page.js';
 import { createRouteGate } from './gate.js';
+import { pageLanguageOf, withPageLanguage } from './html.js';
+import { createLayoutStore } from './layout.js';
+import { createLocalizer } from './localize.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 { frameTexts, interfaceLanguage, registerI18nRoutes } from './routes/i18n.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 { t } from './texts.js';
 import { createWsHeartbeat } from './ws-heartbeat.js';
-/**
- * 工具 / 指令 / 工具组 description 约定：首行 = 人类可读摘要，其余 = 给 agent 的长使用指南。
- * WebUI 管理页只展示首行摘要（避免倾倒整段指南）；完整 description 仍由工具/指令定义抵达 LLM。
- */
-function descSummary(d) {
-    if (!d)
-        return d;
-    const s = d.split('\n')[0].trim();
-    return s.length > 200 ? `${s.slice(0, 200)}…` : s;
-}
 // ===== 插件元数据 =====
 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' },
-];
+// 按宿主身份记打开记录：插件 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('; ');
+/** 请求体解析（express.json）的拒绝按 type 给的整句；别的 type 给 badRequest */
+const BODY_REJECTIONS = {
+    'entity.too.large': t('bodyTooLarge'),
+    'entity.parse.failed': t('bodyNotJson'),
+    'charset.unsupported': t('bodyEncoding'),
+    'encoding.unsupported': t('bodyEncoding'),
+};
 const configSchema = defineConfig({
-    port: { type: 'number', label: '端口', default: 3000, onInvalid: 'error', description: 'Web 管理界面的 HTTP 端口' },
+    port: {
+        type: 'number',
+        label: t('portLabel'),
+        default: 3000,
+        integer: true,
+        min: 0,
+        max: 65535,
+        onInvalid: 'error',
+        description: t('portDescription'),
+    },
     host: {
         type: 'string',
-        label: '监听地址',
+        label: t('hostLabel'),
         default: '127.0.0.1',
+        pattern: '\\S',
         onInvalid: 'error',
-        description: '绑定的 IP 地址，0.0.0.0 可对外访问',
+        description: t('hostDescription'),
     },
-    fileRoot: {
-        type: 'string',
-        label: '文件浏览根',
-        default: 'workspace',
+    allowedHosts: {
+        type: 'multiselect',
+        label: t('allowedHostsLabel'),
+        default: [],
         onInvalid: 'error',
-        description: '文件管理页面使用的 storage 根 ID，默认 workspace',
+        // 主机名由使用者填写，静态选项无法穷举。
+        allowCustom: true,
+        description: t('allowedHostsDescription'),
+        validate(value) {
+            const bad = value.map(String).find(entry => !isHostName(entry));
+            return bad === undefined ? undefined : t('badAllowedHost', { entry: bad });
+        },
     },
     autoOpen: {
         type: 'boolean',
-        label: '启动时自动打开浏览器',
+        label: t('autoOpenLabel'),
         default: true,
         onInvalid: 'error',
-        description: '访问 token 为新生成时（persist 模式首次生成、ephemeral 模式每次生成）以含 token 的 URL 自动开启默认浏览器；沿用已有 token（persist 读回已持久化的 token、fixed 用配置的 fixedToken）时不打开；fixed 模式 fixedToken 为空时按 persist 处理。SSH/headless 环境建议关闭',
+        description: t('autoOpenDescription'),
     },
     tokenMode: {
         type: 'select',
-        label: 'Token 策略',
+        label: t('tokenModeLabel'),
         default: 'persist',
         onInvalid: 'error',
+        secret: false,
         options: [
-            { label: '每次启动随机生成（重启即轮换）', value: 'ephemeral' },
-            { label: '首次生成后持久化（重启不掉登录）', value: 'persist' },
-            { label: '使用下方固定 token', value: 'fixed' },
+            { label: t('tokenEphemeral'), value: 'ephemeral' },
+            { label: t('tokenPersist'), value: 'persist' },
+            { label: t('tokenFixed'), value: 'fixed' },
         ],
-        description: 'ephemeral=每次启动随机；persist=token 写入 data:/webui/token，读取复用；fixed=使用 fixedToken 字段。所有模式都会写出便利文件 data:/webui/access.txt 含访问 URL。',
+        description: t('tokenModeDescription'),
     },
     fixedToken: {
         type: 'string',
-        label: '固定 Token（仅 tokenMode=fixed 生效）',
+        label: t('fixedTokenLabel'),
         default: '',
         onInvalid: 'error',
-        description: '请使用足够长的随机字符串；配置文件不支持环境变量插值，占位符会被原样当作字面量。',
-    },
-    relationGraphDefaultSpacing: {
-        type: 'number',
-        label: '关系图默认密度',
-        default: 120,
-        description: '关系图（RelationGraph）布局密度的服务器默认值（约等于理想边长 px，建议 60–250；越大越稀疏）。前端每个用户可在图工具栏现场覆盖并保存到本地浏览器；改完此项后，刷新关系图页面或新会话生效。',
+        secret: true,
+        description: t('fixedTokenDescription', { min: FIXED_TOKEN_MIN_LENGTH }),
     },
     marketplaceRegistry: {
         type: 'string',
-        label: '插件市场 npm 源',
+        label: t('registryLabel'),
         default: 'https://registry.npmjs.org',
         onInvalid: 'error',
-        description: '插件市场检索用的 npm registry 基址。注意 npm 的 search API 并非所有镜像都支持（淘宝等国内源不支持），默认官方源；国内可填支持 search 的镜像或代理。安装走 package-manager（遵循本机 npm 配置），卡片上的最新版与可更新也按安装使用的源查。',
+        description: t('registryDescription'),
     },
     // 活跃前端不在此配置：前端即 `webui-client` 服务的多 provider，活跃者由「服务偏好」
-    // （servicePreferences['webui-client']）决定——在 WebUI「服务」页的下拉框切换。
+    // （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;
-        },
-    });
-    return lines.map(parseLogLine).filter((e) => e !== null && e.seq < beforeSeq);
-}
 // ===== 插件入口 =====
 /**
- * 本地包扫描目录：项目根的 `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` 时成立。装进用户项目后它解析成
@@ -154,27 +161,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,
@@ -183,25 +175,36 @@ 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 自己会话的出站消息经它的 recordOutbound 记进会话历史，记成了才算送达 */
+    archive: optional(messageArchive),
+    /** 回应里的文字对象按全局层的语言渲染（localize.ts）；缺席时按原文 */
+    i18n: optional(i18n),
 };
 export default definePlugin({
     name,
-    displayName: 'WebUI 服务端',
+    displayName: t('displayName'),
     subsystem: 'platform',
     configSchema,
     provides: [webuiServer, platform],
@@ -210,51 +213,64 @@ export default definePlugin({
 });
 async function startWebuiServer(caps) {
     const { events, logger, lifecycle, provide, services } = caps;
-    const cfg = parseConfig(configSchema, caps.config, logger);
+    const cfg = parseConfig(configSchema, caps.config.use, logger.use);
     const uiConfig = {
         ...cfg,
-        fileRoot: cfg.fileRoot || configSchema.fileRoot.default,
         marketplaceRegistry: cfg.marketplaceRegistry.trim() || configSchema.marketplaceRegistry.default,
     };
-    if (!uiConfig.host.trim())
-        throw configError('host 不能为空');
-    if (!Number.isInteger(uiConfig.port) || uiConfig.port < 0 || uiConfig.port > 65535) {
-        throw configError('port 必须是 0-65535 的整数');
-    }
     if (!URL.canParse(uiConfig.marketplaceRegistry))
-        throw configError('marketplaceRegistry 不是有效 URL');
-    // 创建 storage gateway；所有文件读写（token、access、文件管理）都走这里
-    const storage = createStorageGateway(caps.storage);
+        throw configError(t('registryInvalid'));
+    // 创建 storage gateway；所有文件读写（token、访问凭据、媒体与会话文件）都走这里
+    const storage = caps.storage.use;
+    // 给人看的文字按全局层的语言渲染（localize.ts）：回应、登录页与恢复页、access.txt
+    const localizer = createLocalizer(caps.i18n, logger.use);
+    /** 多语言路由与插件前端的字典要的：i18n、语言包的来源与全局层的语言链 */
+    const i18nDeps = { i18n: caps.i18n, contributions: caps.contributions, localizer };
     // ---- 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(t('tokenTooShort', { min: FIXED_TOKEN_MIN_LENGTH, length: fixedToken.length }));
+    }
     let authToken = fixedToken || Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString('hex');
     /** 监听成功后的访问 URL；持久化 token 晚于监听读回时，据此重写 access.txt */
     let listeningUrl;
-    /** 返回是否真的写成了：调用方据此决定能不能宣称「凭据已写入」 */
+    // 本激活自己发起、没有请求在等的写盘（token 与 access.txt）：收尾时等它们落定。停机、停用或重载返回之后本实例不再往
+    // 家目录里写，接手的实例写下的 access.txt 也不会被旧实例晚到的一次盖掉
+    const pendingWrites = new Set();
+    function trackWrite(work) {
+        const running = work().finally(() => pendingWrites.delete(running));
+        pendingWrites.add(running);
+        return running;
+    }
+    lifecycle.use.onDrain(async () => {
+        await Promise.all(pendingWrites);
+    }, '等 token 与访问凭据落盘');
+    /** 返回是否真的写成了：调用方据此决定能不能宣称「凭据已写入」。说明行按全局层的语言写 */
     async function writeAccessFile(url, token) {
-        const lines = [
-            '# Aalis WebUI 访问凭据（自动生成）',
-            `# 生成时间: ${new Date().toISOString()}`,
-            `# Token 模式: ${uiConfig.tokenMode}`,
+        const lines = textLines([
+            t('accessTitle'),
+            t('accessGenerated', { time: new Date().toISOString() }),
+            t('accessMode', { mode: uiConfig.tokenMode }),
             '',
             `URL: ${url}`,
             `Token: ${token}`,
-            `一键登录: ${url}?token=${token}`,
+            t('accessLogin', { url: `${url}?token=${token}` }),
             '',
-            '# 提示：将该一键登录链接粘贴到浏览器即可自动设置 cookie',
-        ];
+            t('accessHint'),
+        ]);
         try {
-            await storage.writeFile(accessFileUri, `${lines.join('\n')}\n`);
+            await storage.writeFile(accessFileUri, `${localizer.render(lines)}\n`, { secret: true });
             return true;
         }
         catch (err) {
-            logger.warn(`写入访问文件失败: ${err.message}`);
+            logger.use.warn(`写入访问文件失败: ${err.message}`);
             return false;
         }
     }
@@ -264,14 +280,13 @@ 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(() => {
         if (tokenSettled)
             return;
-        tokenLoading = (async () => {
+        tokenLoading = trackWrite(async () => {
             try {
                 const raw = await storage.readFile(tokenFileUri, 'utf-8');
                 const existing = (typeof raw === 'string' ? raw : raw.toString('utf-8')).trim();
@@ -281,8 +296,12 @@ async function startWebuiServer(caps) {
                     if (existing !== authToken) {
                         authToken = existing;
                         if (listeningUrl)
-                            void writeAccessFile(listeningUrl, authToken);
+                            await writeAccessFile(listeningUrl, authToken);
                     }
+                    // 读回的照样按凭据重写一遍：文件原先的权限（别处拷来、按默认权限写下的）一律收紧
+                    await storage
+                        .writeFile(tokenFileUri, existing, { secret: true })
+                        .catch((err) => logger.use.warn(`token 文件没能按凭据重写，别的系统用户可能读得到它: ${err.message}`));
                     return;
                 }
             }
@@ -290,56 +309,70 @@ 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}`);
             }
-        })();
+        });
     });
     // storage 已在线时 follow 是同步首挂：等读回完成再继续，认证从第一个请求起就用持久化的 token
     if (tokenLoading)
         await tokenLoading;
-    const auth = createAuthSystem(() => authToken);
+    const auth = createAuthSystem(() => authToken, localizer, [uiConfig.host, ...uiConfig.allowedHosts]);
     const expressApp = express();
+    // 回应里的文字按全局层的语言渲染：中间件最早挂上，之后的路由与中间件回的 JSON 都经过它
+    expressApp.use(localizer.middleware);
+    // 文档级 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，再由服务解析（偏好 > 优先级 > 注册顺序）定出活跃前端。
@@ -347,14 +380,39 @@ async function startWebuiServer(caps) {
     let staticMiddleware = null;
     function mountStaticDir(dir) {
         if (existsSync(dir)) {
-            staticMiddleware = express.static(dir);
-            logger.info(`前端静态目录: ${dir}`);
+            // 入口 index.html 不由它给：SPA 兜底写好 <html lang> 再发
+            staticMiddleware = express.static(dir, { index: false });
+            logger.use.info(`前端静态目录: ${dir}`);
+            registerClientTexts(join(dir, CLIENT_TEXTS_FILE));
         }
         else {
             staticMiddleware = null;
-            logger.warn(`前端目录不存在: ${dir}`);
+            logger.use.warn(`前端目录不存在: ${dir}`);
         }
     }
+    /**
+     * 前端随它带的字典（api-webui 的 CLIENT_TEXTS_FILE）登记进服务进程的目录：「翻译」页列得出它们，语言包作者拿得到原文指纹。
+     * 目录没有删除，换掉的前端的字典留着。没有这个文件的前端照常挂载；读不出、不是数组时不登记，有条目不合格时合格的照登，都告警
+     */
+    function registerClientTexts(file) {
+        if (!existsSync(file))
+            return;
+        let entries;
+        try {
+            entries = JSON.parse(readFileSync(file, 'utf-8'));
+        }
+        catch (err) {
+            logger.use.warn(`前端的字典 ${file} 读不出，没有登记:`, err);
+            return;
+        }
+        if (!Array.isArray(entries)) {
+            logger.use.warn(`前端的字典 ${file} 不是数组，没有登记`);
+            return;
+        }
+        const refused = entries.filter(entry => !registerCatalogEntry(entry)).length;
+        if (refused > 0)
+            logger.use.warn(`前端的字典 ${file} 里有 ${refused} 条不合格，没有登记`);
+    }
     // 已发现的前端候选（app:ready 时填充，逐个注册为 webui-client 服务 provider）。
     const clientCandidates = [];
     /**
@@ -367,11 +425,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();
@@ -379,11 +438,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) => {
@@ -395,35 +450,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 = {
@@ -446,8 +472,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,
@@ -455,934 +483,482 @@ 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,
+        texts: plugin => frameTexts(i18nDeps, plugin),
+    }, 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: t('logFilterInvalid') });
+            return;
         }
-        catch (err) {
-            res.status(500).json({ error: err.message });
+        if (!caps.logs.present) {
+            res.status(503).json({ error: t('noHostLogs') });
+            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: t('logBeforeRequired') });
             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) {
-            if (p.displayName) {
-                displayNameMap.set(p.name, p.displayName);
-                displayNameMap.set(p.instanceId, p.displayName);
+            const name = asText(p.displayName);
+            if (name) {
+                displayNameMap.set(p.name, name);
+                displayNameMap.set(p.instanceId, name);
             }
         }
         // 根激活归宿主：core 的内置服务与宿主登记的 host-config / plugin-source 都在这里（与市场依赖图同一标签）。
         // 别把内部 id 'root' 裸露给用户。
-        displayNameMap.set('root', '宿主');
-        const serviceNames = services.names();
+        displayNameMap.set('root', t('host'));
+        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,
                     displayName: displayNameMap.get(e.contextId),
-                    label: e.label,
+                    label: asText(e.label),
                     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: t('noProvider', { service: 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: t('noHostConfigPreference') });
             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: t('contextIdRequired') });
+            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: t('contextIdRequired') });
             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: t('pluginMissing', { instance: 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} 不合主题文件的格式，没有列出：${toSource(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} 当前没有已注册的模型，无法刷新`,
+                        ? t('refreshUnsupported', { provider: contextId })
+                        : t('refreshNoModels', { provider: contextId }),
                 });
                 return;
             }
-            const result = await target.instance.refresh();
+            const result = await target.use.refresh();
             res.json({ ok: true, ...result });
         }
         catch (err) {
-            res.status(500).json({ error: err.message });
+            res.status(500).json({ error: textOf(err) });
         }
     });
     // 获取某个服务的可用模型/选项列表
-    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) });
+        // 插件经贡献点 webui:options 登记的可选项来源先查：同名的取全局键最前的那家，dependency 原样交给它
+        const source = caps.contributions.present
+            ? caps.contributions.use.collect('webui:options').find(({ spec }) => spec.id === serviceName)
+            : undefined;
+        if (source) {
+            const { dependency } = req.query;
+            const options = await source.spec.list(typeof dependency === 'string' ? dependency : undefined);
+            res.json({ models: options.map(option => option.value), details: options });
             return;
         }
-        // 特殊处理 gateway-scopes：基于已注册 adapter.sessionTypes 真实声明生成
-        // platform×sessionType 的笛卡尔积。无声明的 adapter 视为单会话（不展开 sessionType）。
-        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 ?? [];
-                platformTypes.set(a.platform, types);
-                for (const t of types)
-                    allTypes.add(t);
-            }
-            const scopes = [];
-            scopes.push({ value: '*', label: '* （全部平台 × 全部类型）' });
-            for (const t of [...allTypes].sort()) {
-                scopes.push({ value: `*:${t}`, label: `*:${t} （所有平台的 ${t} 会话）` });
+        // 深度思考的档位：可选项依赖「模型」这一项，dependency 带它的值（条目 id，按 api-llm 的写法拆）；没带时没有可选项，
+        // 不替调用方挑模型。默认档标 default（没设时界面据它写按哪一档跑），模型不能调时没有可选项。labels 是各模型声明过的
+        // 档位的名字（同一个 id 取先登记的）：换了模型以后存着的档位不在可选项里，界面按它写出名字
+        if (serviceName === 'llm-thinking') {
+            const { dependency } = req.query;
+            const ref = typeof dependency === 'string' ? modelRefOf(dependency) : undefined;
+            if (dependency !== undefined && !ref) {
+                res.status(400).json({ error: t('dependencyInvalid') });
+                return;
             }
-            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}` });
-                }
+            const thinking = ref && 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: scopes.map(s => s.value), details: scopes });
+            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：优先从工具分组注册表获取，回退到扫描工具
+        // 工具分组：已登记的分组与工具上出现过的分组取并集，按名字排；登记过的写名字、说明取 summary（description 只给模型），
+        // 没登记的写原名。'*' 是全部分组（api-tools 的分组约定），总在最前、不带成员。有工具的分组带组内工具的名字（members，按
+        // 名字排，一个工具在几组就在每组都列，同一组写了两遍的只列一次）；不属于任何分组的工具另交 others，没有时不交
         if (serviceName === 'toolGroups') {
-            const groups = caps.tools.current?.getGroups() ?? [];
-            // '*' = 全部分组（plugin-tools 的分组过滤认它），与会话范围选项的「* （全部平台）」同一写法
-            if (groups.length > 0) {
-                res.json({
-                    models: ['*', ...groups.map(g => g.name).sort()],
-                    details: [
-                        { value: '*', label: '* （全部分组）' },
-                        ...groups.map(g => ({
-                            value: g.name,
-                            label: g.label,
-                            description: descSummary(g.description),
-                            pluginName: g.pluginName,
-                        })),
-                    ],
-                });
-            }
-            else {
-                // 回退：从已注册工具中提取分组名称
-                const allTools = caps.tools.current?.getAll() ?? [];
-                const groupSet = new Set();
-                for (const t of allTools) {
-                    t.groups?.forEach((g) => {
-                        groupSet.add(g);
-                    });
+            const registered = new Map((caps.tools.present ? caps.tools.use.getGroups() : []).map(g => [g.name, g]));
+            const members = new Map();
+            const ungrouped = [];
+            for (const tool of caps.tools.present ? caps.tools.use.getAll() : []) {
+                if (!tool.groups?.length)
+                    ungrouped.push(tool.name);
+                for (const g of new Set(tool.groups)) {
+                    const list = members.get(g) ?? [];
+                    list.push(tool.name);
+                    members.set(g, list);
                 }
-                res.json({ models: ['*', ...[...groupSet].sort()] });
             }
+            const names = new Set([...registered.keys(), ...members.keys()]);
+            const details = [...names].sort().map(name => {
+                const group = registered.get(name);
+                return {
+                    value: name,
+                    label: group?.label ?? name,
+                    description: group?.summary,
+                    members: members.get(name)?.sort(),
+                };
+            });
+            res.json({
+                models: ['*', ...details.map(detail => detail.value)],
+                details: [{ value: '*', label: t('allGroups') }, ...details],
+                ...(ungrouped.length > 0 ? { others: { label: t('ungroupedTools'), members: ungrouped.sort() } } : {}),
+            });
             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: asText(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 {
-                    // 单个提供者获取模型失败不影响整体
-                }
-            }
-            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);
-            }
-        });
-        // 挂到 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;
-        };
-    });
-    // ---------- 文件管理 API ----------
-    registerFileRoutes(expressApp, { storage, fileRoot: uiConfig.fileRoot }, gate);
-    registerUploadedFilesRoutes(expressApp, {
-        storage,
-        logger,
-        fileIndex: () => services.get('file-reader'),
-    }, gate);
-    registerProxyRoutes(expressApp, logger, gate);
-    // ---------- WebSocket ----------
-    wss.on('connection', (ws, req) => {
-        // 连接建立时解析一次调用者身份（cookie 在升级请求里；verifyClient 已保证已认证）
-        const wsIdentity = auth.identify(req) ?? { platform: 'webui', userId: 'console' };
-        logger.debug(`WebUI 客户端已连接: ${wsIdentity.platform}:${wsIdentity.userId}`);
-        allClients.add(ws);
-        heartbeat.track(ws);
-        ws.on('message', async (data) => {
-            // 非 JSON 帧与形状不对的帧同属协议违规：都只记一行告警，外层 catch 留给真正的处理失败
-            let raw;
-            try {
-                raw = JSON.parse(data.toString());
-            }
-            catch {
-                logger.warn('WebUI 收到协议违规消息: 非 JSON 帧');
-                return;
-            }
+        // 合起各提供者的取值（人设卡等服务走 listModels()）
+        const allProviders = services.use.all(serviceName);
+        const models = [];
+        for (const provider of allProviders) {
+            if (typeof provider.instance.listModels !== 'function')
+                continue;
             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 } : {}),
-                });
+                models.push(...(await provider.instance.listModels()).map(String));
             }
             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);
+                // 单个提供者获取失败不影响整体，它的取值从下拉里消失：记下是谁、为什么
+                logger.use.warn(`取 ${serviceName} 的可选值时 ${provider.contextId} 失败，它的取值不在下拉里:`, err);
             }
         }
+        res.json({ models });
     });
-    // 重启通知：广播给所有客户端。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)
+    registerI18nRoutes(expressApp, i18nDeps, 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) => {
+        // 每条连接都过心跳，关掉的也一样：回收半开连接，track 同时挂上 'error' 兜底监听（见 ws-heartbeat.ts）
+        heartbeat.track(ws);
+        ws.on('close', () => heartbeat.untrack(ws));
+        // 连接建立时解析一次调用者身份（cookie 在升级请求里）。verifyClient 与这里同步相继判同一个 cookie；认不出时按未认证
+        // 关掉，不补身份
+        const wsIdentity = auth.identify(req);
+        if (!wsIdentity) {
+            logger.use.warn('WebUI 连接认不出身份，已关闭这条连接');
+            ws.close(1008, '认不出身份');
             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);
-            }
-        }
-    });
-    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)
+        logger.use.debug(`WebUI 客户端已连接: ${wsIdentity.platform}:${wsIdentity.userId}`);
+        if (wsPath(req) === ADMIN_PATH) {
+            admin.accept(ws);
             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);
-            }
         }
+        sessionSockets.add(ws);
+        ws.on('close', () => sessionSockets.delete(ws));
+        acceptSessionSocket(ws, { identity: wsIdentity, surface: approvalSurface }, caps.sessionProtocol.present ? caps.sessionProtocol.use : undefined);
     });
-    // 压缩状态通知：memory-summary 发出 session:compressing 事件，广播给订阅该会话的客户端
-    events.on('session:compressing', info => {
-        const sockets = sessions.get(info.sessionId);
-        if (!sockets)
-            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);
-            }
-        }
+    // 管理面推送（/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();
     });
-    // 会话切换不再跨客户端广播：每个 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)
+    // 宿主配置文档变了（插件详情保存、手改配置文件、会话设置写全局层与偏好）：插件详情与界面语言据它重取
+    events.use.on('host-config:changed', () => admin.send({ type: 'plugins.changed' }));
+    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 的收件箱，页面只是查看器，打开着的页面由会话服务推送。
+    // 回执表示这条消息已经由存档记进会话历史（recordOutbound），不看有没有页面在线；送达就是写进历史，不另发 outbound:delivered。
+    // owner 从 WebUI 驱动的 IM 房间（根会话记下了出生平台）由那个平台的适配器认领，子会话没有窗口、由存档认领
+    events.use.on('outbound:message', (msg) => {
+        if (msg.delivery || msg.platform !== 'webui')
             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)
+        const sm = caps.sessions.present ? caps.sessions.use : undefined;
+        const session = sm?.getSession(msg.sessionId);
+        if (session?.parentId)
             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;
-                }
-            }
-        }
-        const sockets = sessions.get(info.sessionId);
-        if (!sockets)
+        const root = sm && rootSessionOf(session, id => sm.getSession(id));
+        if (root?.originPlatform !== undefined)
             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);
-            }
-        }
-    });
-    // 监听 token 使用量统计事件
-    events.on('token:usage', usage => {
-        const sockets = sessions.get(usage.sessionId);
-        if (!sockets)
+        if (!caps.archive.present) {
+            msg.delivery = Promise.resolve({ ok: false, error: t('archiveAbsent') });
             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);
-            }
         }
+        msg.delivery = caps.archive.use.recordOutbound(msg).then(() => ({ ok: true }), error => ({ ok: false, error: textOf(error) }));
     });
     // 前端切换「逃生页」：由 webui-server 直出、独立于任何可被切换的前端，故任意前端（哪怕
     // 极简第三方前端无切换 UI）卡住时都能在此切回。受全局 auth 中间件登录保护；切换走既有 owner
     // 闸的 POST /api/services/webui-client/prefer，本页零新增后端逻辑（见 client-switch-page.ts）。
     // 注册在 SPA 兜底之前，故 `/__clients` 被本路由先接走、不落到前端 index.html。
-    expressApp.get('/__clients', (_req, res) => {
-        res.type('html').send(renderClientSwitchPage());
+    route(expressApp, 'GET /__clients', (_req, res) => {
+        const text = localizer.render(CLIENT_SWITCH_TEXTS);
+        res.type('html').send(renderClientSwitchPage({ ...text, lang: pageLanguageOf(text.lang, localizer.languages()) }));
     });
-    // API 未命中：回 404 JSON，不落到 SPA 兜底（否则客户端拿到 HTML 去解析 JSON）。
-    expressApp.all('/api/{*path}', (req, res) => {
-        res.status(404).json({ error: `未知 API: ${req.method} ${req.path}` });
+    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: t('unknownApi', { method: req.method, path: req.path }) });
     });
-    // SPA fallback: 所有非 API 路径返回 index.html
-    expressApp.get('{*path}', (_req, res) => {
-        const indexPath = resolve(clientDist, 'index.html');
-        if (existsSync(indexPath)) {
-            res.sendFile(indexPath);
+    // SPA fallback: 所有非 API 路径返回 index.html，<html lang> 与界面的语言块按全局层的语言写好；/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)) {
+            // 每次再验证：页面随全局层的语言变
+            const lang = pageLanguageOf(localizer.render(t('pageLanguage')), localizer.languages());
+            res.set('Cache-Control', 'public, max-age=0');
+            res.type('html').send(withPageLanguage(readFileSync(indexPath, 'utf-8'), lang, interfaceLanguage(localizer)));
         }
         else {
-            res
-                .status(404)
-                .json({ error: '前端未就绪：请安装一个带 aalis.client 标记的前端包（如 @aalis/plugin-webui-client）' });
+            res.status(404).json({ error: t('noClient') });
         }
     });
+    // 路由与中间件抛出的错误（请求体不是 JSON 或太大、路径参数解不开、处理函数出错）：/api/ 下回 ErrorResponse，别处回纯文本，
+    // 都不带堆栈，原因只进日志。挂着文字对象的错误（TextError、withText）是写给人看的：状态取它的 status，没有时 400，
+    // 按读者语言给出它的文字。请求体解析的拒绝按 type 给字典里的整句，库的原句（英文、带解析位置）只进 debug 日志。
+    // 挂在全部路由之后（插件前端的挂载另有自己的，紧跟在挂载之后）
+    expressApp.use((err, req, res, next) => {
+        if (res.headersSent)
+            return next(err);
+        const { status, type, message } = err;
+        const told = isTextError(err);
+        const code = typeof status === 'number' && status >= 400 && status < 600 ? status : told ? 400 : 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 = told
+            ? err.text
+            : code >= 500
+                ? t('serverError')
+                : typeof type === 'string' && Object.hasOwn(BODY_REJECTIONS, type)
+                    ? BODY_REJECTIONS[type]
+                    : t('badRequest');
+        if (req.path.startsWith('/api/'))
+            res.status(code).json({ error: reason });
+        else
+            res.status(code).type('text').send(localizer.render(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，
@@ -1397,7 +973,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 更新。不重挂的话，被摘掉的正好是当前
@@ -1407,32 +983,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 →
@@ -1444,7 +1029,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 会让
@@ -1454,10 +1039,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 仅本次启动有效，重启轮换'
@@ -1465,15 +1050,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}`);
-            void (async () => {
+            // 仅打不带 token 的 URL，完整一键登录链接见 access.txt（按凭据写，只给本机用户读）。
+            logger.use.info(`首次访问 URL（${tokenHint}）: ${url} —— 完整一键登录链接见 ${accessFileUri}`);
+            void trackWrite(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;
@@ -1483,24 +1069,28 @@ async function startWebuiServer(caps) {
                     }
                 }
                 catch (err) {
-                    logger.debug(`解析访问凭据文件绝对路径失败: ${err.message}`);
+                    logger.use.debug(`解析访问凭据文件绝对路径失败: ${err.message}`);
                 }
-                logger.info(`访问凭据已写入: ${accessFileUri}（绝对路径: ${absHint}）`);
-            })();
-            if (uiConfig.autoOpen && tokenFresh)
-                openBrowser(accessUrl, createProcessGateway(caps.process));
+                logger.use.info(`访问凭据已写入: ${accessFileUri}（绝对路径: ${absHint}）`);
+            });
+            // 记的是宿主实例本身（业务句柄每次激活各一个，认不出同一个宿主）
+            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 正在卸载');
             }
@@ -1508,95 +1098,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