定时守护

定时守护为无人值守的 cron 作业与后台任务提供可靠性护栏。它把"在 cron 里跑一行 bash"的高危模式，改造为"脚本优先、环境确定、静默成功"的工程化模式，覆盖 shell 引用陷阱、命令替换意外、cwd/env 漂移、SIGPIPE 误报、git 推送冲突等高频故障。 核心能力：脚本优先原则、确定环境...

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陷阱)

关键参数说明

方法/模式	关键参数	说明
脚本提取	tools/<job>.py或tools/<job>.sh	cron多行逻辑移入脚本,cron只跑python3 tools/<job>.py
确定cwd/env	cd "$(dirname "$0")/.", : "${VAR:?未设置}"	脚本开头确定cwd、显式设置PATH、校验环境变量
静默成功	echo "NO_REPLY"(成功), echo "ALERT" >&2(失败)	精确输出NO_REPLY,失败时告警到stderr
trap清理	trap 'rm -f "$TMPFILE"' EXIT	退出时清理临时文件
文件锁	flock -n 200或PowerShell Mutex	防止周期任务并发执行
本地模拟	env -i HOME="$HOME" PATH="..." bash -c '...'	模拟cron最小环境测试

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

输入规范

json

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

响应格式

json

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

错误恢复策略

场景	原因	处理方式
unexpected EOF	$(..)未闭合或bash -lc嵌套引号断裂	把多行shell替换为脚本,cron只跑python3 tools/<job>.py
本地能跑cron里失败	cwd不同、PATH不同、环境变量缺失	脚本内cd到仓库、显式设置PATH、文档化并校验环境变量
git push被拒(non-fast-forward)	远程有新提交,本地推送冲突	fetch后rebase再推送;禁止git push --force
临时文件残留导致冲突	脚本中断后临时文件未清理	用trap 'rm -f "$TMPFILE"' EXIT确保退出时清理
周期任务重叠数据冲突	上一轮未跑完下一轮就启动	用flock -n文件锁防并发,获取不到锁则静默跳过

前置条件

依赖项	类型	是否必需	获取方式
bash或PowerShell	Shell	必需	系统自带
Agent LLM	API	必需	由Agent内置LLM提供
python3	运行时	推荐(脚本载体)	系统自带或python.org
flock	CLI	Linux/Mac推荐(文件锁)	util-linux自带
curl	CLI	可选(健康检查)	系统自带

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

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

示例代码

POSIX cron 脚本模板

bash

#!/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 等效模板

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 配置示例

cron

# 每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守护技能的执行。

---

安全免责声明

风险类型	防范措施
API密钥泄露	通过环境变量传入,不在代码中硬编码
命令执行风险	限定执行预批准命令,不拼接用户输入到参数中
网络通信安全	通过HTTPS安全通信,验证证书有效性
敏感数据暴露	返回内容不包含敏感凭证

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

量化评估

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

差异分析

对比维度	定时守护	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	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能力。如遇权限问题，请参照错误处理章节排查。

错误处理指南

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

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

定时守护通用排查步骤

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

常见疑问速答

依赖说明

运行环境

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

可用性分类

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