@zhin.js/core 1.0.50 → 1.0.52

package/src/built/skill.ts

@@ -5,8 +5,7 @@
  *   Plugin = 运行时容器（生命周期、服务注册、中间件）
  *   Skill  = AI 可见的能力接口（名称、描述、工具列表）
  *
- * 每个 Plugin 可以声明一个 Skill 描述，告诉 AI Agent：
- *   "我叫什么、我能做什么、我有哪些工具"
+ * Skill 记录由运行时注入（如 Agent 从磁盘 SKILL.md 同步），供 Agent 粗筛与工具关联。
  *
  * SkillFeature 全局收集所有 Skill，供 Agent 进行两级过滤：
  *   1. 粗筛：根据用户消息选择相关 Skill
@@ -14,7 +13,6 @@
  */
 
 import { Feature, FeatureJSON } from '../feature.js';
-import { Plugin, getPlugin } from '../plugin.js';
 import type { Tool } from '../types.js';
 
 // ============================================================================
@@ -51,35 +49,21 @@ export interface Skill {
 }
 
 /**
- * Skill 元数据 — 开发者在插件中声明
- * 由 plugin.declareSkill() 注册
+ * SKILL.md frontmatter 常见字段（类型提示；运行时由 Agent 等同步到 SkillFeature）
  */
 export interface SkillMetadata {
   /** 技能描述（必填） */
   description: string;
 
-  /** 触发关键词（可选，自动从工具中聚合） */
+  /** 触发关键词（可选） */
   keywords?: string[];
 
   /** 分类标签（可选） */
   tags?: string[];
 }
 
-// ============================================================================
-// 扩展 Plugin 接口
-// ============================================================================
-
-export interface SkillContextExtensions {
-  /**
-   * 声明本插件的 Skill 元数据
-   * 调用后，插件的工具会自动聚合为一个 Skill 注册到 SkillFeature
-   */
-  declareSkill(metadata: SkillMetadata): void;
-}
-
 declare module '../plugin.js' {
   namespace Plugin {
-    interface Extensions extends SkillContextExtensions {}
     interface Contexts {
       skill: SkillFeature;
     }
@@ -220,60 +204,4 @@ export class SkillFeature extends Feature<Skill> {
       })),
     };
   }
-
-  /**
-   * 提供给 Plugin.prototype 的扩展方法
-   */
-  get extensions() {
-    const feature = this;
-    return {
-      declareSkill(metadata: SkillMetadata) {
-        const plugin = getPlugin();
-        const pluginName = plugin.name;
-
-        // 收集该插件注册的工具
-        const toolService = plugin.root.inject('tool') as { getToolsByPlugin?: (name: string) => Tool[] } | undefined;
-        let tools: Tool[] = [];
-
-        if (toolService && typeof toolService.getToolsByPlugin === 'function') {
-          tools = toolService.getToolsByPlugin(pluginName);
-        } else {
-          tools = plugin.getAllTools?.() || [];
-        }
-
-        // 聚合关键词：开发者声明 + 工具自带
-        const allKeywords = new Set<string>(metadata.keywords || []);
-        for (const tool of tools) {
-          if (tool.keywords) {
-            for (const kw of tool.keywords) {
-              allKeywords.add(kw);
-            }
-          }
-        }
-
-        // 聚合标签
-        const allTags = new Set<string>(metadata.tags || []);
-        for (const tool of tools) {
-          if (tool.tags) {
-            for (const tag of tool.tags) {
-              allTags.add(tag);
-            }
-          }
-        }
-
-        const skill: Skill = {
-          name: pluginName,
-          description: metadata.description,
-          tools,
-          keywords: Array.from(allKeywords),
-          tags: Array.from(allTags),
-          pluginName,
-        };
-
-        const dispose = feature.add(skill, pluginName);
-        plugin.recordFeatureContribution(feature.name, pluginName);
-        plugin.onDispose(dispose);
-      },
-    };
-  }
 }

package/src/index.ts

@@ -33,6 +33,8 @@ export * from './built/skill.js'
 export * from './built/schema-feature.js'
 // Common adapter tool factories (shared across adapters)
 export * from './built/common-adapter-tools.js'
+// Login assist (producer-consumer for QR / SMS / slider etc.)
+export * from './built/login-assist.js'
 // AI 模块 (原 @zhin.js/ai，已合并至 core)
 export * from './ai/index.js'
 

package/src/plugin.ts

@@ -6,19 +6,24 @@
 import { AsyncLocalStorage } from "async_hooks";
 import { EventEmitter } from "events";
 import { createRequire } from "module";
-import type { Database, Definition } from "@zhin.js/database";
-import { Schema } from "@zhin.js/schema";
-import type { Models, RegisteredAdapters, Tool, ToolContext } from "./types.js";
+import type { Tool } from "./types.js";
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import logger, { Logger } from "@zhin.js/logger";
 import { compose, remove, resolveEntry } from "./utils.js";
-import { MessageMiddleware, RegisteredAdapter, MaybePromise, ArrayItem, SendOptions } from "./types.js";
+import {
+  MessageMiddleware,
+  RegisteredAdapter,
+  MaybePromise,
+  ArrayItem,
+  SendOptions,
+} from "./types.js";
 import type { ConfigFeature } from "./built/config.js";
 import type { PermissionFeature } from "./built/permission.js";
 import { Adapter, Adapters } from "./adapter.js";
 import { Notice } from "./notice.js";
+import { Message } from "./message.js";
 import { Request } from "./request.js";
 import { Feature, FeatureJSON } from "./feature.js";
 import { createHash } from "crypto";
@@ -910,7 +915,7 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
     'addMiddleware', 'useContext', 'inject', 'contextIsReady',
     'start', 'stop', 'onMounted', 'onDispose',
     'dispatch', 'broadcast', 'provide', 'import', 'reload', 'watch', 'info',
-    'recordFeatureContribution', 'getFeatures'
+    'recordFeatureContribution', 'getFeatures',
   ]);
 
   /**
@@ -1011,6 +1016,17 @@ export interface Context<T extends keyof Plugin.Contexts = keyof Plugin.Contexts
 // ============================================================================
 // 类型定义
 // ============================================================================
+
+/** 登录辅助：bot.login.pending 事件 payload */
+export interface BotLoginPendingTask {
+  id: string;
+  adapter: string;
+  botId: string;
+  type: string;
+  payload?: { message?: string; image?: string; url?: string; [key: string]: unknown };
+  createdAt: number;
+}
+
 export namespace Plugin {
   /**
    * 生命周期事件
@@ -1026,8 +1042,11 @@ export namespace Plugin {
     'before.sendMessage': [SendOptions];
     "context.mounted": [keyof Plugin.Contexts];
     "context.dispose": [keyof Plugin.Contexts];
+    /** 登录辅助：有待办时触发 */
+    'bot.login.pending': [BotLoginPendingTask];
     // Notice 事件
     'notice.receive': [Notice];
+    'message.receive': [Message];
     [key: `notice.${string}`]: [Notice];
     // Request 事件
     'request.receive': [Request];

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)