schedule-task

定时任务技能

使用 cron 表达式创建和管理仅限 Shell 的任务。任务在后台运行，且仅记录输出日志。

适用场景

✅ 在以下情况下使用此技能：

• 定期清理任务
• 周期性数据处理
• 自动备份
• 定时维护

❌ 在以下情况下不要使用此技能：

• 向频道发送消息 → 使用 cron agent
• 需要用户交互的任务
• 复杂工作流（使用 SOP runner）

⚠️ 警告

Shell 任务的输出只会记录到日志，不会发送到任何频道。对于定时消息，请使用 cron_add，并设置 job_type='agent' 和投递配置。

用法

创建重复任务

const { schedule } = require('/job/.pi/skills/schedule-task/scheduler.js');

const task = await schedule('create', {
  expression: '0 2 * * *', // Daily at 2 AM
  command: 'node cleanup.js --older-than 7d',
  name: 'Daily cleanup',
  approved: true // Required for medium/high risk
});

console.log(task.id); // sched_abc123

创建一次性任务

// Run in 30 minutes
const once = await schedule('once', {
  delay: '30m',
  command: 'echo "Delayed task"'
});

// Run at specific time
const scheduled = await schedule('once', {
  runAt: '2026-02-26T09:00:00Z',
  command: 'node report.js'
});

列出任务

const tasks = await schedule('list');
console.log(tasks);
// [
//   { id: "sched_abc", expression: "0 2 * * *", command: "...", enabled: true },
//   ...
// ]

获取任务详情

const task = await schedule('get', { id: 'sched_abc123' });
console.log(task);
// {
//   id: "sched_abc123",
//   expression: "0 2 * * *",
//   command: "node cleanup.js",
//   enabled: true,
//   lastRun: "2026-02-25T02:00:00Z",
//   nextRun: "2026-02-26T02:00:00Z",
//   status: "scheduled"
// }

取消/移除任务

await schedule('cancel', { id: 'sched_abc123' });
// or
await schedule('remove', { id: 'sched_abc123' });

暂停/恢复任务

await schedule('pause', { id: 'sched_abc123' });
await schedule('resume', { id: 'sched_abc123' });

Cron 表达式

*    *    *    *    *
┬    ┬    ┬    ┬    ┬
│    │    │    │    │
│    │    │    │    └─ Day of week (0-7, 0=Sunday)
│    │    │    └────── Month (1-12)
│    │    └─────────── Day of month (1-31)
│    └──────────────── Hour (0-23)
└───────────────────── Minute (0-59)

示例

// Every 5 minutes
'*/5 * * * *'

// Every hour at 30 minutes past
'30 * * * *'

// Every day at 2:30 AM
'30 2 * * *'

// Every Monday at 9 AM
'0 9 * * 1'

// First day of month
'0 0 1 * *'

// Weekdays at noon
'0 12 * * 1-5'

// Complex: Every 15 min, 9 AM - 5 PM, weekdays
'*/15 9-17 * * 1-5'

延迟格式

// Minutes
'30m'  // 30 minutes

// Hours
'2h'   // 2 hours
'24h'  // 24 hours

// Days
'1d'   // 1 day
'7d'   // 7 days

// Combined
'1h30m'  // 1 hour 30 minutes
'2d12h'  // 2 days 12 hours

API

schedule(action, options = {})

操作： create、add、once、list、get、cancel、remove、pause、resume

选项：

• 对于 create/add：expression、command、name、approved
• 对于 once：delay 或 runAt、command
• 对于 get/cancel/remove/pause/resume：id

返回值：

// create/add/once
{ id: "sched_abc123", status: "scheduled" }

// list
[{ id, expression, command, enabled, lastRun, nextRun }]

// get
{ id, expression, command, enabled, lastRun, nextRun, status }

任务输出

所有任务输出都会记录到日志：

/job/logs/schedule/sched_abc123.log

[2026-02-25T02:00:00Z] Starting task: Daily cleanup
[2026-02-25T02:00:05Z] Cleaning 142 files...
[2026-02-25T02:00:10Z] Task completed (exit code: 0)

错误处理

try {
  await schedule('create', {
    expression: 'invalid',
    command: 'echo test'
  });
} catch (error) {
  if (error.code === 'INVALID_CRON') {
    console.error('Invalid cron expression');
  } else if (error.code === 'APPROVAL_REQUIRED') {
    console.error('Command requires approval');
  } else if (error.code === 'DUPLICATE') {
    console.error('Task already exists');
  }
}

Bash CLI

# Create task
node /job/.pi/skills/schedule-task/scheduler.js \
  --action create \
  --expression "0 2 * * *" \
  --command "node cleanup.js" \
  --name "Daily cleanup"

# List tasks
node /job/.pi/skills/schedule-task/scheduler.js --action list

# Cancel task
node /job/.pi/skills/schedule-task/scheduler.js \
  --action cancel \
  --id sched_abc123

安全

• 自主性级别检查
• 对中/高风险任务的命令审批
• 调度频率限制
• 防止 Shell 注入
• 沙箱执行（可选）

最佳实践

1. 安排任务前，先手动测试命令
2. 在脚本中使用明确的错误处理
3. 将日志写入文件以便调试
4. 为失败的任务设置监控
5. 在名称/描述中说明任务用途
6. 临时禁用时使用暂停，而不是移除