2026/9/19 13:23:31
FEATURED · 精选文章 
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.mdUSER.md关于用户的持久事实durable facts about the usernanobot/templates/USER.mdSOUL.md个性与表达风格personality / style guidancenanobot/templates/SOUL.mdMEMORY.md长期记忆long-term memorynanobot/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 dont, and never fake confidence”知之为知之不知为不知绝不虚张声势。MEMORY.md 模板 声明该文件“由 nanobot 在遇到重要信息时自动更新”用于跨会话持久保存用户信息、偏好、项目背景与重要笔记。值得注意的是AGENTS.md 对定时提醒给出了一条硬性告诫“Do NOT just write reminders to MEMORY.md — that wont trigger actual notifications.”不要只是把提醒写进 MEMORY.md——那不会触发真正的通知。MEMORY.md 只是记忆存储Agent 不会因为里面多了几行文字就去执行提醒真正要触发通知必须走下面的cron工具。二、定时提醒使用内置 cron 工具而不是 exec2.1 核心规则AGENTS.md 的 “Scheduled Reminders” 一节给出了三条硬规则先查技能在安排定时提醒之前先检查当前可用的技能skills并遵循技能文档的指引。使用内置cron工具通过内置cron工具创建/列出/移除任务不要通过exec去调用nanobot cron命令。这是因为内置工具由 Agent 循环直接调度能保证任务作为会话内定时 turn 正确运行而通过exec走 CLI 属于绕过机制的反模式。获取会话上下文从当前会话中取得USER_ID与CHANNEL例如从telegram:8281248569这样的会话标识中拆出8281248569与telegram用于把任务归属到正确的聊天与频道。2.2 cron 工具的三种模式与调用示例仓库内置的 cron 技能文档 nanobot/skills/cron/SKILL.md 把定时任务划分为三种模式与 AGENTS.md 的指引一一对应Reminder提醒消息直接发送给用户。Task任务消息是任务描述Agent 每次到点执行并把结果发回。One-time一次性在指定时间运行一次后自动删除。技能文档给出了可直接套用的调用示例# 固定提醒每 1200 秒20 分钟提醒一次 cron(actionadd, messageTime to take a break!, every_seconds1200) # 动态任务每次到点由 Agent 执行并回报结果 cron(actionadd, messageCheck HKUDS/nanobot GitHub stars and report, every_seconds600) # 一次性定时任务at 参数传 ISO 格式时间从当前时间推算 cron(actionadd, messageRemind me about the meeting, atISO datetime) # 时区感知的 cron 表达式工作日早上 9 点温哥华时区 cron(actionadd, messageMorning standup, cron_expr0 9 * * 1-5, tzAmerica/Vancouver) # 列出 / 移除任务 cron(actionlist) cron(actionremove, job_idabc123)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 什么场景不要用 cronAGENTS.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-L330class HeartbeatConfig(Base): Heartbeat service configuration (now backed by cron). enabled: bool True interval_s: int 30 * 60 # 30 minutes即默认enabledTrue、巡检间隔 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何时用 cronAGENTS.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 行为配置”可以这样组织AGENTS.md写下项目特定的约定——例如“所有定时提醒一律使用内置cron工具禁止用 exec 调用nanobot cron”“后台巡检一律进 HEARTBEAT.md”等让 Agent 每次进入工作区都先读到。USER.md填写用户的时区、语言、沟通风格与技术背景让 Agent 的回复更贴合个人偏好。SOUL.md保留模板中的核心原则必要时补充个性化风格例如“回答保持简短除非用户要求详细”。memory/MEMORY.md作为跨会话长期记忆由 Agent 自动维护不要把提醒任务写在这里。HEARTBEAT.md在 “Active Tasks” 下方维护周期性后台巡检项例如“每天检查磁盘剩余空间低于 20% 才提醒我”配合gateway.heartbeat.enabledtrue与默认 30 分钟间隔interval_s运行完成任务即删除对应条目。定时提醒需要明确汇报的提醒与定时任务用内置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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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.mdUSER.md关于用户的持久事实durable facts about the usernanobot/templates/USER.mdSOUL.md个性与表达风格personality / style guidancenanobot/templates/SOUL.mdMEMORY.md长期记忆long-term memorynanobot/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 dont, and never fake confidence”知之为知之不知为不知绝不虚张声势。MEMORY.md 模板 声明该文件“由 nanobot 在遇到重要信息时自动更新”用于跨会话持久保存用户信息、偏好、项目背景与重要笔记。值得注意的是AGENTS.md 对定时提醒给出了一条硬性告诫“Do NOT just write reminders to MEMORY.md — that wont trigger actual notifications.”不要只是把提醒写进 MEMORY.md——那不会触发真正的通知。MEMORY.md 只是记忆存储Agent 不会因为里面多了几行文字就去执行提醒真正要触发通知必须走下面的cron工具。二、定时提醒使用内置 cron 工具而不是 exec2.1 核心规则AGENTS.md 的 “Scheduled Reminders” 一节给出了三条硬规则先查技能在安排定时提醒之前先检查当前可用的技能skills并遵循技能文档的指引。使用内置cron工具通过内置cron工具创建/列出/移除任务不要通过exec去调用nanobot cron命令。这是因为内置工具由 Agent 循环直接调度能保证任务作为会话内定时 turn 正确运行而通过exec走 CLI 属于绕过机制的反模式。获取会话上下文从当前会话中取得USER_ID与CHANNEL例如从telegram:8281248569这样的会话标识中拆出8281248569与telegram用于把任务归属到正确的聊天与频道。2.2 cron 工具的三种模式与调用示例仓库内置的 cron 技能文档 nanobot/skills/cron/SKILL.md 把定时任务划分为三种模式与 AGENTS.md 的指引一一对应Reminder提醒消息直接发送给用户。Task任务消息是任务描述Agent 每次到点执行并把结果发回。One-time一次性在指定时间运行一次后自动删除。技能文档给出了可直接套用的调用示例# 固定提醒每 1200 秒20 分钟提醒一次 cron(actionadd, messageTime to take a break!, every_seconds1200) # 动态任务每次到点由 Agent 执行并回报结果 cron(actionadd, messageCheck HKUDS/nanobot GitHub stars and report, every_seconds600) # 一次性定时任务at 参数传 ISO 格式时间从当前时间推算 cron(actionadd, messageRemind me about the meeting, atISO datetime) # 时区感知的 cron 表达式工作日早上 9 点温哥华时区 cron(actionadd, messageMorning standup, cron_expr0 9 * * 1-5, tzAmerica/Vancouver) # 列出 / 移除任务 cron(actionlist) cron(actionremove, job_idabc123)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 什么场景不要用 cronAGENTS.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-L330class HeartbeatConfig(Base): Heartbeat service configuration (now backed by cron). enabled: bool True interval_s: int 30 * 60 # 30 minutes即默认enabledTrue、巡检间隔 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何时用 cronAGENTS.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 行为配置”可以这样组织AGENTS.md写下项目特定的约定——例如“所有定时提醒一律使用内置cron工具禁止用 exec 调用nanobot cron”“后台巡检一律进 HEARTBEAT.md”等让 Agent 每次进入工作区都先读到。USER.md填写用户的时区、语言、沟通风格与技术背景让 Agent 的回复更贴合个人偏好。SOUL.md保留模板中的核心原则必要时补充个性化风格例如“回答保持简短除非用户要求详细”。memory/MEMORY.md作为跨会话长期记忆由 Agent 自动维护不要把提醒任务写在这里。HEARTBEAT.md在 “Active Tasks” 下方维护周期性后台巡检项例如“每天检查磁盘剩余空间低于 20% 才提醒我”配合gateway.heartbeat.enabledtrue与默认 30 分钟间隔interval_s运行完成任务即删除对应条目。定时提醒需要明确汇报的提醒与定时任务用内置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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
