@zhin.js/core 1.0.51 → 1.0.52

package/src/types.ts

@@ -64,6 +64,22 @@ export type MaybeArray<T>=T|T[]
  * 消息发送内容类型
  */
 export type SendContent=MaybeArray<string|MessageElement>
+
+/** 出站回复来源（指令 / AI），仅当经 MessageDispatcher.replyWithPolish 发出时由框架填入异步上下文 */
+export type OutboundReplySource = 'command' | 'ai'
+
+/**
+ * 出站润色上下文（`dispatcher.addOutboundPolish` 的 handler 签名的同构类型）。
+ * 与 {@link Adapter.sendMessage} → `before.sendMessage` 同一管道；需 `message`/`source` 时见 `getOutboundReplyStore`（dispatcher 导出）。
+ */
+export interface OutboundPolishContext {
+  message: Message
+  content: SendContent
+  source: OutboundReplySource
+}
+
+/** 返回 `SendContent` 则替换后续 `before.sendMessage` 与发送中的 content */
+export type OutboundPolishMiddleware = (ctx: OutboundPolishContext) => MaybePromise<SendContent | void>
 /**
  * 消息发送者信息
  */

package/src/utils.ts

@@ -107,7 +107,7 @@ export namespace segment {
     const toString = (template: string | MessageElement) => {
       if (typeof template !== "string") return [template];
 
-      const MAX_TEMPLATE_LENGTH = 100000;
+      const MAX_TEMPLATE_LENGTH = 400000;
       if (template.length > MAX_TEMPLATE_LENGTH) {
         throw new Error(`Template too large: ${template.length} > ${MAX_TEMPLATE_LENGTH}`);
       }

package/tests/adapter.test.ts

@@ -107,9 +107,8 @@ describe('Adapter Core Functionality', () => {
       expect(adapter).toBeInstanceOf(EventEmitter)
     })
 
-    it('should register message.receive listener', () => {
-      const listeners = adapter.listeners('message.receive')
-      expect(listeners.length).toBeGreaterThan(0)
+    it('should route message.receive via emit without default listener', () => {
+      expect(adapter.listenerCount('message.receive')).toBe(0)
     })
 
     it('should register call.recallMessage listener', () => {
@@ -199,13 +198,15 @@ describe('Adapter Core Functionality', () => {
 
     it('should remove all event listeners', async () => {
       await adapter.start()
+      const noop = () => {}
+      adapter.on('message.receive', noop)
       const beforeCount = adapter.listenerCount('message.receive')
-      
+      expect(beforeCount).toBe(1)
+
       await adapter.stop()
       const afterCount = adapter.listenerCount('message.receive')
-      
+
       expect(afterCount).toBe(0)
-      expect(beforeCount).toBeGreaterThan(0)
     })
 
     it('should handle bot disconnect errors gracefully', async () => {
@@ -377,97 +378,92 @@ describe('Adapter Core Functionality', () => {
     })
 
     describe('message.receive', () => {
-      it('should process received message through middleware when no dispatcher', async () => {
+      it('should still dispatch plugin message.receive when dispatcher is missing (no middleware fallback)', async () => {
         const config = [{ id: 'bot1' }]
         const adapter = new MockAdapter(plugin, 'test', config)
         await adapter.start()
-        
+
         let middlewareCalled = false
-        plugin.addMiddleware(async (message, next) => {
+        plugin.addMiddleware(async (_message, next) => {
           middlewareCalled = true
           await next()
         })
-        
+
+        let lifecycleCalled = false
+        plugin.on('message.receive', () => {
+          lifecycleCalled = true
+        })
+
         const message = {
           $bot: 'bot1',
           $adapter: 'test',
           $channel: { id: 'channel-id', type: 'text' },
-          $content: 'Hello'
+          $content: 'Hello',
         } as any
-        
+
         adapter.emit('message.receive', message)
-        
-        // 等待异步处理
-        await new Promise(resolve => setTimeout(resolve, 10))
-        expect(middlewareCalled).toBe(true)
+        await new Promise((r) => setTimeout(r, 20))
+        expect(middlewareCalled).toBe(false)
+        expect(lifecycleCalled).toBe(true)
       })
 
-      it('should use MessageDispatcher when available', async () => {
+      it('should await MessageDispatcher then plugin lifecycle', async () => {
         const config = [{ id: 'bot1' }]
         const adapter = new MockAdapter(plugin, 'test', config)
         await adapter.start()
 
-        let dispatchCalled = false
-        let middlewareCalled = false
-
-        // 注册 dispatcher context
+        const order: string[] = []
         plugin.$contexts.set('dispatcher', {
           name: 'dispatcher',
           description: 'mock dispatcher',
           value: {
-            dispatch: (msg: any) => { dispatchCalled = true; return Promise.resolve() },
+            dispatch: async (_msg: any) => {
+              order.push('dispatcher')
+            },
           },
         } as any)
 
-        plugin.addMiddleware(async (message, next) => {
-          middlewareCalled = true
-          await next()
+        plugin.on('message.receive', () => {
+          order.push('lifecycle')
         })
 
         const message = {
           $bot: 'bot1',
           $adapter: 'test',
           $channel: { id: 'channel-id', type: 'text' },
-          $content: 'Hello'
+          $content: 'Hello',
         } as any
 
         adapter.emit('message.receive', message)
-
-        await new Promise(resolve => setTimeout(resolve, 10))
-        expect(dispatchCalled).toBe(true)
-        expect(middlewareCalled).toBe(false)
+        await new Promise((r) => setTimeout(r, 20))
+        expect(order).toEqual(['dispatcher', 'lifecycle'])
       })
 
-      it('should fallback to middleware when dispatcher has no dispatch method', async () => {
+      it('should call adapter.on observers after plugin lifecycle', 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 },
+          description: 'mock dispatcher',
+          value: { dispatch: async () => {} },
         } as any)
 
-        plugin.addMiddleware(async (message, next) => {
-          middlewareCalled = true
-          await next()
-        })
+        const order: string[] = []
+        plugin.on('message.receive', () => order.push('lifecycle'))
+        adapter.on('message.receive', () => order.push('adapterObserver'))
 
         const message = {
           $bot: 'bot1',
           $adapter: 'test',
           $channel: { id: 'channel-id', type: 'text' },
-          $content: 'Hello'
+          $content: 'Hello',
         } as any
 
         adapter.emit('message.receive', message)
-
-        await new Promise(resolve => setTimeout(resolve, 10))
-        expect(middlewareCalled).toBe(true)
+        await new Promise((r) => setTimeout(r, 20))
+        expect(order).toEqual(['lifecycle', 'adapterObserver'])
       })
     })
   })
@@ -617,90 +613,6 @@ 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)

package/tests/dispatcher.test.ts

@@ -2,8 +2,14 @@
  * MessageDispatcher 测试
  */
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMessageDispatcher, type MessageDispatcherService, type RouteResult } from '../src/built/dispatcher.js';
+import { EventEmitter } from 'node:events';
+import {
+  createMessageDispatcher,
+  type MessageDispatcherService,
+} from '../src/built/dispatcher.js';
 import type { Message } from '../src/message.js';
+import type { Plugin } from '../src/plugin.js';
+import type { BeforeSendHandler } from '../src/types.js';
 
 function makeMessage(text: string, overrides: Partial<Message<any>> = {}): Message<any> {
   return {
@@ -21,6 +27,42 @@ function makeMessage(text: string, overrides: Partial<Message<any>> = {}): Messa
   } as any;
 }
 
+function makeRootWithCommand(
+  handleImpl?: (msg: Message<any>, root: Plugin) => Promise<string | void>,
+) {
+  const handle = handleImpl ?? vi.fn(async () => 'cmd-ok');
+  const cmdService = {
+    items: [{ pattern: '/help ping' }],
+    handle,
+  };
+  const root = new EventEmitter() as unknown as Plugin;
+  (root as any).inject = (name: string) => {
+    if (name === 'command') return cmdService;
+    return undefined;
+  };
+  (root as any).root = root;
+  return root;
+}
+
+/** 模拟 $reply → adapter.sendMessage → renderSendMessage（before.sendMessage） */
+function wireMessageReplyThroughBeforeSend(msg: Message<any>, root: EventEmitter) {
+  msg.$reply = vi.fn(async (content: any) => {
+    let options = {
+      content,
+      bot: msg.$bot,
+      id: msg.$channel.id,
+      type: msg.$channel.type,
+      context: 'test',
+    };
+    const fns = root.listeners('before.sendMessage') as BeforeSendHandler[];
+    for (const fn of fns) {
+      const r = await fn(options);
+      if (r) options = r;
+    }
+    return 'mock-msg-id';
+  });
+}
+
 describe('createMessageDispatcher', () => {
   let context: ReturnType<typeof createMessageDispatcher>;
   let service: MessageDispatcherService;
@@ -40,6 +82,10 @@ describe('createMessageDispatcher', () => {
     expect(typeof context.value.setAITriggerMatcher).toBe('function');
     expect(typeof context.value.setAIHandler).toBe('function');
     expect(typeof context.value.hasAIHandler).toBe('function');
+    expect(typeof context.value.addOutboundPolish).toBe('function');
+    expect(typeof context.value.replyWithPolish).toBe('function');
+    expect(typeof service.matchCommand).toBe('function');
+    expect(typeof service.matchAI).toBe('function');
   });
 
   describe('Guardrail', () => {
@@ -98,7 +144,7 @@ describe('createMessageDispatcher', () => {
     it('AI 触发时应调用 handler', async () => {
       const handler = vi.fn();
       service.setAIHandler(handler);
-      service.setAITriggerMatcher((msg) => ({
+      service.setAITriggerMatcher(() => ({
         triggered: true,
         content: 'processed content',
       }));
@@ -121,20 +167,118 @@ describe('createMessageDispatcher', () => {
     });
   });
 
-  describe('Command Matcher', () => {
-    it('自定义命令匹配器应优先', async () => {
+  describe('Command Matcher (exclusive)', () => {
+    it('自定义命令匹配器应优先并阻断 AI（互斥模式）', async () => {
+      const exclusiveCtx = createMessageDispatcher({ dualRoute: { mode: 'exclusive' } });
+      const d = exclusiveCtx.value;
+      const aiHandler = vi.fn();
+      d.setAIHandler(aiHandler);
+      d.setAITriggerMatcher(() => ({ triggered: true, content: '' }));
+      d.setCommandMatcher((text) => text.startsWith('/'));
+
+      const msg = makeMessage('/help');
+      await d.dispatch(msg);
+
+      expect(aiHandler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('双轨 dual 模式', () => {
+    it('同时命中指令与 AI 时应各执行一次（默认 command-first）', async () => {
+      const root = makeRootWithCommand();
+      const fakePlugin = { root } as Plugin;
+      context.mounted(fakePlugin);
+
       const aiHandler = vi.fn();
       service.setAIHandler(aiHandler);
-      service.setAITriggerMatcher(() => ({ triggered: true, content: '' }));
+      service.setAITriggerMatcher(() => ({ triggered: true, content: 'hi' }));
+      service.setDualRouteConfig({ mode: 'dual', order: 'command-first', allowDualReply: true });
+
+      const msg = makeMessage('/help');
+      wireMessageReplyThroughBeforeSend(msg, root as unknown as EventEmitter);
+      await service.dispatch(msg);
 
-      // 设置命令匹配器：以 / 开头视为命令
-      service.setCommandMatcher((text) => text.startsWith('/'));
+      const cmd = root.inject('command') as any;
+      expect(cmd.handle).toHaveBeenCalled();
+      expect(aiHandler).toHaveBeenCalledWith(msg, 'hi');
+      expect(msg.$reply).toHaveBeenCalledWith('cmd-ok');
+    });
+
+    it('ai-first 时应先 AI 后指令', async () => {
+      const order: string[] = [];
+      const root = makeRootWithCommand(async () => {
+        order.push('cmd');
+        return 'c';
+      });
+      const fakePlugin = { root } as Plugin;
+      context.mounted(fakePlugin);
+
+      service.setAIHandler(async () => {
+        order.push('ai');
+      });
+      service.setAITriggerMatcher(() => ({ triggered: true, content: 'x' }));
+      service.setDualRouteConfig({ mode: 'dual', order: 'ai-first', allowDualReply: true });
 
       const msg = makeMessage('/help');
+      wireMessageReplyThroughBeforeSend(msg, root as unknown as EventEmitter);
+      await service.dispatch(msg);
+
+      expect(order).toEqual(['ai', 'cmd']);
+    });
+
+    it('allowDualReply false 且 command-first 时仅执行指令', async () => {
+      const root = makeRootWithCommand();
+      const fakePlugin = { root } as Plugin;
+      context.mounted(fakePlugin);
+
+      const aiHandler = vi.fn();
+      service.setAIHandler(aiHandler);
+      service.setAITriggerMatcher(() => ({ triggered: true, content: 'x' }));
+      service.setDualRouteConfig({ mode: 'dual', order: 'command-first', allowDualReply: false });
+
+      const msg = makeMessage('/help');
+      wireMessageReplyThroughBeforeSend(msg, root as unknown as EventEmitter);
       await service.dispatch(msg);
 
-      // 命令路径不应触发 AI
       expect(aiHandler).not.toHaveBeenCalled();
+      expect(msg.$reply).toHaveBeenCalled();
+    });
+  });
+
+  describe('出站润色', () => {
+    it('replyWithPolish 应经 before.sendMessage 链式润色再发出（$reply 入参仍为原文）', async () => {
+      const root = new EventEmitter() as unknown as Plugin;
+      (root as any).inject = () => undefined;
+      (root as any).root = root;
+      context.mounted({ root } as Plugin);
+
+      const p1 = vi.fn(async (ctx: any) => `[1]${ctx.content}`);
+      const p2 = vi.fn(async (ctx: any) => `${ctx.content}[2]`);
+      service.addOutboundPolish(p1);
+      service.addOutboundPolish(p2);
+
+      const msg = makeMessage('x');
+      wireMessageReplyThroughBeforeSend(msg, root as unknown as EventEmitter);
+      await service.replyWithPolish(msg, 'ai', 'hello');
+
+      expect(p1).toHaveBeenCalled();
+      expect(p2).toHaveBeenCalled();
+      expect(msg.$reply).toHaveBeenCalledWith('hello');
+    });
+
+    it('指令路径应经过润色', async () => {
+      const root = makeRootWithCommand(async () => 'out');
+      const fakePlugin = { root } as Plugin;
+      context.mounted(fakePlugin);
+
+      service.addOutboundPolish(async (ctx) => `<<${ctx.content}>>`);
+      service.setDualRouteConfig({ mode: 'exclusive' });
+
+      const msg = makeMessage('/help');
+      wireMessageReplyThroughBeforeSend(msg, root as unknown as EventEmitter);
+      await service.dispatch(msg);
+
+      expect(msg.$reply).toHaveBeenCalledWith('out');
     });
   });
 
@@ -142,5 +286,8 @@ describe('createMessageDispatcher', () => {
     it('应提供 addGuardrail 扩展', () => {
       expect(typeof context.extensions.addGuardrail).toBe('function');
     });
+    it('应提供 addOutboundPolish 扩展', () => {
+      expect(typeof context.extensions.addOutboundPolish).toBe('function');
+    });
   });
 });

package/tests/redos-protection.test.ts

@@ -72,12 +72,13 @@ describe('ReDoS Protection Tests', () => {
     });
 
     it('should reject extremely large templates', () => {
-      // 测试超大模板
-      const hugeTemplate = '<tag>content</tag>'.repeat(10000);
-      
+      // segment.from 在 utils 中限制单段模板长度 > 400_000（见 MAX_TEMPLATE_LENGTH）
+      const chunk = '<tag>content</tag>';
+      const hugeTemplate = chunk.repeat(Math.ceil(400_001 / chunk.length));
+
       expect(() => {
         segment.from(hugeTemplate);
-      }).toThrow('Template too large');
+      }).toThrow(/Template too large/);
     });
 
     it('should handle nested tags without exponential backtracking', () => {