# 自動化與排程

## Cron 工作

以精確的時間安排代理程式喚醒。Cron 工作在 Gateway 重新啟動後仍然保持，並支援靈活的排程模式。

### 排程類型

| 類型 | 說明 | 範例 |
|------|------|------|
| **Cron 表達式** | 標準 cron 語法，支援時區 | `0 7 * * *`（每天上午 7 點） |
| **間隔** | 固定間隔重複執行 | `30m`、`2h`、`1d` |
| **單次執行** | 在特定時間執行一次 | `2026-03-15T16:00:00Z` |

### 工作階段目標

- **主工作階段**, 在代理程式主要對話中作為系統事件排隊
- **隔離工作階段**, 在專屬工作階段中執行（`cron:<jobId>`），以避免污染主要對話

### 傳遞模式

| 模式 | 說明 |
|------|------|
| **None** | 靜默執行（不發佈輸出） |
| **Announce** | 將結果回傳至特定頻道 |
| **Webhook** | 將結果 HTTP POST 至外部 URL |

### 單次提醒

設定特定時間的提醒。代理程式喚醒後處理提醒，並可在執行後選擇性刪除工作。

### 重複執行工作

使用 cron 表達式和時區支援安排重複任務。工作追蹤其執行歷史（成功、失敗、時間）。

---

## Webhook

接收來自外部服務的事件並路由至代理程式。

### Gmail Pub/Sub

與 Gmail 的推送通知系統整合，在電子郵件到達時觸發代理程式操作：

1. 設定 GCP Pub/Sub 主題和訂閱
2. 設定 Gmail 標籤篩選
3. 將推送傳遞指向您的 webhook URL
4. Neotask 接收訊息並將代理程式事件排隊

### 自訂 Webhook

註冊 HTTP 端點，在被呼叫時觸發代理程式輪次。適用於與 CI/CD 管道、監控系統或任何可以發送 HTTP 請求的服務整合。

---

## 系統事件

系統事件是喚醒代理程式進行處理的信號：

- **立即**, 在下一個心跳時處理
- **下一個心跳**, 排隊等待下一次排程檢查

使用系統事件進行響應式工作流程, , 代理程式在事情發生時喚醒，而不是按固定排程執行。

---

## 心跳

心跳是一個定期信號（預設約 15 秒），讓代理程式有機會處理待處理的工作：

- 檢查新的系統事件
- 處理已排隊的訊息
- 執行待處理的自動化

心跳可以對每個代理程式啟用、停用或設定。

---

## 鉤子

事件驅動的自動化，可響應 Gateway 事件觸發 shell 命令或指令碼：

- **訊息時**, 收到訊息時執行
- **代理程式輪次時**, 在代理程式處理訊息之前或之後執行
- **頻道事件時**, 在特定頻道事件（加入、離開、回應）時執行

鉤子在 Gateway 主機上執行，並可存取事件上下文資料。

---

## 使用案例

| 情境 | 解決方案 |
|------|---------|
| 每日早晨簡報 | 上午 7 點 Cron 工作 → 代理程式摘要一夜的更新 |
| 每週報告生成 | 每週一 Cron 工作 → 代理程式生成並傳送電子郵件報告 |
| 電子郵件監控 | Gmail webhook → 代理程式處理傳入電子郵件 |
| 建置通知 | CI/CD webhook → 代理程式在 Discord 上公告建置結果 |
| 每小時資料檢查 | 間隔式 cron → 代理程式檢查儀表板並在異常時發出警報 |
| 排程社群貼文 | Cron 工作 → 代理程式在最佳時間起草並發佈內容 |