@zhin.js/core 1.0.24 → 1.0.26

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

package/lib/built/permission.js.map

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

package/lib/built/skill.d.ts

@@ -0,0 +1,117 @@
+/**
+ * SkillFeature — AI 可见能力描述层
+ *
+ * 核心概念：
+ *   Plugin = 运行时容器（生命周期、服务注册、中间件）
+ *   Skill  = AI 可见的能力接口（名称、描述、工具列表）
+ *
+ * 每个 Plugin 可以声明一个 Skill 描述，告诉 AI Agent：
+ *   "我叫什么、我能做什么、我有哪些工具"
+ *
+ * SkillFeature 全局收集所有 Skill，供 Agent 进行两级过滤：
+ *   1. 粗筛：根据用户消息选择相关 Skill
+ *   2. 细筛：从选中 Skill 内选择具体 Tool
+ */
+import { Feature, FeatureJSON } from '../feature.js';
+import type { Tool } from '../types.js';
+/**
+ * Skill — AI 可见的能力描述
+ */
+export interface Skill {
+    /** 技能名称（通常与插件名一致） */
+    name: string;
+    /** 技能描述（AI 用来理解这个 Skill 的用途） */
+    description: string;
+    /** 该 Skill 提供的工具列表 */
+    tools: Tool[];
+    /**
+     * 触发关键词
+     * 当用户消息包含这些关键词时，优先选择此 Skill
+     */
+    keywords?: string[];
+    /**
+     * 分类标签
+     * 用于按领域分组（如 'news', 'weather', 'entertainment'）
+     */
+    tags?: string[];
+    /** 来源插件名 */
+    pluginName: string;
+}
+/**
+ * Skill 元数据 — 开发者在插件中声明
+ * 由 plugin.declareSkill() 注册
+ */
+export interface SkillMetadata {
+    /** 技能描述（必填） */
+    description: string;
+    /** 触发关键词（可选，自动从工具中聚合） */
+    keywords?: string[];
+    /** 分类标签（可选） */
+    tags?: string[];
+}
+export interface SkillContextExtensions {
+    /**
+     * 声明本插件的 Skill 元数据
+     * 调用后，插件的工具会自动聚合为一个 Skill 注册到 SkillFeature
+     */
+    declareSkill(metadata: SkillMetadata): void;
+}
+declare module '../plugin.js' {
+    namespace Plugin {
+        interface Extensions extends SkillContextExtensions {
+        }
+        interface Contexts {
+            skill: SkillFeature;
+        }
+    }
+}
+export declare class SkillFeature extends Feature<Skill> {
+    #private;
+    readonly name: "skill";
+    readonly icon = "Brain";
+    readonly desc = "\u6280\u80FD";
+    /** 按名称索引 */
+    readonly byName: Map<string, Skill>;
+    /**
+     * 添加 Skill
+     */
+    add(skill: Skill, pluginName: string): () => void;
+    /**
+     * 移除 Skill
+     */
+    remove(skill: Skill): boolean;
+    /**
+     * 按名称获取 Skill
+     */
+    get(name: string): Skill | undefined;
+    /**
+     * 获取所有已注册 Skill
+     */
+    getAll(): Skill[];
+    /**
+     * 按关键词/标签搜索相关 Skill
+     * 返回按相关性排序的 Skill 列表
+     */
+    search(query: string, options?: {
+        maxResults?: number;
+    }): Skill[];
+    /**
+     * 获取所有 Skill 的工具（扁平化）
+     */
+    collectAllTools(): Tool[];
+    /**
+     * 已注册 Skill 数量
+     */
+    get size(): number;
+    /**
+     * 序列化为 JSON
+     */
+    toJSON(pluginName?: string): FeatureJSON;
+    /**
+     * 提供给 Plugin.prototype 的扩展方法
+     */
+    get extensions(): {
+        declareSkill(metadata: SkillMetadata): void;
+    };
+}
+//# sourceMappingURL=skill.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/built/skill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAMxC;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IAEb,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IAEpB,sBAAsB;IACtB,KAAK,EAAE,IAAI,EAAE,CAAC;IAEd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,YAAY;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,eAAe;IACf,WAAW,EAAE,MAAM,CAAC;IAEpB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,eAAe;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAMD,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;CAC7C;AAED,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,MAAM,CAAC;QACf,UAAU,UAAW,SAAQ,sBAAsB;SAAG;QACtD,UAAU,QAAQ;YAChB,KAAK,EAAE,YAAY,CAAC;SACrB;KACF;CACF;AAMD,qBAAa,YAAa,SAAQ,OAAO,CAAC,KAAK,CAAC;;IAC9C,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IACjC,QAAQ,CAAC,IAAI,WAAW;IACxB,QAAQ,CAAC,IAAI,kBAAQ;IAErB,YAAY;IACZ,QAAQ,CAAC,MAAM,qBAA4B;IAE3C;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,IAAI;IAKjD;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAK7B;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAIpC;;OAEG;IACH,MAAM,IAAI,KAAK,EAAE;IAIjB;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,EAAE;IAWjE;;OAEG;IACH,eAAe,IAAI,IAAI,EAAE;IAQzB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IA0CD;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,WAAW;IAiBxC;;OAEG;IACH,IAAI,UAAU;+BAGa,aAAa;MAiDvC;CACF"}