@zhin.js/core 1.0.24 → 1.0.26

package/tests/plugin.test.ts

@@ -232,13 +232,12 @@ describe('Plugin AsyncLocalStorage', () => {
       })
     })
 
-    it('should create child plugin when called within parent context', () => {
+    it('should return same instance when called twice from same file', () => {
       storage.run(undefined, () => {
-        const parent = usePlugin()
-        const child = usePlugin()
+        const first = usePlugin()
+        const second = usePlugin()
         
-        expect(child.parent).toBe(parent)
-        expect(parent.children).toContain(child)
+        expect(second).toBe(first)
       })
     })
 
@@ -561,6 +560,82 @@ describe('Plugin Event Broadcasting', () => {
   })
 })
 
+describe('Plugin Context mounted Behavior', () => {
+  it('should always call mounted callback even when value is preset', async () => {
+    const plugin = new Plugin('/test/plugin.ts')
+    let mountedCalled = false
+
+    plugin.provide({
+      name: 'test-ctx' as any,
+      description: 'Test context with both value and mounted',
+      value: { original: true },
+      mounted(_p: any) {
+        mountedCalled = true
+        return { fromMounted: true }
+      },
+    } as any)
+
+    await plugin.start()
+    expect(mountedCalled).toBe(true)
+  })
+
+  it('should NOT overwrite preset value with mounted return', async () => {
+    const plugin = new Plugin('/test/plugin.ts')
+    const presetValue = { original: true }
+
+    plugin.provide({
+      name: 'test-ctx' as any,
+      description: 'Test context with both value and mounted',
+      value: presetValue,
+      mounted(_p: any) {
+        return { fromMounted: true }
+      },
+    } as any)
+
+    await plugin.start()
+    const injected = plugin.inject('test-ctx' as any)
+    expect(injected).toBe(presetValue)
+    expect(injected).toEqual({ original: true })
+  })
+
+  it('should assign mounted return value when context.value is not set', async () => {
+    const plugin = new Plugin('/test/plugin.ts')
+    const mountedValue = { fromMounted: true }
+
+    plugin.provide({
+      name: 'test-ctx' as any,
+      description: 'Test context with mounted only',
+      mounted(_p: any) {
+        return mountedValue
+      },
+    } as any)
+
+    await plugin.start()
+    const injected = plugin.inject('test-ctx' as any)
+    expect(injected).toBe(mountedValue)
+  })
+
+  it('mounted side effects should run even when value is preset', async () => {
+    const plugin = new Plugin('/test/plugin.ts')
+    let sideEffectCounter = 0
+
+    plugin.provide({
+      name: 'test-ctx' as any,
+      description: 'Test mounted side effects',
+      value: { data: 'preset' },
+      mounted(_p: any) {
+        sideEffectCounter++
+        return { data: 'mounted' }
+      },
+    } as any)
+
+    await plugin.start()
+    expect(sideEffectCounter).toBe(1)
+    // value should remain preset
+    expect(plugin.inject('test-ctx' as any)).toEqual({ data: 'preset' })
+  })
+})
+
 describe('Plugin Context Management', () => {
   describe('provide', () => {
     it('should register context', () => {
@@ -631,20 +706,19 @@ describe('Plugin Context Management', () => {
 describe('Plugin Features', () => {
   it('should return empty features by default', () => {
     const plugin = new Plugin('/test/plugin.ts')
-    const features = plugin.features
+    const features = plugin.getFeatures()
     
-    expect(features.commands).toEqual([])
-    expect(features.components).toEqual([])
-    expect(features.crons).toEqual([])
-    expect(Array.isArray(features.middlewares)).toBe(true)
+    expect(features).toEqual([])
   })
 
-  it('should include middleware names', () => {
+  it('should include middleware in getFeatures', () => {
     const plugin = new Plugin('/test/plugin.ts')
-    plugin.addMiddleware(async (msg: any, next: any) => await next(), 'test-middleware')
+    plugin.addMiddleware(async (msg: any, next: any) => await next())
     
-    const features = plugin.features
-    expect(features.middlewares.length).toBeGreaterThan(0)
+    const features = plugin.getFeatures()
+    const middlewareFeature = features.find(f => f.name === 'middleware')
+    expect(middlewareFeature).toBeDefined()
+    expect(middlewareFeature!.count).toBeGreaterThan(0)
   })
 })
 

package/tests/skill-feature.test.ts

@@ -0,0 +1,179 @@
+/**
+ * SkillFeature 测试
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SkillFeature, Skill } from '../src/built/skill.js';
+import type { Tool } from '../src/types.js';
+
+function makeTool(name: string, desc: string = ''): Tool {
+  return {
+    name,
+    description: desc,
+    parameters: { type: 'object', properties: {} },
+    execute: async () => '',
+  };
+}
+
+function makeSkill(overrides: Partial<Skill> & { name: string }): Skill {
+  return {
+    description: '默认描述',
+    tools: [],
+    pluginName: overrides.name,
+    ...overrides,
+  };
+}
+
+describe('SkillFeature', () => {
+  let feature: SkillFeature;
+
+  beforeEach(() => {
+    feature = new SkillFeature();
+  });
+
+  describe('add / remove', () => {
+    it('应该能添加 Skill', () => {
+      const skill = makeSkill({ name: 'weather', description: '天气查询' });
+      const dispose = feature.add(skill, 'plugin-weather');
+
+      expect(feature.items).toHaveLength(1);
+      expect(feature.byName.get('weather')).toBe(skill);
+      expect(feature.size).toBe(1);
+    });
+
+    it('dispose 应移除 Skill', () => {
+      const skill = makeSkill({ name: 'weather' });
+      const dispose = feature.add(skill, 'plugin-weather');
+
+      dispose();
+      expect(feature.items).toHaveLength(0);
+      expect(feature.byName.has('weather')).toBe(false);
+    });
+
+    it('remove 应从 byName 和 items 中移除', () => {
+      const skill = makeSkill({ name: 'weather' });
+      feature.add(skill, 'plugin-weather');
+
+      feature.remove(skill);
+      expect(feature.items).toHaveLength(0);
+      expect(feature.byName.has('weather')).toBe(false);
+    });
+  });
+
+  describe('get / getAll', () => {
+    it('按名称获取', () => {
+      const skill = makeSkill({ name: 'news' });
+      feature.add(skill, 'plugin-news');
+
+      expect(feature.get('news')).toBe(skill);
+      expect(feature.get('nonexistent')).toBeUndefined();
+    });
+
+    it('获取所有', () => {
+      feature.add(makeSkill({ name: 'a' }), 'pa');
+      feature.add(makeSkill({ name: 'b' }), 'pb');
+
+      const all = feature.getAll();
+      expect(all).toHaveLength(2);
+    });
+  });
+
+  describe('search', () => {
+    beforeEach(() => {
+      feature.add(makeSkill({
+        name: 'weather',
+        description: '查询天气预报',
+        keywords: ['天气', '气温', '温度'],
+        tags: ['weather', '生活'],
+        tools: [makeTool('get_weather', '获取天气')],
+      }), 'plugin-weather');
+
+      feature.add(makeSkill({
+        name: 'news',
+        description: '获取新闻资讯',
+        keywords: ['新闻', '头条', '资讯'],
+        tags: ['news', '信息'],
+        tools: [makeTool('get_news', '获取新闻')],
+      }), 'plugin-news');
+
+      feature.add(makeSkill({
+        name: 'music',
+        description: '音乐搜索与播放',
+        keywords: ['音乐', '歌曲', '播放'],
+        tags: ['music', '娱乐'],
+        tools: [makeTool('search_music')],
+      }), 'plugin-music');
+    });
+
+    it('关键词匹配应返回相关 Skill', () => {
+      const results = feature.search('今天天气怎么样');
+      expect(results.length).toBeGreaterThan(0);
+      expect(results[0].name).toBe('weather');
+    });
+
+    it('标签匹配应返回相关 Skill', () => {
+      const results = feature.search('news');
+      expect(results.some(s => s.name === 'news')).toBe(true);
+    });
+
+    it('无匹配时应返回空数组', () => {
+      const results = feature.search('完全无关的内容 xyz');
+      expect(results).toHaveLength(0);
+    });
+
+    it('maxResults 应限制返回数量', () => {
+      // 搜索一个泛化词，可能匹配多个
+      const results = feature.search('获取', { maxResults: 1 });
+      expect(results.length).toBeLessThanOrEqual(1);
+    });
+  });
+
+  describe('collectAllTools', () => {
+    it('应收集所有 Skill 的工具', () => {
+      feature.add(makeSkill({
+        name: 'a',
+        tools: [makeTool('t1'), makeTool('t2')],
+      }), 'pa');
+      feature.add(makeSkill({
+        name: 'b',
+        tools: [makeTool('t3')],
+      }), 'pb');
+
+      const tools = feature.collectAllTools();
+      expect(tools).toHaveLength(3);
+      expect(tools.map(t => t.name)).toEqual(['t1', 't2', 't3']);
+    });
+  });
+
+  describe('toJSON', () => {
+    it('应序列化所有 Skill', () => {
+      feature.add(makeSkill({
+        name: 'test',
+        description: '测试技能',
+        keywords: ['test'],
+        tags: ['t'],
+        tools: [makeTool('t1'), makeTool('t2')],
+      }), 'plugin-test');
+
+      const json = feature.toJSON();
+      expect(json.name).toBe('skill');
+      expect(json.icon).toBe('Brain');
+      expect(json.count).toBe(1);
+      expect(json.items[0]).toMatchObject({
+        name: 'test',
+        desc: '测试技能',
+        toolCount: 2,
+        keywords: ['test'],
+        tags: ['t'],
+      });
+    });
+
+    it('按插件名过滤', () => {
+      feature.add(makeSkill({ name: 'a' }), 'pa');
+      feature.add(makeSkill({ name: 'b' }), 'pb');
+
+      const json = feature.toJSON('pa');
+      expect(json.count).toBe(1);
+      expect(json.items[0].name).toBe('a');
+    });
+  });
+});

package/tests/tool-feature.test.ts

@@ -0,0 +1,254 @@
+/**
+ * ToolFeature 补全测试
+ * 测试 toolToCommand / commandToTool / ToolFeature.add / filterByContext
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  generatePattern,
+  extractParamInfo,
+  toolToCommand,
+  commandToTool,
+  canAccessTool,
+  inferPermissionLevel,
+  hasPermissionLevel,
+  ZhinTool,
+  isZhinTool,
+  ToolFeature,
+} from '../src/built/tool.js';
+import type { Tool, ToolContext } from '../src/types.js';
+
+describe('generatePattern', () => {
+  it('应生成无参数的模式', () => {
+    const tool: Tool = {
+      name: 'ping',
+      description: '测试',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => 'pong',
+    };
+    expect(generatePattern(tool)).toBe('ping');
+  });
+
+  it('应生成有必填参数的模式', () => {
+    const tool: Tool = {
+      name: 'weather',
+      description: '天气',
+      parameters: {
+        type: 'object',
+        properties: { city: { type: 'string', description: '城市' } },
+        required: ['city'],
+      },
+      execute: async () => '',
+    };
+    expect(generatePattern(tool)).toBe('weather <city:text>');
+  });
+
+  it('应生成有可选参数的模式', () => {
+    const tool: Tool = {
+      name: 'search',
+      description: '搜索',
+      parameters: {
+        type: 'object',
+        properties: { query: { type: 'string' }, limit: { type: 'number' } },
+        required: ['query'],
+      },
+      execute: async () => '',
+    };
+    const pattern = generatePattern(tool);
+    expect(pattern).toContain('<query:text>');
+    expect(pattern).toContain('[limit:number]');
+  });
+
+  it('应使用自定义 command.pattern', () => {
+    const tool: Tool = {
+      name: 'custom',
+      description: '自定义',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => '',
+      command: { pattern: 'my-custom <arg:text>', enabled: true },
+    };
+    expect(generatePattern(tool)).toBe('my-custom <arg:text>');
+  });
+});
+
+describe('extractParamInfo', () => {
+  it('应从空 properties 返回空数组', () => {
+    expect(extractParamInfo({ type: 'object', properties: {} })).toEqual([]);
+  });
+
+  it('应提取参数信息', () => {
+    const result = extractParamInfo({
+      type: 'object',
+      properties: {
+        city: { type: 'string', description: '城市名' },
+        days: { type: 'number', description: '天数' },
+      },
+      required: ['city'],
+    });
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({ name: 'city', type: 'string', required: true, description: '城市名' });
+    expect(result[1]).toMatchObject({ name: 'days', type: 'number', required: false, description: '天数' });
+  });
+});
+
+describe('canAccessTool', () => {
+  const baseTool: Tool = {
+    name: 'test',
+    description: '测试',
+    parameters: { type: 'object', properties: {} },
+    execute: async () => '',
+  };
+
+  const baseContext: ToolContext = {
+    platform: 'qq',
+    botId: 'bot1',
+    sceneId: 'scene1',
+    senderId: 'user1',
+  };
+
+  it('无限制的工具应始终可访问', () => {
+    expect(canAccessTool(baseTool, baseContext)).toBe(true);
+  });
+
+  it('应检查平台限制', () => {
+    const tool = { ...baseTool, platforms: ['discord'] };
+    expect(canAccessTool(tool, { ...baseContext, platform: 'qq' })).toBe(false);
+    expect(canAccessTool(tool, { ...baseContext, platform: 'discord' })).toBe(true);
+  });
+
+  it('应检查场景限制', () => {
+    const tool = { ...baseTool, scopes: ['group' as const] };
+    expect(canAccessTool(tool, { ...baseContext, scope: 'private' })).toBe(false);
+    expect(canAccessTool(tool, { ...baseContext, scope: 'group' })).toBe(true);
+  });
+
+  it('应检查权限级别', () => {
+    const tool = { ...baseTool, permissionLevel: 'group_admin' as const };
+    expect(canAccessTool(tool, { ...baseContext })).toBe(false); // user level
+    expect(canAccessTool(tool, { ...baseContext, isGroupAdmin: true })).toBe(true);
+  });
+});
+
+describe('inferPermissionLevel', () => {
+  it('应使用 senderPermissionLevel 优先', () => {
+    expect(inferPermissionLevel({ senderPermissionLevel: 'owner' } as any)).toBe('owner');
+  });
+
+  it('应按优先级推断', () => {
+    expect(inferPermissionLevel({ isOwner: true } as any)).toBe('owner');
+    expect(inferPermissionLevel({ isBotAdmin: true } as any)).toBe('bot_admin');
+    expect(inferPermissionLevel({ isGroupOwner: true } as any)).toBe('group_owner');
+    expect(inferPermissionLevel({ isGroupAdmin: true } as any)).toBe('group_admin');
+    expect(inferPermissionLevel({} as any)).toBe('user');
+  });
+});
+
+describe('hasPermissionLevel', () => {
+  it('相同级别应返回 true', () => {
+    expect(hasPermissionLevel('user', 'user')).toBe(true);
+    expect(hasPermissionLevel('owner', 'owner')).toBe(true);
+  });
+
+  it('高级别应能访问低级别', () => {
+    expect(hasPermissionLevel('owner', 'user')).toBe(true);
+    expect(hasPermissionLevel('bot_admin', 'group_admin')).toBe(true);
+  });
+
+  it('低级别不能访问高级别', () => {
+    expect(hasPermissionLevel('user', 'group_admin')).toBe(false);
+    expect(hasPermissionLevel('group_admin', 'owner')).toBe(false);
+  });
+});
+
+describe('ToolFeature', () => {
+  let feature: ToolFeature;
+
+  beforeEach(() => {
+    feature = new ToolFeature();
+  });
+
+  describe('基础操作', () => {
+    it('初始状态应无工具', () => {
+      expect(feature.items).toHaveLength(0);
+      expect(feature.byName.size).toBe(0);
+    });
+
+    it('toJSON 应返回正确结构', () => {
+      const json = feature.toJSON();
+      expect(json).toMatchObject({
+        name: 'tool',
+        icon: 'Wrench',
+        desc: '工具',
+        count: 0,
+        items: [],
+      });
+    });
+  });
+
+  describe('filterByContext', () => {
+    it('应过滤不符合权限的工具', () => {
+      const tools: Tool[] = [
+        { name: 'public', description: '公开', parameters: { type: 'object', properties: {} }, execute: async () => '' },
+        { name: 'admin', description: '管理', parameters: { type: 'object', properties: {} }, execute: async () => '', permissionLevel: 'bot_admin' },
+      ];
+      const context: ToolContext = { platform: 'qq', botId: 'b', sceneId: 's', senderId: 'u' };
+      const filtered = feature.filterByContext(tools, context);
+      expect(filtered).toHaveLength(1);
+      expect(filtered[0].name).toBe('public');
+    });
+
+    it('应过滤不符合平台的工具', () => {
+      const tools: Tool[] = [
+        { name: 'all', description: '', parameters: { type: 'object', properties: {} }, execute: async () => '' },
+        { name: 'discord-only', description: '', parameters: { type: 'object', properties: {} }, execute: async () => '', platforms: ['discord'] },
+      ];
+      const context: ToolContext = { platform: 'qq', botId: 'b', sceneId: 's', senderId: 'u' };
+      const filtered = feature.filterByContext(tools, context);
+      expect(filtered).toHaveLength(1);
+      expect(filtered[0].name).toBe('all');
+    });
+  });
+});
+
+describe('ZhinTool', () => {
+  it('应构建完整的 Tool 对象', () => {
+    const zt = new ZhinTool('test')
+      .desc('测试工具')
+      .param('city', { type: 'string', description: '城市' }, true)
+      .execute(async ({ city }) => `${city}: 晴`);
+
+    const tool = zt.toTool();
+    expect(tool.name).toBe('test');
+    expect(tool.description).toBe('测试工具');
+    expect(tool.parameters.properties).toHaveProperty('city');
+    expect(tool.parameters.required).toEqual(['city']);
+    expect(typeof tool.execute).toBe('function');
+  });
+
+  it('无 execute 应抛错', () => {
+    const zt = new ZhinTool('no-exec').desc('无执行');
+    expect(() => zt.toTool()).toThrow('has no execute()');
+  });
+
+  it('isZhinTool 应正确判断', () => {
+    expect(isZhinTool(new ZhinTool('x'))).toBe(true);
+    expect(isZhinTool({})).toBe(false);
+    expect(isZhinTool(null)).toBe(false);
+  });
+
+  it('toJSON 应返回序列化数据', () => {
+    const zt = new ZhinTool('test')
+      .desc('描述')
+      .param('a', { type: 'string' }, true)
+      .tag('t1')
+      .platform('qq')
+      .permission('bot_admin')
+      .execute(async () => '');
+
+    const json = zt.toJSON();
+    expect(json.name).toBe('test');
+    expect(json.description).toBe('描述');
+    expect(json.tags).toEqual(['t1']);
+    expect(json.platforms).toEqual(['qq']);
+    expect(json.permissionLevel).toBe('bot_admin');
+  });
+});