nanobot Agent Instructions 模板：用 AGENTS.md、HEARTBEAT.md 与 cron 工具配置智能体的定时任务与工作区行为

nanobot Agent Instructions 模板：用 AGENTS.md、HEARTBEAT.md 与 cron 工具配置智能体的定时任务与工作区行为

【免费下载链接】nanobotUltra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps项目地址: https://gitcode.com/gh_mirrors/nanob/nanobot

导读

nanobot 是一个轻量级、可自托管的 Python AI Agent 框架，其nanobot/templates/目录内置了一套“智能体行为模板”，用于告诉运行在 nanobot 中的 AI Agent 如何理解当前工作区、如何安排定时提醒、如何处理周期性后台检查。本文以 AGENTS.md 模板 为骨架，完整讲解这套模板体系的分工（AGENTS / USER / SOUL / MEMORY / HEARTBEAT）、内置cron工具的正确调用方式、受保护 heartbeat 任务的底层机制，并结合 config/schema.py 与 cron 技能文档 给出可直接落地的配置与用法。读完本文，你将能正确地为自己的 nanobot 工作区配置定时提醒与静默后台巡检，并避免常见误用（例如把提醒写进 MEMORY.md、或用exec去调用nanobot cron）。

一、模板体系概览：每个文件该放什么内容

nanobot/templates/AGENTS.md开篇即明确了“工作区引导（Workspace Guidance）”的原则：这个文件用于存放项目特定的偏好、重复出现的工作流约定，以及希望 Agent 在工作区内长期记住的指令。同时它明确划定了各模板文件的职责边界，避免内容放错地方：

文件	用途	相对路径
AGENTS.md	项目特定偏好、重复工作流约定、工作区指令	nanobot/templates/AGENTS.md
USER.md	关于用户的持久事实（durable facts about the user）	nanobot/templates/USER.md
SOUL.md	个性与表达风格（personality / style guidance）	nanobot/templates/SOUL.md
MEMORY.md	长期记忆（long-term memory）	nanobot/templates/memory/MEMORY.md

这种“关注点分离”设计在模板内容中体现得很具体：

• USER.md 模板 提供了一份可编辑的个人资料清单：基础信息（姓名、时区、语言）、沟通偏好（风格、回复长度、技术水平）、工作背景（角色、主要项目、常用工具）、兴趣主题，以及“特殊指令（Special Instructions）”一栏，用于定制 Agent 的行为。
• SOUL.md 模板 定义了 Agent 的核心原则，例如“Solve by doing, not by describing what I would do”（用行动解决问题，而不是描述自己会怎么做）、“Say what I know, flag what I don't, and never fake confidence”（知之为知之，不知为不知，绝不虚张声势）。
• MEMORY.md 模板 声明该文件“由 nanobot 在遇到重要信息时自动更新”，用于跨会话持久保存用户信息、偏好、项目背景与重要笔记。

值得注意的是，AGENTS.md 对定时提醒给出了一条硬性告诫：“Do NOT just write reminders to MEMORY.md — that won't trigger actual notifications.”（不要只是把提醒写进 MEMORY.md——那不会触发真正的通知。）MEMORY.md 只是记忆存储，Agent 不会因为里面多了几行文字就去执行提醒；真正要触发通知必须走下面的cron工具。

二、定时提醒：使用内置 cron 工具，而不是 exec

2.1 核心规则

AGENTS.md 的 “Scheduled Reminders” 一节给出了三条硬规则：

1. 先查技能：在安排定时提醒之前，先检查当前可用的技能（skills），并遵循技能文档的指引。
2. 使用内置cron工具：通过内置cron工具创建/列出/移除任务，不要通过exec去调用nanobot cron命令。这是因为内置工具由 Agent 循环直接调度，能保证任务作为会话内定时 turn 正确运行，而通过exec走 CLI 属于绕过机制的反模式。
3. 获取会话上下文：从当前会话中取得USER_ID与CHANNEL，例如从telegram:8281248569这样的会话标识中拆出8281248569与telegram，用于把任务归属到正确的聊天与频道。

2.2 cron 工具的三种模式与调用示例

仓库内置的 cron 技能文档 nanobot/skills/cron/SKILL.md 把定时任务划分为三种模式，与 AGENTS.md 的指引一一对应：

1. Reminder（提醒）：消息直接发送给用户。
2. Task（任务）：消息是任务描述，Agent 每次到点执行并把结果发回。
3. One-time（一次性）：在指定时间运行一次后自动删除。

技能文档给出了可直接套用的调用示例：

# 固定提醒：每 1200 秒（20 分钟）提醒一次 cron(action="add", message="Time to take a break!", every_seconds=1200) # 动态任务：每次到点由 Agent 执行并回报结果 cron(action="add", message="Check HKUDS/nanobot GitHub stars and report", every_seconds=600) # 一次性定时任务：at 参数传 ISO 格式时间（从当前时间推算） cron(action="add", message="Remind me about the meeting", at="<ISO datetime>") # 时区感知的 cron 表达式：工作日早上 9 点（温哥华时区） cron(action="add", message="Morning standup", cron_expr="0 9 * * 1-5", tz="America/Vancouver") # 列出 / 移除任务 cron(action="list") cron(action="remove", job_id="abc123")

2.3 时间表达与时区约定

技能文档提供了一张“用户说法 → 工具参数”的速查表，方便 Agent 把自然语言时间需求翻译成参数：

用户说法	参数
每 20 分钟	every_seconds: 1200
每小时	every_seconds: 3600
每天早上 8 点	cron_expr: "0 8 * * *"
工作日傍晚 5 点	cron_expr: "0 17 * * 1-5"
每天温哥华时间早 9 点	cron_expr: "0 9 * * *", tz: "America/Vancouver"
指定时间	at: <ISO datetime>（从当前时间推算）

关于时区：使用cron_expr时应配合tz指定 IANA 时区；不传tz时默认使用服务器本地时区。

2.4 什么场景不要用 cron

AGENTS.md 特别强调：不要用 cron 去做“没事就不打扰”的静默后台检查。cron 任务作为定时 turn 在源聊天/会话中运行，通常会把每次运行的结果都发回频道；而周期性后台巡检往往希望“有值得报告的变化才通知”。这类场景应当改用下一节介绍的HEARTBEAT.md机制。

三、心跳任务：HEARTBEAT.md 与受保护的 heartbeat 任务

3.1 机制原理

HEARTBEAT.md是周期性后台检查的任务清单文件，AGENTS.md 说明其底层机制如下：

• nanobot gateway在gateway.heartbeat.enabled为true时会自动注册一个受保护的 heartbeat cron 任务，该任务周期性读取 HEARTBEAT.md 模板 中列出的任务并执行。
• 除非用户已经关闭了内置 heartbeat 任务并明确要求自定义调度，否则不要重复创建 heartbeat 任务，否则会与内置任务产生重复巡检。
• HEARTBEAT.md 中的注释也印证了这一点：文件由 heartbeat 任务周期性检查；“没有任务（只有标题和注释）时，Agent 会直接跳过”；已完成的任务应当删除而不是保留，因为 heartbeat 只读取“Active Tasks（活动任务）”部分。

从配置源码看，heartbeat 服务由GatewayConfig下的HeartbeatConfig管理，位于 nanobot/config/schema.py#L326-L330：

class HeartbeatConfig(Base): """Heartbeat service configuration (now backed by cron).""" enabled: bool = True interval_s: int = 30 * 60 # 30 minutes

即默认enabled=True、巡检间隔 30 分钟（interval_s: 1800），并且该配置“现在由 cron 支撑（now backed by cron）”——也就是说，heartbeat 的调度能力正是建立在 cron 机制之上的，这也解释了为何 AGENTS.md 要求你不要为 heartbeat 另建 cron 任务。对应地，GatewayConfig中挂载了该配置项（schema.py#L359）。

3.2 文件编辑约定

AGENTS.md 针对 HEARTBEAT.md 的日常维护给出了明确的工具选用约定：

• apply_patch：用于常规任务列表更新，尤其是新增、删除或改动多行的场景；
• edit_file：仅用于小规模精确替换，且替换内容必须是从当前 HEARTBEAT.md 原文拷贝出来的；
• write_file：用于首次创建或有意的整文件重写。

这套约定背后是 nanobot 工具体系的现实：apply_patch这类工具适合结构化、多行的差异编辑，而edit_file适合单点精确修改，选用不当会引入格式或语义偏差。

3.3 何时用 HEARTBEAT.md，何时用 cron

AGENTS.md 给出了清晰的决策边界：

• 用户要求周期性/重复的心跳任务，或只在出现可操作变化时才通知的后台巡检→ 更新HEARTBEAT.md；
• 用户要求明确的提醒、每次运行都要汇报的定时任务，或不属于心跳任务清单的自定义调度→ 使用内置cron工具。

同样，cron 技能文档也复述了这一分工：cron用于“应当把结果发回源聊天/会话”的提醒和重复任务；静默后台检查则改走HEARTBEAT.md，由受保护的 heartbeat 任务执行、且只有通过通知门（notification gate）的结果才会被投递。

3.4 关于 heartbeat 通知门与提示词覆盖（进阶）

模板目录下的 prompts/README.md 说明了 heartbeat 的进阶覆盖手段：heartbeat 投递前会经过一个“通知门”评估器（evaluator），由模型判断“本次心跳结果是否值得投递”。如果你想覆盖该评估器的系统提示词，可运行/evaluator-prompt init生成可编辑的prompts/evaluator.md。README 特别警告：覆盖后的提示词必须仍然要求模型调用evaluate_notification工具，否则门会“fail closed”（默认不投递、保持静默）。删除或清空该文件即可恢复内置提示词。同样地，/dream-prompt init可生成prompts/dream.md，用于覆盖 Dream 记忆整理行为的提示词。这些都是对“模板驱动行为”设计的延伸——工作区内的 Markdown 文件本身就是可编程的 Agent 行为层。

四、把模板投入实战：一个完整的工作区配置示例

综合以上模板与机制，一个典型的 nanobot 工作区“Agent 行为配置”可以这样组织：

1. AGENTS.md：写下项目特定的约定——例如“所有定时提醒一律使用内置cron工具，禁止用 exec 调用nanobot cron”“后台巡检一律进 HEARTBEAT.md”等，让 Agent 每次进入工作区都先读到。
2. USER.md：填写用户的时区、语言、沟通风格与技术背景，让 Agent 的回复更贴合个人偏好。
3. SOUL.md：保留模板中的核心原则，必要时补充个性化风格（例如“回答保持简短，除非用户要求详细”）。
4. memory/MEMORY.md：作为跨会话长期记忆，由 Agent 自动维护；不要把提醒任务写在这里。
5. HEARTBEAT.md：在 “Active Tasks” 下方维护周期性后台巡检项（例如“每天检查磁盘剩余空间，低于 20% 才提醒我”），配合gateway.heartbeat.enabled=true与默认 30 分钟间隔（interval_s）运行；完成任务即删除对应条目。
6. 定时提醒：需要明确汇报的提醒与定时任务，用内置cron工具按 cron 技能文档 的三种模式添加。

五、小结：把“行为规则”写进工作区，而不是写进对话

nanobot 的模板体系揭示了一个核心理念：Agent 的持久行为规则应当以 Markdown 文件的形式落在工作区里，由 Agent 在每次运行时读取并遵守，而不是依赖用户反复在对话中叮嘱。AGENTS.md 负责“怎么做事”（工作流约定、工具选择），USER.md 负责“为谁做事”（用户画像），SOUL.md 负责“以什么风格做事”（个性），MEMORY.md 负责“记住什么”（长期记忆），HEARTBEAT.md 负责“周期性地主动做事”（静默巡检）。定时提醒与心跳巡检之间“一个会主动汇报、一个默认静默”的分工，以及apply_patch/edit_file/write_file的编辑约定，共同构成了一个可预期、可维护的 Agent 行为框架。想要定制自己的 Agent，从编辑这些模板文件开始即可。

【免费下载链接】nanobotUltra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps项目地址: https://gitcode.com/gh_mirrors/nanob/nanobot