@koishi-ce/client 1.0.0

package/client/plugins/router.ts

@@ -0,0 +1,278 @@
+/**
+ * 路由服务：控制台页面（activity）与插槽视图的注册中心。
+ *
+ * 封装 vue-router，处理三件事：
+ * 1. `ctx.page()` 注册页面——挂路由、进侧栏、管理标题与缓存路径；
+ * 2. `ctx.slot()` 向具名插槽（layout / status / global 等）注入视图；
+ * 3. 导航守卫——首次导航等待扩展加载，未匹配路径暂存待页面注册后跳转。
+ */
+import type { Disposable } from "cordis";
+import { type Dict, omit, remove } from "cosmokit";
+import {
+	type Component,
+	type MaybeRefOrGetter,
+	reactive,
+	ref,
+	toValue,
+} from "vue";
+import { createRouter, createWebHistory, START_LOCATION } from "vue-router";
+import type { SlotOptions } from "../components";
+import Overlay from "../components/chat/overlay.vue";
+import type { Context } from "../context";
+import { global, type Store, store } from "../data";
+import { insert, Service } from "../utils";
+
+declare module "vue-router" {
+	interface RouteMeta {
+		activity?: Activity;
+	}
+}
+
+declare module "../context" {
+	interface Context {
+		$router: RouterService;
+		slot(options: SlotOptions): () => void;
+		page(options: Activity.Options): () => void;
+	}
+
+	interface Events {
+		activity(activity: Activity): boolean;
+	}
+}
+
+/** activity（控制台页面）的注册选项 */
+export namespace Activity {
+	export interface Options {
+		id?: string;
+		/** 路由路径，支持 vue-router 动态段（如 "/foo/:id"） */
+		path: string;
+		/** 开启严格匹配（默认按路径前缀匹配） */
+		strict?: boolean;
+		component: Component;
+		/** 页面标题（未提供时回退到 id） */
+		name: MaybeRefOrGetter<string>;
+		/** 页面描述（副标题） */
+		desc?: MaybeRefOrGetter<string>;
+		/** 侧栏图标名，默认 "activity:default" */
+		icon?: MaybeRefOrGetter<string>;
+		/** 侧栏排序权重，越小越靠前 */
+		order?: number;
+		/** 访问所需权限等级（authority） */
+		authority?: number;
+		/** 在侧栏中的位置：顶部或底部 */
+		position?: "top" | "bottom";
+		/** 依赖的数据服务键：任一未就绪时页面不可进入 */
+		fields?: (keyof Store)[];
+		/** @deprecated */
+		when?: () => boolean;
+		disabled?: () => boolean;
+	}
+}
+
+// 实例上的 desc/name/icon 是 getter(toValue 解析后的值),与 Options 中
+// MaybeRefOrGetter 形状不同,故从继承中排除后再声明
+export interface Activity
+	extends Omit<Activity.Options, "desc" | "name" | "icon"> {
+	desc?: string | undefined;
+	name?: string | undefined;
+	icon?: string | undefined;
+}
+
+/** 从路由路径提取 activity id（首个非空路径段），如 "/foo/bar" → "foo" */
+function getActivityId(path: string) {
+	return path.split("/").find(Boolean) ?? "";
+}
+
+/** 页面被卸载时暂存的目标路由：等待路由就绪后由 handleUpdate 跳转 */
+export const redirectTo = ref<string | null>();
+
+/**
+ * activity：控制台的一个页面（侧栏一项 + 一条 vue-router 路由）。
+ * 由 ctx.page() 创建，dispose 时移除路由并尝试回退到首页。
+ */
+export class Activity {
+	id: string;
+	_disposables: Disposable[] = [];
+
+	ctx: Context;
+	options: Activity.Options;
+
+	constructor(ctx: Context, options: Activity.Options) {
+		this.ctx = ctx;
+		this.options = options;
+		options.order ??= 0;
+		options.position ??= "top";
+		Object.assign(this, omit(options, ["icon", "name", "desc", "disabled"]));
+		const { path, id = getActivityId(path), component } = options;
+		// 路由挂载时把 activity 实例放进 meta，供导航守卫与标题栏取用
+		this._disposables.push(
+			ctx.$router.router.addRoute({
+				path,
+				name: id,
+				component,
+				meta: { activity: this },
+			}),
+		);
+		this.id ??= id;
+		this.handleUpdate();
+		this.authority ??= 0;
+		this.fields ??= [];
+		ctx.$router.pages[this.id] = this;
+	}
+
+	/** 若存在待跳转目标且当前路由已能解析，则立即完成该跳转 */
+	handleUpdate() {
+		if (redirectTo.value) {
+			const location = this.ctx.$router.router.resolve(redirectTo.value);
+			if (location.matched.length) {
+				redirectTo.value = null;
+				this.ctx.$router.router.replace(location);
+			}
+		}
+	}
+
+	/** 页面图标名（默认 "activity:default"，MaybeRefOrGetter 解析后的值） */
+	get icon() {
+		return toValue(this.options.icon ?? "activity:default");
+	}
+
+	/** 页面标题（默认取 id） */
+	get name() {
+		return toValue(this.options.name ?? this.id);
+	}
+
+	/** 页面描述 */
+	get desc() {
+		return toValue(this.options.desc);
+	}
+
+	/**
+	 * 判断页面当前是否应被禁用：
+	 * activity 事件被拦截（bail）、依赖数据未就绪、when/disabled 判否均视为禁用。
+	 */
+	disabled() {
+		if (this.ctx.bail("activity", this)) return true;
+		if (!this.fields?.every((key) => store[key])) return true;
+		if (this.when && !this.when()) return true;
+		if (this.options.disabled?.()) return true;
+		return false;
+	}
+
+	dispose() {
+		this._disposables.forEach((dispose) => dispose());
+		// 若被卸载的恰是当前展示的页面：暂存目标路由，退回缓存的首页
+		const current = this.ctx.$router.router.currentRoute.value;
+		if (current?.meta?.activity === this) {
+			redirectTo.value = current.fullPath;
+			this.ctx.$router.router.push(this.ctx.$router.cache["home"] || "/");
+		}
+		return delete this.ctx.$router.pages[this.id];
+	}
+}
+
+/**
+ * 路由服务：封装 vue-router，管理 activity 页面注册、插槽视图与页面缓存。
+ *
+ * - `ctx.page()` 注册 activity（页面）；
+ * - `ctx.slot()` 向具名插槽（layout / status / global 等）注入视图；
+ * - `views` 为插槽名 → 视图列表，`pages` 为页面 id → Activity，
+ *   `cache` 记录各页面最近一次访问的完整路径。
+ */
+export default class RouterService extends Service {
+	/** 各插槽（按 type 分组）的视图列表 */
+	public views = reactive<Dict<SlotOptions[]>>({});
+	/** 页面 id → 最近访问的完整路径（用于"返回上次位置"） */
+	public cache = reactive<Record<PropertyKey, string>>({});
+	/** 已注册的全部 activity 页面 */
+	public pages = reactive<Dict<Activity>>({});
+	public router = createRouter({
+		history: createWebHistory(global.uiPath),
+		// 复用全局 .active 类作为路由激活态样式
+		linkActiveClass: "active",
+		routes: [],
+	});
+
+	constructor(ctx: Context) {
+		super(ctx, "$router", true);
+		ctx.mixin("$router", ["slot", "page"]);
+
+		const initialTitle = document.title;
+		ctx.effect(() =>
+			this.router.afterEach((route) => {
+				const { name, fullPath } = this.router.currentRoute.value;
+				if (name) {
+					// 本应用的路由名均为字符串;reactive 收窄了索引签名,不含 symbol
+					this.cache[name as string] = fullPath;
+				}
+				// 进入 activity 页面时更新标签页标题为 "页面名 | 原标题"
+				if (route.meta.activity) {
+					document.title = `${route.meta.activity.name}`;
+					if (initialTitle) document.title += ` | ${initialTitle}`;
+				}
+			}),
+		);
+
+		this.router.beforeEach(async (to, from) => {
+			if (to.matched.length) {
+				// 已能匹配：目标是具体页面时清空待跳转标记
+				if (to.matched[0]?.path !== "/") {
+					redirectTo.value = null;
+				}
+				return;
+			}
+
+			// 首次导航（from 为起始位置）时等待扩展加载完，
+			// 页面路由由扩展注册，未加载前无法匹配
+			if (from === START_LOCATION) {
+				await ctx.$loader.initTask;
+				const resolved = this.router.resolve(to);
+				if (resolved.matched.length) return resolved;
+			}
+
+			// 仍无法匹配：暂存目标路径，先落回缓存首页（或 "/"），
+			// 待对应页面注册后由 Activity.handleUpdate() 自动跳转
+			redirectTo.value = to.fullPath;
+			const result = this.cache["home"] || "/";
+			if (result === to.fullPath) return;
+			return result;
+		});
+
+		// 图片查看器等全局浮层经 global 插槽挂载
+		this.slot({
+			type: "global",
+			component: Overlay,
+		});
+	}
+
+	/**
+	 * 向具名插槽注入视图组件；返回取消注册函数。
+	 * when 是 disabled 的旧写法（取反语义），仅做兼容转换。
+	 */
+	slot(options: SlotOptions) {
+		options.order ??= 0;
+		const component = this.ctx.wrapComponent(options.component);
+		if (component) options.component = component;
+		if (options.when) {
+			const { when } = options;
+			options.disabled = () => !when();
+		}
+		return this.ctx.effect(() => {
+			const list = (this.views[options.type] ||= []);
+			insert(list, options);
+			return () => {
+				remove(list, options);
+				if (!list.length) delete this.views[options.type];
+			};
+		});
+	}
+
+	/** 注册 activity 页面（自动挂到 vue-router 与侧栏）；返回取消注册函数 */
+	page(options: Activity.Options) {
+		const component = this.ctx.wrapComponent(options.component);
+		if (component) options.component = component;
+		return this.ctx.effect(() => {
+			const activity = new Activity(this.ctx, options);
+			return () => activity.dispose();
+		});
+	}
+}

package/client/plugins/setting.ts

@@ -0,0 +1,217 @@
+/**
+ * 设置服务：控制台本地配置（localStorage）与设置面板的管理。
+ *
+ * 配置分两层：original（用户显式修改的原始字段）与 resolved
+ * （经所有插件 schema 补全后的完整配置），二者双向同步（见文末类注释）。
+ * 插件通过 `ctx.settings()` 注册设置分区、`ctx.schema()` 注册自定义控件。
+ */
+import { type RemovableRef, useLocalStorage } from "@vueuse/core";
+import { type Dict, remove } from "cosmokit";
+import { type Component, computed, markRaw, reactive, ref, watch } from "vue";
+import { Schema, SchemaBase } from "../../../components/client/index.ts";
+import type { Config } from "..";
+import type { Context } from "../context";
+import { insert, type Ordered, Service } from "../utils";
+
+declare module "../context" {
+	interface Context {
+		$setting: SettingService;
+		schema(extension: SchemaBase.Extension): () => void;
+		settings(options: SettingOptions): () => void;
+	}
+
+	interface Internal {
+		settings: Dict<SettingOptions[]>;
+	}
+}
+
+/** 设置面板条目：按 id 分组展示于"设置"页面各分区 */
+interface SettingOptions extends Ordered {
+	/** 所属设置分区 id（空串为通用设置） */
+	id: string;
+	/** 分区标题 */
+	title?: string;
+	disabled?: () => boolean;
+	/** 该分区的配置 schema（渲染为表单） */
+	schema?: Schema;
+	/** 自定义渲染组件（替代 schema 表单） */
+	component?: Component;
+}
+
+/**
+ * 带版本号的 localStorage 存储。
+ * 版本号变化（或首次写入）时整体重置为初始值，避免旧结构残留。
+ * 以 "koishi.console." 为键前缀隔离。
+ */
+export let useStorage = <T extends object>(
+	key: string,
+	version?: number,
+	fallback?: () => T,
+): RemovableRef<T> => {
+	const initial = (fallback ? fallback() : {}) as T & {
+		__version__?: number | undefined;
+	};
+	initial.__version__ = version;
+	const storage = useLocalStorage(`koishi.console.${key}`, initial);
+	if (storage.value.__version__ !== version) {
+		storage.value = initial;
+	}
+	return storage;
+};
+
+/** 替换默认的 useStorage 实现（宿主 app 用于接管持久化方式） */
+export function provideStorage(factory: typeof useStorage) {
+	useStorage = factory;
+}
+
+interface StorageData<T> {
+	version: number;
+	data: T;
+}
+
+/** @deprecated 已废弃，请改用 `useConfig` */
+export function createStorage<T extends object>(
+	key: string,
+	version: number,
+	fallback?: () => T,
+) {
+	const storage = useLocalStorage(
+		`koishi.console.${key}`,
+		{} as StorageData<T>,
+	);
+	const initial = fallback ? fallback() : ({} as T);
+	if (storage.value.version !== version) {
+		storage.value = { version, data: initial };
+	} else if (!Array.isArray(storage.value.data)) {
+		storage.value.data = { ...initial, ...storage.value.data };
+	}
+	return reactive<T>(storage.value["data"]);
+}
+
+// 默认配置本来就是「部分」配置:各插件向 Config 合并的必填字段
+// (如 status)在此处并不存在,故做一次收窄断言以兼容任意增强
+/** 用户实际保存的原始配置（localStorage，仅含用户改过的字段） */
+export const original = useStorage<Config>(
+	"config",
+	undefined,
+	() =>
+		({
+			theme: {
+				mode: "auto",
+				dark: "default-dark",
+				light: "default-light",
+			},
+			locale: "zh-CN",
+		}) as unknown as Config,
+);
+
+/** 经全部插件 schema 校验/补全后的完整配置（组件默认读取这一份） */
+export const resolved = ref({} as Config);
+
+/**
+ * 获取客户端配置。
+ * @param useOriginal 为 true 时返回用户原始存储（默认返回补全后的 resolved）
+ */
+export const useConfig = (useOriginal = false) =>
+	useOriginal ? original : resolved;
+
+/**
+ * 设置服务：管理控制台的本地配置与设置面板。
+ *
+ * 核心是 original 与 resolved 的双向同步：
+ * 用户改 resolved → simplify 后写回 original（只保留用户改过的字段）；
+ * original 或 schema 变化 → 重新用 schema 解释得到完整 resolved。
+ */
+export default class SettingService extends Service {
+	constructor(ctx: Context) {
+		super(ctx, "$setting", true);
+		ctx.mixin("$setting", {
+			settings: "settings",
+			extendSchema: "schema",
+		});
+
+		ctx.internal.settings = reactive({});
+
+		this.settings({
+			id: "",
+			title: "通用设置",
+			order: 1000,
+			schema: Schema.object({
+				locale: Schema.union(["zh-CN", "en-US"]).description("语言设置。"),
+			}).description("通用设置"),
+		});
+
+		// 汇总所有分区 schema 为一个相交对象，作为 resolved 的解释器
+		const schema = computed(() => {
+			const list: Schema[] = [];
+			for (const settings of Object.values(ctx.internal.settings)) {
+				for (const options of settings) {
+					if (options.schema) {
+						list.push(options.schema);
+					}
+				}
+			}
+			return Schema.intersect(list);
+		});
+
+		// 监听用户在表单上的修改：化简（只留显式设置的字段）后写回原始存储
+		const doWatch = () =>
+			watch(
+				resolved,
+				(value) => {
+					console.debug("config", JSON.stringify(value));
+					original.value = schema.value.simplify(value);
+				},
+				{ deep: true },
+			);
+
+		let stop = doWatch();
+
+		// 重放同步：先停掉 resolved 监听，用 schema 重新解释 original，
+		// 再重启监听——避免解释过程触发的写回造成回环
+		const update = () => {
+			stop?.();
+			try {
+				resolved.value = schema.value(original.value);
+			} catch (error) {
+				console.error(error);
+			}
+			stop = doWatch();
+		};
+
+		ctx.effect(() => () => stop?.());
+
+		// 原始存储或 schema 集合任一变化，都重新生成 resolved
+		ctx.effect(() => watch(original, update, { deep: true }));
+		ctx.effect(() => watch(schema, update));
+	}
+
+	/**
+	 * 注册一个 schema 扩展（自定义控件类型/角色），供设置表单渲染使用。
+	 * 返回取消注册函数。
+	 */
+	extendSchema(extension: SchemaBase.Extension) {
+		const component = this.ctx.wrapComponent(extension.component);
+		if (component) extension.component = component;
+		return this.ctx.effect(() => {
+			SchemaBase.extensions.add(extension);
+			return () => SchemaBase.extensions.delete(extension);
+		});
+	}
+
+	/** 向设置面板追加一个分区条目；返回取消注册函数 */
+	settings(options: SettingOptions) {
+		markRaw(options);
+		options.order ??= 0;
+		const component = this.ctx.wrapComponent(options.component);
+		if (component) options.component = component;
+		return this.ctx.effect(() => {
+			const list = (this.ctx.internal.settings[options.id] ||= []);
+			insert(list, options);
+			return () => {
+				remove(list, options);
+				if (!list.length) delete this.ctx.internal.settings[options.id];
+			};
+		});
+	}
+}

package/client/plugins/theme.ts

@@ -0,0 +1,134 @@
+/**
+ * 主题服务：管理控制台的深浅色模式与主题注册。
+ *
+ * - 监听系统颜色偏好（auto 模式下自动跟随）；
+ * - 向 <html> 写入 theme 属性与 dark 类，驱动 CSS 变量切换；
+ * - 插件通过 `ctx.theme()` 注册主题，并可附带各插槽位的装饰组件。
+ */
+import { usePreferredDark } from "@vueuse/core";
+import type { Dict } from "cosmokit";
+import { type Component, computed, markRaw, reactive, watchEffect } from "vue";
+import { Schema } from "../../../components/client/index.ts";
+import type { Context } from "../context";
+import { Service } from "../utils";
+import { useConfig } from "./setting";
+
+declare module "../context" {
+	interface Context {
+		$theme: ThemeService;
+		theme(options: ThemeOptions): () => void;
+	}
+
+	interface Internal {
+		themes: Dict<ThemeOptions>;
+	}
+}
+
+declare module ".." {
+	interface Config {
+		theme: Config.Theme;
+	}
+
+	export namespace Config {
+		export interface Theme {
+			mode: "auto" | "dark" | "light";
+			dark: string;
+			light: string;
+		}
+	}
+}
+
+/** 主题注册选项：name 支持多语言文案，components 按插槽名提供装饰组件 */
+export interface ThemeOptions {
+	id: string;
+	name: string | Dict<string>;
+	components?: Dict<Component>;
+}
+
+// 系统级深色偏好（用户操作系统设置）
+const preferDark = usePreferredDark();
+
+const config = useConfig();
+
+// 实际生效的颜色模式：配置为 auto 时跟随系统偏好
+const colorMode = computed(() => {
+	const mode = config.value.theme.mode;
+	if (mode !== "auto") return mode;
+	return preferDark.value ? "dark" : "light";
+});
+
+/** 获取当前生效的颜色模式（"dark" | "light"） */
+export const useColorMode = () => colorMode;
+
+export default class ThemeService extends Service {
+	constructor(ctx: Context) {
+		super(ctx, "$theme", true);
+		ctx.mixin("$theme", ["theme"]);
+
+		ctx.internal.themes = reactive({});
+
+		ctx.settings({
+			id: "appearance",
+			title: "外观设置",
+			order: 900,
+			schema: Schema.object({
+				theme: Schema.object({
+					mode: Schema.union([
+						Schema.const("auto").description("跟随系统"),
+						Schema.const("dark").description("深色"),
+						Schema.const("light").description("浅色"),
+					])
+						.default("auto")
+						.description("主题偏好。"),
+					dark: Schema.string()
+						.role("theme", { mode: "dark" })
+						.default("default-dark")
+						.description("深色主题。"),
+					light: Schema.string()
+						.role("theme", { mode: "light" })
+						.default("default-light")
+						.description("浅色主题。"),
+				}).description("主题设置"),
+			}),
+		});
+
+		ctx.effect(() =>
+			watchEffect(
+				() => {
+					if (!config.value.theme) return;
+					const root = window.document.querySelector("html");
+					if (!root) return;
+					// 把当前主题名写到 <html theme="...">，并同步 dark 类；
+					// 主题样式与深色变量均由 CSS 依据这两个标记选择
+					root.setAttribute("theme", config.value.theme[colorMode.value]);
+					if (colorMode.value === "dark") {
+						root.classList.add("dark");
+					} else {
+						root.classList.remove("dark");
+					}
+				},
+				{ flush: "post" },
+			),
+		);
+	}
+
+	/**
+	 * 注册一个主题；返回取消注册函数。
+	 * components 中的每个插槽组件仅在该主题被选中时启用，
+	 * 用于注入背景装饰、挂件等随主题切换的界面元素。
+	 */
+	theme(options: ThemeOptions) {
+		markRaw(options);
+		for (const [type, component] of Object.entries(options.components || {})) {
+			this.ctx.slot({
+				type,
+				disabled: () => config.value.theme[colorMode.value] !== options.id,
+				component,
+			});
+		}
+		return this.ctx.effect(() => {
+			this.ctx.internal.themes[options.id] = options;
+			return () => delete this.ctx.internal.themes[options.id];
+		});
+	}
+}

package/client/shims.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 浏览器端类型垫片(packages/web/client 自身使用;app 项目通过
+ * app/shims.d.ts 引用本文件):
+ *
+ * 1. "schemastery-vue/client" 虚拟子路径:由根 tsconfig.client.json 的
+ *    paths 解析到 packages/web/components/client/schemastery-vue-client.ts
+ *    (真实模块,单一事实源),运行时经构建器别名映射回真实包。
+ * 2. "@koishi-ce/plugin-console":本包 node_modules 中没有该插件的链接
+ *    (依赖方向相反,浏览器端 tsconfig 也没有 paths),且该插件源码含有
+ *    node 专属导入,无法直接进入浏览器程序,故在此按其公开面手写声明。
+ *    字段与 plugins/webui/console/src/node/index.ts 的 ClientConfig 以及
+ *    packages/node/console 的 DataService / Console.Services 保持一致。
+ */
+
+declare module "@koishi-ce/plugin-console" {
+	import type { Schema } from "@koishi-ce/koishi";
+	import type { Dict } from "cosmokit";
+
+	export interface ClientConfig {
+		devMode: boolean;
+		uiPath: string;
+		endpoint: string;
+		static?: boolean;
+		heartbeat?: HeartbeatConfig;
+		proxyBase?: string;
+	}
+
+	interface HeartbeatConfig {
+		interval?: number;
+		timeout?: number;
+	}
+
+	export interface Events {
+		ping(): string;
+	}
+
+	/** 服务端数据服务的类型骨架（仅类型层面使用，浏览器端无实现） */
+	export abstract class DataService<T = unknown> {}
+
+	/** 扩展入口描述：由服务端 entry 服务推送，loader 据此动态加载扩展 */
+	export interface EntryData {
+		files: string[];
+		paths?: string[];
+		data: unknown;
+	}
+
+	export namespace Console {
+		/** 服务端可用数据服务的清单，Store 类型据此推导各键的负载数据 */
+		export interface Services {
+			entry: DataService<Dict<EntryData>>;
+			schema: DataService<Dict<Schema>>;
+			permissions: DataService<string[]>;
+		}
+	}
+}

package/client/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"extends": "../../../../tsconfig.client",
+	"include": ["."],
+	"compilerOptions": {
+		"alwaysStrict": true,
+		"noPropertyAccessFromIndexSignature": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noImplicitReturns": true,
+		"noFallthroughCasesInSwitch": true,
+		"noImplicitOverride": true,
+		"allowUnreachableCode": false,
+		"allowUnusedLabels": false
+	}
+}