自动化任务

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

功能概述

自动化任务可以：

• 按固定时间间隔执行

• 在指定时间点执行

• 使用 Cron 表达式配置

• 自动触发 AI Agent 执行

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

Cron 表达式限制

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

使用场景

定期报告

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

数据同步

定时同步数据：

提醒通知

定期提醒：

自动维护

定期执行维护任务：

事件驱动自动化

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

详细说明请参考 事件回调 Hook

Webhook 回调自动化

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

配置方式：

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

使用方式：

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

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

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

指定执行人

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

为什么需要指定执行人？

执行人优先级规则

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

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

配置方法

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

指定执行环境

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

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

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

任务类型

系统支持三种任务类型：

事件回调类型的详细配置和使用请参考 事件回调 Hook

创建自动化任务

步骤 1：进入任务管理

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

步骤 2：新建自动化任务

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

步骤 3：配置任务

填写任务配置：

步骤 4：保存并启用

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

执行计划配置

简单模式

使用预设的时间选项：

高级模式（Cron 表达式）

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

Cron 示例

Cron 字段说明

任务内容

文本指令

直接输入要执行的指令：

使用模板

可以使用变量模板：

支持的变量：

管理自动化任务

查看任务列表

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

启用/禁用任务

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

禁用的任务：

• 不会按计划执行

• 配置保留

• 可以随时重新启用

编辑任务

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

删除任务

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

手动执行

可以手动触发任务执行：

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

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

执行历史

查看历史

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

异常执行收敛

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

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

历史保留

执行历史默认保留 30 天。

最佳实践

1. 合理安排执行时间

• 避免高峰时段

• 考虑时区差异

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

2. 控制执行频率

3. 清晰的任务内容

4. 监控执行结果

• 定期检查执行历史

• 关注失败的任务

• 及时调整配置

限制说明

执行频率限制

• 最小间隔：5 分钟

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

执行超时

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

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

常见问题

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

A：检查以下几点：

• 任务是否已启用

• Cron 表达式是否正确

• 是否超过配额限制

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

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

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

A：可以。创建任务时选择"事件回调"类型，配置监听事件和触发条件即可。详见 事件回调 Hook。

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

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

Q：如何临时暂停任务？

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

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

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

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

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

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

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

相关文档

• 任务管理

• 事件回调 Hook

• AI 对话

• 快捷命令