事件回调

了解如何配置事件回调，在系统事件发生时自动触发 Agent 执行任务

事件回调

功能概述

事件回调 Hook 是一种自动化机制，允许系统管理员配置当系统内发生特定事件时，自动唤起 Agent 执行预设任务。

支持的事件类型

任务事件

事件名称	触发时机	上下文变量
`task.created`	新任务创建时	taskId, taskDBId, taskType, taskTitle, taskStatus, createdBy
`task.updated`	任务更新时	taskId, taskDBId, taskType, taskTitle, taskStatus, updatedBy, changes
`task.commented`	添加评论时	taskId, taskDBId, taskType, taskTitle, commentId, commentContent, commenterId, commenterName
`task.reassigned`	负责人变更时	taskId, taskDBId, taskType, taskTitle, assigneeId, assigneeName, updatedBy
`task.status_changed`	状态变更时	taskId, taskDBId, taskType, taskTitle, taskStatus, updatedBy
`task.deleted`	任务删除时	taskId, taskDBId, taskType, taskTitle, deletedBy

对话事件

事件名称	触发时机	上下文变量
`conversation.error`	对话出错时	conversationId, errorMessage, errorStack, retryCount
`conversation.quota_exhausted`	额度用尽时	conversationId, errorMessage, quotaType, remaining
`conversation.timeout`	对话超时时	conversationId, errorMessage, duration, lastMessage

工作空间事件

事件名称	触发时机	上下文变量
`workspace.member_joined`	成员加入时	userId, userName
`workspace.member_left`	成员离开时	userId, userName

使用方式

创建事件回调任务

进入工作空间 → 自动化任务页面
点击"新建任务"
选择类型为"事件回调"
配置监听事件（可多选）
编写 Prompt 模板（支持变量替换）
可选：配置条件表达式
保存任务

上下文变量说明

所有事件都会携带通用变量，不同类别的事件还会携带各自专属的变量。在 Prompt 模板和条件表达式中均可使用这些变量。

通用变量

变量名	类型	说明	示例值
`eventName`	string	触发的事件名称	`task.created`
`timestamp`	string	事件触发时间（ISO 格式）	`2026-01-15T09:00:00Z`
`workspaceId`	string	所属工作空间 ID	`cmkenp...`

任务变量

适用于 task.* 类事件。不同的任务事件携带的变量不同，具体每个事件包含哪些变量请参见上方支持的事件类型表格。

变量名	类型	说明	示例值
`taskId`	string	任务业务编号	`task-1`
`taskDBId`	string	任务数据库 UUID	`a1b2c3d4-...`
`taskType`	string	任务类型（如 task、bug、story 等）	`task`
`taskTitle`	string	任务标题	`修复登录Bug`
`taskStatus`	string	任务当前状态	`todo`
`assigneeId`	string	负责人 ID	`user-uuid-456`
`assigneeName`	string	负责人名称	`张三`
`createdBy`	string	任务创建者	`李四`
`updatedBy`	string	任务更新者	`王五`
`deletedBy`	string	任务删除者	`赵六`
`changes`	string	变更字段详情（JSON 格式）	`{"status":"blocked"}`

评论变量

适用于 task.commented 事件。其他任务事件不包含评论变量。

变量名	类型	说明	示例值
`commentId`	string	评论 ID	`comment-uuid-789`
`commentContent`	string	评论内容	`这个Bug已修复`
`commenterId`	string	评论者 ID	`user-uuid-abc`
`commenterName`	string	评论者名称	`赵六`

对话变量

适用于 conversation.* 类事件。不同的对话事件携带的变量不同，具体见上方支持的事件类型表格。

变量名	类型	说明	示例值
`conversationId`	string	对话 ID	`conv-uuid-abc`
`errorMessage`	string	错误信息	`API调用超时`
`errorStack`	string	错误堆栈（仅 error 事件）	`Error: ...`
`retryCount`	number	重试次数（仅 error 事件）	`2`
`quotaType`	string	额度类型（仅 quota_exhausted 事件）	`token`
`remaining`	number	剩余额度（仅 quota_exhausted 事件）	`0`
`duration`	number	超时时长秒数（仅 timeout 事件）	`300`
`lastMessage`	string	最后一条消息（仅 timeout 事件）	`请帮我分析...`

工作空间变量

适用于 workspace.* 类事件。

变量名	类型	说明	示例值
`userId`	string	相关用户 ID	`user-uuid-def`
`userName`	string	相关用户名称	`孙七`

批量变量

当启用批量合并时，合并后的事件会携带以下额外变量。

变量名	类型	说明	示例值
`batch`	boolean	是否为批量合并事件	`true`
`batchSize`	number	合并的事件数量	`10`
`events`	string	各事件摘要（JSON 数组）	`[{"eventName":"task.created",...}]`

Prompt 模板变量

在 Prompt 中使用 {{变量名}} 插入事件上下文变量：

新任务创建通知：
- 任务标题：{{taskTitle}}
- 任务状态：{{taskStatus}}
- 创建者：{{createdBy}}
请自动分析任务优先级并添加标签。

条件表达式

条件表达式用于精确控制事件触发条件，使用 JavaScript 表达式语法：

// 仅 blocked 状态触发
ctx.taskStatus === 'blocked'

// 标题包含"紧急"时触发
ctx.taskTitle.includes('紧急')

// 复合条件
ctx.taskStatus === 'blocked' && ctx.retryCount < 3

// 多状态匹配
['blocked', 'waiting'].includes(ctx.taskStatus)

留空表示所有匹配事件都触发。

高级特性

操作级去重（operationId）

当一次操作同时触发多个事件时（例如修改任务状态会同时产生 task.updated 和 task.status_changed），系统会自动识别这些事件来自同一次操作，确保每个回调任务只执行一次。

示例：假设配置了一个回调任务同时监听 task.updated 和 task.status_changed，当用户修改任务状态时：

系统产生 2 个事件：task.updated + task.status_changed
两个事件共享同一个 operationId
回调任务只执行 1 次，而不是 2 次

此机制对用户透明，无需额外配置。

事件去重

系统自动对短时间内的重复事件进行去重（默认 5 秒窗口），避免同一事件多次触发回调。

批量事件合并

当短时间内产生大量相同类型事件时，系统会在时间窗口内合并事件，一次性传递给 Agent 处理，提高执行效率。

队列控制

系统限制并发执行的事件回调数量（默认最大 100），防止系统过载。

配置参数

以下参数可通过系统配置管理：

配置项	默认值	说明
`eventCallback.dedupEnabled`	`true`	是否启用事件去重
`eventCallback.dedupWindowMs`	`5000`	去重时间窗口（毫秒）
`eventCallback.mergeEnabled`	`false`	是否启用批量合并
`eventCallback.mergeWindowMs`	`5000`	合并时间窗口（毫秒）
`eventCallback.maxQueueSize`	`100`	最大队列长度

常见问题

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

A：不会。事件回调任务只会被同一工作空间内产生的事件触发。例如，工作空间 A 中配置的回调任务不会被工作空间 B 中的任务创建事件触发。每个事件都携带 workspaceId，系统在匹配回调任务时会严格按工作空间隔离。