@zhin.js/core 1.0.25 → 1.0.26

package/tests/ai/tools-builtin.test.ts

@@ -0,0 +1,346 @@
+/**
+ * 内置工具测试
+ * 
+ * 测试内容：
+ * 1. 计算器工具
+ * 2. 时间工具
+ * 3. 搜索工具
+ * 4. 代码执行工具
+ * 5. HTTP 请求工具
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { 
+  calculatorTool, 
+  timeTool,
+  searchTool,
+  codeRunnerTool,
+  httpTool,
+  getBuiltinTools,
+} from '../../src/ai/tools.js';
+import { ZhinTool } from '@zhin.js/core';
+
+describe('内置工具', () => {
+  describe('计算器工具', () => {
+    const calculator = calculatorTool.toTool();
+
+    it('应该有正确的元数据', () => {
+      expect(calculator.name).toBe('calculator');
+      expect(calculator.description).toContain('计算');
+      expect(calculator.parameters.properties).toHaveProperty('expression');
+      expect(calculator.parameters.required).toContain('expression');
+    });
+
+    it('应该计算简单加法', async () => {
+      const result = await calculator.execute({ expression: '2 + 3' });
+      expect(result.result).toBe(5);
+      expect(result.expression).toBe('2 + 3');
+    });
+
+    it('应该计算简单减法', async () => {
+      const result = await calculator.execute({ expression: '10 - 4' });
+      expect(result.result).toBe(6);
+    });
+
+    it('应该计算简单乘法', async () => {
+      const result = await calculator.execute({ expression: '6 * 7' });
+      expect(result.result).toBe(42);
+    });
+
+    it('应该计算简单除法', async () => {
+      const result = await calculator.execute({ expression: '20 / 4' });
+      expect(result.result).toBe(5);
+    });
+
+    it('应该计算复杂表达式', async () => {
+      const result = await calculator.execute({ expression: '(10 + 5) * 2' });
+      expect(result.result).toBe(30);
+    });
+
+    it('应该支持幂运算 (^)', async () => {
+      const result = await calculator.execute({ expression: '2 ^ 3' });
+      expect(result.result).toBe(8);
+    });
+
+    it('应该支持 sqrt 函数', async () => {
+      const result = await calculator.execute({ expression: 'sqrt(16)' });
+      expect(result.result).toBe(4);
+    });
+
+    it('应该支持 sin 函数', async () => {
+      const result = await calculator.execute({ expression: 'sin(0)' });
+      expect(result.result).toBe(0);
+    });
+
+    it('应该支持 cos 函数', async () => {
+      const result = await calculator.execute({ expression: 'cos(0)' });
+      expect(result.result).toBe(1);
+    });
+
+    it('应该支持 tan 函数', async () => {
+      const result = await calculator.execute({ expression: 'tan(0)' });
+      expect(result.result).toBe(0);
+    });
+
+    it('应该支持 log 函数', async () => {
+      const result = await calculator.execute({ expression: 'log(1)' });
+      expect(result.result).toBe(0);
+    });
+
+    it('应该支持 abs 函数', async () => {
+      const result = await calculator.execute({ expression: 'abs(-5)' });
+      expect(result.result).toBe(5);
+    });
+
+    it('应该支持 pow 函数（通过 ^ 运算符）', async () => {
+      // pow() 函数的逗号会被过滤，所以使用 ^ 运算符
+      const result = await calculator.execute({ expression: '2 ^ 10' });
+      expect(result.result).toBe(1024);
+    });
+
+    it('应该支持 PI 常量', async () => {
+      const result = await calculator.execute({ expression: 'PI' });
+      expect(result.result).toBeCloseTo(Math.PI);
+    });
+
+    it('应该支持 E 常量', async () => {
+      const result = await calculator.execute({ expression: 'E' });
+      expect(result.result).toBeCloseTo(Math.E);
+    });
+
+    it('应该处理无效表达式', async () => {
+      const result = await calculator.execute({ expression: 'invalid_expression' });
+      expect(result.error).toBeDefined();
+    });
+
+    it('应该处理除零', async () => {
+      const result = await calculator.execute({ expression: '1 / 0' });
+      expect(result.result).toBe(Infinity);
+    });
+
+    it('应该处理空表达式', async () => {
+      const result = await calculator.execute({ expression: '' });
+      // 空表达式会返回 undefined 或 error
+      expect(result.error || result.result === undefined).toBeTruthy();
+    });
+  });
+
+  describe('时间工具', () => {
+    const timeToolObj = timeTool.toTool();
+
+    it('应该有正确的元数据', () => {
+      expect(timeToolObj.name).toBe('get_time');
+      expect(timeToolObj.description).toContain('时间');
+      expect(timeToolObj.parameters.properties).toHaveProperty('timezone');
+      expect(timeToolObj.parameters.properties).toHaveProperty('format');
+    });
+
+    it('应该返回当前时间 (默认格式)', async () => {
+      const result = await timeToolObj.execute({});
+      
+      expect(result).toHaveProperty('timestamp');
+      expect(result).toHaveProperty('formatted');
+      expect(result).toHaveProperty('iso');
+      expect(typeof result.timestamp).toBe('number');
+      expect(typeof result.formatted).toBe('string');
+      expect(typeof result.iso).toBe('string');
+    });
+
+    it('应该支持 full 格式', async () => {
+      const result = await timeToolObj.execute({ format: 'full' });
+      
+      expect(result).toHaveProperty('formatted');
+      expect(result).toHaveProperty('timestamp');
+    });
+
+    it('应该支持 date 格式', async () => {
+      const result = await timeToolObj.execute({ format: 'date' });
+      
+      expect(result).toHaveProperty('formatted');
+      expect(result).toHaveProperty('timestamp');
+    });
+
+    it('应该支持 time 格式', async () => {
+      const result = await timeToolObj.execute({ format: 'time' });
+      
+      expect(result).toHaveProperty('formatted');
+      expect(result).toHaveProperty('timestamp');
+    });
+
+    it('应该支持 timestamp 格式', async () => {
+      const result = await timeToolObj.execute({ format: 'timestamp' });
+      
+      expect(result).toHaveProperty('timestamp');
+      expect(result).toHaveProperty('iso');
+      expect(result).not.toHaveProperty('formatted');
+    });
+
+    it('应该支持指定时区', async () => {
+      const result = await timeToolObj.execute({ timezone: 'UTC' });
+      
+      expect(result).toHaveProperty('formatted');
+      expect(result).toHaveProperty('timestamp');
+    });
+
+    it('时间戳应该是有效的数字', async () => {
+      const result = await timeToolObj.execute({});
+      const now = Date.now();
+      
+      // 时间戳应该在合理范围内（前后 1 秒）
+      expect(result.timestamp).toBeGreaterThan(now - 1000);
+      expect(result.timestamp).toBeLessThan(now + 1000);
+    });
+  });
+
+  describe('搜索工具', () => {
+    it('应该有正确的元数据', () => {
+      const searchToolObj = searchTool.toTool();
+      
+      expect(searchToolObj.name).toBe('web_search');
+      expect(searchToolObj.description).toContain('搜索');
+      expect(searchToolObj.parameters.properties).toHaveProperty('query');
+      expect(searchToolObj.parameters.required).toContain('query');
+    });
+
+    it('未配置搜索函数时应返回错误', async () => {
+      const searchToolObj = searchTool.toTool();
+      const result = await searchToolObj.execute({ query: 'test' });
+      
+      expect(result.error).toBeDefined();
+      expect(result.query).toBe('test');
+    });
+  });
+
+  describe('代码执行工具', () => {
+    const codeRunnerObj = codeRunnerTool.toTool();
+
+    it('应该有正确的元数据', () => {
+      expect(codeRunnerObj.name).toBe('run_code');
+      expect(codeRunnerObj.description).toContain('JavaScript');
+      expect(codeRunnerObj.parameters.properties).toHaveProperty('code');
+      expect(codeRunnerObj.parameters.required).toContain('code');
+    });
+
+    it('应该执行简单表达式', async () => {
+      const result = await codeRunnerObj.execute({ code: 'return 1 + 2' });
+      
+      expect(result.success).toBe(true);
+      expect(result.result).toBe('3');
+    });
+
+    it('应该执行字符串操作', async () => {
+      const result = await codeRunnerObj.execute({ code: 'return "hello".toUpperCase()' });
+      
+      expect(result.success).toBe(true);
+      expect(result.result).toBe('HELLO');
+    });
+
+    it('应该执行数组操作', async () => {
+      const result = await codeRunnerObj.execute({ code: 'return [1,2,3].map(x => x * 2)' });
+      
+      expect(result.success).toBe(true);
+      // 数组转字符串时会变成 "2,4,6"
+      expect(result.result).toContain('2,4,6');
+    });
+
+    it('应该处理 undefined 返回值', async () => {
+      const result = await codeRunnerObj.execute({ code: 'let x = 1' });
+      
+      expect(result.success).toBe(true);
+      expect(result.result).toBe('undefined');
+    });
+
+    it('应该处理语法错误', async () => {
+      const result = await codeRunnerObj.execute({ code: 'return {{{' });
+      
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+
+    it('应该处理运行时错误', async () => {
+      const result = await codeRunnerObj.execute({ code: 'throw new Error("test error")' });
+      
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('test error');
+    });
+  });
+
+  describe('HTTP 请求工具', () => {
+    const httpToolObj = httpTool.toTool();
+
+    it('应该有正确的元数据', () => {
+      expect(httpToolObj.name).toBe('http_request');
+      expect(httpToolObj.description).toContain('HTTP');
+      expect(httpToolObj.parameters.properties).toHaveProperty('url');
+      expect(httpToolObj.parameters.properties).toHaveProperty('method');
+      expect(httpToolObj.parameters.required).toContain('url');
+    });
+
+    it('应该处理无效 URL', async () => {
+      const result = await httpToolObj.execute({ url: 'invalid-url' });
+      
+      expect(result.error).toBeDefined();
+    });
+
+    it('应该支持 method 参数', () => {
+      const methodProp = httpToolObj.parameters.properties?.method;
+      
+      expect(methodProp).toBeDefined();
+      expect(methodProp?.type).toBe('string');
+      // 描述中应该包含支持的方法
+      expect(methodProp?.description).toContain('GET');
+      expect(methodProp?.description).toContain('POST');
+      expect(methodProp?.description).toContain('PUT');
+      expect(methodProp?.description).toContain('DELETE');
+    });
+  });
+
+  describe('getBuiltinTools', () => {
+    it('应该返回内置工具列表', () => {
+      const tools = getBuiltinTools();
+      
+      expect(Array.isArray(tools)).toBe(true);
+      expect(tools.length).toBeGreaterThan(0);
+      
+      // tools 现在是 ZhinTool 实例
+      const names = tools.map(t => t.name);
+      expect(names).toContain('calculator');
+      expect(names).toContain('get_time');
+    });
+
+    it('所有工具应该是 ZhinTool 实例', () => {
+      const tools = getBuiltinTools();
+      
+      for (const tool of tools) {
+        expect(tool).toBeInstanceOf(ZhinTool);
+        expect(tool.name).toBeDefined();
+        expect(tool.description).toBeDefined();
+      }
+    });
+
+    it('工具名称应该唯一', () => {
+      const tools = getBuiltinTools();
+      const names = tools.map(t => t.name);
+      const uniqueNames = [...new Set(names)];
+      
+      expect(names.length).toBe(uniqueNames.length);
+    });
+
+    it('所有工具应该能转换为 Tool 对象', () => {
+      const tools = getBuiltinTools();
+      
+      for (const tool of tools) {
+        const toolObj = tool.toTool();
+        
+        expect(toolObj).toHaveProperty('name');
+        expect(toolObj).toHaveProperty('description');
+        expect(toolObj).toHaveProperty('parameters');
+        expect(toolObj).toHaveProperty('execute');
+        expect(typeof toolObj.name).toBe('string');
+        expect(typeof toolObj.description).toBe('string');
+        expect(typeof toolObj.execute).toBe('function');
+        expect(toolObj.parameters).toHaveProperty('type');
+        expect(toolObj.parameters.type).toBe('object');
+      }
+    });
+  });
+});

package/tests/ai/user-profile.test.ts

@@ -0,0 +1,73 @@
+/**
+ * UserProfileStore 测试
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { UserProfileStore } from '../../src/ai/user-profile.js';
+
+describe('UserProfileStore（内存模式）', () => {
+  let store: UserProfileStore;
+
+  beforeEach(() => {
+    store = new UserProfileStore();
+  });
+
+  it('初始 get 应返回 null', async () => {
+    expect(await store.get('u1', 'name')).toBeNull();
+  });
+
+  it('set 后应能 get', async () => {
+    await store.set('u1', 'name', '小明');
+    expect(await store.get('u1', 'name')).toBe('小明');
+  });
+
+  it('getAll 应返回所有键值', async () => {
+    await store.set('u1', 'name', '小明');
+    await store.set('u1', 'style', '简洁');
+    const all = await store.getAll('u1');
+    expect(all).toEqual({ name: '小明', style: '简洁' });
+  });
+
+  it('getAll 不存在的用户应返回空对象', async () => {
+    expect(await store.getAll('nonexistent')).toEqual({});
+  });
+
+  it('delete 已有键应返回 true', async () => {
+    await store.set('u1', 'name', '小明');
+    const result = await store.delete('u1', 'name');
+    expect(result).toBe(true);
+    expect(await store.get('u1', 'name')).toBeNull();
+  });
+
+  it('delete 不存在的键应返回 false', async () => {
+    expect(await store.delete('u1', 'nonexistent')).toBe(false);
+  });
+
+  it('不同用户数据应隔离', async () => {
+    await store.set('u1', 'name', '小明');
+    await store.set('u2', 'name', '小红');
+    expect(await store.get('u1', 'name')).toBe('小明');
+    expect(await store.get('u2', 'name')).toBe('小红');
+  });
+
+  describe('buildProfileSummary', () => {
+    it('无数据应返回空字符串', async () => {
+      expect(await store.buildProfileSummary('u1')).toBe('');
+    });
+
+    it('有数据应生成摘要', async () => {
+      await store.set('u1', 'name', '小明');
+      await store.set('u1', 'interests', '编程');
+      const summary = await store.buildProfileSummary('u1');
+      expect(summary).toContain('[用户画像]');
+      expect(summary).toContain('name: 小明');
+      expect(summary).toContain('interests: 编程');
+    });
+  });
+
+  it('dispose 应清理数据', async () => {
+    await store.set('u1', 'name', '小明');
+    store.dispose();
+    // dispose 后重新获取，内存实现应清空
+    expect(await store.get('u1', 'name')).toBeNull();
+  });
+});

package/tests/ai/zhin-agent.test.ts

@@ -0,0 +1,177 @@
+/**
+ * ZhinAgent 补全测试
+ * 
+ * 测试 collectTools 逻辑、handleMessage 端到端流程、会话管理等
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ZhinAgent } from '../../src/ai/zhin-agent.js';
+import { SkillFeature } from '../../src/built/skill.js';
+import type { AIProvider, ChatResponse, AgentTool } from '../../src/ai/types.js';
+import type { Tool, ToolContext } from '../../src/types.js';
+
+// Mock AIProvider
+function createMockProvider(response: string = '你好！'): AIProvider {
+  return {
+    name: 'mock',
+    models: ['mock-model'],
+    chat: vi.fn(async () => ({
+      choices: [{ message: { role: 'assistant' as const, content: response }, finish_reason: 'stop' }],
+    } as ChatResponse)),
+    listModels: vi.fn(async () => ['mock-model']),
+  };
+}
+
+function makeToolContext(overrides: Partial<ToolContext> = {}): ToolContext {
+  return {
+    platform: 'test',
+    botId: 'bot1',
+    sceneId: 'scene1',
+    senderId: 'user1',
+    ...overrides,
+  };
+}
+
+function makeTool(name: string, desc: string = '', opts: Partial<Tool> = {}): Tool {
+  return {
+    name,
+    description: desc,
+    parameters: { type: 'object', properties: {} },
+    execute: vi.fn(async () => `result of ${name}`),
+    ...opts,
+  };
+}
+
+describe('ZhinAgent', () => {
+  let agent: ZhinAgent;
+  let provider: AIProvider;
+
+  beforeEach(() => {
+    provider = createMockProvider();
+    agent = new ZhinAgent(provider, {
+      persona: '测试助手',
+      maxIterations: 3,
+    });
+  });
+
+  afterEach(() => {
+    agent.dispose();
+  });
+
+  describe('构造', () => {
+    it('应正确初始化', () => {
+      expect(agent).toBeDefined();
+    });
+  });
+
+  describe('依赖注入', () => {
+    it('setSkillRegistry 应正常工作', () => {
+      const registry = new SkillFeature();
+      expect(() => agent.setSkillRegistry(registry)).not.toThrow();
+    });
+
+    it('registerTool 应添加和移除工具', () => {
+      const tool: AgentTool = {
+        name: 'test_tool',
+        description: '测试',
+        parameters: { type: 'object', properties: {} },
+        execute: async () => 'ok',
+      };
+
+      const dispose = agent.registerTool(tool);
+      expect(typeof dispose).toBe('function');
+
+      // 移除
+      dispose();
+    });
+  });
+
+  describe('process', () => {
+    it('应处理简单文本消息并返回 OutputElement[]', async () => {
+      const context = makeToolContext();
+
+      const result = await agent.process(
+        '你好',
+        context,
+        [],
+      );
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBeGreaterThan(0);
+      expect(provider.chat).toHaveBeenCalled();
+    });
+
+    it('应传递工具列表', async () => {
+      const tools: Tool[] = [makeTool('get_time', '获取时间')];
+      const context = makeToolContext();
+
+      await agent.process('现在几点', context, tools);
+
+      // provider.chat 应被调用
+      expect(provider.chat).toHaveBeenCalled();
+    });
+
+    it('速率限制应生效', async () => {
+      // 创建一个严格限制的 agent
+      const strictAgent = new ZhinAgent(provider, {
+        rateLimit: { maxRequestsPerMinute: 1, cooldownSeconds: 5 },
+      });
+
+      const context = makeToolContext();
+
+      // 第一次请求
+      await strictAgent.process('hello', context, []);
+
+      // 第二次应被限制
+      const result = await strictAgent.process('hello again', context, []);
+      
+      // 被限制时应返回友好提示（OutputElement[]）
+      expect(result).toBeDefined();
+      expect(Array.isArray(result)).toBe(true);
+
+      strictAgent.dispose();
+    });
+  });
+
+  describe('collectTools 去重', () => {
+    it('应优先使用 Skill 中的工具', async () => {
+      const registry = new SkillFeature();
+      
+      // 注册一个 Skill 包含 tool_a
+      registry.add({
+        name: 'skill1',
+        description: '技能1',
+        tools: [makeTool('tool_a', '来自 skill 的工具', { keywords: ['天气'] })],
+        keywords: ['天气'],
+        pluginName: 'p1',
+      }, 'p1');
+
+      agent.setSkillRegistry(registry);
+
+      // 外部也传入 tool_a（同名）
+      const externalTools = [makeTool('tool_a', '来自外部的工具')];
+      const context = makeToolContext();
+
+      // 调用 process，两个同名工具应该只保留一个
+      await agent.process('查看天气', context, externalTools);
+
+      // provider.chat 应被调用（正常处理）
+      expect(provider.chat).toHaveBeenCalled();
+    });
+  });
+
+  describe('getUserProfiles', () => {
+    it('应返回 UserProfileStore 实例', () => {
+      const profiles = agent.getUserProfiles();
+      expect(profiles).toBeDefined();
+      expect(typeof profiles.get).toBe('function');
+      expect(typeof profiles.set).toBe('function');
+    });
+  });
+
+  describe('dispose', () => {
+    it('应正常清理资源', () => {
+      expect(() => agent.dispose()).not.toThrow();
+    });
+  });
+});

package/tests/config.test.ts

@@ -324,3 +324,49 @@ describe('ConfigLoader', () => {
     })
   })
 })
+
+// ============================================================================
+// ConfigFeature 补全测试
+// ============================================================================
+describe('ConfigFeature', () => {
+  let feature: import('../src/built/config.js').ConfigFeature
+
+  beforeEach(async () => {
+    const { ConfigFeature } = await import('../src/built/config.js')
+    feature = new ConfigFeature()
+  })
+
+  it('应有正确的元数据', () => {
+    expect(feature.name).toBe('config')
+    expect(feature.icon).toBe('Settings')
+    expect(feature.desc).toBe('配置')
+  })
+
+  it('add 应添加配置记录', () => {
+    const record = { key: 'debug', defaultValue: false }
+    const dispose = feature.add(record, 'test-plugin')
+    expect(feature.items).toHaveLength(1)
+    expect(feature.items[0]).toBe(record)
+    expect(typeof dispose).toBe('function')
+  })
+
+  it('toJSON 应返回正确结构', () => {
+    feature.add({ key: 'debug', defaultValue: false }, 'test-plugin')
+    feature.add({ key: 'port', defaultValue: 8080 }, 'test-plugin')
+
+    const json = feature.toJSON()
+    expect(json.name).toBe('config')
+    expect(json.count).toBe(2)
+    expect(json.items[0]).toEqual({ name: 'debug', defaultValue: false })
+    expect(json.items[1]).toEqual({ name: 'port', defaultValue: 8080 })
+  })
+
+  it('toJSON(pluginName) 应按插件过滤', () => {
+    feature.add({ key: 'a', defaultValue: 1 }, 'plugin-a')
+    feature.add({ key: 'b', defaultValue: 2 }, 'plugin-b')
+
+    const json = feature.toJSON('plugin-a')
+    expect(json.count).toBe(1)
+    expect(json.items[0].name).toBe('a')
+  })
+})