@zhin.js/agent 0.0.0

package/tests/ai/output.test.ts

@@ -0,0 +1,128 @@
+/**
+ * AI Output 模块测试
+ */
+import { describe, it, expect } from 'vitest';
+import { parseOutput, renderToPlainText, renderToSatori } from '@zhin.js/agent';
+
+describe('parseOutput', () => {
+  it('纯文本应返回单个 TextElement', () => {
+    const result = parseOutput('Hello, world!');
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({ type: 'text', content: 'Hello, world!', format: 'markdown' });
+  });
+
+  it('空字符串应返回空白 TextElement', () => {
+    const result = parseOutput('');
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({ type: 'text', content: '', format: 'plain' });
+  });
+
+  it('应解析图片 ![alt](url)', () => {
+    const result = parseOutput('看看这张图 ![cat](https://example.com/cat.png)');
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({ type: 'text', content: '看看这张图' });
+    expect(result[1]).toMatchObject({ type: 'image', url: 'https://example.com/cat.png', alt: 'cat' });
+  });
+
+  it('应解析音频 [audio](url)', () => {
+    const result = parseOutput('[audio](https://example.com/song.mp3)');
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({ type: 'audio', url: 'https://example.com/song.mp3' });
+  });
+
+  it('应解析视频 [video](url)', () => {
+    const result = parseOutput('这是视频 [video](https://example.com/video.mp4)');
+    expect(result).toHaveLength(2);
+    expect(result[1]).toMatchObject({ type: 'video', url: 'https://example.com/video.mp4' });
+  });
+
+  it('应解析文件 [file:name](url)', () => {
+    const result = parseOutput('[file:report.pdf](https://example.com/report.pdf)');
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({ type: 'file', url: 'https://example.com/report.pdf', name: 'report.pdf' });
+  });
+
+  it('应解析 card 代码块', () => {
+    const raw = '```card\n{"title":"天气","description":"晴天"}\n```';
+    const result = parseOutput(raw);
+    expect(result.some(el => el.type === 'card')).toBe(true);
+    const card = result.find(el => el.type === 'card')!;
+    expect(card).toMatchObject({ type: 'card', title: '天气', description: '晴天' });
+  });
+
+  it('无效 card JSON 应降级为文本', () => {
+    const raw = '```card\n{invalid json}\n```';
+    const result = parseOutput(raw);
+    expect(result.some(el => el.type === 'text')).toBe(true);
+  });
+
+  it('应处理混合内容', () => {
+    const raw = '看看这个 ![](https://img.png) 更多文字';
+    const result = parseOutput(raw);
+    expect(result.length).toBeGreaterThanOrEqual(2);
+    expect(result.some(el => el.type === 'image')).toBe(true);
+  });
+});
+
+describe('renderToPlainText', () => {
+  it('应渲染文本元素', () => {
+    expect(renderToPlainText([{ type: 'text', content: 'Hello' }])).toBe('Hello');
+  });
+
+  it('应渲染图片为 [图片: alt]', () => {
+    const result = renderToPlainText([{ type: 'image', url: 'url', alt: '猫' }]);
+    expect(result).toBe('[图片: 猫]');
+  });
+
+  it('应渲染音频的 fallbackText', () => {
+    const result = renderToPlainText([{ type: 'audio', url: 'url', fallbackText: '一段音乐' }]);
+    expect(result).toBe('一段音乐');
+  });
+
+  it('应渲染卡片标题和字段', () => {
+    const result = renderToPlainText([{
+      type: 'card',
+      title: '天气',
+      description: '晴天',
+      fields: [{ label: '温度', value: '25°C' }],
+    }]);
+    expect(result).toContain('天气');
+    expect(result).toContain('晴天');
+    expect(result).toContain('温度: 25°C');
+  });
+
+  it('应渲染文件为 [文件: name]', () => {
+    const result = renderToPlainText([{ type: 'file', url: 'url', name: 'report.pdf' }]);
+    expect(result).toContain('[文件: report.pdf]');
+  });
+});
+
+describe('renderToSatori', () => {
+  it('应将文本包裹在 <p> 标签中', () => {
+    const result = renderToSatori([{ type: 'text', content: 'Hello' }]);
+    expect(result).toBe('<p>Hello</p>');
+  });
+
+  it('应生成 <img> 标签', () => {
+    const result = renderToSatori([{ type: 'image', url: 'https://img.png', alt: '猫' }]);
+    expect(result).toContain('<img');
+    expect(result).toContain('alt="猫"');
+  });
+
+  it('应转义 HTML 特殊字符', () => {
+    const result = renderToSatori([{ type: 'text', content: '<script>alert("xss")</script>' }]);
+    expect(result).not.toContain('<script>');
+    expect(result).toContain('&lt;script&gt;');
+  });
+
+  it('应渲染卡片结构', () => {
+    const result = renderToSatori([{
+      type: 'card',
+      title: '标题',
+      description: '描述',
+    }]);
+    expect(result).toContain('<div class="card">');
+    expect(result).toContain('<h3>标题</h3>');
+    expect(result).toContain('<p>描述</p>');
+  });
+});

package/tests/ai/rate-limiter.test.ts

@@ -0,0 +1,108 @@
+/**
+ * RateLimiter 测试
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { RateLimiter } from '@zhin.js/agent';
+
+describe('RateLimiter', () => {
+  let limiter: RateLimiter;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    limiter?.dispose();
+    vi.useRealTimers();
+  });
+
+  it('应允许正常请求', () => {
+    limiter = new RateLimiter({ maxRequestsPerMinute: 5 });
+    const result = limiter.check('user1');
+    expect(result.allowed).toBe(true);
+    expect(result.message).toBeUndefined();
+  });
+
+  it('应在超过限制后拒绝请求', () => {
+    limiter = new RateLimiter({ maxRequestsPerMinute: 3, cooldownSeconds: 5 });
+
+    // 发送 3 个请求（达到限制）
+    limiter.check('user1');
+    limiter.check('user1');
+    limiter.check('user1');
+
+    // 第 4 个请求应被拒绝
+    const result = limiter.check('user1');
+    expect(result.allowed).toBe(false);
+    expect(result.message).toBeDefined();
+    expect(result.retryAfterSeconds).toBe(5);
+  });
+
+  it('冷却期结束后应允许请求', () => {
+    limiter = new RateLimiter({ maxRequestsPerMinute: 2, cooldownSeconds: 5 });
+
+    limiter.check('user1');
+    limiter.check('user1');
+    limiter.check('user1'); // 触发冷却
+
+    // 推进 6 秒
+    vi.advanceTimersByTime(6000);
+
+    // 推进超过 1 分钟让滑动窗口清空旧记录
+    vi.advanceTimersByTime(60000);
+
+    const result = limiter.check('user1');
+    expect(result.allowed).toBe(true);
+  });
+
+  it('不同用户应独立计数', () => {
+    limiter = new RateLimiter({ maxRequestsPerMinute: 2 });
+
+    limiter.check('user1');
+    limiter.check('user1');
+    const user1Result = limiter.check('user1'); // 超限
+
+    const user2Result = limiter.check('user2'); // 新用户
+    expect(user1Result.allowed).toBe(false);
+    expect(user2Result.allowed).toBe(true);
+  });
+
+  it('滑动窗口应在 1 分钟后清理旧记录', () => {
+    limiter = new RateLimiter({ maxRequestsPerMinute: 2 });
+
+    limiter.check('user1');
+    limiter.check('user1');
+
+    // 推进 61 秒
+    vi.advanceTimersByTime(61000);
+
+    // 旧记录清理后应允许
+    const result = limiter.check('user1');
+    expect(result.allowed).toBe(true);
+  });
+
+  it('dispose 应清理所有资源', () => {
+    limiter = new RateLimiter();
+    limiter.check('user1');
+    limiter.dispose();
+
+    // dispose 后内部 buckets 应清空
+    const result = limiter.check('user1');
+    expect(result.allowed).toBe(true); // 重新开始计数
+  });
+
+  it('在冷却期内请求应返回等待秒数', () => {
+    limiter = new RateLimiter({ maxRequestsPerMinute: 1, cooldownSeconds: 10 });
+
+    limiter.check('user1');
+    limiter.check('user1'); // 触发冷却
+
+    // 推进 3 秒
+    vi.advanceTimersByTime(3000);
+
+    const result = limiter.check('user1');
+    expect(result.allowed).toBe(false);
+    expect(result.retryAfterSeconds).toBeLessThanOrEqual(10);
+    expect(result.retryAfterSeconds).toBeGreaterThan(0);
+  });
+});

package/tests/ai/session.test.ts

@@ -0,0 +1,334 @@
+/**
+ * Session Manager 测试
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock('@zhin.js/core', async (importOriginal) => {
+  const original = await importOriginal() as any;
+  return {
+    ...original,
+    Logger: class {
+      debug = vi.fn();
+      info = vi.fn();
+      warn = vi.fn();
+      error = vi.fn();
+    },
+  };
+});
+
+import {
+  MemorySessionManager,
+  DatabaseSessionManager,
+  SessionManager,
+  createMemorySessionManager,
+} from '@zhin.js/agent';
+
+describe('MemorySessionManager', () => {
+  let manager: MemorySessionManager;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    manager = new MemorySessionManager({
+      maxHistory: 10,
+      expireMs: 60000,
+    });
+  });
+
+  afterEach(() => {
+    manager.dispose();
+    vi.useRealTimers();
+  });
+
+  describe('会话创建', () => {
+    it('应该创建新会话', () => {
+      const session = manager.get('user-1');
+      expect(session).toBeDefined();
+      expect(session.id).toBe('user-1');
+      expect(session.messages).toEqual([]);
+    });
+
+    it('应该返回已存在的会话', () => {
+      const session1 = manager.get('user-1');
+      manager.addMessage('user-1', { role: 'user', content: 'test' });
+      const session2 = manager.get('user-1');
+      expect(session2.messages).toHaveLength(1);
+    });
+
+    it('不同用户应该有不同的会话', () => {
+      const session1 = manager.get('user-1');
+      const session2 = manager.get('user-2');
+      expect(session1.id).not.toBe(session2.id);
+    });
+  });
+
+  describe('消息历史', () => {
+    it('应该添加消息到历史', () => {
+      manager.addMessage('user-1', { role: 'user', content: '你好' });
+      manager.addMessage('user-1', { role: 'assistant', content: '你好！有什么可以帮你的？' });
+      const messages = manager.getMessages('user-1');
+      expect(messages).toHaveLength(2);
+      expect(messages[0].role).toBe('user');
+      expect(messages[1].role).toBe('assistant');
+    });
+
+    it('应该限制历史记录数量', () => {
+      for (let i = 0; i < 15; i++) {
+        manager.addMessage('user-1', { role: 'user', content: `消息 ${i}` });
+      }
+      const messages = manager.getMessages('user-1');
+      expect(messages.length).toBeLessThanOrEqual(10);
+    });
+
+    it('系统消息应该保留', () => {
+      manager.setSystemPrompt('user-1', '你是一个助手');
+      for (let i = 0; i < 15; i++) {
+        manager.addMessage('user-1', { role: 'user', content: `消息 ${i}` });
+      }
+      const messages = manager.getMessages('user-1');
+      const systemMessages = messages.filter((m: { role: string }) => m.role === 'system');
+      expect(systemMessages.length).toBe(1);
+    });
+  });
+
+  describe('系统提示', () => {
+    it('应该设置系统提示', () => {
+      manager.setSystemPrompt('user-1', '你是一个助手');
+      const messages = manager.getMessages('user-1');
+      expect(messages[0].role).toBe('system');
+      expect(messages[0].content).toBe('你是一个助手');
+    });
+
+    it('应该替换旧的系统提示', () => {
+      manager.setSystemPrompt('user-1', '旧提示');
+      manager.setSystemPrompt('user-1', '新提示');
+      const messages = manager.getMessages('user-1');
+      const systemMessages = messages.filter((m: { role: string }) => m.role === 'system');
+      expect(systemMessages.length).toBe(1);
+      expect(systemMessages[0].content).toBe('新提示');
+    });
+  });
+
+  describe('会话清理', () => {
+    it('应该清除指定会话', () => {
+      manager.get('user-1');
+      manager.addMessage('user-1', { role: 'user', content: 'test' });
+      expect(manager.clear('user-1')).toBe(true);
+      expect(manager.has('user-1')).toBe(false);
+    });
+
+    it('清除不存在的会话应返回 false', () => {
+      expect(manager.clear('nonexistent')).toBe(false);
+    });
+
+    it('reset 应该保留系统消息', () => {
+      manager.setSystemPrompt('user-1', '系统提示');
+      manager.addMessage('user-1', { role: 'user', content: 'test' });
+      manager.reset('user-1');
+      const messages = manager.getMessages('user-1');
+      expect(messages.length).toBe(1);
+      expect(messages[0].role).toBe('system');
+    });
+  });
+
+  describe('会话超时', () => {
+    it('应该在超时后清理会话', () => {
+      manager.get('user-1');
+      expect(manager.has('user-1')).toBe(true);
+      vi.advanceTimersByTime(61000);
+      manager.cleanup();
+      expect(manager.has('user-1')).toBe(false);
+    });
+
+    it('活动会话不应该被清理', () => {
+      manager.get('user-1');
+      vi.advanceTimersByTime(30000);
+      manager.addMessage('user-1', { role: 'user', content: '新消息' });
+      vi.advanceTimersByTime(30000);
+      manager.cleanup();
+      expect(manager.has('user-1')).toBe(true);
+    });
+  });
+
+  describe('统计信息', () => {
+    it('应该返回正确的统计信息', () => {
+      manager.get('user-1');
+      manager.get('user-2');
+      const stats = manager.getStats();
+      expect(stats.total).toBe(2);
+      expect(stats.active).toBe(2);
+      expect(stats.expired).toBe(0);
+    });
+
+    it('应该返回会话列表', () => {
+      manager.get('user-1');
+      manager.get('user-2');
+      manager.get('user-3');
+      const sessions = manager.listSessions();
+      expect(sessions).toContain('user-1');
+      expect(sessions).toContain('user-2');
+      expect(sessions).toContain('user-3');
+    });
+  });
+
+  describe('dispose', () => {
+    it('应该清理所有会话', () => {
+      manager.get('user-1');
+      manager.get('user-2');
+      manager.dispose();
+      expect(manager.has('user-1')).toBe(false);
+      expect(manager.has('user-2')).toBe(false);
+    });
+  });
+});
+
+describe('SessionManager', () => {
+  describe('generateId', () => {
+    it('应该生成正确的会话 ID（带频道）', () => {
+      const id = SessionManager.generateId('qq', 'user123', 'channel456');
+      expect(id).toBe('qq:channel456:user123');
+    });
+
+    it('应该生成正确的会话 ID（无频道）', () => {
+      const id = SessionManager.generateId('telegram', 'user123');
+      expect(id).toBe('telegram:user123');
+    });
+  });
+});
+
+describe('createMemorySessionManager', () => {
+  it('应该创建 SessionManager 实例', () => {
+    const manager = createMemorySessionManager({ maxHistory: 50 });
+    expect(manager).toBeDefined();
+    expect(manager.get).toBeDefined();
+    manager.dispose();
+  });
+});
+
+describe('DatabaseSessionManager', () => {
+  function createMockModel(records: any[] = []) {
+    return {
+      select: vi.fn().mockReturnValue({
+        where: vi.fn().mockResolvedValue(records),
+      }),
+      create: vi.fn().mockResolvedValue(undefined),
+      update: vi.fn().mockReturnValue({
+        where: vi.fn().mockResolvedValue(undefined),
+      }),
+      delete: vi.fn().mockReturnValue({
+        where: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+  }
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('loadSession JSON 解析', () => {
+    it('应该解析字符串形式的 messages (JSON)', async () => {
+      const messagesJson = JSON.stringify([
+        { role: 'user', content: 'hello' },
+        { role: 'assistant', content: 'hi there' },
+      ]);
+      const model = createMockModel([{
+        session_id: 'test-1',
+        messages: messagesJson,
+        config: JSON.stringify({ provider: 'ollama' }),
+        created_at: 1000,
+        updated_at: 2000,
+      }]);
+
+      const manager = new DatabaseSessionManager(model);
+      const session = await manager.get('test-1');
+
+      expect(Array.isArray(session.messages)).toBe(true);
+      expect(session.messages).toHaveLength(2);
+      expect(session.messages[0]).toEqual({ role: 'user', content: 'hello' });
+      manager.dispose();
+    });
+
+    it('应该解析字符串形式的 config (JSON)', async () => {
+      const model = createMockModel([{
+        session_id: 'test-2',
+        messages: '[]',
+        config: '{"provider":"ollama","maxHistory":100}',
+        created_at: 1000,
+        updated_at: 2000,
+      }]);
+
+      const manager = new DatabaseSessionManager(model);
+      const session = await manager.get('test-2');
+
+      expect(typeof session.config).toBe('object');
+      expect(session.config).toEqual({ provider: 'ollama', maxHistory: 100 });
+      manager.dispose();
+    });
+
+    it('messages 已是数组时不应二次解析', async () => {
+      const messagesArray = [{ role: 'system', content: 'You are a bot' }];
+      const model = createMockModel([{
+        session_id: 'test-3',
+        messages: messagesArray,
+        config: { provider: 'openai' },
+        created_at: 1000,
+        updated_at: 2000,
+      }]);
+
+      const manager = new DatabaseSessionManager(model);
+      const session = await manager.get('test-3');
+
+      expect(session.messages).toBe(messagesArray);
+      expect(session.config).toEqual({ provider: 'openai' });
+      manager.dispose();
+    });
+
+    it('加载后的 messages 应支持 push 操作', async () => {
+      const model = createMockModel([{
+        session_id: 'test-4',
+        messages: '[{"role":"user","content":"hi"}]',
+        config: '{"provider":"openai"}',
+        created_at: 1000,
+        updated_at: 2000,
+      }]);
+
+      const manager = new DatabaseSessionManager(model);
+      await manager.addMessage('test-4', { role: 'assistant', content: 'hello!' });
+
+      const session = await manager.get('test-4');
+      expect(session.messages).toHaveLength(2);
+      expect(session.messages[1]).toEqual({ role: 'assistant', content: 'hello!' });
+      manager.dispose();
+    });
+
+    it('messages 或 config 为 null/undefined 时应使用默认值', async () => {
+      const model = createMockModel([{
+        session_id: 'test-5',
+        messages: null,
+        config: null,
+        created_at: 1000,
+        updated_at: 2000,
+      }]);
+
+      const manager = new DatabaseSessionManager(model);
+      const session = await manager.get('test-5');
+
+      expect(Array.isArray(session.messages)).toBe(true);
+      expect(session.messages).toHaveLength(0);
+      expect(session.config).toEqual({ provider: 'openai' });
+      manager.dispose();
+    });
+  });
+
+  describe('新会话创建', () => {
+    it('数据库无记录时应创建新会话', async () => {
+      const model = createMockModel([]);
+      const manager = new DatabaseSessionManager(model);
+      const session = await manager.get('new-session');
+
+      expect(session.id).toBe('new-session');
+      expect(Array.isArray(session.messages)).toBe(true);
+      expect(session.messages).toHaveLength(0);
+      manager.dispose();
+    });
+  });
+});