xAgent 触发器：定时任务与事件自动执行
版本范围：下文当前字段与行为按 2026-10-01 源码
43d2698核对。较早公开二进制可能不同；遇到界面或操作差异时，先核对自己的安装版本。
状态：实验性能力，页面和字段可能变化。
适用对象
本文适合需要让 xAgent 定时执行任务，或由外部事件自动创建任务的用户和管理员。
入口： 用户端 > 运行治理 > 触发器（/app/triggers）。当前列表属于登录用户；管理员在用户端查看的同样是自己的触发器，不是全员触发器列表。
这是什么
触发器用于自动提交任务。你可以把它理解为“到时间或收到事件后，自动把一条写好的任务发给 xAgent”。
触发器不等于任务结果。它向已选择的目标会话提交激活消息，由会话继续消费和执行；不会因为每次命中就自动新建一个会话。结果仍然要到目标会话和工作区查看。
图例说明：截图来自
v005。当前界面的 Key 由系统生成且只读；详情抽屉、计数和错误状态以下文说明为准。
什么时候使用
适合使用触发器的场景：
- 每天 9 点检查邮件并生成摘要。
- 每 4 小时收集新闻并推送总结。
- 每周生成固定周报。
- 外部系统有新消息后自动进入会话处理。
- 到点提醒处理某类重复任务。
不适合使用触发器的场景：
- 任务目标还不稳定。
- 每次材料都不同，且需要人工判断。
- 动作风险很高，不能自动启动。
- 外部系统授权还没有准备好。
页面怎么看
触发器管理 页面通常展示：
| 信息 | 含义 |
|---|---|
| 名称 | 触发器的显示名称 |
| key | 用户范围的稳定标识；创建时自动生成，可复制，不在表单中手工编辑 |
| 状态 | 是否启用 |
| 策略 | 定时周期或事件规则 |
| 运行态 | 下次计划时间、最近成功提交时间、成功提交消息次数；不是任务完成次数 |
| 操作 | 手动触发、禁用、编辑或删除 |
普通用户重点看名称、状态、下次运行时间和最近运行结果。
搜索匹配名称和 Key，可再按定时 / 外部类型筛选。当前触发器接口返回自己的完整列表，页面本地搜索；底部“总计”是类型筛选后的数量，不会随关键词匹配数变化，也不是分页页数。
打开详情可查看目标会话、激活上下文、任务内容、最近错误和可复制 Key。读取失败时页面会显示错误，不应把错误或加载中状态当成“没有触发器”；先刷新再判断。
基本用法
新建定时触发器
- 先准备一个用于接收任务的目标会话，再打开 触发器。
- 点击 新增触发器。
- 选择触发方式，例如定时；类型在创建后不可在编辑表单中切换。
- 填写名称，检查并按需复制自动生成的 Key。
- 选择目标会话、激活上下文，设置执行时间或周期。
- 填写触发后发送到目标会话的任务内容，按需设置失效时间和触发上限。
- 保存后检查启用状态和下次计划时间。
- 必要时先手动触发一次测试，并到目标会话核对实际结果。
触发任务内容要写成完整任务，不要只写“继续”“处理一下”。
示例：
请检查今天收到的客户邮件，整理需要回复的邮件清单。先生成草稿，不要自动发送。
选择时间与停止条件
| 设置 | 当前行为 |
|---|---|
| 间隔时间 | 按秒、分钟或小时填写，服务端最小间隔为 1 秒；频率仍应按任务成本和执行时长合理设置 |
| 固定时间 | 支持每天、每周或每月，当前调度使用 Asia/Shanghai（UTC+8），不是浏览器所在时区 |
| 每月日期 | 指定日期超出当月天数时，按当月最后一天计算 |
| 指定时间 | 使用未来的 Unix 毫秒时间，触发上限必须为 1 |
| 失效时间 | Unix 毫秒；0 表示不过期 |
| 触发上限 | 成功提交消息的最大次数；0 表示不限，1 表示成功提交一次后停止后续触发 |
| 激活上下文 | 可选全量上下文、切片上下文或仅通知；按目标会话的处理需要选择 |
例如“每天 9 点”按当前固定时间调度表示东八区 09:00。跨时区使用时先换算并核对页面下次触发时间，不能仅凭自己电脑的时钟判断。
手动触发一次
手动触发适合测试配置是否正确。触发后去对应会话查看是否创建任务、是否有失败提示、是否需要审批。
如果测试任务会影响外部系统，先改成只生成草稿或只读取数据。
外部触发器
选择外部类型时，配置目标会话和激活消息，并按页面保存外部触发 token。自动生成的 token 只在本次保存后显示，不能从列表重新读取；不要放进公开截图、提示词或文档。手动测试外部触发器需要填写有效 token。
外部触发器没有下次定时时间，只有收到有效外部命中后才向会话提交消息。它并不自动代表已经接入某个第三方事件源；外部系统的调用与授权还需单独配置。
禁用触发器
当任务不再需要、外部连接异常、策略待调整或可能重复执行时，先禁用触发器。禁用比删除更适合临时停用。
运行检查与排错
- 先看是否启用、是否过期或达到触发上限，再核对目标会话是否仍可访问。
- 到点未执行时检查下次时间、固定调度时区和详情中的最近错误。
- 自动定时触发遇到目标会话正在运行、压缩、收尾或等待审批时，会顺延 5 分钟；本次不会增加触发次数，也不会修改最近成功触发时间。先处理原会话中的未完成工作。
- 成功触发次数增加只说明消息被目标会话接受。继续核对执行结果、产物或待审批动作，不能用计数替代验收。
- 排错期间可先禁用，修复连接或配置后再启用并做一次低风险验证；避免重复手动触发有外部影响的任务。
编写触发任务
一条适合触发器的任务应包含：
| 内容 | 示例 |
|---|---|
| 目标 | 生成每日邮件摘要 |
| 数据范围 | 只处理今天 00:00 之后的新邮件 |
| 输出格式 | 输出待处理清单和建议回复 |
| 风险限制 | 不要自动发送，等待确认 |
| 失败处理 | 如果连接不可用，在会话里说明原因 |
完整示例：
请检查今天的新邮件，筛选需要我处理的事项，按紧急程度排序。需要回复的邮件只生成草稿，不要直接发送。