schedule-task

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Schedule Task Skill

定时任务技能

Create and manage scheduled shell-only tasks using cron expressions. Tasks run in background and log output only.

使用cron表达式创建并管理仅基于Shell的定时任务。任务在后台运行，仅记录输出日志。

When to Use

适用场景

✅ USE this skill when:

Recurring cleanup jobs
Periodic data processing
Automated backups
Scheduled maintenance

❌ DON'T use this skill when:

Sending messages to channels → use cron agent
Tasks requiring user interaction
Complex workflows (use SOP runner)

✅ 推荐使用本技能的场景：

重复执行的清理任务
周期性数据处理
自动化备份
定时维护

❌ 不推荐使用本技能的场景：

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

⚠️ WARNING

⚠️ 注意事项

Shell task output is only logged, not delivered to any channel. For scheduled messages, use

cron_add

with

job_type='agent'

and delivery config.

Shell任务的输出仅会记录到日志，不会发送到任何频道。如需定时发送消息，请使用

cron_add

并设置

job_type='agent'

及投递配置。

Usage

使用方法

Create Recurring Task

创建重复任务

javascript

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

javascript

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

Create One-Time Task

创建一次性任务

javascript

// 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'
});

javascript

// 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'
});

List Tasks

列出所有任务

javascript

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

javascript

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

Get Task Details

获取任务详情

javascript

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"
// }

javascript

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"
// }

Cancel/Remove Task

取消/删除任务

javascript

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

javascript

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

Pause/Resume Task

暂停/恢复任务

javascript

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

javascript

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

Cron Expressions

Cron表达式

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

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

Examples

示例

javascript

// 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'

javascript

// 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'

Delay Formats

延迟格式

javascript

// 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

javascript

// 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

javascript

schedule(action, options = {})

Actions:

create

add

once

list

get

cancel

remove

pause

resume

Options:

For create/add:
```
expression
```
,
```
command
```
,
```
name
```
,
```
approved
```
For once:
```
delay
```
or
```
runAt
```
,
```
command
```
For get/cancel/remove/pause/resume:
```
id
```

Returns:

javascript

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

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

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

javascript

schedule(action, options = {})

操作类型：

create

add

once

list

get

cancel

remove

pause

resume

参数选项：

创建/添加任务：
```
expression
```
,
```
command
```
,
```
name
```
,
```
approved
```
一次性任务：
```
delay
```
或
```
runAt
```
,
```
command
```
获取/取消/删除/暂停/恢复任务：
```
id
```

返回值：

javascript

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

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

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

Task Output

任务输出

All task output goes to logs:

/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)

所有任务输出都会写入日志文件：

/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)

Error Handling

错误处理

javascript

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');
  }
}

javascript

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

Bash命令行工具

bash

undefined

bash

undefined

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

undefined

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

undefined

Security

安全机制

Autonomy level checks
Command approval for medium/high risk
Rate limiting on scheduling
Shell injection prevention
Sandbox execution (optional)

自主权限等级检查
中/高风险命令需审批
任务调度频率限制
Shell注入防护
沙箱执行（可选）

Best Practices

最佳实践

Test commands manually before scheduling
Use specific error handling in scripts
Log to files for debugging
Set up monitoring for failed tasks
Document task purpose in name/description
Use pause instead of remove for temporary disable

调度前手动测试命令
在脚本中使用特定的错误处理逻辑
将日志写入文件以便调试
为失败任务设置监控
在任务名称/描述中注明任务用途
临时禁用任务时使用暂停而非删除