# Meegle 插件监听事件：去重与可靠接入验证

## 结论与验证范围

**官方协议支持按事件唯一标识去重。** 本方案使用飞书项目（Meegle）插件的「监听事件」，去重字段是请求体中的 `data.idempotent_key`，不是 `event_id`、`log_id` 或自动化 Webhook 的 `header.uuid`。[S1][S3]

本次通过浏览器读取官方文档正文，完成协议层可行性核对；没有实际注册插件、接收真实回调、制造超时或验证服务端实现。下面严格区分平台合同、拟定设计与待联调事项。

## 官方协议事实

### 1. 公网 POST、1 秒响应、有限重试

官方《监听事件》要求回调地址公网可访问，事件通过 HTTP/HTTPS POST 发送；插件配置相关事件并发布版本、在空间安装后生效。[S1]

原文：

> 你在接收到飞书项目的请求后，需要在1000ms内返回状态码为200的响应。

> 为保证用户可以正确接收到监听事件，当发送失败后，会进行4次重试（重试间隔为立即重试，1分钟，2分钟，7分钟）。重试4次仍然发送失败，则不会继续重试。

这里的间隔按官方原文记录，不换算成绝对重试时刻。官方建议将耗时业务异步处理。我们的入口采用 HTTPS；公网入口可通过网关转发到内部调度中心，不需要暴露整个调度服务。[S1；后两句为项目设计]

### 2. 去重键与乱序

官方原文：

> 同一事件可能多次发送，开发者可以通过请求体body中的事件唯一标识("idempotent_key")自行过滤。

通用结构中的关键字段（省略其他字段）：

```json
{
  "log_id": "...",
  "request_time": 1730184005453,
  "signature": "...",
  "source": "normal",
  "source_plugin_id": "...",
  "data": {
    "event_type": 3001,
    "idempotent_key": "..."
  }
}
```

官方字段解释明确 `data.idempotent_key` 是「事件的唯一标识」。因此使用它过滤同一事件的重复推送有直接文档依据，而不是假设 HTTP 请求体或请求时间在每次重试中不变。[S1]

事件无序发送。文档建议参考 `request_time`，并将它解释为事件发送时间、通常近似事件发生时间。因此不能把它当作严格的卡片版本号，也不能认为接收去重就解决了旧状态晚到的问题。[S1；最后一句为设计推论]

**文档未明确**唯一标识的全局唯一范围、保留期、人工重放是否沿用原键、重试时 `request_time` 是否变化。落地时需联调，不承诺任何场景的 exactly-once。

### 3. 验签

配置回调 token 后，官方验签规则是：[S1][S2]

```text
expected_signature = hex(SHA256(plugin_id + request_time + callback_token))
```

按文档顺序直接拼接字符串，不是 HMAC，也不是 GitHub 或普通飞书事件的签名规则。回调 token 虽为平台可选配置，本方案要求配置，并由可信接入配置绑定插件身份后进行校验。

该公式不包含 `data` 全量内容，不能宣传为完整载荷的密码学防篡改保证。需要 HTTPS、保密 token、入口防护；事件来源鉴别也不能代替操作人审批权核对。防重放时间窗口需结合实际重试报文验证，不能贸然按首次事件时间设置过短窗口。[S2；后两句为项目安全要求]

### 4. 不要混用自动化 Webhook

产品手册《Webhook 使用》描述的是在「自动化规则」中添加 Webhook 操作的另一套机制：[S3]

- 幂等串为 JSON 请求体中的 `header.uuid`，不是 HTTP header。
- 超时为 6 秒，最多重试 3 次。
- 该页将 1xx / 2xx 描述为成功响应。

这些规则**不适用于本方案采用的插件监听事件**。插件监听事件采用 `data.idempotent_key`、1000ms、HTTP 200、失败后 4 次重试。[S1]

### 5. Lark 是另一条接入线路

Lark 官方 Node SDK 文档支持用 `WSClient` 建立 WebSocket 长连接接收机器人消息事件，无需对外提供公网 IP 或域名；该连接与 Meegle 插件监听事件的公网回调分开配置。SDK 文档同时说明长连接消费仍有自己的超时重推机制，不能将其理解为无需幂等。[S4]

本次只确认 Lark 长连接接入能力，不把 Lark 消息的去重字段或超时规则套用到 Meegle。

## 拟定的调度中心接收设计（不是平台已提供能力）

1. **校验入口**：HTTPS 接收，绑定可信插件配置，校验结构和签名；非法请求不触发任务。缺少必要去重键的事件隔离并告警，不静默绕过去重。
2. **持久化接收**：以「本地接入配置 + 租户/空间 + `data.idempotent_key`」建立持久化唯一约束。命名空间按最终报文字段及接入配置确定，不把来源插件字段直接当成接收插件身份。唯一写入和后续可恢复处理安排必须可靠衔接，例如事务事件表加扫描/outbox；不能先标记已接收，再依赖可能丢失的内存派工。
3. **快速应答**：验签并可靠记录后，1000ms 内返回 HTTP 200。相同键已经可靠接收的重复请求直接应答，不重复创建任务。未能可靠保存时不返回成功，允许上游有限重试。
4. **异步消费**：记录待处理、处理中、成功、失败等状态；崩溃恢复后继续处理未完成事件。HTTP 200 只代表可靠接收，不代表 Agent 已完成。
5. **副作用幂等**：任务创建、卡片流转、通知和计数还需要业务动作唯一键/条件更新。平台重推、内部工作进程重试、两个不同事件指向同一动作，都不能重复派工或计数。外部写入成功但本地确认失败时，先核对执行结果，不能盲目重做。
6. **乱序与补偿**：动作前核对当前卡片状态和本地流程版本/前置条件，拒绝旧事件倒退流程；时间戳仅辅助判断。处理失败由内部重试、隔离、告警和对账补偿承接，不依赖平台无限重试。
7. **区分重推和反馈循环**：Agent 回写产生的新事件可能具有新去重键；需要结合本地动作记录及事件来源识别反馈，不能只靠事件键去重，也不能一律丢弃所有 Open API 来源事件。

## 待联调验证清单

- 同一事件被故意超时/非 200 触发重推时，`data.idempotent_key` 保持事件身份；观察 `request_time`、签名及实际重试节奏。
- 多个工作项/节点/状态事件是否都具备预期的唯一标识和租户、空间、操作人字段；确认不同安装/订阅及人工重放的标识范围。
- 多进程同时接收同一事件，只落一条有效接收记录、创建一个业务任务。
- 保存后应答前崩溃、应答后消费前崩溃、业务执行后确认前崩溃，均可恢复且不重复副作用。
- 相同卡片事件乱序、Agent 自身回写、平台重试耗尽，以及敏感字段脱敏与审计。
- 入口在预期峰值下完成验签、持久化和应答的端到端耗时满足 1000ms；日志排队或 Agent 启动不得阻塞应答。
- 回调 token 轮换、防重放窗口、网络入口安全，以及未通过校验的请求隔离策略。

这些是验收条件，不是已完成的测试结果。

## 官方来源

- [S1 监听事件 — 飞书项目开发者手册](https://project.feishu.cn/b/helpcenter/1p8d7djs/lvojfwht)：配置流程、重点说明、稳定性说明、事件结构。
- [S2 兼容性说明与验签说明 — 飞书项目开发者手册](https://project.feishu.cn/b/helpcenter/1p8d7djs/kztn7qno)：验签公式、示例代码与公网回调要求。
- [S3 Webhook 使用 — 飞书项目产品手册](https://project.feishu.cn/b/helpcenter/1ykiuvvj/49fq0rvm)：自动化规则 Webhook 的格式、成功标准与重试机制，仅用于辨别不同协议。
- [S4 Lark 官方 Node SDK：Subscribing to Events Using Long Connection Mode](https://github.com/larksuite/node-sdk#subscribing-to-events-using-long-connection-mode)：`WSClient`、连接模式和注意事项；[其引用的官方长连接文档](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/event-subscription-guide/long-connection-mode#62c8b8c8)。
