From 9ce9d2235a87b117989bd8acb0c013e6758cdcb4 Mon Sep 17 00:00:00 2001 From: chengyongru <2755839590@qq.com> Date: Sat, 27 Jun 2026 01:37:23 +0800 Subject: [PATCH] docs: clarify heartbeat versus cron delivery --- docs/chat-commands.md | 10 ++++++---- docs/concepts.md | 4 ++-- docs/configuration.md | 4 +++- docs/webui.md | 7 ++++++- nanobot/skills/cron/SKILL.md | 4 +++- nanobot/templates/AGENTS.md | 3 ++- nanobot/templates/HEARTBEAT.md | 4 +++- 7 files changed, 25 insertions(+), 11 deletions(-) diff --git a/docs/chat-commands.md b/docs/chat-commands.md index fded560d..fafce2a0 100644 --- a/docs/chat-commands.md +++ b/docs/chat-commands.md @@ -57,18 +57,20 @@ Preset names come from the top-level `modelPresets` config. Switching is runtime ## Periodic Tasks -Periodic tasks are driven by `HEARTBEAT.md` in your workspace (`~/.nanobot/workspace/HEARTBEAT.md`). When `nanobot gateway` starts, it registers a protected heartbeat cron job by default. Every 30 minutes, that job checks the file; if it finds tasks under `## Active Tasks`, the agent executes them and delivers results to your most recently active chat channel. If there are no active tasks, the heartbeat is skipped silently. +Periodic background checks are driven by `HEARTBEAT.md` in your workspace (`~/.nanobot/workspace/HEARTBEAT.md`). When `nanobot gateway` starts, it registers a protected heartbeat cron job by default. Every 30 minutes, that job checks the file; if it finds tasks under `## Active Tasks`, the agent executes them and delivers only results that pass the notification gate to your most recently active chat channel. If there are no active tasks, or the result is routine with nothing useful to report, the heartbeat is skipped silently. + +Use heartbeat for recurring checks that should usually stay quiet. User-created cron jobs are different: they run as scheduled turns in the chat/session where they were created and normally deliver the result back to that channel. **Setup:** edit `~/.nanobot/workspace/HEARTBEAT.md` (created automatically by `nanobot onboard`): ```markdown ## Active Tasks -- Check weather forecast and send a summary -- Scan inbox for urgent emails +- Check weather forecast and notify me only if storms are expected +- Scan inbox for urgent emails and notify me if any are found ``` -The agent can also manage this file itself — ask it to "add a periodic task" and it will update `HEARTBEAT.md` for you. Completed tasks should be deleted from the file, not moved to another section. +The agent can also manage this file itself - ask it to "add a periodic background check" or "check this periodically but only notify me if something changes" and it will update `HEARTBEAT.md` for you. Completed tasks should be deleted from the file, not moved to another section. You can change the interval or disable the built-in heartbeat in `~/.nanobot/config.json`: diff --git a/docs/concepts.md b/docs/concepts.md index 405e6540..5f885083 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -136,9 +136,9 @@ When `nanobot gateway` starts, it creates workspace-scoped cron storage at `/HEARTBEAT.md`. If the file has tasks under `## Active Tasks`, nanobot executes them and sends useful results to the most recently active chat target. +Heartbeat reads `/HEARTBEAT.md`. If the file has tasks under `## Active Tasks`, nanobot executes them and sends only useful/actionable results to the most recently active chat target. Routine "nothing changed" results are suppressed. -User-created reminders use the same cron service but are not the same as the protected heartbeat system job. +User-created reminders use the same cron service but are not the same as the protected heartbeat system job. They run as scheduled turns in their origin chat/session and normally deliver the result back to that channel. ## Where to Go Next diff --git a/docs/configuration.md b/docs/configuration.md index ef006976..bba16d76 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1963,7 +1963,9 @@ The gateway can run a protected heartbeat cron job that periodically checks `HEA } ``` -If `HEARTBEAT.md` has tasks under `## Active Tasks`, the agent executes them and delivers useful results to the most recently active chat target. If the file has no active tasks, the heartbeat is skipped silently. +If `HEARTBEAT.md` has tasks under `## Active Tasks`, the agent executes them and sends only useful/actionable results to the most recently active chat target. If the file has no active tasks, or the result is routine with nothing useful to report, the heartbeat is skipped silently. + +This is intentionally different from user-created cron jobs. A cron job created with the `cron` tool runs as a scheduled turn in its origin chat/session and normally delivers the result back to that channel. Use `HEARTBEAT.md` for recurring background checks that should not notify the user on every run. The heartbeat job is backed by the same cron service as user-created reminders. It is stored under the active workspace (`/cron/jobs.json`) and shows up in `cron(action="list")` as `heartbeat`, but it is system-managed and cannot be removed with the `cron` tool. Disable it through config and restart the gateway if you do not want periodic heartbeat checks. diff --git a/docs/webui.md b/docs/webui.md index cf5aadda..a7208e27 100644 --- a/docs/webui.md +++ b/docs/webui.md @@ -118,7 +118,12 @@ to perform that task. Automations are scheduled agent turns. They should be created from the chat, channel, or session where they are supposed to run so nanobot keeps the correct -target context. +target context. When an automation runs, it normally delivers the result back to +that linked chat. + +For recurring background checks that should stay quiet unless there is something +useful to report, use the protected heartbeat job by editing `HEARTBEAT.md` +instead of creating a chat automation. Use the Automations view to: diff --git a/nanobot/skills/cron/SKILL.md b/nanobot/skills/cron/SKILL.md index cc3516e0..c4e6f4fc 100644 --- a/nanobot/skills/cron/SKILL.md +++ b/nanobot/skills/cron/SKILL.md @@ -5,7 +5,9 @@ description: Schedule reminders and recurring tasks. # Cron -Use the `cron` tool to schedule reminders or recurring tasks. +Use the `cron` tool to schedule reminders or recurring tasks that should report back to the originating chat/session when they run. + +Do not use `cron` for periodic background checks that should stay quiet when there is nothing useful to report. For those, update `HEARTBEAT.md`; the protected heartbeat job runs those checks and only delivers results that pass the notification gate. ## Three Modes diff --git a/nanobot/templates/AGENTS.md b/nanobot/templates/AGENTS.md index 08418141..b45305fb 100644 --- a/nanobot/templates/AGENTS.md +++ b/nanobot/templates/AGENTS.md @@ -9,6 +9,7 @@ Use this file for project-specific preferences, recurring workflow conventions, - Before scheduling reminders, check available skills and follow skill guidance first. - Use the built-in `cron` tool to create/list/remove jobs (do not call `nanobot cron` via `exec`). - Get USER_ID and CHANNEL from the current session (e.g., `8281248569` and `telegram` from `telegram:8281248569`). +- Cron jobs run as scheduled turns in the origin chat/session and normally deliver the result back to that channel. Do not use cron for background checks that should stay silent when there is nothing useful to report; use `HEARTBEAT.md` instead. **Do NOT just write reminders to MEMORY.md** — that won't trigger actual notifications. @@ -20,4 +21,4 @@ Use this file for project-specific preferences, recurring workflow conventions, - Use `edit_file` only for small exact replacements copied from the current `HEARTBEAT.md`. - Use `write_file` for first creation or intentional full-file rewrites. -When the user asks for a recurring/periodic heartbeat task, update `HEARTBEAT.md` instead of creating a one-time reminder. Use the built-in `cron` tool for separate reminders or custom schedules that should not be part of the heartbeat task list. +When the user asks for a recurring/periodic heartbeat task, or for a periodic background check that should only notify on actionable changes, update `HEARTBEAT.md` instead of creating a one-time reminder. Use the built-in `cron` tool for explicit reminders, scheduled tasks that should report every run, or custom schedules that should not be part of the heartbeat task list. diff --git a/nanobot/templates/HEARTBEAT.md b/nanobot/templates/HEARTBEAT.md index e8da6fab..97af125c 100644 --- a/nanobot/templates/HEARTBEAT.md +++ b/nanobot/templates/HEARTBEAT.md @@ -3,7 +3,9 @@ ## Active Tasks