better-dsh 0.2.5 → 0.3.0-a

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

@@ -1,247 +0,0 @@
----
-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

@@ -1,227 +0,0 @@
----
-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)。*