better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/cron.md

@@ -1,761 +0,0 @@
----
-sidebar_position: 5
-title: "定时任务（Cron）"
-description: "用自然语言调度自动化任务，通过单一 cron 工具管理，并附加一个或多个 skill"
----
-
-# 定时任务（Cron）
-
-使用自然语言或 cron 表达式调度自动运行的任务。Hermes 通过单一 `cronjob` 工具暴露 cron 管理能力，采用动作式操作，而非分散的 schedule/list/remove 工具。
-
-## Cron 当前能做什么
-
-Cron 任务可以：
-
-- 调度一次性或周期性任务
-- 暂停、恢复、编辑、触发和删除任务
-- 为任务附加零个、一个或多个 skill
-- 将结果回传到来源会话、本地文件或已配置的平台目标
-- 在全新的 agent 会话中运行，使用正常的静态工具列表
-- 以**无 agent 模式**运行——按计划执行脚本，其 stdout 原样投递，零 LLM 参与（参见下方[无 agent 模式](#no-agent-mode-script-only-jobs)章节）
-- 由**外部事件触发**——设置了 `cron_job` 的 webhook 路由会在事情发生的那一刻（PR 收到反馈、服务发出告警）立即触发任务，而不是等待下一次定时 tick。参见[事件触发的 Cron 任务](/user-guide/messaging/webhooks#event-triggered-cron-jobs)。
-
-所有这些功能均可通过 `cronjob` 工具由 Hermes 自身使用，因此你可以用自然语言创建、暂停、编辑和删除任务——无需 CLI。
-
-:::warning
-Cron 运行的会话不能递归创建更多 cron 任务。Hermes 在 cron 执行内部禁用了 cron 管理工具，以防止失控的调度循环。
-:::
-
-## 创建定时任务
-
-### 在聊天中使用 `/cron`
-
-```bash
-/cron add 30m "Remind me to check the build"
-/cron add "every 2h" "Check server status"
-/cron add "every 1h" "Summarize new feed items" --skill blogwatcher
-/cron add "every 1h" "Use both skills and combine the result" --skill blogwatcher --skill maps
-```
-
-### 从独立 CLI
-
-```bash
-hermes cron create "every 2h" "Check server status"
-hermes cron create "every 1h" "Summarize new feed items" --skill blogwatcher
-hermes cron create "every 1h" "Use both skills and combine the result" \
-  --skill blogwatcher \
-  --skill maps \
-  --name "Skill combo"
-```
-
-### 通过自然对话
-
-直接向 Hermes 描述：
-
-```text
-Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.
-```
-
-Hermes 会在内部使用统一的 `cronjob` 工具。
-
-## 附带 skill 的 cron 任务
-
-Cron 任务可以在运行 prompt（提示词）之前加载一个或多个 skill。
-
-### 单个 skill
-
-```python
-cronjob(
-    action="create",
-    skill="blogwatcher",
-    prompt="Check the configured feeds and summarize anything new.",
-    schedule="0 9 * * *",
-    name="Morning feeds",
-)
-```
-
-### 多个 skill
-
-Skill 按顺序加载。Prompt 作为任务指令叠加在这些 skill 之上。
-
-```python
-cronjob(
-    action="create",
-    skills=["blogwatcher", "maps"],
-    prompt="Look for new local events and interesting nearby places, then combine them into one short brief.",
-    schedule="every 6h",
-    name="Local brief",
-)
-```
-
-当你希望定时 agent 继承可复用的工作流，而不必将完整的 skill 文本塞入 cron prompt 本身时，这非常有用。
-
-## 在指定项目目录中运行任务
-
-Cron 任务默认与任何代码仓库脱离运行——不加载 `AGENTS.md`、`CLAUDE.md` 或 `.cursorrules`，终端/文件/代码执行工具从 gateway 启动时的工作目录运行。传入 `--workdir`（CLI）或 `workdir=`（工具调用）可更改此行为：
-
-```bash
-# 独立 CLI（schedule 和 prompt 为位置参数）
-hermes cron create "every 1d at 09:00" \
-  "Audit open PRs, summarize CI health, and post to #eng" \
-  --workdir /home/me/projects/acme
-```
-
-```python
-# 在聊天中，通过 cronjob 工具
-cronjob(
-    action="create",
-    schedule="every 1d at 09:00",
-    workdir="/home/me/projects/acme",
-    prompt="Audit open PRs, summarize CI health, and post to #eng",
-)
-```
-
-设置 `workdir` 后：
-
-- 该目录中的 `AGENTS.md`、`CLAUDE.md` 和 `.cursorrules` 会被注入系统 prompt（发现顺序与交互式 CLI 相同）
-- `terminal`、`read_file`、`write_file`、`patch`、`search_files` 和 `execute_code` 均以该目录为工作目录
-- 路径必须是已存在的绝对目录——相对路径和不存在的目录在创建/更新时会被拒绝
-- 编辑时传入 `--workdir ""`（或工具中的 `workdir=""`）可清除该设置并恢复原有行为
-
-:::note 隔离
-每次 agent 运行都会将其 `workdir` 绑定到该次运行的唯一任务标识。设置了 workdir 的任务因此可使用正常的并行池，不会修改进程全局终端状态，也不会在并发运行之间泄漏路径。如需限制 cron 的总并发量，请设置 `cron.max_parallel_jobs`。
-:::
-
-## 在指定 profile 中运行 cron 任务
-
-默认情况下，cron 任务继承创建它的 gateway/CLI 所属的 Hermes profile。传入 `--profile <name>`（CLI）或 `profile=`（cronjob 工具）可将任务重定向到不同的 profile——调度器会解析该 profile 的 `HERMES_HOME`，在运行期间临时切换到该 profile，加载其 `.env` 和 `config.yaml`，并在其中执行任务：
-
-```bash
-# 将任务固定到 `night-ops` profile，无论在哪里调度
-hermes cron create "every 1d at 03:00" \
-  "Tail the security log and flag anomalies" \
-  --profile night-ops
-```
-
-```python
-# 在聊天中，通过 cronjob 工具
-cronjob(
-    action="create",
-    schedule="every 1d at 03:00",
-    prompt="Tail the security log and flag anomalies",
-    profile="night-ops",
-)
-```
-
-使用 `--profile default` 可显式固定到根 Hermes profile。指定的 profile 必须已存在；调度器不会动态创建 profile。在 `cron edit` 时清除 profile 固定，传入空字符串（`--profile ""` 或 `profile=""`）——任务将恢复在调度器当前所在的 profile 中运行。
-
-如果固定的 profile 后来被删除，调度器会记录警告并回退到在当前 profile 中运行该任务，而不是崩溃——因此过期的 `profile` 引用不会卡住任务。
-
-:::note 串行化
-设置了 `profile` 的任务也串行运行，原因与 `workdir` 固定任务相同：切换 `HERMES_HOME` 是进程全局变更，两个 profile 固定任务并行运行会产生竞争。未固定的任务仍在正常并行池中运行。
-:::
-
-## 编辑任务
-
-无需删除并重建任务来修改它们。
-
-:::tip 任务引用
-下方（以及[生命周期操作](#lifecycle-actions)中）的 `<job_id>` 占位符也接受任务名称（不区分大小写）——当你记得 `morning-digest` 但不记得十六进制 ID 时很方便。精确的任务 ID 优先于名称匹配；如果引用不是 ID 且名称匹配到多个任务，命令会拒绝执行并打印候选 ID 供你消歧义。
-:::
-
-### 聊天
-
-```bash
-/cron edit <job_id> --schedule "every 4h"
-/cron edit <job_id> --prompt "Use the revised task"
-/cron edit <job_id> --skill blogwatcher --skill maps
-/cron edit <job_id> --remove-skill blogwatcher
-/cron edit <job_id> --clear-skills
-```
-
-### 独立 CLI
-
-```bash
-hermes cron edit <job_id> --schedule "every 4h"
-hermes cron edit <job_id> --prompt "Use the revised task"
-hermes cron edit <job_id> --skill blogwatcher --skill maps
-hermes cron edit <job_id> --add-skill maps
-hermes cron edit <job_id> --remove-skill blogwatcher
-hermes cron edit <job_id> --clear-skills
-```
-
-注意：
-
-- 重复使用 `--skill` 会替换任务已附加的 skill 列表
-- `--add-skill` 追加到现有列表，不替换
-- `--remove-skill` 删除指定的已附加 skill
-- `--clear-skills` 删除所有已附加的 skill
-
-## 生命周期操作
-
-Cron 任务现在拥有比创建/删除更完整的生命周期。
-
-### 聊天
-
-```bash
-/cron list
-/cron pause <job_id>
-/cron resume <job_id>
-/cron run <job_id>
-/cron remove <job_id>
-```
-
-### 独立 CLI
-
-```bash
-hermes cron list
-hermes cron pause <job_id>
-hermes cron resume <job_id>
-hermes cron run <job_id>
-hermes cron remove <job_id>
-hermes cron status
-hermes cron tick
-```
-
-各操作说明：
-
-- `pause` — 保留任务但停止调度
-- `resume` — 重新启用任务并计算下次运行时间
-- `run` — 在下次调度器 tick 时触发任务
-- `remove` — 彻底删除任务
-
-## 工作原理
-
-**Cron 执行由 gateway 守护进程处理。** Gateway 每 60 秒 tick 一次调度器，在隔离的 agent 会话中运行到期的任务。
-
-```bash
-hermes gateway install     # 安装为用户服务
-sudo hermes gateway install --system   # Linux：服务器开机启动的系统服务
-hermes gateway             # 或在前台运行
-
-hermes cron list
-hermes cron status
-```
-
-### Gateway 调度器行为
-
-每次 tick 时，Hermes：
-
-1. 从 `~/.hermes/cron/jobs.json` 加载任务
-2. 对照当前时间检查 `next_run_at`
-3. 为每个到期任务启动全新的 `AIAgent` 会话
-4. 可选地将一个或多个已附加的 skill 注入该新会话
-5. 将 prompt 运行至完成
-6. 投递最终响应
-7. 更新运行元数据和下次调度时间
-
-`~/.hermes/cron/.tick.lock` 文件锁可防止重叠的调度器 tick 重复运行同一批任务。
-
-### 执行历史
-
-Hermes 会在执行器或调度提供程序分派之前，将每次已领取的 cron 尝试记录到当前 profile 的 `~/.hermes/cron/executions.db`。尝试会依次进入 `claimed`、`running`，然后进入不可变的终态：`completed`、`failed` 或 `unknown`。重启后，只有原 PID 与进程启动时间指纹能够证明所有者已经消失时，Hermes 才会将遗留尝试标记为 `unknown`。未知尝试仅用于审计，绝不会自动重跑。
-
-使用 `hermes cron runs [job-id] --limit 20`（别名：`history`）查看最近的尝试。终态历史有界，活动尝试不会被清理；快速备份也包含该账本。
-
-## 投递选项
-
-调度任务时，你可以指定输出的去向：
-
-| 选项 | 说明 | 示例 |
-|--------|-------------|---------|
-| `"origin"` | 回传到任务创建的来源 | 消息平台上的默认值 |
-| `"local"` | 仅保存到本地文件（`~/.hermes/cron/output/`） | CLI 上的默认值 |
-| `"telegram"` | Telegram 主频道 | 使用 `TELEGRAM_HOME_CHANNEL` |
-| `"telegram:123456"` | 按 ID 指定的 Telegram 会话 | 直接投递 |
-| `"telegram:-100123:17585"` | 指定 Telegram 话题 | `chat_id:thread_id` 格式 |
-| `"discord"` | Discord 主频道 | 使用 `DISCORD_HOME_CHANNEL` |
-| `"discord:#engineering"` | 按频道名指定的 Discord 频道 | 按频道名 |
-| `"slack"` | Slack 主频道 | |
-| `"whatsapp"` | WhatsApp 主账号 | |
-| `"signal"` | Signal | |
-| `"matrix"` | Matrix 主房间 | |
-| `"mattermost"` | Mattermost 主频道 | |
-| `"email"` | 邮件 | |
-| `"sms"` | 通过 Twilio 发送 SMS | |
-| `"homeassistant"` | Home Assistant | |
-| `"dingtalk"` | 钉钉 | |
-| `"feishu"` | 飞书/Lark | |
-| `"wecom"` | 企业微信 | |
-| `"weixin"` | 微信（WeChat） | |
-| `"bluebubbles"` | BlueBubbles（iMessage） | |
-| `"qqbot"` | QQ Bot（腾讯 QQ） | |
-| `"all"` | 扇出到所有已连接的主频道 | 触发时解析 |
-| `"telegram,discord"` | 扇出到指定的一组频道 | 逗号分隔列表 |
-| `"origin,all"` | 投递到来源**加上**所有其他已连接频道 | 可组合任意 token |
-
-Agent 的最终响应会自动投递，无需在 cron prompt 中调用 `send_message`。
-
-### 路由意图（`all`）
-
-`all` 让你将一个 cron 任务发送到所有已配置的消息频道，无需逐一列举名称。它在**触发时解析**，因此在你配置 `TELEGRAM_HOME_CHANNEL` 之前创建的任务，会在下次 tick 时自动纳入 Telegram。
-
-语义：`all` 展开为所有已配置主频道的平台。零个也没问题；任务只是没有投递目标，并在上游记录为投递失败。
-
-`all` 可与显式目标组合。`origin,all` 投递到来源会话**加上**所有其他已连接的主频道，按 `(platform, chat_id, thread_id)` 去重。
-
-### Telegram cron 话题（`TELEGRAM_CRON_THREAD_ID`）
-
-启用 Telegram 话题模式后，根 DM 被保留为系统大厅——发送到那里的回复会被拒绝并附带大厅提示，`reply_to_message_id` 会被丢弃，因此你无法回复落在主聊天中的 cron 消息。
-
-将 cron 指向专用的论坛话题：
-
-1. 在 Telegram 中打开机器人 DM，创建一个名为 `Cron` 的话题。长按话题标题 → **复制链接**；末尾的整数即为该话题的 `message_thread_id`。
-2. 在 `.env` 中设置 `TELEGRAM_CRON_THREAD_ID=<该 id>`。
-
-这仅适用于 cron 投递。`TELEGRAM_HOME_CHANNEL_THREAD_ID`（用于其他地方，如重启通知）不受影响。显式的 `deliver="telegram:chat_id:thread_id"` 目标仍优先于环境变量。对 cron 消息的回复现在会进入已有的话题会话，你可以直接在其中操作。
-
-### 响应包装
-
-默认情况下，投递的 cron 输出会带有页眉和页脚，以便接收方知道这来自定时任务：
-
-```
-Cronjob Response: Morning feeds
--------------
-
-<agent output here>
-
-Note: The agent cannot see this message, and therefore cannot respond to it.
-```
-
-若要投递不带包装的原始 agent 输出，将 `cron.wrap_response` 设为 `false`：
-
-```yaml
-# ~/.hermes/config.yaml
-cron:
-  wrap_response: false
-```
-
-### 可继续任务（回复 cron 投递）
-
-默认情况下，cron 投递是「发完即忘」的：消息发送出去，但不会进入聊天的对话历史，
-因此如果你回复它，agent 并不记得自己说过什么。将任务设为**可继续**后，投递的简报
-就变成一段你可以回复进去的对话——agent 会把简报保留在上下文中，而不会反问
-「Task #2 是什么？」。
-
-选择性启用，**默认关闭**。可在配置中全局启用，或通过 `cronjob` 工具的
-`attach_to_session` 按任务启用（会覆盖该任务的全局设置）：
-
-```yaml
-# ~/.hermes/config.yaml
-cron:
-  mirror_delivery: false   # 设为 true 使 cron 投递可继续
-```
-
-行为为**优先使用话题**，范围限定在任务的来源聊天：
-
-- **支持话题的平台**（Telegram 话题、Discord/Slack 话题）：每次投递都会新建
-  专用话题，并将简报植入该话题的会话中，因此在话题内回复即可带完整上下文继续。
-- **仅 DM 的平台**（WhatsApp、Signal、SMS）：不存在话题，因此简报会被镜像进
-  来源 DM 会话——DM 本身就是继续的载体。
-
-只有来源聊天会被触及：扇出/广播目标（`all`、显式的其他聊天投递）永远不会被设为可继续。
-
-#### 平铺频道内继续（Slack）
-
-上面的优先话题行为每次投递都会新建专用话题。如果你希望可继续任务**平铺落在频道
-时间线**中——不新建话题——将 Slack 的**继续投递方式**设为 `in_channel`：
-
-```yaml
-# ~/.hermes/config.yaml
-slack:
-  cron_continuable_surface: in_channel   # 默认："thread"
-  reply_in_thread: false                 # 必需搭配（见下）
-  require_mention: false                 # 纯文本回复即可继续任务
-```
-
-在 `in_channel` 模式下，简报作为普通的顶层频道消息投递（不新建话题），你的回复通过
-频道的共享会话继续任务。三项设置协同工作：
-
-- **`cron_continuable_surface: in_channel`**——投递时跳过新建话题。
-- **`reply_in_thread: false`**（必需）——让机器人在频道中*平铺*回复你，并将其
-  归入简报所植入的同一个整频道会话。缺少它时继续功能仍可用，但回复会出现在话题里
-  （安全回退为话题式继续，绝不会丢失回复——网关会在启动时记录一条警告便于发现不匹配）。
-- **`require_mention: false`**（或将该频道加入 `free_response_channels`）——这样你
-  可以用纯文本消息回复；否则机器人只在你每次 `@` 提及它时才被唤醒。
-
-由于继续载体是**整频道**会话，它是共享的：频道里的其他闲聊——以及第二个可继续的
-in_channel 任务——都会加入同一段滚动对话。这是「平铺在频道中」的固有取舍，与
-`reply_in_thread: false` 用户已经接受的取舍相同；若希望每次投递的后续讨论相互隔离，
-请使用默认的 `thread` 方式。
-
-这目前是 Slack 的能力。其他平台接受该键，但会回退到 `thread` 方式（它们的继续原语
-不同）；该选择按平台设置，位于各平台的配置下。这是网关侧的配置项——`/restart` 即可
-生效；无需重新安装 Slack 应用。
-
-:::note 1:1 私信（DM）
-`cron_continuable_surface` 是**频道**设置——1:1 私信没有「话题 vs 时间线」的区分
-（私信本身就是平铺的），因此该键在私信中无效。决定私信 cron 投递是否可继续的是另一个
-已有的独立开关 **`slack.dm_top_level_threads_as_sessions`**：
-
-- **`false`**——所有顶层私信共享同一个滚动私信会话，因此可继续的 cron 简报与你的回复
-  落在**同一个**会话里，任务得以带上下文继续。这正是私信中可继续 cron 所需要的。
-- **`true`**（默认）——每条顶层私信消息各自成为独立会话，因此对已投递简报的回复会开启
-  一个**全新**、不含该简报记录的会话。此模式下继续功能不可用（对 cron 或任何平铺投递皆然）。
-
-所以，若要让 cron 任务在 1:1 私信中可继续，请设置
-`slack.dm_top_level_threads_as_sessions: false`。私信不需要（也会忽略）
-`cron_continuable_surface`。
-:::
-
-### 静默抑制
-
-如果 agent 的最终响应以 `[SILENT]` 开头，投递将被完全抑制。输出仍会保存到本地以供审计（位于 `~/.hermes/cron/output/`），但不会向投递目标发送任何消息。
-
-这对于只在出现问题时才需要上报的监控任务很有用：
-
-```text
-Check if nginx is running. If everything is healthy, respond with only [SILENT].
-Otherwise, report the issue.
-```
-
-失败的任务无论 `[SILENT]` 标记如何都会投递——只有成功的运行才能被静默。
-
-## 脚本超时
-
-预运行脚本（通过 `script` 参数附加）的默认超时为 120 秒。如果你的脚本需要更长时间——例如，包含随机延迟以避免类机器人的时序模式——可以增加此值：
-
-```yaml
-# ~/.hermes/config.yaml
-cron:
-  script_timeout_seconds: 300   # 5 分钟
-```
-
-或设置 `HERMES_CRON_SCRIPT_TIMEOUT` 环境变量。解析顺序为：环境变量 → config.yaml → 默认 120 秒。
-
-## 无 agent 模式（纯脚本任务）
-
-对于不需要 LLM 推理的周期性任务——经典的看门狗、磁盘/内存告警、心跳、CI ping——在创建时传入 `no_agent=True`。调度器按计划运行你的脚本，并直接投递其 stdout，完全跳过 agent：
-
-```bash
-hermes cron create "every 5m" \
-  --no-agent \
-  --script memory-watchdog.sh \
-  --deliver telegram \
-  --name "memory-watchdog"
-```
-
-语义：
-
-- 脚本 stdout（去除首尾空白）→ 原样作为消息投递。
-- **stdout 为空 → 静默 tick**，不投递。这是看门狗模式："只在出现问题时才说话"。
-- 非零退出或超时 → 投递错误告警，确保损坏的看门狗不会静默失败。
-- 最后一行输出 `{"wakeAgent": false}` → 静默 tick（与 LLM 任务使用相同的门控）。
-- 无 token、无模型、无 provider 回退——任务永远不会触及推理层。
-
-`.sh`/`.bash` 文件在 `/bin/bash` 下运行；其他文件在当前 Python 解释器（`sys.executable`）下运行。脚本必须位于 `~/.hermes/scripts/`（与预运行脚本门控相同的沙箱规则）。
-
-### Agent 为你设置这些
-
-`cronjob` 工具的 schema 直接向 Hermes 暴露了 `no_agent`，因此你可以在聊天中描述一个看门狗，让 agent 来配置它：
-
-```text
-Ping me on Telegram if RAM is over 85%, every 5 minutes.
-```
-
-Hermes 会通过 `write_file` 将检查脚本写入 `~/.hermes/scripts/`，然后调用：
-
-```python
-cronjob(action="create", schedule="every 5m",
-        script="memory-watchdog.sh", no_agent=True,
-        deliver="telegram", name="memory-watchdog")
-```
-
-当消息内容完全由脚本决定时（看门狗、阈值告警、心跳），它会自动选择 `no_agent=True`。同一工具也让 agent 可以暂停、恢复、编辑和删除任务——整个生命周期都通过聊天驱动，无需任何人接触 CLI。
-
-参见[纯脚本 Cron 任务指南](/guides/cron-script-only)获取实际示例。
-
-## 通过 `context_from` 串联任务
-
-Cron 任务在隔离的会话中运行，不保留之前运行的记忆。但有时一个任务的输出恰好是下一个任务所需的输入。`context_from` 参数自动建立这种连接——任务 B 的 prompt 在运行时会将任务 A 的最新输出作为上下文前置。
-
-```python
-# 任务 1：收集原始数据
-cronjob(
-    action="create",
-    prompt="Fetch the top 10 AI/ML stories from Hacker News. Save them to ~/.hermes/data/briefs/raw.md in markdown format with title, URL, and score.",
-    schedule="0 7 * * *",
-    name="AI News Collector",
-)
-
-# 任务 2：分类——接收任务 1 的输出作为上下文
-# 从 cronjob(action="list") 获取任务 1 的 ID
-cronjob(
-    action="create",
-    prompt="Read ~/.hermes/data/briefs/raw.md. Score each story 1–10 for engagement potential and novelty. Output the top 5 to ~/.hermes/data/briefs/ranked.md.",
-    schedule="30 7 * * *",
-    context_from="<job1_id>",
-    name="AI News Triage",
-)
-
-# 任务 3：发布——接收任务 2 的输出作为上下文
-cronjob(
-    action="create",
-    prompt="Read ~/.hermes/data/briefs/ranked.md. Write 3 tweet drafts (hook + body + hashtags). Deliver to telegram:7976161601.",
-    schedule="0 8 * * *",
-    context_from="<job2_id>",
-    name="AI News Brief",
-)
-```
-
-**工作原理：**
-
-- 任务 2 触发时，Hermes 从 `~/.hermes/cron/output/{job1_id}/*.md` 读取任务 1 的最新输出
-- 该输出自动前置到任务 2 的 prompt
-- 任务 2 无需硬编码"读取此文件"——它以上下文形式接收内容
-- 链可以是任意长度：任务 1 → 任务 2 → 任务 3 → …
-
-**`context_from` 接受的格式：**
-
-| 格式 | 示例 |
-|--------|---------|
-| 单个任务 ID（字符串） | `context_from="a1b2c3d4"` |
-| 多个任务 ID（列表） | `context_from=["job_a", "job_b"]` |
-
-输出按列表顺序拼接。
-
-**适用场景：**
-
-- 多阶段流水线（收集 → 过滤 → 格式化 → 投递）
-- 步骤 N 依赖步骤 N−1 输出的依赖任务
-- 一个任务聚合多个其他任务结果的扇入模式
-
-## Provider 恢复
-
-Cron 任务继承你配置的回退 provider 和凭证池轮换。如果主 API key 被限速或 provider 返回错误，cron agent 可以：
-
-- **回退到备用 provider**，前提是你在 `config.yaml` 中配置了 `fallback_providers`（或旧版 `fallback_model`）
-- **轮换到下一个凭证**，即同一 provider 的[凭证池](/user-guide/configuration#credential-pool-strategies)中的下一个
-
-这意味着高频运行或在高峰时段运行的 cron 任务更具弹性——单个被限速的 key 不会导致整次运行失败。
-
-## 调度格式
-
-Agent 的最终响应会自动投递——你**无需**在 cron prompt 中为同一目标包含 `send_message`。如果 cron 运行调用了 `send_message` 且目标与调度器已投递的目标完全相同，Hermes 会跳过该重复发送，并告知模型将面向用户的内容放在最终响应中。仅对额外或不同的目标使用 `send_message`。
-
-### 相对延迟（一次性）
-
-```text
-30m     → 30 分钟后运行一次
-2h      → 2 小时后运行一次
-1d      → 1 天后运行一次
-```
-
-### 间隔（周期性）
-
-```text
-every 30m    → 每 30 分钟
-every 2h     → 每 2 小时
-every 1d     → 每天
-```
-
-### Cron 表达式
-
-```text
-0 9 * * *       → 每天上午 9:00
-0 9 * * 1-5     → 工作日上午 9:00
-0 */6 * * *     → 每 6 小时
-30 8 1 * *      → 每月 1 日上午 8:30
-0 0 * * 0       → 每周日午夜
-```
-
-### ISO 时间戳
-
-```text
-2026-03-15T09:00:00    → 2026 年 3 月 15 日上午 9:00 一次性运行
-```
-
-## 重复行为
-
-| 调度类型 | 默认重复次数 | 行为 |
-|--------------|----------------|----------|
-| 一次性（`30m`、时间戳） | 1 | 运行一次 |
-| 间隔（`every 2h`） | 永久 | 运行直到删除 |
-| Cron 表达式 | 永久 | 运行直到删除 |
-
-可以覆盖：
-
-```python
-cronjob(
-    action="create",
-    prompt="...",
-    schedule="every 2h",
-    repeat=5,
-)
-```
-
-## 以编程方式管理任务
-
-面向 agent 的 API 是单一工具：
-
-```python
-cronjob(action="create", ...)
-cronjob(action="list")
-cronjob(action="update", job_id="...")
-cronjob(action="pause", job_id="...")
-cronjob(action="resume", job_id="...")
-cronjob(action="run", job_id="...")
-cronjob(action="remove", job_id="...")
-```
-
-对于 `update`，传入 `skills=[]` 可删除所有已附加的 skill。
-
-## Cron 任务可用的工具集
-
-Cron 在全新的 agent 会话中运行每个任务，不附加任何聊天平台。默认情况下，cron agent 获得**你在 `hermes tools` 中为 `cron` 平台配置的工具集**——不是 CLI 默认值，也不是所有工具。
-
-```bash
-hermes tools
-# → 在 curses UI 中选择 "cron" 平台
-# → 像 Telegram/Discord 等平台一样切换工具集开关
-```
-
-通过 `cronjob.create`（或通过 `cronjob.update` 对现有任务）上的 `enabled_toolsets` 字段可进行更精细的单任务控制：
-
-```text
-cronjob(action="create", name="weekly-news-summary",
-        schedule="every sunday 9am",
-        enabled_toolsets=["web", "file"],      # 仅 web + file，无 terminal/browser 等
-        prompt="Summarize this week's AI news: ...")
-```
-
-当任务上设置了 `enabled_toolsets` 时，它优先生效；否则 `hermes tools` 的 cron 平台配置生效；否则 Hermes 回退到内置默认值。这对成本控制很重要：在每个小型"获取新闻"任务中携带 `moa`、`browser`、`delegation` 会在每次 LLM 调用时膨胀工具 schema prompt。
-
-### 完全跳过 agent：`wakeAgent`
-
-如果你的 cron 任务附加了预检脚本（通过 `script=`），脚本可以在运行时决定 Hermes 是否应该调用 agent。在 stdout 最后一行输出如下格式：
-
-```text
-{"wakeAgent": false}
-```
-
-……cron 将完全跳过本次 tick 的 agent 运行。适用于高频轮询（每 1–5 分钟），只在状态实际发生变化时才需要唤醒 LLM——否则你会为一遍遍的零内容 agent 轮次付费。
-
-```python
-# 预检脚本
-import json, sys
-latest = fetch_latest_issue_count()
-prev = read_state("issue_count")
-if latest == prev:
-    print(json.dumps({"wakeAgent": False}))   # 跳过本次 tick
-    sys.exit(0)
-write_state("issue_count", latest)
-print(json.dumps({"wakeAgent": True, "context": {"new_issues": latest - prev}}))
-```
-
-省略 `wakeAgent` 时，默认为 `true`（照常唤醒 agent）。
-
-#### 实用方案：低成本预运行门控
-
-`wakeAgent` 门控提供了一种零成本的方式，用于决定定时任务是否应该消耗任何 LLM token。三种模式覆盖了大多数使用场景。
-
-**文件变更门控**——仅在被监视文件自上次成功 tick 以来有新内容时运行。调度器记录每个任务的 `last_run_at`；将其与文件的 mtime 比较。
-
-```bash
-#!/bin/bash
-# ~/.hermes/scripts/feed-changed.sh
-FEED="$HOME/data/feed.json"
-STATE="$HOME/.hermes/scripts/.feed-changed.last"
-test -f "$FEED" || { echo '{"wakeAgent": false}'; exit 0; }
-mtime=$(stat -c %Y "$FEED")
-last=$(cat "$STATE" 2>/dev/null || echo 0)
-if [ "$mtime" -le "$last" ]; then
-  echo '{"wakeAgent": false}'
-else
-  echo "$mtime" > "$STATE"
-  echo '{"wakeAgent": true}'
-fi
-```
-
-```text
-cronjob(action="create", name="process-feed",
-        schedule="every 30m",
-        script="feed-changed.sh",
-        prompt="A new ~/data/feed.json has landed. Summarize what changed.")
-```
-
-**外部标志门控**——仅在其他进程发出就绪信号时运行（例如，部署 hook 落下一个文件，CI 任务在状态存储中设置一个值）。
-
-```bash
-#!/bin/bash
-# ~/.hermes/scripts/flag-ready.sh
-if test -f /tmp/new-data-ready; then
-  rm -f /tmp/new-data-ready
-  echo '{"wakeAgent": true}'
-else
-  echo '{"wakeAgent": false}'
-fi
-```
-
-```text
-cronjob(action="create", name="nightly-analysis",
-        schedule="0 9 * * *",
-        script="flag-ready.sh",
-        prompt="Run the nightly analysis over today's batch.")
-```
-
-**SQL 计数门控**——仅在你自己的数据库中有新行需要处理时运行。脚本还可以通过 `context` 将计数传递给 agent，让 agent 无需重新查询就知道数据量。
-
-```python
-#!/usr/bin/env python
-# ~/.hermes/scripts/new-rows.py
-import json, sqlite3
-conn = sqlite3.connect("/home/me/data/app.db")
-n = conn.execute(
-    "SELECT COUNT(*) FROM messages WHERE ts > strftime('%s','now','-2 hours')"
-).fetchone()[0]
-if n < 1:
-    print(json.dumps({"wakeAgent": False}))
-else:
-    print(json.dumps({"wakeAgent": True, "context": {"new_rows": n}}))
-```
-
-```text
-cronjob(action="create", name="summarize-new-msgs",
-        schedule="every 2h",
-        script="new-rows.py",
-        prompt="Summarize the new messages from the last 2 hours.")
-```
-
-同样的模式适用于任何可以从脚本查询的数据源——Postgres、HTTP API、你自己的状态存储——无需将 SQL 求值器内置到 cron 子系统中。
-
-:::tip
-Hermes 自身的 `~/.hermes/state.db` 是内部 schema，会在版本间变更。不要从预运行门控中查询它——指向你自己的数据库或 feed。
-:::
-
-致谢：此方案集由 @iankar8 在 [#2654](https://github.com/NousResearch/hermes-agent/pull/2654) 中的探索所启发，该 PR 提议将 sql/file/command 触发器作为并行机制添加。`script` + `wakeAgent` 门控已以零成本覆盖了所有三种情况，因此该工作以文档形式落地。
-
-### 串联任务：`context_from`
-
-Cron 任务可以通过在 `context_from` 中列出其他任务的名称（或 ID）来消费这些任务最近一次成功运行的输出：
-
-```text
-cronjob(action="create", name="daily-digest",
-        schedule="every day 7am",
-        context_from=["ai-news-fetch", "github-prs-fetch"],
-        prompt="Write the daily digest using the outputs above.")
-```
-
-被引用任务最近一次完成的输出会作为上下文注入到本次运行的 prompt 之上。每个上游条目必须是有效的任务 ID 或名称（参见 `cronjob action="list"`）。注意：串联读取的是*最近一次完成*的输出——它不会等待同一 tick 中正在运行的上游任务。
-
-## 任务存储
-
-任务存储在 `~/.hermes/cron/jobs.json`。任务运行的输出保存到 `~/.hermes/cron/output/{job_id}/{timestamp}.md`。
-
-任务可能将 `model` 和 `provider` 存储为 `null`。省略这些字段时，Hermes 在执行时从全局配置中解析它们。只有设置了单任务覆盖时，这些字段才会出现在任务记录中。
-
-存储使用原子文件写入，因此中断的写入不会留下部分写入的任务文件。
-
-## 自包含的 prompt 仍然重要
-
-:::warning 重要
-Cron 任务在完全全新的 agent 会话中运行。Prompt 必须包含 agent 所需的一切，除非已由附加的 skill 提供。
-:::
-
-**错误：** `"Check on that server issue"`
-
-**正确：** `"SSH into server 192.168.1.100 as user 'deploy', check if nginx is running with 'systemctl status nginx', and verify https://example.com returns HTTP 200."`
-
-## 安全性
-
-定时任务的 prompt 在创建和更新时会扫描 prompt 注入和凭证外泄模式。包含不可见 Unicode 技巧、SSH 后门尝试或明显的密钥外泄载荷的 prompt 会被拦截。