@zhin.js/core 1.0.57 → 1.1.2

package/src/built/ai-trigger.ts

@@ -1,259 +0,0 @@
-/**
- * AI Trigger 工具函数
- * 提供 AI 触发相关的工具函数，可在插件中直接使用
- * 
- * 触发方式：
- * 1. @机器人 - 在群聊中 @ 机器人触发
- * 2. 前缀触发 - 使用配置的前缀（如 # 或 AI:）
- * 3. 私聊直接对话 - 私聊时直接对话
- * 4. 关键词触发 - 包含特定关键词时触发
- */
-
-import { Message } from "../message.js";
-import type { 
-  MessageElement,
-  ToolScope,
-  ToolPermissionLevel,
-  MaybePromise, 
-} from "../types.js";
-import { segment } from "../utils.js";
-
-// ============================================================================
-// 类型定义
-// ============================================================================
-
-/**
- * AI 触发配置
- */
-export interface AITriggerConfig {
-  /** 是否启用（默认 true） */
-  enabled?: boolean;
-  
-  /** 触发前缀列表（默认 ['#', 'AI:']） */
-  prefixes?: string[];
-  
-  /** 是否响应 @ 机器人（默认 true） */
-  respondToAt?: boolean;
-  
-  /** 是否响应私聊（默认 true） */
-  respondToPrivate?: boolean;
-  
-  /** 触发关键词（可选） */
-  keywords?: string[];
-  
-  /** 忽略的前缀（命令前缀，避免与命令冲突） */
-  ignorePrefixes?: string[];
-  
-  /** 超时时间（毫秒，默认 60000） */
-  timeout?: number;
-  
-  /** 思考中提示（可选） */
-  thinkingMessage?: string;
-  
-  /** 错误消息模板 */
-  errorTemplate?: string;
-  
-  /** Zhin 拥有者 ID 列表 */
-  owners?: string[];
-  
-  /** 机器人管理员 ID 列表 */
-  botAdmins?: string[];
-}
-
-/**
- * AI 触发检查结果
- */
-export interface AITriggerResult {
-  triggered: boolean;
-  content: string;
-}
-
-/**
- * 发送者权限信息
- */
-export interface SenderPermissions {
-  scope: ToolScope;
-  isGroupAdmin: boolean;
-  isGroupOwner: boolean;
-  isBotAdmin: boolean;
-  isOwner: boolean;
-  permissionLevel: ToolPermissionLevel;
-}
-
-// ============================================================================
-// 默认配置
-// ============================================================================
-
-export const DEFAULT_AI_TRIGGER_CONFIG: Required<AITriggerConfig> = {
-  enabled: true,
-  prefixes: ['#', 'AI:', 'ai:'],
-  respondToAt: true,
-  respondToPrivate: true,
-  keywords: [],
-  ignorePrefixes: ['/', '!', '！'],
-  timeout: 60000,
-  thinkingMessage: '',
-  errorTemplate: '❌ AI 处理失败: {error}',
-  owners: [],
-  botAdmins: [],
-};
-
-// ============================================================================
-// 工具函数
-// ============================================================================
-
-/**
- * 检查消息是否 @ 了机器人
- */
-export function isAtBot<T extends object>(message: Message<T>): boolean {
-  const botId = String(message.$bot);
-  return message.$content.some(seg =>  {
-    return String(seg.data?.qq) === botId || String(seg.data?.user_id) === botId;
-  });
-}
-
-/**
- * 提取消息文本内容（保留富媒体信息）
- * 使用 segment.toString 将 MessageElement 转为 XML 格式
- */
-export function extractTextContent<T extends object>(message: Message<T>): string {
-  return segment.toString(message.$content);
-}
-
-/**
- * 解析 AI 回复中的富媒体内容
- * 将字符串中的 XML-like 标签解析为 MessageElement
- */
-export function parseRichMediaContent(content: string): MessageElement[] {
-  try {
-    const parsed = segment.from(content);
-    const elements = Array.isArray(parsed) ? parsed : [parsed];
-    return elements.map(el => {
-      if (typeof el === 'string') {
-        return { type: 'text', data: { text: el } };
-      }
-      return el as MessageElement;
-    });
-  } catch (error) {
-    return [{ type: 'text', data: { text: content } }];
-  }
-}
-
-/**
- * 移除 @ 机器人的部分
- */
-export function removeAtBot<T extends object>(message: Message<T>): MessageElement[] {
-  const botId = String(message.$bot);
-  return message.$content.filter(seg => {
-    const { type, data } = seg;
-    if (type !== "at") return true; // 非 at 段全部保留
-    const userId = String(data?.user_id || data?.qq);
-    return userId !== botId; // 只移除 @机器人 的段，保留 @其他人
-  });
-}
-
-/**
- * 从消息中推断发送者的权限级别
- */
-export function inferSenderPermissions<T extends object>(
-  message: Message<T>,
-  config: AITriggerConfig
-): SenderPermissions {
-  const scope: ToolScope = message.$channel?.type as ToolScope || 'private';
-  const senderId = message.$sender.id;
-  const senderPermissions = message.$sender.permissions || [];
-  
-  const owners = config.owners || [];
-  const isOwner = owners.includes(senderId);
-  
-  const botAdmins = config.botAdmins || [];
-  const isBotAdmin = isOwner || botAdmins.includes(senderId);
-  
-  const isGroupOwner = senderPermissions.includes('owner') || 
-                       senderPermissions.includes('group_owner') ||
-                       message.$sender?.role === 'owner';
-  
-  const isGroupAdmin = isGroupOwner || 
-                       senderPermissions.includes('admin') || 
-                       senderPermissions.includes('group_admin') ||
-                       message.$sender?.role === 'admin';
-  
-  let permissionLevel: ToolPermissionLevel = 'user';
-  if (isOwner) permissionLevel = 'owner';
-  else if (isBotAdmin) permissionLevel = 'bot_admin';
-  else if (isGroupOwner) permissionLevel = 'group_owner';
-  else if (isGroupAdmin) permissionLevel = 'group_admin';
-  
-  return {
-    scope,
-    isGroupAdmin,
-    isGroupOwner,
-    isBotAdmin,
-    isOwner,
-    permissionLevel,
-  };
-}
-
-/**
- * 检查消息是否应该触发 AI
- */
-export function shouldTriggerAI<T extends object>(
-  message: Message<T>, 
-  config: AITriggerConfig
-): AITriggerResult {
-  const fullConfig = { ...DEFAULT_AI_TRIGGER_CONFIG, ...config };
-  
-  if (!fullConfig.enabled) {
-    return { triggered: false, content: '' };
-  }
-  
-  const text = extractTextContent(message);
-  
-  // 检查忽略前缀
-  for (const prefix of fullConfig.ignorePrefixes) {
-    if (text.startsWith(prefix)) {
-      return { triggered: false, content: '' };
-    }
-  }
-  
-  // 1. 检查前缀触发
-  for (const prefix of fullConfig.prefixes) {
-    if (text.startsWith(prefix)) {
-      return { triggered: true, content: text.slice(prefix.length).trim() };
-    }
-  }
-  
-  // 2. 检查 @ 触发
-  if (fullConfig.respondToAt && isAtBot(message)) {
-    const content = removeAtBot(message);
-    if (content.length) {
-      return { triggered: true, content: segment.toString(content) };
-    }
-  }
-  
-  // 3. 检查私聊触发
-  if (fullConfig.respondToPrivate && message.$channel?.type === 'private') {
-    if (text.trim()) {
-      return { triggered: true, content: text.trim() };
-    }
-  }
-  
-  // 4. 检查关键词触发
-  if (fullConfig.keywords.length > 0) {
-    const lowerText = text.toLowerCase();
-    for (const keyword of fullConfig.keywords) {
-      if (lowerText.includes(keyword.toLowerCase())) {
-        return { triggered: true, content: text };
-      }
-    }
-  }
-  
-  return { triggered: false, content: '' };
-}
-
-/**
- * 合并配置
- */
-export function mergeAITriggerConfig(config: AITriggerConfig): Required<AITriggerConfig> {
-  return { ...DEFAULT_AI_TRIGGER_CONFIG, ...config };
-}

package/src/built/command.ts

@@ -1,108 +0,0 @@
-/**
- * CommandFeature
- * 管理所有插件注册的命令，继承自 Feature 抽象类
- */
-import { Feature, FeatureJSON } from "../feature.js";
-import { MessageCommand } from "../command.js";
-import { Message } from "../message.js";
-import { Plugin, getPlugin } from "../plugin.js";
-import type { RegisteredAdapter, AdapterMessage } from "../types.js";
-
-/**
- * CommandContext 扩展方法类型
- */
-export interface CommandContextExtensions {
-  /** 添加命令 */
-  addCommand<T extends RegisteredAdapter>(command: MessageCommand<T>): () => void;
-}
-
-// 扩展 Plugin 接口
-declare module "../plugin.js" {
-  namespace Plugin {
-    interface Extensions extends CommandContextExtensions {}
-    interface Contexts {
-      command: CommandFeature;
-    }
-  }
-}
-
-/**
- * 命令服务 Feature
- */
-export class CommandFeature extends Feature<MessageCommand<RegisteredAdapter>> {
-  readonly name = 'command' as const;
-  readonly icon = 'Terminal';
-  readonly desc = '命令';
-
-  /** 按 pattern 索引 */
-  readonly byName = new Map<string, MessageCommand<RegisteredAdapter>>();
-
-  /**
-   * 添加命令
-   */
-  add(command: MessageCommand<RegisteredAdapter>, pluginName: string): () => void {
-    this.byName.set(command.pattern, command);
-    return super.add(command, pluginName);
-  }
-
-  /**
-   * 移除命令
-   */
-  remove(command: MessageCommand<RegisteredAdapter>): boolean {
-    this.byName.delete(command.pattern);
-    return super.remove(command);
-  }
-
-  /**
-   * 按 pattern 获取命令
-   */
-  get(pattern: string): MessageCommand<RegisteredAdapter> | undefined {
-    return this.byName.get(pattern);
-  }
-
-  /**
-   * 处理消息，依次尝试匹配命令
-   */
-  async handle(message: Message<AdapterMessage<RegisteredAdapter>>, plugin: Plugin): Promise<any> {
-    for (const command of this.items) {
-      const result = await command.handle(message, plugin);
-      if (result) return result;
-    }
-    return null;
-  }
-
-  /**
-   * 序列化为 JSON
-   */
-  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(c => ({
-        name: c.pattern,
-        desc: c.helpInfo?.desc,
-        usage: c.helpInfo?.usage,
-        examples: c.helpInfo?.examples,
-      })),
-    };
-  }
-
-  /**
-   * 提供给 Plugin.prototype 的扩展方法
-   */
-  get extensions() {
-    const feature = this;
-    return {
-      addCommand<T extends RegisteredAdapter>(command: MessageCommand<T>) {
-        const plugin = getPlugin();
-        const dispose = feature.add(command as MessageCommand<RegisteredAdapter>, plugin.name);
-        plugin.recordFeatureContribution(feature.name, command.pattern);
-        plugin.onDispose(dispose);
-        return dispose;
-      },
-    };
-  }
-}

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

@@ -1,242 +0,0 @@
-/**
- * Group Management — 方法规范与 Tool 工厂
- *
- * 设计理念：
- *   各 IM 平台在适配器内自行实现群管方法（kickMember、muteMember 等），
- *   并自行注册 Tool；平台说明使用包内 `skills/<adapter>/SKILL.md`。
- *
- * 使用方式（在各适配器 start 或注册方法中）：
- *
- *   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));
- *   // 另：包内 skills/<name>/SKILL.md 供 Agent 发现
- */
-
-import type { Tool, ToolPermissionLevel, ToolScope } from '../types.js';
-
-// ============================================================================
-// Adapter 群管理方法规范
-// ============================================================================
-
-/**
- * 群管理能力接口。
- * Adapter 基类通过此接口声明方法签名，子类选择性覆写。
- */
-export interface IGroupManagement {
-  kickMember?(botId: string, sceneId: string, userId: string): Promise<any>;
-  muteMember?(botId: string, sceneId: string, userId: string, duration?: number): Promise<any>;
-  setMemberNickname?(botId: string, sceneId: string, userId: string, nickname: string): Promise<any>;
-  setAdmin?(botId: string, sceneId: string, userId: string, enable?: boolean): Promise<any>;
-  listMembers?(botId: string, sceneId: string): Promise<any>;
-  banMember?(botId: string, sceneId: string, userId: string, reason?: string): Promise<any>;
-  unbanMember?(botId: string, sceneId: string, userId: string): Promise<any>;
-  setGroupName?(botId: string, sceneId: string, name: string): Promise<any>;
-  muteAll?(botId: string, sceneId: string, enable?: boolean): Promise<any>;
-  getGroupInfo?(botId: string, sceneId: string): Promise<any>;
-}
-
-// ============================================================================
-// 方法 → Tool 元数据映射
-// ============================================================================
-
-export interface GroupMethodSpec {
-  method: keyof IGroupManagement;
-  toolSuffix: string;
-  description: string;
-  keywords: string[];
-  permissionLevel: ToolPermissionLevel;
-  extraParams: Record<string, { type: string; description: string; default?: any }>;
-  extraRequired?: string[];
-  preExecutable?: boolean;
-}
-
-export const GROUP_METHOD_SPECS: GroupMethodSpec[] = [
-  {
-    method: 'kickMember',
-    toolSuffix: 'kick_member',
-    description: '将成员踢出群/服务器。适用于严重违规、广告号等需要移除的场景。踢出后该成员将无法再进入群聊（部分平台可重新邀请）。如果只需要用户名而没有 user_id，请先调用 list_members 查询',
-    keywords: ['踢', 'kick', '移除', '踢出'],
-    permissionLevel: 'group_admin',
-    extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
-    },
-    extraRequired: ['user_id'],
-  },
-  {
-    method: 'muteMember',
-    toolSuffix: 'mute_member',
-    description: '禁言或解除禁言群成员。适用于违规发言、刷屏、骚扰他人等需要临时限制发言的场景。duration 单位为秒，传 0 表示解除禁言。默认禁言 10 分钟(600秒)。如果只有昵称而没有 user_id，请先调用 list_members 查询',
-    keywords: ['禁言', 'mute', '静音', '解除禁言', '解禁', '闭嘴'],
-    permissionLevel: 'group_admin',
-    extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
-      duration: { type: 'number', description: '禁言时长(秒)，0=解除禁言，默认600(10分钟)。常用值：60=1分钟, 600=10分钟, 3600=1小时, 86400=1天', default: 600 },
-    },
-    extraRequired: ['user_id'],
-  },
-  {
-    method: 'setMemberNickname',
-    toolSuffix: 'set_nickname',
-    description: '设置群成员的群昵称/名片。仅修改群内显示名称，不影响用户的全局昵称。如果只有昵称而没有 user_id，请先调用 list_members 查询',
-    keywords: ['昵称', '名片', 'nickname', 'card', '改名片'],
-    permissionLevel: 'group_admin',
-    extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
-      nickname: { type: 'string', description: '新的群昵称/名片' },
-    },
-    extraRequired: ['user_id', 'nickname'],
-  },
-  {
-    method: 'setAdmin',
-    toolSuffix: 'set_admin',
-    description: '设置或取消群管理员。注意：此操作需要群主权限，普通管理员无法执行。enable=true 为设置管理员，enable=false 为取消管理员。如果只有昵称而没有 user_id，请先调用 list_members 查询',
-    keywords: ['管理员', 'admin', '设置管理', '取消管理', '提升管理', '撤销管理'],
-    permissionLevel: 'group_owner',
-    extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
-      enable: { type: 'boolean', description: 'true=设置为管理员，false=取消管理员身份', default: true },
-    },
-    extraRequired: ['user_id'],
-  },
-  {
-    method: 'listMembers',
-    toolSuffix: 'list_members',
-    description: '获取群/服务器成员列表。返回所有成员的 ID、昵称、名片、角色等信息。当用户提供昵称/名片而非 ID 时，应先调用此工具查询成员列表，从中匹配到目标用户的 user_id，再执行禁言、踢人等操作',
-    keywords: ['成员', '列表', 'members', 'list', '查找', '搜索用户'],
-    permissionLevel: 'user',
-    extraParams: {},
-    preExecutable: true,
-  },
-  {
-    method: 'banMember',
-    toolSuffix: 'ban_member',
-    description: '永久封禁成员（拉入黑名单）。与踢人(kick)不同，封禁后该成员无法再加入群聊。适用于恶意用户、严重违规等需要永久禁止的场景。如果只有昵称而没有 user_id，请先调用 list_members 查询',
-    keywords: ['封禁', 'ban', '拉黑', '黑名单'],
-    permissionLevel: 'group_admin',
-    extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
-      reason: { type: 'string', description: '封禁原因（将记录在封禁日志中）' },
-    },
-    extraRequired: ['user_id'],
-  },
-  {
-    method: 'unbanMember',
-    toolSuffix: 'unban_member',
-    description: '解除封禁，将成员从黑名单中移除。解除后该成员可以重新加入群聊。如果只有昵称而没有 user_id，请先调用 list_members 查询',
-    keywords: ['解封', 'unban', '解除封禁', '移出黑名单'],
-    permissionLevel: 'group_admin',
-    extraParams: {
-      user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
-    },
-    extraRequired: ['user_id'],
-  },
-  {
-    method: 'setGroupName',
-    toolSuffix: 'set_group_name',
-    description: '修改群/服务器名称。修改后所有成员立即可见新群名',
-    keywords: ['群名', '改名', 'group name', '修改群名'],
-    permissionLevel: 'group_admin',
-    extraParams: {
-      name: { type: 'string', description: '新群名称' },
-    },
-    extraRequired: ['name'],
-  },
-  {
-    method: 'muteAll',
-    toolSuffix: 'mute_all',
-    description: '开启或关闭全员禁言。开启后除管理员外所有成员都无法发言。适用于紧急维护、重要通知、聊天秩序混乱等场景。enable=true 开启，enable=false 解除',
-    keywords: ['全员禁言', 'mute all', '全体禁言', '全体解禁'],
-    permissionLevel: 'group_admin',
-    extraParams: {
-      enable: { type: 'boolean', description: 'true=开启全员禁言，false=解除全员禁言', default: true },
-    },
-  },
-  {
-    method: 'getGroupInfo',
-    toolSuffix: 'get_group_info',
-    description: '获取群/服务器基本信息，包括群名、群主、成员数量、创建时间等。用于了解群聊概况',
-    keywords: ['群信息', 'group info', '群资料', '群详情'],
-    permissionLevel: 'user',
-    extraParams: {},
-    preExecutable: true,
-  },
-];
-
-// ============================================================================
-// Skill 常量（群管相关 SKILL.md 与文档可复用 keywords/tags）
-// ============================================================================
-
-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 → 有序参数列表）
-// ============================================================================
-
-export function buildMethodArgs(
-  method: keyof IGroupManagement,
-  botId: string,
-  sceneId: string,
-  rest: Record<string, any>,
-): any[] {
-  switch (method) {
-    case 'kickMember':      return [botId, sceneId, rest.user_id];
-    case 'muteMember':      return [botId, sceneId, rest.user_id, rest.duration ?? 600];
-    case 'setMemberNickname': return [botId, sceneId, rest.user_id, rest.nickname];
-    case 'setAdmin':        return [botId, sceneId, rest.user_id, rest.enable ?? true];
-    case 'listMembers':     return [botId, sceneId];
-    case 'banMember':       return [botId, sceneId, rest.user_id, rest.reason];
-    case 'unbanMember':     return [botId, sceneId, rest.user_id];
-    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) as any[])];
-  }
-}