forked from Zakaria/hermes-agent
Hermes-agent
This commit is contained in:
Zakaria
+225
@@ -0,0 +1,225 @@
|
||||
---
|
||||
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`。
|
||||
|
||||
### 检查 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)。*
|
||||
Reference in New Issue
Block a user