@zhin.js/core 1.0.37 → 1.0.38

package/src/adapter.ts

@@ -2,15 +2,29 @@ import { Bot } from "./bot.js";
 import { Plugin } from "./plugin.js";
 import { EventEmitter } from "events";
 import { Message } from "./message.js";
-import { BeforeSendHandler, SendOptions, Tool, ToolContext } from "./types.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实例。
  * 负责根据配置启动/关闭各平台机器人，统一异常处理。
- * 
+ *
  * 适配器可以提供 AI 工具，供 AI 服务调用。
+ *
+ * 群管理能力：
+ *   Adapter 基类声明了 IGroupManagement 中的可选方法规范，
+ *   具体适配器（ICQQ/Discord/Telegram 等）选择性覆写。
+ *   调用 registerGroupManagementSkill() 后，基类自动检测
+ *   哪些方法已被实现，生成对应的 Tool 并注册为 "群聊管理" Skill。
  */
 export abstract class Adapter<R extends Bot = Bot> extends EventEmitter<Adapter.Lifecycle> {
   /** 当前适配器下所有Bot实例，key为bot名称 */
@@ -40,7 +54,7 @@ export abstract class Adapter<R extends Bot = Bot> extends EventEmitter<Adapter.
       this.logger.info(`${message.$bot} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`);
       const rootPlugin = this.plugin?.root || this.plugin;
       // 优先使用 MessageDispatcher（新架构），回退到旧中间件链（兼容）
-      const dispatcher = rootPlugin?.inject('dispatcher' as any) as any;
+      const dispatcher = rootPlugin?.inject('dispatcher') as { dispatch?: (msg: Message) => Promise<void> } | undefined;
       if (dispatcher && typeof dispatcher.dispatch === 'function') {
         void dispatcher.dispatch(message).catch((err: unknown) => {
           this.logger.error('dispatcher.dispatch(message) failed', err);
@@ -87,6 +101,8 @@ 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实例
@@ -145,7 +161,7 @@ export abstract class Adapter<R extends Bot = Bot> extends EventEmitter<Adapter.
 
     // 同步到全局 ToolFeature（如果可用），使适配器工具出现在插件 features 统计中
     let globalDispose: (() => void) | undefined;
-    const toolFeature = this.plugin?.root?.inject('tool' as any) as any;
+    const toolFeature = this.plugin?.root?.inject('tool') as { addTool?: (tool: Tool, name: string, gen: boolean) => () => void } | undefined;
     if (toolFeature && typeof toolFeature.addTool === 'function') {
       const adapterPluginName = this.plugin?.name || `adapter:${this.name}`;
       globalDispose = toolFeature.addTool(toolWithSource, adapterPluginName, false);
@@ -191,7 +207,7 @@ export abstract class Adapter<R extends Bot = Bot> extends EventEmitter<Adapter.
     tags?: string[];
     conventions?: string;
   }): void {
-    const skillFeature = this.plugin?.root?.inject('skill' as any) as SkillFeature | undefined;
+    const skillFeature = this.plugin?.root?.inject('skill') as SkillFeature | undefined;
     if (!skillFeature) {
       this.logger.debug(`declareSkill: SkillFeature 不可用，跳过 Skill 注册`);
       return;
@@ -305,6 +321,70 @@ 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 {

package/src/ai/index.ts

@@ -1,7 +1,7 @@
 /**
- * @zhin.js/core — AI 模块
+ * @zhin.js/core — AI 模块（仅基础类型与 Provider）
  *
- * 原 @zhin.js/ai 包已合并至此，所有 AI 能力内置在 core 中。
+ * Agent 循环、会话、ZhinAgent 等已迁至 @zhin.js/agent。
  */
 
 // ── 类型定义 ──
@@ -21,131 +21,14 @@ export type {
   AgentTool,
   AgentConfig,
   AgentResult,
+  Usage,
+  ToolFilterOptions,
+  SessionConfig,
+  Session,
+  ToolDefinition as ChatToolDefinition,
+  JsonSchema,
 } from './types.js';
 
-// ── AI Service ──
-export { AIService } from './service.js';
-
-// ── Agent ──
-export { Agent, createAgent, formatToolTitle } from './agent.js';
-
-// ── Session ──
-export {
-  SessionManager,
-  createMemorySessionManager,
-  createDatabaseSessionManager,
-  AI_SESSION_MODEL,
-} from './session.js';
-
-// ── Context Manager ──
-export {
-  createContextManager,
-  CHAT_MESSAGE_MODEL,
-  CONTEXT_SUMMARY_MODEL,
-} from './context-manager.js';
-export type {
-  ContextManager,
-  ContextConfig,
-  MessageRecord,
-} from './context-manager.js';
-
-// ── ZhinAgent ──
-export { ZhinAgent } from './zhin-agent/index.js';
-export type { ZhinAgentConfig, OnChunkCallback } from './zhin-agent/index.js';
-
-// ── ZhinAgent sub-modules (for advanced consumers) ──
-export { PERM_MAP, DEFAULT_CONFIG as ZHIN_AGENT_DEFAULT_CONFIG, SECTION_SEP } from './zhin-agent/config.js';
-export { checkExecPolicy, applyExecPolicyToTools, resolveExecAllowlist, EXEC_PRESETS } from './zhin-agent/exec-policy.js';
-export { collectRelevantTools, toAgentTool } from './zhin-agent/tool-collector.js';
-export { buildRichSystemPrompt, buildContextHint, buildEnhancedPersona, buildUserMessageWithHistory, contentToText } from './zhin-agent/prompt.js';
-export type { RichSystemPromptContext } from './zhin-agent/prompt.js';
-export { createChatHistoryTool, createUserProfileTool, createScheduleFollowUpTool, createSpawnTaskTool } from './zhin-agent/builtin-tools.js';
-
-// ── Conversation Memory ──
-export {
-  ConversationMemory,
-  AI_MESSAGE_MODEL,
-  AI_SUMMARY_MODEL,
-} from './conversation-memory.js';
-export type { ConversationMemoryConfig } from './conversation-memory.js';
-
-// ── User Profile ──
-export {
-  UserProfileStore,
-  AI_USER_PROFILE_MODEL,
-} from './user-profile.js';
-
-// ── Rate Limiter ──
-export { RateLimiter } from './rate-limiter.js';
-export type { RateLimitConfig, RateLimitResult } from './rate-limiter.js';
-
-// ── Follow-Up ──
-export { FollowUpManager, AI_FOLLOWUP_MODEL } from './follow-up.js';
-export type { FollowUpRecord, FollowUpSender } from './follow-up.js';
-
-// ── Subagent ──
-export { SubagentManager } from './subagent.js';
-export type {
-  SubagentOrigin,
-  SubagentResultSender,
-  SpawnOptions,
-  SubagentManagerOptions,
-} from './subagent.js';
-
-// ── 持久化定时任务引擎 ──
-export {
-  PersistentCronEngine,
-  readCronJobsFile,
-  writeCronJobsFile,
-  getCronJobsFilePath,
-  generateCronJobId,
-  createCronTools,
-  setCronManager,
-  getCronManager,
-  CRON_JOBS_FILENAME,
-} from './cron-engine.js';
-export type {
-  CronJobRecord,
-  CronRunner,
-  AddCronFn,
-  PersistentCronEngineOptions,
-  CronManager,
-} from './cron-engine.js';
-
-// ── Tone Detector ──
-export { detectTone } from './tone-detector.js';
-export type { Tone } from './tone-detector.js';
-
-// ── 多模态输出 ──
-export {
-  parseOutput,
-  renderToPlainText,
-  renderToSatori,
-} from './output.js';
-export type {
-  OutputElement,
-  TextElement,
-  ImageElement,
-  AudioElement,
-  VideoElement,
-  CardElement,
-  FileElement,
-  CardField,
-  CardButton,
-} from './output.js';
-
-// ── 内置工具 ──
-export {
-  calculatorTool,
-  timeTool,
-  searchTool,
-  codeRunnerTool,
-  httpTool,
-  memoryTool,
-  getBuiltinTools,
-  getAllBuiltinTools,
-} from './tools.js';
-
 // ── Providers ──
 export {
   BaseProvider,
@@ -161,64 +44,3 @@ export type {
   AnthropicConfig,
   OllamaConfig,
 } from './providers/index.js';
-
-// ── 初始化 ──
-export { initAIModule } from './init.js';
-
-// ── Hook 系统 (借鉴 OpenClaw) ──
-export {
-  registerAIHook,
-  unregisterAIHook,
-  triggerAIHook,
-  createAIHookEvent,
-  clearAIHooks,
-  getRegisteredAIHookKeys,
-} from './hooks.js';
-export type {
-  AIHookEvent,
-  AIHookEventType,
-  AIHookHandler,
-  MessageReceivedEvent,
-  MessageSentEvent,
-  SessionCompactEvent,
-  SessionNewEvent,
-  AgentBootstrapEvent,
-  ToolCallEvent,
-} from './hooks.js';
-
-// ── 会话压缩 (借鉴 OpenClaw) ──
-export {
-  estimateTokens,
-  estimateMessagesTokens,
-  splitMessagesByTokenShare,
-  chunkMessagesByMaxTokens,
-  computeAdaptiveChunkRatio,
-  resolveContextWindowTokens,
-  evaluateContextWindowGuard,
-  summarizeWithFallback,
-  summarizeInStages,
-  pruneHistoryForContext,
-  compactSession,
-  DEFAULT_CONTEXT_TOKENS,
-} from './compaction.js';
-export type {
-  ContextWindowSource,
-  ContextWindowInfo,
-  ContextWindowGuardResult,
-  PruneResult,
-} from './compaction.js';
-
-// ── 引导文件管理 (借鉴 OpenClaw) ──
-export {
-  loadBootstrapFiles,
-  buildContextFiles,
-  buildBootstrapContextSection,
-  loadSoulPersona,
-  loadToolsGuide,
-  loadAgentsMemory,
-  clearBootstrapCache,
-} from './bootstrap.js';
-export type {
-  BootstrapFile,
-  ContextFile,
-} from './bootstrap.js';

package/src/ai/types.ts

@@ -51,10 +51,11 @@ export interface JsonSchema {
   properties?: Record<string, JsonSchema>;
   required?: string[];
   items?: JsonSchema;
-  enum?: any[];
+  enum?: unknown[];
   description?: string;
-  default?: any;
-  [key: string]: any;
+  default?: unknown;
+  /** JSON Schema allows arbitrary extension properties */
+  [key: string]: any; // eslint-disable-line @typescript-eslint/no-explicit-any -- JSON Schema spec requires open index
 }
 
 // ============================================================================
@@ -183,7 +184,7 @@ export interface AgentTool {
   name: string;
   description: string;
   parameters: JsonSchema;
-  execute: (args: Record<string, any>) => Promise<any>;
+  execute: (args: Record<string, any>) => Promise<unknown>;
   /** 工具标签，用于分类和快速匹配 */
   tags?: string[];
   /** 触发关键词，用户消息包含这些词时优先选择此工具 */

package/src/built/ai-trigger.ts

@@ -171,12 +171,12 @@ export function inferSenderPermissions<T extends object>(
   
   const isGroupOwner = senderPermissions.includes('owner') || 
                        senderPermissions.includes('group_owner') ||
-                       (message as any).$sender?.role === 'owner';
+                       message.$sender?.role === 'owner';
   
   const isGroupAdmin = isGroupOwner || 
                        senderPermissions.includes('admin') || 
                        senderPermissions.includes('group_admin') ||
-                       (message as any).$sender?.role === 'admin';
+                       message.$sender?.role === 'admin';
   
   let permissionLevel: ToolPermissionLevel = 'user';
   if (isOwner) permissionLevel = 'owner';

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

@@ -0,0 +1,207 @@
+/**
+ * Group Management Skill — 方法规范与元数据
+ *
+ * 设计理念：
+ *   群管理是 IM 系统的一种"技能"(Skill)，而非一组零散的工具。
+ *   Adapter 基类声明群管理操作的方法规范（可选），
+ *   具体适配器（ICQQ/Discord/Telegram 等）选择性覆写。
+ *   Adapter.start() 自动检测哪些方法已被子类实现，
+ *   生成对应的 Tool 并注册为 "群聊管理" Skill。
+ *
+ * 子类无需任何额外调用：
+ *
+ *   class IcqqAdapter extends Adapter<IcqqBot> {
+ *     async kickMember(botId, sceneId, userId) { ... }
+ *     async muteMember(botId, sceneId, userId, duration) { ... }
+ *     // start() 中自动检测 → 自动注册 Skill，零样板代码
+ *   }
+ */
+
+import type { ToolPermissionLevel } 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: '将成员踢出群/服务器',
+    keywords: ['踢', 'kick', '移除', '踢出'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+    },
+    extraRequired: ['user_id'],
+  },
+  {
+    method: 'muteMember',
+    toolSuffix: 'mute_member',
+    description: '禁言群成员（duration=0 解除）',
+    keywords: ['禁言', 'mute', '静音', '解除禁言'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+      duration: { type: 'number', description: '禁言时长(秒)，0=解除', default: 600 },
+    },
+    extraRequired: ['user_id'],
+  },
+  {
+    method: 'setMemberNickname',
+    toolSuffix: 'set_nickname',
+    description: '设置群成员昵称/名片',
+    keywords: ['昵称', '名片', 'nickname', 'card'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+      nickname: { type: 'string', description: '新昵称' },
+    },
+    extraRequired: ['user_id', 'nickname'],
+  },
+  {
+    method: 'setAdmin',
+    toolSuffix: 'set_admin',
+    description: '设置/取消群管理员',
+    keywords: ['管理员', 'admin', '设置管理'],
+    permissionLevel: 'group_owner',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+      enable: { type: 'boolean', description: '设置(true)/取消(false)', default: true },
+    },
+    extraRequired: ['user_id'],
+  },
+  {
+    method: 'listMembers',
+    toolSuffix: 'list_members',
+    description: '获取群/服务器成员列表',
+    keywords: ['成员', '列表', 'members', 'list'],
+    permissionLevel: 'user',
+    extraParams: {},
+    preExecutable: true,
+  },
+  {
+    method: 'banMember',
+    toolSuffix: 'ban_member',
+    description: '封禁成员',
+    keywords: ['封禁', 'ban', '拉黑'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+      reason: { type: 'string', description: '封禁原因' },
+    },
+    extraRequired: ['user_id'],
+  },
+  {
+    method: 'unbanMember',
+    toolSuffix: 'unban_member',
+    description: '解除封禁',
+    keywords: ['解封', 'unban', '解除封禁'],
+    permissionLevel: 'group_admin',
+    extraParams: {
+      user_id: { type: 'string', description: '目标用户 ID' },
+    },
+    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: '全员禁言/解除全员禁言',
+    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 常量
+// ============================================================================
+
+export const GROUP_MANAGEMENT_SKILL_DESCRIPTION =
+  '群聊管理能力：在 IM 系统中对群/服务器进行管理，包括踢人、禁言、封禁、' +
+  '设置管理员、修改群名、查看成员列表等操作。具体可用的操作取决于平台和 Bot 权限。';
+
+export const GROUP_MANAGEMENT_SKILL_TAGS = ['group', 'management', 'im', 'admin'];
+export const GROUP_MANAGEMENT_SKILL_KEYWORDS = [
+  '群管理', '踢人', '禁言', '封禁', '管理员', '群名',
+  '成员', 'kick', 'mute', 'ban', 'admin', 'members',
+];
+
+// ============================================================================
+// 参数映射（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)];
+  }
+}