@zhin.js/core 1.0.25 → 1.0.26

package/lib/built/database.js

@@ -1,28 +1,99 @@
+/**
+ * DatabaseFeature
+ * 数据库服务，管理数据模型定义，继承自 Feature 抽象类
+ */
 import { Registry } from "@zhin.js/database";
-import { defineContext } from "../plugin.js";
+import { Feature } from "../feature.js";
+import { getPlugin } from "../plugin.js";
 import { SystemLogDefinition } from "../models/system-log.js";
 import { UserDefinition } from "../models/user.js";
-export function defineDatabaseService(config) {
-    const db = Registry.create(config.dialect, config, {
-        SystemLog: SystemLogDefinition,
-        User: UserDefinition,
-    });
-    return defineContext({
-        name: 'database',
-        description: '数据库服务',
-        mounted: async (plugin) => {
-            plugin.logger.info(`Database service started`);
-            await db.start();
-            return db;
-        },
-        dispose: async () => {
-            await db.stop();
-        },
-        extensions: {
+export class DatabaseFeature extends Feature {
+    name = 'database';
+    icon = 'Database';
+    desc = '数据模型';
+    /** 内部数据库实例 */
+    db;
+    /** 按模型名索引 */
+    byName = new Map();
+    constructor(config) {
+        super();
+        this.db = Registry.create(config.dialect, config, {
+            SystemLog: SystemLogDefinition,
+            User: UserDefinition,
+        });
+    }
+    // ====================================================================
+    // 向后兼容代理：旧代码 inject('database').xxx 可直接使用
+    // ====================================================================
+    get models() {
+        return this.db.models;
+    }
+    define(name, definition) {
+        return this.db.define(name, definition);
+    }
+    start() {
+        return this.db.start();
+    }
+    stop() {
+        return this.db.stop();
+    }
+    /**
+     * 添加模型定义
+     */
+    add(record, pluginName) {
+        this.db.define(record.name, record.definition);
+        this.byName.set(record.name, record);
+        return super.add(record, pluginName);
+    }
+    /**
+     * 移除模型定义
+     */
+    remove(record) {
+        this.byName.delete(record.name);
+        return super.remove(record);
+    }
+    /**
+     * 生命周期: 启动数据库
+     */
+    async mounted(plugin) {
+        plugin.logger.info('Database service started');
+        await this.db.start();
+    }
+    /**
+     * 生命周期: 停止数据库
+     */
+    async dispose() {
+        await this.db.stop();
+    }
+    /**
+     * 序列化为 JSON
+     */
+    toJSON(pluginName) {
+        const list = pluginName ? this.getByPlugin(pluginName) : this.items;
+        return {
+            name: this.name,
+            icon: this.icon,
+            desc: this.desc,
+            count: list.length,
+            items: list.map(r => ({
+                name: r.name,
+            })),
+        };
+    }
+    /**
+     * 提供给 Plugin.prototype 的扩展方法
+     */
+    get extensions() {
+        const feature = this;
+        return {
             defineModel(name, definition) {
-                db.define(name, definition);
-            }
-        },
-    });
+                const plugin = getPlugin();
+                const record = { name: name, definition };
+                const dispose = feature.add(record, plugin.name);
+                plugin.recordFeatureContribution(feature.name, name);
+                plugin.onDispose(dispose);
+            },
+        };
+    }
 }
 //# sourceMappingURL=database.js.map

package/lib/built/database.js.map

@@ -1 +1 @@
-{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/built/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAgC,MAAM,mBAAmB,CAAC;AAE3E,OAAO,EAAE,aAAa,EAAS,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAWnD,MAAM,UAAU,qBAAqB,CAA4B,MAAyB;IACtF,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAW,MAAM,CAAC,OAAO,EAAE,MAAM,EAAC;QACxD,SAAS,EAAE,mBAAmB;QAC9B,IAAI,EAAE,cAAc;KACvB,CAAC,CAAC;IACH,OAAO,aAAa,CAAC;QACjB,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,OAAO;QACpB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;YACtB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;YAC/C,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,EAAE,CAAC;QACd,CAAC;QACD,OAAO,EAAE,KAAK,IAAI,EAAE;YAChB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;QACD,UAAU,EAAE;YACR,WAAW,CAAqC,IAAO,EAAE,UAAiC;gBACtF,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YAChC,CAAC;SACJ;KACJ,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/built/database.ts"],"names":[],"mappings":"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"}

package/lib/built/dispatcher.d.ts

@@ -0,0 +1,118 @@
+/**
+ * MessageDispatcher — 消息调度器
+ *
+ * 取代原先的"大杂烩中间件链"，将消息处理分为三个清晰阶段：
+ *
+ *   ┌────────────────────────────────────────┐
+ *   │  Stage 1: Guardrail（护栏）             │
+ *   │  鉴权、限流、安全过滤、日志记录          │
+ *   │  始终执行，不可被 AI 跳过                │
+ *   └──────────────┬─────────────────────────┘
+ *                  ▼
+ *   ┌────────────────────────────────────────┐
+ *   │  Stage 2: Route（路径判定）             │
+ *   │  精确命令 → Command 快速路径            │
+ *   │  其它消息 → AI Agent 路径               │
+ *   └──────────────┬─────────────────────────┘
+ *                  ▼
+ *   ┌────────────────────────────────────────┐
+ *   │  Stage 3: Handle（处理）                │
+ *   │  Command: commandService.handle()      │
+ *   │  AI: aiHandler (由 AI 模块注册)         │
+ *   └────────────────────────────────────────┘
+ *
+ * 注意：Context key 为 'dispatcher'，避免与 HTTP 模块的 'router' 冲突。
+ */
+import { Message } from '../message.js';
+import type { MessageMiddleware, RegisteredAdapter, MaybePromise } from '../types.js';
+import type { Context } from '../plugin.js';
+/**
+ * 路由判定结果
+ */
+export type RouteResult = {
+    type: 'command';
+} | {
+    type: 'ai';
+    content: string;
+} | {
+    type: 'skip';
+};
+/**
+ * AI 处理函数签名
+ * 由 AI 模块通过 dispatcher.setAIHandler() 注册
+ */
+export type AIHandler = (message: Message<any>, content: string) => MaybePromise<void>;
+/**
+ * 命令前缀判定函数
+ * 返回 true 表示该消息是精确命令调用
+ */
+export type CommandMatcher = (text: string, message: Message<any>) => boolean;
+/**
+ * AI 触发判定函数
+ * 返回 { triggered, content } 表示是否应该触发 AI 以及提取的内容
+ */
+export type AITriggerMatcher = (message: Message<any>) => {
+    triggered: boolean;
+    content: string;
+};
+/**
+ * Guardrail 中间件
+ * 与 MessageMiddleware 签名一致，但语义上只用于鉴权/限流/安全/日志
+ * 返回 false 或抛异常表示拦截消息
+ */
+export type GuardrailMiddleware = MessageMiddleware<RegisteredAdapter>;
+/**
+ * MessageDispatcher 服务接口
+ */
+export interface MessageDispatcherService {
+    /**
+     * 调度一条消息 — 这是唯一的入口
+     * Adapter 的 message.receive 事件应该调用此方法
+     */
+    dispatch(message: Message<any>): Promise<void>;
+    /**
+     * 注册 Guardrail（护栏中间件）
+     * Guardrail 始终执行，用于鉴权、限流、安全过滤、日志等
+     * @returns 移除函数
+     */
+    addGuardrail(guardrail: GuardrailMiddleware): () => void;
+    /**
+     * 设置命令匹配器
+     * 用于判定消息是否为精确命令调用
+     * 默认：检查消息是否以已注册命令的 pattern 开头
+     */
+    setCommandMatcher(matcher: CommandMatcher): void;
+    /**
+     * 设置 AI 触发判定器
+     * 用于判定消息是否应该触发 AI 处理
+     * 由 AI 模块注册
+     */
+    setAITriggerMatcher(matcher: AITriggerMatcher): void;
+    /**
+     * 注册 AI 处理函数
+     * 由 AI 模块注册，当消息路由到 AI 路径时调用
+     */
+    setAIHandler(handler: AIHandler): void;
+    /**
+     * 获取当前是否已注册 AI 处理能力
+     */
+    hasAIHandler(): boolean;
+}
+export interface DispatcherContextExtensions {
+    /** 注册 Guardrail（护栏中间件） */
+    addGuardrail(guardrail: GuardrailMiddleware): () => void;
+}
+declare module '../plugin.js' {
+    namespace Plugin {
+        interface Extensions extends DispatcherContextExtensions {
+        }
+        interface Contexts {
+            dispatcher: MessageDispatcherService;
+        }
+    }
+}
+/**
+ * 创建 MessageDispatcher Context
+ */
+export declare function createMessageDispatcher(): Context<'dispatcher', DispatcherContextExtensions>;
+//# sourceMappingURL=dispatcher.d.ts.map

package/lib/built/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/built/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EAEjB,YAAY,EAGb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAM5C;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EACrB,OAAO,EAAE,MAAM,KACZ,YAAY,CAAC,IAAI,CAAC,CAAC;AAExB;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC;AAE9E;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;AAMvE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAAC;IAEzD;;;;OAIG;IACH,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAEjD;;;;OAIG;IACH,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAErD;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAEvC;;OAEG;IACH,YAAY,IAAI,OAAO,CAAC;CACzB;AAMD,MAAM,WAAW,2BAA2B;IAC1C,0BAA0B;IAC1B,YAAY,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAAC;CAC1D;AAED,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,MAAM,CAAC;QACf,UAAU,UAAW,SAAQ,2BAA2B;SAAG;QAC3D,UAAU,QAAQ;YAChB,UAAU,EAAE,wBAAwB,CAAC;SACtC;KACF;CACF;AAMD;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAAC,YAAY,EAAE,2BAA2B,CAAC,CAqL5F"}

package/lib/built/dispatcher.js

@@ -0,0 +1,196 @@
+/**
+ * MessageDispatcher — 消息调度器
+ *
+ * 取代原先的"大杂烩中间件链"，将消息处理分为三个清晰阶段：
+ *
+ *   ┌────────────────────────────────────────┐
+ *   │  Stage 1: Guardrail（护栏）             │
+ *   │  鉴权、限流、安全过滤、日志记录          │
+ *   │  始终执行，不可被 AI 跳过                │
+ *   └──────────────┬─────────────────────────┘
+ *                  ▼
+ *   ┌────────────────────────────────────────┐
+ *   │  Stage 2: Route（路径判定）             │
+ *   │  精确命令 → Command 快速路径            │
+ *   │  其它消息 → AI Agent 路径               │
+ *   └──────────────┬─────────────────────────┘
+ *                  ▼
+ *   ┌────────────────────────────────────────┐
+ *   │  Stage 3: Handle（处理）                │
+ *   │  Command: commandService.handle()      │
+ *   │  AI: aiHandler (由 AI 模块注册)         │
+ *   └────────────────────────────────────────┘
+ *
+ * 注意：Context key 为 'dispatcher'，避免与 HTTP 模块的 'router' 冲突。
+ */
+import { getPlugin } from '../plugin.js';
+// ============================================================================
+// 实现
+// ============================================================================
+/**
+ * 创建 MessageDispatcher Context
+ */
+export function createMessageDispatcher() {
+    // 护栏中间件列表
+    const guardrails = [];
+    // AI 处理函数（由 AI 模块注册）
+    let aiHandler = null;
+    // AI 触发判定器（由 AI 模块注册）
+    let aiTriggerMatcher = null;
+    // 命令匹配器（默认由 command service 驱动）
+    let commandMatcher = null;
+    // 根插件引用（mounted 时设置）
+    let rootPlugin = null;
+    /**
+     * 执行 Guardrail 管道
+     * 返回 true 表示消息通过，false 表示被拦截
+     */
+    async function runGuardrails(message) {
+        if (guardrails.length === 0)
+            return true;
+        let passed = true;
+        let index = 0;
+        const runNext = async () => {
+            if (index >= guardrails.length)
+                return;
+            const guardrail = guardrails[index++];
+            try {
+                await guardrail(message, runNext);
+            }
+            catch {
+                // Guardrail 抛异常 → 拦截消息
+                passed = false;
+            }
+        };
+        await runNext();
+        return passed;
+    }
+    /**
+     * 路由判定：这条消息该走哪条路径？
+     */
+    function route(message) {
+        // 提取文本内容
+        const text = extractText(message);
+        // 1. 如果有自定义命令匹配器，优先使用
+        if (commandMatcher && commandMatcher(text, message)) {
+            return { type: 'command' };
+        }
+        // 2. 默认命令匹配：检查 commandService
+        if (rootPlugin) {
+            const commandService = rootPlugin.inject('command');
+            if (commandService?.items) {
+                for (const cmd of commandService.items) {
+                    const pattern = cmd.pattern?.split(/\s/)[0];
+                    if (pattern && text.startsWith(pattern)) {
+                        return { type: 'command' };
+                    }
+                }
+            }
+        }
+        // 3. AI 触发判定
+        if (aiTriggerMatcher) {
+            const { triggered, content } = aiTriggerMatcher(message);
+            if (triggered) {
+                return { type: 'ai', content };
+            }
+        }
+        // 4. 都不匹配 → 跳过
+        return { type: 'skip' };
+    }
+    /**
+     * 提取消息文本（简单实现，与 ai-trigger 中的 extractTextContent 对齐）
+     */
+    function extractText(message) {
+        if (!message.$content)
+            return '';
+        return message.$content
+            .map((seg) => {
+            if (typeof seg === 'string')
+                return seg;
+            if (seg.type === 'text')
+                return seg.data?.text || '';
+            return '';
+        })
+            .join('')
+            .trim();
+    }
+    // ─── 服务实例 ───────────────────────────────────────────────────────────
+    const service = {
+        async dispatch(message) {
+            // Stage 1: Guardrail
+            const passed = await runGuardrails(message);
+            if (!passed)
+                return;
+            // Stage 2: Route
+            const result = route(message);
+            // Stage 3: Handle
+            switch (result.type) {
+                case 'command': {
+                    // 命令快速路径 — 直接委托给 commandService
+                    if (rootPlugin) {
+                        const commandService = rootPlugin.inject('command');
+                        if (commandService) {
+                            const response = await commandService.handle(message, rootPlugin);
+                            if (response) {
+                                await message.$reply(response);
+                            }
+                        }
+                    }
+                    break;
+                }
+                case 'ai': {
+                    // AI Agent 路径
+                    if (aiHandler) {
+                        await aiHandler(message, result.content);
+                    }
+                    break;
+                }
+                case 'skip':
+                default:
+                    // 不处理
+                    break;
+            }
+            // 兼容：仍然执行旧的中间件链（除了默认的命令中间件和 AI 触发中间件）
+            // 这样既有 Guardrail/Dispatcher 新逻辑，又不会丢失已有的自定义中间件
+            // Phase 1 阶段先保持兼容，后续逐步迁移
+        },
+        addGuardrail(guardrail) {
+            guardrails.push(guardrail);
+            return () => {
+                const index = guardrails.indexOf(guardrail);
+                if (index !== -1)
+                    guardrails.splice(index, 1);
+            };
+        },
+        setCommandMatcher(matcher) {
+            commandMatcher = matcher;
+        },
+        setAITriggerMatcher(matcher) {
+            aiTriggerMatcher = matcher;
+        },
+        setAIHandler(handler) {
+            aiHandler = handler;
+        },
+        hasAIHandler() {
+            return aiHandler !== null;
+        },
+    };
+    return {
+        name: 'dispatcher',
+        description: '消息调度器 — 统一消息路由分流 (Command / AI)',
+        value: service,
+        mounted(plugin) {
+            rootPlugin = plugin.root;
+            return service;
+        },
+        extensions: {
+            addGuardrail(guardrail) {
+                const plugin = getPlugin();
+                const dispose = service.addGuardrail(guardrail);
+                plugin.onDispose(dispose);
+                return dispose;
+            },
+        },
+    };
+}
+//# sourceMappingURL=dispatcher.js.map

package/lib/built/dispatcher.js.map

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

package/lib/built/permission.d.ts

@@ -1,15 +1,55 @@
-import { MaybePromise, RegisteredAdapter, Message, AdapterMessage } from "@zhin.js/core";
+/**
+ * PermissionFeature
+ * 权限管理服务，继承自 Feature 抽象类
+ */
+import { Feature, FeatureJSON } from "../feature.js";
+import type { MaybePromise, RegisteredAdapter, AdapterMessage } from "../types.js";
+import { Message as MessageClass } from "../message.js";
 export type PermissionItem<T extends RegisteredAdapter = RegisteredAdapter> = {
     name: string | RegExp;
     check: PermissionChecker<T>;
 };
-export type PermissionChecker<T extends RegisteredAdapter = RegisteredAdapter> = (name: string, message: Message<AdapterMessage<T>>) => MaybePromise<boolean>;
-export declare class PermissionService extends Array<PermissionItem> {
+export type PermissionChecker<T extends RegisteredAdapter = RegisteredAdapter> = (name: string, message: MessageClass<AdapterMessage<T>>) => MaybePromise<boolean>;
+/**
+ * PermissionFeature 扩展方法类型
+ */
+export interface PermissionContextExtensions {
+    addPermission(permission: PermissionItem): () => void;
+}
+declare module "../plugin.js" {
+    namespace Plugin {
+        interface Extensions extends PermissionContextExtensions {
+        }
+        interface Contexts {
+            permission: PermissionFeature;
+        }
+    }
+}
+export declare class PermissionFeature extends Feature<PermissionItem> {
+    readonly name: "permission";
+    readonly icon = "Shield";
+    readonly desc = "\u6743\u9650";
     constructor();
-    add(permission: PermissionItem): void;
-    check(name: string, message: Message<AdapterMessage<RegisteredAdapter>>): Promise<boolean>;
+    /**
+     * 检查权限
+     */
+    check(name: string, message: MessageClass<AdapterMessage<RegisteredAdapter>>): Promise<boolean>;
+    /**
+     * 序列化为 JSON
+     */
+    toJSON(pluginName?: string): FeatureJSON;
+    /**
+     * 提供给 Plugin.prototype 的扩展方法
+     */
+    get extensions(): {
+        addPermission(permission: PermissionItem): () => void;
+    };
 }
 export declare namespace Permissions {
     function define<T extends RegisteredAdapter = RegisteredAdapter>(name: string | RegExp, check: PermissionChecker<T>): PermissionItem<T>;
 }
+/**
+ * @deprecated Use PermissionFeature instead
+ */
+export declare const PermissionService: typeof PermissionFeature;
 //# sourceMappingURL=permission.d.ts.map

package/lib/built/permission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../../src/built/permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACzF,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,IAAI;IAC1E,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IACrB,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAA;CAC9B,CAAA;AACD,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,KAAK,YAAY,CAAC,OAAO,CAAC,CAAA;AAC7J,qBAAa,iBAAkB,SAAQ,KAAK,CAAC,cAAc,CAAC;;IAqCxD,GAAG,CAAC,UAAU,EAAE,cAAc;IAGxB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC,GAAE,OAAO,CAAC,OAAO,CAAC;CAOlG;AACD,yBAAiB,WAAW,CAAA;IACxB,SAAgB,MAAM,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAE7I;CACJ"}
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../../src/built/permission.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,eAAe,CAAC;AAExD,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,IAAI;IAC5E,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,IAAI,CAC/E,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,KACrC,YAAY,CAAC,OAAO,CAAC,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,aAAa,CAAC,UAAU,EAAE,cAAc,GAAG,MAAM,IAAI,CAAC;CACvD;AAED,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,MAAM,CAAC;QACf,UAAU,UAAW,SAAQ,2BAA2B;SAAG;QAC3D,UAAU,QAAQ;YAChB,UAAU,EAAE,iBAAiB,CAAC;SAC/B;KACF;CACF;AAED,qBAAa,iBAAkB,SAAQ,OAAO,CAAC,cAAc,CAAC;IAC5D,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IACtC,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,IAAI,kBAAQ;;IAuDrB;;OAEG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAQrG;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,WAAW;IAaxC;;OAEG;IACH,IAAI,UAAU;kCAGgB,cAAc;MAS3C;CACF;AAED,yBAAiB,WAAW,CAAC;IAC3B,SAAgB,MAAM,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,EACpE,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,CAAC,CAAC,CAEnB;CACF;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,0BAAoB,CAAC"}

package/lib/built/permission.js

@@ -1,9 +1,19 @@
-export class PermissionService extends Array {
+/**
+ * PermissionFeature
+ * 权限管理服务，继承自 Feature 抽象类
+ */
+import { Feature } from "../feature.js";
+import { getPlugin } from "../plugin.js";
+export class PermissionFeature extends Feature {
+    name = 'permission';
+    icon = 'Shield';
+    desc = '权限';
     constructor() {
         super();
+        // 注册默认权限检查器（使用 'built-in' 作为插件名）
         this.add(Permissions.define(/^adapter\([^)]+\)$/, (name, message) => {
             return message.$adapter === name.replace(/^adapter\(([^)]+)\)$/, '$1');
-        }));
+        }), '__built-in__');
         this.add(Permissions.define(/^group\([^)]+\)$/, (name, message) => {
             const match = name.match(/^group\(([^)]+)\)$/);
             if (!match)
@@ -14,7 +24,7 @@ export class PermissionService extends Array {
             if (id === '' || id === '*')
                 return true;
             return message.$channel.id === id;
-        }));
+        }), '__built-in__');
         this.add(Permissions.define(/^private\([^)]+\)$/, (name, message) => {
             const match = name.match(/^private\(([^)]+)\)$/);
             if (!match)
@@ -25,7 +35,7 @@ export class PermissionService extends Array {
             if (id === '' || id === '*')
                 return true;
             return message.$channel.id === id;
-        }));
+        }), '__built-in__');
         this.add(Permissions.define(/^channel\([^)]+\)$/, (name, message) => {
             const match = name.match(/^channel\(([^)]+)\)$/);
             if (!match)
@@ -36,26 +46,57 @@ export class PermissionService extends Array {
             if (id === '' || id === '*')
                 return true;
             return message.$channel.id === id;
-        }));
+        }), '__built-in__');
         this.add(Permissions.define(/^user\([^)]+\)$/, (name, message) => {
-            const match = name.match(/^channel\(([^)]+)\)$/);
+            const match = name.match(/^user\(([^)]+)\)$/);
             if (!match)
                 return false;
             const id = match[1];
             return message.$sender.id === id;
-        }));
-    }
-    add(permission) {
-        this.push(permission);
+        }), '__built-in__');
     }
+    /**
+     * 检查权限
+     */
     async check(name, message) {
-        for (const permission of this) {
+        for (const permission of this.items) {
             const passed = await permission.check(name, message);
             if (passed)
                 return true;
         }
         return false;
     }
+    /**
+     * 序列化为 JSON
+     */
+    toJSON(pluginName) {
+        const list = pluginName ? this.getByPlugin(pluginName) : this.items;
+        return {
+            name: this.name,
+            icon: this.icon,
+            desc: this.desc,
+            count: list.length,
+            items: list.map(p => ({
+                name: p.name instanceof RegExp ? p.name.source : p.name,
+            })),
+        };
+    }
+    /**
+     * 提供给 Plugin.prototype 的扩展方法
+     */
+    get extensions() {
+        const feature = this;
+        return {
+            addPermission(permission) {
+                const plugin = getPlugin();
+                const dispose = feature.add(permission, plugin.name);
+                const permName = permission.name instanceof RegExp ? permission.name.source : permission.name;
+                plugin.recordFeatureContribution(feature.name, permName);
+                plugin.onDispose(dispose);
+                return dispose;
+            },
+        };
+    }
 }
 export var Permissions;
 (function (Permissions) {
@@ -64,4 +105,8 @@ export var Permissions;
     }
     Permissions.define = define;
 })(Permissions || (Permissions = {}));
+/**
+ * @deprecated Use PermissionFeature instead
+ */
+export const PermissionService = PermissionFeature;
 //# sourceMappingURL=permission.js.map