@zhin.js/core 1.0.50 → 1.0.52

package/src/built/dispatcher.ts

@@ -11,42 +11,88 @@
  *                  ▼
  *   ┌────────────────────────────────────────┐
  *   │  Stage 2: Route（路径判定）             │
- *   │  精确命令 → Command 快速路径            │
- *   │  其它消息 → AI Agent 路径               │
+ *   │  exclusive：命令与 AI 互斥（旧行为）     │
+ *   │  dual：命令与 AI 独立判定，可同时命中     │
  *   └──────────────┬─────────────────────────┘
  *                  ▼
  *   ┌────────────────────────────────────────┐
  *   │  Stage 3: Handle（处理）                │
  *   │  Command: commandService.handle()      │
  *   │  AI: aiHandler (由 AI 模块注册)         │
+ *   │  出站：replyWithPolish → $reply → Adapter.sendMessage → before.sendMessage │
  *   └────────────────────────────────────────┘
  *
  * 注意：Context key 为 'dispatcher'，避免与 HTTP 模块的 'router' 冲突。
+ *
+ * 默认路由为 exclusive（命令与 AI 互斥）；需双轨时请显式 dualRoute.mode: 'dual'。
  */
 
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { Message } from '../message.js';
 import { Plugin, getPlugin } from '../plugin.js';
 import type {
   MessageMiddleware,
   RegisteredAdapter,
-  AdapterMessage,
   MaybePromise,
-  ToolContext,
-  Tool,
+  SendContent,
+  OutboundReplySource,
+  OutboundPolishContext,
+  OutboundPolishMiddleware,
+  BeforeSendHandler,
 } from '../types.js';
 import type { Context } from '../plugin.js';
 
+/** Dispatcher 管理的「会话回复」异步上下文，供 `before.sendMessage` 内读取（与 Adapter.renderSendMessage 同链） */
+const outboundReplyAls = new AsyncLocalStorage<{ message: Message<any>; source: OutboundReplySource }>();
+
+export function getOutboundReplyStore(): { message: Message<any>; source: OutboundReplySource } | undefined {
+  return outboundReplyAls.getStore();
+}
+
 // ============================================================================
 // 类型定义
 // ============================================================================
 
 /**
- * 路由判定结果
+ * 路由判定结果（互斥模式 legacy）
  */
 export type RouteResult =
-  | { type: 'command' }    // 精确命令 → Command 快速路径
-  | { type: 'ai'; content: string }  // 自然语言 → AI Agent 路径
-  | { type: 'skip' };     // 不处理（被 Guardrail 拦截等）
+  | { type: 'command' }
+  | { type: 'ai'; content: string }
+  | { type: 'skip' };
+
+/**
+ * 双轨分流配置
+ */
+export interface DualRouteConfig {
+  /**
+   * exclusive：与旧版一致，命中命令则不再走 AI；
+   * dual：命令与 AI 独立判定，可同时执行（顺序由 order 决定）
+   */
+  mode?: 'exclusive' | 'dual';
+  /** 同时命中时的执行顺序，默认先指令后 AI */
+  order?: 'command-first' | 'ai-first';
+  /**
+   * 是否允许在双命中时各回复一次；为 false 时仅执行 order 中的第一个分支
+   */
+  allowDualReply?: boolean;
+}
+
+export type ResolvedDualRouteConfig = Required<DualRouteConfig>;
+
+const DUAL_ROUTE_DEFAULTS: ResolvedDualRouteConfig = {
+  mode: 'exclusive',
+  order: 'command-first',
+  allowDualReply: false,
+};
+
+function resolveDualRouteConfig(partial?: Partial<DualRouteConfig>): ResolvedDualRouteConfig {
+  return {
+    mode: partial?.mode ?? DUAL_ROUTE_DEFAULTS.mode,
+    order: partial?.order ?? DUAL_ROUTE_DEFAULTS.order,
+    allowDualReply: partial?.allowDualReply ?? DUAL_ROUTE_DEFAULTS.allowDualReply,
+  };
+}
 
 /**
  * AI 处理函数签名
@@ -59,68 +105,66 @@ export type AIHandler = (
 
 /**
  * 命令前缀判定函数
- * 返回 true 表示该消息是精确命令调用
  */
 export type CommandMatcher = (text: string, message: Message<any>) => boolean;
 
 /**
  * AI 触发判定函数
- * 返回 { triggered, content } 表示是否应该触发 AI 以及提取的内容
  */
 export type AITriggerMatcher = (message: Message<any>) => { triggered: boolean; content: string };
 
-/**
- * Guardrail 中间件
- * 与 MessageMiddleware 签名一致，但语义上只用于鉴权/限流/安全/日志
- * 返回 false 或抛异常表示拦截消息
- */
 export type GuardrailMiddleware = MessageMiddleware<RegisteredAdapter>;
 
+/** @alias OutboundReplySource：出站回复来源（指令 / AI） */
+export type ReplySource = OutboundReplySource;
+
+export interface CreateMessageDispatcherOptions {
+  dualRoute?: Partial<DualRouteConfig>;
+}
+
 // ============================================================================
 // MessageDispatcher 服务
 // ============================================================================
 
-/**
- * MessageDispatcher 服务接口
- */
 export interface MessageDispatcherService {
-  /**
-   * 调度一条消息 — 这是唯一的入口
-   * Adapter 的 message.receive 事件应该调用此方法
-   */
   dispatch(message: Message<any>): Promise<void>;
 
-  /**
-   * 注册 Guardrail（护栏中间件）
-   * Guardrail 始终执行，用于鉴权、限流、安全过滤、日志等
-   * @returns 移除函数
-   */
   addGuardrail(guardrail: GuardrailMiddleware): () => void;
 
-  /**
-   * 设置命令匹配器
-   * 用于判定消息是否为精确命令调用
-   * 默认：检查消息是否以已注册命令的 pattern 开头
-   */
   setCommandMatcher(matcher: CommandMatcher): void;
 
+  setAITriggerMatcher(matcher: AITriggerMatcher): void;
+
+  setAIHandler(handler: AIHandler): void;
+
+  hasAIHandler(): boolean;
+
+  /** 合并更新双轨配置 */
+  setDualRouteConfig(config: Partial<DualRouteConfig>): void;
+
+  getDualRouteConfig(): Readonly<ResolvedDualRouteConfig>;
+
+  /** 注册出站润色：挂到根插件 `before.sendMessage`；仅在 `replyWithPolish` 触发的发送中生效（见 getOutboundReplyStore） */
+  addOutboundPolish(handler: OutboundPolishMiddleware): () => void;
+
   /**
-   * 设置 AI 触发判定器
-   * 用于判定消息是否应该触发 AI 处理
-   * 由 AI 模块注册
+   * 在 `before.sendMessage` 管道内调用 `message.$reply`（与 Adapter#sendMessage 同一出站链）
    */
-  setAITriggerMatcher(matcher: AITriggerMatcher): void;
+  replyWithPolish(
+    message: Message<any>,
+    source: ReplySource,
+    content: SendContent,
+  ): Promise<unknown>;
 
   /**
-   * 注册 AI 处理函数
-   * 由 AI 模块注册，当消息路由到 AI 路径时调用
+   * 是否匹配为指令路径（与 dispatch 内判定一致）
    */
-  setAIHandler(handler: AIHandler): void;
+  matchCommand(message: Message<any>): boolean;
 
   /**
-   * 获取当前是否已注册 AI 处理能力
+   * AI 触发判定结果
    */
-  hasAIHandler(): boolean;
+  matchAI(message: Message<any>): { triggered: boolean; content: string };
 }
 
 // ============================================================================
@@ -128,8 +172,8 @@ export interface MessageDispatcherService {
 // ============================================================================
 
 export interface DispatcherContextExtensions {
-  /** 注册 Guardrail（护栏中间件） */
   addGuardrail(guardrail: GuardrailMiddleware): () => void;
+  addOutboundPolish(handler: OutboundPolishMiddleware): () => void;
 }
 
 declare module '../plugin.js' {
@@ -145,17 +189,18 @@ declare module '../plugin.js' {
 // 实现
 // ============================================================================
 
-/**
- * 创建 MessageDispatcher Context
- */
-export function createMessageDispatcher(): Context<'dispatcher', DispatcherContextExtensions> {
+export function createMessageDispatcher(
+  options?: CreateMessageDispatcherOptions,
+): Context<'dispatcher', DispatcherContextExtensions> {
   const guardrails: GuardrailMiddleware[] = [];
+  /** mounted 前注册的润色，在 mounted 时挂到 root.before.sendMessage */
+  const pendingOutboundPolish: OutboundPolishMiddleware[] = [];
   let aiHandler: AIHandler | null = null;
   let aiTriggerMatcher: AITriggerMatcher | null = null;
   let commandMatcher: CommandMatcher | null = null;
   let rootPlugin: Plugin | null = null;
+  let dualRoute = resolveDualRouteConfig(options?.dualRoute);
 
-  // Command prefix index — rebuilt lazily for O(1) lookup
   let commandPrefixIndex: Map<string, boolean> | null = null;
   let lastCommandCount = -1;
 
@@ -183,16 +228,15 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
     return commandPrefixIndex;
   }
 
-  /**
-   * Guardrail pipeline — a guardrail that does NOT call next() blocks the message.
-   */
   async function runGuardrails(message: Message<any>): Promise<boolean> {
     if (guardrails.length === 0) return true;
 
     for (const guardrail of guardrails) {
       let nextCalled = false;
       try {
-        await guardrail(message, async () => { nextCalled = true; });
+        await guardrail(message, async () => {
+          nextCalled = true;
+        });
       } catch {
         return false;
       }
@@ -201,14 +245,41 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
     return true;
   }
 
-  function route(message: Message<any>): RouteResult {
+  function extractText(message: Message<any>): string {
+    if (!message.$content) return '';
+    return message.$content
+      .map((seg: any) => {
+        if (typeof seg === 'string') return seg;
+        if (seg.type === 'text') return seg.data?.text || '';
+        return '';
+      })
+      .join('')
+      .trim();
+  }
+
+  function matchCommandInternal(message: Message<any>): boolean {
+    const text = extractText(message);
+    if (commandMatcher && commandMatcher(text, message)) return true;
+    const index = getCommandIndex();
+    for (const [prefix] of index) {
+      if (text.startsWith(prefix)) return true;
+    }
+    return false;
+  }
+
+  function matchAIInternal(message: Message<any>): { triggered: boolean; content: string } {
+    if (!aiTriggerMatcher) return { triggered: false, content: '' };
+    return aiTriggerMatcher(message);
+  }
+
+  /** 互斥路由（与旧版 route 一致） */
+  function routeExclusive(message: Message<any>): RouteResult {
     const text = extractText(message);
 
     if (commandMatcher && commandMatcher(text, message)) {
       return { type: 'command' };
     }
 
-    // Use indexed lookup instead of O(N) scan
     const index = getCommandIndex();
     for (const [prefix] of index) {
       if (text.startsWith(prefix)) {
@@ -226,64 +297,117 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
     return { type: 'skip' };
   }
 
-  function extractText(message: Message<any>): string {
-    if (!message.$content) return '';
-    return message.$content
-      .map((seg: any) => {
-        if (typeof seg === 'string') return seg;
-        if (seg.type === 'text') return seg.data?.text || '';
-        return '';
-      })
-      .join('')
-      .trim();
+  function wrapPolishAsBeforeSend(handler: OutboundPolishMiddleware): BeforeSendHandler {
+    return async (options) => {
+      const store = outboundReplyAls.getStore();
+      if (!store) return;
+      const ctx: OutboundPolishContext = {
+        message: store.message,
+        content: options.content,
+        source: store.source,
+      };
+      const next = await handler(ctx);
+      if (next !== undefined) return { ...options, content: next };
+    };
+  }
+
+  function flushPendingOutboundPolish(): void {
+    if (!rootPlugin) return;
+    const root = rootPlugin.root;
+    for (const mw of pendingOutboundPolish) {
+      const fn = wrapPolishAsBeforeSend(mw);
+      root.on('before.sendMessage', fn);
+    }
+    pendingOutboundPolish.length = 0;
+  }
+
+  async function replyWithPolishInternal(
+    message: Message<any>,
+    source: ReplySource,
+    content: SendContent,
+  ): Promise<unknown> {
+    if (!rootPlugin) {
+      return message.$reply(content);
+    }
+    return outboundReplyAls.run({ message, source }, () => message.$reply(content));
+  }
+
+  async function runCommandBranch(message: Message<any>): Promise<void> {
+    if (!rootPlugin) return;
+    const commandService = rootPlugin.inject('command');
+    if (!commandService) return;
+    const response = await commandService.handle(message, rootPlugin);
+    if (response) {
+      await replyWithPolishInternal(message, 'command', response);
+    }
+  }
+
+  async function runCustomMiddlewares(message: Message<any>): Promise<void> {
+    if (!rootPlugin) return;
+    const customMiddlewares = (rootPlugin as any)._getCustomMiddlewares?.() as
+      | MessageMiddleware<RegisteredAdapter>[]
+      | undefined;
+    if (customMiddlewares && customMiddlewares.length > 0) {
+      const { compose } = await import('../utils.js');
+      const composed = compose(customMiddlewares);
+      await composed(message, async () => {});
+    }
   }
 
   const service: MessageDispatcherService = {
     async dispatch(message: Message<any>) {
-      // Stage 1: Guardrail
       const passed = await runGuardrails(message);
       if (!passed) return;
 
-      // Stage 2: Route
-      const result = route(message);
-
-      // Stage 3: Handle
-      switch (result.type) {
-        case 'command': {
-          if (rootPlugin) {
-            const commandService = rootPlugin.inject('command');
-            if (commandService) {
-              const response = await commandService.handle(message, rootPlugin);
-              if (response) {
-                await message.$reply(response);
-              }
-            }
-          }
-          break;
+      const cfg = dualRoute;
+
+      if (cfg.mode === 'exclusive') {
+        const result = routeExclusive(message);
+        switch (result.type) {
+          case 'command':
+            await runCommandBranch(message);
+            break;
+          case 'ai':
+            if (aiHandler) await aiHandler(message, result.content);
+            break;
+          default:
+            break;
         }
+        await runCustomMiddlewares(message);
+        return;
+      }
 
-        case 'ai': {
-          if (aiHandler) {
-            await aiHandler(message, result.content);
-          }
-          break;
-        }
+      // dual 模式
+      let wantCmd = matchCommandInternal(message);
+      const aiRes = matchAIInternal(message);
+      let wantAi = aiRes.triggered;
 
-        case 'skip':
-        default:
-          break;
+      if (!wantCmd && !wantAi) {
+        await runCustomMiddlewares(message);
+        return;
       }
 
-      // Run legacy custom middlewares (skip the built-in command middleware at index 0).
-      // This ensures plugins that registered middlewares via addMiddleware() still work.
-      if (rootPlugin) {
-        const customMiddlewares = (rootPlugin as any)._getCustomMiddlewares?.() as MessageMiddleware<RegisteredAdapter>[] | undefined;
-        if (customMiddlewares && customMiddlewares.length > 0) {
-          const { compose } = await import('../utils.js');
-          const composed = compose(customMiddlewares);
-          await composed(message, async () => {});
-        }
+      if (!cfg.allowDualReply && wantCmd && wantAi) {
+        if (cfg.order === 'command-first') wantAi = false;
+        else wantCmd = false;
       }
+
+      const runCmd = async () => {
+        if (wantCmd) await runCommandBranch(message);
+      };
+      const runAi = async () => {
+        if (wantAi && aiHandler) await aiHandler(message, aiRes.content);
+      };
+
+      if (cfg.order === 'ai-first') {
+        await runAi();
+        await runCmd();
+      } else {
+        await runCmd();
+        await runAi();
+      }
+
+      await runCustomMiddlewares(message);
     },
 
     addGuardrail(guardrail: GuardrailMiddleware) {
@@ -309,6 +433,40 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
     hasAIHandler() {
       return aiHandler !== null;
     },
+
+    setDualRouteConfig(config: Partial<DualRouteConfig>) {
+      dualRoute = resolveDualRouteConfig({ ...dualRoute, ...config });
+    },
+
+    getDualRouteConfig() {
+      return { ...dualRoute };
+    },
+
+    addOutboundPolish(handler: OutboundPolishMiddleware) {
+      const fn = wrapPolishAsBeforeSend(handler);
+      if (rootPlugin) {
+        const root = rootPlugin.root;
+        root.on('before.sendMessage', fn);
+        return () => root.off('before.sendMessage', fn);
+      }
+      pendingOutboundPolish.push(handler);
+      return () => {
+        const i = pendingOutboundPolish.indexOf(handler);
+        if (i !== -1) pendingOutboundPolish.splice(i, 1);
+      };
+    },
+
+    replyWithPolish(message, source, content) {
+      return replyWithPolishInternal(message, source, content);
+    },
+
+    matchCommand(message) {
+      return matchCommandInternal(message);
+    },
+
+    matchAI(message) {
+      return matchAIInternal(message);
+    },
   };
 
   return {
@@ -317,6 +475,7 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
     value: service,
     mounted(plugin: Plugin) {
       rootPlugin = plugin.root;
+      flushPendingOutboundPolish();
       return service;
     },
     extensions: {
@@ -326,6 +485,12 @@ export function createMessageDispatcher(): Context<'dispatcher', DispatcherConte
         plugin.onDispose(dispose);
         return dispose;
       },
+      addOutboundPolish(handler: OutboundPolishMiddleware) {
+        const plugin = getPlugin();
+        const dispose = service.addOutboundPolish(handler);
+        plugin.onDispose(dispose);
+        return dispose;
+      },
     },
   };
 }

package/src/built/login-assist.ts

@@ -0,0 +1,131 @@
+/**
+ * LoginAssist — 登录辅助生产者-消费者
+ *
+ * 适配器在需要人为辅助登录时（扫码、短信、滑块等）作为生产者投递待办；
+ * Web 控制台、命令行等作为消费者拉取待办并提交结果。
+ * 待办未消费前会一直保留，刷新页面后仍可继续消费。
+ *
+ * 事件：
+ *   bot.login.pending — 有新待办时触发，payload: PendingLoginTask
+ */
+
+import type { Plugin } from '../plugin.js';
+
+// ============================================================================
+// 类型
+// ============================================================================
+
+export type LoginAssistType = 'qrcode' | 'sms' | 'slider' | 'device' | 'other';
+
+export interface PendingLoginTaskPayload {
+  /** 说明文案（如「请扫码登录」） */
+  message?: string;
+  /** 二维码图片 URL 或 base64（type=qrcode 时） */
+  image?: string;
+  /** 滑块验证 URL（type=slider 时） */
+  url?: string;
+  /** 其它扩展字段 */
+  [key: string]: unknown;
+}
+
+export interface PendingLoginTask {
+  id: string;
+  adapter: string;
+  botId: string;
+  type: LoginAssistType;
+  payload: PendingLoginTaskPayload;
+  createdAt: number;
+}
+
+interface PendingEntry {
+  task: PendingLoginTask;
+  resolve: (value: string | Record<string, unknown>) => void;
+  reject: (err: Error) => void;
+}
+
+// ============================================================================
+// LoginAssist 服务
+// ============================================================================
+
+export class LoginAssist {
+  private readonly plugin: Plugin;
+  private readonly pending = new Map<string, PendingEntry>();
+  private idSeq = 0;
+
+  constructor(plugin: Plugin) {
+    this.plugin = plugin;
+  }
+
+  /**
+   * 生产者：等待用户输入后 resolve。会发出 bot.login.pending 事件，未消费前可被 listPending 拉取（刷新后可继续消费）。
+   */
+  waitForInput(
+    adapter: string,
+    botId: string,
+    type: LoginAssistType,
+    payload: PendingLoginTaskPayload = {},
+  ): Promise<string | Record<string, unknown>> {
+    const id = `login-${Date.now()}-${++this.idSeq}`;
+    const task: PendingLoginTask = {
+      id,
+      adapter,
+      botId,
+      type,
+      payload: { message: payload.message ?? '', ...payload },
+      createdAt: Date.now(),
+    };
+    const promise = new Promise<string | Record<string, unknown>>((resolve, reject) => {
+      this.pending.set(id, { task, resolve, reject });
+      this.plugin.emit('bot.login.pending', task);
+    });
+    return promise;
+  }
+
+  /**
+   * 消费者：提交结果，对应 waitForInput 的 Promise 会 resolve。
+   */
+  submit(id: string, value: string | Record<string, unknown>): boolean {
+    const entry = this.pending.get(id);
+    if (!entry) return false;
+    this.pending.delete(id);
+    entry.resolve(value);
+    return true;
+  }
+
+  /**
+   * 消费者：取消某条待办，对应 Promise 会 reject。
+   */
+  cancel(id: string, reason = 'cancelled'): boolean {
+    const entry = this.pending.get(id);
+    if (!entry) return false;
+    this.pending.delete(id);
+    entry.reject(new Error(reason));
+    return true;
+  }
+
+  /**
+   * 列出未消费的待办（供 Web/CLI 展示，刷新后仍可拉取同一列表）。
+   */
+  listPending(): PendingLoginTask[] {
+    return [...this.pending.values()].map((e) => e.task);
+  }
+
+  dispose(): void {
+    for (const [, entry] of this.pending) {
+      entry.reject(new Error('LoginAssist disposed'));
+    }
+    this.pending.clear();
+  }
+}
+
+// ============================================================================
+// 扩展 Plugin.Contexts
+// ============================================================================
+
+declare module '../plugin.js' {
+  namespace Plugin {
+    interface Contexts {
+      loginAssist: LoginAssist;
+    }
+  }
+}