Cloudsome 文档
需求设计报告
  • 通用架构
  • Hermes Agent
  • Hermes Agent V2
  • OpenMausBot
  • 小鹏灵犀 · 静态架构(参考)
  • 土豆(@poteto)· Grok Bot 自动化开发流程
  • 微软人事智能体 · 分层架构(参考)
选型报告
  • 票据 OCR 选型(草稿)
  • OCR 云 API 产品评估与评分(草稿)
  • 票据 OCR 选型需求与评分口径(草稿)
  • 票据 OCR PoC 测试计划(待启动)
  • OCR 通用文档识别选型(维度二·草稿)
财务工作流
补充材料
需求设计报告
  • 通用架构
  • Hermes Agent
  • Hermes Agent V2
  • OpenMausBot
  • 小鹏灵犀 · 静态架构(参考)
  • 土豆(@poteto)· Grok Bot 自动化开发流程
  • 微软人事智能体 · 分层架构(参考)
选型报告
  • 票据 OCR 选型(草稿)
  • OCR 云 API 产品评估与评分(草稿)
  • 票据 OCR 选型需求与评分口径(草稿)
  • 票据 OCR PoC 测试计划(待启动)
  • OCR 通用文档识别选型(维度二·草稿)
财务工作流
补充材料
  • 需求设计报告
    • 静态架构
    • 基本流程
    • 支撑能力
    • 调度中心
    • Agent 分工
    • 运行环境
    • 持久卷与 RSI
    • 评审问题与讨论结论
  • 共用底座
    • 通用架构
    • Hermes Agent 方案
    • Hermes Agent 基础架构 V2
    • OpenMausBot 方案
  • 参考架构

    • 小鹏灵犀 · 静态架构(参考)
    • 土豆(@poteto)· Grok Bot 自动化开发流程
    • 微软人事智能体 · 分层架构(参考)
  • 数字员工选型报告
    • 数字员工目标静态架构
    • 数字员工目标静态架构v2
    • Hermes 会话机制
    • OpenMausBot 会话机制
  • 知识库选型研究
    • 知识库选型需求与评估 SOP
    • 知识库候选产品
    • 知识库逐项资料评分与代码证据
    • 知识库商业托管版横向评分
    • FastGPT 知识库增强源码与自研评估
  • 票据 OCR 选型(草稿)
    • OCR 云 API 产品评估与评分(草稿)
    • 票据 OCR 选型需求与评分口径(草稿)
    • 票据 OCR PoC 测试计划(待启动)
    • OCR 通用文档识别选型(维度二·草稿)
  • 财务工作流
  • 补充材料
    • 流程与组件说明
    • 简版流程图
    • 详细流程图
    • 记忆、技能与会话历史
    • Hermes 记忆与技能研究
    • Hermes 本机版本能力核验
    • Meegle 事件去重研究
    • 项目定位与设计边界
    • 交互架构图说明
    • 原报告导航说明

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")自行过滤。

通用结构中的关键字段(省略其他字段):

{
  "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]

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 监听事件 — 飞书项目开发者手册:配置流程、重点说明、稳定性说明、事件结构。
  • S2 兼容性说明与验签说明 — 飞书项目开发者手册:验签公式、示例代码与公网回调要求。
  • S3 Webhook 使用 — 飞书项目产品手册:自动化规则 Webhook 的格式、成功标准与重试机制,仅用于辨别不同协议。
  • S4 Lark 官方 Node SDK:Subscribing to Events Using Long Connection Mode:WSClient、连接模式和注意事项;其引用的官方长连接文档。