OpenViking vikingbot Cron 技能指南用cron工具为 Agent 编排提醒与定时任务【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking导读本指南围绕 OpenViking 仓库中 vikingbot 的内置技能文档 bot/workspace/skills/cron/SKILL.md 展开系统讲解如何通过cron工具为 AI Agent 调度一次性提醒与周期性任务。读完本文你将掌握三种任务模式Reminder / Task / One-time的选型原则、完整工具参数语义、时间表达式与 ISO 时间戳的换算方法并理解其背后的定时调度服务、持久化存储与 CLI 管理命令能够在自己的 vikingbot 会话中直接落地使用。技能概览Agent 侧的cron工具cron技能位于 bot/workspace/skills/cron/SKILL.mdfrontmatter 声明如下--- name: cron description: Schedule reminders and recurring tasks. ---它属于 vikingbot 的 内置技能体系——每个技能都是一个目录内含带 YAML frontmattername、description、元数据与 Markdown 指令的SKILL.md文件。该技能的核心指引只有一句话使用cron工具来安排提醒reminders或重复任务recurring tasks。在 vikingbot 中cron是一个真实的 Agent 工具Tool其实现位于 bot/vikingbot/agent/tools/cron.py通过 工具注册工厂 在include_cron_tool且传入cron_service时注册到工具注册表。Agent 在会话中调用该工具即可在底层 CronService 上增删改查定时任务并把结果持久化到磁盘上的cron/jobs.json。三种任务模式技能文档定义了cron工具的三种模式理解它们是正确选型的第一步模式行为典型场景Reminder提醒消息直接发送给用户休息提醒、会议提醒、吃药提醒Task任务消息是一段任务描述Agent 执行并把结果发回周期性抓取 GitHub Star 数并汇报One-time一次性在指定时刻仅运行一次运行后自动删除一次性定时提醒、预约执行前两者在调度周期上本质相同都是按固定间隔重复区别在于message的语义Reminder 直接透传文本Task 则让 Agent 将 message 当作任务描述去执行并汇报结果。第三种 One-time 模式对应at参数执行一次后任务即被自动清理。基础用法示例技能文档给出的示例可以直接在会话中调用固定间隔提醒Reminder——每 20 分钟提醒一次休息cron(actionadd, messageTime to take a break!, every_seconds1200)动态任务Task——每 10 分钟让 Agent 查询 HKUDS/vikingbot 的 GitHub Star 数并汇报cron(actionadd, messageCheck HKUDS/vikingbot GitHub stars and report, every_seconds600)一次性定时任务One-time——用 ISO 时间戳指定精确时刻需要先从当前时间推算目标时间cron(actionadd, messageRemind me about the meeting, atISO datetime)列出与删除任务cron(actionlist) cron(actionremove, job_idabc123)从 CronTool.parameters 可以看出action是必填参数取值枚举为add/list/removejob_id仅用于remove。执行结果以文本返回例如创建成功返回Created job xxx (id: xxxxxxxx)列表为空返回No scheduled jobs.删除不存在的任务返回Job xxxx not found。时间表达式速查表技能文档给出了一张「用户说法 → 工具参数」的换算表是编排任务时最常用的参考用户说法参数every 20 minutesevery_seconds: 1200every hourevery_seconds: 3600every day at 8amcron_expr: 0 8 * * *weekdays at 5pmcron_expr: 0 17 * * 1-5at a specific timeat: ISO datetime string从当前时间推算需要补充的是cron_expr使用标准五段 cron 表达式分 时 日 月 周1-5表示周一至周五at必须是 ISO 8601 格式时间字符串。两种周期型调度还支持通过timezone参数指定 IANA 时区如Asia/Shanghai让 cron 表达式在目标时区下求值——但注意 工具实现 明确规定timezone仅在与cron_expr搭配时有效单独使用会返回错误。工具参数完整语义综合 CronTool.parameters 与 CronSchedule 的字段定义cron工具在add动作下支持以下参数参数类型说明actionstring必填add/list/removenamestring任务名称用于add便于list时辨识messagestring提醒文本或任务描述add必填为空会报错every_secondsinteger周期调度每 N 秒运行一次cron_exprstring周期调度标准 cron 表达式如0 9 * * *timezonestringIANA 时区如Asia/Shanghai仅配合cron_expr使用atstring一次性调度ISO 8601 时间戳job_idstring任务 ID仅用于removeadd分支的三路调度选择逻辑如下见 bot/vikingbot/agent/tools/cron.py#L96-L141若提供every_seconds→ 构造CronSchedule(kindevery, every_msevery_seconds * 1000)否则若提供cron_expr→ 构造CronSchedule(kindcron, exprcron_expr, tztimezone)否则若提供at→ 先用parse_iso_datetime解析为 datetime再换算为毫秒时间戳构造CronSchedule(kindat, at_ms...)并自动设置delete_after_runTrue三者皆无 → 返回错误Error: either every_seconds, cron_expr, or at is required。同时add会自动带上会话上下文将当前会话的session_key与渠道元数据reply_to、chat_type、chat_mode、root_id、sender_id等见 DELIVERY_METADATA_KEYS绑定到任务上确保任务到期后能在正确的会话与渠道中投递。底层实现CronService 调度引擎技能文档描述的是 Agent 侧的使用契约而真正驱动任务到点执行的是 bot/vikingbot/cron/service.py 中的CronService。理解它有助于排查问题或评估能力边界。三种调度内核_compute_next_runservice.py#L35-L63按schedule.kind分派at比较目标毫秒时间戳与当前时间未来则返回目标值否则返回None表示已过期every直接返回now every_ms即从当前时刻起滚动计算下一个周期cron借助croniter库在指定 IANA 时区或本地时区内对 cron 表达式求下一个匹配时刻换算为毫秒时间戳返回。任何异常如时区不存在、表达式非法都会导致返回None配合_validate_schedule_timezone在添加任务时用ZoneInfo校验时区非法时区会抛出ValueError: Invalid cron timezone: ...。事件驱动而非轮询服务启动后调用_arm_timerservice.py#L210-L227计算所有启用任务中最早的下一次唤醒时间用asyncio.sleep精确睡到该时刻到点后_on_timer收集所有到期任务逐个执行保存状态并重新武装定时器。因此它是事件驱动的空闲时不占用 CPU。执行与状态机_execute_jobservice.py#L247-L278通过构造时传入的on_job回调执行任务回调返回响应文本并维护每个任务的运行状态next_run_at_ms、last_run_at_ms、last_statusok/error/skipped、last_error。异常会被捕获并记录不会拖垮整个服务。对一次性任务kind at执行后按delete_after_run决定是物理删除还是禁用并清空下次运行时间周期任务则重新计算下一次运行时刻。JSON 持久化所有任务以 JSON 文件落盘默认位于数据目录下的cron/jobs.json见 CLI 实现文件结构由_save_store/_load_storeservice.py#L80-L172维护顶层包含version与jobs数组每个任务序列化id、name、enabled、schedulekind/atMs/everyMs/expr/tz、payload、state、时间戳与deleteAfterRun。数据模型完整定义见 bot/vikingbot/cron/types.py。由于任务持久化在磁盘服务重启后会自动加载并重算各任务的下一运行时刻实现跨重启的可靠性。CLI 管理命令除了会话内由 Agent 调用工具vikingbot 还提供了同等的命令行管理入口基于 typer 实现见 bot/vikingbot/cli/commands.py#L1071-L1220便于运维人员直接查看和干预# 列出任务-a/--all 包含已禁用任务 vikingbot cron list # 添加周期任务每 10 分钟 vikingbot cron add --name star-check --message Check HKUDS/vikingbot stars and report --every 600 # 添加 cron 表达式任务每天 9 点Asia/Shanghai 时区 vikingbot cron add --name morning --message good morning --cron 0 9 * * * --timezone Asia/Shanghai # 添加一次性任务 vikingbot cron add --name release --message ship it --at 2099-08-17T10:00:00Z # 删除 / 启停 / 手动执行 vikingbot cron remove job_id vikingbot cron enable job_id # --disable 表示禁用 vikingbot cron run job_idlist命令以表格形式输出任务 ID、名称、调度方式every Ns/ cron 表达式 /one-time、状态与下次运行时间add与工具侧保持一致的调度校验逻辑--timezone必须搭配--cron、三选一必须命中其一、--at必须是合法 ISO 时间。ISO 时间戳的解析细节One-time 模式要求at为 ISO 8601 格式其解析逻辑复用 openviking/utils/time_utils.py 中的parse_iso_datetime。该函数有两个值得注意的容错处理Z后缀归一化2026-02-12T10:30:00Z会被转换为带00:00时区偏移的字符串再解析超长小数秒截断Windows 等环境可能产生超过 6 位小数秒的时间戳如2026-02-21T13:20:23.147004208:00Python 原生解析会失败该函数会先用正则把小数部分截断到 6 位再解析。bot/tests/test_cron_datetime_parsing.py 中的回归测试直接验证了这些行为at2099-08-17T10:00:00Z能被正确换算为毫秒时间戳4090644000000非法字符串not-a-date会被拒并返回Error: invalid at datetime:同时验证了Asia/Shanghai与America/Los_Angeles下同一 cron 表达式0 9 * * *会计算出不同的 UTC 时刻非法时区Mars/Olympus会被拒绝——这说明时区语义在工具、CLI 与服务三层是保持一致并被测试覆盖的。实操建议与注意事项区分 Reminder 与 Task只希望用户看到文字就用 Reminder需要 Agent 每次执行动作并回传结果就用 Task。同一every_seconds调度下二者成本不同动态任务会真实占用 Agent 执行轮次。every是从当下滚动计算由_compute_next_run的实现可知every模式以每次执行为起点推算下一时刻而非固定锚点长时间运行后可能与整点偏移需要精确锚定请使用cron_expr。One-time 任务自动清理at模式默认delete_after_runTrue执行后即从任务列表中消失如果希望保留记录可通过服务层add_job(delete_after_runFalse)保留为禁用状态。时区一致性cron_expr的求值受timezone影响务必按业务用户所在时区显式指定如Asia/Shanghai避免跨时区错位。持久化位置任务落在数据目录cron/jobs.json备份数据目录即可保留全部定时任务服务重启后会自动重算下次运行时间无需重新录入。小结cron技能是 vikingbot 让 Agent 从被动应答走向主动服务的关键一环Agent 侧一行工具调用即可注册提醒、周期任务或一次性任务底层 CronService 以事件驱动定时器、croniter表达式求值和 JSON 持久化保障任务准确、可靠、跨重启地执行CLI 命令则提供了等价的运维视角。掌握 SKILL.md 中的三种模式与时间表达式速查表配合本文补充的参数语义与实现原理即可为你的 Agent 高效编排各类定时能力。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
