> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 定时任务

通过 schedule actions 运行的工作区级周期任务。

## 初学者演练

先决条件：阅读下面的两个初学者指南，完成 Web 本地设置，并在编辑器的根目录中打开此 monorepo。网页设置属于`apps/web/.env.local`； Next.js不读取根`.env`。默认fake模式下的`/dashboard`是无数据库演示； `/auth` 需要迁移数据库。

简而言之：工作区是一个团队的单独用户、数据和设置。服务器是可信后端；让提供商密钥远离浏览器和电话代码。迁移是创建或更新表的版本化数据库更改。人工智能模型是回答的引擎；型号目录是服务器上可用型号 ID 和价格的列表。提供商是一种外部服务，例如人工智能、电子邮件或计费服务。权利是允许工作区使用某项功能的授权。 Webhook 是一个服务发送到另一个服务的 URL 的消息。

1. 打开 Settings → Developers 并使用 Schedules 控件创建具有 UTC 运行时的测试作业。

2. 保持应用程序运行，并使相同的仅服务器 `SCHEDULER_TICK_SECRET` 可用于应用程序和终端；从存储库根目录运行以下命令。

3. 确认到期时间提前并且作业达到其自身状态。如果没有运行，请检查 UTC 时间、调度程序提供程序和服务器日志；切勿将秘密粘贴到聊天中。

对于自定义代码，请从提供的 `prompts/README.md` 开始，然后复制最接近的提示：对于应用程序屏幕为 `prompts/new-app-screen.md`，对于公共页面为 `prompts/new-landing-page.md`。对于服务器、数据库或提供商工作，请为您的编码代理提供本指南的任务，并要求其读取 `AGENTS.md`、`.ai/PROJECT_CONTEXT.md` 和匹配的 `.ai/` 镜像；检查此处指定的确切源文件；列出文件并在编辑前进行检查；保留工作区所有权和仅限服务器的机密；并向您展示差异。告诉它您想要的行为、输入和输出字段、允许的角色、预期的成功和错误以及测试帐户、提供程序或设备。使用样本值；永远不要粘贴真正的秘密。

[开始之前](https://supastack.dev/zh/docs/web/before-you-start.md)

[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)

[网络本地设置](https://supastack.dev/zh/docs/web/ship-in-5-minutes.md)

[座席提示和项目内存](https://supastack.dev/zh/docs/web/agents.md)

```
corepack pnpm jobs:tick
```


## 将重复工作存储在数据库中

设置计划将作业类型和 cron 规则存储在工作区范围的 `job_schedule` 行中。 Cron 字段在 UTC 中评估。 `createDrizzleJobScheduler.claimDueSchedules` 使用 `FOR UPDATE SKIP LOCKED` 声明到期行，推进下一次运行，然后分派处理程序。

通用 `JobRunner` 承诺入队/状态/取消。循环属于调度程序行； Trigger.dev 工作流程语义保持明确。


## 驱动调度程序滴答声

设置仅服务器 `SCHEDULER_TICK_SECRET` 以启用 `POST /api/internal/scheduler-tick`。 `corepack pnpm jobs:tick` 称其为 dev/CI；缺少配置返回 404。在 `JOB_PROVIDER=trigger` 下，部署的 `scheduler.tick` cron 驱动调度程序。

```
# Against a running local app, with SCHEDULER_TICK_SECRET configured:
corepack pnpm jobs:tick
```


## 分别验证索赔和执行

测试重叠的刻度、到期/未到期规则、禁用的行、处理程序失败、取消和另一个工作区的时间表。分别检查索赔/预付款和工作完成情况；声明的行并不是已完成工作的证明。

[已发送的电子邮件.摘要示例](https://supastack.dev/zh/docs/web/project-structure.md)

[Trigger.dev执行](https://supastack.dev/zh/docs/modules/jobs.md)


## 安装与配置

周期性工作 —— 摘要、清理、续期 —— 走 schedule-actions 而不是临时计时器：listWorkspaceSchedules、upsertScheduleAction 与 removeScheduleAction 管理工作区的 cron 驱动任务。

一条 schedule 指明任务、cron 表达式与其运行所在的工作区。worker 在运行时解析上下文，因此暂停或删除的 schedule 无需重新部署就停止产出任务。

```
listWorkspaceSchedules()
upsertScheduleAction({ task, cron })
removeScheduleAction(formData)
```


## 实现流程

把每次定时运行当作不可信输入：在运行内重新解析工作区与 entitlement，因为状态可能自注册后已变化。任务要幂等 —— 重试或重复触发绝不能产生重复效果。

schedule 是运维界面：让它们在设置或日志中可见，让卡住或失控的 schedule 在用户察觉之前被发现。


## 验证与排障

在沙箱中手动触发 schedule，暂停它，验证被禁用的工作区停止产出运行，并确认重复触发只产生一次效果。cron 表达式放在受管配置里，而不是散落在任务代码中。


## 下一篇

[事务性邮件](https://supastack.dev/zh/docs/modules/email.md)