Zhin.js

English

简体中文

English

简体中文

Appearance

中文版

Generated reference snapshot

Original Cubic page · captured 2026-09-23 · source commit. This AI-generated page has not been verified against the current code. Use the Zhin documentation for current behavior and see known corrections.

Known correction

Some Cubic source line anchors for the plugin example point to unrelated blocks. Check the linked files before copying the example. See Schedules.

Relevant source files

The following files were used as context for generating this wiki page:

Schedule Engine & Cron Jobs ​

The Schedule Engine provides a calendar-semantic scheduling library for Zhin.js. It supports complex timing logic including Solar and Lunar Cron expressions, Chinese statutory holidays, and persistent job management. The system resides in the basic/schedule directory and integrates through the @zhin.js/kernel and @zhin.js/agent layers to provide scheduling capabilities to plugins and AI agents.

Sources: basic/schedule/README.md:1-5, AGENTS.md:68-75

System Architecture ​

The scheduling system operates across multiple architectural layers. The base layer provides core calendar logic, while upper layers wrap this logic for specific IM and Agent workflows.

The diagram shows the upward dependency flow from the basic schedule library to the high-level Agent Job Engine. Sources: basic/schedule/README.md:12-20, CLAUDE.md:73-85

Scheduling Capabilities ​

The CalendarScheduler serves as the primary engine for managing time-based triggers. It handles traditional Cron expressions and specialized Chinese calendar requirements.

Supported Schedule Kinds ​

The system categorizes triggers into several types to handle complex regional requirements.

KindDescription
solarStandard Gregorian Cron (6 segments: sec, min, hour, day, month, week)
lunarTraditional Chinese Lunar Calendar Cron
workdayStatutory workdays, including adjusted working weekends
freeDayRest days and weekends
holidaySpecific festival intervals (e.g., Spring Festival)
scatterTriggers randomly or dispersed within a specific time window

Sources: basic/schedule/README.md:37-47, basic/schedule/package.json:3-5

Holiday Data Management ​

The engine includes built-in holiday data for the years 2019–2026 based on State Council announcements. Users can update these datasets at runtime using the HolidayCalendar.update method or through synchronization scripts like sync-holiday.mjs. Sources: basic/schedule/README.md:52-60

Persistent Storage (JobStore) ​

The Schedule Engine supports multiple persistence backends to ensure jobs survive process restarts. The JobStore interface allows for different implementations based on project scale.

  • Local JSON Store: Created via createLocalJsonStore, suitable for small standalone bots.
  • SQLite Store: Created via createSqliteStore, providing relational persistence.
  • Redis Store: Created via createRedisStore, enabling job claiming across multiple worker instances.

Sources: basic/schedule/README.md:66-72

Agent Integration (ScheduleJobEngine) ​

The ScheduleJobEngine within the @zhin.js/agent package manages scheduled tasks specifically for AI agents. It links the scheduler to a JobWorker and a TaskExecutor.

Job Execution Flow ​

When a scheduled time is reached, the engine coordinates the task execution and notification.

This sequence illustrates the internal communication between the scheduler, the worker, and the AI task executor. Sources: packages/im/agent/tests/assistant/job-engine.test.ts:28-50

Job Configuration ​

Agent jobs include metadata for proper execution context:

  • createdBy: Identifies the user who initiated the job (userId, roles).
  • executionPlan: Contains the prompt, required tools, and skills for the agent.
  • notify: Configuration for success/failure feedback (e.g., silent or specific IM channels).

Sources: packages/im/agent/tests/assistant/job-engine.test.ts:52-105

Plugin Implementation ​

Developers register scheduled tasks in Zhin plugins using the scheduleHostToken. This is the recommended approach for the 1.1.x stable line, moving away from legacy imperative APIs.

typescript
// plugin.ts
import { definePlugin, scheduleHostToken } from 'zhin.js';

export default definePlugin({
  name: 'example-plugin',
  setup(context) {
    if (!context.resources.has(scheduleHostToken)) return;
    const schedule = context.resources.use(scheduleHostToken);

    context.lifecycle.add(
      schedule.register({
        id: 'my-plugin/hourly-task',
        cron: '0 0 * * * *',
        async execute() {
          console.log('Task executed');
        },
      }),
    );
  },
});

Sources: packages/toolkit/create-zhin/template/skills/plugin-develop/SKILL.md:67-84, CLAUDE.md:110-120

Summary ​

The Schedule Engine & Cron Jobs system provides a robust, calendar-aware scheduling solution integrated deeply into the Zhin.js architecture. By leveraging the CalendarScheduler and persistent JobStore implementations, the framework ensures reliable task execution across various time regimes, including specific Chinese holiday adjustments. For AI agents, the ScheduleJobEngine bridges the gap between time-based triggers and automated agent actions, allowing for sophisticated scheduled workflows like morning briefs or periodic maintenance tasks.