@zhin.js/core 1.0.45 → 1.0.47

package/lib/request.d.ts

@@ -0,0 +1,85 @@
+import { Adapters } from './adapter.js';
+import type { MessageSender, MaybePromise } from './types.js';
+/**
+ * 请求类型枚举
+ *
+ * 常见 IM 请求事件分类：
+ * - friend_add:  好友添加请求
+ * - group_add:   主动申请入群
+ * - group_invite: 邀请入群请求
+ *
+ * 适配器可自行扩展更多子类型
+ */
+export type RequestType = 'friend_add' | 'group_add' | 'group_invite' | (string & {});
+/**
+ * 请求频道信息
+ */
+export interface RequestChannel {
+    id: string;
+    type: 'group' | 'private' | 'channel';
+}
+/**
+ * 请求基础结构
+ *
+ * 与 MessageBase / NoticeBase 同构设计。
+ * 核心区别：Request 提供 `$approve()` 和 `$reject()` 方法，用于快速处理请求。
+ *
+ * @example
+ * ```typescript
+ * // 适配器中格式化请求
+ * const request = Request.from(rawEvent, {
+ *   $id: rawEvent.flag,
+ *   $adapter: 'icqq',
+ *   $bot: botName,
+ *   $type: 'group_invite',
+ *   $channel: { id: groupId, type: 'group' },
+ *   $sender: { id: userId, name: '邀请者' },
+ *   $comment: '请求加群消息',
+ *   $timestamp: Date.now(),
+ *   $approve: async (remark?) => { await api.approve(flag, remark); },
+ *   $reject: async (reason?) => { await api.reject(flag, reason); },
+ * });
+ * this.adapter.emit('request.receive', request);
+ * ```
+ */
+export interface RequestBase {
+    /** 请求唯一 ID / flag（平台提供的请求标识，用于后续处理） */
+    $id: string;
+    /** 适配器名称 */
+    $adapter: keyof Adapters;
+    /** Bot 名称 */
+    $bot: string;
+    /** 请求类型 */
+    $type: RequestType;
+    /** 请求子类型 */
+    $subType?: string;
+    /** 请求发生的频道/群/会话 */
+    $channel: RequestChannel;
+    /** 请求发送者 */
+    $sender: MessageSender;
+    /** 请求附言/验证消息 */
+    $comment?: string;
+    /** 请求时间戳 */
+    $timestamp: number;
+    /**
+     * 同意请求
+     * @param remark 备注信息（如好友备注）
+     */
+    $approve(remark?: string): MaybePromise<void>;
+    /**
+     * 拒绝请求
+     * @param reason 拒绝原因
+     */
+    $reject(reason?: string): MaybePromise<void>;
+}
+/**
+ * 完整请求类型，支持平台原始数据扩展
+ */
+export type Request<T extends object = {}> = RequestBase & T;
+export declare namespace Request {
+    /**
+     * 工具方法：合并自定义字段与基础请求结构
+     */
+    function from<T extends object>(input: T, format: RequestBase): Request<T>;
+}
+//# sourceMappingURL=request.d.ts.map

package/lib/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,WAAW,GACX,cAAc,GACd,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY;IACZ,QAAQ,EAAE,MAAM,QAAQ,CAAC;IACzB,aAAa;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,KAAK,EAAE,WAAW,CAAC;IACnB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB;IACnB,QAAQ,EAAE,cAAc,CAAC;IACzB,YAAY;IACZ,OAAO,EAAE,aAAa,CAAC;IACvB,gBAAgB;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9C;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,IAAI,WAAW,GAAG,CAAC,CAAC;AAE7D,yBAAiB,OAAO,CAAC;IACvB;;OAEG;IACH,SAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAEhF;CACF"}

package/lib/request.js

@@ -0,0 +1,11 @@
+export var Request;
+(function (Request) {
+    /**
+     * 工具方法：合并自定义字段与基础请求结构
+     */
+    function from(input, format) {
+        return Object.assign(input, format);
+    }
+    Request.from = from;
+})(Request || (Request = {}));
+//# sourceMappingURL=request.js.map

package/lib/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAuFA,MAAM,KAAW,OAAO,CAOvB;AAPD,WAAiB,OAAO;IACtB;;OAEG;IACH,SAAgB,IAAI,CAAmB,KAAQ,EAAE,MAAmB;QAClE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAFe,YAAI,OAEnB,CAAA;AACH,CAAC,EAPgB,OAAO,KAAP,OAAO,QAOvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/core",
-  "version": "1.0.45",
+  "version": "1.0.47",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -37,11 +37,11 @@
     "segment-matcher": "^1.0.5",
     "smol-toml": "^1.6.0",
     "yaml": "^2.3.4",
-    "@zhin.js/ai": "1.0.6",
-    "@zhin.js/database": "1.0.32",
-    "@zhin.js/kernel": "0.0.6",
-    "@zhin.js/logger": "0.1.29",
-    "@zhin.js/schema": "1.0.29"
+    "@zhin.js/ai": "1.0.8",
+    "@zhin.js/database": "1.0.34",
+    "@zhin.js/kernel": "0.0.8",
+    "@zhin.js/logger": "0.1.31",
+    "@zhin.js/schema": "1.0.31"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",

package/src/adapter.ts

@@ -2,29 +2,18 @@ import { Bot } from "./bot.js";
 import { Plugin } from "./plugin.js";
 import { EventEmitter } from "events";
 import { Message } from "./message.js";
+import { Notice, NoticeType } from "./notice.js";
+import { Request, RequestType } from "./request.js";
 import { BeforeSendHandler, SendOptions, Tool, ToolContext, ToolScope } from "./types.js";
 import { segment } from "./utils.js";
 import { ZhinTool, isZhinTool, type ToolInput } from "./built/tool.js";
 import type { Skill, SkillFeature } from "./built/skill.js";
-import {
-  type IGroupManagement,
-  GROUP_METHOD_SPECS,
-  GROUP_MANAGEMENT_SKILL_DESCRIPTION,
-  GROUP_MANAGEMENT_SKILL_TAGS,
-  GROUP_MANAGEMENT_SKILL_KEYWORDS,
-  buildMethodArgs,
-} from "./built/common-adapter-tools.js";
 /**
- * Adapter类：适配器抽象，管理多平台Bot实例。
+ * Adapter 类：适配器抽象，管理多平台 Bot 实例。
  * 负责根据配置启动/关闭各平台机器人，统一异常处理。
  *
- * 适配器可以提供 AI 工具，供 AI 服务调用。
- *
- * 群管理能力：
- *   Adapter 基类声明了 IGroupManagement 中的可选方法规范，
- *   具体适配器（ICQQ/Discord/Telegram 等）选择性覆写。
- *   调用 registerGroupManagementSkill() 后，基类自动检测
- *   哪些方法已被实现，生成对应的 Tool 并注册为 "群聊管理" Skill。
+ * 适配器可提供 AI 工具并声明 Skill。群管等能力由各 IM 平台在子类中
+ * 自行实现方法并注册 Tool（如使用 createGroupManagementTools）+ declareSkill。
  */
 export abstract class Adapter<R extends Bot = Bot> extends EventEmitter<Adapter.Lifecycle> {
   /** 当前适配器下所有Bot实例，key为bot名称 */
@@ -66,6 +55,21 @@ export abstract class Adapter<R extends Bot = Bot> extends EventEmitter<Adapter.
         });
       }
     });
+    this.on('notice.receive', (notice) => {
+      this.logger.info(`${notice.$bot} notice ${notice.$type}${notice.$subType ? '.' + notice.$subType : ''} ${notice.$channel.type}(${notice.$channel.id})`);
+      const rootPlugin = this.plugin?.root || this.plugin;
+      rootPlugin?.dispatch('notice.receive', notice);
+      // 分发细粒度事件: notice.{type} 和 notice.{channelType}.{type}
+      rootPlugin?.dispatch(`notice.${notice.$type}` as 'notice.receive', notice);
+      rootPlugin?.dispatch(`notice.${notice.$channel.type}.${notice.$type}` as 'notice.receive', notice);
+    });
+    this.on('request.receive', (request) => {
+      this.logger.info(`${request.$bot} request ${request.$type}${request.$subType ? '.' + request.$subType : ''} from ${request.$sender.id}`);
+      const rootPlugin = this.plugin?.root || this.plugin;
+      rootPlugin?.dispatch('request.receive', request);
+      // 分发细粒度事件: request.{type}
+      rootPlugin?.dispatch(`request.${request.$type}` as 'request.receive', request);
+    });
   }
   abstract createBot(config: Adapter.BotConfig<R>): R;
   get logger() {
@@ -101,8 +105,6 @@ export abstract class Adapter<R extends Bot = Bot> extends EventEmitter<Adapter.
       this.bots.set(bot.$id, bot);
     }
     this.logger.debug(`adapter ${this.name} started`);
-
-    this._autoDetectGroupManagement();
   }
   /**
    * 停止适配器，断开并移除所有Bot实例
@@ -322,69 +324,6 @@ export abstract class Adapter<R extends Bot = Bot> extends EventEmitter<Adapter.
     });
   }
 
-  // ==========================================================================
-  // 群管理自动检测 — start() 结束时自动执行
-  // ==========================================================================
-
-  /**
-   * 遍历 GROUP_METHOD_SPECS，检测子类是否覆写了对应方法。
-   * 对每个已实现的方法生成 Tool 并注册，最后聚合为 "群聊管理" Skill。
-   */
-  private _autoDetectGroupManagement(): void {
-    const self = this as unknown as IGroupManagement;
-    const prefix = this.name as string;
-    const generatedTools: Tool[] = [];
-
-    for (const spec of GROUP_METHOD_SPECS) {
-      const fn = self[spec.method];
-      if (typeof fn !== 'function') continue;
-
-      const boundFn: (...args: any[]) => Promise<any> = fn.bind(self);
-
-      const properties: Record<string, any> = {
-        bot_id: { type: 'string', description: 'Bot ID', contextKey: 'botId' },
-        scene_id: { type: 'string', description: '群/服务器 ID', contextKey: 'sceneId' },
-      };
-      const required: string[] = ['bot_id', 'scene_id'];
-
-      for (const [name, schema] of Object.entries(spec.extraParams)) {
-        properties[name] = schema;
-      }
-      if (spec.extraRequired) {
-        required.push(...spec.extraRequired);
-      }
-
-      const tool: Tool = {
-        name: `${prefix}_${spec.toolSuffix}`,
-        description: `${spec.description} (${prefix})`,
-        parameters: { type: 'object' as const, properties, required },
-        execute: async (args: Record<string, any>) => {
-          const { bot_id, scene_id, ...rest } = args;
-          return boundFn(...buildMethodArgs(spec.method, bot_id, scene_id, rest));
-        },
-        tags: ['group', 'management', prefix],
-        keywords: spec.keywords,
-        permissionLevel: spec.permissionLevel,
-        scopes: ['group', 'channel'] as ToolScope[],
-        preExecutable: spec.preExecutable,
-      };
-
-      this.addTool(tool);
-      generatedTools.push(tool);
-    }
-
-    if (generatedTools.length === 0) return;
-
-    this.declareSkill({
-      description: GROUP_MANAGEMENT_SKILL_DESCRIPTION,
-      keywords: GROUP_MANAGEMENT_SKILL_KEYWORDS,
-      tags: GROUP_MANAGEMENT_SKILL_TAGS,
-    });
-
-    this.logger.debug(
-      `自动检测到 ${generatedTools.length} 个群管理方法 → 已注册 Skill`,
-    );
-  }
 }
 export interface Adapters {}
 export namespace Adapter {
@@ -400,6 +339,14 @@ export namespace Adapter {
     'message.private.receive': [Message];
     'message.group.receive': [Message];
     'message.channel.receive': [Message];
+    'notice.receive': [Notice];
+    'notice.private.receive': [Notice];
+    'notice.group.receive': [Notice];
+    'notice.channel.receive': [Notice];
+    'request.receive': [Request];
+    'request.friend_add': [Request];
+    'request.group_add': [Request];
+    'request.group_invite': [Request];
     'call.recallMessage': [string, string];
   }
   /**

package/src/bot.ts

@@ -1,11 +1,13 @@
 import type { SendOptions } from "./types.js";
 import { Message } from "./message.js";
+import { Notice } from "./notice.js";
+import { Request } from "./request.js";
 import { Adapter, Adapters } from "./adapter.js";
 /**
  * Bot接口：所有平台机器人需实现的统一接口。
  * 负责消息格式化、连接、断开、消息发送等。
- * @template M 消息类型
- * @template T 配置类型
+ * @template Config 配置类型
+ * @template Event 消息事件类型
  */
 export interface Bot<Config extends object= {},Event extends object = {}> {
   $id:string
@@ -15,6 +17,10 @@ export interface Bot<Config extends object= {},Event extends object = {}> {
   $connected: boolean;
   /** 格式化平台消息为标准Message结构 */
   $formatMessage(event: Event): Message<Event>;
+  /** 格式化平台通知为标准Notice结构（适配器可选实现） */
+  $formatNotice?(event: any): Notice<any>;
+  /** 格式化平台请求为标准Request结构（适配器可选实现） */
+  $formatRequest?(event: any): Request<any>;
   /** 连接机器人 */
   $connect(): Promise<void>;
   /** 断开机器人 */

package/src/built/common-adapter-tools.ts

@@ -1,23 +1,19 @@
 /**
- * Group Management Skill — 方法规范与元数据
+ * Group Management — 方法规范与 Tool 工厂
  *
  * 设计理念：
- *   群管理是 IM 系统的一种"技能"(Skill)，而非一组零散的工具。
- *   Adapter 基类声明群管理操作的方法规范（可选），
- *   具体适配器（ICQQ/Discord/Telegram 等）选择性覆写。
- *   Adapter.start() 自动检测哪些方法已被子类实现，
- *   生成对应的 Tool 并注册为 "群聊管理" Skill。
+ *   各 IM 平台在适配器内自行实现群管方法（kickMember、muteMember 等），
+ *   并自行注册 Tool 与 declareSkill，保障平台特性与描述一致。
  *
- * 子类无需任何额外调用：
+ * 使用方式（在各适配器 start 或注册方法中）：
  *
- *   class IcqqAdapter extends Adapter<IcqqBot> {
- *     async kickMember(botId, sceneId, userId) { ... }
- *     async muteMember(botId, sceneId, userId, duration) { ... }
- *     // start() 中自动检测 → 自动注册 Skill，零样板代码
- *   }
+ *   import { createGroupManagementTools, GROUP_MANAGEMENT_SKILL_KEYWORDS, GROUP_MANAGEMENT_SKILL_TAGS } from 'zhin.js';
+ *   const tools = createGroupManagementTools(this, this.name);
+ *   tools.forEach(t => this.addTool(t));
+ *   this.declareSkill({ description: '本平台群管说明...', keywords: [...], tags: [...] });
  */
 
-import type { ToolPermissionLevel } from '../types.js';
+import type { Tool, ToolPermissionLevel, ToolScope } from '../types.js';
 
 // ============================================================================
 // Adapter 群管理方法规范
@@ -168,25 +164,58 @@ export const GROUP_METHOD_SPECS: GroupMethodSpec[] = [
 ];
 
 // ============================================================================
-// Skill 常量
+// Skill 常量（各适配器 declareSkill 时可复用 keywords/tags）
 // ============================================================================
 
-export const GROUP_MANAGEMENT_SKILL_DESCRIPTION =
-  '群聊管理能力：在 IM 系统中对群/服务器进行管理，包括踢人、禁言、封禁、' +
-  '设置管理员、修改群名、查看成员列表等操作。具体可用的操作取决于平台和 Bot 权限。\n\n' +
-  '使用指南：\n' +
-  '1. 用户提供昵称/名片而非 ID 时，必须先调用 list_members 查询成员列表，从返回结果中匹配目标用户的 user_id，再执行后续操作\n' +
-  '2. 禁言(mute_member)适用场景：违规发言、刷屏、骚扰他人等；传 duration=0 可解除禁言\n' +
-  '3. 设置/取消管理员(set_admin)需要群主权限，普通管理员无法操作；enable=false 为取消管理员\n' +
-  '4. 踢人(kick_member)是将成员移出群聊，封禁(ban_member)是永久拉黑，两者不同\n' +
-  '5. 操作前应确认目标用户正确，避免误操作';
-
 export const GROUP_MANAGEMENT_SKILL_TAGS = ['group', 'management', 'im', 'admin'];
 export const GROUP_MANAGEMENT_SKILL_KEYWORDS = [
   '群管理', '踢人', '禁言', '封禁', '管理员', '群名',
   '成员', 'kick', 'mute', 'ban', 'admin', 'members',
 ];
 
+// ============================================================================
+// 工厂：根据已实现的方法为指定适配器生成群管 Tool 列表（各平台自行调用并 addTool）
+// ============================================================================
+
+export function createGroupManagementTools(
+  adapter: IGroupManagement,
+  prefix: string,
+): Tool[] {
+  const tools: Tool[] = [];
+  for (const spec of GROUP_METHOD_SPECS) {
+    const fn = adapter[spec.method];
+    if (typeof fn !== 'function') continue;
+
+    const properties: Record<string, any> = {
+      bot_id: { type: 'string', description: 'Bot ID', contextKey: 'botId' },
+      scene_id: { type: 'string', description: '群/服务器 ID', contextKey: 'sceneId' },
+    };
+    const required: string[] = ['bot_id', 'scene_id'];
+    for (const [name, schema] of Object.entries(spec.extraParams)) {
+      properties[name] = schema;
+    }
+    if (spec.extraRequired) required.push(...spec.extraRequired);
+
+    const boundFn = fn.bind(adapter);
+    tools.push({
+      name: `${prefix}_${spec.toolSuffix}`,
+      description: `${spec.description} (${prefix})`,
+      parameters: { type: 'object' as const, properties, required },
+      execute: async (args: Record<string, any>) => {
+        const { bot_id, scene_id, ...rest } = args;
+        const methodArgs = buildMethodArgs(spec.method, bot_id, scene_id, rest);
+        return (boundFn as (...a: any[]) => Promise<any>).apply(adapter, methodArgs);
+      },
+      tags: ['group', 'management', prefix],
+      keywords: spec.keywords,
+      permissionLevel: spec.permissionLevel,
+      scopes: ['group', 'channel'] as ToolScope[],
+      preExecutable: spec.preExecutable,
+    });
+  }
+  return tools;
+}
+
 // ============================================================================
 // 参数映射（method → 有序参数列表）
 // ============================================================================
@@ -208,6 +237,6 @@ export function buildMethodArgs(
     case 'setGroupName':    return [botId, sceneId, rest.name];
     case 'muteAll':         return [botId, sceneId, rest.enable ?? true];
     case 'getGroupInfo':    return [botId, sceneId];
-    default:                return [botId, sceneId, ...Object.values(rest)];
+    default:                return [botId, sceneId, ...(Object.values(rest) as any[])];
   }
 }