@zhin.js/core 1.0.16 → 1.0.18

package/test/minimal-bot.ts

@@ -0,0 +1,31 @@
+import { App } from '../src/app';
+import { LogLevel } from '@zhin.js/logger';
+import { fileURLToPath } from 'url';
+import * as path from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function runMinimalBot() {
+    const app = new App({
+        log_level: LogLevel.INFO,
+        plugin_dirs: [path.join(__dirname, 'plugins')],
+        plugins: [],
+        bots: [],
+        debug: true
+    });
+
+    console.log('Starting Minimal Bot...');
+    await app.start();
+    console.log('Minimal Bot Started');
+
+    // Simulate a message
+    // await app.receiveMessage(...)
+    
+    await app.stop();
+}
+
+if (process.argv[1] === __filename) {
+    runMinimalBot().catch(console.error);
+}
+

package/test/stress-test.ts

@@ -0,0 +1,123 @@
+import { App } from '../src/app';
+import { LogLevel } from '@zhin.js/logger';
+import { fileURLToPath } from 'url';
+import * as path from 'path';
+import * as fs from 'fs';
+// import { Message } from '../src/message'; // Message is a type/namespace, not a class
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function runStressTest() {
+    const PLUGIN_COUNT = 50;
+    const MSG_COUNT = 10000;
+    const WORK_DIR = path.join(__dirname, 'stress_plugins');
+
+    console.log('Starting Core Stress Test');
+    
+    // Setup workspace
+    if (fs.existsSync(WORK_DIR)) fs.rmSync(WORK_DIR, { recursive: true, force: true });
+    fs.mkdirSync(WORK_DIR, { recursive: true });
+
+    // Generate plugins
+    let loadedCount = 0;
+    for (let i = 0; i < PLUGIN_COUNT; i++) {
+        fs.writeFileSync(path.join(WORK_DIR, `plugin-${i}.ts`), `
+            import { useContext } from '${path.resolve(__dirname, '../src/plugin').replace(/\\/g, '/')}';
+            
+            export function install(ctx) {
+                ctx.on('message.receive', (msg) => {
+                    // console.log('Plugin ${i} received message');
+                });
+                
+                ctx.middleware(async (msg, next) => {
+                    await next();
+                });
+            }
+        `);
+    }
+
+    const CONFIG_FILE = path.join(WORK_DIR, 'zhin.test.yaml');
+    // Write config to file to avoid reload overriding it with defaults
+    const config = {
+        log_level: LogLevel.WARN,
+        plugin_dirs: [WORK_DIR],
+        plugins: Array.from({ length: PLUGIN_COUNT }, (_, i) => `plugin-${i}`),
+        bots: [],
+        debug: false
+    };
+    
+    // Simple YAML stringify since we can't require 'yaml' easily in ESM without import
+    const yamlString = `
+log_level: ${config.log_level}
+debug: ${config.debug}
+plugin_dirs:
+${config.plugin_dirs.map(d => `  - ${d}`).join('\n')}
+plugins:
+${config.plugins.map(p => `  - ${p}`).join('\n')}
+bots: []
+    `;
+    
+    fs.writeFileSync(CONFIG_FILE, yamlString);
+
+    const app = new App(CONFIG_FILE);
+
+    console.log('Starting App...');
+    const startBoot = performance.now();
+    await app.start();
+    console.log(`App started in ${(performance.now() - startBoot).toFixed(2)}ms`);
+    
+    // Verify plugins loaded
+    const loadedPlugins = app.hmrManager.dependencyList.length; // App itself + plugins
+    console.log(`Loaded Dependencies: ${loadedPlugins}`);
+    if (loadedPlugins < PLUGIN_COUNT) {
+        console.warn(`WARNING: Only ${loadedPlugins} dependencies loaded (expected >= ${PLUGIN_COUNT})`);
+    }
+
+    const initialMem = process.memoryUsage();
+    console.log(`Initial RSS: ${(initialMem.rss / 1024 / 1024).toFixed(2)} MB`);
+
+    console.log(`Sending ${MSG_COUNT} messages...`);
+    const startMsg = performance.now();
+    
+    // Mock message factory
+    const createMockMsg = (id: number) => ({
+        $id: `msg-${id}`,
+        $adapter: 'mock',
+        $bot: 'bot1',
+        $content: [{ type: 'text', data: { text: 'hello' } }],
+        $sender: { id: 'user1' },
+        $channel: { id: 'group1', type: 'group' as const },
+        $timestamp: Date.now(),
+        $raw: 'hello',
+        $reply: async () => 'reply-id',
+        $recall: async () => {},
+        // Custom fields usually added by adapters
+        raw_message: 'hello',
+        message_type: 'group',
+        sender: { id: 'user1' },
+    });
+
+    for (let i = 0; i < MSG_COUNT; i++) {
+        const msg = createMockMsg(i);
+        await app.receiveMessage(msg as any);
+        
+        if (i % 1000 === 0) {
+            const mem = process.memoryUsage();
+            process.stdout.write(`\rMsgs: ${i}, RSS: ${(mem.rss / 1024 / 1024).toFixed(2)} MB`);
+        }
+    }
+    
+    console.log(`\nProcessed ${MSG_COUNT} messages in ${(performance.now() - startMsg).toFixed(2)}ms`);
+    console.log(`Avg: ${((performance.now() - startMsg) / MSG_COUNT).toFixed(3)}ms/msg`);
+
+    const finalMem = process.memoryUsage();
+    console.log(`Final RSS: ${(finalMem.rss / 1024 / 1024).toFixed(2)} MB`);
+    console.log(`Memory Delta: ${((finalMem.rss - initialMem.rss) / 1024 / 1024).toFixed(2)} MB`);
+
+    await app.stop();
+    fs.rmSync(WORK_DIR, { recursive: true, force: true });
+}
+
+runStressTest().catch(console.error);
+

package/tests/command.test.ts

@@ -49,55 +49,58 @@ vi.mock('segment-matcher', () => {
 })
 
 // Mock App with permissions
+const mockPermissionService = {
+  check: vi.fn(async (perm: string, message: any) => {
+    if (perm === 'adapter(discord)') {
+      return message.$adapter === 'discord'
+    }
+    if (perm === 'adapter(telegram)') {
+      return message.$adapter === 'telegram'
+    }
+    if (perm === 'adapter(email)') {
+      return message.$adapter === 'email'
+    }
+    if (perm === 'adapter(test)') {
+      return message.$adapter === 'test'
+    }
+    return true
+  })
+}
+
 const mockApp = {
-  permissions: {
-    get: vi.fn((permission: string) => {
-      // Mock permit checker
-      return {
-        check: vi.fn(async (perm: string, message: any) => {
-          if (permission === 'adapter(discord)') {
-            return message.$adapter === 'discord'
-          }
-          if (permission === 'adapter(telegram)') {
-            return message.$adapter === 'telegram'
-          }
-          if (permission === 'adapter(email)') {
-            return message.$adapter === 'email'
-          }
-          if (permission === 'adapter(test)') {
-            return message.$adapter === 'test'
-          }
-          return true
-        })
-      }
-    })
-  }
+  contextIsReady: vi.fn((name: string) => name === 'permission'),
+  inject: vi.fn((name: string) => {
+    if (name === 'permission') return mockPermissionService
+    return null
+  })
 } as any
 
 // 为多个权限测试创建特殊的 mock app
+const multiPermitPermissionService = {
+  check: vi.fn(async (perm: string, message: any) => {
+    // 对于多个权限，只要有一个匹配就返回 true
+    if (perm === 'adapter(discord)' && message.$adapter === 'discord') {
+      return true
+    }
+    if (perm === 'adapter(telegram)' && message.$adapter === 'telegram') {
+      return true
+    }
+    if (perm === 'adapter(email)' && message.$adapter === 'email') {
+      return true
+    }
+    if (perm === 'adapter(test)' && message.$adapter === 'test') {
+      return true
+    }
+    return false
+  })
+}
+
 const multiPermitMockApp = {
-  permissions: {
-    get: vi.fn((permission: string) => {
-      return {
-        check: vi.fn(async (perm: string, message: any) => {
-          // 对于多个权限，只要有一个匹配就返回 true
-          if (permission === 'adapter(discord)' && message.$adapter === 'discord') {
-            return true
-          }
-          if (permission === 'adapter(telegram)' && message.$adapter === 'telegram') {
-            return true
-          }
-          if (permission === 'adapter(email)' && message.$adapter === 'email') {
-            return true
-          }
-          if (permission === 'adapter(test)' && message.$adapter === 'test') {
-            return true
-          }
-          return false
-        })
-      }
-    })
-  }
+  contextIsReady: vi.fn((name: string) => name === 'permission'),
+  inject: vi.fn((name: string) => {
+    if (name === 'permission') return multiPermitPermissionService
+    return null
+  })
 } as any
 
 describe('Command系统测试', () => {
@@ -611,6 +614,83 @@ describe('Command系统测试', () => {
     })
   })
 
+  describe('帮助系统测试', () => {
+    it('应该正确设置和获取描述信息', () => {
+      const command = new MessageCommand('help')
+        .desc('这是命令描述', '可以有多行描述')
+
+      expect(command.helpInfo.desc).toEqual(['这是命令描述', '可以有多行描述'])
+    })
+
+    it('应该正确设置和获取用法信息', () => {
+      const command = new MessageCommand('help')
+        .usage('help', 'help <command>')
+
+      expect(command.helpInfo.usage).toEqual(['help', 'help <command>'])
+    })
+
+    it('应该正确设置和获取示例信息', () => {
+      const command = new MessageCommand('help')
+        .examples('help', 'help echo', 'help admin')
+
+      expect(command.helpInfo.examples).toEqual(['help', 'help echo', 'help admin'])
+    })
+
+    it('应该支持链式调用设置帮助信息', () => {
+      const command = new MessageCommand('test')
+        .desc('测试命令', '用于测试功能')
+        .usage('test', 'test <arg>')
+        .examples('test', 'test hello')
+        .action(() => 'Test response')
+
+      expect(command.helpInfo.pattern).toBe('test')
+      expect(command.helpInfo.desc).toEqual(['测试命令', '用于测试功能'])
+      expect(command.helpInfo.usage).toEqual(['test', 'test <arg>'])
+      expect(command.helpInfo.examples).toEqual(['test', 'test hello'])
+    })
+
+    it('应该正确生成帮助文本', () => {
+      const command = new MessageCommand('greet')
+        .desc('打招呼命令')
+        .usage('greet <name>')
+        .examples('greet Alice')
+
+      const help = command.help
+      
+      expect(help).toContain('greet')
+      expect(help).toContain('打招呼命令')
+      expect(help).toContain('greet <name>')
+      expect(help).toContain('greet Alice')
+    })
+
+    it('应该处理没有帮助信息的情况', () => {
+      const command = new MessageCommand('simple')
+
+      expect(command.helpInfo.desc).toEqual([])
+      expect(command.helpInfo.usage).toEqual([])
+      expect(command.helpInfo.examples).toEqual([])
+      expect(command.help).toBe('simple')
+    })
+
+    it('应该正确返回 helpInfo 对象结构', () => {
+      const command = new MessageCommand('info')
+        .desc('信息命令')
+        .usage('info')
+        .examples('info')
+
+      const helpInfo = command.helpInfo
+
+      expect(helpInfo).toHaveProperty('pattern')
+      expect(helpInfo).toHaveProperty('desc')
+      expect(helpInfo).toHaveProperty('usage')
+      expect(helpInfo).toHaveProperty('examples')
+      expect(typeof helpInfo.pattern).toBe('string')
+      expect(Array.isArray(helpInfo.desc)).toBe(true)
+      expect(Array.isArray(helpInfo.usage)).toBe(true)
+      expect(Array.isArray(helpInfo.examples)).toBe(true)
+    })
+  })
+
   describe('权限系统测试', () => {
     it('应该正确处理权限检查失败', async () => {
       const command = new MessageCommand('admin')

package/ASYNC-JSX-SUPPORT.md

@@ -1,173 +0,0 @@
-# 异步 JSX 组件支持
-
-## 概述
-
-Zhin Core 现在原生支持异步 JSX 组件，允许你像使用普通组件一样使用异步组件，无需额外的类型断言或注释。
-
-## 核心改动
-
-### 1. 类型系统扩展
-
-**`packages/core/src/jsx.ts`**：
-- 修改 `JSX.Element` 类型为联合类型，支持 `Promise<SendContent>`
-- `renderJSX` 函数自动检测并 await Promise 返回值
-- 错误时自动捕获并返回错误信息
-
-**`packages/core/src/message.ts`**：
-- `MessageComponent` 类型支持异步组件函数
-
-### 2. 运行时支持
-
-**自动 Promise 处理**：
-```typescript
-export async function renderJSX(element: MessageComponent<any>, context?: ComponentContext): Promise<SendContent> {
-    try {
-        // ... 组件渲染逻辑
-        const result = await component(element.data, context || {} as ComponentContext);
-        
-        // 如果组件返回 Promise，自动 await
-        if (result && typeof result === 'object' && 'then' in result) {
-            return await result;
-        }
-        
-        return result;
-    } catch (error) {
-        // 渲染错误时返回错误信息
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return `❌ 组件渲染失败: ${errorMessage}`;
-    }
-}
-```
-
-**子组件 Promise 处理**：
-```typescript
-async function renderChildren(children: JSXChildren, context?: ComponentContext): Promise<SendContent> {
-    // ... 
-    // 如果子元素是 Promise，自动 await
-    if (children && typeof children === 'object' && 'then' in children) {
-        try {
-            return await children;
-        } catch (error) {
-            return `❌ 组件渲染失败: ${errorMessage}`;
-        }
-    }
-}
-```
-
-## 使用方式
-
-### 定义异步组件
-
-```tsx
-import { defineComponent, addComponent } from 'zhin.js';
-
-const AsyncComponent = defineComponent(async function AsyncComponent({ userId }: { userId: string }) {
-  // 执行异步操作
-  const user = await fetchUserFromDatabase(userId);
-  const profile = await fetchUserProfile(userId);
-  
-  return `👤 ${user.name}\n📧 ${profile.email}`;
-}, 'AsyncComponent');
-
-addComponent(AsyncComponent);
-```
-
-### 在 JSX 中使用（现在完全类型安全）
-
-```tsx
-addCommand(
-  new MessageCommand('用户 <userId:text>')
-    .action(async (message, result) => {
-      // ✅ 直接使用 JSX 语法，无需 @ts-expect-error
-      return <AsyncComponent userId={result.params.userId} />
-    })
-);
-```
-
-### 嵌套异步组件
-
-```tsx
-const UserProfile = defineComponent(async function UserProfile({ userId }: { userId: string }) {
-  const user = await fetchUser(userId);
-  
-  // 嵌套使用其他异步组件
-  return (
-    <div>
-      <h1>{user.name}</h1>
-      <AsyncComponent userId={userId} />
-    </div>
-  );
-}, 'UserProfile');
-```
-
-## 错误处理
-
-异步组件中的错误会自动被捕获并返回友好的错误信息：
-
-```tsx
-const FailingComponent = defineComponent(async function FailingComponent() {
-  throw new Error('数据加载失败');
-}, 'FailingComponent');
-
-// 使用时会自动返回: "❌ 组件渲染失败: 数据加载失败"
-```
-
-## 性能考虑
-
-- **自动 await**：框架自动检测 Promise 并等待，无额外开销
-- **并行渲染**：多个异步组件可以并行加载（使用 `Promise.all`）
-- **错误隔离**：单个组件错误不会影响整体渲染
-
-## 迁移指南
-
-如果你之前使用了 `@ts-expect-error` 或直接函数调用：
-
-```tsx
-// ❌ 旧方式（已废弃）
-return await ShareMusic({ platform: 'qq', musicId: '123' });
-
-// ✅ 新方式（推荐）
-return <ShareMusic platform="qq" musicId="123" />
-```
-
-## TypeScript 类型
-
-```typescript
-// JSX.Element 现在支持 Promise
-declare global {
-    namespace JSX {
-        type Element = MessageComponent<any> | Promise<MessageComponent<any>> | Promise<SendContent>
-    }
-}
-
-// MessageComponent 支持异步函数
-export type MessageComponent<T extends object> = {
-    type: Component<T & {children?: SendContent}> | ((props: T & {children?: SendContent}) => Promise<SendContent>)
-    data: T
-}
-```
-
-## 测试
-
-确保你的异步组件正确工作：
-
-```typescript
-import { describe, it, expect } from 'vitest';
-
-describe('Async Components', () => {
-  it('should render async component', async () => {
-    const result = await renderJSX(<AsyncComponent userId="123" />);
-    expect(result).toBe('👤 User Name\n📧 user@example.com');
-  });
-  
-  it('should handle errors gracefully', async () => {
-    const result = await renderJSX(<FailingComponent />);
-    expect(result).toMatch(/❌ 组件渲染失败/);
-  });
-});
-```
-
----
-
-**版本**: 1.0.15+  
-**文档更新**: 2025-11-19