# 自动化任务

自动化任务功能让您可以设置按计划自动执行的任务。本文档介绍自动化任务的配置和使用方法。

## 功能概述

自动化任务可以：

* 按固定时间间隔执行

* 在指定时间点执行

* 使用 Cron 表达式配置

* 自动触发 AI Agent 执行

* 响应系统事件自动触发（事件回调）

![自动化任务列表](/images/docs/task-management/schedule-tasks.png)

### Cron 表达式限制

空间周期任务仅支持五位 Cron 表达式：`分 时 日 月 周`，最小调度粒度为分钟。例如，`*/5 * * * *` 表示每五分钟触发，`30 8 * * 1` 表示每周一 08:30 触发。

<br />

## 使用场景

### 定期报告

每天/每周自动生成报告：

```
每周一 9:00 生成项目进度报告
```

### 数据同步

定时同步数据：

```
每小时同步一次数据统计
```

### 提醒通知

定期提醒：

```
每天 17:00 提醒整理当日工作
```

### 自动维护

定期执行维护任务：

```
每周日凌晨清理临时文件
```

### 事件驱动自动化

当系统内发生特定事件时，自动触发 Agent 处理：

```
当新任务创建时，自动分析任务优先级并添加标签
当对话出错时，自动通知管理员并记录错误日志
当成员加入工作空间时，自动发送欢迎消息
```

> 详细说明请参考 [事件回调 Hook](/docs/task-management/event-callback-hook)

### Webhook 回调自动化

允许外部系统（如性能压测系统、监控告警系统）通过 HTTP 请求触发 AI 对话：

```
外部监控系统检测到异常 → POST /api/v1/webhook/{taskId} → AI 自动分析并处理
```

**配置方式**：

1. 创建自动化任务时，选择类型为 **Webhook**。
2. 配置 Prompt 模板，可使用 Webhook 变量（`{{query}}`、`{{body}}`、`{{headers}}`、`{{method}}`、`{{sourceIp}}`、`{{timestamp}}`）来引用外部系统传入的数据。
3. （可选）配置 IP 白名单，限制只有指定来源 IP 才能触发。

**使用方式**：

外部系统向 Webhook URL 发送 HTTP 请求即触发 AI 对话：

```bash
# POST 方式
curl -X POST "https://your-host/api/v1/webhook/TASK_ID?_jvs_token=YOUR_PAT" \
  -H "Content-Type: application/json" \
  -d '{"status": "failed", "message": "Service timeout"}'

# GET 方式（使用 query 参数传递数据）
curl "https://your-host/api/v1/webhook/TASK_ID?_jvs_token=YOUR_PAT&status=failed"
```

系统收到请求后会立即返回 `202 Accepted`，AI 对话在后台异步执行。

**认证方式**：支持通过 URL 查询参数 `_jvs_token` 或 `Authorization: Bearer` 请求头传递 PAT（个人访问令牌）进行认证。

![webhook任务](/images/docs/task-management/task-webhook.jpg)

### 指定执行人

自动化任务默认以**触发事件的用户身份**或**任务创建者身份**执行。但在某些场景下，您可能需要指定一个固定的执行人，确保任务始终以特定用户的身份运行。

#### 为什么需要指定执行人？

| 场景         | 说明                                                           |
| ---------- | ------------------------------------------------------------ |
| **权限隔离**   | 某些操作需要管理员权限，而事件触发人可能是普通成员（如 Viewer），指定管理员为执行人可确保任务不会因权限不足而失败 |
| **上下文一致性** | 任务访问的知识库、文件或资源与特定用户相关（如个人笔记目录），需要以该用户身份执行才能正确访问              |
| **责任追溯**   | 自动化任务产生的操作记录（如自动评论、状态变更）需要归属到明确的责任人，而非不固定的触发人                |
| **代理执行**   | 团队负责人需要以自己身份自动处理下属触发的事件（如自动审核、自动分配），而当下属可能没有相应权限             |

#### 执行人优先级规则

系统按以下优先级确定任务的实际执行人：

| 优先级   | 身份来源  | 说明                |
| ----- | ----- | ----------------- |
| 1（最高） | 指定执行人 | 任务配置中明确指定的执行人     |
| 2     | 事件触发人 | 事件回调场景下，触发该事件的用户  |
| 3     | 手动触发人 | 点击"立即执行"按钮的当前登录用户 |
| 4（最低） | 任务创建者 | 以上都为空时，回退到任务创建者   |

> **提示**：如果指定执行人不存在或已离职，系统会自动回退到下一优先级的执行人，不会导致任务失败。

#### 配置方法

在创建或编辑自动化任务时，展开"高级配置"，在"指定执行人"下拉框中选择目标成员。选择"自动（默认）"则不指定固定执行人，按上述优先级规则自动决定。

### 指定执行环境

如果任务需要在某台本地执行机的固定目录中运行（例如读取本机代码仓库、调用本机工具），可以为"Agent 委派"类任务指定执行环境，无需再在 Prompt 中写明机器和目录。

- **配置方法**：创建或编辑任务时，在"执行环境（可选）"中选择当前空间已绑定的执行机和目录，选项显示为"机器名 · 目录摘要"。选择"默认环境"则保持原有的执行方式。
- **可选范围**：只列出当前空间已启用、目录校验通过、初始化已完成、执行机在线，并且**你有使用权**的执行环境（与对话中切换执行环境看到的列表一致）；执行环境由空间管理员在执行机绑定中维护，可用范围见[执行机](../workspace/workspace-execution-machines.md)。
- **权限要求**：只有对该执行环境有使用权的空间管理员或编辑者（环境为"全部成员可用"、本人是负责人或在授权名单中）才能指定它。修改已指定该环境的任务时，编辑者也需要有使用权；空间管理员可以直接修改（例如调整提示词、触发时间或更换执行人），但改选其他环境或把执行人设为自己时，仍需要对应环境的使用权。执行人同样需要有该环境的使用权；未指定执行人时，定时触发以任务创建者身份执行，因此创建者也需要有使用权。事件回调任务指定执行环境时必须同时指定执行人。
- **权限变化后**：如果之后负责人被转让、授权被撤销或可用范围被收紧，导致执行人不再有使用权，触发时本次执行会直接失败并写明原因，不会自动重试；请联系空间管理员重新授权，或由有权限的成员、空间管理员编辑任务，改选其他环境或更换执行人。
- **初始化中的环境**：通过"从空间拷贝"等方式初始化的执行环境，在初始化完成前不能被任务选中；如果触发时环境仍在初始化或初始化失败，本次执行会失败并写明原因。
- **执行机离线**：保存任务时不要求执行机在线；但触发时如果执行机离线，本次执行直接失败并在执行历史中写明原因，不会改用默认环境，也不会自动重试，等下一次触发再执行。
- **执行环境被解绑**：执行环境被解绑或执行机被删除后，引用它的任务会自动禁用，任务列表和详情中会显示"执行环境已解绑"。此时需要编辑任务重新选择执行环境（或改回默认环境），然后再启用；解绑状态下也不能手动运行。

> **提示**：之前在 Prompt 中写明"在某台机器、某个目录执行"的任务，建议改为选择执行环境，并删掉 Prompt 中的位置说明。Prompt 中的文字不会真正改变任务的执行位置。

## 任务类型

系统支持三种任务类型：

| 类型         | 说明               | 触发方式       |
| ---------- | ---------------- | ---------- |
| 一次性任务      | 在指定时间点执行一次       | 到达执行时间自动触发 |
| 周期性任务      | 按 Cron 表达式周期执行   | 按周期自动触发    |
| 事件回调       | 监听系统事件，事件发生时触发   | 事件驱动自动触发   |
| Webhook 回调 | 外部系统通过 HTTP 请求触发 | 外部系统主动调用   |

> 事件回调类型的详细配置和使用请参考 [事件回调 Hook](/docs/task-management/event-callback-hook)

## 创建自动化任务

### 步骤 1：进入任务管理

1. 进入工作空间
2. 点击侧边栏"任务"
3. 切换到"自动化任务"标签

### 步骤 2：新建自动化任务

点击"新建自动化任务"按钮。

### 步骤 3：配置任务

填写任务配置：

| 字段   | 说明      | 示例          |
| ---- | ------- | ----------- |
| 任务名称 | 任务的显示名称 | 每周项目报告      |
| 任务描述 | 任务的详细说明 | 生成本周的项目进度报告 |
| 执行计划 | 执行时间配置  | 每周一 9:00    |
| 任务内容 | 要执行的指令  | 请生成本周项目进度报告 |

### 步骤 4：保存并启用

1. 检查配置
2. 点击保存
3. 确保任务状态为"启用"

## 执行计划配置

### 简单模式

使用预设的时间选项：

| 选项  | 说明          |
| --- | ----------- |
| 每小时 | 每小时执行一次     |
| 每天  | 每天指定时间执行    |
| 每周  | 每周指定日期和时间执行 |
| 每月  | 每月指定日期和时间执行 |

### 高级模式（Cron 表达式）

使用 Cron 表达式进行精细配置：

```
分钟 小时 日 月 周几
```

#### Cron 示例

| 表达式            | 说明              |
| -------------- | --------------- |
| `0 9 * * 1`    | 每周一 9:00        |
| `0 0 1 * *`    | 每月 1 号 0:00     |
| `*/30 * * * *` | 每 30 分钟         |
| `0 9,18 * * *` | 每天 9:00 和 18:00 |
| `0 9 * * 1-5`  | 工作日每天 9:00      |

#### Cron 字段说明

| 字段 | 允许值        | 特殊字符     |
| -- | ---------- | -------- |
| 分钟 | 0-59       | \* , - / |
| 小时 | 0-23       | \* , - / |
| 日  | 1-31       | \* , - / |
| 月  | 1-12       | \* , - / |
| 周几 | 0-6 (0=周日) | \* , - / |

## 任务内容

### 文本指令

直接输入要执行的指令：

```
请生成本周的项目进度报告，包含：
1. 完成的工作
2. 进行中的任务
3. 下周计划
```

### 使用模板

可以使用变量模板：

```
请生成 {{date}} 的数据统计报告
```

支持的变量：

| 变量              | 说明     |
| --------------- | ------ |
| `{{date}}`      | 当前日期   |
| `{{time}}`      | 当前时间   |
| `{{workspace}}` | 工作空间名称 |

## 管理自动化任务

### 查看任务列表

在"自动化任务"标签查看所有自动化任务：

| 字段   | 说明        |
| ---- | --------- |
| 名称   | 任务名称      |
| 执行计划 | Cron 表达式  |
| 下次执行 | 下次执行时间    |
| 状态   | 启用/禁用     |
| 上次执行 | 上次执行时间和结果 |

### 启用/禁用任务

点击状态开关启用或禁用任务。

禁用的任务：

* 不会按计划执行

* 配置保留

* 可以随时重新启用

### 编辑任务

1. 找到目标任务
2. 点击编辑按钮
3. 修改配置
4. 保存

### 删除任务

1. 找到目标任务
2. 点击删除按钮
3. 确认删除

### 手动执行

可以手动触发任务执行：

1. 找到目标任务
2. 点击"立即执行"按钮
3. 任务开始执行

任务处于禁用状态时仍可手动执行一次。禁用状态只停止自动调度；手动执行会正常生成执行历史，且执行完成后任务继续保持禁用，不会恢复后续自动调度。

## 执行历史

### 查看历史

点击任务名称查看执行历史：

| 字段   | 说明         |
| ---- | ---------- |
| 执行时间 | 任务开始执行的时间  |
| 执行状态 | 成功/失败      |
| 执行结果 | 执行的输出或错误信息 |
| 耗时   | 执行所用时间     |

### 异常执行收敛

当执行记录长期停留在"等待执行"或"执行中"，且已超过任务配置的执行超时时间和系统缓冲时间后，执行历史会标记为"疑似异常"。管理员可在执行历史中将该记录人工标记为"成功"或"失败"，并填写处理原因；原因会写入该执行记录的错误信息，便于后续追溯。

如果后端服务在自动化任务执行过程中重启，系统会在服务启动恢复阶段自动检查已超时的运行中记录，并将其收敛为失败，避免执行历史长期停留在运行中。

### 历史保留

执行历史默认保留 30 天。

## 最佳实践

### 1. 合理安排执行时间

* 避免高峰时段

* 考虑时区差异

* 错开多个任务的执行时间

### 2. 控制执行频率

```
✅ 合理：每天 1 次、每周 1 次
❌ 过于频繁：每分钟执行
```

### 3. 清晰的任务内容

```
✅ 好：
请生成本周（{{date}}）的销售报告，包含：
- 总销售额
- 同比增长
- TOP 10 产品

❌ 不好：
生成报告
```

### 4. 监控执行结果

* 定期检查执行历史

* 关注失败的任务

* 及时调整配置

## 限制说明

### 执行频率限制

* 最小间隔：5 分钟

* 每天最多执行：288 次（每 5 分钟一次）

### 执行超时

* 单次执行最大时长：默认 30 分钟，最大可配置为 2 小时（7200 秒）

* 超时任务会被标记为失败

## 常见问题

**Q：自动化任务没有执行怎么办？**

A：检查以下几点：

* 任务是否已启用

* Cron 表达式是否正确

* 是否超过配额限制

**Q：可以设置一次性任务吗？**

A：可以。创建任务时选择"一次性任务"类型，设置执行时间即可。

**Q：可以根据事件自动触发任务吗？**

A：可以。创建任务时选择"事件回调"类型，配置监听事件和触发条件即可。详见 [事件回调 Hook](./event-callback-hook.md)。

**Q：任务执行失败会重试吗？**

A：会。可以在高级配置中设置最大重试次数和重试间隔。

**Q：如何临时暂停任务？**

A：使用禁用功能临时暂停任务，需要时再启用。

**Q：事件回调任务监听了多个事件，一次操作只触发多次自动化任务吗？**

A：不会，只会触发一次。因为有系统有内置的操作级去重机制。当一次操作（如修改任务状态）同时产生多个事件（如 `task.updated` 和 `task.status_changed`）时，系统会自动识别它们来自同一次操作，确保每个回调任务只执行一次，避免重复处理。详见 [事件回调 Hook](./event-callback-hook.md)。

**Q：跨工作空间的事件会触发回调任务吗？**

A：不会。事件回调任务只响应**同一工作空间内**产生的事件，不同工作空间之间的事件互相隔离。

**Q：Webhook 任务如何保证安全性？**
A：Webhook 通过 PAT（个人访问令牌）进行认证，支持 IP 白名单限制。只有持有有效 token 且 IP 在白名单内（如果配置了白名单）的请求才能触发任务。Webhook 任务的 UUID 不可猜测，配合 PAT 认证提供双重安全保障。

**Q：Webhook 的请求数据如何传递给 AI？**
A：你可以在 Prompt 模板中使用变量（如 `{{body}}`、`{{query}}`、`{{method}}` 等）引用外部系统的请求数据。系统会根据 Content-Type 自动处理请求体（支持 JSON、表单、纯文本格式）。

## 相关文档

* [任务管理](/docs/task-management/task-management)

* [事件回调 Hook](./event-callback-hook.md)

* [AI 对话](/docs/ai-assistant/ai-chat)

* [快捷命令](/docs/ai-assistant/quick-commands)