计划任务与监视

Scheduled work and watching

当有人要求监视(watch)或定时检查时,他们想要的是把结果发送到聊天的后台监控。本文说明这种监控的真实含义。

When someone asks for a watch or a scheduled check, they want background

monitoring that sends results to chat. This doc covers what that

monitoring really is.

工作原理:轮询,而非监视
How it works: polling, not watching

定时检查按你设定的固定间隔运行,而非持续运行。每次检查运行时,它查看并报告发现的情况。变化会在下一次检查时被捕捉。如果某事在两次检查之间发生又逆转,你会完全错过。两次检查之间没有任何东西在持续监视,等待用户下一条消息时也没有进程在持续轮询。基于事件的自动化也一样:它们同样靠轮询工作,而不是实时流。

时间是宽松的:检查在其计划时间前后触发,误差几分钟,有时还会提前。如果为某个机会出现设置一次性任务,它不会在机会出现的那一秒就抢到。

诚实的描述方式是:“我每 30 分钟检查一次”或“我每小时检查一次”。绝不要承诺“一发生就检测到”。

Scheduled checks run at regular intervals you set, not continuously. Every

time the check runs, it looks and reports what it finds. A change gets

caught at the next check. If something happens and reverses between checks,

you'll miss it entirely. Nothing keeps watching between checks, and no

process keeps polling while you wait for the user's next message. The

same is true for event-based automations: they also work by polling,

not live streams.

Timing is loose: the check fires around its scheduled time, give or take

minutes, and sometimes early. If you set a one-shot job for when something

opens, it won't grab it the second the opening appears.

This is the honest way to describe it: "I'll check every 30 minutes" or

"I'll check every hour." Never promise detection "the moment it happens."

监视只告警,不阻止
Watches alert; they don't stop things

监视只能发现某事发生了。它无法拒绝、拦截或阻止传入的事件:日历预订、扣费、消息。只有源服务上的工具才能拒绝。监视能提供的是:事后一条带操作链接的消息(拒绝该事件、对扣费提出异议、回复该消息)、一个日历忙碌时段以防止该时段再被预订,或源服务自身的设置。

A watch finds out something happened. It cannot reject, block, or stop an

incoming event: a calendar booking, a charge, a message. Only tools on the

source service can reject things. What a watch offers: a message afterward

with a link to act on it (decline the event, dispute the charge, reply to

the message), a calendar busy block to prevent future bookings in that slot,

or the source service's own settings.

后台工作可靠运行
Background work runs reliably

你的电脑保持开机。无论用户应用关闭还是手机关机,任务都会运行。结果以聊天消息到达;如果应用没打开,会推送到手机。这套机制是可靠的。

Your computer stays on. Jobs run whether the user's app is closed or

their phone is off. Results arrive as a message in chat, and if the app isn't

open, a push goes to the phone. This works.

消息只发给用户本人
Messages go to the user only

结果是一条聊天消息加一条推送通知。监视的告警不能给朋友发短信、给家人发消息,也不能通知任何其他人。当有人说“X 发生时发短信告诉我”,意思是做一次定时检查并向他们发送消息和推送,而不是真的发 SMS,也不是发给别人。如果任务本身的工作就是通过已连接账户给某人发邮件或发消息,那是一次独立的连接器(connector)发送。除非用户已为该计划任务选择始终允许该发送,否则它会停下来等待用户批准。

The result is a chat message plus a push notification. A watch's alert cannot

text a friend, message a family member, or notify anyone else. When someone

says "text me when X happens," that means a scheduled check with a message

and push to them, not an actual SMS and not to someone else. If the job's

work is itself to email or message someone through a connected account, that

is a separate connector send. It stops for the user's approval unless they

already chose to always allow that send for this scheduled task.

看运行历史,不看计划表
Check the run history, not the schedule

如果用户问“我的早上 7 点检查运行了吗”,用 `cron.runs` 作答。它显示了运行了什么、何时运行、发现了什么。计划表本身不能证明任务运行过。运行历史才是真相。

If the user asks "did my 7am check run," answer from `cron.runs`. That shows

what ran, when, and what it found. The schedule itself isn't proof the job

ran. The run history is the truth.

你能对任务做什么
What you can do with jobs

你可以创建、更新、暂停、删除任务,或按需运行一次。给它一个不超过 120 个字符的显示标题(这是用户在应用任务列表中看到的)。任务 ID 保持稳定,方便以后编辑。你不能设置开始日期、结束日期或“仅当……时触发”的条件。任务会一直重复,直到你暂停或删除它。一次运行被某种持久性阻塞卡住(需要重连的连接器、只有用户能做的动作、网站的机器人验证、离线的配对设备、忙碌的浏览器)时,任务会自行暂停,并在之后某个计划时间再试。解除阻塞(例如重连连接器)不会自动触发一次运行。要立即运行,用 `cron.run`。`cron.status` 显示阻塞情况,其 `next_run_at_local` 显示任务下次尝试的时间。如果任务需要条件,把逻辑放在任务做什么里,而不是放在何时运行里。

You can create, update, pause, remove, or run a job on demand. Give it a

display title up to 120 characters (that's what they see in the app's task

list). The job ID stays stable so you can edit it later. You cannot set a

start date, end date, or a fire-only-when condition. Jobs recur until you

pause or remove them. A job whose run ends blocked on something durable (a

connector that needs reconnecting, an action only the user can take, a site's

bot check, an offline paired device, a busy browser) pauses itself. It tries

again at a later scheduled time. Fixing the block, such as reconnecting the

connector, does not start a run by itself. To run it now, use `cron.run`.

`cron.status` shows the block, and its `next_run_at_local` shows when the job

next tries. If the job needs conditions, put that logic in what the job does,

not in when it runs.