@zhin.js/core 1.0.30 → 1.0.32

package/src/ai/init.ts

@@ -10,6 +10,9 @@
  *   - AI 管理工具
  */
 
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
 import { Logger } from '@zhin.js/logger';
 import { getPlugin, type Plugin } from '../plugin.js';
 import { Message } from '../message.js';
@@ -40,6 +43,7 @@ import {
 import { AI_MESSAGE_MODEL, AI_SUMMARY_MODEL } from './conversation-memory.js';
 import { AI_USER_PROFILE_MODEL } from './user-profile.js';
 import { AI_FOLLOWUP_MODEL } from './follow-up.js';
+import { PersistentCronEngine, setCronManager, createCronTools } from './cron-engine.js';
 import { renderToPlainText, type OutputElement } from './output.js';
 import type { AIConfig, ContentPart } from './types.js';
 
@@ -169,19 +173,18 @@ export function initAIModule(): void {
   });
 
   // ── ZhinAgent 全局大脑 ──
-  useContext('ai' as any, (ai: AIService) => {
+  useContext('ai', (ai) => {
     if (!ai.isReady()) {
       logger.warn('AI Service not ready, ZhinAgent not created');
       return;
     }
 
     const provider = ai.getProvider();
-    const agent = new ZhinAgent(provider);
+    const agentConfig = ai.getAgentConfig();
+    const agent = new ZhinAgent(provider, agentConfig);
     zhinAgentInstance = agent;
 
-    const skillRegistry = root.inject('skill' as any) as
-      | SkillFeature
-      | undefined;
+    const skillRegistry = root.inject('skill');
     if (skillRegistry) agent.setSkillRegistry(skillRegistry);
 
     // 注入跟进提醒的发送回调（不依赖数据库，内存模式也能发）
@@ -201,8 +204,32 @@ export function initAIModule(): void {
       });
     });
 
+    // 持久化定时任务引擎：加载 data/cron-jobs.json，到点用 prompt 调用 Agent；并暴露给 AI 管理（list/add/remove/pause/resume）
+    let cronEngine: PersistentCronEngine | null = null;
+    const cronFeature = root.inject('cron' as any);
+    if (cronFeature && typeof cronFeature.add === 'function') {
+      const dataDir = path.join(process.cwd(), 'data');
+      const addCron = (c: any) => cronFeature.add(c, 'cron-engine');
+      const runner = async (prompt: string) => {
+        if (!zhinAgentInstance) return;
+        await zhinAgentInstance.process(prompt, {
+          platform: 'cron',
+          senderId: 'system',
+          sceneId: 'cron',
+        });
+      };
+      cronEngine = new PersistentCronEngine({ dataDir, addCron, runner });
+      cronEngine.load();
+      setCronManager({ cronFeature, engine: cronEngine });
+    }
+
     logger.debug('ZhinAgent created');
     return () => {
+      setCronManager(null);
+      if (cronEngine) {
+        cronEngine.unload();
+        cronEngine = null;
+      }
       agent.dispose();
       zhinAgentInstance = null;
     };
@@ -511,61 +538,55 @@ export function initAIModule(): void {
     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`);
+    const cronTools = createCronTools();
+    for (const tool of cronTools) disposers.push(toolService.addTool(tool, root.name));
+    logger.info(`Registered ${builtinTools.length} built-in + ${cronTools.length} cron tools`);
+
+    let skillWatchers: fs.FSWatcher[] = [];
+    let skillReloadDebounce: ReturnType<typeof setTimeout> | null = null;
+
+    async function syncWorkspaceSkills(): Promise<number> {
+      const skillFeature = root.inject?.('skill') as SkillFeature | undefined;
+      if (!skillFeature) return 0;
+      // 先移除当前插件注册的所有工作区技能（增量更新）
+      const existing = skillFeature.getByPlugin(root.name);
+      for (const s of existing) skillFeature.remove(s);
+      const skills = await discoverWorkspaceSkills();
+      if (skills.length === 0) return 0;
+      const allRegisteredTools = toolService.getAll();
+      const toolNameIndex = new Map<string, Tool>();
+      for (const t of allRegisteredTools) {
+        toolNameIndex.set(t.name, t);
+        const parts = t.name.split('_');
+        if (parts.length === 2) toolNameIndex.set(`${parts[1]}_${parts[0]}`, t);
+      }
+      for (const s of skills) {
+        const associatedTools: Tool[] = [];
+        const toolNames = s.toolNames || [];
+        for (const toolName of toolNames) {
+          let tool = toolService.get(toolName) || toolNameIndex.get(toolName);
+          if (tool) associatedTools.push(tool);
+        }
+        skillFeature.add({
+          name: s.name,
+          description: s.description,
+          tools: associatedTools,
+          keywords: s.keywords || [],
+          tags: s.tags || [],
+          pluginName: root.name,
+        }, root.name);
+      }
+      return skills.length;
+    }
 
     // 异步发现工作区技能 + 加载引导文件（不阻塞注册流程）
     (async () => {
       // ── 第一步：发现和注册工作区技能 ──
       try {
-        const skills = await discoverWorkspaceSkills();
+        const count = await syncWorkspaceSkills();
         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`);
+        if (count > 0 && skillFeature) {
+          logger.info(`✅ Registered ${count} workspace skills`);
         }
       } catch (e: any) {
         logger.warn(`Failed to discover workspace skills: ${e.message}`);
@@ -619,8 +640,41 @@ export function initAIModule(): void {
         skillCount: skillFeature2?.size ?? 0,
         bootstrapFiles: loadedFiles,
       }));
+
+      // ── 技能目录热重载：监听 workspace + local 技能目录，防抖后重新发现并更新 ──
+      const workspaceSkillDir = path.join(process.cwd(), 'skills');
+      const localSkillDir = path.join(os.homedir(), '.zhin', 'skills');
+      const onSkillDirChange = () => {
+        if (skillReloadDebounce) clearTimeout(skillReloadDebounce);
+        skillReloadDebounce = setTimeout(async () => {
+          skillReloadDebounce = null;
+          try {
+            const count = await syncWorkspaceSkills();
+            await triggerAIHook(createAIHookEvent('agent', 'skills-reloaded', undefined, { skillCount: count }));
+            if (count >= 0) logger.info(`[技能热重载] 已更新，当前工作区技能数: ${count}`);
+          } catch (e: any) {
+            logger.warn(`[技能热重载] 失败: ${e.message}`);
+          }
+        }, 400);
+      };
+      for (const dir of [workspaceSkillDir, localSkillDir]) {
+        if (fs.existsSync(dir)) {
+          try {
+            const w = fs.watch(dir, { recursive: true }, onSkillDirChange);
+            skillWatchers.push(w);
+            logger.debug(`[技能热重载] 监听目录: ${dir}`);
+          } catch (e: any) {
+            logger.debug(`[技能热重载] 无法监听 ${dir}: ${e.message}`);
+          }
+        }
+      }
     })();
 
-    return () => disposers.forEach(d => d());
+    return () => {
+      disposers.forEach(d => d());
+      skillWatchers.forEach(w => w.close());
+      skillWatchers = [];
+      if (skillReloadDebounce) clearTimeout(skillReloadDebounce);
+    };
   });
 }

package/src/ai/service.ts

@@ -44,6 +44,7 @@ export class AIService {
   private sessionConfig: { maxHistory?: number; expireMs?: number };
   private contextConfig: ContextConfig;
   private triggerConfig: AITriggerConfig;
+  private agentConfig: AIConfig['agent'];
   private plugin?: Plugin;
   private customTools: Map<string, AgentTool> = new Map();
 
@@ -52,6 +53,7 @@ export class AIService {
     this.sessionConfig = config.sessions || {};
     this.contextConfig = config.context || {};
     this.triggerConfig = config.trigger || {};
+    this.agentConfig = config.agent;
     this.sessions = createMemorySessionManager(this.sessionConfig);
     this.builtinTools = getBuiltinTools().map(tool => this.convertToolToAgentTool(tool.toTool()));
 
@@ -253,6 +255,8 @@ ${preExecutedData ? `\n已自动获取的数据：${preExecutedData}\n` : ''}
   getContextConfig(): ContextConfig { return this.contextConfig; }
   getSessionConfig() { return this.sessionConfig; }
   getTriggerConfig(): AITriggerConfig { return this.triggerConfig; }
+  /** Agent 配置（如 disabledTools / allowedTools），供 ZhinAgent 使用 */
+  getAgentConfig(): AIConfig['agent'] { return this.agentConfig; }
 
   registerProvider(provider: AIProvider): void { this.providers.set(provider.name, provider); }
   getProvider(name?: string): AIProvider {

package/src/ai/types.ts

@@ -174,6 +174,8 @@ export interface AgentTool {
   permissionLevel?: number;
   /** 是否允许预执行（opt-in），默认 false */
   preExecutable?: boolean;
+  /** 工具分类（如 file / shell / web），用于 formatToolTitle 等展示 */
+  kind?: string;
 }
 
 /**
@@ -274,6 +276,19 @@ export interface AIConfig {
     /** 自定义总结提示词 */
     summaryPrompt?: string;
   };
+  /** Agent 工具开关与执行安全 */
+  agent?: {
+    /** 禁用的工具名列表，这些工具不会下发给 AI */
+    disabledTools?: string[];
+    /** 仅允许的工具名列表；若设置则只下发列表中的工具（与 disabledTools 二选一，allowedTools 优先） */
+    allowedTools?: string[];
+    /** bash 执行策略：deny=禁止执行，allowlist=仅允许列表内命令，full=不限制 */
+    execSecurity?: 'deny' | 'allowlist' | 'full';
+    /** allowlist 模式下允许的命令（支持正则字符串，如 "^ls "、"^cat "） */
+    execAllowlist?: string[];
+    /** allowlist 未命中时：true=需审批（当前实现为拒绝并提示），false=直接拒绝 */
+    execAsk?: boolean;
+  };
   /** AI 触发配置 */
   trigger?: {
     /** 是否启用（默认 true） */

package/src/ai/zhin-agent.ts

@@ -52,6 +52,25 @@ const logger = new Logger(null, 'ZhinAgent');
 /** 高精度计时 */
 const now = () => performance.now();
 
+const HISTORY_CONTEXT_MARKER = '[Chat messages since your last reply - for context]';
+const CURRENT_MESSAGE_MARKER = '[Current message - respond to this]';
+
+function contentToText(c: string | ContentPart[]): string {
+  if (typeof c === 'string') return c;
+  return (c as ContentPart[]).map(p => (p.type === 'text' ? p.text : '')).join('');
+}
+
+
+function buildUserMessageWithHistory(history: ChatMessage[], currentContent: string): string {
+  if (history.length === 0) return currentContent;
+  const roleLabel = (role: string) => (role === 'user' ? '用户' : role === 'assistant' ? '助手' : '系统');
+  const lines = history
+    .filter(m => m.role === 'user' || m.role === 'assistant' || m.role === 'system')
+    .map(m => `${roleLabel(m.role)}: ${contentToText(m.content)}`);
+  const historyBlock = lines.join('\n');
+  return `${HISTORY_CONTEXT_MARKER}\n${historyBlock}\n\n${CURRENT_MESSAGE_MARKER}\n${currentContent}`;
+}
+
 // ============================================================================
 // 配置
 // ============================================================================
@@ -85,6 +104,16 @@ export interface ZhinAgentConfig {
   contextTokens?: number;
   /** 历史记录最大占比（默认 0.5 = 50%） */
   maxHistoryShare?: number;
+  /** 禁用的工具名列表（来自配置，这些工具不会下发给 AI） */
+  disabledTools?: string[];
+  /** 仅允许的工具名列表；若设置则只下发列表中的工具（与 disabledTools 二选一，allowedTools 优先） */
+  allowedTools?: string[];
+  /** bash 执行策略：deny=禁止，allowlist=仅允许列表内，full=不限制 */
+  execSecurity?: 'deny' | 'allowlist' | 'full';
+  /** allowlist 模式下允许的命令（正则字符串） */
+  execAllowlist?: string[];
+  /** allowlist 未命中时 true=需审批（当前为拒绝并提示），false=直接拒绝 */
+  execAsk?: boolean;
 }
 
 const DEFAULT_CONFIG: Required<ZhinAgentConfig> = {
@@ -102,6 +131,11 @@ const DEFAULT_CONFIG: Required<ZhinAgentConfig> = {
   visionModel: '',
   contextTokens: DEFAULT_CONTEXT_TOKENS,
   maxHistoryShare: 0.5,
+  disabledTools: [],
+  allowedTools: [],  // 空数组表示不限制；非空时仅允许列表中的工具
+  execSecurity: 'deny',  // 默认禁止 bash，避免误用
+  execAllowlist: [],
+  execAsk: false,
 };
 
 // ============================================================================
@@ -392,15 +426,15 @@ ${preData ? `\n已获取数据：${preData}\n` : ''}`;
 
       // 始终传递所有工具给 Agent，因为 activate_skill 激活后可能需要调用
       // 之前被分类为 noParamTools 的工具（确保技能中引用的所有工具都可用）
-      const agentTools = allTools;
+      const agentTools = this.applyExecPolicyToTools(allTools);
       const agent = createAgent(this.provider, {
         systemPrompt,
         tools: agentTools,
         maxIterations: this.config.maxIterations,
       });
 
-      // Agent 路径也注入历史上下文
-      const result = await agent.run(content, historyMessages);
+      const userMessageWithHistory = buildUserMessageWithHistory(historyMessages, content);
+      const result = await agent.run(userMessageWithHistory, []);
       reply = result.content || this.fallbackFormat(result.toolCalls);
       logger.info(`[Agent 路径] 过滤=${filterMs}ms, 记忆=${memMs}ms, Agent=${(now() - tAgent).toFixed(0)}ms, 总=${(now() - t0).toFixed(0)}ms`);
     }
@@ -619,17 +653,83 @@ ${preData ? `\n已获取数据：${preData}\n` : ''}`;
       }
     }
 
+    // 5. 配置级工具开关：disabledTools / allowedTools（权限与安全）
+    let final = filtered;
+    const allowed = this.config.allowedTools;
+    const disabled = this.config.disabledTools ?? [];
+    if (allowed && allowed.length > 0) {
+      const allowSet = new Set(allowed.map(n => n.toLowerCase()));
+      final = final.filter(t => allowSet.has(t.name.toLowerCase()));
+      if (final.length < filtered.length) {
+        logger.debug(`[工具开关] allowedTools 限制: ${filtered.length} -> ${final.length}`);
+      }
+    } else if (disabled.length > 0) {
+      const disabledSet = new Set(disabled.map(n => n.toLowerCase()));
+      final = final.filter(t => !disabledSet.has(t.name.toLowerCase()));
+      if (final.length < filtered.length) {
+        logger.debug(`[工具开关] disabledTools 过滤: ${filtered.length} -> ${final.length}`);
+      }
+    }
+
     // 诊断日志：显示收集的工具总数、过滤后的数量、以及列表
-    if (filtered.length > 0) {
+    if (final.length > 0) {
       logger.debug(
-        `[工具收集] 收集了 ${collected.length} 个工具，过滤后 ${filtered.length} 个，` +
-        `用户消息相关性最高的: ${filtered.slice(0, 3).map(t => t.name).join(', ')}`
+        `[工具收集] 收集了 ${collected.length} 个工具，过滤后 ${final.length} 个，` +
+        `用户消息相关性最高的: ${final.slice(0, 3).map(t => t.name).join(', ')}`
       );
     } else {
       logger.debug(`[工具收集] 收集了 ${collected.length} 个工具，但过滤后 0 个（没有超过相关性阈值的）`);
     }
 
-    return filtered;
+    return final;
+  }
+
+  /**
+   * bash 执行策略检查：未通过时抛出 Error（供上层返回给用户）。
+   */
+  private checkExecPolicy(command: string): void {
+    const security = this.config.execSecurity ?? 'deny';
+    if (security === 'full') return;
+    if (security === 'deny') {
+      throw new Error('当前配置禁止执行 Shell 命令（execSecurity=deny）。如需开放请在配置中设置 ai.agent.execSecurity。');
+    }
+    // allowlist
+    const list = this.config.execAllowlist ?? [];
+    const cmd = (command || '').trim();
+    const allowed = list.some(pattern => {
+      try {
+        const re = new RegExp(pattern);
+        return re.test(cmd);
+      } catch {
+        return cmd === pattern || cmd.startsWith(pattern);
+      }
+    });
+    if (!allowed) {
+      const ask = this.config.execAsk;
+      throw new Error(
+        ask
+          ? '该命令不在允许列表中，需要审批后执行。当前版本请将命令加入 ai.agent.execAllowlist 或联系管理员。'
+          : '该命令不在允许列表中，已被拒绝执行。可将允许的命令模式加入 ai.agent.execAllowlist。',
+      );
+    }
+  }
+
+  /**
+   * 对传入的 Agent 工具列表应用 bash 执行策略（仅包装 bash 工具）。
+   */
+  private applyExecPolicyToTools(tools: AgentTool[]): AgentTool[] {
+    return tools.map(t => {
+      if (t.name !== 'bash') return t;
+      const original = t.execute;
+      return {
+        ...t,
+        execute: async (args: Record<string, any>) => {
+          const cmd = args?.command != null ? String(args.command) : '';
+          this.checkExecPolicy(cmd);
+          return original(args);
+        },
+      };
+    });
   }
 
   // ── 辅助方法 ─────────────────────────────────────────────────────────
@@ -709,6 +809,7 @@ ${preData ? `\n已获取数据：${preData}\n` : ''}`;
     if (tool.keywords?.length) at.keywords = tool.keywords;
     if (tool.permissionLevel) at.permissionLevel = PERM_MAP[tool.permissionLevel] ?? 0;
     if (tool.preExecutable) at.preExecutable = true;
+    if ((tool as any).kind) at.kind = (tool as any).kind;
     return at;
   }
 
@@ -738,7 +839,7 @@ ${preData ? `\n已获取数据：${preData}\n` : ''}`;
     lines.push(this.config.persona);
     lines.push('');
 
-    // §2 核心规则（精简为 6 条短句）
+    // §2 核心规则（精简为 7 条短句）
     lines.push('## 规则');
     lines.push('1. 直接调用工具执行操作，不要描述步骤或解释意图');
     lines.push('2. 时间/日期问题：直接用下方"当前时间"回答，不调工具');
@@ -746,6 +847,7 @@ ${preData ? `\n已获取数据：${preData}\n` : ''}`;
     lines.push('4. activate_skill 返回后，必须继续调用其中指导的工具，不要停');
     lines.push('5. 所有回答必须基于工具返回的实际数据');
     lines.push('6. 工具失败时尝试替代方案，不要直接把错误丢给用户');
+    lines.push('7. 只根据用户**最后一条**消息作答，前面的对话仅作背景');
     lines.push('');
 
     // §3 技能列表（紧凑格式）
@@ -1003,10 +1105,12 @@ ${preData ? `\n已获取数据：${preData}\n` : ''}`;
     onChunk?: OnChunkCallback,
   ): Promise<string> {
     const model = this.provider.models[0];
+    const userContent = history.length > 0
+      ? buildUserMessageWithHistory(history, content)
+      : content;
     const messages: ChatMessage[] = [
       { role: 'system', content: systemPrompt },
-      ...history,
-      { role: 'user', content },
+      { role: 'user', content: userContent },
     ];
 
     // 优先流式（对 Ollama 等本地模型有明显提速）

package/src/built/tool.ts

@@ -188,6 +188,7 @@ export class ZhinTool {
   #hidden: boolean = false;
   #source?: string;
   #preExecutable: boolean = false;
+  #kind?: string;
 
   constructor(name: string) {
     this.#name = name;
@@ -265,6 +266,12 @@ export class ZhinTool {
     return this;
   }
 
+  /** 设置工具分类（如 file / shell / web），用于展示与 TOOLS.md 协同 */
+  kind(value: string): this {
+    this.#kind = value;
+    return this;
+  }
+
   usage(...usage: string[]): this {
     this.#commandConfig.usage = [...(this.#commandConfig.usage || []), ...usage];
     return this;
@@ -365,6 +372,7 @@ export class ZhinTool {
     if (this.#source) tool.source = this.#source;
     if (this.#keywords.length > 0) tool.keywords = this.#keywords;
     if (this.#preExecutable) tool.preExecutable = true;
+    if (this.#kind) tool.kind = this.#kind;
 
     if (!this.#commandCallback) {
       tool.command = false;

package/src/plugin.ts

@@ -11,7 +11,7 @@ import { Schema } from "@zhin.js/schema";
 import type { Models, RegisteredAdapters, Tool, ToolContext } from "./types.js";
 import * as fs from "fs";
 import * as path from "path";
-import { fileURLToPath } from "url";
+import { fileURLToPath, pathToFileURL } from "url";
 import logger, { Logger } from "@zhin.js/logger";
 import { compose, remove, resolveEntry } from "./utils.js";
 import { MessageMiddleware, RegisteredAdapter, MaybePromise, ArrayItem, SendOptions } from "./types.js";
@@ -927,7 +927,7 @@ export class Plugin extends EventEmitter<Plugin.Lifecycle> {
     loadedModules.set(realPath, plugin);
 
     await storage.run(plugin, async () => {
-      await import(`${import.meta.resolve(entryFile)}?t=${Date.now()}`);
+      await import(`${pathToFileURL(entryFile).href}?t=${Date.now()}`);
     });
 
     return plugin;

package/src/types.ts

@@ -380,6 +380,9 @@ export interface Tool {
    * 默认为 false，即不预执行。
    */
   preExecutable?: boolean;
+
+  /** 工具分类（如 file / shell / web），用于展示与 TOOLS.md 协同 */
+  kind?: string;
 }
 
 /**