> ## 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-tw/docs/web/before-you-start.md)

[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)

[網路本地設定](https://supastack.dev/zh-tw/docs/web/ship-in-5-minutes.md)

[座席提示和專案記憶體](https://supastack.dev/zh-tw/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-tw/docs/web/project-structure.md)

[Trigger.dev執行](https://supastack.dev/zh-tw/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-tw/docs/modules/email.md)