@aalis/plugin-webui-server 0.1.2 → 0.3.0

package/dist/gate.d.ts

@@ -1,5 +1,5 @@
 import type { Context } from '@aalis/core';
-import type { UserIdentity } from '@aalis/plugin-authority-api';
+import type { CapabilityVisibility, UserIdentity } from '@aalis/plugin-authority-api';
 /** 从请求解析调用者身份（auth.ts 的 AuthSystem.identify） */
 type IdentifyFn = (req: {
     headers: {
@@ -18,21 +18,22 @@ interface GateResponse {
 }
 type GateMiddleware = (req: GateRequest, res: GateResponse, next: () => void) => void;
 /**
- * REST 路由权限闸工厂。
+ * REST 路由能力闸工厂。
  *
  * 连接级认证（auth middleware）只回答"是否登录"；本闸回答"该身份能否做这件事"——
- * 每条 REST 路由声明一个 capability 与基础等级门槛，过 authorize 统一闸
- * （与 tool/command/page-action 同一裁决：permissionPolicy > deny > grant > 角色链，
- * 因此可对单个账户 grant `webui:files:read` 这类细粒度放行）。
+ * 每条 REST 路由声明一个 capability 与默认可见性，过 authorize 统一闸
+ * （deny > owner(*) > public > granted）。owner 拥有一切；可对单账户 grant 某条
+ * restricted capability（如 `webui:files:read`）做细粒度委托。
  *
- * 分层缺省（可经 config.permissionAuthority 或 per-user grant/deny 调整）：
- * - 1：公共读（status / pages / 模型列表等，聊天面板可用即可）
- * - 4：管理读（插件清单含原始配置、日志、文件浏览——可能含密钥/敏感信息）
- * - 'owner'：变更操作（配置写、插件启停装卸、服务偏好、文件删改）
+ * 可见性约定（颗粒度由 capability 字符串本身承载，owner 之外的细分靠委托 grant）：
+ * - 'public'：公共读（status / pages / 模型列表等，聊天面板可用即可）。
+ * - 'restricted'：管理读（插件清单含原始配置、日志、文件浏览——可能含密钥）与
+ *   一切变更操作（配置写、插件启停装卸、服务偏好、文件删改）；默认禁，须 owner /
+ *   被委托授予。
  *
- * authority 服务缺席时放行（与 tools/commands 守卫缺席语义一致）。
+ * authority 服务缺席时：public 放行、restricted 503（fail-closed，不在权限服务缺位时裸奔）。
  */
-export declare function createRouteGate(ctx: Context, identify: IdentifyFn): (capability: string, declared: number | "owner") => GateMiddleware;
+export declare function createRouteGate(ctx: Context, identify: IdentifyFn): (capability: string, visibility: CapabilityVisibility) => GateMiddleware;
 /** createRouteGate 返回的闸生成函数类型（传给各 routes/ 注册器） */
 export type RouteGate = ReturnType<typeof createRouteGate>;
 export {};

package/dist/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAElF,gDAAgD;AAChD,KAAK,UAAU,GAAG,CAAC,GAAG,EAAE;IAAE,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAAK,YAAY,GAAG,SAAS,CAAC;AAKtF,UAAU,WAAW;IACnB,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9B;AACD,UAAU,YAAY;IACpB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;CACxD;AACD,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAEtF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,IAIxD,YAAY,MAAM,EAAE,UAAU,MAAM,GAAG,OAAO,KAAG,cAAc,CAuBxE;AAED,kDAAkD;AAClD,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAoB,oBAAoB,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAExG,gDAAgD;AAChD,KAAK,UAAU,GAAG,CAAC,GAAG,EAAE;IAAE,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAAK,YAAY,GAAG,SAAS,CAAC;AAKtF,UAAU,WAAW;IACnB,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9B;AACD,UAAU,YAAY;IACpB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;CACxD;AACD,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAEtF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,IACxD,YAAY,MAAM,EAAE,YAAY,oBAAoB,KAAG,cAAc,CAqB9E;AAED,kDAAkD;AAClD,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/gate.js

@@ -1,38 +1,34 @@
 /**
- * REST 路由权限闸工厂。
+ * REST 路由能力闸工厂。
  *
  * 连接级认证（auth middleware）只回答"是否登录"；本闸回答"该身份能否做这件事"——
- * 每条 REST 路由声明一个 capability 与基础等级门槛，过 authorize 统一闸
- * （与 tool/command/page-action 同一裁决：permissionPolicy > deny > grant > 角色链，
- * 因此可对单个账户 grant `webui:files:read` 这类细粒度放行）。
+ * 每条 REST 路由声明一个 capability 与默认可见性，过 authorize 统一闸
+ * （deny > owner(*) > public > granted）。owner 拥有一切；可对单账户 grant 某条
+ * restricted capability（如 `webui:files:read`）做细粒度委托。
  *
- * 分层缺省（可经 config.permissionAuthority 或 per-user grant/deny 调整）：
- * - 1：公共读（status / pages / 模型列表等，聊天面板可用即可）
- * - 4：管理读（插件清单含原始配置、日志、文件浏览——可能含密钥/敏感信息）
- * - 'owner'：变更操作（配置写、插件启停装卸、服务偏好、文件删改）
+ * 可见性约定（颗粒度由 capability 字符串本身承载，owner 之外的细分靠委托 grant）：
+ * - 'public'：公共读（status / pages / 模型列表等，聊天面板可用即可）。
+ * - 'restricted'：管理读（插件清单含原始配置、日志、文件浏览——可能含密钥）与
+ *   一切变更操作（配置写、插件启停装卸、服务偏好、文件删改）；默认禁，须 owner /
+ *   被委托授予。
  *
- * authority 服务缺席时放行（与 tools/commands 守卫缺席语义一致）。
+ * authority 服务缺席时：public 放行、restricted 503（fail-closed，不在权限服务缺位时裸奔）。
  */
 export function createRouteGate(ctx, identify) {
-    // 公共读基线：authority 缺席时，门槛 <= 此值的路由仍放行（聊天面板可用即可），
-    // 高于此值的（管理读/变更）一律拒绝——fail-closed，不在权限服务缺位时裸奔。
-    const PUBLIC_BASELINE = 1;
-    return (capability, declared) => (req, res, next) => {
-        const ownerLevel = ctx.config.get('ownerAuthority') ?? 5;
-        const declaredAuthority = declared === 'owner' ? ownerLevel : declared;
+    return (capability, visibility) => (req, res, next) => {
         const authority = ctx.getService('authority');
         if (!authority) {
-            // authority 缺席（未配置/启动失败/bounce 窗口期）→ 无法裁决等级。
-            // 公共读放行，其余 503（区别于 403：服务暂不可用，非权限不足）。
-            if (declaredAuthority > PUBLIC_BASELINE) {
-                res.status(503).json({ error: '权限服务不可用，敏感操作暂时被拒绝' });
+            // authority 缺席（未配置/启动失败/bounce 窗口期）→ 无法裁决。
+            // 公共读放行，受限操作 503（区别于 403：服务暂不可用，非权限不足）。
+            if (visibility === 'restricted') {
+                res.status(503).json({ error: '权限服务不可用，受限操作暂时被拒绝' });
                 return;
             }
             next();
             return;
         }
         const caller = identify(req) ?? { platform: 'webui', userId: 'console' };
-        const denied = authority.authorize(caller, { capabilities: [capability], declaredAuthority });
+        const denied = authority.authorize(caller, { capability, visibility });
         if (denied) {
             res.status(403).json({ error: denied });
             return;

package/dist/gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,QAAoB;IAChE,gDAAgD;IAChD,8CAA8C;IAC9C,MAAM,eAAe,GAAG,CAAC,CAAC;IAC1B,OAAO,CAAC,UAAkB,EAAE,QAA0B,EAAkB,EAAE,CACxE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACjB,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,iBAAiB,GAAG,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;QACvE,MAAM,SAAS,GAAG,GAAG,CAAC,UAAU,CAAmB,WAAW,CAAC,CAAC;QAChE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,6CAA6C;YAC7C,sCAAsC;YACtC,IAAI,iBAAiB,GAAG,eAAe,EAAE,CAAC;gBACxC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC;gBACrD,OAAO;YACT,CAAC;YACD,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACzE,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,YAAY,EAAE,CAAC,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC,CAAC;QAC9F,IAAI,MAAM,EAAE,CAAC;YACX,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;YACxC,OAAO;QACT,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,QAAoB;IAChE,OAAO,CAAC,UAAkB,EAAE,UAAgC,EAAkB,EAAE,CAC9E,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACjB,MAAM,SAAS,GAAG,GAAG,CAAC,UAAU,CAAmB,WAAW,CAAC,CAAC;QAChE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,2CAA2C;YAC3C,wCAAwC;YACxC,IAAI,UAAU,KAAK,YAAY,EAAE,CAAC;gBAChC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC;gBACrD,OAAO;YACT,CAAC;YACD,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACzE,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;QACvE,IAAI,MAAM,EAAE,CAAC;YACX,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;YACxC,OAAO;QACT,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACN,CAAC"}

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export declare const defaultConfig: {
     fixedToken: string;
     relationGraphDefaultSpacing: number;
     marketplaceRegistry: string;
+    client: string;
 };
 export { type WSIncoming, WSIncomingSchema } from './protocol.js';
 export declare function apply(ctx: Context, config: Record<string, unknown>): Promise<void>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAc,YAAY,EAAE,OAAO,EAAkC,MAAM,aAAa,CAAC;AAqCrG,eAAO,MAAM,IAAI,+BAA+B,CAAC;AACjD,eAAO,MAAM,WAAW,6BAAc,CAAC;AACvC,eAAO,MAAM,SAAS,aAAa,CAAC;AACpC,eAAO,MAAM,QAAQ,UAAmB,CAAC;AACzC,eAAO,MAAM,MAAM;;CAMlB,CAAC;AAWF,eAAO,MAAM,YAAY,EAAE,YAgD1B,CAAC;AAEF,eAAO,MAAM,aAAa;;;;;;;;;CASzB,CAAC;AAoBF,OAAO,EAAE,KAAK,UAAU,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAqIlE,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAg0CxF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAc,YAAY,EAAE,OAAO,EAAkC,MAAM,aAAa,CAAC;AAqCrG,eAAO,MAAM,IAAI,+BAA+B,CAAC;AACjD,eAAO,MAAM,WAAW,6BAAc,CAAC;AACvC,eAAO,MAAM,SAAS,aAAa,CAAC;AACpC,eAAO,MAAM,QAAQ,UAAmB,CAAC;AACzC,eAAO,MAAM,MAAM;;CAMlB,CAAC;AAWF,eAAO,MAAM,YAAY,EAAE,YAuD1B,CAAC;AAEF,eAAO,MAAM,aAAa;;;;;;;;;;CAUzB,CAAC;AAsBF,OAAO,EAAE,KAAK,UAAU,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAqIlE,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAq3CxF"}

package/dist/index.js

@@ -1,11 +1,12 @@
 // node:fs/node:path 仅用于发现前端 dist 静态目录（位于工作区外部），
 // 已在 biome.json noRestrictedImports 中作为基础设施例外列出。
 import { Buffer } from 'node:buffer';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { LogHub, parseLogLine } from '@aalis/core';
 import { aggregatePlatformDetails, getPlatformAdapters, getPlatformNames, } from '@aalis/plugin-platform-api';
 import { createProcessGateway } from '@aalis/plugin-process-api';
@@ -85,6 +86,12 @@ export const configSchema = {
         default: 'https://registry.npmjs.org',
         description: '插件市场检索用的 npm registry 基址。注意 npm 的 search API 并非所有镜像都支持（淘宝等国内源不支持），默认官方源；国内可填支持 search 的镜像或代理。安装走 package-manager（遵循本机 npm 配置）。',
     },
+    client: {
+        type: 'string',
+        label: '活跃前端（多前端时选用）',
+        default: '',
+        description: '装了多个前端（aalis.client 包）时指定哪个为活跃前端，填包名（如 @aalis/plugin-webui-client）。留空 = 自动选第一个发现到的（默认前端优先）。插件主动 provide(webui-client) 仍优先于此。',
+    },
 };
 export const defaultConfig = {
     port: 3000,
@@ -95,6 +102,7 @@ export const defaultConfig = {
     fixedToken: '',
     relationGraphDefaultSpacing: 120,
     marketplaceRegistry: 'https://registry.npmjs.org',
+    client: '',
 };
 // ===== WebSocket 消息协议 =====
 // 入站消息类型 + 校验 schema 见 ./protocol.ts（zod 强校验）
@@ -143,6 +151,7 @@ export async function apply(ctx, config) {
             return Number.isFinite(v) && v > 0 ? v : 120;
         })(),
         marketplaceRegistry: config.marketplaceRegistry?.trim() || 'https://registry.npmjs.org',
+        client: config.client?.trim() ?? '',
     };
     // 创建 storage gateway；所有文件读写（token、access、文件管理）都走这里
     const storage = createStorageGateway(ctx);
@@ -219,7 +228,6 @@ export async function apply(ctx, config) {
         const authority = ctx.getService('authority');
         res.json({
             identity,
-            authority: authority?.getAuthority(identity.platform, identity.userId) ?? null,
             isOwner: authority?.isOwner(identity.platform, identity.userId) ?? false,
         });
     });
@@ -266,6 +274,22 @@ export async function apply(ctx, config) {
             ctx.logger.warn(`前端目录不存在: ${dir}`);
         }
     }
+    // 已发现的前端候选 + 当前活跃 id（供「切换活跃前端」UI 读/写；ready 时填充）。
+    const clientCandidates = [];
+    let activeClientId = '';
+    /** 切换活跃前端：实时重挂静态目录 + 更新 SPA 回退 + 持久化 webui.client，下次启动沿用。 */
+    function activateClient(id) {
+        const c = clientCandidates.find(x => x.id === id);
+        if (!c)
+            return false;
+        clientDist = c.dir;
+        mountStaticDir(c.dir);
+        activeClientId = id;
+        ctx.config.setPluginConfig(name, { ...ctx.config.getPluginConfig(name), client: id });
+        ctx.config.save();
+        ctx.logger.info(`活跃前端切换为: ${c.label} (${id})`);
+        return true;
+    }
     // 动态静态文件中间件（支持运行时切换前端）
     expressApp.use((req, res, next) => {
         if (staticMiddleware) {
@@ -277,7 +301,7 @@ export async function apply(ctx, config) {
     });
     // ---------- REST API ----------
     // 获取系统状态
-    expressApp.get('/api/status', gate('webui:status:read', 1), (_req, res) => {
+    expressApp.get('/api/status', gate('webui:status:read', 'public'), (_req, res) => {
         const persona = ctx.getService('persona');
         // 判断上传能力
         const hasMedia = ctx.hasService('media');
@@ -310,8 +334,7 @@ export async function apply(ctx, config) {
                 .map(c => ({
                 name: c.name,
                 description: c.description,
-                authority: c.authority,
-                safety: c.safety,
+                visibility: c.visibility,
             })),
         });
     });
@@ -320,7 +343,7 @@ export async function apply(ctx, config) {
     registerMarketplaceRoutes(expressApp, ctx, getPluginMgr, gate, uiConfig.marketplaceRegistry);
     // 获取历史日志：从 data/latest.log 读尾部 N 条（lazy load）。
     // 单进程内 LogHub 不再缓存 buffer——历史以文件为单一数据源。
-    expressApp.get('/api/logs', gate('webui:logs:read', 4), async (_req, res) => {
+    expressApp.get('/api/logs', gate('webui:logs:read', 'restricted'), async (_req, res) => {
         try {
             const entries = await readLogFileTail(200);
             res.json(entries);
@@ -330,7 +353,7 @@ export async function apply(ctx, config) {
         }
     });
     // 尾部 N 条（首屏 / 显式刷新）
-    expressApp.get('/api/logs/tail', gate('webui:logs:read', 4), async (req, res) => {
+    expressApp.get('/api/logs/tail', gate('webui:logs:read', 'restricted'), async (req, res) => {
         const limit = Math.min(Math.max(Number(req.query.limit) || 200, 1), 5000);
         try {
             res.json(await readLogFileTail(limit));
@@ -340,7 +363,7 @@ export async function apply(ctx, config) {
         }
     });
     // 历史分页：返回 seq < before 的最近 limit 条（向上滚动加载更早）
-    expressApp.get('/api/logs/range', gate('webui:logs:read', 4), async (req, res) => {
+    expressApp.get('/api/logs/range', gate('webui:logs:read', 'restricted'), async (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)) {
@@ -355,7 +378,7 @@ export async function apply(ctx, config) {
         }
     });
     // 获取服务列表（含提供者信息）
-    expressApp.get('/api/services', gate('webui:services:read', 1), async (_req, res) => {
+    expressApp.get('/api/services', gate('webui:services:read', 'public'), async (_req, res) => {
         const pluginMgr = getPluginMgr();
         const pluginStatus = pluginMgr ? pluginMgr.getStatus() : [];
         const displayNameMap = new Map();
@@ -387,7 +410,7 @@ export async function apply(ctx, config) {
      * 设置服务偏好。body: { contextId: string }
      * 偏好语义：`preferred > priority > 注册顺序`。持久化到 aalis.config.yaml 的 servicePreferences。
      */
-    expressApp.post('/api/services/:name/prefer', gate('webui:services:manage', 'owner'), async (req, res) => {
+    expressApp.post('/api/services/:name/prefer', gate('webui:services:manage', 'restricted'), async (req, res) => {
         const svcName = String(req.params.name);
         const contextId = String(req.body?.contextId ?? '').trim();
         if (!contextId) {
@@ -406,19 +429,35 @@ export async function apply(ctx, config) {
         res.json({ ok: true });
     });
     /** 清除服务偏好 */
-    expressApp.delete('/api/services/:name/prefer', gate('webui:services:manage', 'owner'), async (req, res) => {
+    expressApp.delete('/api/services/:name/prefer', gate('webui:services:manage', 'restricted'), async (req, res) => {
         const svcName = String(req.params.name);
         ctx.unpreferService(svcName);
         ctx.config.removeServicePreference(svcName);
         ctx.config.save();
         res.json({ ok: true });
     });
+    // 前端切换：列出已发现的前端 + 当前活跃（多前端时 UI 展示）。只回 id/label/active，不泄露 fs 路径。
+    expressApp.get('/api/clients', gate('webui:status:read', 'public'), (_req, res) => {
+        res.json({
+            clients: clientCandidates.map(c => ({ id: c.id, label: c.label, active: c.id === activeClientId })),
+            active: activeClientId,
+        });
+    });
+    // 设活跃前端（owner）：实时重挂 + 持久化；前端切完自行 reload 即加载新前端。
+    expressApp.post('/api/clients/active', gate('webui:clients:manage', 'restricted'), (req, res) => {
+        const id = String(req.body?.id ?? '').trim();
+        if (!activateClient(id)) {
+            res.status(404).json({ ok: false, error: `未找到已发现的前端 "${id}"` });
+            return;
+        }
+        res.json({ ok: true, active: id });
+    });
     // 获取所有平台适配器及其连接状态
-    expressApp.get('/api/platforms', gate('webui:status:read', 1), (_req, res) => {
+    expressApp.get('/api/platforms', gate('webui:status:read', 'public'), (_req, res) => {
         res.json({ platforms: aggregatePlatformDetails(ctx) });
     });
     // 获取已注册的工具分组（含元数据 + 各组工具数量 + 贡献插件列表）
-    expressApp.get('/api/tool-groups', gate('webui:status:read', 1), (_req, res) => {
+    expressApp.get('/api/tool-groups', gate('webui:status:read', 'public'), (_req, res) => {
         const groups = ctx.getService('tools')?.getGroups() ?? [];
         const allTools = ctx.getService('tools')?.getAll() ?? [];
         const knownNames = new Set(groups.map(g => g.name));
@@ -447,7 +486,7 @@ export async function apply(ctx, config) {
         res.json({ groups: result });
     });
     // 获取服务分组（manifest 驱动：每个插件自己声明 subsystem，本路由仅聚合）
-    expressApp.get('/api/service-groups', gate('webui:status:read', 1), (_req, res) => {
+    expressApp.get('/api/service-groups', gate('webui:status:read', 'public'), (_req, res) => {
         const pluginMgr = getPluginMgr();
         const pluginStatus = pluginMgr ? pluginMgr.getStatus() : [];
         // 按 plugin.subsystem 归组（未声明 → 'external'）
@@ -487,7 +526,7 @@ export async function apply(ctx, config) {
         res.json({ groups });
     });
     // 获取所有 LLM 模型（枚举所有注册的 per-model entry）
-    expressApp.get('/api/llm-models', gate('webui:llm:read', 4), async (_req, res) => {
+    expressApp.get('/api/llm-models', gate('webui:llm:read', 'restricted'), async (_req, res) => {
         try {
             const entries = ctx.getAllServices('llm');
             const models = entries.map(e => ({
@@ -503,7 +542,7 @@ export async function apply(ctx, config) {
         }
     });
     // LLM providers + per-provider models（供 schema type='llm-ref' 联动 select 使用）
-    expressApp.get('/api/llm-providers', gate('webui:llm:read', 4), async (_req, res) => {
+    expressApp.get('/api/llm-providers', gate('webui:llm:read', 'restricted'), async (_req, res) => {
         try {
             const entries = ctx.getAllServices('llm');
             const byProvider = new Map();
@@ -540,7 +579,7 @@ export async function apply(ctx, config) {
     // 触发指定 provider 重新探测远端模型列表（用于 webui 上的"刷新模型"按钮）
     // 仅对在 LLMModel 上实现了 refresh() 的 provider 生效（远端动态发现型，如 Ollama / OpenAI）。
     // 同 provider 下所有 model entries 共享同一份 refresh 闭包，调任一个 entry 即可。
-    expressApp.post('/api/llm-providers/:contextId/refresh', gate('webui:llm:manage', 'owner'), async (req, res) => {
+    expressApp.post('/api/llm-providers/:contextId/refresh', gate('webui:llm:manage', 'restricted'), async (req, res) => {
         const contextId = req.params.contextId;
         if (!contextId) {
             res.status(400).json({ error: 'contextId is required' });
@@ -563,7 +602,7 @@ export async function apply(ctx, config) {
         }
     });
     // 获取某个服务的可用模型/选项列表
-    expressApp.get('/api/models/:service', gate('webui:models:read', 1), async (req, res) => {
+    expressApp.get('/api/models/:service', gate('webui:models:read', 'public'), async (req, res) => {
         const serviceName = req.params.service;
         // 特殊处理 platform：通过 helper 获取已注册的平台名称
         if (serviceName === 'platform') {
@@ -687,13 +726,13 @@ export async function apply(ctx, config) {
             res.json({ models: [] });
         }
     });
-    // ---------- 高危操作交互式确认（内联对话式） ----------
+    // ---------- 受限操作交互式确认（内联对话式；restricted 能力的临时委托） ----------
     const CONFIRM_TIMEOUT = 60_000; // 60 秒超时
     const pendingSessionConfirms = new Map();
     ctx.getService('authority')?.setConfirmHandler('webui', async (request) => {
         const typeLabel = request.type === 'command' ? '指令' : '工具';
         const nameStr = request.type === 'command' ? `/${request.name}` : request.name;
-        const prompt = `⚠️ ${typeLabel} ${nameStr} 是高危操作。回复 Y 仅允许本次；回复 YS 允许本会话 10 分钟；其他任意输入取消。`;
+        const prompt = `⚠️ ${typeLabel} ${nameStr} 是受限操作。回复 Y 仅允许本次；回复 YS 允许本会话 10 分钟；其他任意输入取消。`;
         // 以确认消息形式发送（不影响客户端 loading/streaming 状态）
         const payload = {
             type: 'confirm',
@@ -726,7 +765,7 @@ export async function apply(ctx, config) {
                 // 超时后向会话发送提示
                 const timeoutPayload = {
                     type: 'confirm',
-                    content: '⏰ 高危操作确认已超时，已自动取消。',
+                    content: '⏰ 受限操作确认已超时，已自动取消。',
                     sessionId: request.sessionId,
                 };
                 const timeoutJson = JSON.stringify(timeoutPayload);
@@ -836,7 +875,7 @@ export async function apply(ctx, config) {
                     sessions.set(sessionId, new Set());
                 }
                 sessions.get(sessionId).add(ws);
-                // 检查是否有待确认的高危操作（拦截用户输入作为确认/取消）
+                // 检查是否有待确认的受限操作（拦截用户输入作为确认/取消）
                 const pending = pendingSessionConfirms.get(sessionId);
                 if (pending) {
                     clearTimeout(pending.timer);
@@ -1182,39 +1221,68 @@ export async function apply(ctx, config) {
     });
     // 启动服务器
     ctx.on('ready', () => {
-        // 自动发现同级 webui-client 包并注册为 webui-client 服务提供者
+        // 自动发现 webui-client 包并注册为 webui-client 服务提供者。
+        // 解析以「项目根 package.json」为基准（与 runtime 的 node-modules 加载器同源），
+        // 这样 npm 扁平 / pnpm 隔离 / monorepo 软链三种 node_modules 拓扑都自洽——
+        // client 是项目顶层依赖（create-aalis 选 WebUI 时自动带），从项目根能 resolve 到。
+        // 回退：webui-server 同级目录（cwd≠项目根等边角场景兜底）。
         const __dirname = dirname(fileURLToPath(import.meta.url));
-        const clientCandidates = [
-            {
-                id: '@aalis/plugin-webui-client',
-                label: 'Aalis 默认前端',
-                dir: resolve(__dirname, '../../plugin-webui-client/dist'),
-            },
-            {
-                id: '@aalis/plugin-webui-client-napcat',
-                label: 'NapCat 前端',
-                dir: resolve(__dirname, '../../plugin-webui-client-napcat/dist'),
-            },
-        ];
-        // 如果已有外部插件注册了 webui-client 服务，则跳过自动发现
+        const projectRequire = createRequire(pathToFileURL(resolve(process.cwd(), 'package.json')));
+        const resolveClientDir = (id) => {
+            try {
+                return resolve(dirname(projectRequire.resolve(`${id}/package.json`)), 'dist');
+            }
+            catch {
+                const sibling = resolve(__dirname, `../../${id.replace('@aalis/', '')}/dist`);
+                return existsSync(sibling) ? sibling : undefined;
+            }
+        };
+        const addCandidate = (id, label, dir) => {
+            if (!dir || clientCandidates.some(c => c.id === id))
+                return;
+            if (existsSync(dir) && existsSync(resolve(dir, 'index.html')))
+                clientCandidates.push({ id, label, dir });
+        };
+        // ① 已知 @aalis 前端（保证 monorepo/默认拓扑可用——根 deps 未必列 client）
+        addCandidate('@aalis/plugin-webui-client', 'Aalis 默认前端', resolveClientDir('@aalis/plugin-webui-client'));
+        addCandidate('@aalis/plugin-webui-client-napcat', 'NapCat 前端', resolveClientDir('@aalis/plugin-webui-client-napcat'));
+        // ② 追加发现：项目 deps 里任何带 aalis.client marker 的第三方前端（忒修斯之船可换）
+        try {
+            const rootPkg = JSON.parse(readFileSync(resolve(process.cwd(), 'package.json'), 'utf-8'));
+            const deps = Object.keys({ ...rootPkg.dependencies, ...rootPkg.optionalDependencies });
+            for (const dep of deps) {
+                if (clientCandidates.some(c => c.id === dep))
+                    continue;
+                try {
+                    const pkgPath = projectRequire.resolve(`${dep}/package.json`);
+                    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                    if (pkg?.aalis?.client !== true)
+                        continue;
+                    addCandidate(dep, pkg.displayName ?? pkg.description ?? dep, resolve(dirname(pkgPath), 'dist'));
+                }
+                catch {
+                    /* 该 dep 无法解析/读取，跳过 */
+                }
+            }
+        }
+        catch {
+            /* 无项目根 package.json（如 monorepo 直跑），跳过 dep 扫描 */
+        }
+        // 如果已有外部插件主动注册了 webui-client 服务（apply 覆盖路径），则跳过自动发现
         const hasExternalClient = ctx.hasService('webui-client');
-        if (!hasExternalClient) {
-            let isFirst = true;
+        if (!hasExternalClient && clientCandidates.length > 0) {
+            // 活跃前端：config.client 指定者优先，否则取第一个（默认前端排在最前）
+            const preferred = uiConfig.client && clientCandidates.find(c => c.id === uiConfig.client);
+            const active = preferred || clientCandidates[0];
             for (const candidate of clientCandidates) {
-                if (existsSync(candidate.dir) && existsSync(resolve(candidate.dir, 'index.html'))) {
-                    const childCtx = ctx.fork(candidate.id);
-                    childCtx.provide('webui-client', {
-                        getClientDir: () => candidate.dir,
-                    }, { label: candidate.label });
-                    ctx.logger.info(`发现前端: ${candidate.label} (${candidate.dir})`);
-                    if (isFirst) {
-                        clientDist = candidate.dir;
-                        mountStaticDir(candidate.dir);
-                        ctx.logger.info(`活跃前端: ${candidate.label}`);
-                        isFirst = false;
-                    }
-                }
+                const childCtx = ctx.fork(candidate.id);
+                childCtx.provide('webui-client', { getClientDir: () => candidate.dir }, { label: candidate.label });
+                ctx.logger.info(`发现前端: ${candidate.label} (${candidate.dir})`);
             }
+            clientDist = active.dir;
+            mountStaticDir(active.dir);
+            activeClientId = active.id;
+            ctx.logger.info(`活跃前端: ${active.label}${preferred ? '（config.client 指定）' : ''}`);
         }
         // 若已有外部 webui-client 服务，使用其提供的目录
         if (hasExternalClient) {