cron

Cron（定时任务管理）

何时使用

仅当你需要在未来某个时间自动执行某项操作或按计划重复执行时，才使用此技能。

应该使用

• 用户要求“每天 / 每周 / 每小时”做某件事
• 用户要求“明天上午 9 点 / 下周一 / 在某个特定时间”自动提醒或执行
• 需要长期的周期性通知、检查或报告

不应该使用

• 任务只需要现在立即执行一次
• 它只是当前会话中的普通回复
• 用户没有指定执行时间或计划
• 目标频道 / 用户 / 会话仍不明确

决策规则

1. 仅在未来的定时或周期性执行时使用 cron
2. 如果只需要立即执行一次，不要创建 cron 任务
3. 创建前，确认执行时间/计划、目标频道、目标用户和目标会话
4. 所有 cron 命令都必须显式包含 --agent-id
5. 不要依赖默认 Agent，否则任务可能会进入默认工作区
6. 对于不应输出到频道的 Agent 任务，添加 --silent；执行、会话历史、trace 以及可选的 Inbox 记录仍会继续
7. 当 requires_review 被设置时，绝不要运行或恢复导入的任务；请先在 Console 中审查并批准

---

硬性规则

必须显式指定 --agent-id

所有 qwenpaw cron 命令都必须包含：

--agent-id <your_agent_id>

你的 agent_id 可在系统提示词的 Agent Identity 部分找到（Your agent id is ...）。 不要省略它，否则任务可能会被错误地创建到默认 Agent 的工作区中。

---

常用命令

# List tasks
qwenpaw cron list --agent-id <agent_id>

# View task details
qwenpaw cron get <job_id> --agent-id <agent_id>

# View task status
qwenpaw cron state <job_id> --agent-id <agent_id>

# Create a task
qwenpaw cron create --agent-id <agent_id> ...

# Delete a task
qwenpaw cron delete <job_id> --agent-id <agent_id>

# Pause / Resume a task
qwenpaw cron pause <job_id> --agent-id <agent_id>
qwenpaw cron resume <job_id> --agent-id <agent_id>

# Run an existing task once immediately
qwenpaw cron run <job_id> --agent-id <agent_id>

# Update an existing task
qwenpaw cron update <job_id> --agent-id <agent_id> ...

---

创建任务

支持两种类型：

• text：按计划发送固定消息
• agent：按计划向 Agent 提问，并将回复发送到目标频道

支持两种计划模式：

• cron（--schedule-type cron）：经典 cron 重复（例如每天 09:00 或每 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 minutes
--timeout 3600   # 1 hour

核心规则：

1. 如果 Agent 任务涉及网页搜索、代码执行或多步工具调用，请设置 --timeout 600 或更高
2. 超时必须小于调度间隔，以防止重叠（上一次仍在执行时又触发新的一次运行）。例如：
   • 每 15 分钟：--timeout 不应超过 900 秒
   • 每 10 分钟：--timeout 建议不超过间隔的 80%（即 480 秒）
   • 每天：--timeout 可以更大，无需特别限制
3. 对于高频任务（间隔 ≤ 10 分钟），遵循超时 ≤ 间隔的 80%；对于低频任务（每小时或以上），根据实际需要设置

创建前必须提供的最少信息

• --type
• --name
• --schedule-type
• --cron（当 --schedule-type cron 时）
• --run-at（当 --schedule-type scheduled 时）
• --channel
• --target-user
• --target-session
• --text
• --agent-id
• --timeout（对于 agent 类型任务，根据预期执行时间设置合适的超时）

如果缺少上述任何信息，请在创建任务前与用户确认。

创建示例

# Recurring task (--schedule-type cron)
qwenpaw cron create \
  --agent-id <agent_id> \
  --type text \
  --schedule-type cron \
  --name "Daily Greeting" \
  --cron "0 9 * * *" \
  --channel imessage \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "Good morning!"

# Recurring task (--schedule-type cron)
qwenpaw cron create \
  --agent-id <agent_id> \
  --type agent \
  --schedule-type cron \
  --name "Check Todos" \
  --cron "0 */2 * * *" \
  --channel dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "What are my pending tasks?" \
  --timeout 600

对于后台 agent 任务，在上述命令中添加 --silent。不要将其用于 text 任务。

# Scheduled one-time: remind at 9 AM tomorrow (no repeat)
qwenpaw cron create \
  --agent-id <agent_id> \
  --type text \
  --schedule-type scheduled \
  --name "Tomorrow Morning Reminder" \
  --run-at "2026-05-13T09:00:00+08:00" \
  --channel dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "Standup starts at 9:00." \
  --save-result-to-inbox

# Scheduled repeating: next two weeks, every day at 9 AM (14 runs)
qwenpaw cron create \
  --agent-id <agent_id> \
  --type text \
  --schedule-type scheduled \
  --name "Two-week Standup Reminder" \
  --run-at "2026-05-13T09:00:00+08:00" \
  --repeat-every-days 1 \
  --repeat-end-type count \
  --repeat-count 14 \
  --channel dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "Standup starts at 9:00." \
  --save-result-to-inbox

从 JSON 创建

qwenpaw cron create --agent-id <agent_id> -f job_spec.json

---

最小工作流

1. Determine whether this truly requires "future scheduling" or "periodic execution"
2. Confirm execution time/schedule
3. Confirm channel, target-user, target-session
4. Explicitly include --agent-id
5. Create the task with qwenpaw cron create
6. Manage tasks afterwards with list / state / pause / resume / delete

审查导入的任务

由 PawPort 导入的任务会被禁用，并受不可绕过的审查门控保护。

请在 Console Cron Jobs 页面中审查并批准导入的任务。批准会记录审查结果，但任务仍保持禁用状态。只有在用户明确要求时，才在那里单独启用它。

---

Cron 表达式示例

0 9 * * *      Every day at 9:00
0 */2 * * *    Every 2 hours
30 8 * * 1-5   Weekdays at 8:30
0 0 * * 0      Every Sunday at midnight
*/15 * * * *   Every 15 minutes

---

常见错误

错误 1：为一次性立即执行创建 cron 任务

如果任务只需要在现在执行一次，请不要创建 cron 任务。

错误 2：未传入 --agent-id

这会导致任务被分配给错误的 agent / 工作区。所有 cron 命令都必须显式包含 --agent-id。

错误 3：在信息不完整的情况下创建任务

如果用户未指定时间、计划、目标频道或目标会话，请先询问以获得澄清。

错误 4：未先检查就修改现有任务

在暂停、恢复或删除之前，请先运行：

qwenpaw cron list --agent-id <agent_id>

以找到正确的 job_id。

---

使用提示

• 当缺少参数时，请在创建前询问用户
• 在修改/暂停/删除之前，先运行 qwenpaw cron list --agent-id <agent_id>
• 要排查问题，请使用 qwenpaw cron state <job_id> --agent-id <agent_id>
• 向用户展示命令时，请提供完整、可复制粘贴的版本
• 如果用户提到“保存到收件箱”（或未提到），请显式包含 --save-result-to-inbox 或 --no-save-result-to-inbox
• 如果用户要求后台或静默执行且不返回频道回复，请在 agent 任务上使用 --silent
• 在创建之前，你可以运行 qwenpaw chats list --agent-id <agent_id> 来获取有效的 target-user 和 target-session

---

帮助信息

qwenpaw cron -h
qwenpaw cron list -h
qwenpaw cron create -h
qwenpaw cron get -h
qwenpaw cron state -h
qwenpaw cron pause -h
qwenpaw cron resume -h
qwenpaw cron delete -h
qwenpaw cron run -h