@zhin.js/core 1.0.24 → 1.0.26

package/src/types.ts

@@ -86,16 +86,8 @@ export interface UserInfo {
   role?: string;
 }
 
-/**
- * 权限服务接口
- */
-import type { PermissionService } from './built/permission.js';
-/**
- * 配置服务接口
- */
-import type { ConfigService } from './built/config.js';
-
-export { PermissionService, ConfigService };
+// PermissionService and ConfigService are now exported from their respective
+// built files as backward-compatible aliases for PermissionFeature / ConfigFeature.
 /**
  * 群组信息结构
  */
@@ -134,4 +126,307 @@ export type QueueItem = {
   action: string;
   payload: any;
 };
-export type BeforeSendHandler=(options:SendOptions)=>MaybePromise<SendOptions|void>
+export type BeforeSendHandler=(options:SendOptions)=>MaybePromise<SendOptions|void>
+
+// ============================================================================
+// 统一 Tool 类型定义
+// 支持 AI Agent 调用和自动转换为 Command
+// ============================================================================
+
+/**
+ * JSON Schema 定义，用于描述工具参数
+ */
+export interface ToolJsonSchema {
+  type: string;
+  properties?: Record<string, ToolJsonSchema & { 
+    /** 参数类型提示，用于命令解析 */
+    paramType?: 'text' | 'number' | 'boolean' | 'rest';
+  }>;
+  required?: string[];
+  items?: ToolJsonSchema;
+  enum?: any[];
+  description?: string;
+  default?: any;
+  [key: string]: any;
+}
+
+// ============================================================================
+// 类型反射工具类型
+// ============================================================================
+
+/**
+ * 从 TypeScript 类型推断 JSON Schema 的 type 字段
+ */
+type InferSchemaType<T> = 
+  T extends string ? 'string' :
+  T extends number ? 'number' :
+  T extends boolean ? 'boolean' :
+  T extends any[] ? 'array' :
+  T extends object ? 'object' :
+  'string';
+
+/**
+ * 单个属性的 Schema 定义
+ */
+export interface PropertySchema<T = any> extends ToolJsonSchema {
+  type: InferSchemaType<T>;
+  description?: string;
+  default?: T;
+  enum?: T extends string | number ? T[] : never;
+  paramType?: 'text' | 'number' | 'boolean' | 'rest';
+}
+
+/**
+ * 从 TArgs 构建 properties 类型
+ * 每个属性的 key 必须与 TArgs 的 key 一致
+ */
+type ToolPropertiesSchema<TArgs extends Record<string, any>> = {
+  [K in keyof TArgs]: PropertySchema<TArgs[K]>;
+};
+
+/**
+ * 提取必需的属性名
+ * 通过检查属性是否可以为 undefined 来判断
+ */
+type RequiredKeys<T> = {
+  [K in keyof T]-?: undefined extends T[K] ? never : K;
+}[keyof T];
+
+/**
+ * 带类型反射的参数 Schema
+ * @template TArgs 参数类型
+ */
+export interface ToolParametersSchema<TArgs extends Record<string, any> = Record<string, any>> {
+  type: 'object';
+  /** 属性定义，key 与 TArgs 的 key 一致 */
+  properties: ToolPropertiesSchema<TArgs>;
+  /** 必需的属性列表 */
+  required?: (keyof TArgs & string)[];
+  /** 描述 */
+  description?: string;
+}
+
+/**
+ * 工具执行上下文
+ * 包含消息来源、发送者等信息
+ */
+export interface ToolContext {
+  /** 来源平台 */
+  platform?: string;
+  /** 来源 Bot */
+  botId?: string;
+  /** 场景 ID（群号/频道ID/私聊用户ID） */
+  sceneId?: string;
+  /** 发送者 ID */
+  senderId?: string;
+  /** 原始消息对象（如果从消息触发） */
+  message?: Message<any>;
+  /** 
+   * 消息场景类型
+   * private: 私聊, group: 群聊, channel: 频道
+   */
+  scope?: ToolScope;
+  /**
+   * 发送者权限级别
+   * 用于工具权限过滤
+   */
+  senderPermissionLevel?: ToolPermissionLevel;
+  /**
+   * 发送者是否为群管理员
+   */
+  isGroupAdmin?: boolean;
+  /**
+   * 发送者是否为群主
+   */
+  isGroupOwner?: boolean;
+  /**
+   * 发送者是否为机器人管理员
+   */
+  isBotAdmin?: boolean;
+  /**
+   * 发送者是否为 Zhin 拥有者
+   */
+  isOwner?: boolean;
+  /** 额外数据 */
+  extra?: Record<string, any>;
+}
+
+/**
+ * 统一的 Tool 定义
+ * 可同时用于：
+ * - AI Agent 工具调用
+ * - 自动生成 Command
+ * - MCP 工具暴露
+ * 
+ * @example
+ * ```typescript
+ * // 使用 defineTool 获得类型安全
+ * const weatherTool = defineTool<{ city: string }>({
+ *   name: 'weather',
+ *   description: '查询天气',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: {
+ *       city: { type: 'string', description: '城市名称' }
+ *     },
+ *     required: ['city']
+ *   },
+ *   execute: async (args) => {
+ *     return `${args.city} 的天气是晴天`;  // args.city 有类型提示
+ *   },
+ * });
+ * 
+ * plugin.addTool(weatherTool);  // 无需类型断言
+ * ```
+ */
+/**
+ * 消息场景类型
+ */
+export type ToolScope = 'private' | 'group' | 'channel';
+
+/**
+ * 工具权限级别
+ * - user: 普通用户（默认）
+ * - group_admin: 群管理员
+ * - group_owner: 群主
+ * - bot_admin: 机器人管理员
+ * - owner: Zhin 拥有者（最高权限）
+ */
+export type ToolPermissionLevel = 'user' | 'group_admin' | 'group_owner' | 'bot_admin' | 'owner';
+
+export interface Tool {
+  /** 工具名称（唯一标识，建议使用 snake_case） */
+  name: string;
+  
+  /** 工具描述（供 AI 和帮助系统使用） */
+  description: string;
+  
+  /** 
+   * 参数定义（JSON Schema 格式）
+   */
+  parameters: ToolParametersSchema;
+  
+  /** 
+   * 工具执行函数
+   * @param args 解析后的参数
+   * @param context 执行上下文（包含消息、发送者等信息）
+   * @returns 执行结果（字符串会直接作为回复，对象会被 JSON 序列化）
+   */
+  execute: (args: Record<string, any>, context?: ToolContext) => MaybePromise<any>;
+  
+  /** 工具来源标识（自动填充：adapter:xxx / plugin:xxx） */
+  source?: string;
+  
+  /** 工具标签（用于分类和过滤） */
+  tags?: string[];
+
+  /** 触发关键词（用户消息包含这些词时优先选择此工具） */
+  keywords?: string[];
+  
+  /** 
+   * 命令配置（可选）
+   * 如果不提供，会根据 parameters 自动生成命令模式
+   * 如果设置为 false，则不生成命令
+   */
+  command?: Tool.CommandConfig | false;
+  
+  /** 
+   * 权限要求（旧版，保留兼容）
+   * 执行此工具需要的权限列表
+   */
+  permissions?: string[];
+  
+  /**
+   * 支持的平台列表
+   * 例如：['qq', 'telegram', 'discord']
+   * 不填则支持所有平台
+   */
+  platforms?: string[];
+  
+  /**
+   * 支持的场景列表
+   * 例如：['private', 'group', 'channel']
+   * 不填则支持所有场景
+   */
+  scopes?: ToolScope[];
+  
+  /**
+   * 调用所需的最低权限级别
+   * 默认为 'user'（普通用户可调用）
+   */
+  permissionLevel?: ToolPermissionLevel;
+  
+  /**
+   * 是否隐藏
+   * 隐藏的工具不会出现在帮助列表中，但仍可被调用
+   */
+  hidden?: boolean;
+}
+
+/**
+ * 类型安全的 Tool 定义（用于 defineTool）
+ * 提供泛型参数以获得 execute 函数的类型推断
+ */
+export interface ToolDefinition<TArgs extends Record<string, any> = Record<string, any>> {
+  name: string;
+  description: string;
+  parameters: ToolParametersSchema<TArgs>;
+  execute: (args: TArgs, context?: ToolContext) => MaybePromise<any>;
+  source?: string;
+  tags?: string[];
+  keywords?: string[];
+  command?: Tool.CommandConfig | false;
+  permissions?: string[];
+  /** 支持的平台列表（不填则支持所有平台） */
+  platforms?: string[];
+  /** 支持的场景列表（不填则支持所有场景） */
+  scopes?: ToolScope[];
+  /** 调用所需的最低权限级别（默认 'user'） */
+  permissionLevel?: ToolPermissionLevel;
+  hidden?: boolean;
+}
+
+export namespace Tool {
+  /**
+   * 命令配置
+   */
+  export interface CommandConfig {
+    /** 
+     * 自定义命令模式
+     * 如果不提供，会根据 parameters 自动生成
+     * @example 'weather <city>' | 'calc <expression:text>'
+     */
+    pattern?: string;
+    
+    /** 命令别名 */
+    alias?: string[];
+    
+    /** 命令使用说明 */
+    usage?: string[];
+    
+    /** 命令示例 */
+    examples?: string[];
+    
+    /** 是否启用（默认 true） */
+    enabled?: boolean;
+  }
+  
+  /**
+   * 参数信息
+   */
+  export interface ParamInfo {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+    default?: any;
+    enum?: any[];
+  }
+}
+
+// ============================================================================
+// 兼容性别名（逐步废弃）
+// ============================================================================
+
+/** @deprecated 使用 Tool 替代 */
+export type AITool = Tool;

package/src/utils.ts

@@ -197,23 +197,46 @@ export namespace segment {
       template = unescape(template);
       const result: MessageElement[] = [];
       // 修复 ReDoS 漏洞：使用更安全的正则表达式
-      // 原: /<(\S+)(\s[^>]+)?\/>/  可能导致回溯
-      const closingReg = /<(\w+)(?:\s+[^>]*?)?\/>/;
-      // 原: /<(\S+)(\s[^>]+)?>([\s\S]*?)<\/\1>/  可能导致回溯
-      const twinningReg = /<(\w+)(?:\s+[^>]*?)?>([^]*?)<\/\1>/;
+      // 注意：需要使用捕获组来获取属性字符串，否则无法正确重建原始标签
+      // closingReg: 自闭合标签 <type attr="val"/>
+      const closingReg = /<(\w+)(\s+[^>]*?)?\/>/;
+      // twinningReg: 成对标签 <type attr="val">child</type>
+      const twinningReg = /<(\w+)(\s+[^>]*?)?>([^]*?)<\/\1>/;
       
       let iterations = 0;
       const MAX_ITERATIONS = 1000; // 防止无限循环
       
       while (template.length && iterations++ < MAX_ITERATIONS) {
-        const [_, type, attrStr = "", child = ""] =
-          template.match(twinningReg) || template.match(closingReg) || [];
-        if (!type) break;
-        const isClosing = closingReg.test(template);
-        const matched = isClosing
-          ? `<${type}${attrStr}/>`
-          : `<${type}${attrStr}>${child}</${type}>`;
-        const index = template.indexOf(matched);
+        const twinMatch = template.match(twinningReg);
+        const closeMatch = template.match(closingReg);
+        
+        // 选择位置更靠前的匹配
+        let match: RegExpMatchArray | null = null;
+        let isClosing = false;
+        
+        if (twinMatch && closeMatch) {
+          const twinIndex = template.indexOf(twinMatch[0]);
+          const closeIndex = template.indexOf(closeMatch[0]);
+          if (closeIndex <= twinIndex) {
+            match = closeMatch;
+            isClosing = true;
+          } else {
+            match = twinMatch;
+          }
+        } else if (closeMatch) {
+          match = closeMatch;
+          isClosing = true;
+        } else if (twinMatch) {
+          match = twinMatch;
+        }
+        
+        if (!match) break;
+        
+        const [fullMatch, type, attrStr = "", child = ""] = isClosing 
+          ? [match[0], match[1], match[2] || ""]
+          : [match[0], match[1], match[2] || "", match[3] || ""];
+        const index = template.indexOf(fullMatch);
+        if (index === -1) break; // 安全检查
         const prevText = template.slice(0, index);
         if (prevText)
           result.push({
@@ -222,7 +245,7 @@ export namespace segment {
               text: unescape(prevText),
             },
           });
-        template = template.slice(index + matched.length);
+        template = template.slice(index + fullMatch.length);
         // 修复 ReDoS 漏洞：使用更简单的正则表达式
         // 原: /\s([^=]+)(?=(?=="([^"]+)")|(?=='([^']+)'))/g  嵌套前瞻断言
         const attrArr = [
@@ -271,6 +294,7 @@ export namespace segment {
         if (typeof item === "string") return item;
         const { type, data } = item;
         if (type === "text") return data.text;
+        if (type === "at") return `@${data.user_id||data.qq}`;
         return data.text ? `{${type}}(${data.text})` : `{${type}}`;
       })
       .join("");

package/tests/adapter.test.ts

@@ -377,7 +377,7 @@ describe('Adapter Core Functionality', () => {
     })
 
     describe('message.receive', () => {
-      it('should process received message through middleware', async () => {
+      it('should process received message through middleware when no dispatcher', async () => {
         const config = [{ id: 'bot1' }]
         const adapter = new MockAdapter(plugin, 'test', config)
         await adapter.start()
@@ -401,6 +401,74 @@ describe('Adapter Core Functionality', () => {
         await new Promise(resolve => setTimeout(resolve, 10))
         expect(middlewareCalled).toBe(true)
       })
+
+      it('should use MessageDispatcher when available', async () => {
+        const config = [{ id: 'bot1' }]
+        const adapter = new MockAdapter(plugin, 'test', config)
+        await adapter.start()
+
+        let dispatchCalled = false
+        let middlewareCalled = false
+
+        // 注册 dispatcher context
+        plugin.$contexts.set('dispatcher', {
+          name: 'dispatcher',
+          description: 'mock dispatcher',
+          value: {
+            dispatch: (msg: any) => { dispatchCalled = true },
+          },
+        } as any)
+
+        plugin.addMiddleware(async (message, next) => {
+          middlewareCalled = true
+          await next()
+        })
+
+        const message = {
+          $bot: 'bot1',
+          $adapter: 'test',
+          $channel: { id: 'channel-id', type: 'text' },
+          $content: 'Hello'
+        } as any
+
+        adapter.emit('message.receive', message)
+
+        await new Promise(resolve => setTimeout(resolve, 10))
+        expect(dispatchCalled).toBe(true)
+        expect(middlewareCalled).toBe(false)
+      })
+
+      it('should fallback to middleware when dispatcher has no dispatch method', async () => {
+        const config = [{ id: 'bot1' }]
+        const adapter = new MockAdapter(plugin, 'test', config)
+        await adapter.start()
+
+        let middlewareCalled = false
+
+        // 注册一个没有 dispatch 方法的 dispatcher
+        plugin.$contexts.set('dispatcher', {
+          name: 'dispatcher',
+          description: 'broken dispatcher',
+          value: { noDispatch: true },
+        } as any)
+
+        plugin.addMiddleware(async (message, next) => {
+          middlewareCalled = true
+          await next()
+        })
+
+        const message = {
+          $bot: 'bot1',
+          $adapter: 'test',
+          $channel: { id: 'channel-id', type: 'text' },
+          $content: 'Hello'
+        } as any
+
+        adapter.emit('message.receive', message)
+
+        await new Promise(resolve => setTimeout(resolve, 10))
+        expect(middlewareCalled).toBe(true)
+      })
     })
   })
 
@@ -549,6 +617,90 @@ describe('Adapter Core Functionality', () => {
   })
 })
 
+describe('Adapter declareSkill', () => {
+  it('should register a skill when SkillFeature is available', () => {
+    const plugin = new Plugin('/test/adapter-plugin.ts')
+    
+    // 模拟 SkillFeature
+    const mockSkillFeature = {
+      add: vi.fn(() => vi.fn()),
+    }
+    
+    // 设置 root plugin 和 inject
+    ;(plugin as any)._root = plugin
+    const originalInject = plugin.inject.bind(plugin)
+    plugin.inject = ((name: string) => {
+      if (name === 'skill') return mockSkillFeature
+      return originalInject(name)
+    }) as any
+    ;(plugin as any).recordFeatureContribution = vi.fn()
+
+    const adapter = new MockAdapter(plugin, 'test-adapter')
+    
+    // 添加一个工具
+    adapter.addTool({
+      name: 'test_tool',
+      description: '测试工具',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => '',
+      keywords: ['test'],
+      tags: ['testing'],
+    })
+
+    adapter.declareSkill({
+      description: '测试适配器的技能',
+      keywords: ['adapter'],
+      tags: ['adapter-tag'],
+    })
+
+    expect(mockSkillFeature.add).toHaveBeenCalledTimes(1)
+    const [skill] = mockSkillFeature.add.mock.calls[0]
+    expect(skill.name).toContain('test-adapter')
+    expect(skill.description).toBe('测试适配器的技能')
+    expect(skill.tools).toHaveLength(1)
+    // keywords 应合并适配器和工具的关键词
+    expect(skill.keywords).toContain('adapter')
+    expect(skill.keywords).toContain('test')
+    // tags 应合并
+    expect(skill.tags).toContain('adapter-tag')
+    expect(skill.tags).toContain('testing')
+  })
+
+  it('should clean up skill on stop', async () => {
+    const disposeSkill = vi.fn()
+    const plugin = new Plugin('/test/adapter-plugin.ts')
+    
+    const mockSkillFeature = {
+      add: vi.fn(() => disposeSkill),
+    }
+    ;(plugin as any)._root = plugin
+    plugin.inject = ((name: string) => {
+      if (name === 'skill') return mockSkillFeature
+      return undefined
+    }) as any
+    ;(plugin as any).recordFeatureContribution = vi.fn()
+
+    const adapter = new MockAdapter(plugin, 'test-adapter')
+    adapter.declareSkill({ description: '测试' })
+
+    await adapter.stop()
+
+    expect(disposeSkill).toHaveBeenCalledTimes(1)
+  })
+
+  it('should skip when SkillFeature is not available', () => {
+    const plugin = new Plugin('/test/adapter-plugin.ts')
+    ;(plugin as any)._root = plugin
+
+    const adapter = new MockAdapter(plugin, 'test-adapter')
+    
+    // 不应抛错
+    expect(() => {
+      adapter.declareSkill({ description: '测试' })
+    }).not.toThrow()
+  })
+})
+
 describe('Adapter Registry', () => {
   it('should have a Registry Map', () => {
     expect(Adapter.Registry).toBeInstanceOf(Map)