Nocobase App Plugin Scheduler Agent Skill

Develop Scheduled Tasks in an Application

Use the installed version's public exports, without importing plugin internals. The application owns business logic, schedule declarations, Providers, permissions, and deployment timing. Scheduler owns scheduling projections, trigger history, and execution state. The plugin's skills/ directory is the source of truth; do not edit the synchronized application copy under .agents/skills/.

Decide Whether to Use Scheduler

The primary reason to define tasks through Scheduler is UI observability for business administrators. Developers define schedules and execution logic in code. Business administrators use the task list and detail pages the application builds on the Scheduler API to view schedules, track individual executions, and enable or disable tasks when authorized.

Tasks that do not need to be viewed and tracked through the UI must not be managed by the Scheduler plugin. Give recurring ones a ScheduleExecutor of their own from the application's jobs service (jobExecutorServiceToken in @nocobase/app-server/jobs), and one-off background work a JobExecutor; the application development Skill describes both. For administrator-visible tasks, deliver Client registration, access permissions, meaningful task names, and accurate final execution status together; successful server-side dispatch alone is incomplete.

Then Choose the Execution Model

After deciding to use Scheduler, choose according to business complexity:

| Scenario | Choice | Implementation boundary |

| ----------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |

| Periodic cleanup, cache refresh, a single report, or one business Service call | Own target type | Short operations may complete directly; hand lengthy work to a JobExecutor |

| A simple operation that happens hourly | Own target type | Cron alone is not a reason to introduce a heavier execution system |

| Immediate asynchronous execution | JobExecutor | No Cron Schedule is needed |

| A one-time delay, such as ten minutes after a request | Queue delay | No Cron Schedule is needed; JobExecutor has no delay |

| Another execution system with its own references, status queries, and completion protocol | Own target type | The same registerTarget() call, with inspect() and completion reporting for work that finishes later |

Every schedule points at a registered target; registerTarget() is the target extension surface, and there is no built-in target type. A target does not guarantee exactly-once external business effects; design business idempotency.

Read by Task

• To create or change a schedule, read Definitions, Registration, and Synchronization.
• To register or review a target, hand its work to a JobExecutor, report completion, or diagnose a historical occurrence after retargeting, read Target Extensions and Execution Protocol.
• To integrate or review the UI/API and permissions, interpret status, or diagnose missing definitions, read Operations and Verification, including the complete management route table, separate status dimensions, and application identity checks.

Development Loop

• Establish which tasks and execution records administrators need to see. Check Server/Client/CLI registration, page permissions, the application's jobs configuration (a redis adapter for more than one instance; memory serves one process) and JobExecutorServiceProvider composition and target availability, then choose or register the target type.
• Implement business logic and Providers in application source, and call schedulerServiceToken.defineSchedule(definition) with an application-wide stable key from that Provider's register()/boot().
• Validate payload/input, timezone, idempotency, and the full asynchronous chain: submission, actual job execution, terminal notification, and recovery from persisted execution state. Obtain credentials through secure business Service configuration, never target.config.
• Run application type checks, relevant tests, and build. Synchronize definitions and, in development, use an administrator account to find the task in the UI and track a real execution to its final state. Confirm the business result.
• Report the schedule key, execution model, timezone, validation evidence, and unverified runtime boundaries. Use --finalize in production only when the complete manifest is visible.

Schedules are defined in code. There is no management API for creating or editing Cron definitions, but the UI and API support enabling and disabling tasks. Do not modify schedule_definitions, schedule_occurrences, or the schedule backend's rules (BullMQ job schedulers, or the memory adapter's state file) directly, and do not add jobs under Scheduler's @nocobase/app-plugin-scheduler scope.