How yt-koike/dify-cron works
Project type and purpose
• This is a Dify “extension” plugin named “Cron” (see README: Type: extension).
• Its purpose is to let Dify users schedule and trigger workflows at specified times or intervals using cron syntax and, in the cloud version, the external service cron-job.org.
File structure
• Top-level files:
• main.py → plugin entry point
• manifest.yaml → plugin metadata and endpoint definitions
• requirements.txt, .env.example, ruff.toml → dependencies and linting
• endpoints/ → Python code + YAML for each HTTP endpoint
• /cron.yaml → group definition for permissions or routing
• tests/ → unit tests (e.g., test_cron.py)
• endpoints directory:
• cron.py + cron.yaml → handles scheduling start/stop calls
• entry.py + entry.yaml → handles incoming cron callback and triggers the workflow
• GUIDE.md, README.md, PRIVACY.md, OWNERSHIP.md, etc., provide docs and policies.
README for additional insights
• Describes two operational modes: self-hosted (pure plugin) vs. cloud (needs cron-job.org API).
• Workflow:
1. User adds an “endpoint” via Dify UI.
2. Plugin registers a cron job (via cron-job.org in cloud mode).
3. cron-job.org calls back the plugin’s entry endpoint.
4. Plugin invokes the Dify Workflow or Chatflow API to run the user’s logic.
• No database; state is managed by cron-job.org for cloud or in-memory for self-hosted.
a. Main components
• Dify Core / Plugin Host
• Cron Plugin Service
– HTTP endpoints: /cron (start/stop), /entry (webhook)
– Scheduling logic (cron syntax parsing)
• External Scheduler Service (cron-job.org) [cloud only]
• Dify Workflow Engine API
• User Interface (Dify Admin UI)
b. Relationships and interactions
1. User configures a new Cron endpoint in Dify Admin UI →
plugin Host reads manifest.yaml → loads cron endpoint definitions.
2. Plugin receives “start” request → parses cron string →
if cloud: calls cron-job.org API to register schedule
if self-hosted: spins up an internal timer.
3. At scheduled time, external service (or internal timer) makes HTTP POST to plugin’s /entry endpoint.
4. Plugin’s entry handler receives callback → sets is_cron = yes → calls Dify Workflow Engine API to trigger the user’s workflow.
5. Workflow Engine executes the workflow; responses flow back via plugin.
c. Architectural patterns and design principles
• Event-driven / webhook-based scheduling
• Minimal internal state (stateless plugin, relies on external scheduler)
• Clear separation of concerns:
• Endpoint definitions (YAML) vs. handler logic (Python)
• Plugin host vs. external scheduler vs. workflow engine
• Extensibility: adding new endpoints just means adding new .py + .yaml pairs under endpoints/
d. Key technologies
• Python (cron.py, entry.py)
• Dify plugin framework (manifest.yaml, group definitions)
• cron-job.org REST API (cloud)
• Standard cron format libraries or custom parser
• Dify Workflow Engine REST API
Essential elements to capture
• Labels: name each endpoint (/cron, /entry) and each service.
• Annotations: note “cloud mode” vs. “self-hosted” paths.
• Plugin’s two handlers together under a single Plugin Service boundary.