定时守护

cron 作业的失败很少是"逻辑 bug",多半是 shell 引用炸了、环境漂移了、管道误报了。本技能用"脚本优先 + 确定环境 + 静默成功"三原则,把这些无聊但致命的坑堵死.

主要能力

1. 脚本优先原则

禁止在cron里写多行bash -lc '..',把逻辑放进仓库脚本(tools/<job>.py),cron只跑一行短命令,避免引用地狱。使用input_params参数支持创建/查询/导出操作。

2. 确定环境

显式确定cwd(cd "$(dirname "$0")/.")、PATH(不依赖.bashrc)、文档化必需环境变量(: "${API_KEY:?未设置}"),解决"本地能跑cron里失败"。

3. 静默成功约定

成功时输出NO_REPLY(或空),只在失败时输出ALERT到stderr,避免每次成功都发通知淹没用户。

4. 故障模式目录

8种高频故障(EOF引号错误/SIGPIPE误报/cwd漂移/git push被拒/Python -c陷阱/Windows路径/临时文件残留/并发冲突)附修复模板。

5. 跨平台适配

POSIX(bash/sh)与Windows(PowerShell)等效模式对照表,覆盖三大平台。

6. 上线前预检清单

10项检查清单(逻辑在脚本/cwd确定/变量校验/PATH设置/静默成功/trap清理/文件锁/无force-push等)+ 本地cron环境模拟测试。

使用场景

何时使用: 编写或加固cron作业、定时任务脚本;后台无人值守脚本需提升可靠性;Agent长驻守护脚本的健康检查与告警;跨平台定时作业编写;CI定时任务与调度系统的被调度脚本

不适用场景: 调度系统本身的配置(时区/并发/熔断,由"定时调度专家"负责);非定时一次性脚本;纯业务逻辑bug修复(本skill聚焦环境与shell陷阱)

关键参数说明

典型流程: 逻辑进脚本→确定cwd/env→实现静默成功→添加trap清理与文件锁→上线前预检→本地模拟cron环境测试。跨平台用uname -s检测平台跑对应脚本,Windows用PowerShell等效模式。

输入规范

{
  "input": "定时任务脚本路径或命令",
  "options": {
    "mode": "create|query|export",
    "silent_success": true,
    "lock_file": "/tmp/cron-guard.lock"
  }
}

响应格式

{
  "success": true,
  "result": "NO_REPLY",
  "metadata": {
    "exit_code": 0,
    "duration_ms": 150,
    "locked": true
  }
}

错误恢复策略

前置条件

运行环境: Linux/macOS(POSIX)/Windows(PowerShell),bash 4+/sh/PowerShell 5+。本技能无需API Key;被守护脚本可能需外部API Key,必须通过环境变量引用并文档化,禁止硬编码。

可用性分类: MD+EXEC模式Markdown指南 + 脚本执行),Agent据此编写/审查cron脚本,实际执行由调度系统调用脚本

示例代码

POSIX cron 脚本模板

#!/usr/bin/env bash
set -euo pipefail

# 确定环境
cd "$(dirname "$0")/."
: "${API_KEY:?未设置API_KEY环境变量}"
export PATH="/usr/local/bin:/usr/bin:/bin"

# 文件锁防并发
exec 200>/tmp/cron-guard.lock
flock -n 200 || { echo "ALERT: 另一个实例正在运行" >&2; exit 0; }

# 静默成功约定
TMPFILE=$(mktemp)
trap 'rm -f "$TMPFILE"' EXIT

# 主逻辑
if python3 tools/job.py --input "$1" 2>"$TMPFILE"; then
    echo "NO_REPLY"
else
    echo "ALERT: 任务失败" >&2
    cat "$TMPFILE" >&2
    exit 1
fi

Windows PowerShell 等效模板

# cron-guard PowerShell 模式
$ErrorActionPreference = "Stop"
Set-Location -Path $PSScriptRoot

# 环境变量校验
if (-not $env:API_KEY) {
    Write-Error "未设置API_KEY环境变量"
    exit 1
}

# Mutex 防并发
$mutex = New-Object System.Threading.Mutex($false, "Global\cron-guard")
if (-not $mutex.WaitOne(0, $false)) {
    Write-Output "NO_REPLY"
    exit 0
}

# 静默成功
try {
    python3 tools/job.py --input $args[0]
    Write-Output "NO_REPLY"
} catch {
    Write-Error "ALERT: 任务失败 - $_"
    exit 1
} finally {
    $mutex.ReleaseMutex()
}

crontab 配置示例

# 每5分钟执行,静默成功,失败时告警
*/5 * * * * cd /opt/app && ./tools/cron-guard.sh >> /var/log/cron-guard.log 2>&1

# 每日凌晨备份,使用文件锁防重叠
0 2 * * * cd /opt/app && flock -n /tmp/backup.lock python3 tools/backup.py

热门问题

Q: NO_REPLY必须精确匹配吗? A: 是的,精确输出NO_REPLY(大写、无多余空格)。许多平台视为"静默成功"(不触发人工通知)。若平台不识别,等效于"成功时无输出"。

Q: pipefail到底该不该用? A: 该用,但要注意| head场景。set -euo pipefail是好习惯,遇到SIGPIPE误报时局部|| true或改用脚本读取。

Q: force-push真的完全禁止吗? A: 自动化脚本里禁止。cron作业绝不能force-push,会覆盖他人提交。被拒后用fetch+rebase重试。

能力限制说明

输入限制

• 脚本路径或命令长度：输入的脚本路径或命令长度不应超过系统允许的最大长度限制，通常POSIX系统中为1024字符。
• 参数数量：cron守护技能不支持大量的输入参数，通常cron作业的参数数量不应超过9个。
• 脚本内容复杂性：过于复杂的脚本可能无法正确解析或执行，建议脚本保持简洁，避免复杂的逻辑和循环。

性能边界

• 执行时间：cron守护技能对脚本执行时间有一定的限制，过长的执行时间可能导致cron守护技能超时。
• 资源消耗：脚本执行过程中不应消耗过多的系统资源，如CPU、内存等，以免影响系统稳定性。

兼容性约束

• 操作系统：cron守护技能主要支持POSIX兼容系统和Windows PowerShell，不支持其他操作系统。
• Shell类型：cron守护技能主要针对bash和sh，对于其他shell类型（如csh、tcsh等）可能存在兼容性问题。
• Python版本：cron守护技能依赖于Python 3，不支持Python 2或其他版本的Python。

其他限制

• 文件路径：输入的脚本路径不应包含特殊字符或路径分隔符，以免引起解析错误。
• 环境变量：cron守护技能对环境变量的使用有限制，建议仅在必要时使用，并确保其值正确。
• 网络访问：脚本中不应包含对网络的访问，以免影响cron守护技能的执行。

---

安全免责声明

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

量化评估

差异分析

功能能力

• 自动化执行: cron 作业可靠性护栏，脚本优先、确定环境、静默成功，跨平台故障模式一网打尽. 定时守护为cron作业与后台任务提供可
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

功能特性总览

定时守护为cron作业与后台任务提供可

• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

实操说明

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪

用户咨询

Q1: 定时守护支持哪些输入格式？

A1: cron 作业可靠性护栏，脚本优先、确定环境、静默成功，跨平台故障模式一网打尽. 定时守护为cron作业与后台任务提供可靠性护栏,遵循脚本优先、确定环境、静默成。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

错误处理指南

针对定时守护使用中可能遇到的常见问题,提供以下排查方案:

定时守护通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

常见疑问速答

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent
• 操作系统: Windows / macOS / Linux

可用性分类

• 分类: MD（纯Markdown指令，通过自然语言驱动Agent完成操作）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作。