@koishi-ce/client 1.0.0

package/client/components/layout/card.vue

@@ -0,0 +1,69 @@
+<!--
+  k-card：通用卡片容器。
+  可选 header（标题文字或 header 插槽）与 footer 插槽；
+  scrollbar 开启时正文区使用 el-scrollbar 滚动。
+-->
+<template>
+  <section class="k-card">
+    <header v-if="title || $slots.header">
+      <slot name="header">{{ title }}</slot>
+    </header>
+    <el-scrollbar v-if="scrollbar">
+      <div class="k-card-body"><slot/></div>
+    </el-scrollbar>
+    <div v-else class="k-card-body"><slot/></div>
+    <footer v-if="$slots.footer">
+      <slot name="footer"></slot>
+    </footer>
+  </section>
+</template>
+
+<script lang="ts" setup>
+defineProps<{
+	title?: string;
+	scrollbar?: boolean;
+}>();
+</script>
+
+<style lang="scss">
+
+$paddingX: 1.25rem;
+$paddingY: 1.5rem;
+
+.k-card {
+  border-radius: 8px;
+  overflow: hidden;
+  position: relative;
+  background-color: var(--k-card-bg);
+  border: 1px solid var(--k-card-border);
+  box-shadow: var(--k-card-shadow);
+  transition: var(--color-transition);
+
+  header {
+    position: relative;
+    font-size: 1.25rem;
+    font-weight: bolder;
+    margin: $paddingX 0;
+    padding: 0 $paddingY;
+    transition: color 0.3s ease;
+  }
+
+  footer {
+    position: relative;
+    margin: $paddingX 0;
+    padding: 0 $paddingY;
+  }
+
+  .k-card-body {
+    position: relative;
+    margin: $paddingX 0;
+    padding: 0 $paddingY;
+  }
+
+  &.frameless .k-card-body {
+    margin: 0;
+    padding: 0;
+  }
+}
+
+</style>

package/client/components/layout/content.vue

@@ -0,0 +1,37 @@
+<!--
+  k-content：页面主内容区容器。
+  水平居中、限宽 55rem，自带垂直滚动（el-scrollbar），
+  左右留白随屏幕宽度自适应收窄。
+-->
+<template>
+  <el-scrollbar>
+    <div class="k-content">
+      <slot></slot>
+    </div>
+  </el-scrollbar>
+</template>
+
+<style lang="scss">
+
+.k-content {
+  --content-padding: 3rem;
+
+  margin: auto;
+  max-width: 55rem;
+  box-sizing: border-box;
+  padding: 3rem var(--content-padding);
+
+  > :first-child {
+    margin-top: 0;
+  }
+
+  @media screen and (max-width: 768px) {
+    --content-padding: 2rem;
+  }
+
+  @media screen and (max-width: 480px) {
+    --content-padding: 1.5rem;
+  }
+}
+
+</style>

package/client/components/layout/empty.vue

@@ -0,0 +1,41 @@
+<!--
+  k-empty：空状态占位组件。
+  居中展示 Koishi 徽标图标与默认插槽文案，用于无数据 / 无权限等场景。
+-->
+<template>
+  <div class="k-empty">
+    <div class="image">
+      <k-icon name="koishi"></k-icon>
+    </div>
+    <slot></slot>
+  </div>
+</template>
+
+<style lang="scss">
+
+.k-empty {
+  height: 100%;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  flex-direction: column;
+  text-align: center;
+  box-sizing: border-box;
+  padding: 2rem 0;
+  gap: 1.5rem;
+  font-size: 14px;
+  color: var(--el-text-color-secondary);
+
+  .image {
+    width: 10rem;
+    color: var(--k-page-bg);
+    transition: color 0.3s ease;
+
+    svg {
+      height: 100%;
+      width: 100%;
+    }
+  }
+}
+
+</style>

package/client/components/layout/index.ts

@@ -0,0 +1,15 @@
+import type { App } from "vue";
+import Card from "./card.vue";
+import Content from "./content.vue";
+import Empty from "./empty.vue";
+import TabGroup from "./tab-group.vue";
+import TabItem from "./tab-item.vue";
+
+/** 注册布局组件（k-card / k-content / k-empty / k-tab-group / k-tab-item） */
+export default function (app: App) {
+	app.component("k-card", Card);
+	app.component("k-content", Content);
+	app.component("k-empty", Empty);
+	app.component("k-tab-group", TabGroup);
+	app.component("k-tab-item", TabItem);
+}

package/client/components/layout/tab-group.vue

@@ -0,0 +1,45 @@
+<!--
+  k-tab-group：侧栏式选项卡分组。
+  遍历 data（键 → 条目对象），filter 可按条目过滤显示；
+  每个条目渲染为一个 k-tab-item，选中键经 v-model 双向绑定，
+  条目数据通过作用域插槽传给内容。
+-->
+<template>
+  <template v-for="(item, key) in data" :key="key">
+    <k-tab-item v-model="model" :label="key"
+      v-if="filter ? filter(item) : true">
+      <slot v-bind="item"></slot>
+    </k-tab-item>
+  </template>
+</template>
+
+<script lang="ts" setup>
+import { computed } from "vue";
+
+const props = defineProps<{
+	data: object;
+	modelValue?: string;
+	filter?: (item: unknown) => boolean;
+}>();
+
+const emits = defineEmits(["update:modelValue"]);
+
+const model = computed({
+	get: () => props.modelValue,
+	set: (val) => emits("update:modelValue", val),
+});
+</script>
+
+<style lang="scss">
+
+.k-tab-group-title {
+  line-height: 2.25rem;
+  padding: 0 2rem !important;
+  font-weight: bold;
+}
+
+.k-tab-group-title:not(.k-select-item) {
+  margin-top: 0.5rem;
+}
+
+</style>

package/client/components/layout/tab-item.vue

@@ -0,0 +1,35 @@
+<!--
+  k-tab-item：选项卡条目（配合 k-tab-group 使用）。
+  label 为条目标识兼默认文案，点击时 emit update:modelValue；
+  与当前选中值相等时高亮。
+-->
+<template>
+  <div class="k-tab-item k-tab-menu-item truncate"
+    :title="label"
+    :class="{ active: label === modelValue }"
+    @click="$emit('update:modelValue', label)">
+    <slot>{{ label }}</slot>
+  </div>
+</template>
+
+<script lang="ts" setup>
+defineEmits(["update:modelValue"]);
+
+defineProps<{
+	label: string;
+	modelValue: string;
+}>();
+</script>
+
+<style lang="scss">
+
+.k-tab-item {
+  line-height: 2.25rem;
+  padding: 0 2rem 0 4rem;
+
+  &.active {
+    background-color: var(--k-hover-bg);
+  }
+}
+
+</style>

package/client/components/link.ts

@@ -0,0 +1,39 @@
+import { type App, defineComponent, h } from "vue";
+import { RouterLink } from "vue-router";
+import { useContext } from "../context";
+
+/**
+ * activity 页面链接组件（k-activity-link）：
+ * 传入页面 id，渲染一个指向该页面的 RouterLink。
+ * 目标路径优先取该页面上次访问的完整路径（缓存），
+ * 无缓存则回退到页面路由路径（去掉动态参数段）；默认插槽为空时
+ * 以页面名称作为链接文案。
+ */
+const KActivityLink = defineComponent({
+	props: {
+		/** 目标 activity 的 id */
+		id: String,
+	},
+	setup(props, { slots }) {
+		const ctx = useContext();
+		return () => {
+			const activity = props.id ? ctx.$router.pages[props.id] : undefined;
+			return h(
+				RouterLink,
+				{
+					// /:.+/ 去掉路径中的动态参数段，得到可直接访问的静态前缀
+					to: (ctx.$router.cache[activity?.id ?? ""] ||
+						activity?.path.replace(/:.+/, "")) as string,
+				},
+				{
+					default: () => slots["default"]?.() ?? activity?.name,
+				},
+			);
+		};
+	},
+});
+
+/** 注册全局组件 k-activity-link */
+export default function (app: App) {
+	app.component("k-activity-link", KActivityLink);
+}

package/client/components/perms.vue

@@ -0,0 +1,73 @@
+<!--
+  perms.vue：权限选择控件（array + perms 角色）。
+  把服务端下发的扁平权限名（如 "channel.xxx"）按 ":" 逐级拆分，
+  构造成 el-cascader 的级联选项树；checkStrictly 允只勾选父级权限，
+  emitPath: false 使选中值仍是完整的权限路径字符串。
+-->
+<template>
+  <schema-base>
+    <template #title><slot name="title"></slot></template>
+    <template #desc><slot name="desc"></slot></template>
+    <template #menu><slot name="menu"></slot></template>
+    <template #prefix><slot name="prefix"></slot></template>
+    <template #suffix><slot name="suffix"></slot></template>
+    <template #control>
+      <el-cascader
+        collapse-tags
+        v-model="config"
+        :options="options"
+        :props="{ multiple: true, checkStrictly: true, emitPath: false }"
+        :disabled="disabled">
+      </el-cascader>
+    </template>
+  </schema-base>
+</template>
+
+<script lang="ts" setup>
+// SchemaBase 经由 components 包的再导出获取:本包的 node_modules 没有
+// schemastery-vue 链接(它是 components 的依赖,Bun 隔离布局下不跨包可见)
+
+import { store } from "@koishi-ce/client";
+import { type Schema, SchemaBase } from "@koishi-ce/components";
+import type { CascaderOption } from "element-plus";
+import { computed, type PropType } from "vue";
+
+defineProps({
+	schema: {} as PropType<Schema>,
+	modelValue: {} as PropType<string>,
+	disabled: {} as PropType<boolean>,
+	prefix: {} as PropType<string>,
+	initial: {} as PropType<Record<never, never>>,
+});
+
+defineEmits(["update:modelValue"]);
+
+const config = SchemaBase.useModel();
+
+/**
+ * 递归插入一个权限路径（如 ["channel", "admin", "x"]）：
+ * 逐段查找/创建级联节点；中间段（还有下级时）标记为 disabled，
+ * 因为 el-cascader 的父节点勾选会影响子级，而中间段并非真实权限。
+ */
+function addNode(nodes: CascaderOption[], path: string[], prefix = "") {
+	const name = path.shift();
+	let node = nodes.find((node) => node.value === prefix + name);
+	if (!node) {
+		node = { value: prefix + name, label: name, disabled: !!path.length };
+		nodes.push(node);
+	}
+	if (!path.length) return;
+	addNode((node.children ||= []), path, `${prefix + name}:`);
+}
+
+// 由全部权限名构建级联选项树
+const options = computed(() => {
+	const result: CascaderOption[] = [];
+	for (const name of store.permissions) {
+		const path = name.split(":");
+		addNode(result, path);
+	}
+	console.log(result);
+	return result;
+});
+</script>

package/client/components/slot.ts

@@ -0,0 +1,95 @@
+import { type App, type Component, defineComponent, h } from "vue";
+import { useContext } from "../context";
+
+/** 插槽条目的基础形状：参与排序的组件 */
+export interface SlotItem {
+	order?: number;
+	component: Component;
+}
+
+/**
+ * 通过 `ctx.slot()` 注册的外部插槽视图。
+ * type 为插槽名（layout / status / global 等）。
+ */
+export interface SlotOptions extends SlotItem {
+	type: string;
+	/** @deprecated */
+	when?: () => boolean;
+	disabled?: () => boolean;
+}
+
+/**
+ * 具名插槽渲染组件（k-slot）。
+ *
+ * 合并两种来源的内容并按 order 降序渲染：
+ * - internal：模板里直接写在 k-slot 内的 k-slot-item 子节点；
+ * - external：由 ctx.slot() 注册到该插槽名的视图组件。
+ * single 模式下只渲染排序最高的一项（用于 activity 页面等独占插槽）。
+ */
+export const KSlot = defineComponent({
+	props: {
+		/** 插槽名 */
+		name: String,
+		/** 透传给外部视图组件的属性 */
+		data: Object,
+		/** 是否单选模式（只渲染排序最高的一项） */
+		single: Boolean,
+	},
+	setup(props, { slots }) {
+		const ctx = useContext();
+		return () => {
+			// internal：模板内以 k-slot-item 声明的节点，order 取其 props
+			const internal = props.single
+				? []
+				: [...(slots["default"]?.() || [])]
+						.filter((node) => node.type === KSlotItem)
+						.map((node) => ({ node, order: node.props?.["order"] || 0 }));
+			// external：ctx.slot() 注册的视图，disabled 的不渲染
+			const external = [
+				...(props.name ? ctx.$router.views[props.name] || [] : []),
+			]
+				.filter((item) => !item.disabled?.())
+				.map((item) => ({
+					node: h(item.component, { ...props.data }, slots),
+					order: item.order,
+					layer: 1,
+				}));
+			const children = [...internal, ...external].sort(
+				(a, b) => b.order - a.order,
+			);
+			if (props.single) {
+				// 无外部视图时回退到模板默认内容
+				return children[0]?.node || slots["default"]?.();
+			}
+			return children.map((item) => item.node);
+		};
+	},
+});
+
+/** 插槽条目包装组件（k-slot-item）：仅透传 order 排序权重 */
+const KSlotItem = defineComponent({
+	props: {
+		order: Number,
+	},
+	setup(_props, { slots }) {
+		return () => slots["default"]?.();
+	},
+});
+
+/** 生成绑定固定插槽名的单选 k-slot 快捷组件 */
+function defineSlotComponent(name: string) {
+	return defineComponent({
+		inheritAttrs: false,
+		setup(_, { slots, attrs }) {
+			return () => h(KSlot, { name, data: attrs, single: true }, slots);
+		},
+	});
+}
+
+/** 注册插槽相关全局组件（k-slot / k-slot-item / k-layout / k-status） */
+export default (app: App) => {
+	app.component("k-slot", KSlot);
+	app.component("k-slot-item", KSlotItem);
+	app.component("k-layout", defineSlotComponent("layout"));
+	app.component("k-status", defineSlotComponent("status"));
+};

package/client/context.ts

@@ -0,0 +1,143 @@
+import * as cordis from "cordis";
+import {
+	type App,
+	type Component,
+	createApp,
+	defineComponent,
+	h,
+	inject,
+	markRaw,
+	onBeforeUnmount,
+	provide,
+	type Ref,
+	resolveComponent,
+} from "vue";
+import ActionService from "./plugins/action";
+import I18nService from "./plugins/i18n";
+import LoaderService from "./plugins/loader";
+import RouterService from "./plugins/router";
+import SettingService from "./plugins/setting";
+import ThemeService from "./plugins/theme";
+
+// —— 布局相关的 Context 类型扩展 ——
+
+/** 前端侧事件表：在 cordis 事件的基础上扩展本库自定义事件 */
+export interface Events<C extends Context = Context> extends cordis.Events<C> {}
+
+/**
+ * 前端 Context 接口：各服务插件通过 `declare module "../context"`
+ * 向本接口合并自身的方法与属性（如 `$router`、`page()` 等）。
+ */
+export interface Context {
+	[Context.events]: Events<this>;
+	internal: Internal;
+}
+
+/**
+ * 在组件 setup 中获取与当前组件生命周期绑定的 Context。
+ *
+ * 实现：从父级注入根 Context，创建一个空的插件 fork，使得返回的
+ * 子上下文在组件卸载时（onBeforeUnmount）自动 dispose，从而组件内
+ * 通过它注册的副作用（effect / 事件监听等）会随组件销毁被清理。
+ */
+export function useContext() {
+	const parent = inject("cordis") as Context;
+	const fork = parent.plugin(() => {});
+	onBeforeUnmount(() => fork.dispose());
+	return fork.ctx;
+}
+
+/**
+ * 获取当前扩展（extension）通过 RPC 携带的只读数据。
+ * 仅在由 loader 动态加载的扩展组件内可用。
+ */
+export function useRpc<T>(): Ref<T> {
+	const parent = inject("cordis") as Context;
+	return parent.extension?.data as Ref<T>;
+}
+
+// 各服务通过 `declare module "../context"` 对 Internal 做接口合并,
+// 因此这里必须是 interface 而非类型别名(空 interface 不能被 biome 自动
+// 改写为 type alias,否则合并会变成 TS2300 重复标识符)
+// biome-ignore lint/suspicious/noEmptyInterface: 需要保持 interface 以支持声明合并
+export interface Internal {}
+
+/**
+ * 前端根 Context：持有 Vue 根应用 `app`，构造时安装六个核心服务插件，
+ * 并在 `ready` 阶段（扩展入口加载完毕后）挂载到 `#app` 节点。
+ */
+export class Context extends cordis.Context {
+	app: App;
+
+	constructor() {
+		super();
+		// cordis.Context 上对应字段不含 null(exactOptionalPropertyTypes),
+		// 运行时以 null 表示「尚未加载」,类型层面按已知模式收窄
+		this.extension = null as never;
+		this.internal = {} as Internal;
+		// Vue 根应用：渲染两个顶级插槽位——root（单选，承载 activity 页面）
+		// 与 global（多选，承载全局浮层如右键菜单、图片查看器）
+		this.app = createApp(
+			defineComponent({
+				setup: () => () => [
+					h(resolveComponent("k-slot"), { name: "root", single: true }),
+					h(resolveComponent("k-slot"), { name: "global" }),
+				],
+			}),
+		);
+		// 向整棵组件树提供根 Context，供 useContext() 注入
+		this.app.provide("cordis", this);
+
+		this.plugin(ActionService);
+		this.plugin(I18nService);
+		this.plugin(LoaderService);
+		this.plugin(RouterService);
+		this.plugin(SettingService);
+		this.plugin(ThemeService);
+
+		this.on("ready", async () => {
+			// 先等待全部扩展入口就绪（i18n / router 依赖扩展注册的资源），
+			// 再依次挂载国际化与路由，最后把 Vue 应用渲染到页面上
+			await this.$loader.initTask;
+			this.app.use(this.$i18n.i18n);
+			this.app.use(this.$router.router);
+			this.app.mount("#app");
+		});
+	}
+
+	/**
+	 * 注册 window 级事件监听，并纳入 cordis effect 管理：
+	 * 当前作用域销毁时自动移除监听。
+	 */
+	addEventListener<K extends keyof WindowEventMap>(
+		type: K,
+		listener: (this: Window, ev: WindowEventMap[K]) => unknown,
+		options?: boolean | AddEventListenerOptions,
+	) {
+		return this.effect(() => {
+			window.addEventListener(type, listener, options);
+			return () => window.removeEventListener(type, listener, options);
+		});
+	}
+
+	/**
+	 * 包装组件：为动态加载的组件提供独立的 cordis 注入源。
+	 *
+	 * 未加载任何扩展（extension 为 null）时原样返回；
+	 * 否则包一层 wrapper 组件，将当前 ctx provide 为 "cordis"，
+	 * 使组件树内部通过 useContext() 拿到的是注册它时的上下文。
+	 */
+	wrapComponent(component: Component | undefined) {
+		if (!component) return;
+		if (!this.extension) return component;
+		return defineComponent((props, { slots }) => {
+			provide("cordis", this);
+			return () => h(component, props, slots);
+		});
+	}
+}
+
+// cordis 的原型对象不参与 Vue 响应式代理，避免被 reactive 包裹后
+// 触发不必要的依赖收集与性能开销
+markRaw(cordis.Context.prototype);
+markRaw(cordis.EffectScope.prototype);