cron

定时任务管理

什么时候用

只有在需要未来某个时间自动执行，或按周期重复执行时，使用本 skill。

应该使用

• 用户要求"每天 / 每周 / 每小时"执行某事
• 用户要求"明天 9 点 / 下周一 / 某个时间"自动提醒或执行
• 需要长期周期性通知、检查、汇报

不应使用

• 只是要现在立即执行一次
• 只是当前会话中的正常回复
• 用户没有明确执行时间或周期
• 目标 channel / user / session 还不明确

决策规则

1. 只有在未来定时执行或周期执行时才使用 cron
2. 如果只是立即做一次，通常不要创建 cron
3. 创建前必须确认执行时间/周期、目标 channel、target-user、target-session
4. 所有 cron 命令都必须显式传 --agent-id
5. 不要依赖默认 agent，否则任务可能落到 default workspace
6. 如果 agent 任务只需后台执行、不向渠道输出，添加 --silent；执行、会话历史、追踪和可选收件箱记录仍会继续

---

硬规则

必须显式指定 --agent-id

所有 qwenpaw cron 命令都必须传：

--agent-id <your_agent_id>

你的 agent_id 在系统提示中的 Agent Identity 部分（Your agent id is ...）。 不得省略，否则任务可能错误创建到 default agent 的 workspace。

---

常用命令

# 列出任务
qwenpaw cron list --agent-id <agent_id>

# 查看任务详情
qwenpaw cron get <job_id> --agent-id <agent_id>

# 查看任务状态
qwenpaw cron state <job_id> --agent-id <agent_id>

# 创建任务
qwenpaw cron create --agent-id <agent_id> ...

# 删除任务
qwenpaw cron delete <job_id> --agent-id <agent_id>

# 暂停 / 恢复任务
qwenpaw cron pause <job_id> --agent-id <agent_id>
qwenpaw cron resume <job_id> --agent-id <agent_id>

# 立即执行一次已有任务
qwenpaw cron run <job_id> --agent-id <agent_id>

# 更新已有任务
qwenpaw cron update <job_id> --agent-id <agent_id> ...

---

创建任务

支持两种类型：

• text：定时发送固定消息
• agent：定时向 agent 提问，并把回复发送到目标 channel

支持两种调度形态：

• cron（--schedule-type cron）：经典 cron 周期（如每天 9 点、每 2 小时），与循环任务相对应
• scheduled（--schedule-type scheduled）：日程任务（从 --run-at 开始，可一次性或按天重复）

调度选择规则（必须遵守）

• 用户表达“每小时/每天/每周”且不强调具体起始日时，优先用 cron
• 用户表达“明天/下周一/从某天开始/未来两周/有明确截止时间”时，优先用 scheduled
• scheduled 不重复时（即一次性任务）：只传 --run-at，不要传 --repeat-*
• scheduled 重复时：传 --repeat-every-days，并根据结束条件传：
  • 限定次数：--repeat-end-type count --repeat-count N
  • 限定结束时间：--repeat-end-type until --repeat-until <ISO8601>
  • 不设结束：--repeat-end-type never

超时设置

默认超时 120 秒（2 分钟）。对于较长的 agent 任务，应显式设置更大的超时时间，避免任务被提前取消：

--timeout 600   # 10 分钟
--timeout 3600   # 1 小时