@zhin.js/core 1.0.45 → 1.0.47

package/src/built/message-filter.ts

@@ -0,0 +1,390 @@
+/**
+ * MessageFilterFeature — 消息过滤引擎
+ *
+ * 设计理念：
+ *   将过滤规则视为 Feature Item，与命令 (CommandFeature)、权限 (PermissionFeature) 同构，
+ *   遵循框架的 add/remove/extensions/toJSON 范式，支持插件级 CRUD 和生命周期自动回收。
+ *
+ * 核心特性：
+ *   - 基于优先级的规则引擎（first-match-wins，类似防火墙规则）
+ *   - 多维匹配：scope / adapter / bot / channel / sender
+ *   - 支持精确匹配、通配符 `*`、正则 `/pattern/`
+ *   - 通过 Dispatcher Guardrail 集成，在消息调度第一阶段拦截
+ *   - 插件通过 `addFilterRule()` 动态注册规则，卸载时自动清理
+ */
+
+import { Feature, FeatureJSON } from '../feature.js';
+import { getPlugin } from '../plugin.js';
+import type { Message, MessageType } from '../message.js';
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+/** 过滤动作 */
+export type FilterAction = 'allow' | 'deny';
+
+/** 匹配模式：精确字符串 / 正则表达式 */
+export type FilterPattern = string | RegExp;
+
+/** 消息作用域 */
+export type FilterScope = MessageType; // 'private' | 'group' | 'channel'
+
+/**
+ * 过滤规则
+ *
+ * 每条规则描述一组匹配条件和对应的动作。
+ * 所有条件之间为 AND 关系（必须全部满足），每个条件内部的多个值为 OR 关系（满足任一即可）。
+ * 未设置的条件视为匹配所有。
+ *
+ * @example
+ * // 拒绝特定群的消息
+ * { name: 'block-spam', action: 'deny', scopes: ['group'], channels: ['123456'] }
+ *
+ * // 放行 VIP 用户（高优先级）
+ * { name: 'allow-vip', action: 'allow', priority: 100, senders: ['admin001'] }
+ *
+ * // 正则匹配：拒绝所有 test- 开头的频道
+ * { name: 'block-test', action: 'deny', scopes: ['channel'], channels: [/^test-/] }
+ */
+export interface FilterRule {
+  /** 规则名称（唯一标识） */
+  name: string;
+  /** 规则描述 */
+  description?: string;
+  /** 过滤动作：allow 放行 / deny 拦截 */
+  action: FilterAction;
+  /** 优先级，数值越大越先匹配（默认 0） */
+  priority?: number;
+  /** 是否启用（默认 true） */
+  enabled?: boolean;
+  /** 匹配的消息作用域，未设置则匹配所有 */
+  scopes?: FilterScope[];
+  /** 匹配的适配器名称 */
+  adapters?: FilterPattern[];
+  /** 匹配的 Bot 名称 */
+  bots?: FilterPattern[];
+  /** 匹配的频道/群/会话 ID */
+  channels?: FilterPattern[];
+  /** 匹配的发送者 ID */
+  senders?: FilterPattern[];
+}
+
+/** 过滤检测结果 */
+export interface FilterResult {
+  /** 是否允许处理 */
+  allowed: boolean;
+  /** 匹配到的规则名称（null 表示无规则匹配，走默认策略） */
+  matchedRule: string | null;
+  /** 结果原因 */
+  reason: string;
+}
+
+// ---- 配置类型 ----
+
+/** 配置文件中的规则（pattern 均为 string，正则用 /pattern/ 表示） */
+export interface FilterRuleConfig {
+  name: string;
+  description?: string;
+  action: FilterAction;
+  priority?: number;
+  enabled?: boolean;
+  scopes?: FilterScope[];
+  adapters?: string[];
+  bots?: string[];
+  channels?: string[];
+  senders?: string[];
+}
+
+/**
+ * 消息过滤配置
+ *
+ * ```yaml
+ * message_filter:
+ *   default_policy: allow
+ *   rules:
+ *     - name: block-spam
+ *       action: deny
+ *       scopes: [group]
+ *       channels: ['123456']
+ *     - name: vip-pass
+ *       action: allow
+ *       priority: 100
+ *       senders: ['admin001']
+ * ```
+ */
+export interface MessageFilterConfig {
+  /** 默认策略：无规则匹配时的行为（默认 'allow'） */
+  default_policy?: FilterAction;
+  /** 规则列表 */
+  rules?: FilterRuleConfig[];
+}
+
+// ============================================================================
+// Plugin 扩展声明
+// ============================================================================
+
+export interface MessageFilterContextExtensions {
+  /** 添加过滤规则，返回 dispose 函数 */
+  addFilterRule(rule: FilterRule): () => void;
+  /** 检测消息是否应被处理 */
+  testFilter(message: Message<any>): FilterResult;
+  /** 设置默认过滤策略 */
+  setDefaultFilterPolicy(policy: FilterAction): void;
+}
+
+declare module '../plugin.js' {
+  namespace Plugin {
+    interface Extensions extends MessageFilterContextExtensions {}
+    interface Contexts {
+      'message-filter': MessageFilterFeature;
+    }
+  }
+}
+
+// ============================================================================
+// 规则工厂
+// ============================================================================
+
+export namespace FilterRules {
+  /** 创建拒绝规则 */
+  export function deny(name: string, conditions: Omit<FilterRule, 'name' | 'action'>): FilterRule {
+    return { ...conditions, name, action: 'deny' };
+  }
+
+  /** 创建放行规则 */
+  export function allow(name: string, conditions: Omit<FilterRule, 'name' | 'action'>): FilterRule {
+    return { ...conditions, name, action: 'allow' };
+  }
+
+  /**
+   * 创建黑名单规则组
+   * @returns 一条 deny 规则
+   */
+  export function blacklist(
+    scope: FilterScope,
+    ids: string[],
+    name?: string,
+  ): FilterRule {
+    return {
+      name: name ?? `${scope}-blacklist`,
+      action: 'deny',
+      scopes: [scope],
+      channels: ids,
+    };
+  }
+
+  /**
+   * 创建白名单规则组
+   * @returns [allow 规则, deny-catch-all 规则]
+   */
+  export function whitelist(
+    scope: FilterScope,
+    ids: string[],
+    name?: string,
+  ): [FilterRule, FilterRule] {
+    const baseName = name ?? `${scope}-whitelist`;
+    return [
+      { name: baseName, action: 'allow', scopes: [scope], channels: ids, priority: 1 },
+      { name: `${baseName}-deny-rest`, action: 'deny', scopes: [scope], priority: -100 },
+    ];
+  }
+}
+
+// ============================================================================
+// Feature 实现
+// ============================================================================
+
+export class MessageFilterFeature extends Feature<FilterRule> {
+  readonly name = 'message-filter' as const;
+  readonly icon = 'Filter';
+  readonly desc = '消息过滤';
+
+  /** 按规则名称索引 */
+  readonly byName = new Map<string, FilterRule>();
+
+  #defaultPolicy: FilterAction = 'allow';
+  #sortedCache: FilterRule[] | null = null;
+
+  constructor(config?: MessageFilterConfig) {
+    super();
+    if (config) this.#loadConfig(config);
+  }
+
+  // ---- 公共 API ----
+
+  /** 默认策略 */
+  get defaultPolicy(): FilterAction { return this.#defaultPolicy; }
+  set defaultPolicy(policy: FilterAction) { this.#defaultPolicy = policy; }
+
+  /** 获取按优先级排序的启用规则列表（带缓存） */
+  get sortedRules(): FilterRule[] {
+    if (!this.#sortedCache) {
+      this.#sortedCache = [...this.items]
+        .filter(r => r.enabled !== false)
+        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    }
+    return this.#sortedCache;
+  }
+
+  /** 按名称查询规则 */
+  getRule(name: string): FilterRule | undefined {
+    return this.byName.get(name);
+  }
+
+  /**
+   * 检测消息是否应该被处理
+   *
+   * 遍历按优先级排序的规则列表，返回第一个匹配的规则结果。
+   * 若无规则匹配，按默认策略决定。
+   */
+  test(message: Message<any>): FilterResult {
+    for (const rule of this.sortedRules) {
+      if (this.#matchRule(rule, message)) {
+        return {
+          allowed: rule.action === 'allow',
+          matchedRule: rule.name,
+          reason: `matched rule "${rule.name}" → ${rule.action}`,
+        };
+      }
+    }
+    return {
+      allowed: this.#defaultPolicy === 'allow',
+      matchedRule: null,
+      reason: `no rule matched → default policy: ${this.#defaultPolicy}`,
+    };
+  }
+
+  // ---- Feature 重写 ----
+
+  /** 添加规则，维护 byName 索引 */
+  add(rule: FilterRule, pluginName: string): () => void {
+    this.byName.set(rule.name, rule);
+    this.#sortedCache = null;
+    return super.add(rule, pluginName);
+  }
+
+  /** 移除规则，清理 byName 索引 */
+  remove(rule: FilterRule, pluginName?: string): boolean {
+    this.byName.delete(rule.name);
+    this.#sortedCache = null;
+    return super.remove(rule, pluginName);
+  }
+
+  /** 序列化为 JSON（供 Web 控制台展示） */
+  toJSON(pluginName?: string): FeatureJSON {
+    const list = pluginName ? this.getByPlugin(pluginName) : this.items;
+    return {
+      name: this.name,
+      icon: this.icon,
+      desc: this.desc,
+      count: list.length,
+      items: list.map(r => ({
+        name: r.name,
+        description: r.description,
+        action: r.action,
+        priority: r.priority ?? 0,
+        enabled: r.enabled !== false,
+        scopes: r.scopes,
+        adapters: r.adapters?.map(p => p instanceof RegExp ? p.source : p),
+        bots: r.bots?.map(p => p instanceof RegExp ? p.source : p),
+        channels: r.channels?.map(p => p instanceof RegExp ? p.source : p),
+        senders: r.senders?.map(p => p instanceof RegExp ? p.source : p),
+      })),
+    };
+  }
+
+  /** 插件扩展方法 */
+  get extensions() {
+    const feature = this;
+    return {
+      addFilterRule(rule: FilterRule) {
+        const plugin = getPlugin();
+        const dispose = feature.add(rule, plugin.name);
+        plugin.recordFeatureContribution(feature.name, rule.name);
+        plugin.onDispose(dispose);
+        return dispose;
+      },
+      testFilter(message: Message<any>) {
+        return feature.test(message);
+      },
+      setDefaultFilterPolicy(policy: FilterAction) {
+        feature.defaultPolicy = policy;
+      },
+    };
+  }
+
+  // ============================================================================
+  // 配置加载
+  // ============================================================================
+
+  #loadConfig(config: MessageFilterConfig): void {
+    if (config.default_policy) {
+      this.#defaultPolicy = config.default_policy;
+    }
+
+    if (config.rules) {
+      for (const rc of config.rules) {
+        this.add(this.#parseRuleConfig(rc), '__config__');
+      }
+    }
+  }
+
+  // ============================================================================
+  // 规则匹配
+  // ============================================================================
+
+  /** 解析配置中的规则字符串为 FilterPattern */
+  #parseRuleConfig(rc: FilterRuleConfig): FilterRule {
+    return {
+      name: rc.name,
+      description: rc.description,
+      action: rc.action,
+      priority: rc.priority,
+      enabled: rc.enabled,
+      scopes: rc.scopes,
+      adapters: rc.adapters?.map(p => this.#parsePattern(p)),
+      bots: rc.bots?.map(p => this.#parsePattern(p)),
+      channels: rc.channels?.map(p => this.#parsePattern(p)),
+      senders: rc.senders?.map(p => this.#parsePattern(p)),
+    };
+  }
+
+  /** 解析单个 pattern："/regex/flags" → RegExp，其余为精确字符串 */
+  #parsePattern(pattern: string): FilterPattern {
+    const match = pattern.match(/^\/(.+)\/([gimsuy]*)$/);
+    if (match) {
+      return new RegExp(match[1], match[2]);
+    }
+    return pattern;
+  }
+
+  /** 检查规则是否匹配消息（所有条件 AND，条件内 OR） */
+  #matchRule(rule: FilterRule, message: Message<any>): boolean {
+    if (rule.scopes?.length && !rule.scopes.includes(message.$channel.type as FilterScope)) {
+      return false;
+    }
+    if (rule.adapters?.length && !this.#matchAny(rule.adapters, String(message.$adapter))) {
+      return false;
+    }
+    if (rule.bots?.length && !this.#matchAny(rule.bots, String(message.$bot))) {
+      return false;
+    }
+    if (rule.channels?.length && !this.#matchAny(rule.channels, String(message.$channel.id))) {
+      return false;
+    }
+    if (rule.senders?.length && !this.#matchAny(rule.senders, String(message.$sender.id))) {
+      return false;
+    }
+    return true;
+  }
+
+  /** 检查值是否与任一 pattern 匹配 */
+  #matchAny(patterns: FilterPattern[], value: string): boolean {
+    return patterns.some(p => {
+      if (p instanceof RegExp) return p.test(value);
+      if (p === '*') return true;
+      return p === value;
+    });
+  }
+}

package/src/index.ts

@@ -6,6 +6,8 @@ export * from './command.js'
 export * from './component.js'
 export * from './adapter.js'
 export * from './message.js'
+export * from './notice.js'
+export * from './request.js'
 export * from './prompt.js'
 // Models
 export * from './models/system-log.js'
@@ -18,6 +20,7 @@ export * from './built/permission.js'
 export * from './built/adapter-process.js'
 export * from './built/component.js'
 export * from './built/database.js'
+export * from './built/message-filter.js'
 // Tool Service (纯工具，无副作用)
 export * from './built/tool.js'
 // AI Trigger Service (纯工具，无副作用)

package/src/notice.ts

@@ -0,0 +1,98 @@
+import { Adapters } from './adapter.js';
+import type { MessageSender } from './types.js';
+
+/**
+ * 通知类型枚举
+ *
+ * 常见 IM 通知事件分类：
+ * - group_member_increase: 群成员增加（入群）
+ * - group_member_decrease: 群成员减少（退群/被踢）
+ * - group_admin_change:    群管理员变动
+ * - group_ban:             群禁言
+ * - group_recall:          群消息撤回
+ * - friend_recall:         好友消息撤回
+ * - friend_add:            新增好友
+ * - group_poke:            群戳一戳
+ * - friend_poke:           好友戳一戳
+ * - group_transfer:        群转让
+ *
+ * 适配器可自行扩展更多子类型
+ */
+export type NoticeType =
+  | 'group_member_increase'
+  | 'group_member_decrease'
+  | 'group_admin_change'
+  | 'group_ban'
+  | 'group_recall'
+  | 'friend_recall'
+  | 'friend_add'
+  | 'group_poke'
+  | 'friend_poke'
+  | 'group_transfer'
+  | (string & {}); // 允许适配器扩展自定义类型
+
+/**
+ * 通知频道信息
+ */
+export interface NoticeChannel {
+  id: string;
+  type: 'group' | 'private' | 'channel';
+}
+
+/**
+ * 通知基础结构
+ *
+ * 与 MessageBase 同构设计，所有通知共享以下字段。
+ * 适配器通过 `Notice.from(raw, base)` 合并平台原始数据和标准字段。
+ *
+ * @example
+ * ```typescript
+ * // 适配器中格式化通知
+ * const notice = Notice.from(rawEvent, {
+ *   $id: rawEvent.id,
+ *   $adapter: 'icqq',
+ *   $bot: botName,
+ *   $type: 'group_member_decrease',
+ *   $subType: 'kick',
+ *   $channel: { id: groupId, type: 'group' },
+ *   $operator: { id: operatorId, name: '管理员' },
+ *   $target: { id: userId, name: '被踢者' },
+ *   $timestamp: Date.now(),
+ * });
+ * this.adapter.emit('notice.receive', notice);
+ * ```
+ */
+export interface NoticeBase {
+  /** 通知唯一 ID（平台提供或自生成） */
+  $id: string;
+  /** 适配器名称 */
+  $adapter: keyof Adapters;
+  /** Bot 名称 */
+  $bot: string;
+  /** 通知类型 */
+  $type: NoticeType;
+  /** 通知子类型（如 leave/kick、set/unset） */
+  $subType?: string;
+  /** 通知发生的频道/群/会话 */
+  $channel: NoticeChannel;
+  /** 操作者信息（如管理员） */
+  $operator?: MessageSender;
+  /** 被操作目标信息（如被踢的成员） */
+  $target?: MessageSender;
+  /** 通知时间戳 */
+  $timestamp: number;
+}
+
+/**
+ * 完整通知类型，支持平台原始数据扩展
+ */
+export type Notice<T extends object = {}> = NoticeBase & T;
+
+export namespace Notice {
+  /**
+   * 工具方法：合并自定义字段与基础通知结构
+   */
+  export function from<T extends object>(input: T, format: NoticeBase): Notice<T> {
+    return Object.assign(input, format);
+  }
+}

package/src/plugin.ts

@@ -18,6 +18,8 @@ import { MessageMiddleware, RegisteredAdapter, MaybePromise, ArrayItem, SendOpti
 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 { Request } from "./request.js";
 import { Feature, FeatureJSON } from "./feature.js";
 import { createHash } from "crypto";
 const contextsKey = Symbol("contexts");
@@ -1024,6 +1026,12 @@ export namespace Plugin {
     'before.sendMessage': [SendOptions];
     "context.mounted": [keyof Plugin.Contexts];
     "context.dispose": [keyof Plugin.Contexts];
+    // Notice 事件
+    'notice.receive': [Notice];
+    [key: `notice.${string}`]: [Notice];
+    // Request 事件
+    'request.receive': [Request];
+    [key: `request.${string}`]: [Request];
   }
 
   /**

package/src/request.ts

@@ -0,0 +1,95 @@
+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 namespace Request {
+  /**
+   * 工具方法：合并自定义字段与基础请求结构
+   */
+  export function from<T extends object>(input: T, format: RequestBase): Request<T> {
+    return Object.assign(input, format);
+  }
+}