@zhin.js/core 1.0.26 → 1.0.28

package/src/ai/hooks.ts

@@ -0,0 +1,223 @@
+/**
+ * AI Hooks — AI 生命周期事件钩子系统
+ *
+ * 借鉴 OpenClaw 的 Hooks 设计，提供可扩展的事件驱动钩子：
+ *
+ *   - message:received   — 收到消息时触发
+ *   - message:sent       — 发送消息时触发
+ *   - session:compact    — 会话压缩时触发
+ *   - session:new        — 新建会话时触发
+ *   - agent:bootstrap    — Agent 初始化时触发
+ *   - agent:tool-call    — 工具调用时触发
+ *
+ * 钩子按注册顺序执行，错误不会中断其他钩子。
+ */
+
+import { Logger } from '@zhin.js/logger';
+
+const logger = new Logger(null, 'AI-Hooks');
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+/** 事件类型 */
+export type AIHookEventType =
+  | 'message'
+  | 'session'
+  | 'agent'
+  | 'tool';
+
+/** Hook 事件基础接口 */
+export interface AIHookEvent {
+  /** 事件类型 */
+  type: AIHookEventType;
+  /** 具体动作 */
+  action: string;
+  /** 会话标识 */
+  sessionId?: string;
+  /** 附加上下文 */
+  context: Record<string, unknown>;
+  /** 事件时间戳 */
+  timestamp: Date;
+  /** 钩子可以推送消息到这个数组 */
+  messages: string[];
+}
+
+/** 消息接收事件 */
+export interface MessageReceivedEvent extends AIHookEvent {
+  type: 'message';
+  action: 'received';
+  context: {
+    from: string;
+    content: string;
+    platform: string;
+    channelId?: string;
+    messageId?: string;
+  };
+}
+
+/** 消息发送事件 */
+export interface MessageSentEvent extends AIHookEvent {
+  type: 'message';
+  action: 'sent';
+  context: {
+    to: string;
+    content: string;
+    success: boolean;
+    error?: string;
+    platform: string;
+  };
+}
+
+/** 会话压缩事件 */
+export interface SessionCompactEvent extends AIHookEvent {
+  type: 'session';
+  action: 'compact';
+  context: {
+    compactedCount: number;
+    savedTokens: number;
+    summary: string;
+  };
+}
+
+/** 会话新建事件 */
+export interface SessionNewEvent extends AIHookEvent {
+  type: 'session';
+  action: 'new';
+  context: {
+    previousSessionId?: string;
+  };
+}
+
+/** Agent 初始化事件 */
+export interface AgentBootstrapEvent extends AIHookEvent {
+  type: 'agent';
+  action: 'bootstrap';
+  context: {
+    workspaceDir: string;
+    toolCount: number;
+    skillCount: number;
+    bootstrapFiles: string[];
+  };
+}
+
+/** 工具调用事件 */
+export interface ToolCallEvent extends AIHookEvent {
+  type: 'tool';
+  action: 'call';
+  context: {
+    toolName: string;
+    args: Record<string, unknown>;
+    result?: string;
+    durationMs?: number;
+    success: boolean;
+    error?: string;
+  };
+}
+
+/** Hook 处理函数 */
+export type AIHookHandler = (event: AIHookEvent) => Promise<void> | void;
+
+// ============================================================================
+// Hook 管理器
+// ============================================================================
+
+/** 按事件 key 存储的处理函数注册表 */
+const handlers = new Map<string, AIHookHandler[]>();
+
+/**
+ * 注册 Hook 处理函数
+ *
+ * @param eventKey - 事件类型（如 'message'）或具体动作（如 'message:received'）
+ * @param handler - 处理函数
+ *
+ * @example
+ * ```ts
+ * // 监听所有消息事件
+ * registerAIHook('message', async (event) => {
+ *   console.log('消息事件:', event.action);
+ * });
+ *
+ * // 只监听消息接收
+ * registerAIHook('message:received', async (event) => {
+ *   console.log('收到消息:', event.context.content);
+ * });
+ * ```
+ */
+export function registerAIHook(eventKey: string, handler: AIHookHandler): () => void {
+  if (!handlers.has(eventKey)) {
+    handlers.set(eventKey, []);
+  }
+  handlers.get(eventKey)!.push(handler);
+
+  // 返回注销函数
+  return () => unregisterAIHook(eventKey, handler);
+}
+
+/**
+ * 注销 Hook 处理函数
+ */
+export function unregisterAIHook(eventKey: string, handler: AIHookHandler): void {
+  const eventHandlers = handlers.get(eventKey);
+  if (!eventHandlers) return;
+
+  const index = eventHandlers.indexOf(handler);
+  if (index !== -1) eventHandlers.splice(index, 1);
+  if (eventHandlers.length === 0) handlers.delete(eventKey);
+}
+
+/**
+ * 清除所有 Hook（测试用）
+ */
+export function clearAIHooks(): void {
+  handlers.clear();
+}
+
+/**
+ * 获取已注册的事件 key 列表（调试用）
+ */
+export function getRegisteredAIHookKeys(): string[] {
+  return Array.from(handlers.keys());
+}
+
+/**
+ * 触发 Hook 事件
+ *
+ * 同时调用通用类型（如 'message'）和具体动作（如 'message:received'）的处理函数。
+ * 处理函数按注册顺序执行，错误被捕获并记录，不影响其他处理函数。
+ */
+export async function triggerAIHook(event: AIHookEvent): Promise<void> {
+  const typeHandlers = handlers.get(event.type) ?? [];
+  const specificHandlers = handlers.get(`${event.type}:${event.action}`) ?? [];
+  const allHandlers = [...typeHandlers, ...specificHandlers];
+
+  if (allHandlers.length === 0) return;
+
+  for (const handler of allHandlers) {
+    try {
+      await handler(event);
+    } catch (err: any) {
+      logger.error(`Hook 错误 [${event.type}:${event.action}]: ${err.message}`);
+    }
+  }
+}
+
+/**
+ * 创建 Hook 事件（辅助函数）
+ */
+export function createAIHookEvent(
+  type: AIHookEventType,
+  action: string,
+  sessionId?: string,
+  context: Record<string, unknown> = {},
+): AIHookEvent {
+  return {
+    type,
+    action,
+    sessionId,
+    context,
+    timestamp: new Date(),
+    messages: [],
+  };
+}

package/src/ai/index.ts

@@ -126,3 +126,61 @@ export type {
 
 // ── 初始化 ──
 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/init.ts

@@ -26,6 +26,9 @@ import type { MessageDispatcherService } from '../built/dispatcher.js';
 import type { SkillFeature } from '../built/skill.js';
 import { AIService } from './service.js';
 import { ZhinAgent } from './zhin-agent.js';
+import { createBuiltinTools, discoverWorkspaceSkills, loadSoulPersona } from './builtin-tools.js';
+import { loadBootstrapFiles, buildContextFiles, buildBootstrapContextSection, loadToolsGuide } from './bootstrap.js';
+import { triggerAIHook, createAIHookEvent } from './hooks.js';
 import { SessionManager, createDatabaseSessionManager } from './session.js';
 import { AI_SESSION_MODEL } from './session.js';
 import {
@@ -131,7 +134,7 @@ export function initAIModule(): void {
     async mounted(p: Plugin) {
       const configService = root.inject('config');
       const appConfig =
-        configService?.get<{ ai?: AIConfig }>('zhin.config.yml') || {};
+        configService?.getPrimary<{ ai?: AIConfig }>() || {};
       const config = appConfig.ai || {};
 
       if (config.enabled === false) {
@@ -146,7 +149,7 @@ export function initAIModule(): void {
       const providers = service.listProviders();
       if (providers.length === 0) {
         logger.warn(
-          'No AI providers configured. Please add API keys in zhin.config.yml',
+          'No AI providers configured. Please add API keys in zhin.config (yml/json/toml)',
         );
       } else {
         logger.info(
@@ -358,7 +361,7 @@ export function initAIModule(): void {
       if (!aiServiceInstance) return;
       const configService = root.inject('config');
       const appConfig =
-        configService?.get<{ ai?: AIConfig }>('zhin.config.yml') || {};
+        configService?.getPrimary<{ ai?: AIConfig }>() || {};
       const config = appConfig.ai || {};
 
       if (config.sessions?.useDatabase === false) return;
@@ -499,4 +502,125 @@ export function initAIModule(): void {
     logger.debug(`Registered ${tools.length} AI management tools`);
     return () => disposers.forEach(d => d());
   });
+
+  // ── 内置系统工具（文件/Shell/网络/计划/记忆/技能） ──
+  useContext('ai', 'tool', (ai, toolService) => {
+    if (!ai || !toolService) return;
+
+    // 注册工具
+    const builtinTools = createBuiltinTools();
+    const disposers: (() => void)[] = [];
+    for (const tool of builtinTools) disposers.push(toolService.addTool(tool, root.name));
+    logger.info(`Registered ${builtinTools.length} built-in system tools`);
+
+    // 异步发现工作区技能 + 加载引导文件（不阻塞注册流程）
+    (async () => {
+      // ── 第一步：发现和注册工作区技能 ──
+      try {
+        const skills = await discoverWorkspaceSkills();
+        const skillFeature = root.inject?.('skill') as SkillFeature | undefined;
+        if (skillFeature && skills.length > 0) {
+          logger.debug(`[技能注册] 开始注册 ${skills.length} 个技能...`);
+          // 构建所有已注册工具名的索引（用于模糊匹配）
+          const allRegisteredTools = toolService.getAll();
+          const toolNameIndex = new Map<string, Tool>();
+          for (const t of allRegisteredTools) {
+            toolNameIndex.set(t.name, t);
+            // 建立反向别名索引：read_file ↔ file_read 等
+            const parts = t.name.split('_');
+            if (parts.length === 2) {
+              toolNameIndex.set(`${parts[1]}_${parts[0]}`, t);
+            }
+          }
+
+          for (const s of skills) {
+            // 从 toolService 中查找技能声明的关联工具（支持模糊匹配）
+            const associatedTools: Tool[] = [];
+            const toolNames = s.toolNames || [];
+            if (toolNames.length > 0 && toolService) {
+              logger.debug(`[技能注册] 技能 '${s.name}' 声明的工具: ${toolNames.join(', ')}`);
+              for (const toolName of toolNames) {
+                // 精确匹配
+                let tool = toolService.get(toolName);
+                // 若精确匹配失败，尝试反向别名（file_read → read_file）
+                if (!tool) {
+                  tool = toolNameIndex.get(toolName) || undefined;
+                }
+                if (tool) {
+                  associatedTools.push(tool);
+                  const matchType = toolService.get(toolName) ? '精确' : '模糊';
+                  logger.debug(`[技能注册]   ✅ 找到工具: ${toolName}${matchType === '模糊' ? ` → ${tool.name} (模糊匹配)` : ''}`);
+                } else {
+                  logger.warn(`[技能注册]   ❌ 工具 '${toolName}' 未找到（已注册: ${allRegisteredTools.map(t => t.name).join(', ')}）`);
+                }
+              }
+            }
+            skillFeature.add({
+              name: s.name,
+              description: s.description,
+              tools: associatedTools,
+              keywords: s.keywords || [],
+              tags: s.tags || [],
+              pluginName: root.name,
+            }, root.name);
+            logger.debug(`[技能注册] 技能 '${s.name}' 已注册 (${associatedTools.length} 个工具)`);
+          }
+          logger.info(`✅ Registered ${skills.length} workspace skills with ${skills.reduce((sum, s) => sum + ((s.toolNames || []).length), 0)} total tool references`);
+        }
+      } catch (e: any) {
+        logger.warn(`Failed to discover workspace skills: ${e.message}`);
+      }
+
+      // ── 第二步：加载引导文件 ──
+      const loadedFiles: string[] = [];
+      try {
+        // 使用项目根目录或当前工作目录作为工作区目录
+        const workspaceDir = process.cwd();
+        const bootstrapFiles = await loadBootstrapFiles(workspaceDir);
+        const contextFiles = buildContextFiles(bootstrapFiles);
+        
+        logger.debug(`Bootstrap files loaded (cwd: ${workspaceDir}): ${bootstrapFiles.map(f => f.name + (f.missing ? ' (missing)' : '')).join(', ')}`);
+
+        // SOUL.md → 注入到 agent persona
+        const soulFile = contextFiles.find(f => f.path === 'SOUL.md');
+        if (soulFile && zhinAgentInstance) {
+          logger.info('Loaded SOUL.md persona → agent prompt');
+          loadedFiles.push('SOUL.md');
+        }
+
+        // TOOLS.md → 记录已加载
+        const toolsFile = contextFiles.find(f => f.path === 'TOOLS.md');
+        if (toolsFile) {
+          logger.info('Loaded TOOLS.md tool guidance → agent prompt');
+          loadedFiles.push('TOOLS.md');
+        }
+
+        // AGENTS.md → 记录已加载
+        const agentsFile = contextFiles.find(f => f.path === 'AGENTS.md');
+        if (agentsFile) {
+          logger.info('Loaded AGENTS.md memory → agent prompt');
+          loadedFiles.push('AGENTS.md');
+        }
+
+        // 注入引导上下文到 ZhinAgent
+        if (zhinAgentInstance && contextFiles.length > 0) {
+          const contextSection = buildBootstrapContextSection(contextFiles);
+          zhinAgentInstance.setBootstrapContext(contextSection);
+        }
+      } catch (e: any) {
+        logger.debug(`Bootstrap files not loaded: ${e.message}`);
+      }
+
+      // 触发 agent:bootstrap Hook
+      const skillFeature2 = (root as any).inject?.('skill') as SkillFeature | undefined;
+      await triggerAIHook(createAIHookEvent('agent', 'bootstrap', undefined, {
+        workspaceDir: process.cwd(),
+        toolCount: builtinTools.length,
+        skillCount: skillFeature2?.size ?? 0,
+        bootstrapFiles: loadedFiles,
+      }));
+    })();
+
+    return () => disposers.forEach(d => d());
+  });
 }

package/src/ai/types.ts

@@ -172,6 +172,8 @@ export interface AgentTool {
   keywords?: string[];
   /** 所需权限级别 (0=所有人, 1=群管理, 2=群主, 3=Bot管理员, 4=拥有者) */
   permissionLevel?: number;
+  /** 是否允许预执行（opt-in），默认 false */
+  preExecutable?: boolean;
 }
 
 /**