@koishi-ce/client 1.0.3 → 1.1.0

package/client/locales/ru-RU.yml

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+# Copyright (c) 2026-present Koishi-CE contributors.
+
+pages:
+  home: Главная
+  settings: Настройки пользователя
+home:
+  connecting: Подключение к серверу Koishi...
+welcome:
+  title: Добро пожаловать в Koishi!
+  description: Ваш бот готов к работе. Выберите любой пункт ниже, чтобы начать путешествие по Koishi.
+  docs:
+    title: Документация
+    description: Начните читать официальную документацию — в ней есть всё, что вы хотите узнать.
+  forum:
+    title: Форум
+    description: Общайтесь с другими пользователями на форуме. Если возникнут проблемы, здесь можно обратиться за помощью.
+settings:
+  general: Общие настройки
+  appearance: Оформление
+  status: Настройки строки состояния
+loading:
+  page: Загрузка компонентов страницы
+  data: Загрузка данных...
+blank:
+  hint: Если вы видите эту страницу, плагин консоли загрузился успешно, но расширения консоли ещё не установлены.
+menu:
+  resetActivity: Сбросить панель активности
+overlay:
+  zoomOut: Уменьшить
+  zoomIn: Увеличить
+  reset: Сбросить
+  rotateLeft: Повернуть против часовой стрелки
+  rotateRight: Повернуть по часовой стрелке
+schema:
+  settings:
+    $description: Общие настройки
+    locale: Настройки языка.
+  theme:
+    $description: Настройки темы
+    mode: Предпочтительная тема.
+    mode-auto: Как в системе
+    mode-dark: Тёмная
+    mode-light: Светлая
+    dark: Тёмная тема.
+    light: Светлая тема.

package/client/locales/zh-CN.yml

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+# Copyright (c) 2026-present Koishi-CE contributors.
+
+pages:
+  home: 欢迎
+  settings: 用户设置
+home:
+  connecting: 正在连接到 Koishi 服务器……
+welcome:
+  title: 欢迎使用 Koishi！
+  description: 你的机器人已经准备就绪。点击下面的任一选项，开启你的 Koishi 之旅吧。
+  docs:
+    title: 阅读文档
+    description: 开始阅读官方文档。官方文档里包含了你想要了解的全部内容。
+  forum:
+    title: 前往论坛
+    description: 前往论坛与其他用户交流。如果你遇到了问题，可以在这里寻求帮助。
+settings:
+  general: 通用设置
+  appearance: 外观设置
+  status: 状态栏设置
+loading:
+  page: 正在加载页面组件
+  data: 正在加载数据……
+blank:
+  hint: 如果你看到了这个页面，说明控制台插件已经加载成功，但你尚未安装任何控制台扩展。
+menu:
+  resetActivity: 重置活动栏
+overlay:
+  zoomOut: 缩小
+  zoomIn: 放大
+  reset: 复原
+  rotateLeft: 逆时针旋转
+  rotateRight: 顺时针旋转
+schema:
+  settings:
+    $description: 通用设置
+    locale: 语言设置。
+  theme:
+    $description: 主题设置
+    mode: 主题偏好。
+    mode-auto: 跟随系统
+    mode-dark: 深色
+    mode-light: 浅色
+    dark: 深色主题。
+    light: 浅色主题。

package/client/locales/zh-TW.yml

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+# Copyright (c) 2026-present Koishi-CE contributors.
+
+pages:
+  home: 歡迎
+  settings: 使用者設定
+home:
+  connecting: 正在連線到 Koishi 伺服器……
+welcome:
+  title: 歡迎使用 Koishi！
+  description: 你的機器人已經準備就緒。點擊下面的任一選項，開啟你的 Koishi 之旅吧。
+  docs:
+    title: 閱讀文件
+    description: 開始閱讀官方文件。官方文件裡包含了你想要了解的全部內容。
+  forum:
+    title: 前往論壇
+    description: 前往論壇與其他使用者交流。如果你遇到了問題，可以在這裡尋求幫助。
+settings:
+  general: 一般設定
+  appearance: 外觀設定
+  status: 狀態列設定
+loading:
+  page: 正在載入頁面元件
+  data: 正在載入資料……
+blank:
+  hint: 如果你看到了這個頁面，說明控制檯插件已經載入成功，但你尚未安裝任何控制檯擴充功能。
+menu:
+  resetActivity: 重置活動欄
+overlay:
+  zoomOut: 縮小
+  zoomIn: 放大
+  reset: 復原
+  rotateLeft: 逆時針旋轉
+  rotateRight: 順時針旋轉
+schema:
+  settings:
+    $description: 一般設定
+    locale: 語言設定。
+  theme:
+    $description: 主題設定
+    mode: 主題偏好。
+    mode-auto: 跟隨系統
+    mode-dark: 深色
+    mode-light: 淺色
+    dark: 深色主題。
+    light: 淺色主題。

package/client/plugins/action.ts

@@ -11,7 +11,11 @@
  * 绑定右键菜单。作用域变量支持 "a.b" 点分键，经 Flatten 类型
  * 与运行时代理呈现为嵌套对象。
  */
-import { type Dict, type Intersect, remove } from "cosmokit";
+import {
+	type Dict,
+	type Intersect,
+	remove,
+} from "cosmokit";
 import {
 	type MaybeRefOrGetter,
 	markRaw,
@@ -58,7 +62,8 @@ export interface ActionOptions {
 }
 
 /** 旧版菜单项写法（字段与 ActionOptions 部分重叠），仅为兼容保留 */
-export type LegacyMenuItem = Partial<ActionOptions> & Omit<MenuItem, "id">;
+export type LegacyMenuItem = Partial<ActionOptions> &
+	Omit<MenuItem, "id">;
 
 /** 菜单项：label / type / icon 均支持写成随作用域变化的 getter */
 export interface MenuItem {
@@ -70,10 +75,14 @@ export interface MenuItem {
 }
 
 /** 值或（以作用域为参数的）取值函数 */
-export type MaybeGetter<T> = T | ((scope: Flatten<ActionContext>) => T);
+export type MaybeGetter<T> =
+	| T
+	| ((scope: Flatten<ActionContext>) => T);
 
 /** 作用域存储：扁平键到「值或 ref 或 getter」的映射 */
-type Store<S extends {}> = { [K in keyof S]?: MaybeRefOrGetter<S[K]> };
+type Store<S extends {}> = {
+	[K in keyof S]?: MaybeRefOrGetter<S[K]>;
+};
 
 /**
  * 把 "a.b.c" 形式的扁平键名归并为 { a: { b: { c } } } 的嵌套结构，
@@ -103,9 +112,14 @@ export interface ActiveMenu {
  * 触发时把附加值写入作用域，并在鼠标位置弹出自定义菜单（由 global 插槽渲染）。
  * @param id 菜单标识，menu() 注册的条目将展示在该菜单中
  */
-export function useMenu<K extends keyof ActionContext>(id: K) {
+export function useMenu<K extends keyof ActionContext>(
+	id: K,
+) {
 	const ctx = useContext();
-	return (event: MouseEvent, value: MaybeRefOrGetter<ActionContext[K]>) => {
+	return (
+		event: MouseEvent,
+		value: MaybeRefOrGetter<ActionContext[K]>,
+	) => {
 		ctx.define(id, value);
 		event.preventDefault();
 		const { clientX, clientY } = event;
@@ -133,7 +147,9 @@ export default class ActionService extends Service {
 		super(ctx, "$action", true);
 		ctx.mixin("$action", ["action", "menu", "define"]);
 
-		ctx.internal.scope = shallowReactive({} as Store<ActionContext>);
+		ctx.internal.scope = shallowReactive(
+			{} as Store<ActionContext>,
+		);
 		ctx.internal.menus = reactive({});
 		ctx.internal.actions = reactive({});
 		ctx.internal.activeMenus = reactive([]);
@@ -142,7 +158,9 @@ export default class ActionService extends Service {
 		// 与键盘事件逐项比对（ctrl 在 macOS 平台映射为 meta 键）
 		ctx.addEventListener("keydown", (event) => {
 			const scope = this.createScope();
-			for (const action of Object.values(ctx.internal.actions)) {
+			for (const action of Object.values(
+				ctx.internal.actions,
+			)) {
 				if (!action.shortcut) continue;
 				const keys = action.shortcut
 					.split("+")
@@ -158,7 +176,11 @@ export default class ActionService extends Service {
 							continue;
 						case "ctrl":
 							// macOS 没有 ctrl+字母 的快捷键惯例，改用 Cmd（meta）
-							if (navigator.platform.toLowerCase().includes("mac")) {
+							if (
+								navigator.platform
+									.toLowerCase()
+									.includes("mac")
+							) {
 								metaKey = true;
 							} else {
 								ctrlKey = true;
@@ -195,7 +217,8 @@ export default class ActionService extends Service {
 			items.forEach((item) => insert(list, item));
 			return () => {
 				items.forEach((item) => remove(list, item));
-				if (!list.length) delete this.ctx.internal.menus[id];
+				if (!list.length)
+					delete this.ctx.internal.menus[id];
 			};
 		});
 	}
@@ -222,7 +245,10 @@ export default class ActionService extends Service {
 	 * 可用 override 临时覆盖若干键值。
 	 */
 	createScope(override = {}) {
-		const scope = { ...this.ctx.internal.scope, ...override };
+		const scope = {
+			...this.ctx.internal.scope,
+			...override,
+		};
 		return createScope(scope);
 	}
 }
@@ -241,11 +267,18 @@ function createScope(
 			if (typeof key === "symbol")
 				return (target as Record<symbol, unknown>)[key];
 			key = prefix + key;
-			const source = scope as Record<string, MaybeRefOrGetter<unknown>>;
+			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))) {
+			if (
+				Object.keys(scope).some((k) =>
+					k.startsWith(_prefix),
+				)
+			) {
 				return createScope(scope, `${key}.`);
 			}
 			// 完全未命中：显式返回 undefined（noImplicitReturns）

package/client/plugins/i18n.ts

@@ -2,9 +2,17 @@
 // Copyright (c) 2019-present Shigma and Koishijs contributors.
 // Copyright (c) 2026-present Koishi-CE contributors.
 
+import { type Dict, valueMap } from "cosmokit";
 import { watchEffect } from "vue";
 import { createI18n } from "vue-i18n";
 import type { Context } from "../context";
+import deDE from "../locales/de-DE.yml";
+import enUS from "../locales/en-US.yml";
+import frFR from "../locales/fr-FR.yml";
+import jaJP from "../locales/ja-JP.yml";
+import ruRU from "../locales/ru-RU.yml";
+import zhCN from "../locales/zh-CN.yml";
+import zhTW from "../locales/zh-TW.yml";
 import { Service } from "../utils";
 import { useConfig } from "./setting";
 
@@ -14,22 +22,69 @@ declare module "../context" {
 	}
 }
 
-// 客户端本地配置（未与服务端同步前的原始值）
-const config = useConfig();
+/** 宿主自身的全局词典：随服务启动注入，键结构见 client/locales/zh-CN.yml */
+export const localeMessages: Dict<Dict> = {
+	"de-DE": deDE,
+	"en-US": enUS,
+	"fr-FR": frFR,
+	"ja-JP": jaJP,
+	"ru-RU": ruRU,
+	"zh-CN": zhCN,
+	"zh-TW": zhTW,
+};
+
+/**
+ * 从一组 `{ locale: 词典 }` 映射中按路径摘取各语种的同一子树，
+ * 构造 Schemastery `.i18n()` 的入参形态（`{ locale: 子树 }`）。
+ * 宿主与扩展的 schema 词典均可经此摘取；yaml 为动态数据，
+ * 收窄集中在这一处。
+ */
+export function pickFrom(
+	messages: Dict<unknown>,
+	...path: string[]
+): Dict {
+	return valueMap(messages, (data) => {
+		let node: unknown = data;
+		for (const key of path) {
+			node = (node as Dict<unknown> | undefined)?.[key];
+		}
+		return node;
+	});
+}
+
+/**
+ * 从宿主词典中按路径摘取各语种的同一子树（`pickFrom` 的宿主词典
+ * 专用便捷形式），叶节点上亦可取得 `Dict<string>`（const 选项的
+ * 显示名直接传 description）。
+ */
+export function pickMessages<T = unknown>(
+	...path: string[]
+): Dict<T> {
+	return pickFrom(localeMessages, ...path) as Dict<T>;
+}
 
 /**
  * 国际化服务：持有 vue-i18n 实例（默认回退语言 zh-CN），
  * 并监听本地配置中的 locale 变化实时切换界面语言。
- * 各扩展自身的语言包由 loader 加载时注入该实例。
+ *
+ * 宿主词典在实例创建时整体传入；各扩展自身的语言包由其 client
+ * 入口调用 `ctx.$i18n.extend()` 深合并注入（vue-i18n 已被构建别名
+ * 钉到宿主单实例，扩展与宿主共享同一 composer）。
  */
 export default class I18nService extends Service {
 	public i18n = createI18n({
 		legacy: false,
 		fallbackLocale: "zh-CN",
+		messages: localeMessages,
 	});
 
 	constructor(ctx: Context) {
 		super(ctx, "$i18n", true);
+		instance = this;
+
+		// 客户端本地配置（在构造期获取而非模块顶层，避免与
+		// setting.ts 的循环依赖在模块求值顺序上踩 TDZ）
+		const config = useConfig();
 
 		// flush: "post" 确保在语言切换引起重渲染前完成 locale 写入
 		ctx.effect(() =>
@@ -44,4 +99,64 @@ export default class I18nService extends Service {
 			),
 		);
 	}
+
+	/**
+	 * 注入扩展语言包：按 locale 深合并进全局词典。
+	 * 扩展应把自身的键收纳在独立命名空间（如 `explorer.*`）下，
+	 * 避免与其他扩展或宿主词典冲突。
+	 */
+	extend(locale: string, messages: Dict) {
+		this.i18n.global.mergeLocaleMessage(locale, messages);
+	}
+
+	/**
+	 * 全局翻译函数（非组件上下文使用，如 activity 名的 getter 与
+	 * echarts 等纯 ts 模块）。可携带位置插值参数。
+	 */
+	t(key: string, args?: unknown[]) {
+		return this.i18n.global.t(key, args ?? []);
+	}
+}
+
+// 服务实例的模块级引用：仅用于开发期 HMR 回调中定位热替换目标
+let instance: I18nService | undefined;
+
+// 开发模式下宿主词典 yml 改动即时热替换（accept 的路径须为静态字面量）；
+// 用 merge 而非 set，以免覆盖扩展此前经 extend() 注入的同语种词条
+if (import.meta.hot) {
+	const replace = (locale: string) => (module: unknown) => {
+		// 热替换模块的 default 导出即该语种的完整词典
+		const messages = (
+			module as { default?: Dict } | undefined
+		)?.default;
+		instance?.extend(locale, messages ?? {});
+	};
+	import.meta.hot.accept(
+		"../locales/de-DE.yml",
+		replace("de-DE"),
+	);
+	import.meta.hot.accept(
+		"../locales/en-US.yml",
+		replace("en-US"),
+	);
+	import.meta.hot.accept(
+		"../locales/fr-FR.yml",
+		replace("fr-FR"),
+	);
+	import.meta.hot.accept(
+		"../locales/ja-JP.yml",
+		replace("ja-JP"),
+	);
+	import.meta.hot.accept(
+		"../locales/ru-RU.yml",
+		replace("ru-RU"),
+	);
+	import.meta.hot.accept(
+		"../locales/zh-CN.yml",
+		replace("zh-CN"),
+	);
+	import.meta.hot.accept(
+		"../locales/zh-TW.yml",
+		replace("zh-TW"),
+	);
 }

package/client/plugins/loader.ts

@@ -29,12 +29,17 @@ export function defineExtension(callback: Extension) {
 
 /** 兼容 rollup 与 vite 两种产物：优先取 default 导出 */
 export function unwrapExports(module: unknown): Plugin {
-	const record = module as { default?: unknown } | null | undefined;
+	const record = module as
+		| { default?: unknown }
+		| null
+		| undefined;
 	return (record?.default || module) as Plugin;
 }
 
 /** 按文件后缀分发的加载器：样式表插入 <link>，其余按动态模块导入 */
-const loaders: Dict<(ctx: Context, url: string) => Promise<void>> = {
+const loaders: Dict<
+	(ctx: Context, url: string) => Promise<void>
+> = {
 	async [`.css`](ctx, url) {
 		const link = document.createElement("link");
 		link.rel = "stylesheet";
@@ -53,7 +58,10 @@ const loaders: Dict<(ctx: Context, url: string) => Promise<void>> = {
 	async [``](ctx, url) {
 		const exports = await import(/* @vite-ignore */ url);
 		// 扩展入口均为函数式插件；断言到 Function 形状以走 config 可选的重载
-		ctx.plugin(unwrapExports(exports) as Plugin.Function, ctx.extension?.data);
+		ctx.plugin(
+			unwrapExports(exports) as Plugin.Function,
+			ctx.extension?.data,
+		);
 	},
 };
 
@@ -77,20 +85,25 @@ export default class LoaderService extends Service {
 	private backendId: string | undefined;
 
 	/** 当前已加载扩展的 id → LoadResult 映射 */
-	public extensions: Dict<LoadResult> = shallowReactive({} as Dict<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;
-		});
+		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;
+			},
+		);
 	}
 
 	/**
@@ -102,10 +115,15 @@ export default class LoaderService extends Service {
 			() => store.entry,
 			async (newValue, oldValue) => {
 				// _id 标识后端实例：变化说明服务端已重启，页面状态不再可信
-				const { _id, ...rest } = (newValue || {}) as Dict<EntryData> & {
+				const { _id, ...rest } = (newValue ||
+					{}) as Dict<EntryData> & {
 					_id?: string | undefined;
 				};
-				if (this.backendId && _id && this.backendId !== _id) {
+				if (
+					this.backendId &&
+					_id &&
+					this.backendId !== _id
+				) {
 					window.location.reload();
 					return;
 				}
@@ -119,38 +137,42 @@ export default class LoaderService extends Service {
 				}
 
 				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；
-						// task 返回给外层 Promise.all，使 initTask 真正等到全部
-						// 入口文件 settle 后才放行（否则 router install 早于扩展
-						// 注册路由，初始导航会对当前路径报 no match）。
-						// 扩展加载失败不阻塞界面可用性
-						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;
-							}),
-						);
-						void task.finally(() => {
-							const extension = this.extensions[key];
-							if (extension) extension.done.value = true;
-						});
-						return task.catch(() => {});
-					}),
+					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；
+							// task 返回给外层 Promise.all，使 initTask 真正等到全部
+							// 入口文件 settle 后才放行（否则 router install 早于扩展
+							// 注册路由，初始导航会对当前路径报 no match）。
+							// 扩展加载失败不阻塞界面可用性
+							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;
+								}),
+							);
+							void task.finally(() => {
+								const extension = this.extensions[key];
+								if (extension) extension.done.value = true;
+							});
+							return task.catch(() => {});
+						},
+					),
 				);
 
 				// 首次加载完成（oldValue 为空）时放行 initTask