About

Imported from bog5d/claude-skills (devops/cronjob-troubleshooting/SKILL.md). Install upstream with npx skills add bog5d/claude-skills --skill cronjob-troubleshooting. Copyright stays with the author.

Cronjob故障排查

Name: cronjob-troubleshooting
Author: bog5d

当用户报告定时任务没有按预期执行时，使用此技能进行系统化排查。

触发条件

用户报告“定时任务没有执行”或“提醒没有收到”
系统时间已过预定执行时间
需要验证cronjob是否正常运行

排查步骤

1. 验证系统时间

首先检查当前系统时间是否已过预定执行时间：

date

2. 检查活跃任务列表

查看当前配置的cronjob：

cronjob action=list

如果列表为空，说明任务可能已被删除或从未创建成功。

3. 检查cron目录结构

ls -la ~/.hermes/cron/
ls -la ~/.hermes/cron/output/

4. 查找最近的执行记录

检查output目录中最新的子目录（按时间排序）：

ls -lt ~/.hermes/cron/output/ | head -5

5. 读取执行日志

进入最新的执行目录并查看日志文件：

read_file path=~/.hermes/cron/output/<job_id>/<timestamp_file>.md

或使用终端命令：

ls ~/.hermes/cron/output/
# 找到最新的job_id目录
ls ~/.hermes/cron/output/<job_id>/
cat ~/.hermes/cron/output/<job_id>/<timestamp_file>.md

6. 分析错误信息

常见错误模式：

错误类型	可能原因	解决方案
`HTTP 502: Error code: 502`	网关错误，API服务暂时不可用	重试发送，检查网络连接
`API call failed after 3 retries`	网络问题或认证失败	验证API密钥和连接
`Job not found`	任务已被删除或配置丢失	重新创建cronjob
`Schedule mismatch`	时间格式错误或系统时区不匹配	检查schedule格式和系统时区
`Delivery target unreachable`	目标平台连接失败	检查send_message目标配置
`任务重复执行（提醒了两次）`	`ONESHOT_GRACE_SECONDS=120`导致的oneshot任务恢复Bug	见下方"重复执行排查"章节

7. 重复执行排查（一次性任务提醒了多次）

当用户报告"提醒了一次，过一会儿又提醒了一次"时：

根因：cron/jobs.py 中的 _recoverable_oneshot_run_at() 的 grace 窗口太大

# ONESHOT_GRACE_SECONDS = 120  ← 120秒窗口
# 一次性任务完成后，如果gateway在120秒内重启或ticker抖动，
# _recoverable_oneshot_run_at() 会认为"任务还没执行过"，
# 再次恢复并执行，导致重复提醒

排查确认步骤：

检查 ~/.hermes/cron/output/<job_id>/ 下是否有多个时间戳的输出文件（证明执行了多次）
检查 ~/.hermes/cron/jobs.json 中该任务是否已被删除（oneshot执行后正常会删除）
确认 gateway 是否在该时间段内重启过

修复方案：

将 ONESHOT_GRACE_SECONDS 从 120 缩小到 10
或在 mark_job_run() 中给已执行的 oneshot 任务在 jobs.json 中添加 "completed": true 标记，_recoverable_oneshot_run_at() 检查该标记跳过恢复
两个修复都做最保险

代码位置：

cron/jobs.py — _recoverable_oneshot_run_at() 函数（grace判定）
cron/jobs.py — mark_job_run() 函数（任务完成标记）

8. 检查jobs.json配置文件

查看cronjob配置文件：

read_file path=~/.hermes/cron/jobs.json

确认任务是否在配置中，以及配置是否正确。

8. 重新创建或重试

根据错误原因：

对于临时性错误（如HTTP 502），建议用户重试发送
对于配置问题，重新创建cronjob
对于平台连接问题，测试平台连接状态

验证步骤

确认任务已成功执行：检查output目录中是否有新的执行记录
验证错误已解决：重新创建后，等待下一次执行时间验证
测试平台连接：使用send_message action=list检查平台连接状态

注意事项

cronjob使用本地系统时间，确保时区正确
一次性任务（schedule: once in Xm）执行后会自动删除
重复性任务会持续存在直到手动删除
HTTP 502等网关错误通常是暂时性的，可能需要重试

示例

用户报告：“你提醒我11:58左右，但现在已经12点了，也没有给我任何提醒”

排查流程：

date → 确认当前时间已过12:00
cronjob action=list → 可能为空（一次性任务已执行并删除）
ls -la ~/.hermes/cron/output/ → 查找最近的执行记录
找到最新的job_id目录，读取日志文件
发现“API call failed after 3 retries: HTTP 502”
结论：任务已执行但API调用失败，需要重试发送提醒

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/bog5d-claude-skills-cronjob-troubleshooting/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

bog5d-claude-skills-cronjob-troubleshooting.ocm.jsonjson

{
  "ocm": "1",
  "id": "bog5d-claude-skills-cronjob-troubleshooting",
  "kind": "skill",
  "name": "cronjob-troubleshooting",
  "description": "排查Hermes Agent定时任务执行失败的调试流程，包括检查任务状态、查看执行日志、分析错误原因",
  "publisher": "bog5d",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "cron",
      "debugging",
      "troubleshooting",
      "scheduled-tasks",
      "github"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "排查Hermes Agent定时任务执行失败的调试流程，包括检查任务状态、查看执行日志、分析错误原因"
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/bog5d/claude-skills",
      "path": "devops/cronjob-troubleshooting/SKILL.md",
      "ref": "00cf064ad4ee063a75faeb8d924295456658b0a1",
      "url": "https://github.com/bog5d/claude-skills/blob/00cf064ad4ee063a75faeb8d924295456658b0a1/devops/cronjob-troubleshooting/SKILL.md",
      "key": "bog5d/claude-skills/devops/cronjob-troubleshooting/SKILL.md"
    }
  },
  "instructions": "# Cronjob故障排查\n\n当用户报告定时任务没有按预期执行时，使用此技能进行系统化排查。\n\n## 触发条件\n\n- 用户报告“定时任务没有执行”或“提醒没有收到”\n- 系统时间已过预定执行时间\n- 需要验证cronjob是否正常运行\n\n## 排查步骤\n\n### 1. 验证系统时间\n首先检查当前系统时间是否已过预定执行时间：\n```bash\ndate\n```\n\n### 2. 检查活跃任务列表\n查看当前配置的cronjob：\n```bash\ncronjob action=list\n```\n\n如果列表为空，说明任务可能已被删除或从未创建成功。\n\n### 3. 检查cron目录结构\n查看cron目录下的文件和子目录：\n```bash\nls -la ~/.hermes/cron/\nls -la ~/.hermes/cron/output/\n```\n\n### 4. 查找最近的执行记录\n检查output目录中最新的子目录（按时间排序）：\n```bash\nls -lt ~/.hermes/cron/output/ | head -5\n```\n\n### 5. 读取执行日志\n进入最新的执行目录并查看日志文件：\n```bash\nread_file path=~/.hermes/cron/output/<job_id>/<timestamp_file>.md\n```\n\n或使用终端命令：\n```bash\n",
  "cost": {
    "context_tokens": 672
  }
}

Fetch it by URL: GET /api/v1/registry/bog5d-claude-skills-cronjob-troubleshooting/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.