npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0-c - Mend

better-dsh 0.2.5 → 0.3.0-c

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1002) hide show

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

@@ -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 会被拦截。