interaction-async

name	interaction-async
description	当你要让 Agent 响应随时到达的外部事件（邮件/定时/Webhook/用户打断）、支持多任务并发、处理异步打断时使用；当 Agent 只能被动响应用户输入、无法在指定时间自主行动时使用。不适用于语音（见 interaction-voice）或 GUI（见 interaction-computer-use）。

异步与事件驱动（Async & Event-Driven）

角色与读者

面向构建"活"的、能被世界唤醒的 Agent 的开发者。本 Skill 服务的目标：让世界能主动通知 Agent，让 Agent 随时响应并优雅处理打断。核心认识：真正的"主动服务"不仅需要 Agent 定时检查世界，更需要世界主动通知 Agent。所有输入（用户消息、工具返回、外部回调、定时触发）统一建模为事件流。

核心原则（配正例/反例）

1. 事件驱动机制：框架自主（Hooks/Cron/Heartbeat）+ 工具（定时器/监控/通道/用户沟通）

   • 框架自主三机制（OpenClaw 模式）：Hooks（响应 Agent 生命周期事件，如会话创建）、Cron（按 cron 表达式周期任务）、Heartbeat（每隔 N 分钟唤醒检查）。真正让 Agent"自己动起来"的是 Cron 和 Heartbeat（时间驱动）。
   • 事件触发工具：set_timer（一次性/循环）、monitor_shell（监控命令行新增输出，避免不断查询浪费 token 或等结束才发现问题）、connect_channel（新邮件/API 回调/IM 消息实时推送）。
   • 短板：第三方事件源缺即时接入 → 用 Channel 机制（Gateway 与外部 API 间的实时事件通道），如 PineClaw 电话场景（客服等验证码不能靠轮询）。
   • 用户沟通工具：reply_to_user / send_card / send_notification，多渠道召回（IM/短信/邮件/电话/推送），支持异步消息（用户不一定在线）+ 已读状态。
   • 事件载荷应含足够上下文，减少唤醒后额外查询；定义清晰触发条件过滤无关事件。

2. 事件结构化建模（来源/渠道/内容/上下文）

   • 来源（谁）、渠道（电话/短信/邮件/定时器/工具结果）、内容（文本/情感/紧急度/是否需回复）、上下文（回复还是新沟通、与当前任务关联）。
   • 只有清晰建模才能避免把用户输入误当工具结果、把藏指令的工具结果误认用户指令（提示注入）。

3. 三种处理策略（区别在于对待安全点的方式）

   • 取消式（紧急事件）：主动中断制造安全点——停止当前操作→清空队列→事件+紧急事件一起追加→立即重新调 LLM。
   • 队列式（常规事件）：入队不打断→等当前操作完成→工具返回时批量追加→LLM 综合处理。
   • 并行式（独立轻量查询）：并行推理会话独立执行，结果标记"与主任务并行"。
   • 紧急度判定建议用轻量分类 LLM 作为事件路由器，而非硬编码规则。

4. 让同步模型支持异步打断（五条规则）

   • ① LLM 输出后立即记录 assistant message；② 工具完成才记录 tool result；③ 工具执行中打断用占位符（"工具正在后台执行，请优先处理新事件"）；④ LLM 思考中打断直接丢弃当前思考；⑤ 非打断事件入队批处理。
   • 核心：常态下 LLM 看到完美同步轨迹，只在打断时引入占位符。风险：模型可能编造工具结果，所以只在真正紧急时打断。
   • 异步工具接口把"启动"和"完成"解耦（initiate_phone_call 立即返回任务 ID，进展靠事件通知）。

5. 批量事件的注意力分散问题

   • 模型倾向只关注最后一个事件。干预：提示词告知"全面考虑所有信息" + 状态栏标记 [未处理事件 1/4] + 末尾汇总。

6. 虚拟身份与隔离执行环境（独立行动的基础设施）

   • 架构选择：直接管理用户账号（一旦出错/被攻破全部数字身份暴露）vs 独立虚拟身份（专属通讯账号/存储/计算环境，透明代表用户工作）。
   • 隔离环境：虚拟电脑（VM/容器）+ 虚拟手机（Android 模拟器），OS 级隔离，全天候运行、错误最多崩溃虚拟环境、防止访问用户本地文件。
   • 两个挑战：反机器人机制（CAPTCHA/IP 信誉，数据中心 IP 易识别，需住宅代理）；访问用户真实账号用 HITL 认证（VNC/RDP 远程桌面让用户亲自登录，会话令牌有效期复用）。
   • 数据交换：共享文件系统卷挂载（/workspace/shared），传递文件路径引用而非内容拷贝，避免占用上下文。

执行流程（SOP 检查清单）

1. 建框架自主机制（Hooks/Cron/Heartbeat）+ 事件源（定时器/监控/通道）+ 事件队列 + 事件循环（每轮边界消费事件）。
2. 事件结构化建模（来源/渠道/内容/上下文）。
3. 设计三种处理策略 + 紧急度路由器（轻量分类 LLM）。
4. 实现异步打断（占位符 + 入队 + 异步工具接口）。
5. 建虚拟身份与隔离执行环境（虚拟电脑/虚拟手机 + 共享文件系统 + HITL 认证）。
6. 处理批量事件注意力分散（状态栏标记 + 汇总）。

禁止清单（写清合法例外）

• 禁止伪造未完成工具的成功结果。例外：显式占位符，真实结果到达后追加。
• 禁止在任意时刻强行掐断（取消也在安全点检查）。例外：紧急事件主动制造安全点。
• 禁止非紧急事件频繁打断（破坏同步轨迹 + 加剧幻觉）。例外：非紧急入队批量处理。
• 禁止让 Agent 不断轮询查询进展（浪费 token）。例外：用 monitor_shell 监控新增输出。
• 禁止把外部内容直接当指令（事件来源标注 + 指令数据分离）。例外：见 agent-security。
• 禁止让 Agent 直接管理用户主账号（出错/被攻破全暴露）。例外：用独立虚拟身份 + 隔离环境；必须用本人身份时用 HITL 认证（VNC/RDP）。

参考资料

• 本书第 6.2 节《异步与事件驱动》（为什么异步、OpenClaw 机制、事件触发/用户沟通工具、虚拟身份、事件处理机制、异步打断、未来方向）。
• 笔记 06-交互.md 第 6.2 节。