Heartbeat Tasks【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingActive TasksCompleted三个区块各司其职 - **# Heartbeat Tasks**文件主标题同时是空内容判定时被跳过的标题行见下文 _is_heartbeat_empty 的过滤逻辑 - **## Active Tasks**待执行的周期性任务列表用户在此行下方添加任务条目 - **## Completed**已完成任务归档区。模板注释明确给出两种维护方式——把已完成任务移动到该区或直接删除。 ## 二、心跳服务的运行原理 ### 2.1 一次完整的心跳周期 HeartbeatService 的核心逻辑在 [bot/vikingbot/heartbeat/service.py](https://link.gitcode.com/i/ed0292dadc72c74d5a92e8a26285cc54) 中。服务启动后进入异步循环 _run_loop每经过 interval_s 秒休眠调用一次 _tick() 执行单轮巡检 python async def _run_loop(self) - None: while self._running: try: await asyncio.sleep(self.interval_s) if self._running: await self._tick() except asyncio.CancelledError: break except Exception as e: logger.exception(fHeartbeat error: {e})_tick()是单轮巡检的核心其流程可以概括为收集工作区 → 读取任务清单 → 唤醒 Agent → 判定结果四步通过_get_all_workspaces()枚举所有可巡检的会话工作区对每个工作区调用_read_heartbeat_file()读取其中的HEARTBEAT.md用_is_heartbeat_empty()判定清单是否无可执行内容为空则跳过该工作区对非空清单调用on_heartbeat回调把预置提示词与heartbeat元数据交给 Agent最后用is_heartbeat_noop_response()判定返回值是否代表无操作。2.2 预置提示词与 HEARTBEAT_OK 协议每次唤醒 Agent 时服务注入的固定提示词定义在源码常量HEARTBEAT_PROMPT中Read HEARTBEAT.md in your workspace (if it exists). Follow any instructions or tasks listed there. IMPORTANT: Use the message tool to send any results or updates to the user. If nothing needs attention, reply with just: HEARTBEAT_OK这条协议规定了心跳轮次中 Agent 的两个行为出口有可汇报的更新使用message工具主动把结果发送给用户无事可做原样回复令牌HEARTBEAT_OK。服务端对回复做宽松匹配。normalize_heartbeat_response()会把响应内容去掉首尾空白、转大写、并剥离下划线与空格def normalize_heartbeat_response(content: str | None) - str: if not content: return return content.strip().upper().replace(_, ).replace( , )随后is_heartbeat_noop_response()将其与规范化后的HEARTBEAT_OKHEARTBEATOK比对。因此HEARTBEAT_OK、heartbeat_ok、HEARTBEAT OK等变体都会被识别为无操作响应容错性较好。Agent 循环在 bot/vikingbot/agent/loop.py 中结合消息元数据里的heartbeat标记跳过对这类无操作响应的常规记录避免心跳轮次污染会话历史。2.3 空文件判定逻辑_is_heartbeat_empty()实现了对无任务的保守判定。它逐行扫描内容跳过以下几类行后若仍无有效内容即判定为空空行以#开头的标题行以!--开头的 HTML 注释行空复选框条目- [ ]、* [ ]、- [x]、* [x]。这意味着默认模板只有标题、注释和空复选框被视为空清单心跳会直接跳过该工作区不会白白消耗一次模型调用。反过来只要清单中出现任何一行实质任务文本Agent 就会被唤醒。三、配置文件与运行参数3.1 HeartbeatConfig 配置项心跳的启停与间隔由 bot/vikingbot/config/schema.py 中的HeartbeatConfig定义class HeartbeatConfig(BaseModel): Heartbeat service configuration. enabled: bool True interval_seconds: int 10 * 60 # Default: 5 minutes对应到配置文件即bot.heartbeat.*前缀。根据 README_CN.md 的配置总表配置默认值说明bot.heartbeat.enabledtrue是否周期检查HEARTBEAT.mdbot.heartbeat.interval_seconds600心跳间隔需要说明的是配置 schema 层的默认值是 600 秒10 分钟而 heartbeat/service.py 中作为服务构造参数兜底的DEFAULT_HEARTBEAT_INTERVAL_S 30 * 6030 分钟。实际生效值取决于装配时传入的配置——CLI 装配逻辑见下总是显式传入config.heartbeat.interval_seconds因此线上行为以配置值为准默认即 600 秒。3.2 CLI 装配链路心跳服务在 CLI 启动流程中被组装见 bot/vikingbot/cli/commands.py 的prepare_heartbeat()async def on_heartbeat( prompt: str, session_key: SessionKey | None None, metadata: dict | None None, ) - str: return await agent_loop.process_direct( prompt, session_keysession_key, metadatametadata, ) heartbeat HeartbeatService( workspaceconfig.workspace_path, on_heartbeaton_heartbeat, interval_sconfig.heartbeat.interval_seconds, enabledconfig.heartbeat.enabled, sandbox_modeconfig.sandbox.mode, session_managersession_manager, )关键点是on_heartbeat回调直接复用了 Agent 主循环的process_direct因此心跳唤醒的本质上就是一次定向注入提示词的 Agent 执行与普通对话共用同一套工具与安全边界。启动时控制台会打印✓ Heartbeat: every {interval}s或禁用提示commands.py。四、工作区枚举与跳过规则4.1 会话与工作区的映射_get_all_workspaces()通过session_manager.list_sessions()枚举会话再根据沙箱模式解析每个会话对应的工作区路径shared模式所有会话共享workspace / shared目录下的同一个 HEARTBEAT.md其他模式调用resolve_workspace_path()位于 bot/vikingbot/utils/session_paths.py按会话维度解析独立工作区。4.2 三类被跳过的会话从_get_all_workspaces()与_is_session_stale()的实现可以归纳出三类不会触发心跳的会话显式禁用会话元数据中带skip_heartbeat: true则跳过。设置入口在 bot/vikingbot/session/manager.py 的get_or_create(key, skip_heartbeatFalse)Agent 主循环在创建会话时对 CLI/直连会话默认开启跳过loop.py 中session_key.type cli长期不活跃会话的updated_at/created_at距当前超过STALE_SESSION_THRESHOLD timedelta(days2)即视为失活service.py空任务清单HEARTBEAT.md 不存在或_is_heartbeat_empty()判定为空。这类三级跳过保证了心跳只在确有任务、确有活跃用户的工作区上消耗模型预算。五、Heartbeat 与 Cron 的边界心跳机制常与定时任务混淆TOOLS.md 与 02-agent-capabilities.md 均明确了两者的分工维度CronHeartbeat触发方式at一次性、every_seconds固定间隔、cron_expr日历表达式周期读取HEARTBEAT.md精度精确时间点/间隔尽力而为best-effort不适合精确到秒的提醒适用场景一次性提醒、固定时刻任务持续巡检一组可能变化的任务内容来源调度时指定任务工作区中的HEARTBEAT.md文件同一份文档还给出了使用边界只有用户明确要求持续周期检查时才应修改 HEARTBEAT.md任务指令应当具体、安全、幂等过时任务要及时移除而非永久悬挂。这正呼应了模板中Move completed tasks here or delete them的维护约定。六、实战编写你的心跳任务清单在活动 Workspace首次使用时从 bot/workspace 模板复制中编辑 HEARTBEAT.md把周期任务写入## Active Tasks区块。一个可直接套用的示例# Heartbeat Tasks ## Active Tasks - [ ] 检查工作区临时目录删除超过 7 天的构建产物 - [ ] 汇总最近 24 小时来自各渠道的待办消息通过 message 工具汇报 - [ ] 巡检 OpenViking 资源索引标记失效资源 ## Completed !-- Move completed tasks here or delete them -- - [x] 清理上周的过期日志已完成2026-09-01【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Heartbeat Tasks
Heartbeat Tasks【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingActive TasksCompleted三个区块各司其职 - **# Heartbeat Tasks**文件主标题同时是空内容判定时被跳过的标题行见下文 _is_heartbeat_empty 的过滤逻辑 - **## Active Tasks**待执行的周期性任务列表用户在此行下方添加任务条目 - **## Completed**已完成任务归档区。模板注释明确给出两种维护方式——把已完成任务移动到该区或直接删除。 ## 二、心跳服务的运行原理 ### 2.1 一次完整的心跳周期 HeartbeatService 的核心逻辑在 [bot/vikingbot/heartbeat/service.py](https://link.gitcode.com/i/ed0292dadc72c74d5a92e8a26285cc54) 中。服务启动后进入异步循环 _run_loop每经过 interval_s 秒休眠调用一次 _tick() 执行单轮巡检 python async def _run_loop(self) - None: while self._running: try: await asyncio.sleep(self.interval_s) if self._running: await self._tick() except asyncio.CancelledError: break except Exception as e: logger.exception(fHeartbeat error: {e})_tick()是单轮巡检的核心其流程可以概括为收集工作区 → 读取任务清单 → 唤醒 Agent → 判定结果四步通过_get_all_workspaces()枚举所有可巡检的会话工作区对每个工作区调用_read_heartbeat_file()读取其中的HEARTBEAT.md用_is_heartbeat_empty()判定清单是否无可执行内容为空则跳过该工作区对非空清单调用on_heartbeat回调把预置提示词与heartbeat元数据交给 Agent最后用is_heartbeat_noop_response()判定返回值是否代表无操作。2.2 预置提示词与 HEARTBEAT_OK 协议每次唤醒 Agent 时服务注入的固定提示词定义在源码常量HEARTBEAT_PROMPT中Read HEARTBEAT.md in your workspace (if it exists). Follow any instructions or tasks listed there. IMPORTANT: Use the message tool to send any results or updates to the user. If nothing needs attention, reply with just: HEARTBEAT_OK这条协议规定了心跳轮次中 Agent 的两个行为出口有可汇报的更新使用message工具主动把结果发送给用户无事可做原样回复令牌HEARTBEAT_OK。服务端对回复做宽松匹配。normalize_heartbeat_response()会把响应内容去掉首尾空白、转大写、并剥离下划线与空格def normalize_heartbeat_response(content: str | None) - str: if not content: return return content.strip().upper().replace(_, ).replace( , )随后is_heartbeat_noop_response()将其与规范化后的HEARTBEAT_OKHEARTBEATOK比对。因此HEARTBEAT_OK、heartbeat_ok、HEARTBEAT OK等变体都会被识别为无操作响应容错性较好。Agent 循环在 bot/vikingbot/agent/loop.py 中结合消息元数据里的heartbeat标记跳过对这类无操作响应的常规记录避免心跳轮次污染会话历史。2.3 空文件判定逻辑_is_heartbeat_empty()实现了对无任务的保守判定。它逐行扫描内容跳过以下几类行后若仍无有效内容即判定为空空行以#开头的标题行以!--开头的 HTML 注释行空复选框条目- [ ]、* [ ]、- [x]、* [x]。这意味着默认模板只有标题、注释和空复选框被视为空清单心跳会直接跳过该工作区不会白白消耗一次模型调用。反过来只要清单中出现任何一行实质任务文本Agent 就会被唤醒。三、配置文件与运行参数3.1 HeartbeatConfig 配置项心跳的启停与间隔由 bot/vikingbot/config/schema.py 中的HeartbeatConfig定义class HeartbeatConfig(BaseModel): Heartbeat service configuration. enabled: bool True interval_seconds: int 10 * 60 # Default: 5 minutes对应到配置文件即bot.heartbeat.*前缀。根据 README_CN.md 的配置总表配置默认值说明bot.heartbeat.enabledtrue是否周期检查HEARTBEAT.mdbot.heartbeat.interval_seconds600心跳间隔需要说明的是配置 schema 层的默认值是 600 秒10 分钟而 heartbeat/service.py 中作为服务构造参数兜底的DEFAULT_HEARTBEAT_INTERVAL_S 30 * 6030 分钟。实际生效值取决于装配时传入的配置——CLI 装配逻辑见下总是显式传入config.heartbeat.interval_seconds因此线上行为以配置值为准默认即 600 秒。3.2 CLI 装配链路心跳服务在 CLI 启动流程中被组装见 bot/vikingbot/cli/commands.py 的prepare_heartbeat()async def on_heartbeat( prompt: str, session_key: SessionKey | None None, metadata: dict | None None, ) - str: return await agent_loop.process_direct( prompt, session_keysession_key, metadatametadata, ) heartbeat HeartbeatService( workspaceconfig.workspace_path, on_heartbeaton_heartbeat, interval_sconfig.heartbeat.interval_seconds, enabledconfig.heartbeat.enabled, sandbox_modeconfig.sandbox.mode, session_managersession_manager, )关键点是on_heartbeat回调直接复用了 Agent 主循环的process_direct因此心跳唤醒的本质上就是一次定向注入提示词的 Agent 执行与普通对话共用同一套工具与安全边界。启动时控制台会打印✓ Heartbeat: every {interval}s或禁用提示commands.py。四、工作区枚举与跳过规则4.1 会话与工作区的映射_get_all_workspaces()通过session_manager.list_sessions()枚举会话再根据沙箱模式解析每个会话对应的工作区路径shared模式所有会话共享workspace / shared目录下的同一个 HEARTBEAT.md其他模式调用resolve_workspace_path()位于 bot/vikingbot/utils/session_paths.py按会话维度解析独立工作区。4.2 三类被跳过的会话从_get_all_workspaces()与_is_session_stale()的实现可以归纳出三类不会触发心跳的会话显式禁用会话元数据中带skip_heartbeat: true则跳过。设置入口在 bot/vikingbot/session/manager.py 的get_or_create(key, skip_heartbeatFalse)Agent 主循环在创建会话时对 CLI/直连会话默认开启跳过loop.py 中session_key.type cli长期不活跃会话的updated_at/created_at距当前超过STALE_SESSION_THRESHOLD timedelta(days2)即视为失活service.py空任务清单HEARTBEAT.md 不存在或_is_heartbeat_empty()判定为空。这类三级跳过保证了心跳只在确有任务、确有活跃用户的工作区上消耗模型预算。五、Heartbeat 与 Cron 的边界心跳机制常与定时任务混淆TOOLS.md 与 02-agent-capabilities.md 均明确了两者的分工维度CronHeartbeat触发方式at一次性、every_seconds固定间隔、cron_expr日历表达式周期读取HEARTBEAT.md精度精确时间点/间隔尽力而为best-effort不适合精确到秒的提醒适用场景一次性提醒、固定时刻任务持续巡检一组可能变化的任务内容来源调度时指定任务工作区中的HEARTBEAT.md文件同一份文档还给出了使用边界只有用户明确要求持续周期检查时才应修改 HEARTBEAT.md任务指令应当具体、安全、幂等过时任务要及时移除而非永久悬挂。这正呼应了模板中Move completed tasks here or delete them的维护约定。六、实战编写你的心跳任务清单在活动 Workspace首次使用时从 bot/workspace 模板复制中编辑 HEARTBEAT.md把周期任务写入## Active Tasks区块。一个可直接套用的示例# Heartbeat Tasks ## Active Tasks - [ ] 检查工作区临时目录删除超过 7 天的构建产物 - [ ] 汇总最近 24 小时来自各渠道的待办消息通过 message 工具汇报 - [ ] 巡检 OpenViking 资源索引标记失效资源 ## Completed !-- Move completed tasks here or delete them -- - [x] 清理上周的过期日志已完成2026-09-01【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考