> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 定时任务

> Cron 调度、任务链与无人值守自动化完整指南。

# 定时任务

用自然语言描述创建周期性任务。Myrm Cron 支持三种调度模式、任务链、态势报告与 10 层防噪 — 远超基础 Cron。

## 创建任务

### 对话（自然语言）

在任意对话中自然描述：

> 「每天早上 9 点抓取竞品价格并邮件发对比报告」

Agent 自动识别定时意图并弹出审批卡片——你确认后即刻创建。创建成功后聊天流内直接展示结构化任务卡片（名称、调度时间、下次运行、绑定模型），点击可跳转管理面板。Agent 还会自动匹配最合适的内置蓝图模板以提升任务质量。周期性计划需显式确认以防误创建。

### Cron 工具模式（智能体配置）

默认情况下，定时任务管理为**可发现加载**——不占用 Turn1 工具 schema（约 0 cron token）。在对话中描述调度时，Myrm 按需加载 `cron_manage_tool`。

| 配置                  | Turn1 工具              | 适用场景                              |
| ------------------- | --------------------- | --------------------------------- |
| **Cron 关闭**（默认）     | 识别意图后加载               | 日常对话——更省 token，对 Prompt Cache 更友好 |
| **Cron 开启**（内置工具面板） | Turn1 直接挂载（约 827 tok） | 高级用户——每轮可直接调用 cron，无需发现步骤         |

在 **智能体配置 → 内置工具 → 定时任务 (Cron)** 中开关。云沙箱未开通 cron 权益时，开关禁用并显示升级链接——GUI、REST API、Agent 路径规则一致。

可发现（默认）与 eager 两种模式均已通过自动化测试与真实模型 WebUI 端到端验证。

### GUI

进入 **设置 > 定时任务**，点 **创建** 使用可视化对话框（计划选择器、模型、投递选项）。可从 **14 种蓝图模板**（每日简报、每周回顾、知识库晨间摘要、稍后读内化等）一键创建——与 Agent 通过 API 使用的模板完全一致。`GET /cron/blueprints` API 返回 **en/zh/ja/de/ko** 五语系的 title、description、prompt\_template；目录仅从 API 加载（失败可重试），slot 标签使用前端 locale。

## 任务类型

| 类型               | 说明                                 | LLM 成本     |
| ---------------- | ---------------------------------- | ---------- |
| **Agent 任务**     | 完整 AI Agent 执行（提示词、模型、记忆）          | 按 Token 计费 |
| **Shell 命令**     | 直接执行 Shell（仅本地/桌面端，云端隐藏）           | 免费         |
| **纯脚本 (Python)** | 沙箱 Python 脚本，60s 超时（所有部署环境可用，包括云端） | 免费         |

### 纯脚本模式（零 LLM 成本）

创建任务时选择 **纯脚本 (Python)** 即可运行 Python 代码，无需 LLM 调用。脚本在隔离子进程中执行，超时 60 秒。

* **标准输出即结果** — 非空输出推送到配置的渠道，空输出静默跳过
* **跳过信号**：打印 `[SKIP]` 或 `{"action": "skip"}` 可优雅中止任务
* **云端安全**：与 Shell 不同，Python 脚本在所有部署模式下均可用（本地、桌面端、云托管）
* **适用场景**：API 健康检查、数据监控、RSS 过滤、数据库审计

## 三种调度模式

| 模式           | 语法           | 示例                    |
| ------------ | ------------ | --------------------- |
| **CRON**     | 标准 Cron 表达式  | `0 9 * * *`（每天 9:00）  |
| **INTERVAL** | 每 N 分钟（最少 5） | `every_minutes=30`    |
| **ONCE**     | ISO 8601 单次  | `2026-06-01T10:00:00` |

## 会话模式

控制 Agent 在多次执行间如何处理对话上下文：

| 模式               | 行为                          | 适用场景             |
| ---------------- | --------------------------- | ---------------- |
| **Isolated**（默认） | 每次全新上下文——不保留历史              | 独立一次性任务          |
| **Main**         | 延续 Agent 主聊天线程（加载最近 30 条消息） | 需要完整对话历史的任务      |
| **Daily**        | 自动注入当天历次执行输出到提示词；UTC 零点自动重置 | 定时监控、趋势检测、周期数据采集 |

### Daily 模式工作方式

选择 **Daily** 模式后：

1. Agent 按时间顺序看到同日历次输出（最多 5 条，每条截断至 500 字符）
2. 新的一天首次执行时，会包含昨日最后一次输出的摘要
3. 这让 Agent 能识别趋势变化——例如"CPU 过去 3 小时从 45% → 72% → 90%"

Daily 模式零额外存储（复用已有执行记录），不影响 Prompt Cache 效率。

## 任务链（context\_from）

将任务串联，前一任务输出喂给下一任务：

> 「任务 A 收集日销售数据，任务 B 分析并生成报告」

设置 `context_from` 将引用任务最近成功输出注入下一任务提示词。

## 心跳监控

内置周期性自检（`__heartbeat__`）+ **态势报告**注入 — 每次 tick 前 Agent 回顾记忆变更、待办提醒、到期的跟进承诺（智能跟进追踪）与系统健康，将盲目检查变为智能驱动动作。到期的承诺投递后自动标记为已发送，避免重复通知。

### 智能体绑定

在 **设置 → 系统 → 心跳巡检** 中将任意智能体绑定到心跳。心跳将继承所绑定智能体的模型、系统提示词、技能和工具配置，无需单独配置。

* **一键绑定**：从内置或自定义智能体中选择。
* **模型继承**：UI 显示将使用的模型（如「使用模型：openai/gpt-4o-mini」）。
* **解绑**：切换回「默认智能体」清除绑定 — 心跳恢复使用全局默认模型。
* **Agent Profile SSOT**：更新智能体模型一次，所有绑定的心跳在下次执行时自动使用新模型。

## 调度器存活面板

定时任务面板顶部实时展示调度器健康状态：

| 状态     | 含义                                 | 视觉效果    |
| ------ | ---------------------------------- | ------- |
| **绿色** | 健康 — 调度器正常运行和 tick                 | 呼吸动画圆点  |
| **黄色** | 降级 — 启动中、tick 超时(>120秒)、或有 tick 错误 | 静态琥珀色圆点 |
| **红色** | 停止 — 调度器未运行或缺少定时器                  | 静态红色圆点  |

组件每 30 秒轮询 `GET /api/v1/cron/scheduler/health`。当浏览器标签页隐藏时自动暂停请求，切回时立即刷新 — 多标签页工作场景下零浪费。

悬浮可查看精确的最后 tick 时间和错误计数。

## 智能投递

| 特性                     | 说明                                                                                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **多渠道**                | 经聊天、Webhook、飞书、Slack 等 35+ 渠道投递                                                                                                     |
| **飞书/ Lark 群机器人 Hook** | 自定义机器人 Webhook（`open.feishu.cn` / `open.larksuite.com`）自动发送 **`msg_type=text`** 格式，开箱即用，无需 OAuth chat\_id                           |
| **企业微信群机器人 Hook**      | 粘贴 `qyapi.weixin.qq.com/cgi-bin/webhook/send?key=...` URL 即自动识别，发送 **`msgtype=markdown`** 富文本（粗体标题+状态 emoji）；指数退避重试；校验 `errcode` 响应 |
| **内联 IM 直投**           | 脚本任务创建时直接选择投递渠道（Telegram/Slack/飞书/Discord），无需额外步骤                                                                                   |
| **\[SILENT] 跳过**       | 无可执行内容时 Agent 回复 `[SILENT]` 跳过通知                                                                                                    |
| **失败告警**               | 独立 `failure_webhook_url` 运维告警                                                                                                       |

### 脚本投递（内联渠道选择）

创建 **脚本 (Python)** 任务时，对话框展示内联投递目标选择器：

1. **聊天**（默认）— 输出保留在任务历史中
2. **已连接 IM 渠道** — 自动从已配置的集成中发现（仅显示已连接的渠道）
3. **目标字段** — 根据选择的渠道指定 Chat ID、频道名或 Webhook URL

无需跳转到单独的投递配置页面。脚本任务会自动隐藏模型选择器（无 LLM 参与）。

## 交付保障（可选事后复核）

针对 **Agent 定时任务**（非纯脚本任务），可按智能体开启可选的交付复核：

1. 打开 **设置 → 智能体 → \[你的智能体] → 能力**
2. 在 **交付保障** 下开启 **定时任务交付复核**
3. 保存 — 默认关闭，按智能体持久化

**开启后的行为：**

| 步骤                          | 用户可见效果                                  |
| --------------------------- | --------------------------------------- |
| 定时任务成功完成                    | 运行记录仍显示成功（不变）                           |
| 任务使用了有副作用的工具（写文件、bash、浏览器等） | 内置 reviewer 子智能体事后复核（≤120 秒，且不超过任务剩余超时） |
| 复核通过                        | 运行历史显示 **交付复核：通过** 徽章                   |
| 复核未通过                       | 运行 **仍显示成功**，但历史追加琥珀色警告 — **不会自动重跑**    |

**适用场景：** 无人值守夜间任务「说完成了但交付错了」— 早上看 Cron 历史即可发现，无需翻完整日志。竞品多为交互式 turn-end guard 或 Goal rubric，缺少 **Cron 运行史结构化复核 + WebUI 徽章**。

**成本控制：** 默认关闭；只读任务自动跳过；不影响交互式聊天（无额外 Turn1 工具）。

## 验收标准（结构化输出验证）

为每个定时任务定义可量化的质量检查条件，每次运行后自动验证输出质量。与交付保障（LLM 复核）不同，验收标准是**确定性**的 —— shell 命令或语义检查直接判定成功/失败。

### 添加验收标准

创建或编辑任务时，在 GUI 中展开 **验收标准** 区域（仅 agent 类型任务）：

1. 点击 **添加条件**
2. 选择类型：
   * **Shell** — 必须成功执行（退出码 0）或匹配期望输出的 shell 命令
   * **Semantic** — LLM 裁判评估输出是否满足自然语言描述的条件
3. 填写描述（如 "输出 JSON 至少包含 3 个条目" 或 "报告必须提到所有 5 个竞品"）

### 工作原理

| 路径                   | 触发条件                                   | 机制                                                       |
| -------------------- | -------------------------------------- | -------------------------------------------------------- |
| **Goal 队列**（存在活跃目标时） | `create_goal(acceptance_criteria=...)` | Harness `VerificationGatekeeper` 在目标完成后运行                |
| **直接执行**（无活跃目标时）     | `_run_once` 后                          | `acceptance_verification.py` 桥接 `VerificationGatekeeper` |

两条路径使用同一个 Harness 框架的 `VerificationGatekeeper` —— 无论执行模式如何，验收标准的评估方式完全一致。

### 失败行为

* 任何一条标准失败 → 运行状态标记为 **FAIL**
* 触发失败投递（已配置的告警渠道）
* 不会自动重试（与普通失败处理一致）

### 示例

每日竞品价格爬虫配合验收标准：

| 类型       | 描述                                                  |
| -------- | --------------------------------------------------- |
| Shell    | `jq '.items \| length' /tmp/prices.json` 输出必须 `>=3` |
| Semantic | "报告包含所有被监控竞品的定价数据"                                  |

如果爬虫因网站变更仅获取了 3 家竞品中的 2 家数据，shell 检查立即失败 —— 你会即时收到告警，而非数天后才发现数据缺失。

### API 支持

`POST /cron/jobs` 和 `PATCH /cron/jobs/:id` 接口支持 `acceptance_criteria` 数组：

```json theme={null}
{
  "acceptance_criteria": [
    { "type": "shell", "description": "jq '.count' output.json >= 5" },
    { "type": "semantic", "description": "摘要涵盖所有关键指标" }
  ]
}
```

## 10 层防噪

| 层  | 机制                     | 效果                       |
| -- | ---------------------- | ------------------------ |
| 1  | Active Hours           | 仅在配置时间窗运行                |
| 2  | \[SILENT] 指令           | AI 自判无价值内容跳过推送           |
| 3  | Output Hash 去重         | 相同结果不重复推                 |
| 4  | Cooldown               | 推送间强制最小间隔                |
| 5  | Max Fires              | N 次执行后自动停止，推送通知告知用户      |
| 6  | Skip If Active         | 上次仍在跑则不启新实例              |
| 7  | Expires At             | 到期 datetime 自动停，推送通知告知用户 |
| 8  | PreFlight Condition    | 沙箱探测脚本通过才执行              |
| 9  | No-content Skip        | 各节为空时心跳跳过 LLM            |
| 10 | Failure Alert Cooldown | 失败告警也有冷却                 |

## 增量监控

启用智能增量检测，仅在有真正新内容时通知：

| 设置                        | 用途              |
| ------------------------- | --------------- |
| `monitor_config.enabled`  | 启用增量监控          |
| `monitor_config.ttl_days` | 基线超过此 TTL 后自动重置 |

启用后，系统计算当前输出与存储基线之间的差异。若无新内容则静默跳过投递（exit\_code=0）。仅真正的新信息触发通知（exit\_code=1），且只投递增量部分。

基线在 TTL 过期后自动重置，防止长期运行的监控累积陈旧状态。

## 完整性验证（Merkle 链）

每次执行通过 SHA-256 链接到前一次，形成防篡改审计链：

* 通过 `POST /api/v1/cron/{job_id}/verify-integrity` 验证链完整性
* 检测缺口（丢失执行）、篡改（修改输出）或重排序
* 企业合规：定时任务按预期运行的加密证明

## 事件驱动触发

除定时调度外，任务可被外部事件触发：

| 触发类型               | 工作方式                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| **事件正则**           | 入站 IM 渠道消息匹配 regex 模式时触发任务 — GUI 配置，无需 Webhook 公网 URL                                                  |
| **系统事件**           | 结构化事件（source + event\_type + filters）自动触发                                                              |
| **Webhook**        | 外部服务发送 HTTP POST，HMAC-SHA256 签名验证                                                                      |
| **实时流监听 (WS/SSE)** | 出站 WebSocket 或 Server-Sent Events 连接 — 实时监听外部服务事件。无需公网 URL，在 NAT/防火墙后也能工作。支持 JSONPath + 正则过滤，自动重连指数退避。 |
| **URL 轮询**         | 定期 HTTP GET + 内容哈希变更检测 — 仅在响应内容变化时触发。支持 JSONPath 字段提取，精准监控目标数据。                                        |

触发上下文（匹配的消息、事件载荷、Webhook body、流数据或轮询内容）会注入 Agent 提示词，让它知道*为什么*被触发。

### IM 消息 → 事件触发（架构）

已连接渠道（飞书、Telegram、Slack 等）的入站消息可自动触发事件型 Cron 任务：

1. **连接渠道** — Settings 中长连接或 Webhook Ingress
2. **创建任务** — 触发类型选 **Event**，设置渠道过滤与正则模式
3. **消息流经 Router** — `/stop`、`/new`、表情反应、待审批消息自动跳过；匹配消息仅 dispatch 一次

:::tip 云端与本地一致
云托管场景下，Control Plane Ingress 仅入队消息；事件 dispatch 在沙箱 Router 内执行 — 避免双层 dispatch 导致重复触发。
:::

**已测场景：** 正常 dispatch、命令跳过、审批跳过、反应跳过、重复消息去重 — 16 项自动化测试覆盖全链路。

### 远程节点事件（移动端 / IoT 自动化）

外部系统可通过 HTTP 上报结构化事件到你的 Agent — 无需保持长连接，无需 SDK：

```bash theme={null}
curl -X POST https://your-myrm.example/api/v1/remote-access/node/events \
  -H "Authorization: Bearer <pair_token>" \
  -H "Content-Type: application/json" \
  -d '{"source": "ios_shortcuts", "event_type": "location_arrived", "payload": {"location": "home"}}'
```

| 字段           | 说明                                                          |
| ------------ | ----------------------------------------------------------- |
| `source`     | 上报系统标识（如 `ios_shortcuts`、`android_tasker`、`home_assistant`） |
| `event_type` | 事件名称（如 `location_arrived`、`wifi_connected`、`battery_low`）   |
| `payload`    | 任意 JSON 上下文，传递给被触发的 Agent 任务                                |

**认证方式：** 需要有效的 `pair_token`（hub\_list 范围，通过扫码配对签发），或活跃的 WebUI 会话。

**配置步骤：**

1. 在设置 → 远程访问 → 二维码中配对移动设备
2. 创建定时任务，触发类型选 **系统事件** — 设置 source 和 event\_type 过滤条件
3. 在 iOS Shortcuts / Android Tasker / Home Assistant 中配置 POST 请求到该端点

事件会自动与你配置的 SystemEventTrigger 规则匹配，触发绑定的 Agent 任务并将 payload 作为上下文注入。限流 60 次/分钟。

:::tip 零电量消耗
竞品要求维持 WebSocket 长连接（耗电且需要后台保活 hack），我们基于 HTTP 的方案仅在事件发生时触发 — 零空闲功耗。
:::

## 崩溃恢复

Myrm 调度器在意外重启后三阶段自动恢复：

1. **僵尸任务恢复** — 检测标记为"运行中"但从未完成的任务（进程崩溃），重新调度
2. **漏执行回放** — 识别宕机期间遗漏的 Cron 槽位并回放执行
3. **宽限窗口** — 在 misfire 宽限窗口内的任务立即执行；过期则跳到下一周期

## 安全

* **Fail-closed 默认安全**：未声明 `required_capabilities` 的任务，shell/代码执行/MCP 调用等危险操作一律拒绝并提供清晰引导
* **Per-job 能力围栏**：每个任务独立声明所需权限（`shell_exec`、`file_write`、`mcp_invoke` 等），已声明能力自动预批准，未声明一律拒绝
* **BLOCK 级绝对拦截**：`rm -rf /`、`sudo`、`DROP DATABASE` 等破坏性命令即使在已批准能力范围内也始终拒绝
* 每次执行前**提示词注入扫描**（12 种模式）
* **ContextVar 自调度防护**防无限任务链（Cron 不能创建新 Cron）
* **预算强制**超日预算则阻断执行
* **ReDoS 防护**事件触发正则模式安全检查
* **SSRF 防护** Webhook 投递 URL 安全检查

## 桌面电源管理

Tauri 桌面端定时任务自动获取 **PowerLock** 防系统休眠：

* **macOS**：`caffeinate` 子进程
* **Linux**：`systemd-inhibit`
* **Windows**：`SetThreadExecutionState`

RAII 守护，任务结束（含失败）自动释放。

## 蓝图模板（一键创建）

通过预置模板 3 次点击即可创建常用自动化任务。进入 **定时任务 > 新建 > 从模板** 浏览可用蓝图。

| 蓝图          | 分类 | 配置项                     | 说明                                  |
| ----------- | -- | ----------------------- | ----------------------------------- |
| 每日早报        | 效率 | 时间, 重复                  | 每天获取新闻、天气和提醒                        |
| 每周回顾        | 效率 | 时间, 星期几                 | 总结周进展并规划下周                          |
| 自定义提醒       | 个人 | 时间, 消息                  | 自定义内容的定期提醒                          |
| 新闻摘要        | 信息 | 时间, 重复, 话题              | 关注话题的精选新闻                           |
| 晚间放松        | 个人 | 时间, 重复                  | 一天的平静总结                             |
| 本地健康巡检      | 运维 | 时间, 重复                  | 监控 CPU/内存/磁盘                        |
| 竞品动态监控      | 商业 | 时间, 星期几, 竞品             | 追踪竞品新闻和更新                           |
| 习惯打卡        | 个人 | 时间, 习惯                  | 每日习惯追踪                              |
| 每日学习        | 教育 | 时间, 重复, 主题              | 每天学一个知识点                            |
| **社媒舆情监控**  | 商业 | 时间, 重复, 品牌, 平台, 关键词（选填） | 监控品牌提及和舆情                           |
| **稍后读知识内化** | 效率 | 时间, 重复                  | 自动将收藏文章内化到知识库                       |
| **知识库晨间摘要** | 效率 | 时间, 重复                  | 每日 vault 变更三行摘要；无变化时 `[SILENT]` 不打扰 |

**第二大脑快速开始（设置 → Wiki）：** 一键应用预设智能体并创建 **两条** 定时任务（06:00 稍后读 + 07:00 晨间摘要），无需手工选蓝图。若早期只应用过单 cron 版本，点「重新应用预设」即可幂等补齐。

使用浏览器自动化的品牌监控 —— 适用于没有公开 API 的平台（小红书、微博、Twitter/X、LinkedIn、抖音）。

**设置：** 选择社媒舆情监控模板 → 填入品牌名和目标平台 → 关键词为选填（仅按品牌名监控即可）→ 选择投递渠道 → 完成。

**每次执行流程：**

1. 通过浏览器自动化导航目标平台
2. 使用配置的关键词搜索品牌提及
3. 分类情感倾向（正面/中性/负面）
4. 生成结构化情报报告
5. 标记强负面帖子以便立即关注
6. 通过配置的 IM 渠道投递（无重要信息时静默跳过）

**核心优势：** 与 API 依赖工具不同，浏览器自动化适用于任何有登录会话的平台 —— 无需 API 密钥，无速率限制，平台更新 API 也不受影响。

## 示例

| 描述        | 计划                    | 用到的特性                   |
| --------- | --------------------- | ----------------------- |
| 日报        | `0 9 * * *`           | Cron + 渠道投递             |
| 周备份       | `0 2 * * 1`           | Cron + Shell            |
| 小时监控      | `0 * * * *`           | Interval + \[SILENT]    |
| 单次提醒      | `2026-06-01T10:00:00` | Once + 聊天               |
| 数据流水线     | `0 8 * * *`           | Cron + context\_from 链  |
| 心跳自检      | 可配置                   | Heartbeat + 态势报告        |
| API 可用性监控 | `*/5 * * * *`         | 纯脚本模式 + \[SKIP] 健康跳过    |
| 数据库审计     | `0 6 * * *`           | 纯脚本模式 + 多行输出            |
| 社媒舆情监控    | `0 9 * * 1-5`         | 蓝图 + 浏览器自动化 + \[SILENT] |

## 相关功能

* **[成长仪表板](/zh/core-concepts/memory-system#growth-dashboard)** — AI 每日总结（DailyWrap）自动生成当日关键词和行动建议。成长仪表板可视化活跃度热图、记忆健康雷达、技能进化事件和成本节省。
* **[统计 API](/zh/api-reference/statistics)** — 编程访问每日总结数据、成长指标和用量分析。