---
title: 事件、等待与唤醒
summary: 消息、任务结果、定时器与外部事件如何让 Agent 暂停并恢复已授权的工作。
order: 70
aliases:
  - /zh-CN/concepts/external-triggers
  - /zh-CN/concepts/external-triggers.md
---

<a id="external-triggers"></a>
<a id="the-trigger-model"></a>

# 事件、等待与唤醒

事件为运行时提供待处理的输入；等待记录 Agent 在继续工作前预期的外部条件；唤醒则让运行时重新评估或恢复工作。这三者共同构成了异步工作流。

例如，负责修复构建的 Agent 触发了 CI，登记了一个针对该 CI 运行的等待记录，随后暂停执行。CI 的完成通知能够将其唤醒。唤醒后，Agent 仍需核实该次构建的状态，以判断最初的目标是否已经达成。

## 工作来源与事实依据

操作者发送的消息可以启动或调整工作；命令执行的结果可以唤醒正在等待测试的工作；定时器到期可以触发周期性检查；外部回调端点可以通知 Holon 外部发生的状态变动。此外，Agent 也可以自行将后续跟进事项入队。

这些输入会完整保留各自的来源信息。定时器到期不等于人类提出的新需求；Webhook 触发也不能擅自扩大操作者最初设定的范围。调度的紧急程度与指令的授权权威始终相互独立。

<a id="the-agents-waitfor-cycle"></a>

## 登记等待记录

Agent 通过等待操作声明其所期望的条件：任务结果、定时器、外部对象或操作者输入。对于任务和定时器等待，资源标识即为实际的运行时句柄；对于外部等待，资源标识指向外部系统中的具体对象（例如 Pull Request 或 CI 运行记录）。

登记等待本身并不会自动订阅外部服务、启动定时器或触发任务执行，这些资源需要独立就绪。登记等待也不代表 Agent 必须立即让出执行权：如果请求的任务结果已经就绪，运行时会直接返回该结果，供当前轮次继续使用。

即便工作项当前仍存在独立的业务阻塞，明确的等待记录在匹配到唤醒条件时依然可以恢复对应的后续流程。但这种恢复既不会清除业务阻塞，也不会授权执行无关操作。如果发生取消、停止或已完成标记，旧的后续执行同样会失效。

<a id="delivery-modes"></a>
<a id="callback-endpoints"></a>
<a id="example-wake-callback"></a>
<a id="example-enqueue-callback"></a>

## 唤醒提示与消息传递

外部请求接入支持两种交付模式：

| 模式 | Agent 接收到的内容 |
|---|---|
| `wake_hint` | 重新检查外部状态的唤醒信号。回调请求的载荷不会作为模型可见的消息传递。 |
| `enqueue_message` | 包含外部完整载荷的排队消息，完整保留其来源与可信度元数据。 |

当外部真实状态可直接被主动查询时（如 CI 构建状态），使用唤醒提示（wake hint）；当后续推进必须依赖回调载荷中的具体数据时，使用排队消息（enqueue message）。无论哪种方式，收到通知仅证明网络交付成功，并不代表外部业务操作已顺利完成。

关于回调端点的配置及两种交付模式的示例，请参阅[连接外部事件](../guides/connect-external-events.md)。

<a id="default-ingress-capability"></a>

Agent 的默认外部接入凭证可以在多个不同目标之间复用。各个工作项各自管理自身的等待记录，无需在每个常规等待周期中频繁创建和吊销回调。

<a id="scheduled-timers"></a>

## 定时器与回退检查

定时器用于安排未来的唤醒；创建定时器不会暂停当前轮次。如果当前工作必须等待定时器触发，Agent 会显式登记一个定时器等待。周期性重复的定时器在被显式取消前，会持续承担调度触发的责任。
取消活跃定时器时，依赖该定时器的未准入等待会被原子结算，终态原因为 `timer_cancelled`，避免遗留悬挂的等待注册，同时让所属工作项保持显式阻塞状态，直至产生新的等待或操作者操作。

等待记录中附带的回退检查时限（fallback recheck deadline）具有不同用途：它是在预期唤醒信号未到达时，对该次特定等待进行重新评估的保障机制，不能替代独立管理的周期性定时调度。

<a id="integration-patterns"></a>
<a id="cicd-pipeline"></a>
<a id="github-webhooks"></a>

## 完整的 CI 异步流转实例

操作者指示 Agent 修复构建并等待 CI 验证。Agent 记录该目标并触发构建，随后配置回调并进入等待。当通知到达时，Agent 校验对应的构建记录与代码版本。若 CI 失败，在授权范围内排查原因；若 CI 成功，在标记完成前进一步核对剩余的验收标准。

整个过程中，只要守护进程持续运行，操作者无需保持客户端界面常开。如果守护进程停止或进程意外中断，则属于独立的恢复流程；详见[上下文连续性](./context-continuity.md)。

<a id="security-model"></a>
<a id="reset-callback-token"></a>
<a id="cancelling-triggers"></a>

## 访问控制与授权安全

回调 URL 中包含能力凭证。拥有该 URL 即可触发对应的唤醒或入队动作，因此绝不能将其放入公开报告或提交到源码仓库中。该 URL 并不赋予发送者操作者级别的权威。只有在确实需要终止外部访问时才进行轮换或吊销，不要将吊销凭证当作常规清理等待状态的手段。

<a id="agent-stop-auto-revocation"></a>

停止 Agent 会自动吊销其绑定的外部触发器。在重新建立集成前，应检查当前有效凭证并替换已失效的 URL。关于回调的更换与吊销，参见[连接外部事件](../guides/connect-external-events.md)。

<a id="see-also"></a>

## 下一步

- [连接外部事件](../guides/connect-external-events.md)
- [调度一次性或周期性工作](../guides/schedule-agent-work.md)
- [HTTP 控制平面参考](../reference/http-control-plane.md)
- [唤醒与后续执行规格](../spec/wake-and-continuation.md)