@zhin.js/core 1.0.36 → 1.0.38

package/src/ai/cron-engine.ts

@@ -1,337 +0,0 @@
-/**
- * 持久化定时任务
- *
- * 将定时任务持久化到 data/cron-jobs.json，进程重启后自动加载；
- * 触发时以 prompt 调用 ZhinAgent，实现「到点执行 AI 任务」。
- *
- * - 存储：id, cronExpression, prompt, label?, enabled, createdAt
- * - 启动时：读取文件 → 为每条启用的任务创建 Cron → 注册到 CronFeature
- * - CLI / AI 工具：可对持久化任务做 list / add / remove / pause / resume（AI 侧立即生效）
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { Cron } from '../cron.js';
-import { Logger } from '@zhin.js/logger';
-import { ZhinTool } from '../built/tool.js';
-
-const logger = new Logger(null, 'cron-engine');
-
-// ─────────────────────────────────────────────────────────────────────────────
-// 类型与存储路径
-// ─────────────────────────────────────────────────────────────────────────────
-
-export const CRON_JOBS_FILENAME = 'cron-jobs.json';
-
-export interface CronJobRecord {
-  id: string;
-  /** Cron 表达式，5 字段：分 时 日 月 周 */
-  cronExpression: string;
-  /** 触发时发给 AI 的 prompt */
-  prompt: string;
-  /** 可选标签，便于识别 */
-  label?: string;
-  /** 是否启用（暂停的任务不加载） */
-  enabled: boolean;
-  createdAt: number;
-}
-
-export function getCronJobsFilePath(dataDir: string): string {
-  return path.join(dataDir, CRON_JOBS_FILENAME);
-}
-
-export async function readCronJobsFile(dataDir: string): Promise<CronJobRecord[]> {
-  const filePath = getCronJobsFilePath(dataDir);
-  try {
-    const raw = await fs.promises.readFile(filePath, 'utf-8');
-    const data = JSON.parse(raw);
-    if (!Array.isArray(data)) return [];
-    return data;
-  } catch (e: any) {
-    if (e?.code === 'ENOENT') return [];
-    logger.warn('读取定时任务文件失败: ' + (e?.message || String(e)));
-    return [];
-  }
-}
-
-export async function writeCronJobsFile(dataDir: string, jobs: CronJobRecord[]): Promise<void> {
-  const filePath = getCronJobsFilePath(dataDir);
-  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.promises.writeFile(filePath, JSON.stringify(jobs, null, 2), 'utf-8');
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// 持久化引擎：加载文件并注册到 CronFeature
-// ─────────────────────────────────────────────────────────────────────────────
-
-export type CronRunner = (prompt: string, jobId: string) => void | Promise<void>;
-
-export type AddCronFn = (cron: Cron) => () => void;
-
-export interface PersistentCronEngineOptions {
-  dataDir: string;
-  addCron: AddCronFn;
-  runner: CronRunner;
-}
-
-export class PersistentCronEngine {
-  private options: PersistentCronEngineOptions;
-  /** jobId -> dispose */
-  private disposes = new Map<string, () => void>();
-
-  constructor(options: PersistentCronEngineOptions) {
-    this.options = options;
-  }
-
-  getDataDir(): string {
-    return this.options.dataDir;
-  }
-
-  /**
-   * 从文件加载任务并注册到 CronFeature；仅加载 enabled 的任务。
-   */
-  load(): void {
-    const { dataDir, addCron, runner } = this.options;
-    readCronJobsFile(dataDir).then((jobs) => {
-      for (const job of jobs) {
-        if (!job.enabled) continue;
-        this.registerOne(job, addCron, runner);
-      }
-      if (jobs.filter((j) => j.enabled).length > 0) {
-        logger.info(`已加载 ${this.disposes.size} 个持久化定时任务`);
-      }
-    }).catch((e) => {
-      logger.warn('加载持久化定时任务失败: ' + (e?.message || String(e)));
-    });
-  }
-
-  private registerOne(
-    job: CronJobRecord,
-    addCron: AddCronFn,
-    runner: CronRunner,
-  ): void {
-    const { prompt, id: jobId, cronExpression } = job;
-    try {
-      const cron = new Cron(cronExpression, async () => {
-        await runner(prompt, jobId);
-      });
-      cron.id = jobId;
-      const dispose = addCron(cron);
-      this.disposes.set(jobId, dispose);
-    } catch (e: any) {
-      logger.warn(`定时任务加载失败 [${jobId}]: ${e?.message || String(e)}`);
-    }
-  }
-
-  /**
-   * 列出所有持久化任务（从文件读取）
-   */
-  async listJobs(): Promise<CronJobRecord[]> {
-    return readCronJobsFile(this.options.dataDir);
-  }
-
-  /**
-   * 添加持久化任务并立即生效
-   */
-  async addJob(record: Omit<CronJobRecord, 'createdAt'> & { createdAt?: number }): Promise<CronJobRecord> {
-    const jobs = await readCronJobsFile(this.options.dataDir);
-    const full: CronJobRecord = {
-      ...record,
-      createdAt: record.createdAt ?? Date.now(),
-      enabled: record.enabled ?? true,
-    };
-    jobs.push(full);
-    await writeCronJobsFile(this.options.dataDir, jobs);
-    if (full.enabled) {
-      this.registerOne(full, this.options.addCron, this.options.runner);
-    }
-    return full;
-  }
-
-  /**
-   * 删除持久化任务并立即生效
-   */
-  async removeJob(id: string): Promise<boolean> {
-    const jobs = await readCronJobsFile(this.options.dataDir);
-    const next = jobs.filter((j) => j.id !== id);
-    if (next.length === jobs.length) return false;
-    await writeCronJobsFile(this.options.dataDir, next);
-    const dispose = this.disposes.get(id);
-    if (dispose) {
-      dispose();
-      this.disposes.delete(id);
-    }
-    return true;
-  }
-
-  /**
-   * 暂停任务（不删除，停止调度）
-   */
-  async pauseJob(id: string): Promise<boolean> {
-    const jobs = await readCronJobsFile(this.options.dataDir);
-    const j = jobs.find((x) => x.id === id);
-    if (!j) return false;
-    j.enabled = false;
-    await writeCronJobsFile(this.options.dataDir, jobs);
-    const dispose = this.disposes.get(id);
-    if (dispose) {
-      dispose();
-      this.disposes.delete(id);
-    }
-    return true;
-  }
-
-  /**
-   * 恢复已暂停的任务
-   */
-  async resumeJob(id: string): Promise<boolean> {
-    const jobs = await readCronJobsFile(this.options.dataDir);
-    const j = jobs.find((x) => x.id === id);
-    if (!j) return false;
-    j.enabled = true;
-    await writeCronJobsFile(this.options.dataDir, jobs);
-    this.registerOne(j, this.options.addCron, this.options.runner);
-    return true;
-  }
-
-  /**
-   * 卸载所有由本引擎注册的定时任务（用于 dispose）
-   */
-  unload(): void {
-    for (const dispose of this.disposes.values()) {
-      try {
-        dispose();
-      } catch (_) {}
-    }
-    this.disposes.clear();
-  }
-}
-
-/**
- * 生成唯一 ID（用于 CLI / AI 添加时）
- */
-export function generateCronJobId(): string {
-  return `cron_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// 供 AI 工具使用的 Cron 管理器引用（init 中设置）
-// ─────────────────────────────────────────────────────────────────────────────
-
-export interface CronManager {
-  cronFeature: { getStatus(): Array<{ expression: string; running: boolean; nextExecution: Date | null; plugin: string }> };
-  engine: PersistentCronEngine | null;
-}
-
-let cronManager: CronManager | null = null;
-
-export function setCronManager(m: CronManager | null): void {
-  cronManager = m;
-}
-
-export function getCronManager(): CronManager | null {
-  return cronManager;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// AI 可调用的定时任务管理工具
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function createCronTools(): ZhinTool[] {
-  const listTool = new ZhinTool('cron_list')
-    .desc('列出所有定时任务：包括插件注册的内存任务与持久化任务（持久化任务有 id，可用于 cron_remove/cron_pause/cron_resume）')
-    .keyword('定时任务', 'cron', '计划任务', '任务列表')
-    .tag('cron', 'schedule')
-    .execute(async () => {
-      const m = getCronManager();
-      if (!m) {
-        return { error: '定时任务服务不可用' };
-      }
-      const memory = m.cronFeature.getStatus().map((s) => ({
-        type: 'memory' as const,
-        expression: s.expression,
-        running: s.running,
-        nextExecution: s.nextExecution?.toISOString() ?? null,
-        plugin: s.plugin,
-      }));
-      const persistent = m.engine
-        ? (await m.engine.listJobs()).map((j) => ({
-            type: 'persistent' as const,
-            id: j.id,
-            cronExpression: j.cronExpression,
-            prompt: j.prompt,
-            label: j.label,
-            enabled: j.enabled,
-            createdAt: j.createdAt,
-          }))
-        : [];
-      return { memory, persistent };
-    });
-
-  const addTool = new ZhinTool('cron_add')
-    .desc('添加一条持久化定时任务：到点由 AI 执行指定 prompt，重启后仍保留')
-    .keyword('添加定时', '新建定时任务', 'cron add')
-    .tag('cron', 'schedule')
-    .param('cron_expression', { type: 'string', description: 'Cron 表达式，如 "0 9 * * *" 表示每天 9:00' }, true)
-    .param('prompt', { type: 'string', description: '到点触发时发给 AI 的提示词' }, true)
-    .param('label', { type: 'string', description: '可选标签，便于识别' })
-    .execute(async (args) => {
-      const m = getCronManager();
-      if (!m?.engine) {
-        return { error: '持久化定时任务引擎不可用' };
-      }
-      const id = generateCronJobId();
-      const job = await m.engine.addJob({
-        id,
-        cronExpression: args.cron_expression as string,
-        prompt: args.prompt as string,
-        label: args.label as string | undefined,
-        enabled: true,
-      });
-      return { success: true, id: job.id, message: '已添加并立即生效' };
-    });
-
-  const removeTool = new ZhinTool('cron_remove')
-    .desc('按 id 删除一条持久化定时任务')
-    .keyword('删除定时', '取消定时', 'cron remove')
-    .tag('cron', 'schedule')
-    .param('id', { type: 'string', description: '任务 ID（cron_list 中 persistent 的 id）' }, true)
-    .execute(async (args) => {
-      const m = getCronManager();
-      if (!m?.engine) {
-        return { error: '持久化定时任务引擎不可用' };
-      }
-      const ok = await m.engine.removeJob(args.id as string);
-      return ok ? { success: true, message: '已删除' } : { error: '未找到该任务' };
-    });
-
-  const pauseTool = new ZhinTool('cron_pause')
-    .desc('暂停一条持久化定时任务（不删除，可 cron_resume 恢复）')
-    .keyword('暂停定时', 'cron pause')
-    .tag('cron', 'schedule')
-    .param('id', { type: 'string', description: '任务 ID' }, true)
-    .execute(async (args) => {
-      const m = getCronManager();
-      if (!m?.engine) {
-        return { error: '持久化定时任务引擎不可用' };
-      }
-      const ok = await m.engine.pauseJob(args.id as string);
-      return ok ? { success: true, message: '已暂停' } : { error: '未找到该任务' };
-    });
-
-  const resumeTool = new ZhinTool('cron_resume')
-    .desc('恢复已暂停的持久化定时任务')
-    .keyword('恢复定时', 'cron resume')
-    .tag('cron', 'schedule')
-    .param('id', { type: 'string', description: '任务 ID' }, true)
-    .execute(async (args) => {
-      const m = getCronManager();
-      if (!m?.engine) {
-        return { error: '持久化定时任务引擎不可用' };
-      }
-      const ok = await m.engine.resumeJob(args.id as string);
-      return ok ? { success: true, message: '已恢复' } : { error: '未找到该任务' };
-    });
-
-  return [listTool, addTool, removeTool, pauseTool, resumeTool];
-}

package/src/ai/follow-up.ts

@@ -1,357 +0,0 @@
-/**
- * FollowUpStore — 定时跟进任务的持久化存储
- *
- * 解决纯 setTimeout 重启即丢失的问题：
- *   1. 创建任务时同步写入数据库
- *   2. 执行完成 / 过期后从数据库中删除
- *   3. 机器人启动时从数据库加载所有未完成任务，重新挂定时器
- *   4. 同一会话创建新任务时，自动取消旧的 pending 任务（防止重复提醒）
- *
- *   ai_followups 表：
- *   ┌──────────────────────────────────────────────────────────────────┐
- *   │ id (PK)  | session_id | platform | sender_id | scene_id        │
- *   │          | message    | fire_at  | created_at | status          │
- *   └──────────────────────────────────────────────────────────────────┘
- */
-
-import { Logger } from '@zhin.js/logger';
-
-const logger = new Logger(null, 'FollowUp');
-
-// ============================================================================
-// 数据库模型
-// ============================================================================
-
-export const AI_FOLLOWUP_MODEL = {
-  session_id: { type: 'text' as const, nullable: false },
-  platform: { type: 'text' as const, nullable: false },
-  bot_id: { type: 'text' as const, nullable: false },
-  sender_id: { type: 'text' as const, nullable: false },
-  scene_id: { type: 'text' as const, nullable: false },
-  scene_type: { type: 'text' as const, nullable: false },
-  message: { type: 'text' as const, nullable: false },
-  /** 触发时间戳 (ms) */
-  fire_at: { type: 'integer' as const, nullable: false },
-  created_at: { type: 'integer' as const, default: 0 },
-  /** pending | fired | cancelled */
-  status: { type: 'text' as const, default: 'pending' },
-};
-
-// ============================================================================
-// 类型
-// ============================================================================
-
-export interface FollowUpRecord {
-  id?: number;
-  session_id: string;
-  platform: string;
-  bot_id: string;
-  sender_id: string;
-  scene_id: string;
-  scene_type: string;
-  message: string;
-  fire_at: number;
-  created_at: number;
-  status: string;
-}
-
-/**
- * 数据库模型接口（与 RelatedModel 的链式查询 API 对齐）
- */
-interface DbModel {
-  select(...fields: string[]): any;  // 返回 Selection (thenable, 支持 .where())
-  create(data: Record<string, any>): Promise<any>;
-  update(data: Partial<any>): any;   // 返回 Updation (thenable, 支持 .where())
-  delete(condition: Record<string, any>): any; // 返回 Deletion (thenable, 支持 .where())
-}
-
-/**
- * 发送提醒的回调函数
- *
- * 由 ZhinAgent 在 init 阶段注入，负责把提醒消息发到正确的会话。
- */
-export type FollowUpSender = (record: FollowUpRecord) => Promise<void>;
-
-// ============================================================================
-// Store 接口
-// ============================================================================
-
-interface IFollowUpStore {
-  create(record: Omit<FollowUpRecord, 'id'>): Promise<FollowUpRecord>;
-  markFired(id: number): Promise<void>;
-  cancel(id: number): Promise<void>;
-  getPending(): Promise<FollowUpRecord[]>;
-  getPendingBySession(sessionId: string): Promise<FollowUpRecord[]>;
-  dispose(): void;
-}
-
-// ============================================================================
-// 内存实现
-// ============================================================================
-
-class MemoryFollowUpStore implements IFollowUpStore {
-  private records: FollowUpRecord[] = [];
-  private nextId = 1;
-
-  async create(record: Omit<FollowUpRecord, 'id'>): Promise<FollowUpRecord> {
-    const full: FollowUpRecord = { ...record, id: this.nextId++ };
-    this.records.push(full);
-    return full;
-  }
-
-  async markFired(id: number): Promise<void> {
-    const r = this.records.find(r => r.id === id);
-    if (r) r.status = 'fired';
-  }
-
-  async cancel(id: number): Promise<void> {
-    const r = this.records.find(r => r.id === id);
-    if (r) r.status = 'cancelled';
-  }
-
-  async getPending(): Promise<FollowUpRecord[]> {
-    return this.records.filter(r => r.status === 'pending');
-  }
-
-  async getPendingBySession(sessionId: string): Promise<FollowUpRecord[]> {
-    return this.records.filter(r => r.status === 'pending' && r.session_id === sessionId);
-  }
-
-  dispose(): void {
-    this.records = [];
-  }
-}
-
-// ============================================================================
-// 数据库实现
-// ============================================================================
-
-class DatabaseFollowUpStore implements IFollowUpStore {
-  constructor(private model: DbModel) {}
-
-  async create(record: Omit<FollowUpRecord, 'id'>): Promise<FollowUpRecord> {
-    const created = await this.model.create(record);
-    return { ...record, id: created.id ?? created };
-  }
-
-  async markFired(id: number): Promise<void> {
-    await this.model.update({ status: 'fired' }).where({ id });
-  }
-
-  async cancel(id: number): Promise<void> {
-    await this.model.update({ status: 'cancelled' }).where({ id });
-  }
-
-  async getPending(): Promise<FollowUpRecord[]> {
-    return this.model.select().where({ status: 'pending' }) as Promise<FollowUpRecord[]>;
-  }
-
-  async getPendingBySession(sessionId: string): Promise<FollowUpRecord[]> {
-    return this.model.select().where({ status: 'pending', session_id: sessionId }) as Promise<FollowUpRecord[]>;
-  }
-
-  dispose(): void {}
-}
-
-// ============================================================================
-// FollowUpManager
-// ============================================================================
-
-export class FollowUpManager {
-  private store: IFollowUpStore;
-  /** 内存中活跃的定时器: recordId → timer */
-  private timers: Map<number, ReturnType<typeof setTimeout>> = new Map();
-  private sender: FollowUpSender | null = null;
-
-  constructor() {
-    this.store = new MemoryFollowUpStore();
-  }
-
-  /** 注入消息发送回调 */
-  setSender(sender: FollowUpSender): void {
-    this.sender = sender;
-  }
-
-  /** 升级到数据库存储 */
-  upgradeToDatabase(model: DbModel): void {
-    const old = this.store;
-    this.store = new DatabaseFollowUpStore(model);
-    old.dispose();
-    logger.debug('FollowUpManager: 已升级到数据库存储');
-  }
-
-  /**
-   * 创建一个跟进任务
-   *
-   * 重要：同一会话的旧 pending 任务会被自动取消，防止重复提醒。
-   *
-   * @returns 人类可读的确认文本
-   */
-  async schedule(params: {
-    sessionId: string;
-    platform: string;
-    botId: string;
-    senderId: string;
-    sceneId: string;
-    sceneType: string;
-    message: string;
-    delayMinutes: number;
-  }): Promise<string> {
-    const { sessionId, platform, botId, senderId, sceneId, sceneType, message, delayMinutes } = params;
-
-    // ── 详细参数日志（方便排查问题） ──
-    logger.debug(`[跟进] 收到请求: delay_minutes=${delayMinutes}, message="${message}", session=${sessionId}`);
-
-    // 限制最大延迟 7 天
-    const maxDelay = 7 * 24 * 60;
-    const actualDelay = Math.min(Math.max(delayMinutes, 1), maxDelay);
-    const delayMs = actualDelay * 60 * 1000;
-    const fireAt = Date.now() + delayMs;
-
-    // ── 自动取消同一会话的旧 pending 任务 ──
-    const existingPending = await this.store.getPendingBySession(sessionId);
-    if (existingPending.length > 0) {
-      for (const old of existingPending) {
-        if (old.id != null) {
-          // 取消数据库记录
-          await this.store.cancel(old.id);
-          // 清除内存中的定时器
-          const timer = this.timers.get(old.id);
-          if (timer) {
-            clearTimeout(timer);
-            this.timers.delete(old.id);
-          }
-          logger.debug(`[跟进] 自动取消旧任务: id=${old.id}, "${old.message}"`);
-        }
-      }
-    }
-
-    const record = await this.store.create({
-      session_id: sessionId,
-      platform,
-      bot_id: botId,
-      sender_id: senderId,
-      scene_id: sceneId,
-      scene_type: sceneType,
-      message,
-      fire_at: fireAt,
-      created_at: Date.now(),
-      status: 'pending',
-    });
-
-    // 挂定时器
-    this.scheduleTimer(record);
-
-    const readableTime = actualDelay >= 1440
-      ? `${(actualDelay / 1440).toFixed(1)} 天后`
-      : actualDelay >= 60
-      ? `${(actualDelay / 60).toFixed(1)} 小时后`
-      : `${actualDelay} 分钟后`;
-
-    // 精确触发时间（方便日志对照）
-    const fireDate = new Date(fireAt);
-    const fireTimeStr = fireDate.toLocaleString('zh-CN', { hour12: false });
-
-    logger.debug(`[跟进] 已创建: id=${record.id}, delay=${actualDelay}分钟(${delayMs}ms), 触发时间=${fireTimeStr}, "${message}"`);
-    return `✅ 已安排提醒，将在 ${readableTime}（${fireTimeStr}）提醒你：${message}`;
-  }
-
-  /**
-   * 取消指定会话的所有 pending 任务
-   */
-  async cancelBySession(sessionId: string): Promise<number> {
-    const pending = await this.store.getPendingBySession(sessionId);
-    let count = 0;
-    for (const record of pending) {
-      if (record.id != null) {
-        await this.store.cancel(record.id);
-        const timer = this.timers.get(record.id);
-        if (timer) {
-          clearTimeout(timer);
-          this.timers.delete(record.id);
-        }
-        count++;
-      }
-    }
-    if (count > 0) {
-      logger.debug(`[跟进] 已取消 ${count} 个待执行任务 (session=${sessionId})`);
-    }
-    return count;
-  }
-
-  /**
-   * 启动时从数据库恢复所有未完成的跟进任务
-   */
-  async restore(): Promise<number> {
-    const pending = await this.store.getPending();
-    const now = Date.now();
-    let restored = 0;
-
-    for (const record of pending) {
-      if (record.fire_at <= now) {
-        // 已过期但未执行 → 立即触发（延迟 2 秒，等系统完全就绪）
-        const overdueSec = Math.round((now - record.fire_at) / 1000);
-        logger.debug(`[跟进恢复] id=${record.id} 已过期 ${overdueSec}s，立即触发`);
-        this.scheduleTimerWithDelay(record, 2000);
-        restored++;
-      } else {
-        // 还没到时间 → 重新挂定时器
-        this.scheduleTimer(record);
-        const remainMs = record.fire_at - now;
-        const remainMin = (remainMs / 60_000).toFixed(1);
-        logger.debug(`[跟进恢复] id=${record.id} 剩余 ${remainMin} 分钟, "${record.message}"`);
-        restored++;
-      }
-    }
-
-    if (restored > 0) {
-      logger.info(`[跟进恢复] 共恢复 ${restored} 个待执行任务`);
-    }
-    return restored;
-  }
-
-  /**
-   * 为一条记录挂定时器
-   */
-  private scheduleTimer(record: FollowUpRecord): void {
-    const delay = Math.max(record.fire_at - Date.now(), 0);
-    this.scheduleTimerWithDelay(record, delay);
-  }
-
-  private scheduleTimerWithDelay(record: FollowUpRecord, delayMs: number): void {
-    if (!record.id) return;
-
-    // 清除旧定时器（如果有）
-    const existing = this.timers.get(record.id);
-    if (existing) clearTimeout(existing);
-
-    const timer = setTimeout(async () => {
-      try {
-        this.timers.delete(record.id!);
-
-        // 发送提醒
-        if (this.sender) {
-          await this.sender(record);
-          logger.info(`[跟进提醒] 已发送: id=${record.id}, "${record.message}"`);
-        } else {
-          logger.warn(`[跟进提醒] 无法发送 (sender 未注入): id=${record.id}`);
-        }
-
-        // 标记完成
-        await this.store.markFired(record.id!);
-      } catch (e) {
-        logger.warn(`[跟进提醒] 发送失败: id=${record.id}`, e);
-      }
-    }, delayMs);
-
-    this.timers.set(record.id, timer);
-  }
-
-  dispose(): void {
-    for (const timer of this.timers.values()) {
-      clearTimeout(timer);
-    }
-    this.timers.clear();
-    this.store.dispose();
-  }
-}