> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/integrations/triggers.md).

# 触发器

已连接的集成不仅仅是一个代理可按需读取的地方。它也是一个 **实时事件来源**。当有人给你发邮件、编辑 Notion 页面、在你的某个仓库里打开 GitHub issue、在 Stripe 上发起一笔扣款，或在 Slack 上给你发私信时，OpenHuman 会近乎实时地接收该事件，并决定是否要对此采取行动。

本页讲述的是这条流水线：触发器如何到达、如何被分类，以及无需你输入任何内容，一个触发器如何转化为完整的代理动作。

## 什么是触发器

触发器是由你已连接的集成发布的外部事件。常见形式：

| 集成         | 示例触发器                                                      |
| ---------- | ---------------------------------------------------------- |
| **Gmail**  | `GMAIL_NEW_GMAIL_MESSAGE`，收件箱中的新邮件                         |
| **Slack**  | `SLACK_NEW_MESSAGE`，你被提及的频道/私信消息                           |
| **Notion** | `NOTION_PAGE_UPDATED`，被跟踪的页面发生了变化                          |
| **GitHub** | `GITHUB_ISSUE_OPENED`, `GITHUB_PULL_REQUEST_OPENED` 在你的仓库中 |
| **Stripe** | `STRIPE_CHARGE_SUCCEEDED`，你账户上的一笔扣款成功                      |
| **日历**     | `GOOGLE_CALENDAR_EVENT_CREATED`，你的日历中新建了一个事件               |

完整列表来自 [Composio](https://composio.dev) 为 [第三方集成](/openhuman/zh/gong-neng/integrations.md)提供支持的连接器层。 当连接处于活动状态时，相关的触发器订阅会自动接入。

### Gmail OAuth 范围

Gmail 触发器订阅需要对已连接的 Google 账户拥有读取消息的权限。新的 OpenHuman Gmail 授权会请求 `https://www.googleapis.com/auth/gmail.readonly` 以便 `GMAIL_NEW_GMAIL_MESSAGE` 可以启用，并且原生 Gmail 同步路径可以读取新消息元数据。

如果某个较早的 Gmail 连接是在请求此范围之前创建的，请先在设置中重新连接 Gmail，然后再启用 Gmail 触发器。

## 触发器从何而来，端到端

```
┌────────────────────┐
│ 第三方 API │ Gmail / Slack / Notion / GitHub / ...
└─────────┬──────────┘
 │ webhook
 ▼
┌────────────────────┐
│ OpenHuman 后端 │ 进行 webhook 的 HMAC 验证，规范化载荷
└─────────┬──────────┘
 │ Socket.IO 事件 ("composio:trigger")
 ▼
┌────────────────────┐
│ Rust 核心 │ 发布 DomainEvent::ComposioTriggerReceived
│（你的笔记本）│ 在进程内事件总线上
└─────────┬──────────┘
 │
 ▼
┌────────────────────┐
│ 触发器分流 │ 分类：丢弃 / 确认 / 响应 / 升级
└─────────┬──────────┘
 │
 ▼
┌────────────────────┐
│ 其中之一：│
│ - 什么都不做 │ ← 丢弃
│ - 记忆备注 │ ← 确认
│ - Trigger Reactor │ ← 响应（1-2 次工具调用）
│ - Orchestrator │ ← 升级（完整的多步骤规划）
└────────────────────┘
```

webhook 不会以原始形式直接到达你的机器。保存 OAuth 令牌并直接从第三方接收 webhook 的是后端。它会进行 HMAC 验证，规范化载荷，并通过现有的已认证 socket 将其转发到你的 Rust 核心。你的笔记本看到的是一个干净、已验证的 `ComposioTriggerReceived` 总线上的事件，仅此而已。

## 分流步骤

在任何动作运行之前，每个触发器都会经过 [`trigger_triage`](https://github.com/tinyhumansai/openhuman/tree/main/src/openhuman/agent/agents/trigger_triage/README.md) 代理。它唯一的工作就是决定系统其余部分应当做什么。

它会且仅会选择四种动作中的一种：

| 动作       | 会发生什么                                                                                                                                            | 适用场景                                                |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| **`丢弃`** | 什么都不做。触发器会被静默记录并丢弃。                                                                                                                              | 垃圾信息、重复项、无关噪音。对于你不关心的内容，这是默认处理。                     |
| **`确认`** | 会保存一条简短的记忆备注，不运行任何代理。                                                                                                                            | 值得记住的被动通知（“归档中创建了一个新页面”）。                           |
| **`响应`** | The [`trigger_reactor`](https://github.com/tinyhumansai/openhuman/tree/main/src/openhuman/agent/agents/trigger_reactor/README.md) 代理会执行一到两次工具调用。 | 一个小的、单步的副作用：保存一条记忆记录、快速发一条确认回复、将线程标记为已读。            |
| **`升级`** | 完整的 **orchestrator** 代理接管并具备规划能力。                                                                                                                | 任何需要推理、多步骤或多种技能的事情：起草回复、更新多个 Notion 页面、决定如何处理传入的问题。 |

分流代理拥有与代理其余部分相同的记忆和工作区上下文。它可以判断某个触发器是否与您当前正在处理的内容相关、相关人员是谁，以及这是否属于你以前曾要求 OpenHuman 处理过的那类事情。

## 当触发器变成代理动作时

这正是区分“OpenHuman 有一个 Gmail 集成”和“OpenHuman 负责全天候接管你的收件箱”的部分：

* **`响应`** 是低成本路径。Trigger Reactor 是一个专精角色，硬性预算只有几次工具调用。它非常适合：写一条一行的记忆备注，内容是“看到一笔来自 Stripe 的 84 美元新扣款，客户 X，商家 Y”；因为这是一条你本周已经处理过两次的自动告警而静默地将 Slack 消息标记为已处理；或者存储一条结构化事件记录，供用户日后查询。
* **`升级`** 是高成本路径。当分流代理判断该触发器需要真正处理时，它会向 Orchestrator 移交一份自包含的任务描述。Orchestrator 可以访问你全部的技能、工具、记忆，以及 [潜意识循环](https://github.com/tinyhumansai/openhuman/tree/main/gitbooks/features/subconscious.md) 输出。从那里它可能会：
  * 起草一封重要邮件的回复并排队等你批准。
  * 调出相关的 Notion / Linear / Drive 上下文，为一条传入的问题写一条结构化评论。
  * 基于单个传入事件更新三个互联系统（“这位客户在 Stripe 上的套餐变更了，更新 HubSpot，在 #revenue 里发帖，并在他们的 Notion 文件里添加一条备注”）。

在这两种情况下，动作都在你的机器上运行，作用于你本地的 Memory Tree，并使用代理其余部分所用的相同模型路由和工具面。

## 为什么还要有分流步骤

人们很容易跳过分类器，直接把每个触发器都送进 orchestrator。但这有两个坏处：

1. **大多数触发器都是噪音。** 一个已连接的 Gmail 账户每小时会触发数十个事件，其中绝大多数用户并不关心。对每个事件都运行 orchestrator 会耗尽预算，并产生持续不断的后台活动流。
2. **不同触发器应有不同的上限。** 自动生成的 Stripe 收据和私人 Slack 私信，不应该花费同样多的 token 来处理。分流让低成本路径保持低成本，并把 orchestrator 留给真正值得用它的事情。

分流运行在快速模型层（参见 [自动模型路由](/openhuman/zh/gong-neng/model-routing.md)），因此分类本身是亚秒级的。

## 配置与退出

* **默认开启。** 一旦集成连接成功，其触发器就会自动进入流水线。
* **可退出。** 分流路径受以下环境变量控制： `OPENHUMAN_TRIGGER_TRIAGE_DISABLED` 将其设置为 `1` / `true` / `yes` 会关闭代理分类，并仅回退到被动记录。集成本身仍保持连接；只是自动执行动作的行为被抑制。
* **按触发器设置。** 触发器设置（要评估哪些集成和事件类型）在以下位置管理： **设置**；底层 RPC 方法为 `update_composio_trigger_settings` / `get_composio_trigger_settings`.
* **审计日志。** 无论最终决定如何，每个触发器都会写入触发器历史，因此你可以看到什么事件到达、分类器做了什么决定，以及实际运行了什么（如果有的话）。决策和升级也会作为 `TriggerEvaluated` / `TriggerEscalated` 事件发布到进程内总线上，这意味着核心内部的任何内容都可以订阅它们。

## 隐私边界

触发器遵循与产品其余部分相同的边界（参见 [隐私与安全](/openhuman/zh/gong-neng/privacy-and-security.md)):

* 第三方令牌保存在后端，绝不会放在你的笔记本上。
* webhook 在到达你的机器之前，会先由后端进行 HMAC 验证。
* 触发器载荷由你的本地核心处理；分类以及任何响应都在你的机器上执行，作用于你本地的 Memory Tree。
* 由 `确认` / `响应` / `升级` 路径写入的记忆备注会像其他来源一样，存储在你的本地 SQLite 记忆树和 Markdown vault 中。

## 实现提示（供开发者参考）

* 分流代理： `src/openhuman/agent/agents/trigger_triage/`
* 响应代理： `src/openhuman/agent/agents/trigger_reactor/`
* Composio 总线订阅者： `src/openhuman/integrations/composio/bus.rs` (`ComposioTriggerSubscriber`)
* 触发器历史持久化： `src/openhuman/integrations/composio/trigger_history.rs`
* 领域事件： `DomainEvent::ComposioTriggerReceived`, `DomainEvent::TriggerEscalated` 位于 `src/core/event_bus/events.rs`
* 触发器设置 RPC： `update_composio_trigger_settings` / `get_composio_trigger_settings` 位于 `src/openhuman/config/`

## 另见

* [第三方集成](/openhuman/zh/gong-neng/integrations.md)，触发器所来源的服务目录。
* [从集成自动获取](/openhuman/zh/gong-neng/obsidian-wiki/auto-fetch.md)，轮询对应功能，定期将源数据摄入 Memory Tree。
* [潜意识循环](https://github.com/tinyhumansai/openhuman/tree/main/gitbooks/features/subconscious.md)，使用触发器上下文和记忆进行前瞻规划的后台循环。