@aalis/plugin-webui-server 0.15.0 → 0.16.0

package/dist/index.js

@@ -12,70 +12,47 @@ import { contributions } from '@aalis/api-contributions';
 import { hostConfig } from '@aalis/api-host-config';
 import { hostLogs } from '@aalis/api-host-logs';
 import { hostPaths } from '@aalis/api-host-paths';
-import { llm, resolveLLMModel } from '@aalis/api-llm';
+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 { aggregatePlatformDetails, getPlatformAdapters, getPlatformNames, platform, sessionTypesOf, } from '@aalis/api-platform';
+import { aggregatePlatformDetails, platform } from '@aalis/api-platform';
 import { pluginSource } from '@aalis/api-plugin-source';
 import { processService } from '@aalis/api-process';
 import { rootSessionOf, sessionManager } from '@aalis/api-session-manager';
 import { sessionProtocol } from '@aalis/api-session-protocol';
-import { isStorageUri, storage } from '@aalis/api-storage';
+import { storage } from '@aalis/api-storage';
 import { tools } from '@aalis/api-tools';
-import { parseTheme, webuiClient, webuiServer, } from '@aalis/api-webui';
+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 { outboundMediaMessage, WellKnownKinds, WellKnownMetadataKeys, } from '@aalis/schema-message';
+import { asText, isTextError, registerCatalogEntry, textLines, textOf, toSource, } from '@aalis/schema-i18n';
 import express from 'express';
 import { WebSocketServer } from 'ws';
 import { ADMIN_PATH, createAdminChannel } from './admin-channel.js';
 import { blockedStatus, createAttention } from './attention.js';
-import { createAuthSystem, openBrowser, originAllowed } from './auth.js';
+import { createAuthSystem, isHostName, openBrowser, originAllowed } from './auth.js';
 import { collectLocalPackageDeps, discoverClients, pickFreshClients } from './client-discovery.js';
-import { CLIENT_SWITCH_SCRIPT, 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 { 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 { 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;
-}
-/** 可选项接口的 dependency 查询参数当模型引用读（llm-ref 的取值，JSON）：没带为 undefined，写法不对为 null */
-function modelRefOf(raw) {
-    if (raw === undefined)
-        return undefined;
-    let value;
-    try {
-        value = typeof raw === 'string' ? JSON.parse(raw) : undefined;
-    }
-    catch {
-        return null;
-    }
-    if (typeof value !== 'object' || value === null || Array.isArray(value))
-        return null;
-    const { provider, model } = value;
-    return (provider === undefined || typeof provider === 'string') && (model === undefined || typeof model === 'string')
-        ? { provider, model }
-        : null;
-}
 // ===== 插件元数据 =====
 const name = '@aalis/plugin-webui-server';
 // 按宿主身份记打开记录：插件 bounce 保留，新 App 独立；弱引用不延长宿主寿命。
@@ -96,116 +73,83 @@ const DOCUMENT_CSP = [
     "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: '端口',
+        label: t('portLabel'),
         default: 3000,
         integer: true,
         min: 0,
         max: 65535,
         onInvalid: 'error',
-        description: 'Web 管理界面的 HTTP 端口',
+        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'),
+    },
+    allowedHosts: {
+        type: 'multiselect',
+        label: t('allowedHostsLabel'),
+        default: [],
+        onInvalid: 'error',
+        // 主机名由使用者填写，静态选项无法穷举。
+        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 的插件重载不重复打开，重新生成 token 时再次打开以便登录。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',
         secret: true,
-        description: `至少 ${FIXED_TOKEN_MIN_LENGTH} 个字符的随机字符串（去掉首尾空白后计），短了插件不启动；留空按 persist 处理。存进 secrets.yaml，WebUI 不回显。`,
+        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 设置「系统」的服务偏好里切换。
 });
-// ===== WebUI 会话的收件箱 =====
-/**
- * 发往 WebUI 自己会话的出站消息里，要由本插件写进会话历史的部分。WebUI 的收件箱就是会话历史，记不记全不取决于
- * 别的插件是否在场。agent 的文字回复由 agent 存档，这里不再记，免得历史里重复。其余部分：
- * - 不是她说的文字（系统提示、指令回复、宿主通知）记成事件标记：回看时显示成分隔条，不进模型上下文，与其他平台一致；
- * - 图片、视频、音频用 outboundMediaMessage 记，回看时还原成附件；
- * - 给的是存储地址的文件（插件发出的成品等）同样用 outboundMediaMessage 记，描述位记文件名，会话服务据此签发下载句柄。
- *   metadata 另记原样的地址与文件名（登记的键 SentRef、SentName）：占位符里的地址遇到「]」会截断，描述位的「]」「|」换成了全角。这样的文件以
- *   「[文件: 名称 | ref:…]」进模型上下文与记忆，不看全局出站归档记不记文件。不是存储地址的文件
- *   （网址、data URL）签不出句柄，记成事件标记「[文件] 名称」，内容不进历史；
- * - 快照里的 data 未经平台改写，就是页面上显示的那份，直接记它。带 skipArchive 的（history_ref 重发）原图已在
- *   历史里，不再记。她发出的媒体在别的平台由全局出站归档在 outbound:delivered 上记；发往 WebUI 的由这里记，
- *   outbound:delivered 的快照给附件标上 skipArchive，免得全局出站归档再记一份。代价是这些网址图片与视频不再由
- *   全局出站归档在后台补视觉描述
- */
-function inboxRecords(msg) {
-    const timestamp = Date.now();
-    const marker = (content) => ({
-        role: 'system',
-        kind: WellKnownKinds.EventMarker,
-        content,
-        timestamp,
-    });
-    const records = [];
-    if (msg.source !== 'agent' && msg.content.trim())
-        records.push(marker(msg.content));
-    for (const att of msg.attachments ?? []) {
-        if (att.skipArchive)
-            continue;
-        if (att.kind !== 'file') {
-            records.push({
-                ...outboundMediaMessage(att.kind, att.data, att.description),
-                timestamp,
-                metadata: { [WellKnownMetadataKeys.Source]: 'webui-server', [WellKnownMetadataKeys.SentRef]: att.data },
-            });
-        }
-        else if (isStorageUri(att.data)) {
-            records.push({
-                ...outboundMediaMessage('file', att.data, att.name),
-                timestamp,
-                metadata: {
-                    [WellKnownMetadataKeys.Source]: 'webui-server',
-                    [WellKnownMetadataKeys.SentRef]: att.data,
-                    [WellKnownMetadataKeys.SentName]: att.name,
-                },
-            });
-        }
-        else {
-            records.push(marker(`[文件] ${att.name ?? att.data.split('/').pop()}`));
-        }
-    }
-    return records;
-}
 // ===== 插件入口 =====
 /**
  * 本地包扫描目录：安装集（host-paths 的 `app`）下的 `packages/` 与 `node_modules/@aalis`，与插件加载器读的是同一处。
@@ -253,12 +197,14 @@ const uses = {
     llm: optional(llm),
     /** 插件经贡献点 webui:theme 提供的主题（GET /api/themes） */
     contributions: optional(contributions),
-    // 发往 WebUI 自己会话的出站消息由本插件写进会话历史（见 inboxRecords）
+    /** 发往 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],
@@ -273,9 +219,13 @@ async function startWebuiServer(caps) {
         marketplaceRegistry: cfg.marketplaceRegistry.trim() || configSchema.marketplaceRegistry.default,
     };
     if (!URL.canParse(uiConfig.marketplaceRegistry))
-        throw configError('marketplaceRegistry 不是有效 URL');
+        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，重启复用（默认）
@@ -286,26 +236,37 @@ async function startWebuiServer(caps) {
     const accessFileUri = 'data:/webui/access.txt';
     const fixedToken = uiConfig.tokenMode === 'fixed' ? uiConfig.fixedToken.trim() : '';
     if (fixedToken && fixedToken.length < FIXED_TOKEN_MIN_LENGTH) {
-        throw configError(`fixedToken 至少要 ${FIXED_TOKEN_MIN_LENGTH} 个字符（现在 ${fixedToken.length} 个）`);
+        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`, { secret: true });
+            await storage.writeFile(accessFileUri, `${localizer.render(lines)}\n`, { secret: true });
             return true;
         }
         catch (err) {
@@ -325,7 +286,7 @@ async function startWebuiServer(caps) {
     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();
@@ -335,7 +296,7 @@ async function startWebuiServer(caps) {
                     if (existing !== authToken) {
                         authToken = existing;
                         if (listeningUrl)
-                            void writeAccessFile(listeningUrl, authToken);
+                            await writeAccessFile(listeningUrl, authToken);
                     }
                     // 读回的照样按凭据重写一遍：文件原先的权限（别处拷来、按默认权限写下的）一律收紧
                     await storage
@@ -354,13 +315,15 @@ async function startWebuiServer(caps) {
             catch (err) {
                 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) => {
@@ -417,14 +380,39 @@ async function startWebuiServer(caps) {
     let staticMiddleware = null;
     function mountStaticDir(dir) {
         if (existsSync(dir)) {
-            staticMiddleware = express.static(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.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 = [];
     /**
@@ -520,6 +508,7 @@ async function startWebuiServer(caps) {
         storageReady: () => caps.storage.present,
         send: event => admin.send(event),
         logger: logger.use,
+        texts: plugin => frameTexts(i18nDeps, plugin),
     }, auth.identify, gate);
     registerMarketplaceRoutes(expressApp, {
         logger: logger.use,
@@ -552,11 +541,11 @@ async function startWebuiServer(caps) {
     const sendLogs = async (query, res, before) => {
         const filter = parseLogFilter(query);
         if (!filter) {
-            res.status(400).json({ error: '日志筛选写法不对：level 只收 debug、info、warn、error，每一项最多给一次' });
+            res.status(400).json({ error: t('logFilterInvalid') });
             return;
         }
         if (!caps.logs.present) {
-            res.status(503).json({ error: '宿主未提供日志服务（host-logs），读不到日志' });
+            res.status(503).json({ error: t('noHostLogs') });
             return;
         }
         const limit = Math.min(Math.max(Number(query.limit) || 200, 1), 5000);
@@ -568,7 +557,7 @@ async function startWebuiServer(caps) {
     route(expressApp, 'GET /api/logs/range', gate(), (req, res) => {
         const before = Number(req.query.before);
         if (!Number.isFinite(before)) {
-            res.status(400).json({ error: '往前翻日志要给数字参数 before（取 seq 比它小的那几条）' });
+            res.status(400).json({ error: t('logBeforeRequired') });
             return;
         }
         return sendLogs(req.query, res, before);
@@ -579,14 +568,15 @@ async function startWebuiServer(caps) {
         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', '宿主');
+        displayNameMap.set('root', t('host'));
         const serviceNames = services.use.names();
         const detail = {};
         for (const svcName of serviceNames) {
@@ -596,7 +586,7 @@ async function startWebuiServer(caps) {
                 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,
                 })),
@@ -612,11 +602,11 @@ async function startWebuiServer(caps) {
      */
     const changePreference = async (svcName, contextId, scope, res) => {
         if (contextId !== null && !services.use.inspect(svcName).some(e => e.contextId === contextId)) {
-            res.status(404).json({ error: `服务 ${svcName} 没有 id 为 ${contextId} 的提供者` });
+            res.status(404).json({ error: t('noProvider', { service: svcName, id: contextId }) });
             return;
         }
         if (!caps.hostConfig.present) {
-            res.status(503).json({ error: '宿主未提供配置文档（host-config），无法保存偏好' });
+            res.status(503).json({ error: t('noHostConfigPreference') });
             return;
         }
         const host = caps.hostConfig.use;
@@ -640,7 +630,7 @@ async function startWebuiServer(caps) {
     route(expressApp, 'POST /api/services/:name/prefer', gate(), async (req, res) => {
         const contextId = preferredIn(req.body);
         if (!contextId) {
-            res.status(400).json({ error: '请求体要给 contextId：偏好的那个提供者的 id' });
+            res.status(400).json({ error: t('contextIdRequired') });
             return;
         }
         await changePreference(String(req.params.name), contextId, {}, res);
@@ -649,12 +639,12 @@ async function startWebuiServer(caps) {
     route(expressApp, 'POST /api/plugins/:instanceId/services/:name/prefer', gate(), async (req, res) => {
         const contextId = preferredIn(req.body);
         if (!contextId) {
-            res.status(400).json({ error: '请求体要给 contextId：偏好的那个提供者的 id' });
+            res.status(400).json({ error: t('contextIdRequired') });
             return;
         }
         const instanceId = String(req.params.instanceId);
         if (!caps.plugins.present || !caps.plugins.use.getPlugin(instanceId)) {
-            res.status(404).json({ error: `插件 ${instanceId} 不存在` });
+            res.status(404).json({ error: t('pluginMissing', { instance: instanceId }) });
             return;
         }
         await changePreference(String(req.params.name), contextId, { for: instanceId }, res);
@@ -671,7 +661,7 @@ async function startWebuiServer(caps) {
                 themes.push({ id: key, instance: key.slice(0, key.lastIndexOf('/')), theme: parsed.theme });
             else if (!warnedThemes.has(spec)) {
                 warnedThemes.add(spec);
-                logger.use.warn(`插件主题 ${key} 不合主题文件的格式，没有列出：${parsed.errors.join('；')}`);
+                logger.use.warn(`插件主题 ${key} 不合主题文件的格式，没有列出：${toSource(parsed.errors).join('；')}`);
             }
         }
         res.json({ themes });
@@ -695,8 +685,8 @@ async function startWebuiServer(caps) {
             if (!target) {
                 res.status(404).json({
                     error: llmEntries.length > 0
-                        ? `提供者 ${contextId} 不支持运行时刷新模型列表（例如关闭了模型发现）`
-                        : `提供者 ${contextId} 当前没有已注册的模型，无法刷新`,
+                        ? t('refreshUnsupported', { provider: contextId })
+                        : t('refreshNoModels', { provider: contextId }),
                 });
                 return;
             }
@@ -704,51 +694,33 @@ async function startWebuiServer(caps) {
             res.json({ ok: true, ...result });
         }
         catch (err) {
-            res.status(500).json({ error: err.message });
+            res.status(500).json({ error: textOf(err) });
         }
     });
     // 获取某个服务的可用模型/选项列表
     route(expressApp, 'GET /api/models/:service', gate(), async (req, res) => {
         const serviceName = req.params.service;
-        // 特殊处理 platform：通过 helper 获取已注册的平台名称
-        if (serviceName === 'platform') {
-            res.json({ models: getPlatformNames(caps.platform) });
-            return;
-        }
-        // 特殊处理 gateway-scopes：已注册平台与它们的类型名（sessionTypesOf：没声明类型的平台只有一个类型 private）
-        // 的笛卡尔积
-        if (serviceName === 'gateway-scopes') {
-            const platformTypes = new Map();
-            const allTypes = new Set();
-            for (const a of getPlatformAdapters(caps.platform)) {
-                const types = sessionTypesOf(a).map(t => t.name);
-                platformTypes.set(a.platform, types);
-                for (const t of types)
-                    allTypes.add(t);
-            }
-            const scopes = [];
-            scopes.push({ value: '*', label: '* （全部平台 × 全部类型）' });
-            for (const t of [...allTypes].sort()) {
-                scopes.push({ value: `*:${t}`, label: `*:${t} （所有平台的 ${t} 会话）` });
-            }
-            for (const [p, types] of platformTypes) {
-                scopes.push({ value: `${p}:*`, label: `${p}:* （${p} 全部类型）` });
-                for (const t of types)
-                    scopes.push({ value: `${p}:${t}`, label: `${p}:${t}` });
-            }
-            res.json({ models: scopes.map(s => s.value), details: scopes });
+        // 插件经贡献点 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;
         }
-        // 深度思考的档位：可选项依赖「模型」这一项，dependency 带它的生效值；没带时按服务偏好解析，与对话时同一种解析。
-        // 默认档标 default（没设时界面据它写按哪一档跑），模型不能调时没有可选项。labels 是各模型声明过的档位的名字
-        // （同一个 id 取先登记的）：换了模型以后存着的档位不在可选项里，界面按它写出名字
+        // 深度思考的档位：可选项依赖「模型」这一项，dependency 带它的值（条目 id，按 api-llm 的写法拆）；没带时没有可选项，
+        // 不替调用方挑模型。默认档标 default（没设时界面据它写按哪一档跑），模型不能调时没有可选项。labels 是各模型声明过的
+        // 档位的名字（同一个 id 取先登记的）：换了模型以后存着的档位不在可选项里，界面按它写出名字
         if (serviceName === 'llm-thinking') {
-            const ref = modelRefOf(req.query.dependency);
-            if (ref === null) {
-                res.status(400).json({ error: 'dependency 要是模型引用 { provider, model } 的 JSON' });
+            const { dependency } = req.query;
+            const ref = typeof dependency === 'string' ? modelRefOf(dependency) : undefined;
+            if (dependency !== undefined && !ref) {
+                res.status(400).json({ error: t('dependencyInvalid') });
                 return;
             }
-            const thinking = resolveLLMModel(caps.llm, ref, ['chat'])?.use.thinking;
+            const thinking = ref && resolveLLMModel(caps.llm, ref, ['chat'])?.use.thinking;
             const levels = thinking?.levels ?? [];
             const labels = {};
             for (const entry of caps.llm.list()) {
@@ -764,35 +736,37 @@ async function startWebuiServer(caps) {
             });
             return;
         }
-        // 特殊处理 toolGroups：优先从工具分组注册表获取，回退到扫描工具
+        // 工具分组：已登记的分组与工具上出现过的分组取并集，按名字排；登记过的写名字、说明取 summary（description 只给模型），
+        // 没登记的写原名。'*' 是全部分组（api-tools 的分组约定），总在最前、不带成员。有工具的分组带组内工具的名字（members，按
+        // 名字排，一个工具在几组就在每组都列，同一组写了两遍的只列一次）；不属于任何分组的工具另交 others，没有时不交
         if (serviceName === 'toolGroups') {
-            const groups = caps.tools.present ? caps.tools.use.getGroups() : [];
-            // '*' = 全部分组（api-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.present ? caps.tools.use.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）。
@@ -802,7 +776,7 @@ async function startWebuiServer(caps) {
                 const entries = caps.llm.list();
                 const providers = entries.map(e => ({
                     model: e.use.id,
-                    provider: e.label ?? e.id,
+                    provider: asText(e.label) ?? e.id,
                     contextId: e.use.providerId,
                     capabilities: [...e.use.capabilities],
                 }));
@@ -829,17 +803,24 @@ async function startWebuiServer(caps) {
         }
         res.json({ models });
     });
+    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) => {
-        // 连接建立时解析一次调用者身份（cookie 在升级请求里；verifyClient 已保证已认证）
-        const wsIdentity = auth.identify(req) ?? { platform: 'webui', userId: 'console' };
-        logger.use.debug(`WebUI 客户端已连接: ${wsIdentity.platform}:${wsIdentity.userId}`);
-        // 每条连接都过心跳：回收半开连接，track 同时挂上 'error' 兜底监听（见 ws-heartbeat.ts）
+        // 每条连接都过心跳，关掉的也一样：回收半开连接，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;
+        }
+        logger.use.debug(`WebUI 客户端已连接: ${wsIdentity.platform}:${wsIdentity.userId}`);
         if (wsPath(req) === ADMIN_PATH) {
             admin.accept(ws);
             return;
@@ -855,47 +836,37 @@ async function startWebuiServer(caps) {
         admin.send({ type: 'plugins.changed' });
         attention.pluginsChanged();
     });
+    // 宿主配置文档变了（插件详情保存、手改配置文件、会话设置写全局层与偏好）：插件详情与界面语言据它重取
+    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 的收件箱，页面只是查看器，打开着的页面由会话服务推送。
-    // 回执表示这条消息已经进了会话历史，不看有没有页面在线。owner 从 WebUI 驱动的 IM 房间（根会话记下了出生平台）
-    // 由那个平台的适配器认领
+    // 回执表示这条消息已经由存档记进会话历史（recordOutbound），不看有没有页面在线；送达就是写进历史，不另发 outbound:delivered。
+    // owner 从 WebUI 驱动的 IM 房间（根会话记下了出生平台）由那个平台的适配器认领，子会话没有窗口、由存档认领
     events.use.on('outbound:message', (msg) => {
         if (msg.delivery || msg.platform !== 'webui')
             return;
         const sm = caps.sessions.present ? caps.sessions.use : undefined;
-        const root = sm && rootSessionOf(sm.getSession(msg.sessionId), id => sm.getSession(id));
+        const session = sm?.getSession(msg.sessionId);
+        if (session?.parentId)
+            return;
+        const root = sm && rootSessionOf(session, id => sm.getSession(id));
         if (root?.originPlatform !== undefined)
             return;
-        // 同步挂上 Promise，始终 resolve，即使其他 outbound 监听器随后耗时，也不会产生未处理的 rejection。
-        msg.delivery = (async () => {
-            try {
-                // 保存快照：下游处理不应受生产者或其他适配器后续改写影响。
-                const snapshot = { ...msg, attachments: msg.attachments?.map(att => ({ ...att })) };
-                if (!caps.archive.present)
-                    return { ok: false, error: '消息存档服务不在场，这条消息没有存进 WebUI 会话的历史' };
-                const archive = caps.archive.use;
-                for (const record of inboxRecords(snapshot))
-                    await archive.saveMessage(msg.sessionId, record);
-                if (snapshot.attachments?.length) {
-                    // 附件已由上面记进会话历史（见 inboxRecords），标上 skipArchive，免得全局出站归档再记一份
-                    const attachments = snapshot.attachments.map(att => ({ ...att, skipArchive: true }));
-                    void events.use.emit('outbound:delivered', { ...snapshot, attachments, delivery: undefined });
-                }
-                return { ok: true };
-            }
-            catch (error) {
-                return { ok: false, error: error instanceof Error ? error.message : String(error) };
-            }
-        })();
+        if (!caps.archive.present) {
+            msg.delivery = Promise.resolve({ ok: false, error: t('archiveAbsent') });
+            return;
+        }
+        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。
     route(expressApp, 'GET /__clients', (_req, res) => {
-        res.type('html').send(renderClientSwitchPage());
+        const text = localizer.render(CLIENT_SWITCH_TEXTS);
+        res.type('html').send(renderClientSwitchPage({ ...text, lang: pageLanguageOf(text.lang, localizer.languages()) }));
     });
     route(expressApp, 'GET /__clients.js', (_req, res) => {
         res.type('application/javascript').send(CLIENT_SWITCH_SCRIPT);
@@ -904,10 +875,10 @@ async function startWebuiServer(caps) {
     expressApp.use((req, res, next) => {
         if (!req.path.startsWith('/api/'))
             return next();
-        res.status(404).json({ error: `未知 API: ${req.method} ${req.path}` });
+        res.status(404).json({ error: t('unknownApi', { method: req.method, path: req.path }) });
     });
-    // SPA fallback: 所有非 API 路径返回 index.html；/assets/ 下缺失的文件回 404（旧页面引用的资源换了构建就不在了，
-    // 回 index.html 只会让浏览器把 HTML 当脚本执行）
+    // 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();
@@ -916,32 +887,40 @@ async function startWebuiServer(caps) {
         // 还没有选中的前端时 clientDist 为空：不能拼出相对 cwd 的 index.html
         const indexPath = clientDist ? join(clientDist, 'index.html') : undefined;
         if (indexPath && existsSync(indexPath)) {
-            res.sendFile(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 标记的前端包' });
+            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, expose, message } = err;
-        const code = typeof status === 'number' && status >= 400 && status < 600 ? status : 500;
+        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 = code >= 500
-            ? '处理这个请求时出错，原因见日志'
-            : expose === true && typeof message === '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(reason);
+            res.status(code).type('text').send(localizer.render(reason));
     });
     /**
      * 全动态发现前端：按 `aalis.client:true` 标记扫描，**不硬编码任何前端包名**
@@ -1073,7 +1052,7 @@ async function startWebuiServer(caps) {
             // 不把 token 打进日志（会落 latest.log / 被 /api/logs/* 回放 / 贴日志求助时外泄）。
             // 仅打不带 token 的 URL，完整一键登录链接见 access.txt（按凭据写，只给本机用户读）。
             logger.use.info(`首次访问 URL（${tokenHint}）: ${url} —— 完整一键登录链接见 ${accessFileUri}`);
-            void (async () => {
+            void trackWrite(async () => {
                 // 先把文件写出来，再解析它的绝对路径：resolveLocalPath 走 realpath，文件尚未落盘会抛
                 // ENOENT 被吞掉，于是「绝对路径」退化成原样重复一遍 URI——偏偏首启（新用户唯一需要
                 // 这行的时刻）必然命中，二次启动因文件已在反而正常。两者原先都是 void，谁先到看调度。
@@ -1093,7 +1072,7 @@ async function startWebuiServer(caps) {
                     logger.use.debug(`解析访问凭据文件绝对路径失败: ${err.message}`);
                 }
                 logger.use.info(`访问凭据已写入: ${accessFileUri}（绝对路径: ${absHint}）`);
-            })();
+            });
             // 记的是宿主实例本身（业务句柄每次激活各一个，认不出同一个宿主）
             const host = services.use.get(appService);
             if (uiConfig.autoOpen && (tokenFresh || !host || !browserOpenedFor.has(host))) {