@yunzai-ng/core 0.1.0

package/dist/plugin/host.d.ts

@@ -0,0 +1,160 @@
+import type { AppView, CommandInfo, HttpClient, KvNamespace, Logger, MiddlewareInfo, PluginState, PluginsView, RuntimePaths, TaskInfo } from "@yunzai-ng/types";
+import type { ConfigStore } from "../config/store.js";
+import { type PluginContextHandle } from "./context.js";
+import { type SkippedPlugin } from "./discover.js";
+import type { CoreEventBus } from "./events.js";
+import type { KernelHooks } from "./hooks.js";
+import type { ServiceRegistry } from "./services.js";
+/** KV 命名空间的最小契约（只用到取子空间） */
+export interface KvNamespaceSource {
+    /**
+     * 取一个子命名空间
+     * @param name 命名空间名
+     * @returns KV 视图
+     */
+    namespace(name: string): KvNamespace;
+}
+/** 构造插件宿主所需的依赖 */
+export interface PluginHostDeps {
+    /** 目录布局 */
+    paths: RuntimePaths;
+    /** 根日志器（每个插件会派生 child） */
+    logger: Logger;
+    /** 配置仓库 */
+    config: ConfigStore;
+    /** KV 存储 */
+    kv: KvNamespaceSource;
+    /** HTTP 客户端 */
+    http: HttpClient;
+    /** 服务注册表 */
+    services: ServiceRegistry;
+    /** 内核事件总线 */
+    events: CoreEventBus;
+    /**
+     * 子系统接缝
+     *
+     * 内核可以**在插件加载之后**继续往这个对象里填真实实现（服务器通常最后才起），
+     * 上下文每次调用都是现取现用，所以替换会立即对已加载的插件生效。
+     */
+    hooks: KernelHooks;
+    /**
+     * 取应用视图
+     *
+     * 刻意是函数而不是值：`AppView.plugins` 正是本宿主提供的，宿主必须先存在。
+     * 加载插件时才调用，那时视图已装配完毕。
+     */
+    app: () => AppView;
+    /** 额外扫描的插件目录（绝对路径），排在默认目录之前 */
+    extraDirs?: string[];
+    /** 随发行版预置的插件目录（绝对路径） */
+    builtinDirs?: string[];
+    /** 用户禁用的插件名 */
+    disabled?: readonly string[];
+    /** setup 超时毫秒，缺省 30s */
+    setupTimeout?: number;
+}
+/** 加载一批插件后的汇总 */
+export interface LoadReport {
+    /** 成功加载的插件名 */
+    loaded: string[];
+    /** 失败或被跳过的插件 */
+    failed: SkippedPlugin[];
+    /** 总耗时毫秒 */
+    cost: number;
+}
+/**
+ * 插件宿主
+ *
+ * 线程模型：单线程；`loadAll` / `reload` / `unload` 之间用一条串行链互斥，
+ * 避免"WebUI 点重载"与"文件监听触发重载"同时进来把状态搅乱。
+ */
+export declare class PluginHost {
+    #private;
+    /**
+     * @param deps 依赖
+     */
+    constructor(deps: PluginHostDeps);
+    /** 已加载插件数 */
+    get size(): number;
+    /**
+     * 扫描并加载全部插件
+     * @returns 加载汇总
+     */
+    loadAll(): Promise<LoadReport>;
+    /**
+     * 卸载一个插件
+     * @param name 插件名
+     * @returns 是否确实卸载了（未加载时 false）
+     */
+    unload(name: string): Promise<boolean>;
+    /**
+     * 重载一个插件
+     *
+     * 会重新读磁盘上的代码。见文件头第 4 条：这在 Node 里必然泄漏一份旧模块，
+     * 仅供开发期使用。
+     * @param name 插件名
+     * @returns 是否成功
+     */
+    reload(name: string): Promise<boolean>;
+    /**
+     * 卸载全部插件
+     *
+     * 逆加载顺序卸载：先卸载依赖别人的，再卸载被依赖的。
+     * @returns 卸载的插件数
+     */
+    dispose(): Promise<number>;
+    /**
+     * 列出全部插件状态
+     * @returns 状态数组，按名字排序
+     */
+    list(): PluginState[];
+    /**
+     * 按名取插件状态
+     * @param name 插件名
+     * @returns 状态；未知插件时 undefined
+     */
+    get(name: string): PluginState | undefined;
+    /**
+     * 按名取插件的运行时上下文
+     *
+     * 供事件分发器使用：执行某个插件的命令处理函数时，`e.render()` 要用该插件的
+     * 模板根、`e.prompt()` 要用该插件的卸载信号。返回值刻意是完整的上下文而不是
+     * 另包一层窄接口 —— 分发器那边的参数类型（`PluginRuntimeView`）只取三个成员，
+     * 结构上天然满足，多定义一层适配器反而让"这两者必须对得上"变得不明显。
+     *
+     * 插件已卸载时返回 undefined：分发器据此把那条命令当作已失效跳过，
+     * 而不是拿着一个 signal 已 abort 的上下文继续跑。
+     * @param name 插件名
+     * @returns 上下文；未加载或已卸载时 undefined
+     */
+    runtime(name: string): PluginContextHandle["ctx"] | undefined;
+}
+/** 命令与任务的查询入口（由路由器与调度器提供） */
+export interface RegistryInspectors {
+    /**
+     * 列出全部命令
+     * @returns 命令描述数组
+     */
+    commands(): CommandInfo[];
+    /**
+     * 列出全部定时任务
+     * @returns 任务描述数组
+     */
+    tasks(): TaskInfo[];
+    /**
+     * 列出全部中间件，顺序即实际的执行顺序
+     * @returns 中间件描述数组
+     */
+    middlewares(): MiddlewareInfo[];
+}
+/**
+ * 组装 `AppView.plugins`
+ *
+ * 插件状态在宿主这里，命令与任务清单在路由器/调度器那里；视图把两边拼起来，
+ * 免得内核里到处传三个对象。
+ * @param host 插件宿主
+ * @param inspectors 命令与任务查询入口
+ * @returns 插件视图
+ */
+export declare function createPluginsView(host: PluginHost, inspectors: RegistryInspectors): PluginsView;
+//# sourceMappingURL=host.d.ts.map

package/dist/plugin/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/plugin/host.ts"],"names":[],"mappings":"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"}