@koishi-ce/client 1.0.0

package/client/data.ts

@@ -0,0 +1,178 @@
+/// <reference path="./shims.d.ts" />
+import type { Promisify, Universal } from "@koishi-ce/koishi";
+import type {
+	ClientConfig,
+	Console,
+	DataService,
+	Events,
+} from "@koishi-ce/plugin-console";
+import { markRaw, reactive, ref } from "vue";
+import type { Context } from "./context";
+
+/**
+ * 全局数据仓库的类型：按服务名映射到该 DataService 推送的负载数据。
+ * 服务端每类数据（entry、schema、permissions 等）对应 Store 的一个键。
+ */
+export type Store = {
+	[K in keyof Console.Services]?: Console.Services[K] extends DataService<
+		infer T
+	>
+		? T
+		: never;
+};
+
+// 由构建期注入的客户端配置（见 @koishi-ce/plugin-console 的 define 替换）
+declare const KOISHI_CONFIG: ClientConfig;
+/** 服务端下发的客户端配置（uiPath、heartbeat、proxyBase 等），只读 */
+export const global = KOISHI_CONFIG;
+/** 全局响应式数据仓库：服务端通过 data/patch 事件驱动其更新 */
+export const store = reactive<Store>({});
+
+/**
+ * 为资源 URL 拼上代理前缀。
+ * 控制台在反向代理后部署时，静态资源需经由 proxyBase 转发。
+ */
+export function withProxy(url: string) {
+	return (global.proxyBase || "") + url;
+}
+
+/** 当前与服务端的 WebSocket 连接（未连接时为 null） */
+export const socket = ref<Universal.WebSocket | null>(null);
+/** 按事件名登记的推送监听器（receive 注册） */
+const listeners: Record<string, (data: unknown) => void> = {};
+/** 按报文 id 暂存的 RPC 应答钩子 [resolve, reject]（send 写入） */
+const responseHooks: Record<
+	string,
+	[(value: unknown) => void, (reason?: unknown) => void]
+> = {};
+
+/**
+ * 向服务端发起一次 RPC 调用。
+ *
+ * 通过 WebSocket 发送 `{ id, type, args }` 报文，并以随机 id 关联
+ * 异步应答（见下方 "response" 监听）；超时 60s 后 reject。
+ * @param type 事件名（对应服务端 Events 接口的方法名）
+ * @param args 调用参数
+ */
+export function send<T extends keyof Events>(
+	type: T,
+	...args: Parameters<Events[T]>
+): Promisify<ReturnType<Events[T]>>;
+export function send(type: string, ...args: unknown[]) {
+	if (!socket.value) return;
+	console.debug("↑%c", "color:brown", type, args);
+	const id = Math.random().toString(36).slice(2, 9);
+	socket.value.send(JSON.stringify({ id, type, args }));
+	return new Promise((resolve, reject) => {
+		responseHooks[id] = [resolve, reject];
+		setTimeout(() => {
+			delete responseHooks[id];
+			reject(new Error("timeout"));
+		}, 60000);
+	});
+}
+
+/**
+ * 注册服务端主动推送事件的监听器（每类事件仅保留最后一个监听）。
+ * @param event 事件名，如 "data" / "patch" / "response" / "entry-data"
+ */
+export function receive<T = unknown>(
+	event: string,
+	listener: (data: T) => void,
+) {
+	// 注册表按 unknown 分发实际报文，监听器的载荷类型由调用方以泛型参数自行声明
+	listeners[event] = listener as (data: unknown) => void;
+}
+
+/** Store 各键负载数据的联合（服务端推送的合法取值集合） */
+type StoreValue = Store[keyof Store];
+
+// 服务端整表推送：直接覆盖 store 中对应键
+// （key 为联合类型时直写 store[key] 会被要求交叉类型，故经 Record 视图写入）
+receive<{ key: keyof Store; value: unknown }>("data", ({ key, value }) => {
+	(store as Record<keyof Store, StoreValue>)[key] = value as StoreValue;
+});
+
+// 服务端增量推送：数组做追加，对象做浅合并
+receive<{ key: keyof Store; value: unknown }>("patch", ({ key, value }) => {
+	const current = store[key];
+	if (Array.isArray(current)) {
+		(current as unknown[]).push(...(value as unknown[]));
+	} else if (current) {
+		Object.assign(current, value);
+	}
+});
+
+// RPC 应答分发：按报文 id 找到 send() 留下的 resolve/reject 并结算
+receive<{ id: string; value?: unknown; error?: unknown }>(
+	"response",
+	({ id, value, error }) => {
+		const hooks = responseHooks[id];
+		if (!hooks) return;
+		delete responseHooks[id];
+		const [resolve, reject] = hooks;
+		if (error) {
+			reject(error);
+		} else {
+			resolve(value);
+		}
+	},
+);
+
+/**
+ * 建立 WebSocket 连接并维护其生命周期。
+ *
+ * - 开启心跳：按配置间隔发送 ping，超时未收到消息则主动断开；
+ * - 断线重连：清空 store 后 1s 重试，重连成功则刷新页面以恢复完整状态。
+ * @param ctx 根 Context，用于把消息转发为 cordis 事件
+ * @param callback 创建 WebSocket 实例的工厂函数
+ */
+export function connect(ctx: Context, callback: () => Universal.WebSocket) {
+	const value = callback();
+
+	let sendTimer: number;
+	let closeTimer: number;
+	// 每收到一条消息就重置两个计时器：interval 到点发 ping，
+	// timeout 到点仍无消息则强制断线（触发 reconnect）
+	const refresh = () => {
+		if (!global.heartbeat) return;
+		clearTimeout(sendTimer);
+		clearTimeout(closeTimer);
+		sendTimer = +setTimeout(() => send("ping"), global.heartbeat.interval);
+		closeTimer = +setTimeout(() => value?.close(), global.heartbeat.timeout);
+	};
+
+	const reconnect = () => {
+		socket.value = null;
+		// 清空本地数据仓库：断线期间的数据已不可信，等待重连后重新拉取
+		for (const key in store) {
+			(store as Record<string, unknown>)[key] = undefined;
+		}
+		console.log("[koishi] websocket disconnected, will retry in 1s...");
+		setTimeout(() => {
+			connect(ctx, callback).then(location.reload, () => {
+				console.log("[koishi] websocket disconnected, will retry in 1s...");
+			});
+		}, 1000);
+	};
+
+	value.addEventListener("message", (ev) => {
+		refresh();
+		const data = JSON.parse(ev.data);
+		console.debug("↓%c", "color:purple", data.type, data.body);
+		if (data.type in listeners) {
+			listeners[data.type]?.(data.body);
+		}
+		ctx.emit(data.type, data.body);
+	});
+
+	value.addEventListener("close", reconnect);
+
+	return new Promise<Universal.WebSocket.Event>((resolve, reject) => {
+		value.addEventListener("open", (event) => {
+			socket.value = markRaw(value);
+			resolve(event);
+		});
+		value.addEventListener("error", reject);
+	});
+}

package/client/index.ts

@@ -0,0 +1,76 @@
+/**
+ * @koishi_ce/client 包的主入口（Koishi 控制台前端组件库）。
+ *
+ * 职责：
+ * - 创建根 Context（`root`），安装内置组件库并启动六个核心服务
+ *   （action / i18n / loader / router / setting / theme）；
+ * - 通过 `export *` 汇总对外暴露组件、数据层与各服务插件的公共 API，
+ *   供宿主 app 与各控制台插件统一从 `@koishi-ce/client` 导入；
+ * - 声明可被其它插件以 `declare module` 合并增强的 `ActionContext`、
+ *   `Config` 接口。
+ */
+import install from "./components";
+import { Context } from "./context";
+
+declare module "@koishi-ce/plugin-console" {
+	export interface ClientConfig {
+		/** 服务端声明不支持的功能列表（版本不兼容时用于前端降级提示） */
+		unsupported?: string[];
+	}
+}
+
+// Satori 协议类型的两个命名空间别名：旧代码多用 Universal，新代码建议用 Satori
+export * as Satori from "@satorijs/protocol";
+export * as Universal from "@satorijs/protocol";
+// cordis 以 ambient const enum 声明 ScopeStatus,verbatimModuleSyntax 下
+// 禁止对其实施运行时访问/再导出(TS2748);这里按等价值展开为 const 对象,
+// 与 cordis(@cordisjs/core)运行时导出的枚举数值保持一致
+export const ScopeStatus = {
+	PENDING: 0,
+	LOADING: 1,
+	ACTIVE: 2,
+	FAILED: 3,
+	DISPOSED: 4,
+} as const;
+
+export type ScopeStatus = (typeof ScopeStatus)[keyof typeof ScopeStatus];
+export * from "./components";
+export * from "./context";
+export * from "./data";
+export * from "./plugins/action";
+export * from "./plugins/i18n";
+export * from "./plugins/loader";
+export * from "./plugins/router";
+export * from "./plugins/setting";
+export * from "./plugins/theme";
+export { Service } from "./utils";
+
+/** 组件库安装函数（在 Vue app 上注册全部内置组件） */
+export default install;
+
+// 各插件通过 `declare module "@koishi-ce/client"` 对该接口做合并增强,
+// 因此必须是 interface 而非类型别名(同 context.ts 的 Internal)
+// biome-ignore lint/suspicious/noEmptyInterface: 需要保持 interface 以支持声明合并
+export interface ActionContext {}
+
+/** 客户端本地配置（持久化于 localStorage，读写见 plugins/setting.ts） */
+export interface Config {
+	/** 界面语言，如 "zh-CN" / "en-US" */
+	locale?: string;
+}
+
+/** 根 Context：整个控制台前端共享的唯一上下文实例 */
+export const root = new Context();
+
+// 在根 Vue 应用上安装内置组件库（组件注册 + schema 扩展注册）
+root.app.use(install);
+
+// activity 事件的兜底监听：正常传入的 activity 实例恒为真值，
+// 故默认不禁用任何页面；插件可另行监听 "activity" 事件按需隐藏页面
+root.on("activity", (data) => !data);
+
+/** @deprecated 已废弃，请改用 `useRouter()` */
+export const router = root.$router.router;
+
+/** @deprecated 已废弃，请改用 `useRouter()` */
+export const activities = root.$router.pages;

package/client/plugins/action.ts

@@ -0,0 +1,251 @@
+/**
+ * 动作（action）与菜单服务：控制台的快捷键、右键菜单、
+ * 作用域变量的统一管理。
+ *
+ * 插件通过 `ctx.action()` 注册动作、`ctx.menu()` 注册菜单条目、
+ * `ctx.define()` 暴露作用域变量；组件通过 `useMenu()` 在元素上
+ * 绑定右键菜单。作用域变量支持 "a.b" 点分键，经 Flatten 类型
+ * 与运行时代理呈现为嵌套对象。
+ */
+import { type Dict, type Intersect, remove } from "cosmokit";
+import {
+	type MaybeRefOrGetter,
+	markRaw,
+	reactive,
+	shallowReactive,
+	toValue,
+} from "vue";
+import type { ActionContext } from "..";
+import { type Context, useContext } from "../context";
+import { insert, Service } from "../utils";
+
+declare module "../context" {
+	interface Context {
+		$action: ActionService;
+		action(id: string, options: ActionOptions): () => void;
+		menu(id: string, items: MenuItem[]): () => void;
+		define<K extends keyof ActionContext>(
+			key: K,
+			value: MaybeRefOrGetter<ActionContext[K]>,
+		): () => void;
+	}
+
+	interface Internal {
+		scope: Store<ActionContext>;
+		menus: Dict<MenuItem[]>;
+		actions: Dict<ActionOptions>;
+		activeMenus: ActiveMenu[];
+	}
+}
+
+/**
+ * 动作（action）注册选项。
+ * 动作是可被快捷键或菜单触发的操作，其执行时可读取当前上下文作用域。
+ */
+export interface ActionOptions {
+	/** 触发快捷键，如 "Control+S"（macOS 上 ctrl 自动映射为 meta） */
+	shortcut?: string;
+	/** 返回 true 时在菜单中隐藏该动作 */
+	hidden?: (scope: Flatten<ActionContext>) => boolean;
+	/** 返回 true 时禁用该动作（快捷键与菜单均不触发） */
+	disabled?: (scope: Flatten<ActionContext>) => boolean;
+	/** 动作本体，传入当前作用域执行 */
+	action: (scope: Flatten<ActionContext>) => unknown;
+}
+
+/** 旧版菜单项写法（字段与 ActionOptions 部分重叠），仅为兼容保留 */
+export type LegacyMenuItem = Partial<ActionOptions> & Omit<MenuItem, "id">;
+
+/** 菜单项：label / type / icon 均支持写成随作用域变化的 getter */
+export interface MenuItem {
+	id: string;
+	label?: MaybeGetter<string>;
+	type?: MaybeGetter<string>;
+	icon?: MaybeGetter<string>;
+	order?: number;
+}
+
+/** 值或（以作用域为参数的）取值函数 */
+export type MaybeGetter<T> = T | ((scope: Flatten<ActionContext>) => T);
+
+/** 作用域存储：扁平键到「值或 ref 或 getter」的映射 */
+type Store<S extends {}> = { [K in keyof S]?: MaybeRefOrGetter<S[K]> };
+
+/**
+ * 把 "a.b.c" 形式的扁平键名归并为 { a: { b: { c } } } 的嵌套结构，
+ * 供动作/菜单以对象路径的方式消费作用域。
+ */
+type Flatten<S extends {}> = Intersect<
+	{
+		[K in keyof S]: K extends `${infer L}.${infer R}`
+			? { [P in L]: Flatten<{ [P in R]: S[K] }> }
+			: { [P in K]: S[K] };
+	}[keyof S]
+>;
+
+/** 当前激活的右键菜单：id 加上弹出位置（四边坐标） */
+export interface ActiveMenu {
+	id: string;
+	relative: {
+		left: number;
+		top: number;
+		right: number;
+		bottom: number;
+	};
+}
+
+/**
+ * 创建右键菜单触发器：返回值直接绑到元素的 contextmenu 事件上。
+ * 触发时把附加值写入作用域，并在鼠标位置弹出自定义菜单（由 global 插槽渲染）。
+ * @param id 菜单标识，menu() 注册的条目将展示在该菜单中
+ */
+export function useMenu<K extends keyof ActionContext>(id: K) {
+	const ctx = useContext();
+	return (event: MouseEvent, value: MaybeRefOrGetter<ActionContext[K]>) => {
+		ctx.define(id, value);
+		event.preventDefault();
+		const { clientX, clientY } = event;
+		ctx.internal.activeMenus.splice(0, Infinity, {
+			id,
+			relative: {
+				left: clientX,
+				top: clientY,
+				right: clientX,
+				bottom: clientY,
+			},
+		});
+	};
+}
+
+/**
+ * 动作服务：管理全局快捷键、菜单与作用域变量。
+ *
+ * - `ctx.action()` 注册动作（可含快捷键，由全局 keydown 统一分发）；
+ * - `ctx.menu()` 向具名菜单追加条目；
+ * - `ctx.define()` 声明作用域变量，供动作/菜单项在执行时读取。
+ */
+export default class ActionService extends Service {
+	constructor(ctx: Context) {
+		super(ctx, "$action", true);
+		ctx.mixin("$action", ["action", "menu", "define"]);
+
+		ctx.internal.scope = shallowReactive({} as Store<ActionContext>);
+		ctx.internal.menus = reactive({});
+		ctx.internal.actions = reactive({});
+		ctx.internal.activeMenus = reactive([]);
+
+		// 全局快捷键：解析每个动作的 shortcut 描述串，
+		// 与键盘事件逐项比对（ctrl 在 macOS 平台映射为 meta 键）
+		ctx.addEventListener("keydown", (event) => {
+			const scope = this.createScope();
+			for (const action of Object.values(ctx.internal.actions)) {
+				if (!action.shortcut) continue;
+				const keys = action.shortcut
+					.split("+")
+					.map((key) => key.toLowerCase().trim());
+				let ctrlKey = false,
+					shiftKey = false,
+					metaKey = false,
+					code: string | undefined;
+				for (const key of keys) {
+					switch (key) {
+						case "shift":
+							shiftKey = true;
+							continue;
+						case "ctrl":
+							// macOS 没有 ctrl+字母 的快捷键惯例，改用 Cmd（meta）
+							if (navigator.platform.toLowerCase().includes("mac")) {
+								metaKey = true;
+							} else {
+								ctrlKey = true;
+							}
+							continue;
+						default:
+							code = key;
+					}
+				}
+				if (ctrlKey !== event.ctrlKey) continue;
+				if (shiftKey !== event.shiftKey) continue;
+				if (metaKey !== event.metaKey) continue;
+				if (code !== event.key.toLowerCase()) continue;
+				if (action.disabled?.(scope)) continue;
+				event.preventDefault();
+				action.action(scope);
+			}
+		});
+	}
+
+	/** 注册动作；返回取消注册函数 */
+	action(id: string, options: ActionOptions) {
+		markRaw(options);
+		return this.ctx.effect(() => {
+			this.ctx.internal.actions[id] = options;
+			return () => delete this.ctx.internal.actions[id];
+		});
+	}
+
+	/** 向具名菜单追加条目（按 order 插入有序列表）；返回取消注册函数 */
+	menu(id: string, items: MenuItem[]) {
+		return this.ctx.effect(() => {
+			const list = (this.ctx.internal.menus[id] ||= []);
+			items.forEach((item) => insert(list, item));
+			return () => {
+				items.forEach((item) => remove(list, item));
+				if (!list.length) delete this.ctx.internal.menus[id];
+			};
+		});
+	}
+
+	/** 声明一个作用域变量（组件卸载/插件停止时自动移除）；返回取消函数 */
+	define<K extends keyof ActionContext>(
+		key: K,
+		value: MaybeRefOrGetter<ActionContext[K]>,
+	) {
+		return this.ctx.effect(() => {
+			// 泛型键直写映射属性会被要求交叉类型，经字符串索引视图写入；
+			// 载荷以 unknown 收纳，具体类型由 ActionContext 的声明合并保证
+			const scope = this.ctx.internal.scope as Record<
+				string,
+				MaybeRefOrGetter<unknown>
+			>;
+			scope[key as string] = value;
+			return () => delete this.ctx.internal.scope[key];
+		});
+	}
+
+	/**
+	 * 基于当前已注册的作用域变量构造快照对象（嵌套代理形式），
+	 * 可用 override 临时覆盖若干键值。
+	 */
+	createScope(override = {}) {
+		const scope = { ...this.ctx.internal.scope, ...override };
+		return createScope(scope);
+	}
+}
+
+/**
+ * 把扁平键存储包装成嵌套对象的代理：
+ * 读取 "a" 时若存在 "a.b" 等子键，则递归返回子级作用域代理；
+ * 命中普通键则经 toValue 解析 ref/getter 后返回实际值。
+ */
+function createScope(
+	scope: Store<ActionContext>,
+	prefix = "",
+): Flatten<ActionContext> {
+	return new Proxy({} as Record<string, unknown>, {
+		get: (target, key) => {
+			if (typeof key === "symbol")
+				return (target as Record<symbol, unknown>)[key];
+			key = prefix + key;
+			const source = scope as Record<string, MaybeRefOrGetter<unknown>>;
+			if (key in scope) return toValue(source[key]);
+			// 键本身不存在，但存在以其为前缀的子键：返回子级作用域代理
+			const _prefix = `${key}.`;
+			if (Object.keys(scope).some((k) => k.startsWith(_prefix))) {
+				return createScope(scope, `${key}.`);
+			}
+			// 完全未命中：显式返回 undefined（noImplicitReturns）
+			return undefined;
+		},
+	}) as Flatten<ActionContext>;
+}

package/client/plugins/i18n.ts

@@ -0,0 +1,43 @@
+import { watchEffect } from "vue";
+import { createI18n } from "vue-i18n";
+import type { Context } from "../context";
+import { Service } from "../utils";
+import { useConfig } from "./setting";
+
+declare module "../context" {
+	interface Context {
+		$i18n: I18nService;
+	}
+}
+
+// 客户端本地配置（未与服务端同步前的原始值）
+const config = useConfig();
+
+/**
+ * 国际化服务：持有 vue-i18n 实例（默认回退语言 zh-CN），
+ * 并监听本地配置中的 locale 变化实时切换界面语言。
+ * 各扩展自身的语言包由 loader 加载时注入该实例。
+ */
+export default class I18nService extends Service {
+	public i18n = createI18n({
+		legacy: false,
+		fallbackLocale: "zh-CN",
+	});
+
+	constructor(ctx: Context) {
+		super(ctx, "$i18n", true);
+
+		// flush: "post" 确保在语言切换引起重渲染前完成 locale 写入
+		ctx.effect(() =>
+			watchEffect(
+				() => {
+					const locale = config.value.locale;
+					if (locale) {
+						this.i18n.global.locale.value = locale;
+					}
+				},
+				{ flush: "post" },
+			),
+		);
+	}
+}

package/client/plugins/loader.ts

@@ -0,0 +1,154 @@
+import type { EntryData } from "@koishi-ce/plugin-console";
+import type { EffectScope, Plugin } from "cordis";
+import type { Dict } from "cosmokit";
+import { type Ref, ref, shallowReactive, watch } from "vue";
+import type { Context } from "../context";
+import { receive, store } from "../data";
+import { Service } from "../utils";
+
+declare module "../context" {
+	interface Context {
+		$loader: LoaderService;
+		extension?: LoadResult;
+	}
+}
+
+/** 取消函数 */
+export type Disposable = () => void;
+/** 扩展入口函数：以插件形式安装到控制台上下文 */
+export type Extension = (ctx: Context) => void;
+
+/** 标记一个函数为扩展入口（仅类型层面，便于构建工具识别） */
+export function defineExtension(callback: Extension) {
+	return callback;
+}
+
+/** 兼容 rollup 与 vite 两种产物：优先取 default 导出 */
+export function unwrapExports(module: unknown): Plugin {
+	const record = module as { default?: unknown } | null | undefined;
+	return (record?.default || module) as Plugin;
+}
+
+/** 按文件后缀分发的加载器：样式表插入 <link>，其余按动态模块导入 */
+const loaders: Dict<(ctx: Context, url: string) => Promise<void>> = {
+	async [`.css`](ctx, url) {
+		const link = document.createElement("link");
+		link.rel = "stylesheet";
+		link.href = url;
+		// 等待样式真正加载完成后再插入文档，避免无样式闪烁；
+		// link 的挂载/卸载纳入 ctx.effect，随扩展作用域销毁而移除
+		await new Promise((resolve, reject) => {
+			link.onload = resolve;
+			link.onerror = reject;
+			ctx.effect(() => {
+				document.head.appendChild(link);
+				return () => document.head.removeChild(link);
+			});
+		});
+	},
+	async [``](ctx, url) {
+		const exports = await import(/* @vite-ignore */ url);
+		// 扩展入口均为函数式插件；断言到 Function 形状以走 config 可选的重载
+		ctx.plugin(unwrapExports(exports) as Plugin.Function, ctx.extension?.data);
+	},
+};
+
+/** 单个扩展的加载结果：独立作用域 + 数据 ref + 完成标记 */
+export interface LoadResult {
+	scope: EffectScope;
+	paths?: string[] | undefined;
+	done: Ref<boolean>;
+	data: Ref;
+}
+
+/**
+ * 扩展加载服务：根据服务端推送的 entry 数据动态加载各控制台扩展
+ * （样式表与 JS 模块），并为每个扩展创建隔离的作用域。
+ *
+ * 服务端入口集合变化时做增量同步：新增的加载、消失的卸载；
+ * 后端实例 id 变化（服务重启）则整页刷新。
+ */
+export default class LoaderService extends Service {
+	/** 最近一次见到的后端实例 id（用于检测服务端重启） */
+	private backendId: string | undefined;
+
+	/** 当前已加载扩展的 id → LoadResult 映射 */
+	public extensions: Dict<LoadResult> = shallowReactive({} as Dict<LoadResult>);
+
+	constructor(ctx: Context) {
+		super(ctx, "$loader", true);
+
+		// 服务端推送扩展入口的随附数据（entry-data）：
+		// 同步到 store.entry 并刷新已加载扩展的 data ref
+		receive<{ id: string; data: unknown }>("entry-data", ({ id, data }) => {
+			const entry = store.entry?.[id];
+			if (!entry) return;
+			entry.data = data;
+			const extension = this.extensions[id];
+			if (extension) extension.data.value = data;
+		});
+	}
+
+	/**
+	 * 初始加载任务：监听 store.entry（deep），完成首次全量加载时 resolve。
+	 * context.ts 的 ready 阶段会 await 本任务，再挂载 i18n / router。
+	 */
+	initTask = new Promise<void>((resolve) => {
+		watch(
+			() => store.entry,
+			async (newValue, oldValue) => {
+				// _id 标识后端实例：变化说明服务端已重启，页面状态不再可信
+				const { _id, ...rest } = (newValue || {}) as Dict<EntryData> & {
+					_id?: string | undefined;
+				};
+				if (this.backendId && _id && this.backendId !== _id) {
+					window.location.reload();
+					return;
+				}
+				this.backendId = _id;
+
+				// 增量卸载：入口列表中已消失的扩展，销毁其作用域
+				for (const key in this.extensions) {
+					if (rest[key]) continue;
+					this.extensions[key]?.scope.dispose();
+					delete this.extensions[key];
+				}
+
+				await Promise.all(
+					Object.entries(rest).map(([key, { files, paths, data }]) => {
+						if (this.extensions[key]) return;
+						// 每个扩展在隔离的 "extension" 作用域中运行，
+						// 并通过 ctx.extension 拿到自己的加载结果
+						const scope = this.ctx.isolate("extension").plugin(() => {});
+						scope.ctx.extension = this.extensions[key] = {
+							done: ref(false),
+							scope,
+							paths,
+							data: ref(data),
+						};
+						// 依次加载入口声明的全部文件，按后缀分发给对应 loader
+						const task = Promise.all(
+							files.map((url) => {
+								for (const ext in loaders) {
+									if (!url.endsWith(ext)) continue;
+									return loaders[ext]?.(scope.ctx, url);
+								}
+								// 无匹配后缀的入口文件：显式跳过（noImplicitReturns）
+								return undefined;
+							}),
+						);
+						// 加载完成即标记 done（扩展加载失败不阻塞界面可用性）
+						void task.finally(() => {
+							const extension = this.extensions[key];
+							if (extension) extension.done.value = true;
+						});
+					}),
+				);
+
+				// 首次加载完成（oldValue 为空）时放行 initTask
+				if (!oldValue) resolve();
+			},
+			{ deep: true },
+		);
+	});
+}