# 自动化与调度

## 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 表达式和时区支持安排重复任务。任务会跟踪其执行历史（成功、失败、时间）。

---

## Webhooks

从外部服务接收事件并将其路由到代理。

### Gmail Pub/Sub

与 Gmail 的推送通知系统集成，在收到邮件时触发代理操作：

1. 设置 GCP Pub/Sub 主题和订阅
2. 配置 Gmail 标签过滤
3. 将推送交付指向您的 webhook URL
4. Neotask 接收消息并将代理事件入队

### 自定义 Webhooks

注册 HTTP 端点，在被调用时触发代理轮次。适用于与 CI/CD 流水线、监控系统或任何能发送 HTTP 请求的服务集成。

---

## 系统事件

系统事件是唤醒代理进行处理的信号：

- **立即** -- 在下一个心跳时处理
- **下一个心跳** -- 排队等待下一次计划签到

使用系统事件进行响应式工作流 -- 代理在事件发生时醒来，而不是按固定计划。

---

## 心跳

心跳是一个周期性信号（默认约 15 秒），给代理处理待办工作的机会：

- 检查新的系统事件
- 处理排队的消息
- 运行待处理的自动化

心跳可以按代理启用、禁用或配置。

---

## Hooks

事件驱动的自动化，响应 Gateway 事件触发 shell 命令或脚本：

- **消息接收时** -- 在收到消息时执行
- **代理轮次时** -- 在代理处理消息之前或之后执行
- **频道事件时** -- 在频道特定事件（加入、离开、反应）时执行

Hooks 在 Gateway 主机上运行，可以访问事件上下文数据。

---

## 使用场景

| 场景 | 解决方案 |
|----------|----------|
| 每日早间简报 | 早上 7 点的 Cron 任务 -> 代理总结隔夜更新 |
| 每周报告生成 | 每周一的 Cron 任务 -> 代理生成并发送报告 |
| 邮件监控 | Gmail webhook -> 代理处理收到的邮件 |
| 构建通知 | CI/CD webhook -> 代理在 Discord 上发布构建结果 |
| 每小时数据检查 | 基于间隔的 cron -> 代理检查仪表盘并在异常时发出警报 |
| 定时社交发布 | Cron 任务 -> 代理在最佳时间起草并发布内容 |