hermes教程-Cron 内部机制

关键文件

调度模型

支持四种调度格式：

面向模型的接口是一个单一的 cronjob 工具，支持动作式操作：create、list、update、pause、resume、run、remove。

任务存储

任务存储在 ~/.hermes/cron/jobs.json 中，采用原子写入语义（先写入临时文件，再重命名）。每个任务记录包含：

{
  "id": "a1b2c3d4e5f6",
  "name": "每日简报",
  "prompt": "总结今天的 AI 新闻和融资轮次",
  "schedule": {
    "kind": "cron",
    "expr": "0 9 * * *",
    "display": "0 9 * * *"
  },
  "skills": ["ai-funding-daily-report"],
  "deliver": "telegram:-1001234567890",
  "repeat": {
    "times": null,
    "completed": 42
  },
  "state": "scheduled",
  "enabled": true,
  "next_run_at": "2025-01-16T09:00:00Z",
  "last_run_at": "2025-01-15T09:00:00Z",
  "last_status": "ok",
  "created_at": "2025-01-01T00:00:00Z",
  "model": null,
  "provider": null,
  "script": null
}

任务生命周期状态

向后兼容

旧版任务可能使用单个 skill 字段而非 skills 数组。调度器在加载时会将其规范化——单个 skill 会被提升为 skills: [skill]。

调度器运行时

滴答周期

调度器按周期性滴答运行（默认每 60 秒）：

tick()
  1. 获取调度器锁（防止滴答重叠）
  2. 从 jobs.json 加载所有任务
  3. 筛选出到期任务（next_run <= now 且 state == "scheduled"）
  4. 对每个到期任务：
     a. 将状态设为 "running"
     b. 创建全新的 AIAgent 会话（无对话历史）
     c. 按顺序加载附加的技能（作为用户消息注入）
     d. 通过代理运行任务提示
     e. 将响应投递到配置的目标
     f. 更新 run_count，计算 next_run
     g. 如果重复次数已耗尽 → state = "completed"
     h. 否则 → state = "scheduled"
  5. 将更新后的任务写回 jobs.json
  6. 释放调度器锁

网关集成

在网关模式下，调度器在专用的后台线程中运行（gateway/run.py 中的 _start_cron_ticker），该线程每 60 秒调用 scheduler.tick()，与消息处理并行。

在 CLI 模式下，cron 任务仅在运行 hermes cron 命令或处于活跃 CLI 会话期间触发。

全新会话隔离

每个 cron 任务都在一个完全全新的代理会话中运行：

• 没有之前运行的对话历史
• 没有之前 cron 执行的记忆（除非持久化到内存/文件）
• 提示必须自包含——cron 任务不能提出澄清性问题
• cronjob 工具集被禁用（递归防护）

技能支持的任务

cron 任务可以通过 skills 字段附加一个或多个技能。执行时：

1. 按指定顺序加载技能
2. 每个技能的 SKILL.md 内容作为上下文注入
3. 任务的提示作为任务指令附加
4. 代理处理组合的技能上下文 + 提示

这使得可以重用经过测试的工作流，而无需将完整指令粘贴到 cron 提示中。例如：

脚本支持的任务

任务还可以通过 script 字段附加一个 Python 脚本。该脚本在每次代理轮次之前运行，其标准输出作为上下文注入到提示中。这支持数据收集和变更检测模式：

## ~/.hermes/scripts/check_competitors.py
import requests, json
## 获取竞争对手发布说明，与上次运行对比
## 将摘要输出到标准输出——代理分析并报告

脚本超时默认为 120 秒。_get_script_timeout() 通过三层链解析限制：

1. 模块级覆盖——_SCRIPT_TIMEOUT（用于测试/猴子补丁）。仅当与默认值不同时使用。
2. 环境变量——HERMES_CRON_SCRIPT_TIMEOUT
3. 配置——config.yaml 中的 cron.script_timeout_seconds（通过 load_config() 读取）
4. 默认值——120 秒

提供商恢复

run_job() 将用户配置的回退提供商和凭据池传递给 AIAgent 实例：

• 回退提供商——从 config.yaml 读取 fallback_providers（列表）或 fallback_model（旧版字典），匹配网关的 _load_fallback_model() 模式。作为 fallback_model= 传递给 AIAgent.__init__，该函数将两种格式规范化为回退链。
• 凭据池——通过 agent.credential_pool 中的 load_pool(provider) 加载，使用解析后的运行时提供商名称。仅当池中有凭据时传递（pool.has_credentials()）。支持在 429/速率限制错误时进行同提供商密钥轮换。

这镜像了网关的行为——没有它，cron 代理会在速率限制时失败而不尝试恢复。

投递模型

cron 任务结果可以投递到任何支持的平台：

对于 Telegram 话题，使用格式 telegram:<chat_id>:<thread_id>（例如 telegram:-1001234567890:17585）。

响应包装

默认情况下（cron.wrap_response: true），cron 投递会被包装：

• 一个头部，标识 cron 任务名称和任务
• 一个脚注，说明代理无法在对话中看到已投递的消息

cron 响应中的 [SILENT] 前缀会完全抑制投递——适用于仅需写入文件或执行副作用的任务。

会话隔离

cron 投递不会镜像到网关会话的对话历史中。它们仅存在于 cron 任务自身的会话中。这防止了目标聊天对话中的消息交替违规。

递归防护

cron 运行的会话禁用了 cronjob 工具集。这防止了：

• 调度任务创建新的 cron 任务
• 可能导致令牌使用量激增的递归调度
• 在任务内部意外修改任务调度

锁定

调度器使用跨进程的基于文件的锁定（Unix 上为 fcntl.flock，Windows 上为 msvcrt.locking）来防止重叠的滴答执行同一批到期任务两次——即使在网关的进程内滴答器与独立的 hermes cron / 手动 tick() 调用之间也是如此。如果无法获取锁，tick() 会立即返回 0。

CLI 接口

hermes cron CLI 提供直接的任务管理：

hermes cron list                    # 显示所有任务
hermes cron create                  # 交互式创建任务（别名：add）
hermes cron edit <job_id>           # 编辑任务配置
hermes cron pause <job_id>          # 暂停运行中的任务
hermes cron resume <job_id>         # 恢复暂停的任务
hermes cron run <job_id>            # 立即触发执行
hermes cron remove <job_id>         # 删除任务

相关文档

• Cron 功能指南
• 网关内部机制
• 代理循环内部机制