From 1a30cba626c2a63a8626ebf04ab33562d64c27c5 Mon Sep 17 00:00:00 2001 From: zlei9 Date: Sun, 29 Mar 2026 09:46:18 +0800 Subject: [PATCH] Initial commit with translated description --- SKILL.md | 114 ++++++++++++++++++++++++++++++++++++++++ _meta.json | 6 +++ references/templates.md | 83 +++++++++++++++++++++++++++++ 3 files changed, 203 insertions(+) create mode 100644 SKILL.md create mode 100644 _meta.json create mode 100644 references/templates.md diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..f44a97a --- /dev/null +++ b/SKILL.md @@ -0,0 +1,114 @@ +--- +name: cron-mastery +description: "掌握OpenClaw的定时系统。用于安排可靠的提醒、设置定期维护和理解何时使用Cron与Heartbeat。" +--- + +# Cron Mastery + +**Rule #1: Heartbeats drift. Cron is precise.** + +This skill provides the definitive guide for managing time in OpenClaw 2026.2.15+. It solves the "I missed my reminder" problem by enforcing a strict separation between casual checks (heartbeat) and hard schedules (cron). + +## The Core Principle + +| System | Behavior | Best For | Risk | +| :--- | :--- | :--- | :--- | +| **Heartbeat** | "I'll check in when I can" (e.g., every 30-60m) | Email checks, casual news summaries, low-priority polling. | **Drift:** A "remind me in 10m" task will fail if the heartbeat is 30m. | +| **Cron** | "I will run at exactly X time" | Reminders ("in 5 mins"), daily reports, system maintenance. | **Clutter:** Creates one-off jobs that need cleanup. | + +## 1. Setting Reliable Reminders (2026.2.15+ Standard) + +**Rule:** Never use `act:wait` or internal loops for long delays (>1 min). Use `cron:add` with a one-shot `at` schedule. + +### Precision & The "Scheduler Tick" +While Cron is precise, execution depends on the **Gateway Heartbeat** (typically every 10-60s). A job set for `:00` seconds will fire on the first "tick" after that time. Expect up to ~30s of variance depending on your gateway config. + +### Modern One-Shot Reminder Pattern +Use this payload structure for "remind me in X minutes" tasks. + +**Key Features (v2026.2.15+):** +- **Payload Choice:** Use **AgentTurn** with **Strict Instructions** for push notifications (reminders that ping your phone). Use **systemEvent** only for silent logs or background state updates. +- **Reliability:** `nextRunAtMs` corruption and "Add-then-Update" deadlocks are resolved. +- **Auto-Cleanup:** One-shot jobs auto-delete after success (`deleteAfterRun: true`). + +**CRITICAL: Push Notifications vs. Silent Logs** + +- **systemEvent (Silent):** Injects text into the chat history. Great for background logs, but **WILL NOT** ping the user's phone on Telegram/WhatsApp. +- **AgentTurn (Proactive):** Wakes an agent to deliver the message. **REQUIRED** for push notifications. Use the "Strict" prompt to avoid AI chatter. + +**For push-notification reminders (Reliable):** +```json +{ + "name": "Remind: Water", + "schedule": { "kind": "at", "at": "2026-02-06T01:30:00Z" }, + "payload": { + "kind": "agentTurn", + "message": "DELIVER THIS EXACT MESSAGE TO THE USER WITHOUT MODIFICATION OR COMMENTARY:\n\n💧 Drink water, Momo!" + }, + "sessionTarget": "isolated", + "delivery": { "mode": "announce", "channel": "telegram", "to": "1027899060" } +} +``` + +**For background logs (Silent):** +```json +{ + "name": "Log: System Pulse", + "schedule": { "kind": "every", "everyMs": 3600000 }, + "payload": { + "kind": "systemEvent", + "text": "[PULSE] System healthy." + }, + "sessionTarget": "main" +} +``` + +### Cron Concurrency Rule (Stabilized) +Pre-2026.2.15, the "Add-then-Update" pattern caused deadlocks. While this is now stabilized, it is still **best practice** to pass all parameters (including `wakeMode: "now"`) directly in the initial `cron.add` call for maximum efficiency. + +## 2. The Janitor (Auto-Cleanup) - LEGACY + +**Note:** As of v2026.2.14, OpenClaw includes **maintenance recompute semantics**. The gateway now automatically cleans up stuck jobs and repairs corrupted schedules. + +**Manual cleanup is only needed for:** +- One-shot jobs created with `deleteAfterRun: false`. +- Stale recurring jobs you no longer want. + +### Why use `sessionTarget: "main"`? (CRITICAL) +Sub-agents (`isolated`) often have restricted tool policies and cannot call `gateway` or delete other `cron` jobs. For system maintenance like the Janitor, **always** target the `main` session via `systemEvent` so the primary agent (with full tool access) performs the cleanup. + +## 3. Reference: Timezone Lock + +For cron to work, the agent **must** know its time. +* **Action:** Add the user's timezone to `MEMORY.md`. +* **Example:** `Timezone: Cairo (GMT+2)` +* **Validation:** If a user says "remind me at 9 PM," confirm: "9 PM Cairo time?" before scheduling. + +## 4. The Self-Wake Rule (Behavioral) + +**Problem:** If you say "I'll wait 30 seconds" and end your turn, you go to sleep. You cannot wake up without an event. +**Solution:** If you need to "wait" across turns, you **MUST** schedule a Cron job. + +* **Wait < 1 minute (interactive):** Only allowed if you keep the tool loop open (using `act:wait`). +* **Wait > 1 minute (async):** Use Cron with `wakeMode: "now"`. + +## 5. Legacy Migration Guide + +If you have old cron jobs using these patterns, update them: + +| Legacy (Pre-2026.2.3) | Modern (2026.2.15+) | +| :--- | :--- | +| `"schedule": {"kind": "at", "atMs": 1234567890}` | `"schedule": {"kind": "at", "at": "2026-02-06T01:30:00Z"}` | +| `"deliver": true` in payload | Not needed - `announce` mode handles delivery | +| `"sessionTarget": "main"` | `"sessionTarget": "isolated"` (default behavior) | +| Manual ghost cleanup required | One-shots auto-delete (`deleteAfterRun: true`) | +| `cron.update` after `cron.add` | Single-step `cron.add` with all properties | + +## Troubleshooting + +* **"My reminder didn't fire":** Check `cron:list`. Verify the `at` timestamp is in the future (ISO 8601 format). Ensure `wakeMode: "now"` is set. +* **"Gateway Timeout (10000ms)":** This happens if the `cron` tool takes too long (huge job list or file lock). + - **Fix 1:** Manually delete `~/.openclaw/state/cron/jobs.json` and restart the gateway if it's corrupted. + - **Fix 2:** Run a manual sweep to reduce the job count. +* **"Job ran but I didn't get the message":** Ensure you are using the **Strict Instruction Pattern** with `agentTurn` + `announce` mode for proactive pings. +* **"The reminder message has extra commentary":** The subagent is being conversational. Use the strict prompt pattern: `"DELIVER THIS EXACT MESSAGE TO THE USER WITHOUT MODIFICATION OR COMMENTARY:\n\n💧 Your message here"` diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..c46680e --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn77tqkcm269sx2m1yqg1ja83n8090mv", + "slug": "cron-mastery", + "version": "1.0.3", + "publishedAt": 1771282970279 +} \ No newline at end of file diff --git a/references/templates.md b/references/templates.md new file mode 100644 index 0000000..2af5104 --- /dev/null +++ b/references/templates.md @@ -0,0 +1,83 @@ +# Cron Examples & Templates + +## One-Shot Reminder (Push Notification / Reliable) + +**Context:** User says "Remind me to check the oven in 15 mins." +**Best for:** Timers that MUST ping the user's phone. + +```json +{ + "action": "add", + "job": { + "name": "Oven Timer", + "schedule": { + "kind": "at", + "at": "2026-02-16T21:15:00+02:00" + }, + "payload": { + "kind": "agentTurn", + "message": "DELIVER THIS EXACT MESSAGE TO THE USER WITHOUT MODIFICATION OR COMMENTARY:\n\n🔥 OVEN CHECK! It's been 15 minutes." + }, + "sessionTarget": "isolated", + "delivery": { + "mode": "announce", + "channel": "telegram", + "to": "1027899060" + }, + "wakeMode": "now" + } +} +``` + +## The Janitor (System Maintenance) + +**Context:** Cleaning up finished one-shot jobs daily. +**Best for:** Running with full tool access in the main session. + +```json +{ + "action": "add", + "job": { + "name": "Daily Cron Sweep", + "schedule": { + "kind": "every", + "everyMs": 86400000 + }, + "payload": { + "kind": "systemEvent", + "text": "Time for the 24-hour cron sweep. List all cron jobs (includeDisabled: true). Delete any disabled jobs with lastStatus: ok. Report results." + }, + "sessionTarget": "main", + "wakeMode": "now" + } +} +``` + +## Complex Task (Recurring/Async) + +**Context:** User says "Summarize my emails every morning at 8 AM." + +```json +{ + "action": "add", + "job": { + "name": "Morning Briefing", + "schedule": { + "kind": "cron", + "expr": "0 8 * * *", + "tz": "Africa/Cairo" + }, + "payload": { + "kind": "agentTurn", + "message": "Good morning! Search for unread emails and top tech news, then summarize them." + }, + "sessionTarget": "isolated", + "wakeMode": "now", + "delivery": { + "mode": "announce", + "channel": "telegram", + "to": "1027899060" + } + } +} +```