foliko 2.0.7 → 2.0.9

package/plugins/core/scheduler/index.js

@@ -1,792 +1,993 @@
 /**
- * Scheduler 定时任务调度插件
- * 支持 Cron 表达式、绝对时间、相对时间调度
- * 任务触发时自动唤醒 Agent 发送消息
+ * Scheduler 定时任务调度插件 (v2)
+ *
+ * 基于 croner 重新实现，关键改进：
+ * - 用绝对时间戳校验，事件循环阻塞恢复后自动 catch-up（解决"漏触发"）
+ * - 任务重叠保护（cron 短间隔 vs LLM 慢响应）
+ * - 原子化 + debounce 持久化（避免写盘半残、减少 IO）
+ * - 过期一次性任务恢复时立即补触发（catch-up 语义）
+ * - SubAgent 复用（避免长跑漏内存）
+ * - 统一 shell / 普通 任务模型（去除重复代码）
+ * - 删除死代码（_checkTasks / _taskStats / _startScheduler）
  */
 
-const { Plugin } = require('../../../src/plugin/base')
-const { logger } = require('../../../src/common/logger')
-const log = logger.child('Scheduler')
-const { z } = require('zod')
-const fs = require('fs')
-const path = require('path')
-
-let schedule = null
-try {
-  schedule = require('node-schedule')
-} catch (e) {
-  log.warn(' node-schedule not installed, cron tasks will not work')
-}
-
+const { Plugin } = require('../../../src/plugin/base');
+const { logger } = require('../../../src/common/logger');
+const { Cron } = require('croner');
+const { z } = require('zod');
+const fs = require('fs');
+const path = require('path');
+const { randomUUID } = require('crypto');
+
+const log = logger.child('Scheduler');
+
+// 过期一次性任务的最大补触发容忍时间（24h）；超过则直接丢弃
+const ONCE_EXPIRY_GRACE_MS = 24 * 60 * 60 * 1000;
+// 持久化 debounce 时间窗
+const PERSIST_DEBOUNCE_MS = 500;
+
+// 简单关键词检测：判断 reminder 消息是否需要 LLM 处理
+const LLM_KEYWORDS = [
+  '分析', '查询', '查看', '检查', '总结', '搜索', '获取',
+  'list', 'get', 'check', 'search', 'find', 'fetch',
+  '什么', '如何', '为什么', '什么时候', '多少', '谁',
+  '今天', '明天', '昨天', '这周', '这月', '今年',
+];
+
+// ============================================================
+// 持久化存储：原子写 + 加载
+// ============================================================
 class TaskStore {
   constructor(persistencePath) {
-    this._persistencePath = persistencePath
-    this._ensureDir()
+    this._persistencePath = persistencePath;
+    this._ensureDir();
   }
 
   _ensureDir() {
     if (!fs.existsSync(this._persistencePath)) {
-      fs.mkdirSync(this._persistencePath, { recursive: true })
+      fs.mkdirSync(this._persistencePath, { recursive: true });
     }
   }
 
   _getTasksPath() {
-    return path.join(this._persistencePath, 'tasks.json')
+    return path.join(this._persistencePath, 'tasks.json');
   }
 
+  /**
+   * 原子写：先写 .tmp，再 rename（同卷下原子替换）
+   * 避免进程在 writeFileSync 中途崩溃导致 tasks.json 半残
+   */
   saveTasks(tasks) {
+    const finalPath = this._getTasksPath();
+    const tmpPath = finalPath + '.tmp';
     try {
-      const serializable = tasks.map(t => ({
+      const serializable = tasks.map((t) => ({
         id: t.id,
         name: t.name,
         type: t.type,
         message: t.message,
+        shell: t.shell || null,
         enabled: t.enabled,
         createdAt: t.createdAt,
         lastRun: t.lastRun,
         runCount: t.runCount,
         runAt: t.runAt,
         cronExpression: t.cronExpression,
+        timezone: t.timezone,
         sessionId: t.sessionId,
         llm: t.llm,
-        persistDelay: t.persistDelay,
-        persistNextRun: t.persistNextRun,
         notify: t.notify,
-        shell: t.shell
-      }))
-      fs.writeFileSync(this._getTasksPath(), JSON.stringify(serializable, null, 2))
+      }));
+      fs.writeFileSync(tmpPath, JSON.stringify(serializable, null, 2), 'utf-8');
+      fs.renameSync(tmpPath, finalPath);
     } catch (err) {
-      log.error(' 保存任务失败:', err.message)
+      log.error(' 保存任务失败:', err.message);
     }
   }
 
   loadTasks() {
     try {
-      const filePath = this._getTasksPath()
+      const filePath = this._getTasksPath();
       if (fs.existsSync(filePath)) {
-        const data = fs.readFileSync(filePath, 'utf-8')
-        return JSON.parse(data)
+        const data = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(data);
       }
     } catch (err) {
-      log.error(' 加载任务失败:', err.message)
+      log.error(' 加载任务失败:', err.message);
     }
-    return []
+    return [];
   }
 }
 
+// ============================================================
+// 时间解析工具
+// ============================================================
 function parseDelay(delayStr) {
-  const match = delayStr.match(/^(\d+)\s*(second|minute|hour|day|week)s?$/i)
-  if (!match) return null
-  const value = parseInt(match[1])
-  const unit = match[2].toLowerCase()
+  const match = delayStr.match(/^(\d+)\s*(second|minute|hour|day|week)s?$/i);
+  if (!match) return null;
+  const value = parseInt(match[1], 10);
+  const unit = match[2].toLowerCase();
   const multipliers = {
     second: 1000,
     minute: 60 * 1000,
     hour: 60 * 60 * 1000,
     day: 24 * 60 * 60 * 1000,
-    week: 7 * 24 * 60 * 60 * 1000
-  }
-  return value * (multipliers[unit] || 1000)
+    week: 7 * 24 * 60 * 60 * 1000,
+  };
+  return value * (multipliers[unit] || 1000);
 }
 
 function parseAtTime(timeStr) {
-  const now = new Date()
-  const timeMatch = timeStr.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/)
+  const now = new Date();
+  const timeMatch = timeStr.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/);
   if (timeMatch) {
-    const date = new Date(now)
-    date.setHours(parseInt(timeMatch[1]), parseInt(timeMatch[2]), parseInt(timeMatch[3] || 0), 0)
+    const date = new Date(now);
+    date.setHours(parseInt(timeMatch[1], 10), parseInt(timeMatch[2], 10), parseInt(timeMatch[3] || 0, 10), 0);
     if (date <= now) {
-      date.setDate(date.getDate() + 1)
+      date.setDate(date.getDate() + 1);
     }
-    return date
+    return date;
   }
-  return new Date(timeStr)
+  return new Date(timeStr);
 }
 
-function generateId() {
-  if (require('crypto').randomUUID) {
-    return require('crypto').randomUUID()
-  }
-  return `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+function detectLLM(message, explicitFlag) {
+  if (explicitFlag === true) return true;
+  if (explicitFlag === false) return false;
+  const lower = message.toLowerCase();
+  return LLM_KEYWORDS.some((kw) => message.includes(kw) || lower.includes(kw.toLowerCase()));
 }
 
+function isCronString(str) {
+  if (!str) return false;
+  return /^[\d*,\/-\s]+$/.test(str) && str.trim().split(/\s+/).length >= 5;
+}
+
+// ============================================================
+// SchedulerPlugin
+// ============================================================
 class SchedulerPlugin extends Plugin {
   constructor(config = {}) {
-    super()
-    this.name = 'scheduler'
-    this.version = '1.0.0'
-    this.description = '定时任务调度插件，支持 Cron 表达式、绝对时间、相对时间'
-    this.priority = 15
-    this.system = true
-    this.config = {
-      checkInterval: config.checkInterval || 1000,
-      persistencePath: config.persistencePath || '.foliko/data/scheduler'
-    }
+    super();
+    this.name = 'scheduler';
+    this.version = '2.0.2';
+    this.description = '定时任务调度 v2（croner 引擎，事件循环阻塞自愈 + 持久化 + 重叠保护 + 增删改查 + 并发安全）';
+    this.priority = 15;
+    this.system = true;
 
-    this._framework = null
-    this._agent = null
-    this._tasks = new Map()
-    this._timer = null
-    this._taskStore = null
-    this._taskStats = {
-      total: 0,
-      running: 0,
-      completed: 0,
-      failed: 0
-    }
+    this.config = {
+      persistencePath: config.persistencePath || '.foliko/data/scheduler',
+      timezone: config.timezone || process.env.TZ || 'Asia/Shanghai',
+    };
+
+    this._framework = null;
+    this._agent = null;
+    this._tasks = new Map();
+    this._taskStore = new TaskStore(this.config.persistencePath);
+    // 复用的 LLM 执行 subagent（避免每次 tick 新建导致 _agents 数组漏内存）
+    this._schedulerSubAgent = null;
+    // LLM 任务互斥链：B6 修复，避免不同任务的 subagent.chat() 并发污染 subagent 内部状态
+    this._llmMutex = Promise.resolve();
+    // debounce 写入
+    this._persistTimer = null;
+    this._persistDirty = false;
   }
 
   install(framework) {
-    this._framework = framework
-    this._taskStore = new TaskStore(this.config.persistencePath)
-    return this
+    this._framework = framework;
+    return this;
   }
 
   _getAgent() {
-    if (this._agent) return this._agent
+    if (this._agent) return this._agent;
+    if (!this._framework) return null;
     if (this._framework._mainAgent) {
-      this._agent = this._framework._mainAgent
+      this._agent = this._framework._mainAgent;
     } else {
-      const agents = this._framework._agents || []
-      this._agent = agents.length > 0 ? agents[agents.length - 1] : null
+      const agents = this._framework._agents || [];
+      this._agent = agents.length > 0 ? agents[agents.length - 1] : null;
     }
-    return this._agent
+    return this._agent;
+  }
+
+  _getSchedulerSubAgent() {
+    if (this._schedulerSubAgent) return this._schedulerSubAgent;
+    if (!this._framework) return null;
+    this._schedulerSubAgent = this._framework.createSubAgent({
+      name: 'scheduler_task',
+      role: '定时任务执行助手，专注于处理定时提醒和任务执行',
+      hidden: true,
+    });
+    return this._schedulerSubAgent;
   }
 
+  // ============================================================
+  // 工具注册
+  // ============================================================
   start(framework) {
-    this._agent = this._getAgent()
+    this._agent = this._getAgent();
 
     framework.registerTool({
       name: 'schedule_task',
       description: '设置定时提醒任务。支持多种时间格式：相对时间(1 minute, 2 hours)、具体时间(12:00)、Cron表达式(* * * * *)。系统会自动判断任务是否需要 LLM 处理。',
       inputSchema: z.object({
         name: z.string().optional().describe('任务名称'),
-        scheduleTime: z.string().describe('执行时间。支持格式：\n- 相对时间: "1 minute", "2 hours", "1 day"\n- 具体时间: "12:00", "14:30"\n- Cron表达式: "*/5 * * * *" (每5分钟)'),
-        message: z.string().describe('提醒消息内容。系统会自动判断：\n- 简单提醒（喝水、吃饭）直接显示\n- 需要查询/分析的任务（查看列表、分析数据）自动启用 LLM'),
+        scheduleTime: z.string().describe(
+          '执行时间。支持格式：\n- 相对时间: "1 minute", "2 hours", "1 day"\n- 具体时间: "12:00", "14:30"\n- Cron表达式: "*/5 * * * *" (每5分钟)'
+        ),
+        message: z.string().describe('提醒消息内容（shell 模式下作为命令说明）'),
         repeat: z.boolean().optional().describe('是否重复执行 (默认 false)'),
         cronExpression: z.string().optional().describe('Cron 表达式 (当 repeat 为 true 时使用)'),
         sessionId: z.string().optional().describe('会话 ID（提醒将发送到该会话，不填则使用默认会话）'),
         llm: z.boolean().optional().describe('是否需要 LLM 处理（自动检测，可手动覆盖）'),
-        notify: z.boolean().optional().describe('任务完成后是否发送通知（默认 true）。设为 false 时，任务将在后台静默执行，不发送任何通知'),
-        shell: z.string().optional().describe('要执行的 Shell/Bash 命令（如 echo hello, ls -la）')
+        notify: z.boolean().optional().describe('任务完成后是否发送通知（默认 true）'),
+        shell: z.string().optional().describe('要执行的 Shell/Bash 命令（如 echo hello, ls -la）'),
       }),
-      execute: async (args) => {
-        try {
-          const { scheduleTime, message, repeat, cronExpression, sessionId, shell } = args
-          const agent = this._getAgent()
-          if (!agent) {
-            return { success: false, error: 'Agent not available' }
-          }
-
-          if (shell) {
-            const taskId = `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
-            const isCron = /^[\d*,\/-\s]+$/.test(scheduleTime) && scheduleTime.split(' ').length >= 5
-
-            if (isCron || repeat) {
-              if (!schedule) {
-                return { success: false, error: 'node-schedule not installed' }
-              }
-              const task = {
-                id: taskId,
-                name: args.name || 'ShellTask',
-                type: 'shell',
-                cronExpression: cronExpression || scheduleTime,
-                message: message || shell,
-                enabled: true,
-                createdAt: new Date(),
-                lastRun: null,
-                runCount: 0,
-                timer: null,
-                cronTask: null,
-                sessionId: sessionId || null,
-                shell,
-                notify: args.notify !== false
-              }
-              task.cronTask = schedule.scheduleJob(task.cronExpression, async () => {
-                await this._executeTask(task)
-              })
-              this._tasks.set(task.id, task)
-              this._taskStats.total++
-              this._saveTasks()
-              return {
-                success: true,
-                data: repeat ? 'Shell 定时任务已创建 (重复执行)' : 'Shell 任务已创建',
-                metadata: {
-                  taskId: task.id,
-                  name: task.name,
-                  type: 'shell',
-                  shell,
-                  scheduleTime,
-                  cronExpression: task.cronExpression,
-                  sessionId: sessionId || 'default',
-                  notify: task.notify
-                }
-              }
-            } else {
-              const delayMs = parseDelay(scheduleTime)
-              if (!delayMs && !scheduleTime.includes(':')) {
-                return { success: false, error: '无效的时间格式' }
-              }
-              let runAt = null
-              let delay = 0
-              if (scheduleTime.includes(':')) {
-                runAt = parseAtTime(scheduleTime)
-                delay = runAt.getTime() - Date.now()
-              } else {
-                delay = parseDelay(scheduleTime)
-                runAt = new Date(Date.now() + delay)
-              }
-              const task = {
-                id: taskId,
-                name: args.name || 'ShellTask',
-                type: 'shell',
-                runAt,
-                message: message || shell,
-                enabled: true,
-                createdAt: new Date(),
-                lastRun: null,
-                runCount: 0,
-                timer: null,
-                sessionId: sessionId || null,
-                shell,
-                persistDelay: delay,
-                notify: args.notify !== false
-              }
-              task.timer = setTimeout(async () => {
-                await this._executeTask(task)
-              }, delay)
-              this._tasks.set(task.id, task)
-              this._taskStats.total++
-              this._saveTasks()
-              return {
-                success: true,
-                data: 'Shell 任务已创建',
-                metadata: {
-                  taskId: task.id,
-                  name: task.name,
-                  type: 'shell',
-                  shell,
-                  scheduleTime,
-                  executeAt: runAt.toISOString(),
-                  sessionId: sessionId || 'default',
-                  notify: task.notify
-                }
-              }
-            }
-          }
-
-          let targetSessionId = sessionId
-          if (!targetSessionId) {
-            const ctx = this._framework.getExecutionContext()
-            if (ctx?.sessionId) {
-              targetSessionId = ctx.sessionId
-            }
-          }
-          if (!targetSessionId) {
-            const sessionPlugin = this._framework.pluginManager.get('session')
-            if (sessionPlugin) {
-              const sessions = sessionPlugin.listSessions()
-              if (sessions.length > 0) {
-                sessions.sort((a, b) => {
-                  const aTime = a.lastActive ? new Date(a.lastActive).getTime() : 0
-                  const bTime = b.lastActive ? new Date(b.lastActive).getTime() : 0
-                  return bTime - aTime
-                })
-                targetSessionId = sessions[0].id
-              }
-            }
-          }
-
-          const taskId = `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
-          let task
-
-          const LLM_KEYWORDS = [
-            '分析', '查询', '查看', '检查', '总结', '搜索', '获取',
-            'list', 'get', 'check', 'search', 'find', 'fetch',
-            '什么', '如何', '为什么', '什么时候', '多少', '谁',
-            '今天', '明天', '昨天', '这周', '这月', '今年'
-          ]
-          const messageLower = message.toLowerCase()
-          const needsLLM = args.llm === true || LLM_KEYWORDS.some(kw =>
-            message.includes(kw) || messageLower.includes(kw.toLowerCase())
-          )
-          const llmMode = needsLLM
-
-          const isCron = /^[\d*,\/-\s]+$/.test(scheduleTime) && scheduleTime.split(' ').length >= 5
-
-          if (isCron || repeat) {
-            if (!schedule) {
-              return { success: false, error: 'node-schedule not installed' }
-            }
-            task = {
-              id: taskId,
-              name: args.name || 'CronTask',
-              type: 'cron',
-              cronExpression: cronExpression || scheduleTime,
-              message,
-              enabled: true,
-              createdAt: new Date(),
-              lastRun: null,
-              runCount: 0,
-              timer: null,
-              cronTask: null,
-              sessionId: targetSessionId || null,
-              llm: llmMode,
-              notify: args.notify !== false
-            }
-
-            task.cronTask = schedule.scheduleJob(task.cronExpression, async () => {
-              await this._executeTask(task)
-            })
-          } else if (scheduleTime.includes(':')) {
-            const runAt = parseAtTime(scheduleTime)
-            task = {
-              id: taskId,
-              name: args.name || 'Reminder',
-              type: 'once',
-              runAt,
-              message,
-              enabled: true,
-              createdAt: new Date(),
-              lastRun: null,
-              runCount: 0,
-              timer: null,
-              sessionId: targetSessionId || null,
-              llm: llmMode,
-              notify: args.notify !== false
-            }
-            task.timer = setTimeout(async () => {
-              await this._executeTask(task)
-            }, runAt.getTime() - Date.now())
-          } else {
-            const delayMs = parseDelay(scheduleTime)
-            if (!delayMs) {
-              return { success: false, error: '无效的时间格式' }
-            }
-            const runAt = new Date(Date.now() + delayMs)
-            task = {
-              id: taskId,
-              name: args.name || 'Reminder',
-              type: 'once',
-              runAt,
-              message,
-              enabled: true,
-              createdAt: new Date(),
-              lastRun: null,
-              runCount: 0,
-              timer: null,
-              sessionId: targetSessionId || null,
-              llm: llmMode,
-              persistDelay: delayMs,
-              notify: args.notify !== false
-            }
-            task.timer = setTimeout(async () => {
-              await this._executeTask(task)
-            }, delayMs)
-          }
-
-          this._tasks.set(task.id, task)
-          this._taskStats.total++
-          this._saveTasks()
-
-          this._framework.emit('scheduler:task_created', {
-            taskId: task.id,
-            taskName: task.name,
-            type: task.type,
-            scheduleTime,
-            cronExpression: task.cronExpression
-          })
-
-          return {
-            success: true,
-            taskId: task.id,
-            name: task.name,
-            scheduleTime,
-            executeAt: task.runAt ? task.runAt.toISOString() : null,
-            cronExpression: task.cronExpression,
-            message: repeat ? '定时任务已创建 (重复执行)' : '提醒已设置',
-            sessionId: sessionId || 'default',
-            llm: llmMode,
-            notify: task.notify
-          }
-        } catch (err) {
-          return { success: false, error: err.message }
-        }
-      }
-    })
+      execute: async (args) => this._createTask(args),
+    });
 
     framework.registerTool({
       name: 'schedule_list',
       description: '列出所有定时任务',
       inputSchema: z.object({}),
       execute: async () => {
-        const tasks = Array.from(this._tasks.values()).map(t => ({
-          id: t.id,
-          name: t.name,
-          type: t.type,
-          message: t.message,
-          enabled: t.enabled,
-          nextRun: t.nextRun || t.runAt,
-          runCount: t.runCount,
-          lastRun: t.lastRun,
-          cronExpression: t.cronExpression,
-          llm: t.llm,
-          notify: t.notify,
-          sessionId: t.sessionId,
-          shell: t.shell
-        }))
+        const tasks = Array.from(this._tasks.values()).map((t) => {
+          // croner 提供 nextRun() getter：cron 任务下一触发时间；once 任务固定 runAt
+          let nextRun = null;
+          try {
+            nextRun = t.scheduleHandle?.nextRun?.() || t.runAt || null;
+          } catch {
+            nextRun = t.runAt || null;
+          }
+          return {
+            id: t.id,
+            name: t.name,
+            type: t.type,
+            message: t.message,
+            shell: t.shell || null,
+            enabled: t.enabled,
+            nextRun,
+            runCount: t.runCount,
+            lastRun: t.lastRun,
+            cronExpression: t.cronExpression,
+            timezone: t.timezone,
+            llm: t.llm,
+            notify: t.notify,
+            sessionId: t.sessionId,
+          };
+        });
+        return { success: true, tasks, total: tasks.length };
+      },
+    });
+
+    framework.registerTool({
+      name: 'schedule_cancel',
+      description: '取消定时任务',
+      inputSchema: z.object({ taskId: z.string().describe('任务 ID') }),
+      execute: async (args) => this._cancelTask(args.taskId),
+    });
 
+    framework.registerTool({
+      name: 'schedule_get',
+      description: '按 ID 获取单个定时任务的完整详情',
+      inputSchema: z.object({ taskId: z.string().describe('任务 ID') }),
+      execute: async (args) => {
+        const task = this._tasks.get(args.taskId);
+        if (!task) return { success: false, error: 'Task not found' };
+        let nextRun = null;
+        try { nextRun = task.scheduleHandle?.nextRun?.() || task.runAt || null; } catch {}
         return {
           success: true,
-          tasks,
-          total: tasks.length,
-          stats: { ...this._taskStats }
-        }
-      }
-    })
+          task: {
+            id: task.id,
+            name: task.name,
+            type: task.type,
+            message: task.message,
+            shell: task.shell || null,
+            enabled: task.enabled,
+            running: task.running,
+            nextRun,
+            runCount: task.runCount,
+            lastRun: task.lastRun,
+            createdAt: task.createdAt,
+            cronExpression: task.cronExpression,
+            runAt: task.runAt,
+            timezone: task.timezone,
+            llm: task.llm,
+            notify: task.notify,
+            sessionId: task.sessionId,
+          },
+        };
+      },
+    });
 
     framework.registerTool({
-      name: 'schedule_cancel',
-      description: '取消定时任务',
+      name: 'schedule_update',
+      description: '修改已存在的定时任务。可以修改：name/message/scheduleTime/cronExpression/sessionId/llm/notify/shell。如果改了 scheduleTime 或 cronExpression，会自动重新创建调度。runCount/lastRun/createdAt 保持不变。',
       inputSchema: z.object({
-        taskId: z.string().describe('任务 ID')
+        taskId: z.string().describe('要修改的任务 ID'),
+        name: z.string().optional().describe('新任务名称'),
+        message: z.string().optional().describe('新提醒消息'),
+        scheduleTime: z.string().optional().describe('新时间（覆盖原 scheduleTime）。格式同 schedule_task'),
+        cronExpression: z.string().optional().describe('新 Cron 表达式（仅 cron 任务有效，优先级高于 scheduleTime）'),
+        sessionId: z.string().optional().describe('新会话 ID'),
+        llm: z.boolean().optional().describe('是否需要 LLM 处理'),
+        notify: z.boolean().optional().describe('是否发送通知'),
+        shell: z.string().optional().describe('新的 shell 命令（覆盖旧值）'),
+        enabled: z.boolean().optional().describe('启用/禁用任务（不删除）'),
       }),
-      execute: async (args) => {
-        const task = this._tasks.get(args.taskId)
-        if (!task) {
-          return { success: false, error: 'Task not found' }
-        }
-
-        const taskName = task.name
-        this._cancelTask(task)
-        this._saveTasks()
-
-        this._framework.emit('notification', {
-          title: '任务已取消',
-          message: `定时任务 "${taskName}" 已取消`,
-          source: 'scheduler',
-          level: 'info',
-          sessionId: task.sessionId,
-          timestamp: new Date()
-        })
-
-        return { success: true, cancelled: args.taskId }
-      }
-    })
+      execute: async (args) => this._updateTask(args),
+    });
 
     framework.registerTool({
       name: 'cron_examples',
       description: '获取常用 Cron 表达式示例',
       inputSchema: z.object({}),
-      execute: async () => {
-        return {
-          examples: [
-            { expression: '* * * * *', description: '每分钟' },
-            { expression: '*/5 * * * *', description: '每5分钟' },
-            { expression: '*/15 * * * *', description: '每15分钟' },
-            { expression: '0 * * * *', description: '每小时' },
-            { expression: '0 9 * * *', description: '每天早上9点' },
-            { expression: '0 12 * * *', description: '每天中午12点' },
-            { expression: '0 18 * * *', description: '每天下午6点' },
-            { expression: '0 9 * * 1-5', description: '工作日上午9点' },
-            { expression: '0 9 * * 0,6', description: '周末上午9点' },
-            { expression: '0 9 * * 1', description: '每周一上午9点' },
-            { expression: '0 */2 * * *', description: '每2小时' }
-          ]
+      execute: async () => ({
+        examples: [
+          { expression: '* * * * *', description: '每分钟' },
+          { expression: '*/5 * * * *', description: '每5分钟' },
+          { expression: '*/15 * * * *', description: '每15分钟' },
+          { expression: '0 * * * *', description: '每小时' },
+          { expression: '0 9 * * *', description: '每天早上9点' },
+          { expression: '0 12 * * *', description: '每天中午12点' },
+          { expression: '0 18 * * *', description: '每天下午6点' },
+          { expression: '0 9 * * 1-5', description: '工作日上午9点' },
+          { expression: '0 9 * * 0,6', description: '周末上午9点' },
+          { expression: '0 9 * * 1', description: '每周一上午9点' },
+          { expression: '0 */2 * * *', description: '每2小时' },
+        ],
+      }),
+    });
+
+    this._loadPersistedTasks();
+    return this;
+  }
+
+  // ============================================================
+  // 任务创建（统一入口，shell 与普通合并）
+  // ============================================================
+  async _createTask(args) {
+    try {
+      const { scheduleTime, message, repeat, cronExpression, sessionId, shell } = args;
+
+      // 解析时间
+      const isCron = isCronString(scheduleTime);
+      let taskType; // 'cron' | 'once'
+      let runAt = null;
+      let cron = null;
+
+      if (isCron || repeat) {
+        taskType = 'cron';
+        cron = cronExpression || scheduleTime;
+      } else if (scheduleTime.includes(':')) {
+        taskType = 'once';
+        runAt = parseAtTime(scheduleTime);
+        if (isNaN(runAt.getTime())) {
+          return { success: false, error: `无法解析时间: ${scheduleTime}` };
+        }
+      } else {
+        const delayMs = parseDelay(scheduleTime);
+        if (!delayMs) {
+          return { success: false, error: '无效的时间格式' };
         }
+        taskType = 'once';
+        runAt = new Date(Date.now() + delayMs);
       }
-    })
 
-    this._startScheduler()
+      // shell 任务的实际执行受 _runShell 内的安全策略控制：必须通过已注册的 shell 工具
+      if (shell && !this._hasShellTool()) {
+        // 创建时仍允许；执行时会被 _runShell 拒绝（fail-closed）
+        log.warn(` Shell 任务 ${args.name} 创建时未检测到 shell_exec/shell 工具，触发时将失败`);
+      }
 
-    this._loadPersistedTasks()
+      // 解析 sessionId
+      let targetSessionId = sessionId;
+      if (!targetSessionId) {
+        const ctx = this._framework?.getExecutionContext?.();
+        if (ctx?.sessionId) targetSessionId = ctx.sessionId;
+      }
+      if (!targetSessionId) {
+        const sessionPlugin = this._framework?.pluginManager?.get('session');
+        if (sessionPlugin) {
+          const sessions = sessionPlugin.listSessions();
+          if (sessions.length > 0) {
+            sessions.sort((a, b) => {
+              const aTime = a.lastActive ? new Date(a.lastActive).getTime() : 0;
+              const bTime = b.lastActive ? new Date(b.lastActive).getTime() : 0;
+              return bTime - aTime;
+            });
+            targetSessionId = sessions[0].id;
+          }
+        }
+      }
 
-    return this
-  }
+      const llmMode = shell ? false : detectLLM(message, args.llm);
+      const task = {
+        id: `task_${randomUUID()}`,
+        name: args.name || (shell ? 'ShellTask' : taskType === 'cron' ? 'CronTask' : 'Reminder'),
+        type: taskType,
+        message,
+        shell: shell || null,
+        enabled: true,
+        createdAt: new Date(),
+        lastRun: null,
+        runCount: 0,
+        cronExpression: cron,
+        runAt,
+        timezone: this.config.timezone,
+        sessionId: targetSessionId || null,
+        llm: llmMode,
+        notify: args.notify !== false,
+        running: false,
+        stopped: false,        // 显式跟踪被 stop() 的状态（croner stop() 不清 handle 引用）
+        scheduleHandle: null,
+      };
+
+      // 创建 croner 调度
+      try {
+        if (taskType === 'cron') {
+          task.scheduleHandle = new Cron(cron, this._cronOptions(task), () => this._onFire(task));
+        } else {
+          // once：startAt 限定未来触发
+          task.scheduleHandle = new Cron(runAt, this._cronOptions(task), () => this._onFire(task));
+        }
+      } catch (err) {
+        return { success: false, error: `调度创建失败: ${err.message}` };
+      }
+
+      this._tasks.set(task.id, task);
+      this._schedulePersist();
 
-  _startScheduler() {
-    if (this._timer) {
-      clearInterval(this._timer)
+      this._framework?.emit('scheduler:task_created', {
+        taskId: task.id,
+        taskName: task.name,
+        type: task.type,
+        scheduleTime,
+        cronExpression: task.cronExpression,
+      });
+
+      return {
+        success: true,
+        taskId: task.id,
+        name: task.name,
+        scheduleTime,
+        executeAt: task.runAt ? task.runAt.toISOString() : null,
+        cronExpression: task.cronExpression,
+        message: task.type === 'cron' ? '定时任务已创建 (重复执行)' : '提醒已设置',
+        sessionId: targetSessionId || 'default',
+        llm: llmMode,
+        notify: task.notify,
+      };
+    } catch (err) {
+      return { success: false, error: err.message };
     }
+  }
 
-    this._timer = setInterval(() => {
-      this._checkTasks()
-    }, this.config.checkInterval)
+  _cronOptions(task) {
+    return {
+      timezone: this.config.timezone,
+      protect: true, // 防重叠：上一次还没跑完，跳过本次
+      catch: true,   // catch-up：进程恢复后补触发错过的触发
+      name: `scheduler:${task.id}`,
+      unref: true,   // 不阻止进程退出
+    };
   }
 
-  _checkTasks() {
-    for (const [id, task] of this._tasks) {
-      if (!task.enabled) continue
+  // ============================================================
+  // 触发回调
+  // ============================================================
+  async _onFire(task) {
+    if (!task.enabled) return;
+    if (task.running) {
+      // 理论上 protect:true 已经处理过；这里再保险一次
+      log.warn(` 任务 ${task.name} 仍在执行中，跳过本次触发`);
+      return;
+    }
+    task.running = true;
+    task.lastRun = new Date();
+    task.runCount++;
+    try {
+      await this._executeTask(task);
+    } finally {
+      task.running = false;
     }
-  }
 
-  _saveTasks() {
-    if (this._taskStore) {
-      this._taskStore.saveTasks(Array.from(this._tasks.values()))
+    // once 任务触发一次后清理
+    if (task.type === 'once') {
+      this._cleanupTask(task.id);
+    } else {
+      // cron 任务只更新持久化（不写 runAt）
+      this._schedulePersist();
     }
   }
 
-  _loadPersistedTasks() {
-    if (!this._taskStore) return
-
-    const savedTasks = this._taskStore.loadTasks()
-    if (!savedTasks || savedTasks.length === 0) return
-
-    for (const saved of savedTasks) {
-      if (saved.type === 'once' && saved.runCount > 0) {
-        continue
-      }
-
-      let task = { ...saved }
-
-      if (task.type === 'cron' && task.enabled && schedule) {
-        try {
-          task.cronTask = schedule.scheduleJob(task.cronExpression, async () => {
-            await this._executeTask(task)
-          })
-          this._tasks.set(task.id, task)
-          this._taskStats.total++
-        } catch (err) {
-          log.error(` 恢复 Cron 任务失败: ${task.name}`, err.message)
-        }
-      }
-      else if (task.type === 'shell' && task.enabled && task.cronExpression && schedule) {
-        try {
-          task.cronTask = schedule.scheduleJob(task.cronExpression, async () => {
-            await this._executeTask(task)
-          })
-          this._tasks.set(task.id, task)
-          this._taskStats.total++
-        } catch (err) {
-          log.error(` 恢复 Shell Cron 任务失败: ${task.name}`, err.message)
-        }
-      }
-      else if (task.type === 'once' && task.enabled && task.persistDelay) {
-        const newDelay = task.persistDelay
-        if (newDelay > 0) {
-          task.runAt = new Date(Date.now() + newDelay)
-          task.timer = setTimeout(async () => {
-            await this._executeTask(task)
-          }, newDelay)
-          this._tasks.set(task.id, task)
-          this._taskStats.total++
-        }
+  async _executeTask(task) {
+    try {
+      // shell 执行
+      if (task.shell) {
+        return await this._runShell(task);
       }
-      else if (task.type === 'once' && task.enabled && task.runAt) {
-        const runAt = new Date(task.runAt)
-        if (runAt > new Date()) {
-          const delay = runAt.getTime() - Date.now()
-          task.timer = setTimeout(async () => {
-            await this._executeTask(task)
-          }, delay)
-          this._tasks.set(task.id, task)
-          this._taskStats.total++
-        }
+      // LLM 执行
+      if (task.llm) {
+        return await this._runLLM(task);
       }
+      // 普通提醒（直接发通知）
+      return await this._runNotification(task);
+    } catch (err) {
+      log.error(` Task ${task.name} failed:`, err.message);
+      this._framework?.emit('notification', {
+        title: `任务失败: ${task.name}`,
+        message: err.message,
+        source: 'scheduler',
+        level: 'error',
+        sessionId: task.sessionId,
+        timestamp: new Date(),
+      });
+      this._framework?.emit('scheduler:task_failed', {
+        taskId: task.id,
+        error: err.message,
+      });
+      return { error: err.message };
     }
   }
 
-  _cancelTask(task) {
-    if (task.timer) {
-      clearTimeout(task.timer)
-      task.timer = null
+  async _runShell(task) {
+    // 安全要求：shell 命令必须通过已注册的 shell 工具执行（这些工具应实现沙箱/白名单）
+    // 不再 fallback 到 child_process.exec，避免任意命令执行漏洞
+    const shellTool = this._hasShellTool() ? this._pickShellTool() : null;
+    if (!shellTool) {
+      const errMsg = '未检测到 shell_exec/shell 工具，拒绝执行 shell 任务（安全策略）';
+      log.error(` ${task.name}: ${errMsg}`);
+      this._framework?.emit('notification', {
+        title: `任务失败: ${task.name}`,
+        message: errMsg,
+        source: 'scheduler',
+        level: 'error',
+        sessionId: task.sessionId,
+        timestamp: new Date(),
+      });
+      this._framework?.emit('scheduler:task_failed', { taskId: task.id, error: errMsg });
+      return { error: errMsg };
     }
-    if (task.cronTask) {
-      task.cronTask.cancel()
-      task.cronTask = null
+
+    let result;
+    try {
+      const raw = await this._framework.executeTool(shellTool, { command: task.shell });
+      // 适配不同 shell 工具的返回格式
+      if (raw?.error) {
+        result = { error: raw.error, stdout: raw.stdout, stderr: raw.stderr };
+      } else if (raw?.success === false) {
+        const msg = raw.exitCode !== undefined ? `退出码 ${raw.exitCode}: ${raw.stderr || ''}` : (raw.error || 'shell 执行失败');
+        result = { error: msg, stdout: raw.stdout, stderr: raw.stderr };
+      } else {
+        result = { output: raw.stdout || raw.output || '', stdout: raw.stdout, stderr: raw.stderr };
+      }
+    } catch (e) {
+      result = { error: e.message || String(e) };
     }
-    task.enabled = false
-  }
 
-  async _executeTask(task) {
-    task.lastRun = new Date()
-    task.runCount++
-    this._taskStats.running++
+    const output = result.error
+      ? `执行失败: ${result.error}`
+      : (result.output || result.stdout || JSON.stringify(result));
 
-    try {
-      if (task.type === 'shell') {
-        let result;
-        if (this._framework.toolRegistry?.has?.('shell_exec') || this._framework.toolRegistry?.has?.('shell')) {
-          const toolName = this._framework.toolRegistry.has('shell_exec') ? 'shell_exec' : 'shell';
-          result = await this._framework.executeTool(toolName, { command: task.shell });
-          // 适配 shell_exec 的返回格式（{success, stdout, stderr}）到统一格式
-          if (result.success === false && result.error) {
-            // shell_exec 已捕获错误
-          } else if (result.success === false && result.exitCode !== 0) {
-            result = { error: `退出码 ${result.exitCode}: ${result.stderr}`, stdout: result.stdout, stderr: result.stderr };
-          } else {
-            result = { output: result.stdout, stdout: result.stdout, stderr: result.stderr };
-          }
-        } else {
-          // 兜底：shell 工具不存在时直接用 child_process 执行
-          const { exec } = require('child_process');
-          const util = require('util');
-          const execAsync = util.promisify(exec);
-          try {
-            const { stdout, stderr } = await execAsync(task.shell, { timeout: 60000 });
-            result = { output: stdout.trim(), stdout: stdout.trim(), stderr: stderr.trim() };
-          } catch (e) {
-            result = { error: e.message, stderr: e.stderr || '' };
-          }
-        }
-        this._taskStats.completed++
+    if (task.notify !== false) {
+      this._framework?.emit('notification', {
+        title: task.name,
+        message: output,
+        source: 'scheduler',
+        level: result.error ? 'error' : 'info',
+        sessionId: task.sessionId,
+        timestamp: new Date(),
+      });
+    }
+    this._framework?.emit('scheduler:task_completed', { taskId: task.id, result: output });
+    return { success: true };
+  }
 
-        const output = result.error ? `执行失败: ${result.error}` : (result.output || result.stdout || JSON.stringify(result))
-        if (task.notify !== false) {
-          this._framework.emit('notification', {
+  async _runLLM(task) {
+    const subAgent = this._getSchedulerSubAgent();
+    if (!subAgent) {
+      return { error: '无法创建 scheduler subagent' };
+    }
+    // B6 修复：用 promise-chain 互斥，把 LLM 任务串行化
+    // 即使两个不同任务同时触发 _onFire，它们的 subagent.chat() 也会排队执行
+    const work = async () => {
+      try {
+        const result = await subAgent.chat(task.message);
+        const responseText = result?.message;
+        if (task.notify !== false && responseText && responseText.trim()) {
+          this._framework?.emit('notification', {
             title: task.name,
-            message: output,
+            message: responseText,
             source: 'scheduler',
-            level: result.error ? 'error' : 'info',
+            level: 'info',
             sessionId: task.sessionId,
-            timestamp: new Date()
-          })
+            timestamp: new Date(),
+          });
+          this._framework?.emit('scheduler:reminder', {
+            taskId: task.id,
+            message: task.message,
+            time: task.runAt || null,
+          });
         }
-
-        this._framework.emit('scheduler:task_completed', {
+        this._framework?.emit('scheduler:task_completed', {
           taskId: task.id,
-          result: output
-        })
+          result: responseText || task.message,
+        });
+        return { success: true };
+      } catch (e) {
+        const errMsg = e?.message || String(e);
+        log.error(` _runLLM ${task.name}:`, errMsg);
+        this._framework?.emit('notification', {
+          title: `任务失败: ${task.name}`,
+          message: errMsg,
+          source: 'scheduler',
+          level: 'error',
+          sessionId: task.sessionId,
+          timestamp: new Date(),
+        });
+        this._framework?.emit('scheduler:task_failed', { taskId: task.id, error: errMsg });
+        return { error: errMsg };
+      }
+    };
+    this._llmMutex = this._llmMutex.then(work, work);
+    return this._llmMutex;
+  }
 
-        if (task.type === 'once' && !task.cronTask) {
-          this._cleanupTask(task.id)
-        }
+  async _runNotification(task) {
+    if (task.notify !== false) {
+      this._framework?.emit('notification', {
+        title: task.name,
+        message: task.message,
+        source: 'scheduler',
+        level: 'info',
+        sessionId: task.sessionId,
+        timestamp: new Date(),
+      });
+      this._framework?.emit('scheduler:reminder', {
+        taskId: task.id,
+        message: task.message,
+        time: task.runAt || null,
+      });
+    }
+    this._framework?.emit('scheduler:task_completed', {
+      taskId: task.id,
+      result: task.message,
+    });
+    return { success: true };
+  }
 
-        return { success: true }
-      } else if (task.llm) {
-        const schedulerAgent = this._framework.createSubAgent({
-          name: 'scheduler_task',
-          role: '定时任务执行助手，专注于处理定时提醒和任务执行',
-          hidden: true
-        })
+  // ============================================================
+  // 取消 & 清理
+  // ============================================================
+  _cancelTask(taskId) {
+    const task = this._tasks.get(taskId);
+    if (!task) return { success: false, error: 'Task not found' };
 
-        const result = await schedulerAgent.chat(task.message)
+    const taskName = task.name;
+    try {
+      task.scheduleHandle?.stop();
+    } catch {}
+    task.enabled = false;
+    task.stopped = true;
+    this._tasks.delete(taskId);
+    this._schedulePersist();
+
+    this._framework?.emit('notification', {
+      title: '任务已取消',
+      message: `定时任务 "${taskName}" 已取消`,
+      source: 'scheduler',
+      level: 'info',
+      sessionId: task.sessionId,
+      timestamp: new Date(),
+    });
+
+    return { success: true, cancelled: taskId };
+  }
 
-        this._taskStats.completed++
+  /**
+   * 修改任务。
+   * 关键规则：
+   * 1. 改 scheduleTime / cronExpression → 二阶段提交：先构造验证新 handle 成功，再 commit
+   * 2. 改 message / shell / llm / notify / sessionId / name / enabled → 仅更新字段
+   * 3. runCount / lastRun / createdAt / id 永远不变
+   * 4. type 字段（cron/once）不能跨类型切换——例如不能把 once 改成 cron（语义差异大），
+   *    这种情况下提示用户先 cancel 再 create
+   * 5. enable: false → set stopped=true + stop() handle；enable: true → 检查 stopped 重建 handle
+   */
+  _updateTask(args) {
+    const { taskId } = args;
+    const task = this._tasks.get(taskId);
+    if (!task) return { success: false, error: 'Task not found' };
+
+    const updated = {};
+    // 收集"非时间"变更（这些变更先做；时间变更走二阶段提交）
+    if (args.name !== undefined) { task.name = args.name; updated.name = args.name; }
+    if (args.message !== undefined) { task.message = args.message; updated.message = task.message; }
+    if (args.sessionId !== undefined) { task.sessionId = args.sessionId || null; updated.sessionId = task.sessionId; }
+    if (args.notify !== undefined) { task.notify = !!args.notify; updated.notify = task.notify; }
+    if (args.llm !== undefined) { task.llm = !!args.llm; updated.llm = task.llm; }
+    if (args.shell !== undefined) {
+      task.shell = args.shell || null;
+      // shell 与 llm 互斥
+      if (task.shell) { task.llm = false; updated.llm = false; }
+      updated.shell = task.shell;
+    }
 
-        const responseText = result.message
+    // enabled 处理（影响 stopped 状态和后续重建）
+    if (args.enabled !== undefined) {
+      const wasEnabled = task.enabled;
+      task.enabled = !!args.enabled;
+      updated.enabled = task.enabled;
+      if (!task.enabled) {
+        // 暂停：stop handle，标记 stopped=true
+        try { task.scheduleHandle?.stop(); } catch {}
+        task.stopped = true;
+      } else if (!wasEnabled) {
+        // 从暂停恢复：标记为需要重建（在时间变更之后统一重建）
+        task.stopped = true; // 强制让下面"重建"分支执行
+      }
+    }
 
-        if (task.notify !== false && responseText && responseText.trim()) {
-          this._framework.emit('notification', {
-            title: task.name,
-            message: responseText,
-            source: 'scheduler',
-            level: 'info',
-            sessionId: task.sessionId,
-            timestamp: new Date()
-          })
-          this._framework.emit('scheduler:reminder', {
-            taskId: task.id,
-            message: task.message,
-            time: task.runAt || task.nextRun
-          })
-        }
+    // 时间变更（cronExpression / scheduleTime）— 二阶段提交
+    let newCron = task.cronExpression;
+    let newRunAt = task.runAt;
+    let typeChanged = false;
+    let timeValidationError = null;
 
-        this._framework.emit('scheduler:task_completed', {
-          taskId: task.id,
-          result: responseText || task.message
-        })
+    if (args.cronExpression !== undefined) {
+      // 显式 cron 表达式：必须是 cron 任务
+      if (task.type !== 'cron') {
+        timeValidationError = `无法把 ${task.type} 任务改为 cron 表达式（类型不兼容）。请先取消再创建。`;
       } else {
-        if (task.notify !== false) {
-          this._framework.emit('notification', {
-            title: task.name,
-            message: task.message,
-            source: 'scheduler',
-            level: 'info',
-            sessionId: task.sessionId,
-            timestamp: new Date()
-          })
-          this._framework.emit('scheduler:reminder', {
-            taskId: task.id,
-            message: task.message,
-            time: task.runAt || task.nextRun
-          })
+        newCron = args.cronExpression;
+      }
+    } else if (args.scheduleTime !== undefined) {
+      const st = args.scheduleTime;
+      const isCron = isCronString(st);
+      if (isCron) {
+        if (task.type !== 'cron') {
+          timeValidationError = `无法把 ${task.type} 任务改为 cron 表达式（类型不兼容）。请先取消再创建。`;
+        } else {
+          newCron = st;
+        }
+      } else {
+        if (task.type !== 'once') {
+          timeValidationError = `无法把 ${task.type} 任务改为一次性时间（类型不兼容）。请先取消再创建。`;
+        } else {
+          // 解析 runAt
+          let parsed;
+          if (st.includes(':')) {
+            parsed = parseAtTime(st);
+          } else {
+            const delayMs = parseDelay(st);
+            if (!delayMs) {
+              timeValidationError = `无效的时间格式: ${st}`;
+            } else {
+              parsed = new Date(Date.now() + delayMs);
+            }
+          }
+          if (parsed && isNaN(parsed.getTime())) {
+            timeValidationError = `无法解析时间: ${st}`;
+          } else if (parsed) {
+            if (task.runCount > 0) {
+              timeValidationError = '一次性任务已执行过，无法修改时间。请取消后重建。';
+            } else {
+              newRunAt = parsed;
+            }
+          }
         }
-
-        this._framework.emit('scheduler:task_completed', {
-          taskId: task.id,
-          result: task.message
-        })
-        this._taskStats.completed++
       }
+    }
+
+    if (timeValidationError) {
+      return { success: false, error: timeValidationError };
+    }
 
-      if (task.type === 'once' && !task.cronTask) {
-        this._cleanupTask(task.id)
+    // 二阶段提交：先尝试构造新 handle 验证
+    let newHandle = null;
+    const handleChanged =
+      newCron !== task.cronExpression ||
+      newRunAt !== task.runAt ||
+      (args.enabled !== undefined && task.enabled === true && task.stopped);
+
+    if (handleChanged && task.enabled) {
+      try {
+        if (task.type === 'cron') {
+          newHandle = new Cron(newCron, this._cronOptions(task), () => this._onFire(task));
+        } else {
+          newHandle = new Cron(newRunAt, this._cronOptions(task), () => this._onFire(task));
+        }
+      } catch (err) {
+        return { success: false, error: `新调度表达式无效: ${err.message}` };
       }
+    }
 
-      return { success: true }
-    } catch (err) {
-      this._taskStats.failed++
-      log.error(` Task ${task.name} failed: ${err.message}`)
+    // 验证通过，commit
+    if (newHandle) {
+      try { task.scheduleHandle?.stop(); } catch {}
+      task.scheduleHandle = newHandle;
+      task.cronExpression = newCron;
+      task.runAt = newRunAt;
+      task.stopped = false;
+      if (args.cronExpression !== undefined || (args.scheduleTime !== undefined && isCronString(args.scheduleTime))) {
+        updated.cronExpression = task.cronExpression;
+      }
+      if (args.scheduleTime !== undefined && !isCronString(args.scheduleTime)) {
+        updated.runAt = task.runAt.toISOString();
+      }
+    } else if (args.enabled !== undefined && task.enabled) {
+      // enable: true 但 handle 没变（任务本来就是 enabled）；无需操作
+    }
 
-      this._framework.emit('notification', {
-        title: `任务失败: ${task.name}`,
-        message: err.message,
-        source: 'scheduler',
-        level: 'error',
+    this._tasks.set(task.id, task);
+    this._schedulePersist();
+
+    let nextRun = null;
+    try { nextRun = task.scheduleHandle?.nextRun?.() || task.runAt || null; } catch {}
+
+    return {
+      success: true,
+      taskId: task.id,
+      updated,
+      task: {
+        id: task.id,
+        name: task.name,
+        type: task.type,
+        message: task.message,
+        shell: task.shell || null,
+        enabled: task.enabled,
+        stopped: task.stopped,
+        llm: task.llm,
+        notify: task.notify,
         sessionId: task.sessionId,
-        timestamp: new Date()
-      })
+        cronExpression: task.cronExpression,
+        runAt: task.runAt,
+        nextRun,
+      },
+    };
+  }
 
-      this._framework.emit('scheduler:task_failed', {
-        taskId: task.id,
-        error: err.message
-      })
+  _cleanupTask(taskId) {
+    const task = this._tasks.get(taskId);
+    if (!task) return;
+    try {
+      task.scheduleHandle?.stop();
+    } catch {}
+    this._tasks.delete(taskId);
+    this._schedulePersist();
+  }
 
-      if (task.type === 'once' && !task.cronTask) {
-        this._cleanupTask(task.id)
-      }
+  // ============================================================
+  // 持久化（debounce 500ms + 原子写）
+  // ============================================================
+  _schedulePersist() {
+    this._persistDirty = true;
+    if (this._persistTimer) return;
+    this._persistTimer = setTimeout(() => {
+      this._persistTimer = null;
+      if (!this._persistDirty) return;
+      this._persistDirty = false;
+      this._taskStore.saveTasks(Array.from(this._tasks.values()));
+    }, PERSIST_DEBOUNCE_MS);
+    this._persistTimer.unref?.();
+  }
 
-      return { error: err.message }
-    } finally {
-      this._taskStats.running--
+  _flushPersist() {
+    if (this._persistTimer) {
+      clearTimeout(this._persistTimer);
+      this._persistTimer = null;
+    }
+    if (this._persistDirty) {
+      this._persistDirty = false;
+      this._taskStore.saveTasks(Array.from(this._tasks.values()));
     }
   }
 
-  _cleanupTask(taskId) {
-    const task = this._tasks.get(taskId)
-    if (task) {
-      if (task.timer) {
-        clearTimeout(task.timer)
-        task.timer = null
-      }
-      if (task.cronTask) {
-        task.cronTask.cancel()
-        task.cronTask = null
+  // ============================================================
+  // 启动时从持久化恢复（含过期补触发）
+  // ============================================================
+  _loadPersistedTasks() {
+    const savedTasks = this._taskStore.loadTasks();
+    if (!savedTasks || savedTasks.length === 0) return;
+    const now = Date.now();
+
+    for (const saved of savedTasks) {
+      // 已完成的 once 任务不再恢复
+      if (saved.type === 'once' && (saved.runCount || 0) > 0) continue;
+
+      const task = {
+        ...saved,
+        createdAt: saved.createdAt ? new Date(saved.createdAt) : new Date(),
+        lastRun: saved.lastRun ? new Date(saved.lastRun) : null,
+        runAt: saved.runAt ? new Date(saved.runAt) : null,
+        running: false,
+        stopped: false,
+        scheduleHandle: null,
+      };
+
+      try {
+        if (task.type === 'cron' && task.enabled && task.cronExpression) {
+          task.scheduleHandle = new Cron(task.cronExpression, this._cronOptions(task), () => this._onFire(task));
+          this._tasks.set(task.id, task);
+        } else if (task.type === 'once' && task.enabled) {
+          if (!task.runAt) continue;
+          const fireAt = task.runAt.getTime();
+          if (fireAt <= now) {
+            // 已过期：超过 grace period 就丢弃
+            if (now - fireAt > ONCE_EXPIRY_GRACE_MS) {
+              log.warn(` 丢弃过期任务 ${task.name}（已过期 ${Math.round((now - fireAt) / 1000)}s，超出 24h 容忍期）`);
+              continue;
+            }
+            // B4/B5 修复：catchup 也用 croner 调度过去时间，croner 会立即触发；
+            // stop() 能真正取消，update 走 stop()+new Cron() 不会双触发
+            // protect:false 是因为"补触发"不应被 startup 期间的并发阻塞
+            task.scheduleHandle = new Cron(task.runAt, {
+              ...this._cronOptions(task),
+              protect: false,
+            }, () => this._onFire(task));
+            this._tasks.set(task.id, task);
+          } else {
+            // 未来触发
+            task.scheduleHandle = new Cron(task.runAt, this._cronOptions(task), () => this._onFire(task));
+            this._tasks.set(task.id, task);
+          }
+        }
+      } catch (err) {
+        log.error(` 恢复任务失败: ${task.name}`, err.message);
       }
-      this._tasks.delete(taskId)
-      this._saveTasks()
     }
+    log.info(` 已恢复 ${this._tasks.size} 个定时任务`);
+  }
+
+  // ============================================================
+  // 辅助
+  // ============================================================
+  _hasShellTool() {
+    if (!this._framework?.toolRegistry) return false;
+    return this._framework.toolRegistry.has?.('shell_exec') || this._framework.toolRegistry.has?.('shell');
+  }
+
+  _pickShellTool() {
+    const reg = this._framework.toolRegistry;
+    if (reg.has?.('shell_exec')) return 'shell_exec';
+    if (reg.has?.('shell')) return 'shell';
+    return null;
   }
 
   stopAll() {
     for (const task of this._tasks.values()) {
-      this._cancelTask(task)
-    }
-
-    if (this._timer) {
-      clearInterval(this._timer)
-      this._timer = null
+      try { task.scheduleHandle?.stop(); } catch {}
     }
-
-    this._saveTasks()
+    this._tasks.clear();
+    this._flushPersist();
   }
 
   reload(framework) {
-    this._tasks.clear()
-    this._framework = framework
-    this._agent = this._getAgent()
-    this._startScheduler()
-    this._loadPersistedTasks()
+    for (const task of this._tasks.values()) {
+      try { task.scheduleHandle?.stop(); } catch {}
+    }
+    this._tasks.clear();
+    this._schedulerSubAgent = null;
+    // 清掉未触发的 debounce，避免 reload 后旧 timer 用空 _tasks 写盘
+    if (this._persistTimer) {
+      clearTimeout(this._persistTimer);
+      this._persistTimer = null;
+    }
+    this._persistDirty = false;
+    this._llmMutex = Promise.resolve();
+    this._framework = framework;
+    this._agent = this._getAgent();
+    this._loadPersistedTasks();
   }
 
   uninstall(framework) {
-    this.stopAll()
-    this._tasks.clear()
-    this._taskStats = { total: 0, running: 0, completed: 0, failed: 0 }
-    this._framework = null
-    this._agent = null
+    this.stopAll();
+    this._schedulerSubAgent = null;
+    this._framework = null;
+    this._agent = null;
   }
 }
 
-module.exports = SchedulerPlugin
+module.exports = SchedulerPlugin;