跳到主要内容

计划任务(Cron)

使用自然语言或 cron 表达式安排任务自动运行。Kopi Agent 通过单个 cronjob 工具以操作式(action-style)的接口管理 cron,而不是使用独立的 schedule/list/remove 工具。

Cron 目前能做什么​

Cron 任务可以:

  • 安排一次性或周期性任务
  • 暂停、恢复、编辑、触发和移除任务
  • 为任务附加零个、一个或多个 skills
  • 将结果投递回原始聊天、本地文件或已配置的平台目标
  • 在全新的 agent 会话中运行,使用常规的静态工具列表
  • 以 no-agent 模式运行 —— 按计划运行一个脚本,其 stdout 原样投递,完全不涉及 LLM(参见下文的 no-agent 模式章节)

以上所有功能都通过 cronjob 工具对 Kopi Agent 本身开放,因此你只需用日常语言提出需求,就能创建、暂停、编辑和移除任务 —— 无需 CLI。

提示

创建时,未固定的任务(即未明确指定 provider/model 的任务)会遵循 kopi model 选择的全局默认值 —— Kopi Agent 会将该 provider 和 model 快照保存到任务中。如果之后全局默认值发生变化,该任务会安全失败(fail closed):跳过本次运行、不发起任何推理调用,并发送告警,提示你需要显式固定 provider/model(cronjob action=update job_id=… provider=… model=…)才能继续。这可以防止无人值守的任务默默继承到付费的 provider/model,产生你并不打算支付的费用(#44585)。如果希望任务有意跟踪全局默认值,请在更改后将其固定到新的值。kopi setup --portal 是无人值守运行中摩擦最低的选择,因为 OAuth 刷新是自动完成的。参见 KOPI Proxy。

注意

Cron 运行的会话不能递归创建更多 cron 任务。Kopi Agent 会在 cron 执行过程中禁用 cron 管理工具,以防止调度循环失控。

创建计划任务​

在聊天中使用 /cron​

/cron add 30m "Remind me to check the build"
/cron add "every 2h" "Check server status"
/cron add "every 1h" "Summarize new feed items" --skill blogwatcher
/cron add "every 1h" "Use both skills and combine the result" --skill blogwatcher --skill maps

通过独立的 CLI​

kopi cron create "every 2h" "Check server status"
kopi cron create "every 1h" "Summarize new feed items" --skill blogwatcher
kopi cron create "every 1h" "Use both skills and combine the result" \
--skill blogwatcher \
--skill maps \
--name "Skill combo"

通过自然对话​

正常地向 Kopi Agent 提问:

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

Kopi Agent 会在内部使用统一的 cronjob 工具。

基于 Skill 的 cron 任务​

Cron 任务可以在运行 prompt 之前加载一个或多个 skills。

单个 skill​

cronjob(
action="create",
skill="blogwatcher",
prompt="Check the configured feeds and summarize anything new.",
schedule="0 9 * * *",
name="Morning feeds",
)

多个 skill​

Skills 会按顺序加载。prompt 则成为叠加在这些 skills 之上的任务指令。

cronjob(
action="create",
skills=["blogwatcher", "maps"],
prompt="Look for new local events and interesting nearby places, then combine them into one short brief.",
schedule="every 6h",
name="Local brief",
)

当你希望计划运行的 agent 继承可复用的工作流,而不必将完整的 skill 文本塞进 cron prompt 本身时,这非常有用。

在项目目录中运行任务​

Cron 任务默认与任何仓库解耦运行 —— 不加载 AGENTS.md、CLAUDE.md 或 .cursorrules,终端 / 文件 / 代码执行工具会在网关启动时所在的工作目录中运行。传入 --workdir(CLI)或 workdir=(工具调用)可以更改这一点:

# Standalone CLI (schedule and prompt are positional)
kopi cron create "every 1d at 09:00" \
"Audit open PRs, summarize CI health, and post to #eng" \
--workdir /home/me/projects/acme
# From a chat, via the cronjob tool
cronjob(
action="create",
schedule="every 1d at 09:00",
workdir="/home/me/projects/acme",
prompt="Audit open PRs, summarize CI health, and post to #eng",
)

设置 workdir 后:

  • 该目录中的 AGENTS.md、CLAUDE.md 和 .cursorrules 会被注入系统 prompt(发现顺序与交互式 CLI 相同)
  • terminal、read_file、write_file、patch、search_files 和 execute_code 都以该目录作为工作目录
  • 路径必须是已存在的绝对目录 —— 相对路径和不存在的目录会在创建 / 更新时被拒绝
  • 编辑时传入 --workdir ""(或通过工具传入 workdir="")可清除它并恢复原有行为
序列化

带 workdir 的任务会在调度器 tick 上顺序运行,而不是进入并行池。这是有意为之:cron worker 通过进程级全局终端状态应用任务的 workdir,因此两个 workdir 任务同时运行会互相破坏对方的 cwd。没有 workdir 的任务仍像之前一样并行运行。

编辑任务​

无需为了修改任务而删除再重新创建。

任务引用

下文(以及生命周期操作中)的 <job_id> 占位符也接受任务的名称(不区分大小写)—— 当你记得 morning-digest 但忘了十六进制 ID 时很方便。精确匹配的任务 ID 优先于名称匹配;如果引用不是 ID 且名称匹配到多个任务,命令会拒绝执行并打印候选 ID,供你区分。

聊天​

/cron edit <job_id> --schedule "every 4h"
/cron edit <job_id> --prompt "Use the revised task"
/cron edit <job_id> --skill blogwatcher --skill maps
/cron edit <job_id> --remove-skill blogwatcher
/cron edit <job_id> --clear-skills

独立 CLI​

kopi cron edit <job_id> --schedule "every 4h"
kopi cron edit <job_id> --prompt "Use the revised task"
kopi cron edit <job_id> --skill blogwatcher --skill maps
kopi cron edit <job_id> --add-skill maps
kopi cron edit <job_id> --remove-skill blogwatcher
kopi cron edit <job_id> --clear-skills

说明:

  • 重复的 --skill 会替换任务已附加的 skill 列表
  • --add-skill 会追加到现有列表,而不是替换它
  • --remove-skill 移除特定的已附加 skills
  • --clear-skills 移除所有已附加 skills

生命周期操作​

Cron 任务现在拥有比单纯的创建/移除更完整的生命周期。

聊天​

/cron list
/cron pause <job_id>
/cron resume <job_id>
/cron run <job_id>
/cron remove <job_id>

独立 CLI​

kopi cron list
kopi cron pause <job_id_or_name>
kopi cron resume <job_id_or_name>
kopi cron run <job_id_or_name>
kopi cron remove <job_id_or_name>
kopi cron edit <job_id_or_name> [...flags]
kopi cron status
kopi cron tick

各操作的作用:

  • pause —— 保留任务但停止为其调度
  • resume —— 重新启用任务并计算下一次未来的运行时间
  • run —— 在下一个调度器 tick 触发该任务
  • remove —— 彻底删除它
  • edit —— 修改调度计划、prompt、投递方式等

基于名称的查找。所有四个变更类动词(pause、resume、run、remove、edit)以及 agent 的 cronjob 工具现在都接受用任务名称(不区分大小写)代替十六进制 ID。如果存在精确匹配的 ID,agent 和 CLI 都会优先使用 ID;对于有歧义的名称匹配(多个任务同名),会连同完整的候选 ID 列表一起拒绝执行,供你显式选择。名称并非唯一,因此这道保护至关重要 —— 它可以防止在两个任务同名时误操作了错误的任务。

工作原理​

Cron 任务的执行由 gateway daemon(网关守护进程)处理。 gateway 每 60 秒触发一次调度器,在隔离的 agent 会话中运行所有到期的 job。

kopi gateway install     # Install as a user service
sudo kopi gateway install --system # Linux: boot-time system service for servers
kopi gateway # Or run in foreground

kopi cron list
kopi cron status

Gateway 调度器行为​

每次触发时,Kopi Agent 会:

  1. 从 ~/.kopi/cron/jobs.json 加载 job
  2. 将 next_run_at 与当前时间进行比对
  3. 为每个到期的 job 启动一个全新的 AIAgent 会话
  4. 可选地向该全新会话注入一个或多个已附加的 skill
  5. 运行 prompt 直至完成
  6. 传递最终响应
  7. 更新运行元数据和下一次调度时间

~/.kopi/cron/.tick.lock 处的文件锁可防止调度器触发发生重叠时重复运行同一批 job。

投递选项​

在安排任务时,你需要指定输出的去向:

选项说明示例
"origin"回到任务创建的地方消息平台上的默认选项
"local"仅保存到本地文件(~/.kopi/cron/output/)CLI 上的默认选项
"telegram"Telegram 主频道使用 TELEGRAM_HOME_CHANNEL
"telegram:123456"通过 ID 指定 Telegram 会话直接投递
"telegram:-100123:17585"指定 Telegram 话题chat_id:thread_id 格式
"discord"Discord 主频道使用 DISCORD_HOME_CHANNEL
"discord:#engineering"指定 Discord 频道按频道名称
"slack"Slack 主频道
"whatsapp"WhatsApp 主会话
"signal"Signal
"matrix"Matrix 主房间
"mattermost"Mattermost 主频道
"email"电子邮件
"sms"通过 Twilio 发送短信
"homeassistant"Home Assistant
"dingtalk"钉钉(DingTalk)
"feishu"飞书(Feishu/Lark)
"wecom"企业微信(WeCom)
"weixin"微信(Weixin)
"bluebubbles"BlueBubbles (iMessage)
"qqbot"QQ 机器人(腾讯 QQ)
"all"分发到每一个已连接的主频道在触发时解析
"telegram,discord"分发到指定的一组频道以逗号分隔的列表
"origin,all"投递到来源以及所有其他已连接的频道可组合任意 token

Agent 的最终响应会自动投递到配置的 deliver: 目标 —— agent 本身不发送消息,因此在 cron prompt 中无需调用任何发送方法。

路由意图(all)​

all 让你把一个 cron 任务发送到所有已配置的消息频道,而无需逐个列出它们的名称。它在触发时解析,因此在你接入 Telegram 之前创建的任务,会在你设置 TELEGRAM_HOME_CHANNEL 之后的下一个触发点自动包含 Telegram。

语义:all 会展开为所有已配置主频道的平台。零个也没问题;该任务只是不产生任何投递目标,并在上游被记录为投递失败。

all 可与显式目标组合使用。origin,all 会投递到来源会话以及所有其他已连接的主频道,并按 (platform, chat_id, thread_id) 去重。

Telegram cron 话题(TELEGRAM_CRON_THREAD_ID)​

当 Telegram 话题模式启用时,根私信被保留为系统大厅 —— 发送到那里的回复会被大厅提醒拒绝,并且 reply_to_message_id 会被丢弃,因此你无法回复落在主聊天中的 cron 消息。

请改为将 cron 指向一个专用的论坛话题:

  1. 在 Telegram 中打开机器人私信并创建一个话题,例如命名为 Cron。长按话题标题 → 复制链接;末尾的整数就是该话题的 message_thread_id。
  2. 在你的 .env 中设置 TELEGRAM_CRON_THREAD_ID=<that id>。

这仅适用于 cron 投递。TELEGRAM_HOME_CHANNEL_THREAD_ID(用于其他场景,例如重启通知)保持不变。显式的 deliver="telegram:chat_id:thread_id" 目标仍然优先于环境变量。对 cron 消息的回复现在会到达已有的话题会话中,因此你可以直接处理它们。

响应包装​

默认情况下,投递的 cron 输出会被包装上页眉和页脚,以便接收者知道它来自一个定时任务:

Cronjob Response: Morning feeds
-------------

<agent output here>

Note: The agent cannot see this message, and therefore cannot respond to it.

要投递未经包装的原始 agent 输出,请将 cron.wrap_response 设置为 false:

# ~/.kopi/config.yaml
cron:
wrap_response: false

可继续的任务(回复 cron 投递)​

默认情况下,cron 投递是一次性即忘的:消息发送出去后,并不会保存在该会话的对话历史中,因此如果你回复它,agent 无从得知自己说过什么。将任务设置为可继续(continuable),投递的简报就会变成一个你可以回复的对话 —— agent 在上下文中持有该简报,而不是问"Task #2 是什么?"。

需主动启用,默认关闭。可在配置中全局启用,也可通过 cronjob 工具的 attach_to_session 按任务启用(它会为该单个任务覆盖全局设置):

# ~/.kopi/config.yaml
cron:
mirror_delivery: false # set true to make cron deliveries continuable

行为为优先使用线程,作用范围限定在任务的来源会话:

  • 支持线程的平台(Telegram 话题、Discord/Slack 线程):每次投递都会开启自己的专用线程,简报被写入该线程的会话,因此在线程内回复即可带着完整上下文继续对话。重复任务(例如每日简报)每次运行都会开启新线程,使每次投递的后续讨论相互隔离。
  • 仅支持私信的平台(WhatsApp、Signal、SMS):不存在线程,因此简报会被镜像写入来源私信会话 —— 私信本身就是继续对话的载体。

只会影响来源会话:分发/广播目标(all、显式的其他会话投递)永远不会被设为可继续。镜像会以带标签的用户轮次([Cron delivery: <task name>])写入,这使对话历史在所有模型 provider 之间保持交替安全。

平铺式频道内继续(Slack)​

上述优先使用线程的行为会在每次投递时创建一个专用线程。如果你更希望可继续的任务平铺在频道时间线中(不创建线程),请将 Slack 的 continuable surface 设置为 in_channel:

# ~/.kopi/config.yaml
slack:
cron_continuable_surface: in_channel # default: thread
reply_in_thread: false # required pairing (see below)
require_mention: false # so a plain reply continues the job

在 in_channel 模式下,简报作为普通的顶层频道消息投递(不开启线程),你的回复通过该频道的共享会话继续该任务。三个设置配合使用:

  • cron_continuable_surface: in_channel —— 投递时跳过创建线程。
  • reply_in_thread: false(必需)—— 让机器人平铺在频道中回答你的回复,并将其绑定到简报所写入的同一整频道会话。没有它,继续仍然有效,但会以线程形式出现(它会安全地回退到线程式继续,绝不会丢失回复 —— 网关会在启动时记录警告,方便你发现配置不匹配)。
  • require_mention: false(或将该频道添加到 free_response_channels) —— 这样你就可以用普通消息回复;否则机器人只会在你每次回复时 @ 提及它时才会被唤醒。

由于继续使用的是整频道会话,它是共享的:频道中的其他聊天内容 —— 以及第二个频道内的可继续任务 —— 都会加入同一个滚动对话。这是"平铺在频道中"固有的特性,也是 reply_in_thread: false 用户早已接受的权衡;当你希望每次投递的后续讨论相互隔离时,请使用默认的 thread surface。

这目前是 Slack 的能力。其他平台接受该键但会回退到 thread surface(它们的继续原语不同);该选择按平台设置,位于各平台的配置下。这是一个网关侧的配置标志 —— /restart 即可生效;无需重新安装 Slack 应用。

一对一直聊

cron_continuable_surface 是一个频道级设置 —— 一对一直聊没有线程与时间线之分可供选择(私信本身就是平铺的),因此该键在那里不起作用。决定私信 cron 投递是否可继续的是另一个早已存在的开关 slack.dm_top_level_threads_as_sessions:

  • false —— 所有顶层私信共享同一个滚动私信会话,因此可继续的 cron 简报和你的回复会落在同一个会话中,任务得以带着上下文继续。这就是你在私信中使用可继续 cron 时想要的效果。
  • true(默认)—— 每条顶层私信消息各自是一个会话,因此对已投递简报的回复会开启一个全新会话,其中没有简报的任何记录。在此模式下继续不可用(对 cron 或任何其他平铺投递均如此)。

因此,对于投递到一对一直聊的可继续 cron 任务,请设置 slack.dm_top_level_threads_as_sessions: false。对于私信,cron_continuable_surface 不是必需的(并且会被忽略)。

静默抑制​

如果 agent 的最终响应包含 [SILENT],投递会被完全抑制。输出仍会保存在本地以供审计(保存在 ~/.kopi/cron/output/),但不会向投递目标发送任何消息。

这对于只应在出现问题时才报告的监控任务非常有用:

Check if nginx is running. If everything is healthy, respond with only [SILENT].
Otherwise, report the issue.

失败的任务无论是否含 [SILENT] 标记都始终会投递 —— 只有成功的运行才能被静音。对于安静的监控任务,请提示 agent 在无事可报时仅回复 [SILENT]。

脚本超时​

预运行脚本(通过 script 参数附加)的默认超时时间为 3600 秒(1 小时)。该值仅限定脚本本身——基于 skill / 由 LLM 驱动的作业运行在单独的不活动预算机制下,不受此值限制。如果你的脚本需要不同的限制,可以这样修改:

# ~/.kopi/config.yaml
cron:
script_timeout_seconds: 1800 # 30 minutes

或者设置 KOPI_CRON_SCRIPT_TIMEOUT 环境变量。解析优先级为:环境变量 → config.yaml → 3600 秒默认值。

无 agent 模式(仅脚本作业)​

对于不需要 LLM 推理的周期性作业——经典的看门狗、磁盘/内存告警、心跳、CI ping——在创建时传入 no_agent=True。调度器会按计划运行你的脚本,并直接投递其 stdout,完全跳过 agent:

kopi cron create "every 5m" \
--no-agent \
--script memory-watchdog.sh \
--deliver telegram \
--name "memory-watchdog"

语义:

  • 脚本 stdout(去除首尾空白后)→ 原样作为消息投递。
  • 空 stdout → 静默 tick,不进行任何投递。这就是看门狗模式:"只在出问题时才说话"。
  • 非零退出码或超时 → 投递错误告警,因此损坏的看门狗不会悄无声息地失败。
  • 最后一行包含 {"wakeAgent": false} → 静默 tick(与 LLM 作业使用的门控机制相同)。
  • 不消耗 token,不调用模型,不涉及 provider(服务提供商)回退——作业完全不触碰推理层。

.sh / .bash 文件在 /bin/bash 下运行;其他文件则在当前 Python 解释器(sys.executable)下运行。脚本必须位于 ~/.kopi/scripts/ 中(与预运行脚本门控相同的沙箱规则)。

agent 会为你完成这些设置​

cronjob 工具的 schema 会把 no_agent 直接暴露给 Kopi Agent,因此你可以在聊天中描述一个看门狗,让 agent 来搭建它:

Ping me on Telegram if RAM is over 85%, every 5 minutes.

Kopi Agent 会通过 write_file 将检查脚本写入 ~/.kopi/scripts/,然后调用:

cronjob(action="create", schedule="every 5m",
script="memory-watchdog.sh", no_agent=True,
deliver="telegram", name="memory-watchdog")

当消息内容完全由脚本确定时(看门狗、阈值告警、心跳),它会自动选择 no_agent=True。同一个工具还允许 agent 暂停、恢复、编辑和移除作业——因此整个生命周期都由聊天驱动,无需任何人操作 CLI。

有关完整示例,请参阅仅脚本的 Cron 作业指南。

通过 context_from 串联作业​

Cron 作业在隔离的会话中运行,不会记忆之前的运行结果。但有时某个作业的输出恰好是下一个作业所需要的。context_from 参数会自动建立这种连接——Job B 的 prompt 会在运行时把 Job A 最近一次输出作为上下文前置。

# Job 1: Collect raw data
cronjob(
action="create",
prompt="Fetch the top 10 AI/ML stories from Hacker News. Save them to ~/.kopi/data/briefs/raw.md in markdown format with title, URL, and score.",
schedule="0 7 * * *",
name="AI News Collector",
)

# Job 2: Triage — receives Job 1's output as context
# Get Job 1's ID from: cronjob(action="list")
cronjob(
action="create",
prompt="Read ~/.kopi/data/briefs/raw.md. Score each story 1–10 for engagement potential and novelty. Output the top 5 to ~/.kopi/data/briefs/ranked.md.",
schedule="30 7 * * *",
context_from="<job1_id>",
name="AI News Triage",
)

# Job 3: Ship — receives Job 2's output as context
cronjob(
action="create",
prompt="Read ~/.kopi/data/briefs/ranked.md. Write 3 tweet drafts (hook + body + hashtags). Deliver to telegram:7976161601.",
schedule="0 8 * * *",
context_from="<job2_id>",
name="AI News Brief",
)

工作原理:

  • 当 Job 2 触发时,Kopi Agent 会从 ~/.kopi/cron/output/{job1_id}/*.md 读取 Job 1 最近一次的输出
  • 该输出会自动前置到 Job 2 的 prompt 中
  • Job 2 无需硬编码"读取这个文件"——它会将内容作为上下文接收
  • 链条可以任意长:Job 1 → Job 2 → Job 3 → ...

context_from 接受的格式:

格式示例
单个作业 ID(字符串)context_from="a1b2c3d4"
多个作业 ID(列表)context_from=["job_a", "job_b"]

输出会按列出的顺序拼接。

使用场景:

  • 多阶段流水线(采集 → 过滤 → 格式化 → 投递)
  • 有依赖关系的任务,其中第 N 步的工作依赖于第 N−1 步的输出
  • 扇出/扇入模式,由一个作业聚合多个其他作业的结果

Provider 恢复​

Cron 作业会继承你配置的 fallback provider(回退服务提供商)和凭证池轮换。如果主 API key 受到速率限制,或者 provider 返回错误,cron agent 可以:

  • 回退到备用 provider,前提是你在 config.yaml 中配置了 fallback_providers(或旧版的 fallback_model)
  • 轮换到下一个凭证,在凭证池中为同一 provider 轮换

这意味着高频运行或在高峰时段运行的 cron 作业具有更强的韧性——单个受速率限制的 key 不会导致整个运行失败。

调度格式​

agent 的最终响应会自动投递到作业的 deliver: 目标——agent 不再自行发送消息,因此面向用户的内容只需放在最终响应中即可。要投递到额外或不同的目标,请在 cron 作业上列出多个 deliver: 目标(用逗号分隔,例如 deliver: "telegram,discord"),而不是让 agent 去发送。

相对延迟(一次性)​

30m     → Run once in 30 minutes
2h → Run once in 2 hours
1d → Run once in 1 day

间隔(周期性)​

every 30m    → Every 30 minutes
every 2h → Every 2 hours
every 1d → Every day

Cron 表达式​

0 9 * * *       → Daily at 9:00 AM
0 9 * * 1-5 → Weekdays at 9:00 AM
0 */6 * * * → Every 6 hours
30 8 1 * * → First of every month at 8:30 AM
0 0 * * 0 → Every Sunday at midnight

ISO 时间戳​

2026-03-15T09:00:00    → One-time at March 15, 2026 9:00 AM

重复行为​

调度类型默认重复次数行为
一次性(30m、时间戳)1运行一次
间隔(every 2h)永久运行直到被移除
Cron 表达式永久运行直到被移除

你可以覆盖它:

cronjob(
action="create",
prompt="...",
schedule="every 2h",
repeat=5,
)

以编程方式管理作业​

面向 agent 的 API 只有一个工具:

cronjob(action="create", ...)
cronjob(action="list")
cronjob(action="update", job_id="...")
cronjob(action="pause", job_id="...")
cronjob(action="resume", job_id="...")
cronjob(action="run", job_id="...")
cronjob(action="remove", job_id="...")

对于 update,传入 skills=[] 即可移除所有附加的 skill。

Cron 任务可用的工具集​

Cron 会在一个全新的 agent 会话中运行每个任务,且不附加任何聊天平台。默认情况下,cron agent 会获得你在 kopi tools 中为 cron 平台配置的工具集 —— 既不是 CLI 默认工具集,也不是所有工具的大杂烩。

kopi tools
# → pick the "cron" platform in the curses UI
# → toggle toolsets on/off just like you would for Telegram/Discord/etc.

通过 cronjob.create 上的 enabled_toolsets 字段(或通过 cronjob.update 为现有任务设置)可以实现更细粒度的按任务控制:

cronjob(action="create", name="weekly-news-summary",
schedule="every sunday 9am",
enabled_toolsets=["web", "file"], # just web + file, no terminal/browser/etc.
prompt="Summarize this week's AI news: ...")

当任务上设置了 enabled_toolsets 时,以该设置为准;否则以 kopi tools 的 cron 平台配置为准;否则 Kopi Agent 会回退到内置默认值。这对成本控制很重要:把 browser、delegation 塞进每一个小小的“抓取新闻”任务里,会在每次 LLM 调用时都撑大工具 schema 提示词。

完全跳过 agent:wakeAgent​

如果你的 cron 任务附加了预检脚本(通过 script=),该脚本可以在运行时决定 Kopi Agent 是否应当调用 agent。输出一行形如以下格式的最终 stdout:

{"wakeAgent": false}

……cron 就会在本次调度周期完全跳过 agent 运行。这在频繁轮询(每 1–5 分钟一次)且只有状态真正发生变化时才需要唤醒 LLM 的场景下非常有用 —— 否则你会为一轮又一轮毫无内容的 agent 回合反复付费。

# pre-check script
import json, sys
latest = fetch_latest_issue_count()
prev = read_state("issue_count")
if latest == prev:
print(json.dumps({"wakeAgent": False})) # skip this tick
sys.exit(0)
write_state("issue_count", latest)
print(json.dumps({"wakeAgent": True, "context": {"new_issues": latest - prev}}))

当省略 wakeAgent 时,默认值为 true(照常唤醒 agent)。

实用方案:低成本的预运行门控​

wakeAgent 门控让你以 0 美元的成本决定一个定时任务是否应该花费任何 LLM token。三种模式即可覆盖绝大多数用例。

文件变更门控 —— 仅当被监视的文件自上次成功调度周期以来有新内容时才运行。调度器会记录每个任务的 last_run_at;将其与文件的 mtime 进行比较。

#!/bin/bash
# ~/.kopi/scripts/feed-changed.sh
FEED="$HOME/data/feed.json"
STATE="$HOME/.kopi/scripts/.feed-changed.last"
test -f "$FEED" || { echo '{"wakeAgent": false}'; exit 0; }
mtime=$(stat -c %Y "$FEED")
last=$(cat "$STATE" 2>/dev/null || echo 0)
if [ "$mtime" -le "$last" ]; then
echo '{"wakeAgent": false}'
else
echo "$mtime" > "$STATE"
echo '{"wakeAgent": true}'
fi
cronjob(action="create", name="process-feed",
schedule="every 30m",
script="feed-changed.sh",
prompt="A new ~/data/feed.json has landed. Summarize what changed.")

外部标志门控 —— 仅当其他进程发出就绪信号时才运行(例如部署钩子落下一个文件、CI 任务在你的状态存储中设置某个值)。

#!/bin/bash
# ~/.kopi/scripts/flag-ready.sh
if test -f /tmp/new-data-ready; then
rm -f /tmp/new-data-ready
echo '{"wakeAgent": true}'
else
echo '{"wakeAgent": false}'
fi
cronjob(action="create", name="nightly-analysis",
schedule="0 9 * * *",
script="flag-ready.sh",
prompt="Run the nightly analysis over today's batch.")

SQL 计数门控 —— 仅当你自己的数据库中有待处理的新行时才运行。脚本还可以通过 context 将计数传递给 agent,这样 agent 无需重新查询就能知道要处理多少数据。

#!/usr/bin/env python
# ~/.kopi/scripts/new-rows.py
import json, sqlite3
conn = sqlite3.connect("/home/me/data/app.db")
n = conn.execute(
"SELECT COUNT(*) FROM messages WHERE ts > strftime('%s','now','-2 hours')"
).fetchone()[0]
if n < 1:
print(json.dumps({"wakeAgent": False}))
else:
print(json.dumps({"wakeAgent": True, "context": {"new_rows": n}}))
cronjob(action="create", name="summarize-new-msgs",
schedule="every 2h",
script="new-rows.py",
prompt="Summarize the new messages from the last 2 hours.")

同样的模式适用于任何可以从脚本查询的数据源 —— Postgres、HTTP API、你自己的状态存储 —— 而无需把 SQL 求值器内建到 cron 子系统中。

提示

Kopi Agent 自身的 ~/.kopi/state.db 是一个会在版本之间变化的内部 schema。不要从预运行门控中查询它 —— 请指向你自己的数据库或数据源。

致谢:这套实用方案源于 @iankar8 在 #2654 中的探索,该提议主张加入 sql/file/command 触发器作为一种并行机制。而 script + wakeAgent 门控已经以 0 美元的成本覆盖了这三种情况,因此这项工作最终以文档形式落地。

任务串联:context_from​

Cron 任务可以通过在 context_from 中列出其他任务的名称(或 ID)来消费一个或多个其他任务最近一次成功运行的输出:

cronjob(action="create", name="daily-digest",
schedule="every day 7am",
context_from=["ai-news-fetch", "github-prs-fetch"],
prompt="Write the daily digest using the outputs above.")

被引用任务最近一次完成的输出会被注入到本次运行的提示词之上,作为上下文。每个上游条目必须是有效的任务 ID 或名称(参见 cronjob action="list")。注意:串联读取的是最近一次已完成的输出 —— 它不会等待在同一个调度周期内仍在运行的上游任务。

任务存储​

任务存储在 ~/.kopi/cron/jobs.json 中。任务运行的输出保存到 ~/.kopi/cron/output/{job_id}/{timestamp}.md。

任务可以将 model 和 provider 以 null 的形式存储。当省略这些字段时,Kopi Agent 会在执行时从全局配置中解析它们。只有在设置了按任务覆盖时,它们才会出现在任务记录中。

存储使用原子文件写入,因此中断的写入不会留下写了一半的任务文件。

自包含提示词依然重要​

重要

Cron 任务在完全全新的 agent 会话中运行。提示词必须包含 agent 需要、而附加的 skill 尚未提供的所有内容。

错误做法: "Check on that server issue"

正确做法: "SSH into server 192.168.1.100 as user 'deploy', check if nginx is running with 'systemctl status nginx', and verify https://example.com returns HTTP 200."

安全​

定时任务的提示词会在创建和更新时扫描提示词注入与凭据外泄模式。包含不可见 Unicode 技巧、SSH 后门尝试或明显机密外泄载荷的提示词会被阻止。