@zhin.js/core 1.0.32 → 1.0.34

package/src/component.ts

@@ -470,34 +470,38 @@ export async function renderComponent<P = any>(component: Component<P>, template
     const props = getProps(component, template, context);
     return component(props, context);
 }
-// 渲染函数 - 支持新的组件系统
+// 渲染函数 - 支持新的组件系统；无组件时仍对内容执行 ${...} 模板编译，与有组件时行为一致
 export async function renderComponents(
     componentMap: Map<string, Component>,
     options: SendOptions,
     customContext?: ComponentContext
 ): Promise<SendOptions> {
-    if (!componentMap.size) return options;
+    const template = typeof options.content === 'string'
+        ? options.content
+        : segment.toString(options.content as MessageElement);
 
-    const components = [...Array.from(componentMap.values()), Fetch, Fragment];
-
-    // 创建根上下文
     const rootContext = customContext || createComponentContext(
         options,
         undefined,
-        typeof options.content === 'string' ? options.content : segment.toString(options.content as MessageElement)
+        template
     );
 
-    // 实现渲染逻辑
-    const renderWithContext = async (template: string, context: ComponentContext): Promise<SendContent> => {
-        let result = template;
+    if (!componentMap.size) {
+        const compiled = rootContext.compile(template);
+        return {
+            ...options,
+            content: typeof compiled === 'string' ? segment.from(compiled) : (compiled as MessageElement[]),
+        };
+    }
+
+    const components = [...Array.from(componentMap.values()), Fetch, Fragment];
+
+    const renderWithContext = async (tpl: string, context: ComponentContext): Promise<SendContent> => {
+        let result = context.compile(tpl);
         let hasChanges = true;
         let iterations = 0;
-        const maxIterations = 10; // 防止无限循环
+        const maxIterations = 10;
 
-        // 编译模板
-        result = context.compile(result);
-
-        // 递归处理所有组件，直到没有更多组件需要渲染
         while (hasChanges && iterations < maxIterations) {
             hasChanges = false;
             iterations++;
@@ -505,22 +509,21 @@ export async function renderComponents(
             for (const comp of components) {
                 const match = matchComponent(comp, result);
                 if (match) {
-                    // 创建组件特定的上下文
                     const componentContext = createComponentContext(
                         context.props,
                         context,
                         result
                     );
                     let SendContent;
-                    try{
+                    try {
                         SendContent = await renderComponent(comp, match, componentContext);
-                    }catch(error){
-                        SendContent = `[${comp.name} Error: ${(error as Error)?.message||String(error)}]`
+                    } catch (error) {
+                        SendContent = `[${comp.name} Error: ${(error as Error)?.message || String(error)}]`;
                     }
                     const renderedString = typeof SendContent === 'string' ? SendContent : segment.toString(SendContent as MessageElement);
                     result = result.replace(match, renderedString);
                     hasChanges = true;
-                    break; // 处理一个组件后重新开始循环
+                    break;
                 }
             }
         }
@@ -528,20 +531,18 @@ export async function renderComponents(
         return result;
     };
 
-    // 更新根上下文的渲染函数
-    rootContext.render = async (template: string, context?: Partial<ComponentContext>) => {
-        return await renderWithContext(template, rootContext);
+    rootContext.render = async (tpl: string, context?: Partial<ComponentContext>) => {
+        return await renderWithContext(tpl, rootContext);
     };
 
-    // 渲染模板
     const output = await renderWithContext(rootContext.root, rootContext);
     const content = typeof output === 'string' ? segment.from(output) : output as MessageElement[];
 
-        return {
-            ...options,
-            content
-        };
-    }
+    return {
+        ...options,
+        content,
+    };
+}
 
 // 内置组件
 export const Fragment = defineComponent(async (props: { children?: SendContent }, context: ComponentContext) => {

package/src/index.ts

@@ -33,6 +33,7 @@ export * from './types.js'
 export * from './utils.js'
 export * from './errors.js'  // 导出错误处理系统
 export * from './cron.js'
+export * from './scheduler/index.js'
 export * from '@zhin.js/database'
 export * from '@zhin.js/logger'
 // 只导出 Schema 类，避免与 utils.js 的 isEmpty 冲突

package/src/scheduler/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Scheduler module — at / every / cron + heartbeat
+ */
+
+export type {
+  Schedule,
+  JobPayload,
+  JobState,
+  ScheduledJob,
+  JobStore,
+  JobCallback,
+  AddJobOptions,
+  IScheduler,
+} from './types.js';
+export { Scheduler } from './scheduler.js';
+export type { SchedulerOptions } from './scheduler.js';
+
+import type { Scheduler } from './scheduler.js';
+
+let schedulerInstance: Scheduler | null = null;
+
+export function getScheduler(): Scheduler | null {
+  return schedulerInstance;
+}
+
+export function setScheduler(s: Scheduler | null): void {
+  schedulerInstance = s;
+}

package/src/scheduler/scheduler.ts

@@ -0,0 +1,372 @@
+/**
+ * Unified scheduler — at / every / cron + heartbeat
+ *
+ * 持久化到 data/scheduler-jobs.json，支持单次 at、间隔 every、cron 表达式，
+ * 以及可选的 HEARTBEAT.md 周期检查。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomUUID } from 'crypto';
+import { Cron as Croner } from 'croner';
+import type {
+  Schedule,
+  JobPayload,
+  ScheduledJob,
+  JobStore,
+  JobCallback,
+  AddJobOptions,
+  IScheduler,
+} from './types.js';
+import { Logger } from '@zhin.js/logger';
+
+const logger = new Logger(null, 'scheduler');
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30 * 60 * 1000;
+
+const HEARTBEAT_PROMPT = `Read HEARTBEAT.md in your workspace (if it exists).
+Follow any instructions or tasks listed there.
+If nothing needs attention, reply with just: HEARTBEAT_OK`;
+
+function nowMs(): number {
+  return Date.now();
+}
+
+function computeNextRun(schedule: Schedule, currentMs: number): number | undefined {
+  if (schedule.kind === 'at') {
+    return schedule.atMs != null && schedule.atMs > currentMs ? schedule.atMs : undefined;
+  }
+  if (schedule.kind === 'every') {
+    if (schedule.everyMs == null || schedule.everyMs <= 0) return undefined;
+    return currentMs + schedule.everyMs;
+  }
+  if (schedule.kind === 'cron' && schedule.expr) {
+    try {
+      const job = new Croner(schedule.expr, { paused: true, timezone: schedule.tz });
+      const next = job.nextRun();
+      job.stop();
+      return next ? next.getTime() : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+function createStore(): JobStore {
+  return { version: 1, jobs: [] };
+}
+
+function isHeartbeatEmpty(content: string | null): boolean {
+  if (!content) return true;
+  const skipPatterns = new Set(['- [ ]', '* [ ]', '- [x]', '* [x]']);
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('<!--') || skipPatterns.has(trimmed)) continue;
+    return false;
+  }
+  return true;
+}
+
+export interface SchedulerOptions {
+  storePath: string;
+  workspace: string;
+  onJob?: JobCallback;
+  heartbeatEnabled?: boolean;
+  heartbeatIntervalMs?: number;
+}
+
+export class Scheduler implements IScheduler {
+  private storePath: string;
+  private workspace: string;
+  private onJob: JobCallback | null = null;
+  private store: JobStore | null = null;
+  private timerTimeout: ReturnType<typeof setTimeout> | null = null;
+  private _running = false;
+  private heartbeatEnabled: boolean;
+  private heartbeatIntervalMs: number;
+  private heartbeatJobId: string | null = null;
+
+  constructor(options: SchedulerOptions) {
+    this.storePath = options.storePath;
+    this.workspace = options.workspace;
+    this.onJob = options.onJob ?? null;
+    this.heartbeatEnabled = options.heartbeatEnabled ?? true;
+    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+  }
+
+  private loadStore(): JobStore {
+    if (this.store) return this.store;
+    if (fs.existsSync(this.storePath)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(this.storePath, 'utf-8'));
+        const jobs: ScheduledJob[] = (data.jobs || []).map((j: any) => ({
+          id: j.id,
+          name: j.name,
+          enabled: j.enabled ?? true,
+          schedule: {
+            kind: j.schedule?.kind ?? 'cron',
+            atMs: j.schedule?.atMs,
+            everyMs: j.schedule?.everyMs,
+            expr: j.schedule?.expr,
+            tz: j.schedule?.tz,
+          },
+          payload: {
+            kind: j.payload?.kind ?? 'agent_turn',
+            message: j.payload?.message ?? '',
+            deliver: j.payload?.deliver ?? false,
+            channel: j.payload?.channel,
+            to: j.payload?.to,
+          },
+          state: {
+            nextRunAtMs: j.state?.nextRunAtMs,
+            lastRunAtMs: j.state?.lastRunAtMs,
+            lastStatus: j.state?.lastStatus,
+            lastError: j.state?.lastError,
+          },
+          createdAtMs: j.createdAtMs ?? 0,
+          updatedAtMs: j.updatedAtMs ?? 0,
+          deleteAfterRun: j.deleteAfterRun ?? false,
+        }));
+        this.store = { version: data.version ?? 1, jobs };
+      } catch (e) {
+        logger.warn('Failed to load scheduler store', e);
+        this.store = createStore();
+      }
+    } else {
+      this.store = createStore();
+    }
+    return this.store;
+  }
+
+  private saveStore(): void {
+    if (!this.store) return;
+    const dir = path.dirname(this.storePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const persistJobs = this.store.jobs.filter(j => j.id !== this.heartbeatJobId);
+    const data = {
+      version: this.store.version,
+      jobs: persistJobs.map(j => ({
+        id: j.id,
+        name: j.name,
+        enabled: j.enabled,
+        schedule: j.schedule,
+        payload: j.payload,
+        state: j.state,
+        createdAtMs: j.createdAtMs,
+        updatedAtMs: j.updatedAtMs,
+        deleteAfterRun: j.deleteAfterRun,
+      })),
+    };
+    fs.writeFileSync(this.storePath, JSON.stringify(data, null, 2));
+  }
+
+  async start(): Promise<void> {
+    this._running = true;
+    this.loadStore();
+    if (this.heartbeatEnabled) this.addHeartbeatJob();
+    this.recomputeNextRuns();
+    this.saveStore();
+    this.armTimer();
+    logger.info({ jobs: this.store?.jobs.length ?? 0 }, 'Scheduler started');
+  }
+
+  stop(): void {
+    this._running = false;
+    if (this.timerTimeout) {
+      clearTimeout(this.timerTimeout);
+      this.timerTimeout = null;
+    }
+  }
+
+  private addHeartbeatJob(): void {
+    if (!this.store) return;
+    const existing = this.store.jobs.find(j => j.payload.kind === 'heartbeat');
+    if (existing) {
+      this.heartbeatJobId = existing.id;
+      return;
+    }
+    const now = nowMs();
+    const job: ScheduledJob = {
+      id: `heartbeat-${randomUUID().slice(0, 8)}`,
+      name: 'Heartbeat',
+      enabled: true,
+      schedule: { kind: 'every', everyMs: this.heartbeatIntervalMs },
+      payload: { kind: 'heartbeat', message: HEARTBEAT_PROMPT, deliver: false },
+      state: { nextRunAtMs: now + this.heartbeatIntervalMs },
+      createdAtMs: now,
+      updatedAtMs: now,
+      deleteAfterRun: false,
+    };
+    this.heartbeatJobId = job.id;
+    this.store.jobs.push(job);
+    logger.info({ intervalMs: this.heartbeatIntervalMs }, 'Heartbeat job added');
+  }
+
+  private recomputeNextRuns(): void {
+    if (!this.store) return;
+    const now = nowMs();
+    for (const job of this.store.jobs) {
+      if (job.enabled) job.state.nextRunAtMs = computeNextRun(job.schedule, now);
+    }
+  }
+
+  private getNextWakeMs(): number | undefined {
+    if (!this.store) return undefined;
+    const times = this.store.jobs
+      .filter(j => j.enabled && j.state.nextRunAtMs != null)
+      .map(j => j.state.nextRunAtMs!);
+    return times.length > 0 ? Math.min(...times) : undefined;
+  }
+
+  private armTimer(): void {
+    if (this.timerTimeout) {
+      clearTimeout(this.timerTimeout);
+      this.timerTimeout = null;
+    }
+    const nextWake = this.getNextWakeMs();
+    if (nextWake == null || !this._running) return;
+    const delayMs = Math.max(0, nextWake - nowMs());
+    this.timerTimeout = setTimeout(async () => {
+      if (this._running) await this.onTimer();
+    }, delayMs);
+  }
+
+  private async onTimer(): Promise<void> {
+    if (!this.store) return;
+    const now = nowMs();
+    const dueJobs = this.store.jobs.filter(
+      j => j.enabled && j.state.nextRunAtMs != null && now >= j.state.nextRunAtMs!
+    );
+    for (const job of dueJobs) await this.executeJob(job);
+    this.saveStore();
+    this.armTimer();
+  }
+
+  private async executeJob(job: ScheduledJob): Promise<void> {
+    const startMs = nowMs();
+    if (job.payload.kind === 'heartbeat') {
+      const shouldRun = this.checkHeartbeatFile();
+      if (!shouldRun) {
+        job.state.lastStatus = 'skipped';
+        job.state.lastRunAtMs = startMs;
+        job.updatedAtMs = nowMs();
+        job.state.nextRunAtMs = computeNextRun(job.schedule, nowMs());
+        return;
+      }
+    }
+    logger.info({ jobId: job.id, name: job.name }, 'Scheduler: executing job');
+    try {
+      if (this.onJob) await this.onJob(job);
+      job.state.lastStatus = 'ok';
+      job.state.lastError = undefined;
+      logger.info({ jobId: job.id, name: job.name }, 'Scheduler: job completed');
+    } catch (error) {
+      job.state.lastStatus = 'error';
+      job.state.lastError = String(error);
+      logger.error({ jobId: job.id, name: job.name, lastError: String(error) }, 'Scheduler: job failed');
+    }
+    job.state.lastRunAtMs = startMs;
+    job.updatedAtMs = nowMs();
+    if (job.schedule.kind === 'at') {
+      if (job.deleteAfterRun && this.store) {
+        this.store.jobs = this.store.jobs.filter(j => j.id !== job.id);
+      } else {
+        job.enabled = false;
+        job.state.nextRunAtMs = undefined;
+      }
+    } else {
+      job.state.nextRunAtMs = computeNextRun(job.schedule, nowMs());
+    }
+  }
+
+  private checkHeartbeatFile(): boolean {
+    const heartbeatPath = path.join(this.workspace, 'HEARTBEAT.md');
+    if (!fs.existsSync(heartbeatPath)) return false;
+    try {
+      const content = fs.readFileSync(heartbeatPath, 'utf-8');
+      return !isHeartbeatEmpty(content);
+    } catch {
+      return false;
+    }
+  }
+
+  listJobs(): ScheduledJob[] {
+    const store = this.loadStore();
+    return store.jobs
+      .filter(j => j.id !== this.heartbeatJobId)
+      .sort((a, b) => (a.state.nextRunAtMs ?? Infinity) - (b.state.nextRunAtMs ?? Infinity));
+  }
+
+  addJob(options: AddJobOptions): ScheduledJob {
+    const store = this.loadStore();
+    const now = nowMs();
+    const job: ScheduledJob = {
+      id: randomUUID().slice(0, 8),
+      name: options.name,
+      enabled: options.enabled ?? true,
+      schedule: options.schedule,
+      payload: options.payload,
+      state: { nextRunAtMs: computeNextRun(options.schedule, now) },
+      createdAtMs: now,
+      updatedAtMs: now,
+      deleteAfterRun: options.deleteAfterRun ?? false,
+    };
+    store.jobs.push(job);
+    this.saveStore();
+    this.armTimer();
+    logger.info({ jobId: job.id, name: job.name }, 'Scheduler: added job');
+    return job;
+  }
+
+  removeJob(jobId: string): boolean {
+    const store = this.loadStore();
+    const before = store.jobs.length;
+    store.jobs = store.jobs.filter(j => j.id !== jobId);
+    const removed = store.jobs.length < before;
+    if (removed) {
+      this.saveStore();
+      this.armTimer();
+      logger.info({ jobId }, 'Scheduler: removed job');
+    }
+    return removed;
+  }
+
+  enableJob(jobId: string, enabled: boolean = true): boolean {
+    const store = this.loadStore();
+    const job = store.jobs.find(j => j.id === jobId);
+    if (!job) return false;
+    job.enabled = enabled;
+    job.updatedAtMs = nowMs();
+    job.state.nextRunAtMs = enabled ? computeNextRun(job.schedule, nowMs()) : undefined;
+    this.saveStore();
+    this.armTimer();
+    return true;
+  }
+
+  async runJob(jobId: string): Promise<void> {
+    const store = this.loadStore();
+    const job = store.jobs.find(j => j.id === jobId);
+    if (job) {
+      await this.executeJob(job);
+      this.saveStore();
+      this.armTimer();
+    }
+  }
+
+  status(): { running: boolean; jobCount: number; nextWakeAt?: number } {
+    const store = this.loadStore();
+    return {
+      running: this._running,
+      jobCount: store.jobs.filter(j => j.id !== this.heartbeatJobId).length,
+      nextWakeAt: this.getNextWakeMs(),
+    };
+  }
+
+  async triggerHeartbeat(): Promise<void> {
+    if (this.heartbeatJobId && this.store) {
+      const job = this.store.jobs.find(j => j.id === this.heartbeatJobId);
+      if (job && this.onJob) await this.onJob(job);
+    }
+  }
+}

package/src/scheduler/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Scheduler types
+ *
+ * 支持三种调度：at（单次指定时间）、every（固定间隔）、cron（表达式）
+ * Payload 支持 agent_turn（到点执行 prompt）、heartbeat（读 HEARTBEAT.md）、system_event
+ */
+
+export interface Schedule {
+  kind: 'at' | 'every' | 'cron';
+  /** 单次执行时间戳（kind=at） */
+  atMs?: number;
+  /** 间隔毫秒（kind=every） */
+  everyMs?: number;
+  /** Cron 表达式（kind=cron） */
+  expr?: string;
+  /** 时区（kind=cron 可选） */
+  tz?: string;
+}
+
+export interface JobPayload {
+  kind: 'system_event' | 'agent_turn' | 'heartbeat';
+  /** 触发时发给 AI 的 prompt（agent_turn）或 heartbeat 说明 */
+  message: string;
+  /** 是否投递到指定 channel/user */
+  deliver: boolean;
+  channel?: string;
+  to?: string;
+}
+
+export interface JobState {
+  nextRunAtMs?: number;
+  lastRunAtMs?: number;
+  lastStatus?: 'ok' | 'error' | 'skipped';
+  lastError?: string;
+}
+
+export interface ScheduledJob {
+  id: string;
+  name: string;
+  enabled: boolean;
+  schedule: Schedule;
+  payload: JobPayload;
+  state: JobState;
+  createdAtMs: number;
+  updatedAtMs: number;
+  /** 单次任务执行后是否删除 */
+  deleteAfterRun: boolean;
+}
+
+export interface JobStore {
+  version: number;
+  jobs: ScheduledJob[];
+}
+
+export type JobCallback = (job: ScheduledJob) => Promise<void>;
+
+export interface AddJobOptions {
+  name: string;
+  schedule: Schedule;
+  payload: JobPayload;
+  enabled?: boolean;
+  deleteAfterRun?: boolean;
+}
+
+export interface IScheduler {
+  start(): Promise<void>;
+  stop(): void;
+  addJob(options: AddJobOptions): ScheduledJob;
+  removeJob(jobId: string): boolean;
+  enableJob(jobId: string, enabled: boolean): boolean;
+  runJob(jobId: string): Promise<void>;
+  listJobs(): ScheduledJob[];
+  status(): { running: boolean; jobCount: number; nextWakeAt?: number };
+}