docs: add cron tasks and heartbeat sections to READMEs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-17 03:37:51 +08:00
parent a2ed88a54b
commit 85e595a141
3 changed files with 66 additions and 3 deletions
--- a/README.md
+++ b/README.md
@@ -127,6 +127,8 @@ mimi> memory_write "content"   # write to MEMORY.md
 mimi> heap_info                # how much RAM is free?
 mimi> session_list             # list all chat sessions
 mimi> session_clear 12345      # wipe a conversation
+mimi> heartbeat_trigger           # manually trigger a heartbeat check
+mimi> cron_start                  # start cron scheduler now
 mimi> restart                     # reboot
 ```

@@ -139,6 +141,8 @@ MimiClaw stores everything as plain text files you can read and edit:
 | `SOUL.md` | The bot's personality — edit this to change how it behaves |
 | `USER.md` | Info about you — name, preferences, language |
 | `MEMORY.md` | Long-term memory — things the bot should always remember |
+| `HEARTBEAT.md` | Task list the bot checks periodically and acts on autonomously |
+| `cron.json` | Scheduled jobs — recurring or one-shot tasks created by the AI |
 | `2026-02-05.md` | Daily notes — what happened today |
 | `tg_12345.jsonl` | Chat history — your conversation with the bot |

@@ -150,9 +154,24 @@ MimiClaw supports tool calling for both Anthropic and OpenAI — the LLM can cal
 |------|-------------|
 | `web_search` | Search the web via Brave Search API for current information |
 | `get_current_time` | Fetch current date/time via HTTP and set the system clock |
+| `cron_add` | Schedule a recurring or one-shot task (the LLM creates cron jobs on its own) |
+| `cron_list` | List all scheduled cron jobs |
+| `cron_remove` | Remove a cron job by ID |

 To enable web search, set a [Brave Search API key](https://brave.com/search/api/) via `MIMI_SECRET_SEARCH_KEY` in `mimi_secrets.h`.

+## Cron Tasks
+
+MimiClaw has a built-in cron scheduler that lets the AI schedule its own tasks. The LLM can create recurring jobs ("every N seconds") or one-shot jobs ("at unix timestamp") via the `cron_add` tool. When a job fires, its message is injected into the agent loop — so the AI wakes up, processes the task, and responds.
+
+Jobs are persisted to SPIFFS (`cron.json`) and survive reboots. Example use cases: daily summaries, periodic reminders, scheduled check-ins.
+
+## Heartbeat
+
+The heartbeat service periodically reads `HEARTBEAT.md` from SPIFFS and checks for actionable tasks. If uncompleted items are found (anything that isn't an empty line, a header, or a checked `- [x]` box), it sends a prompt to the agent loop so the AI can act on them autonomously.
+
+This turns MimiClaw into a proactive assistant — write tasks to `HEARTBEAT.md` and the bot will pick them up on the next heartbeat cycle (default: every 30 minutes).
+
 ## Also Included

 - **WebSocket gateway** on port 18789 — connect from your LAN with any WebSocket client
@@ -160,6 +179,8 @@ To enable web search, set a [Brave Search API key](https://brave.com/search/api/
 - **Dual-core** — network I/O and AI processing run on separate CPU cores
 - **HTTP proxy** — CONNECT tunnel support for restricted networks
 - **Multi-provider** — supports both Anthropic (Claude) and OpenAI (GPT), switchable at runtime
+- **Cron scheduler** — the AI can schedule its own recurring and one-shot tasks, persisted across reboots
+- **Heartbeat** — periodically checks a task file and prompts the AI to act autonomously
 - **Tool use** — ReAct agent loop with tool calling for both providers

 ## For Developers
--- a/README_CN.md
+++ b/README_CN.md
@@ -142,6 +142,8 @@ mimi> memory_write "内容"       # 写入 MEMORY.md
 mimi> heap_info                # 还剩多少内存？
 mimi> session_list             # 列出所有会话
 mimi> session_clear 12345      # 删除一个会话
+mimi> heartbeat_trigger           # 手动触发一次心跳检查
+mimi> cron_start                  # 立即启动 cron 调度器
 mimi> restart                     # 重启
 ```

@@ -154,6 +156,8 @@ MimiClaw 把所有数据存为纯文本文件，可以直接读取和编辑：
 | `SOUL.md` | 机器人的人设 — 编辑它来改变行为方式 |
 | `USER.md` | 关于你的信息 — 姓名、偏好、语言 |
 | `MEMORY.md` | 长期记忆 — 它应该一直记住的事 |
+| `HEARTBEAT.md` | 待办清单 — 机器人定期检查并自主执行 |
+| `cron.json` | 定时任务 — AI 创建的周期性或一次性任务 |
 | `2026-02-05.md` | 每日笔记 — 今天发生了什么 |
 | `tg_12345.jsonl` | 聊天记录 — 你和它的对话 |

@@ -165,9 +169,24 @@ MimiClaw 同时支持 Anthropic 和 OpenAI 的工具调用 — LLM 在对话中
 |------|------|
 | `web_search` | 通过 Brave Search API 搜索网页，获取实时信息 |
 | `get_current_time` | 通过 HTTP 获取当前日期和时间，并设置系统时钟 |
+| `cron_add` | 创建定时或一次性任务（LLM 自主创建 cron 任务） |
+| `cron_list` | 列出所有已调度的 cron 任务 |
+| `cron_remove` | 按 ID 删除 cron 任务 |

 启用网页搜索需要在 `mimi_secrets.h` 中设置 [Brave Search API key](https://brave.com/search/api/)（`MIMI_SECRET_SEARCH_KEY`）。

+## 定时任务（Cron）
+
+MimiClaw 内置 cron 调度器，让 AI 可以自主安排任务。LLM 可以通过 `cron_add` 工具创建周期性任务（"每 N 秒"）或一次性任务（"在某个时间戳"）。任务触发时，消息会注入到 Agent 循环 — AI 自动醒来、处理任务并回复。
+
+任务持久化存储在 SPIFFS（`cron.json`），重启后不会丢失。典型用途：每日总结、定时提醒、定期巡检。
+
+## 心跳（Heartbeat）
+
+心跳服务会定期读取 SPIFFS 上的 `HEARTBEAT.md`，检查是否有待办事项。如果发现未完成的条目（非空行、非标题、非已勾选的 `- [x]`），就会向 Agent 循环发送提示，让 AI 自主处理。
+
+这让 MimiClaw 变成一个主动型助理 — 把任务写入 `HEARTBEAT.md`，机器人会在下一次心跳周期自动拾取执行（默认每 30 分钟）。
+
 ## 其他功能

 - **WebSocket 网关** — 端口 18789，局域网内用任意 WebSocket 客户端连接
@@ -175,6 +194,8 @@ MimiClaw 同时支持 Anthropic 和 OpenAI 的工具调用 — LLM 在对话中
 - **双核** — 网络 I/O 和 AI 处理分别跑在不同 CPU 核心
 - **HTTP 代理** — CONNECT 隧道，适配受限网络
 - **多提供商** — 同时支持 Anthropic (Claude) 和 OpenAI (GPT)，运行时可切换
+- **定时任务** — AI 可自主创建周期性和一次性任务，重启后持久保存
+- **心跳服务** — 定期检查任务文件，驱动 AI 自主执行
 - **工具调用** — ReAct Agent 循环，两种提供商均支持工具调用

 ## 开发者
--- a/README_JA.md
+++ b/README_JA.md
@@ -127,6 +127,8 @@ mimi> memory_write "内容"       # MEMORY.mdに書き込み
 mimi> heap_info                # 空きRAMはどれくらい？
 mimi> session_list             # 全チャットセッションを一覧
 mimi> session_clear 12345      # 会話を削除
+mimi> heartbeat_trigger           # ハートビートチェックを手動トリガー
+mimi> cron_start                  # cronスケジューラを今すぐ開始
 mimi> restart                     # 再起動
 ```

@@ -139,6 +141,8 @@ MimiClawはすべてのデータをプレーンテキストファイルとして
 | `SOUL.md` | ボットの性格 — 編集して振る舞いを変更 |
 | `USER.md` | あなたの情報 — 名前、好み、言語 |
 | `MEMORY.md` | 長期記憶 — ボットが常に覚えておくべきこと |
+| `HEARTBEAT.md` | タスクリスト — ボットが定期的にチェックして自律的に実行 |
+| `cron.json` | スケジュールジョブ — AIが作成した定期・単発タスク |
 | `2026-02-05.md` | 日次メモ — 今日あったこと |
 | `tg_12345.jsonl` | チャット履歴 — ボットとの会話 |

@@ -150,9 +154,24 @@ MimiClawはAnthropicとOpenAI両方のツール呼び出しをサポート — L
 |--------|------|
 | `web_search` | Brave Search APIでウェブ検索、最新情報を取得 |
 | `get_current_time` | HTTP経由で現在の日時を取得し、システムクロックを設定 |
+| `cron_add` | 定期または単発タスクをスケジュール（LLMが自律的にcronジョブを作成） |
+| `cron_list` | スケジュール済みのcronジョブを一覧表示 |
+| `cron_remove` | IDでcronジョブを削除 |

 ウェブ検索を有効にするには、`mimi_secrets.h`で[Brave Search APIキー](https://brave.com/search/api/)（`MIMI_SECRET_SEARCH_KEY`）を設定してください。

+## Cronタスク
+
+MimiClawにはcronスケジューラが内蔵されており、AIが自律的にタスクをスケジュールできます。LLMは`cron_add`ツールで定期ジョブ（「N秒ごと」）や単発ジョブ（「UNIXタイムスタンプで指定」）を作成できます。ジョブが発火すると、メッセージがエージェントループに注入され、AIが起動してタスクを処理・応答します。
+
+ジョブはSPIFFS（`cron.json`）に永続化され、再起動後も保持されます。活用例：日次サマリー、定期リマインダー、スケジュールチェック。
+
+## ハートビート
+
+ハートビートサービスはSPIFFS上の`HEARTBEAT.md`を定期的に読み取り、アクション可能なタスクがあるかチェックします。未完了の項目（空行、見出し、チェック済み`- [x]`以外）が見つかると、エージェントループにプロンプトを送信し、AIが自律的に処理します。
+
+これによりMimiClawはプロアクティブなアシスタントになります — `HEARTBEAT.md`にタスクを書き込めば、次のハートビートサイクルで自動的に拾い上げて実行します（デフォルト：30分ごと）。
+
 ## その他の機能

 - **WebSocketゲートウェイ** — ポート18789、LAN内から任意のWebSocketクライアントで接続
@@ -160,6 +179,8 @@ MimiClawはAnthropicとOpenAI両方のツール呼び出しをサポート — L
 - **デュアルコア** — ネットワークI/OとAI処理が別々のCPUコアで動作
 - **HTTPプロキシ** — CONNECTトンネル対応、制限付きネットワークに対応
 - **マルチプロバイダー** — Anthropic (Claude) と OpenAI (GPT) の両方をサポート、実行時に切り替え可能
+- **Cronスケジューラ** — AIが定期・単発タスクを自律的にスケジュール、再起動後も永続化
+- **ハートビート** — タスクファイルを定期チェックし、AIを自律的に駆動
 - **ツール呼び出し** — ReActエージェントループ、両プロバイダーでツール呼び出し対応

 ## 開発者向け