Hooks
低风险系统内部生命周期钩子
触发源系统事件（消息接收、会话开始等）
用途在关键时机插入规则、流程或内容替换
示例消息预处理、响应后处理、会话初始化
Triggers
触发机制
触发机制解决的是"什么时候把动作插进来"的问题。理解 Hooks、Webhooks、Cron 和 Heartbeat 的区别，才能设计出清晰可控的自动化流程。
Trigger Types
四种触发类型
理解每种触发类型的特点，选择最适合场景的触发方式。
Webhooks
中风险外部事件推送入口
触发源外部系统 HTTP 请求
用途接收外部系统事件，触发自动化流程
示例邮件通知、表单提交、CI/CD 事件
Cron
中风险时间驱动定时任务
触发源固定时间点或间隔
用途周期性执行任务
示例日报生成、健康检查、数据同步
Heartbeat
低风险主动唤醒机制
触发源固定间隔主动触发
用途让 agent 主动联系用户
示例定时提醒、状态汇报、周期检查
Hooks
生命周期钩子
Hooks 在系统内部关键时机插入规则、流程或动作，是生命周期扩展的核心机制。
可用事件
onMessageReceived收到消息时触发
消息预处理、内容过滤、意图识别onMessageSending发送消息前触发
响应修改、内容注入、格式转换onMessageSent消息发送后触发
日志记录、状态更新、后续动作onSessionStart会话开始时触发
初始化上下文、加载用户偏好onSessionEnd会话结束时触发
清理资源、保存状态、生成摘要onToolCall工具调用时触发
审批检查、参数验证、日志记录配置示例
{
"hooks": {
"enabled": true,
"entries": {
"content-filter": {
"event": "onMessageReceived",
"handler": "filterContent",
"priority": 100
},
"log-response": {
"event": "onMessageSent",
"handler": "logMessage",
"priority": 50
}
}
}
}Webhooks
外部事件入口
Webhooks 让外部系统把事件推送进来，是外部集成的关键入口。
常用端点示例
/hooks/gmailGmail 邮件通知
处理新邮件，生成摘要或提醒/hooks/githubGitHub 事件
处理 PR、Issue、Push 等事件/hooks/form表单提交
处理用户反馈、订单等表单数据/hooks/alert监控告警
接收监控系统告警，触发响应流程配置示例
{
"hooks": {
"enabled": true,
"token": "${WEBHOOK_TOKEN}",
"path": "/hooks",
"mappings": [
{
"match": { "path": "gmail" },
"action": "agent",
"agentId": "email-assistant",
"deliver": true
},
{
"match": { "path": "github" },
"action": "workflow",
"workflowId": "github-handler"
}
]
}
}安全建议
使用 token 验证请求来源
限制允许的 IP 范围
验证请求签名
记录所有 webhook 请求日志
Mappings
事件路由映射
Mappings 把路径或事件映射到 agent、动作和投递方式上，是入口分发的关键配置。
agent
路由到指定 Agent
{
"match": { "path": "support" },
"action": "agent",
"agentId": "support-bot"
}workflow
触发工作流
{
"match": { "path": "deploy" },
"action": "workflow",
"workflowId": "deploy-pipeline"
}skill
调用技能
{
"match": { "path": "summarize" },
"action": "skill",
"skillId": "summarizer"
}transform
数据转换后投递
{
"match": { "path": "notify" },
"action": "transform",
"template": "收到新消息：{content}"
}Comparison
事件驱动 vs 时间驱动
理解两种触发模式的区别，选择最适合场景的方式。
| 维度 | 事件驱动 | 时间驱动 |
|---|---|---|
| 触发方式 | 外部事件或系统事件触发 | 固定时间点或间隔触发 |
| 响应速度 | 实时响应，延迟低 | 取决于调度周期 |
| 资源消耗 | 事件驱动，按需消耗 | 持续轮询，固定消耗 |
| 适用场景 | 消息处理、告警响应、用户交互 | 日报生成、定期检查、数据同步 |
| 可靠性 | 依赖事件源可靠性 | 更可控，不依赖外部 |
| 调试难度 | 需要模拟事件，较复杂 | 可预测，较简单 |
Use Cases
典型应用场景
根据场景选择合适的触发方式。
消息预处理
Hooks - onMessageReceived在消息进入 agent 前进行过滤、转换或增强
- 接收原始消息
- 执行内容过滤
- 提取关键信息
- 注入上下文
- 传递给 agent
外部系统集成
Webhooks接收外部系统事件并触发响应
- 配置 webhook 端点
- 外部系统推送事件
- 验证请求合法性
- 解析事件数据
- 触发对应处理流程
定时任务执行
Cron按固定时间表执行任务
- 定义 cron 表达式
- 配置任务内容
- 设置并发限制
- 配置失败处理
- 记录执行日志
主动提醒服务
Heartbeat让 agent 主动联系用户
- 配置心跳间隔
- 定义触发条件
- 设置提醒内容
- 指定目标用户
- 处理用户响应
Examples
完整配置示例
参考这些配置示例，快速搭建触发系统。
完整 Hooks 配置
包含生命周期钩子和 webhook 映射
{
"hooks": {
"enabled": true,
"token": "${HOOKS_TOKEN}",
"path": "/hooks",
// 生命周期钩子
"entries": {
"content-filter": {
"event": "onMessageReceived",
"handler": "./handlers/filter.js",
"priority": 100
},
"logger": {
"event": "onMessageSent",
"handler": "./handlers/logger.js"
}
},
// Webhook 映射
"mappings": [
{
"match": { "path": "gmail" },
"action": "agent",
"agentId": "email-bot"
},
{
"match": { "path": "alert" },
"action": "workflow",
"workflowId": "alert-handler"
}
]
}
}Cron 定时任务配置
配置多个定时任务
{
"cron": {
"enabled": true,
"maxConcurrentRuns": 2,
"sessionRetention": "24h",
"jobs": [
{
"id": "daily-report",
"schedule": "0 8 * * *",
"agentId": "reporter",
"prompt": "生成昨日工作日报"
},
{
"id": "health-check",
"schedule": "*/15 * * * *",
"agentId": "monitor",
"prompt": "检查系统健康状态"
}
],
"runLog": {
"maxBytes": "2mb",
"keepLines": 2000
}
}
}Heartbeat 心跳配置
配置主动唤醒机制
{
"agents": {
"defaults": {
"heartbeat": {
"every": "30m",
"target": "last",
"directPolicy": "allow",
"prompt": "检查是否有需要提醒的事项"
}
}
}
}Best Practices
最佳实践
先定义事件链
事件从哪里来、交给谁、输出去哪，至少先写成三段。
优先最小 mapping
先让一个路径只做一件事，再决定要不要扩成复杂流。
保留人工兜底
任何外部事件入口都应该有失败后人工查看和补处理的办法。
分层管理触发器
事件触发、时间触发、主动唤醒三者最好不要揉成一个配置故事。
记录完整日志
所有触发事件都应记录，便于事后排查和审计。
设置超时和重试
外部调用要设置合理的超时时间和重试策略。
FAQ
常见问题
Hooks 和 Webhooks 有什么区别？
Hooks 是系统内部的生命周期钩子，在特定事件发生时触发。Webhooks 是外部系统通过 HTTP 请求推送事件的入口。前者是内部事件驱动，后者是外部事件接入。
什么时候用 Cron，什么时候用 Webhook？
如果任务是固定时间执行的（如日报），用 Cron。如果任务是响应外部事件的（如收到邮件），用 Webhook。不要把 webhook 当 cron 用。
如何保证 Webhook 安全？
使用 token 验证、限制 IP 范围、验证请求签名、记录请求日志。不要直接暴露 webhook 端点到公网。
Heartbeat 和 Cron 有什么区别？
Cron 是时间驱动的定时任务，在固定时间点执行。Heartbeat 是 agent 主动唤醒机制，让 agent 按固定间隔主动联系用户，更像"定期汇报"。
多个 Hooks 的执行顺序如何控制？
通过 priority 字段控制优先级，数值越大越先执行。相同优先级的执行顺序不确定。
Related