mcpField
W
webhook-transforms

webhook-transforms

github.com/garrytan数据与数据库31.3k237 次安装今天更新
代码仓库

关于 webhook-transforms

将传入的 webhook 事件转换为带引用的 brain 页面。它会清理输入、提取实体，并保存转换失败的原始载荷以供重试。

主要功能

  1. 01转换 webhook 载荷
  2. 02清理 HTML 与脚本内容
  3. 03提取实体并进行丰富处理
  4. 04死信记录并重试一次

适用场景

  1. 01将收到的 SMS 写入 brain 页面
  2. 02记录社交提及并建立实体关联
  3. 03将已完成会议转交摄取流程

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/garrytan/gbrain --skill webhook-transforms

安装后在 Claude Code 中输入/webhook-transforms确认已加载。

详细介绍

Webhook 转换

约定

本技能保证：

  • 外部事件会被转换为带有正确引用的大脑页面
  • 原始负载会被保留（转换失败时进入死信队列）
  • 每个转换后的事件都会运行实体提取
  • 输入净化：原始 HTML/脚本不会进入大脑页面
  • 错误处理：转换失败时记录原始负载，并重试一次

阶段

  1. 定义转换。 将事件结构映射为大脑页面格式：

    • 输入：原始 webhook 负载（JSON）
    • 输出：大脑页面内容（Markdown）+ 元数据（slug、类型、引用）
    • 必须净化：去除 HTML 标签，转义脚本内容

  2. 注册 webhook URL。 向外部服务提供 webhook 端点。

  3. 收到事件时：

    • 解析负载
    • 运行转换函数
    • 通过 gbrain put 写入大脑页面
    • 提取实体，运行富化
    • 为被提及的实体添加时间线条目
    • 同步：gbrain sync

  4. 错误处理：

    • 如果转换抛出异常：将原始负载记录到 _dead-letter/{timestamp}.md
    • 向 Agent 报告错误类型
    • 重试一次
    • 不要丢失事件

转换示例

收到短信
Input: {from: "+1555...", body: "Meeting moved to 3pm", timestamp: "..."}
Output: Timeline entry on sender's brain page + task update if action item detected
会议完成
Input: {title: "Weekly sync", attendees: [...], transcript: "...", summary: "..."}
Output: Delegate to meeting-ingestion skill
社交媒体提及
Input: {platform: "twitter", author: "@handle", text: "...", url: "..."}
Output: Brain page in media/ + entity extraction + backlinks

输出格式

事件已转换并写入大脑。报告格式："Webhook: {event_type} from {source} → {brain_page_path}"

失败时的处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或提示块，请遵循Agent 操作员协议。本技能的具体要求如下：

  • 转换后的写入返回 write_pending（退出码 10）：事件已被接收；记录请求 ID 并轮询该请求，切勿以新 ID 重放事件。
  • source_binding_required / insufficient_scope：该 webhook 的令牌无法写入该来源；告知用户大脑主机的操作员需要添加哪项授权。
  • 负载格式错误：拒绝该负载并返回解析错误，同时记录日志；不要写入不完整的页面。

反模式

  • 将原始 HTML/脚本传入大脑页面（XSS 风险）
  • 转换失败时静默丢弃事件（应使用死信队列）
  • 处理 webhook 时不进行实体提取
  • 写入大脑前不净化外部输入

评论

支持 Markdown