better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/cron-script-only.md

@@ -0,0 +1,247 @@
+---
+sidebar_position: 13
+title: "纯脚本 Cron 任务（无 LLM）"
+description: "完全跳过 LLM 的经典看门狗 cron 任务——脚本按计划运行，其 stdout 输出直接投递到你的消息平台。内存告警、磁盘告警、CI 通知、定期健康检查。"
+---
+
+# 纯脚本 Cron 任务
+
+有时你已经清楚地知道要发送什么消息。你不需要 agent 来推理——你只需要一个脚本按计时器运行，并将其输出（如有）发送到 Telegram / Discord / Slack / Signal。
+
+Hermes 将此称为**无 agent 模式**。这是去掉 LLM 的 cron 系统。
+
+<!-- ascii-guard-ignore -->
+```
+   ┌──────────────────┐          ┌──────────────────┐
+   │ scheduler tick   │  every   │ run script       │
+   │ (every N minutes)│ ──────▶ │ (bash or python) │
+   └──────────────────┘          └──────────────────┘
+                                          │
+                                          │ stdout
+                                          ▼
+                                 ┌──────────────────┐
+                                 │ delivery router  │
+                                 │ (telegram/disc…) │
+                                 └──────────────────┘
+```
+<!-- ascii-guard-ignore-end -->
+
+- **无 LLM 调用。** 零 token，零 agent 循环，零模型费用。
+- **脚本即任务。** 由脚本决定是否告警。有输出 → 发送消息；无输出 → 静默执行。
+- **Bash 或 Python。** `.sh` / `.bash` 文件在 `/bin/bash` 下运行；其他扩展名在当前 Python 解释器下运行。`~/.hermes/scripts/` 中的任何文件均可接受。
+- **同一调度器。** 与 LLM 任务共存于 `cronjob` 中——暂停、恢复、列出、日志和投递目标的操作方式完全相同。
+
+## 适用场景
+
+以下情况使用无 agent 模式：
+
+- **内存 / 磁盘 / GPU 看门狗。** 每 5 分钟运行一次，仅在超过阈值时告警。
+- **CI hook（钩子）。** 部署完成 → 发送 commit SHA；构建失败 → 发送最后 100 行日志。
+- **定期指标。** "每天上午 9 点的 Stripe 收入"——一次简单的 API 调用加格式化输出。
+- **外部事件轮询。** 检查 API，在状态变化时告警。
+- **心跳。** 每 N 分钟 ping 一次仪表板，证明主机存活。
+
+当你需要 agent **决定**说什么时——总结长文档、从 feed 中挑选有趣条目、起草友好提醒——请使用普通的（LLM 驱动的）cron 任务。无 agent 路径适用于脚本的 stdout 本身就是消息内容的场景。
+
+## 通过聊天创建
+
+无 agent 模式的真正优势在于：agent 本身可以为你设置看门狗——无需编辑器、无需 shell、无需记忆 CLI 参数。你描述需求，Hermes 编写脚本、安排计划，并告知你何时触发。
+
+### 示例对话
+
+> **你：** 每 5 分钟检查一次，如果内存超过 85% 就在 telegram 通知我
+>
+> **Hermes：** *（写入 `~/.hermes/scripts/memory-watchdog.sh`，然后以 `no_agent=true` 调用 `cronjob(...)`）*
+>
+> 已设置。每 5 分钟运行一次，仅在内存超过 85% 时告警 Telegram。脚本：`memory-watchdog.sh`。任务 ID：`abc123`。
+
+在底层，agent 进行了两次工具调用：
+
+```python
+# 1. 写入检查脚本
+write_file(
+    path="~/.hermes/scripts/memory-watchdog.sh",
+    content='''#!/usr/bin/env bash
+ram_pct=$(free | awk '/^Mem:/ {printf "%d", $3 * 100 / $2}')
+if [ "$ram_pct" -ge 85 ]; then
+  echo "RAM ${ram_pct}% on $(hostname)"
+fi
+# Empty stdout = silent tick; no message sent.
+''',
+)
+
+# 2. 调度任务 — no_agent=True 在每次触发时跳过 LLM
+cronjob(
+    action="create",
+    schedule="every 5m",
+    script="memory-watchdog.sh",
+    no_agent=True,
+    deliver="telegram",
+    name="memory-watchdog",
+)
+```
+
+此后每次触发都是免费的：调度器运行脚本，若 stdout 非空则将其发送到 Telegram，且从不调用模型。
+
+### agent 为你决定的内容
+
+当你的请求类似"当 X 时告警我"或"每 N 分钟检查 Y，如果 Z 则通知我"，Hermes 的 `cronjob` 工具描述会指示它在消息内容完全由脚本决定时使用 `no_agent=True`。当请求需要推理时（*"总结新 issue"*、*"挑选最有趣的头条"*、*"起草一条友好提醒"*），则回退到普通的 LLM 驱动路径。
+
+你不必自己指定 `--no-agent`。只需描述你想要的行为即可。
+
+### 通过聊天管理看门狗
+
+agent 可以用与创建任务相同的方式暂停、恢复、编辑和删除任务：
+
+> **你：** 今晚先停掉内存看门狗
+>
+> **Hermes：** *（调用 `cronjob(action='pause', job_id='abc123')`）*
+>
+> 已暂停。说"重新开启"或执行 `hermes cron resume abc123` 可恢复。
+
+> **你：** 改成每 15 分钟一次
+>
+> **Hermes：** *（调用 `cronjob(action='update', job_id='abc123', schedule='every 15m')`）*
+
+完整生命周期（创建 / 列出 / 更新 / 暂停 / 恢复 / 立即运行 / 删除）均可由 agent 操作，无需你学习任何 CLI 命令。
+
+## 通过 CLI 创建
+
+偏好 shell？CLI 路径用三条命令即可达到相同效果：
+
+```bash
+# 1. 编写脚本
+cat > ~/.hermes/scripts/memory-watchdog.sh <<'EOF'
+#!/usr/bin/env bash
+# Alert when RAM usage is over 85%. Silent otherwise.
+RAM_PCT=$(free | awk '/^Mem:/ {printf "%d", $3 * 100 / $2}')
+if [ "$RAM_PCT" -ge 85 ]; then
+  echo "⚠ RAM ${RAM_PCT}% on $(hostname)"
+fi
+# Empty stdout = silent run; no message sent.
+EOF
+chmod +x ~/.hermes/scripts/memory-watchdog.sh
+
+# 2. 调度任务
+hermes cron create "every 5m" \
+  --no-agent \
+  --script memory-watchdog.sh \
+  --deliver telegram \
+  --name "memory-watchdog"
+
+# 3. 验证
+hermes cron list
+hermes cron run <job_id>    # 触发一次以测试
+```
+
+就这些。无 prompt（提示词），无技能，无模型。
+
+
+## 脚本输出与投递的映射关系
+
+| 脚本行为 | 结果 |
+|-----------------|--------|
+| 退出码 0，stdout 非空 | stdout 原样投递 |
+| 退出码 0，stdout 为空 | 静默执行——不投递 |
+| 退出码 0，stdout 最后一行包含 `{"wakeAgent": false}` | 静默执行（与 LLM 任务共用的门控） |
+| 非零退出码 | 投递错误告警（确保损坏的看门狗不会静默失败） |
+| 脚本超时 | 投递错误告警 |
+
+"空则静默"的行为是经典看门狗模式的关键：脚本可以每分钟运行一次，但只有在真正需要关注时，频道才会收到消息。
+
+## 脚本规则
+
+脚本必须位于 `~/.hermes/scripts/`。这在任务创建时和运行时均会强制检查——绝对路径、`~/` 展开以及路径穿越模式（`../`）均会被拒绝。该目录与 LLM 任务使用的预检脚本门控共享。
+
+解释器由文件扩展名决定：
+
+| 扩展名 | 解释器 |
+|-----------|-------------|
+| `.sh`、`.bash` | `/bin/bash` |
+| 其他任意扩展名 | `sys.executable`（当前 Python） |
+
+我们有意**不**遵循 `#!/...` shebang——保持解释器集合明确且精简，可减少调度器信任的攻击面。
+
+## 计划语法
+
+与所有其他 cron 任务相同：
+
+```bash
+hermes cron create "every 5m"        # 间隔
+hermes cron create "every 2h"
+hermes cron create "0 9 * * *"       # 标准 cron：每天上午 9 点
+hermes cron create "30m"             # 单次：30 分钟后运行一次
+```
+
+完整语法请参阅 [cron 功能参考](/user-guide/features/cron)。
+
+## 投递目标
+
+`--deliver` 接受 gateway 已知的所有目标。常见形式：
+
+```bash
+--deliver telegram                       # 平台默认频道
+--deliver telegram:-1001234567890        # 指定聊天
+--deliver telegram:-1001234567890:17585  # 指定 Telegram 论坛话题
+--deliver discord:#ops
+--deliver slack:#engineering
+--deliver signal:+15551234567
+--deliver local                          # 仅保存到 ~/.hermes/cron/output/
+```
+
+对于使用 bot token 的平台（Telegram、Discord、Slack、Signal、SMS、WhatsApp），脚本运行时无需运行中的 gateway——工具直接使用 `~/.hermes/.env` / `~/.hermes/config.yaml` 中已有的凭据调用各平台的 REST 端点。
+
+## 编辑与生命周期
+
+```bash
+hermes cron list                                    # 查看所有任务
+hermes cron pause <job_id>                          # 停止触发，保留定义
+hermes cron resume <job_id>
+hermes cron edit <job_id> --schedule "every 10m"    # 调整频率
+hermes cron edit <job_id> --agent                   # 切换为 LLM 模式
+hermes cron edit <job_id> --no-agent --script …     # 切换回无 agent 模式
+hermes cron remove <job_id>                         # 删除任务
+```
+
+所有适用于 LLM 任务的操作（暂停、恢复、手动触发、投递目标变更）同样适用于无 agent 任务。
+
+## 实战示例：磁盘空间告警
+
+```bash
+cat > ~/.hermes/scripts/disk-alert.sh <<'EOF'
+#!/usr/bin/env bash
+# Alert when / or /home is over 90% full.
+THRESHOLD=90
+df -h / /home 2>/dev/null | awk -v t="$THRESHOLD" '
+  NR > 1 && $5+0 >= t {
+    printf "⚠ Disk %s full on %s\n", $5, $6
+  }
+'
+EOF
+chmod +x ~/.hermes/scripts/disk-alert.sh
+
+hermes cron create "*/15 * * * *" \
+  --no-agent \
+  --script disk-alert.sh \
+  --deliver telegram \
+  --name "disk-alert"
+```
+
+当两个文件系统均低于 90% 时静默；当某个文件系统超出阈值时，每个超限文件系统触发一行告警。
+
+## 与其他模式的对比
+
+| 方式 | 运行内容 | 适用场景 |
+|----------|-----------|-------------|
+| `cronjob --no-agent`（本页） | 你的脚本，由 Hermes 调度 | 不需要推理的周期性看门狗 / 告警 / 指标 |
+| `cronjob`（默认，LLM） | 带可选预检脚本的 agent | 消息内容需要对数据进行推理时 |
+| OS cron + `curl` 到 [webhook 订阅](/user-guide/messaging/webhooks) | 你的脚本，由 OS 调度 | 当 Hermes 本身可能不健康时（即被监控对象） |
+
+对于必须在 **gateway 宕机时也能触发**的关键系统健康看门狗，请使用 OS 级 cron 配合 `curl` 调用 Hermes webhook 订阅（或任何外部告警端点）——这些作为独立 OS 进程运行，不依赖 Hermes 是否在线。当被监控对象是外部系统时，in-gateway 调度器才是正确选择。
+
+## 相关文档
+
+- [用 Cron 自动化一切](/guides/automate-with-cron) — LLM 驱动的 cron 模式。
+- [定时任务（Cron）参考](/user-guide/features/cron) — 完整计划语法、生命周期、投递路由。
+- [Webhook 订阅](/user-guide/messaging/webhooks) — 供外部调度器使用的即发即忘 HTTP 入口。
+- [Gateway 内部机制](/developer-guide/gateway-internals) — 投递路由器内部实现。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/cron-troubleshooting.md

@@ -0,0 +1,227 @@
+---
+sidebar_position: 12
+title: "Cron 故障排查"
+description: "诊断并修复常见的 Hermes cron 问题——任务未触发、投递失败、skill 加载错误及性能问题"
+---
+
+# Cron 故障排查
+
+当 cron 任务行为异常时，请按顺序逐项检查。大多数问题属于以下四类之一：时序、投递、权限或 skill 加载。
+
+---
+
+## 任务未触发
+
+### 检查 1：确认任务存在且处于活跃状态
+
+```bash
+hermes cron list
+```
+
+找到该任务并确认其状态为 `[active]`（而非 `[paused]` 或 `[completed]`）。若显示 `[completed]`，可能是重复次数已耗尽——编辑该任务以重置。
+
+### 检查 2：确认调度表达式正确
+
+格式错误的调度表达式会静默降级为单次执行，或被直接拒绝。测试你的表达式：
+
+| 你的表达式 | 应解析为 |
+|----------------|-------------------|
+| `0 9 * * *` | 每天上午 9:00 |
+| `0 9 * * 1` | 每周一上午 9:00 |
+| `every 2h` | 从现在起每 2 小时 |
+| `30m` | 从现在起 30 分钟后 |
+| `2025-06-01T09:00:00` | 2025 年 6 月 1 日 09:00 UTC |
+
+若任务触发一次后从列表中消失，说明这是单次调度（`30m`、`1d` 或 ISO 时间戳）——属于预期行为。
+
+### 检查 3：gateway 是否正在运行？
+
+Cron 任务由 gateway 的后台 ticker 线程触发，该线程每 60 秒 tick 一次。普通的 CLI 聊天会话**不会**自动触发 cron 任务。
+
+如果你期望任务自动触发，需要运行一个 gateway（前台运行用 `hermes gateway`，安装为服务用 `hermes gateway start`）。如需单次调试，可手动触发一次 tick：`hermes cron tick`。
+
+**桌面应用：** 桌面端的主后端自带 ticker，并且会 tick **本机每个 profile** 的 cron 存储——因此即使某个次要 profile 的后端处于休眠状态（桌面端会在约 10 分钟空闲后让 profile 后端休眠），该 profile 上的任务也会照常触发。你不需要保持某个 profile 打开来让它的定时任务运行。
+
+### 检查 4：检查系统时钟和时区
+
+任务使用本地时区。若机器时钟有误或时区与预期不符，任务将在错误的时间触发。验证方法：
+
+```bash
+date
+hermes cron list   # 将 next_run 时间与本地时间对比
+```
+
+---
+
+## 投递失败
+
+### 检查 1：确认投递目标正确
+
+投递目标区分大小写，且要求对应平台已正确配置。目标配置错误会静默丢弃响应。
+
+| 目标 | 所需配置 |
+|--------|----------|
+| `telegram` | `~/.hermes/.env` 中的 `TELEGRAM_BOT_TOKEN` |
+| `discord` | `~/.hermes/.env` 中的 `DISCORD_BOT_TOKEN` |
+| `slack` | `~/.hermes/.env` 中的 `SLACK_BOT_TOKEN` |
+| `whatsapp` | 已配置 WhatsApp gateway |
+| `signal` | 已配置 Signal gateway |
+| `matrix` | 已配置 Matrix homeserver |
+| `email` | `config.yaml` 中已配置 SMTP |
+| `sms` | 已配置 SMS 提供商 |
+| `local` | 对 `~/.hermes/cron/output/` 有写权限 |
+| `origin` | 投递到创建该任务的聊天会话 |
+
+其他支持的平台包括 `mattermost`、`homeassistant`、`dingtalk`、`feishu`、`wecom`、`weixin`、`bluebubbles`、`qqbot` 和 `webhook`。你也可以使用 `platform:chat_id` 语法指定特定聊天（例如 `telegram:-1001234567890`）。
+
+若投递失败，任务仍会执行——只是不会发送到任何地方。检查 `hermes cron list` 中的 `last_error` 字段（如有）。
+
+### 检查 2：检查 `[SILENT]` 的使用
+
+若你的 cron 任务没有输出，或 agent 响应为 `[SILENT]`，投递会被抑制。这对监控类任务是预期行为——但请确认你的 prompt（提示词）没有意外地抑制所有输出。
+
+若 prompt 中写有"如果没有变化则回复 [SILENT]"，非空响应也可能被静默吞掉。请检查你的条件逻辑。
+
+### 检查 3：平台 token 权限
+
+每个消息平台的 bot 需要特定权限才能发送消息。若投递静默失败：
+
+- **Telegram**：Bot 必须是目标群组/频道的管理员
+- **Discord**：Bot 必须有目标频道的发送权限
+- **Slack**：Bot 必须已加入工作区并拥有 `chat:write` scope
+
+### 检查 4：响应包装
+
+默认情况下，cron 响应会添加页眉和页脚（`config.yaml` 中的 `cron.wrap_response: true`）。某些平台或集成可能无法正常处理。如需禁用：
+
+```yaml
+cron:
+  wrap_response: false
+```
+
+---
+
+## Skill 加载失败
+
+### 检查 1：确认 skill 已安装
+
+```bash
+hermes skills list
+```
+
+Skill 必须先安装才能附加到 cron 任务。若 skill 缺失，先用 `hermes skills install <skill-name>` 安装，或在 CLI 中通过 `/skills` 安装。
+
+### 检查 2：检查 skill 名称与 skill 文件夹名称
+
+Skill 名称区分大小写，必须与已安装 skill 的文件夹名称完全匹配。若任务指定的是 `ai-funding-daily-report`，但 skill 文件夹也是 `ai-funding-daily-report`，请从 `hermes skills list` 确认确切名称。
+
+### 检查 3：依赖交互式工具的 skill
+
+Cron 任务运行时，`cronjob`、`messaging` 和 `clarify` 工具集均被禁用。这可防止递归创建 cron、直接发送消息（投递由调度器处理）以及交互式提示。若某 skill 依赖这些工具集，它将无法在 cron 上下文中运行。
+
+请查阅该 skill 的文档，确认其支持非交互式（headless）模式。
+
+### 检查 4：多 skill 加载顺序
+
+使用多个 skill 时，它们按顺序加载。若 Skill A 依赖 Skill B 的上下文，请确保 B 先加载：
+
+```bash
+/cron add "0 9 * * *" "..." --skill context-skill --skill target-skill
+```
+
+在此示例中，`context-skill` 先于 `target-skill` 加载。
+
+---
+
+## 任务错误与失败
+
+### 检查 1：查看近期任务输出
+
+若任务运行后失败，可在以下位置查看错误上下文：
+
+1. 任务投递的聊天会话（若投递成功）
+2. `~/.hermes/logs/agent.log`（调度器消息）或 `errors.log`（警告信息）
+3. 通过 `hermes cron list` 查看任务的 `last_run` 元数据
+
+### 检查 2：常见错误模式
+
+**脚本报 "No such file or directory"**
+`script` 路径必须为绝对路径（或相对于 Hermes 配置目录的路径）。验证：
+```bash
+ls ~/.hermes/scripts/your-script.py   # 必须存在
+hermes cron edit <job_id> --script ~/.hermes/scripts/your-script.py
+```
+
+**任务执行时报 "Skill not found"**
+Skill 必须安装在运行调度器的机器上。若你在不同机器间切换，skill 不会自动同步——请用 `hermes skills install <skill-name>` 重新安装。
+
+**任务运行但没有投递任何内容**
+可能是投递目标问题（见上方"投递失败"部分）或响应被静默抑制（`[SILENT]`）。
+
+**任务挂起或超时**
+调度器使用基于不活跃时间的超时机制（默认 600 秒，可通过 `HERMES_CRON_TIMEOUT` 环境变量配置，`0` 表示无限制）。只要 agent 持续调用工具，就可以一直运行——计时器仅在持续不活跃后触发。长时间运行的任务应使用脚本处理数据采集，仅将结果投递出去。
+
+### 检查 3：锁竞争
+
+调度器使用基于文件的锁来防止 tick 重叠。若同时运行了两个 gateway 实例（或 CLI 会话与 gateway 冲突），任务可能被延迟或跳过。
+
+终止重复的 gateway 进程：
+```bash
+ps aux | grep hermes
+# 终止重复进程，只保留一个
+```
+
+### 检查 4：jobs.json 的权限
+
+任务存储在 `~/.hermes/cron/jobs.json`。若该文件对当前用户不可读写，调度器将静默失败：
+
+```bash
+ls -la ~/.hermes/cron/jobs.json
+chmod 600 ~/.hermes/cron/jobs.json   # 应由你的用户拥有
+```
+
+---
+
+## 性能问题
+
+### 任务启动缓慢
+
+每个 cron 任务都会创建一个全新的 AIAgent 会话，可能涉及提供商认证和模型加载。对于时间敏感的调度，请预留缓冲时间（例如用 `0 8 * * *` 代替 `0 9 * * *`）。
+
+### 过多任务重叠
+
+调度器在每次 tick 内顺序执行任务。若多个任务同时到期，它们将依次运行。考虑错开调度时间（例如用 `0 9 * * *` 和 `5 9 * * *` 代替两者都设为 `0 9 * * *`）以避免延迟。
+
+### 脚本输出过大
+
+输出数兆字节数据的脚本会拖慢 agent，并可能触及 token 限制。请在脚本层面进行过滤/摘要——只输出 agent 需要推理的内容。
+
+---
+
+## 诊断命令
+
+```bash
+hermes cron list                    # 显示所有任务、状态、next_run 时间
+hermes cron run <job_id>            # 安排在下次 tick 执行（用于测试）
+hermes cron edit <job_id>           # 修复配置问题
+hermes logs                         # 查看近期 Hermes 日志
+hermes skills list                  # 确认已安装的 skill
+```
+
+---
+
+## 获取更多帮助
+
+若你已按本指南逐项排查，问题仍未解决：
+
+1. 使用 `hermes cron run <job_id>` 运行任务（在下次 gateway tick 时触发），观察聊天输出中的错误
+2. 查看 `~/.hermes/logs/agent.log` 中的调度器消息和 `~/.hermes/logs/errors.log` 中的警告
+3. 在 [github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) 提交 issue，并附上：
+   - 任务 ID 和调度表达式
+   - 投递目标
+   - 预期行为与实际行为
+   - 日志中的相关错误信息
+
+---
+
+*完整的 cron 参考文档，请参阅 [用 Cron 自动化一切](/guides/automate-with-cron) 和 [定时任务（Cron）](/user-guide/features/cron)。*