@koishi-ce/plugin-config 1.0.0

package/src/node/packages.ts

@@ -0,0 +1,64 @@
+/**
+ * PackageProvider 的 Node 端实现：基于 LocalScanner 扫描本机
+ * node_modules 中的插件包，并在扫描过程中顺带解析已加载插件的
+ * 运行时信息写入共享 cache。
+ */
+import { Logger } from "@koishi-ce/koishi";
+import { LocalScanner } from "@koishi-ce/registry";
+import * as shared from "../shared/index.ts";
+
+const logger = new Logger("config");
+
+/**
+ * 本机插件扫描器：在 LocalScanner 的基础上扩展 parsePackage，
+ * 让"扫描到某个包"与"解析该插件的运行时信息"在同一次遍历中完成。
+ */
+class PackageScanner extends LocalScanner {
+	private service: PackageProvider;
+
+	constructor(service: PackageProvider) {
+		super(service.ctx.baseDir);
+		this.service = service;
+	}
+
+	/** 单个包解析失败时仅记录警告，不中断整体扫描。 */
+	override async onError(error: unknown, name: string) {
+		logger.warn("failed to resolve %c", name);
+		logger.warn(error);
+	}
+
+	/**
+	 * 解析包元数据后，若该插件的入口模块已被 require 进内存，
+	 * 则顺带解析其导出并写入服务缓存，供前端立即取用。
+	 */
+	override async parsePackage(name: string) {
+		const result = await super.parsePackage(name);
+		try {
+			// require.resolve(name) 的结果可能与 require.resolve(path) 不同,
+			// 因为 tsconfig-paths 可能以不同方式解析路径
+			const entry = require.resolve(name);
+			if (require.cache[entry]) {
+				name = name.replace(/(koishi-|^@koishijs\/)plugin-/, "");
+				this.service.cache[name] = await this.service.parseExports(name);
+			}
+		} catch (error) {
+			void this.onError(error, name);
+		}
+		return result;
+	}
+}
+
+/** Node 端包提供器：collect 委托给本机扫描器。 */
+export class PackageProvider extends shared.PackageProvider {
+	scanner = new PackageScanner(this);
+
+	/**
+	 * 扫描本机插件包并返回扫描结果。
+	 *
+	 * @param forced 为 true 时强制重新扫描（不走缓存）
+	 */
+	async collect(forced: boolean) {
+		await this.scanner.collect(forced);
+		return this.scanner.objects;
+	}
+}

package/src/shared/index.ts

@@ -0,0 +1,25 @@
+/**
+ * 服务端共享代码的汇总出口。
+ *
+ * 一方面把 packages / services / writer 三个模块统一 re-export 给
+ * node 与 browser 两个入口使用；另一方面通过声明合并把三个数据服务
+ * 注册进 console 的 Services 接口，使浏览器端能以类型安全的方式
+ * 访问 `store.packages`、`store.services`、`store.config`。
+ */
+import type { PackageProvider } from "./packages.ts";
+import type { ServiceProvider } from "./services.ts";
+import type { ConfigWriter } from "./writer.ts";
+
+declare module "@koishi-ce/console" {
+	namespace Console {
+		interface Services {
+			packages: PackageProvider;
+			services: ServiceProvider;
+			config: ConfigWriter;
+		}
+	}
+}
+
+export * from "./packages.ts";
+export * from "./services.ts";
+export * from "./writer.ts";

package/src/shared/packages.ts

@@ -0,0 +1,245 @@
+/**
+ * 插件包元数据提供器（服务端共享实现）。
+ *
+ * 以 `packages` 数据服务的形式向浏览器端提供本机可用的插件包列表及
+ * 各自的运行时信息（Config schema、用法文档、注入的服务依赖、fork
+ * 状态等）。运行时信息通过解析插件模块的导出（parseExports）获得并
+ * 缓存在 cache 中，监听 runtime/fork/status 等内部事件按需刷新。
+ *
+ * 抽象类只定义"运行时信息"这一半；列表如何收集（本机扫描还是市场
+ * 数据）分别由 node / browser 两个运行环境的子类实现。
+ */
+import { DataService } from "@koishi-ce/console";
+import {
+	Context,
+	type Dict,
+	Logger,
+	type MainScope,
+	type Plugin,
+	type Schema,
+	type ScopeStatus,
+} from "@koishi-ce/koishi";
+import type { LoaderScope } from "@koishi-ce/loader";
+import type {} from "@koishi-ce/plugin-hmr";
+import type {
+	PackageJson,
+	SearchObject,
+	SearchResult,
+} from "@koishi-ce/registry";
+
+declare module "@koishi-ce/loader" {
+	interface Loader {
+		market: SearchResult;
+	}
+}
+
+declare module "@koishi-ce/console" {
+	interface Events {
+		"config/request-runtime"(name: string): void;
+	}
+}
+
+const logger = new Logger("config");
+
+export abstract class PackageProvider extends DataService<
+	Dict<PackageProvider.Data>
+> {
+	cache: Dict<PackageProvider.RuntimeData> = {};
+	debouncedRefresh: () => void;
+
+	override ctx: Context;
+
+	/**
+	 * @param ctx 应用上下文
+	 */
+	constructor(ctx: Context) {
+		super(ctx, "packages", { authority: 4 });
+		this.ctx = ctx;
+
+		this.debouncedRefresh = ctx.debounce(() => this.refresh(false), 0);
+		// 插件的加载 / fork / 状态变化都可能影响运行时信息，统一走 update
+		ctx.on("internal/runtime", (scope) => this.update(scope.runtime.plugin));
+		ctx.on("internal/fork", (scope) => this.update(scope.runtime.plugin));
+		ctx.on("internal/status", (scope) => this.update(scope.runtime.plugin));
+		ctx.on("hmr/reload", (reloads) => {
+			for (const [plugin] of reloads) {
+				this.update(plugin);
+			}
+		});
+
+		// 前端按需请求：某插件缺少运行时信息时（如刚安装尚未解析），
+		// 按短名解析其导出并立即推送
+		ctx.console.addListener(
+			"config/request-runtime",
+			async (name) => {
+				name = name.replace(/(koishi-|^@koishijs\/)plugin-/, "");
+				this.cache[name] = await this.parseExports(name);
+				this.refresh(false);
+			},
+			{ authority: 4 },
+		);
+	}
+
+	/**
+	 * 收集插件包列表。由运行环境子类实现：node 端本机扫描 node_modules，
+	 * browser 端复用 loader 缓存的市场搜索结果。
+	 *
+	 * @param forced 是否强制重新收集（绕过缓存）
+	 */
+	abstract collect(forced: boolean): Promise<PackageProvider.Data[]>;
+
+	/**
+	 * 某插件的运行时状态发生变化时，重新解析其导出并去抖刷新服务。
+	 *
+	 * @param plugin 发生变化的插件对象
+	 */
+	async update(plugin: Plugin) {
+		const name = this.ctx.loader.keyFor(plugin);
+		if (!name || !this.cache[name]) return;
+		this.cache[name] = await this.parseExports(name);
+		this.debouncedRefresh();
+	}
+
+	/**
+	 * 从插件主作用域提取 fork 运行状态，写入 result 的 id/forkable/forks 字段。
+	 *
+	 * @param state 插件的主作用域
+	 * @param result 待填充的运行时数据（原地修改）
+	 */
+	parseRuntime(state: MainScope, result: PackageProvider.RuntimeData) {
+		// 已销毁的 runtime(uid 为 null)不展示 id
+		if (state.runtime.uid !== null) {
+			result.id = state.runtime.uid;
+		}
+		result.forkable = state.runtime.isForkable;
+		// fork 的 key 由 loader 写入(cordis 的 ForkScope 类型上没有该属性)
+		const forks: Dict<{ status?: ScopeStatus }> = {};
+		for (const fork of state.children) {
+			const key = (fork as LoaderScope).key;
+			if (!key) continue;
+			forks[key] = { status: fork.status };
+		}
+		result.forks = forks;
+	}
+
+	/**
+	 * 数据服务读取入口：收集包列表，合并缓存的运行时信息，
+	 * 并在最前面附加一个 name 为空串的"应用全局设置"条目。
+	 */
+	override async get(forced = false) {
+		const objects = (await this.collect(forced)).slice();
+		for (const object of objects) {
+			object.name = object.package?.name || "";
+			const cached = this.cache[object.shortname];
+			if (!cached) continue;
+			object.runtime = cached;
+		}
+
+		// 附加应用全局设置（使用 Context.Config 作为 schema，name 为空串）
+		objects.unshift({
+			name: "",
+			runtime: {
+				schema: Context.Config,
+			},
+			package: { name: "" },
+			// 全局设置条目不带市场元数据字段，用双断言放宽必填约束
+		} as unknown as PackageProvider.Data);
+		return Object.fromEntries(objects.map((data) => [data.name, data]));
+	}
+
+	/**
+	 * 解析插件模块的导出，提取配置 schema、用法文档、过滤器开关与
+	 * 注入的服务依赖（required / optional），并附带运行时 fork 状态。
+	 * 解析失败时返回 `{ failed: true }` 而不是抛错。
+	 *
+	 * @param name 插件短名（不含 koishi-plugin- 前缀）
+	 * @returns 可序列化的运行时数据
+	 */
+	async parseExports(name: string) {
+		try {
+			// 插件本体之外的附加导出（配置面板消费的元信息）
+			type Extras = {
+				Config?: Schema;
+				schema?: Schema;
+				usage?: string;
+				filter?: boolean;
+				using?: string[] | { required?: string[]; optional?: string[] };
+				inject?: string[] | { required?: string[]; optional?: string[] };
+			};
+			const exports = (await this.ctx.loader.resolve(name)) as
+				| (Plugin & Extras)
+				| undefined;
+			const result: PackageProvider.RuntimeData = {};
+			const schema = exports?.Config || exports?.schema;
+			if (schema) result.schema = schema;
+			if (exports?.usage) result.usage = exports.usage;
+			if (exports?.filter !== undefined) result.filter = exports.filter;
+			// using 与 inject 是新旧两种声明注入服务的方式
+			const inject = exports?.using || exports?.inject || [];
+			if (Array.isArray(inject)) {
+				result.required = inject;
+				result.optional = [];
+			} else {
+				result.required = inject.required || [];
+				result.optional = inject.optional || [];
+			}
+
+			// 确保 result 可以被 JSON 序列化（schema 中可能混入不可序列化的值）
+			JSON.stringify(result);
+
+			const runtime = exports ? this.ctx.registry.get(exports) : undefined;
+			if (runtime) this.parseRuntime(runtime, result);
+			return result;
+		} catch (error) {
+			logger.warn("failed to load %c", name);
+			logger.warn(error);
+			return { failed: true };
+		}
+	}
+}
+
+/** PackageProvider 相关的数据类型定义。 */
+export namespace PackageProvider {
+	/**
+	 * 下发给前端的插件包条目：市场/本机元数据 + 运行时信息。
+	 * name 为空串的条目特指应用全局设置。
+	 */
+	export interface Data
+		extends Pick<
+			SearchObject,
+			"shortname" | "workspace" | "manifest" | "portable"
+		> {
+		/** 完整包名 */
+		name?: string;
+		/** 运行时信息（schema、依赖、fork 状态等） */
+		runtime?: RuntimeData;
+		package: Pick<
+			PackageJson,
+			"name" | "version" | "peerDependencies" | "peerDependenciesMeta"
+		>;
+	}
+
+	/** 从插件模块导出解析出的运行时数据。 */
+	export interface RuntimeData {
+		/** 插件主作用域 uid（未加载时缺失） */
+		id?: number;
+		/** 是否暴露 filter（过滤器设置） */
+		filter?: boolean;
+		/** 是否可重用（允许同时存在多份配置） */
+		forkable?: boolean;
+		/** 插件的配置 schema */
+		schema?: Schema;
+		/** 用法说明（Markdown 文档） */
+		usage?: string;
+		/** 必需注入的服务列表 */
+		required?: string[];
+		/** 可选注入的服务列表 */
+		optional?: string[];
+		/** 模块解析失败标记 */
+		failed?: boolean;
+		/** 各 fork 配置的运行状态，键为配置路径 */
+		forks?: Dict<{
+			status?: ScopeStatus;
+		}>;
+	}
+}

package/src/shared/services.ts

@@ -0,0 +1,51 @@
+/**
+ * 服务状态提供器：以 `services` 数据服务的形式向浏览器端上报当前
+ * 应用中每个已注册服务的提供者信息（服务名 → 提供该服务的上下文 uid）。
+ * 前端据此判断某插件"必需/可选注入的服务"是否已可用。
+ *
+ * 遍历方式：从根上下文的 internal 对象出发沿原型链逐层收集类型为
+ * "service" 的属性，再通过 Context.current 访问器反查服务实例所属的
+ * 上下文，取其作用域 uid。
+ */
+import { DataService } from "@koishi-ce/console";
+import { Context, type Dict } from "@koishi-ce/koishi";
+
+export class ServiceProvider extends DataService<Dict<number>> {
+	constructor(ctx: Context) {
+		super(ctx, "services");
+		// 任何服务的注册 / 注销都会改变统计结果
+		ctx.on("internal/service", () => this.refresh());
+	}
+
+	override async get() {
+		const services = {} as Dict<number>;
+		/**
+		 * 递归遍历 internal 对象的原型链，收集所有服务属性。
+		 *
+		 * @param internal 当前层级的 internal 对象
+		 */
+		const attach = (internal: Context[typeof Context.internal]) => {
+			if (!internal) return;
+			attach(Object.getPrototypeOf(internal));
+			for (const [key, { type }] of Object.entries(internal)) {
+				if (type !== "service") continue;
+				const instance = this.ctx.get(key);
+				if (!(instance instanceof Object)) continue;
+				// Context.current 是个访问器属性，其值即服务实例所属的上下文
+				const ctx: Context = Reflect.getOwnPropertyDescriptor(
+					instance,
+					Context.current,
+				)?.value;
+				if (!ctx) continue;
+				// 服务内部名形如 __foo__，对外展示时去掉首尾下划线
+				const name = key.replace(/^__/, "").replace(/__$/, "");
+				// 已销毁的 scope(uid 为 null)不参与统计
+				if (ctx.scope.uid !== null) {
+					services[name] = ctx.scope.uid;
+				}
+			}
+		};
+		attach(this.ctx.root[Context.internal]);
+		return services;
+	}
+}