npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0-a - Mend

better-dsh 0.2.5 → 0.3.0-a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (999) hide show

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/messaging/webhooks.md DELETED Viewed

@@ -1,601 +0,0 @@
----
-sidebar_position: 13
-title: "Webhooks"
-description: "接收来自 GitHub、GitLab 等服务的事件以触发 Hermes agent 运行"
----
-# Webhooks
-接收来自外部服务（GitHub、GitLab、JIRA、Stripe 等）的事件，并自动触发 Hermes agent 运行。Webhook 适配器运行一个 HTTP 服务器，接受 POST 请求、验证 HMAC 签名、将 payload（载荷）转换为 agent prompt（提示词），并将响应路由回来源或其他已配置的平台。
-agent 处理事件后，可通过在 PR 上发布评论、向 Telegram/Discord 发送消息或记录结果来响应。
-## 视频教程
-<div style={{position: 'relative', width: '100%', aspectRatio: '16 / 9', marginBottom: '1.5rem'}}>
-  <iframe
-    src="https://www.youtube.com/embed/WNYe5mD4fY8"
-    title="Hermes Agent — Webhooks Tutorial"
-    style={{position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', border: 0}}
-    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-    allowFullScreen
-  />
-</div>
----
-## 快速开始
-1. 通过 `hermes gateway setup` 或环境变量启用
-2. 在 `config.yaml` 中定义路由，**或**使用 `hermes webhook subscribe` 动态创建
-3. 将你的服务指向 `http://your-server:8644/webhooks/<route-name>`
----
-## 设置
-有两种方式启用 webhook 适配器。
-### 通过设置向导
-```bash
-hermes gateway setup
-```
-按照提示启用 webhooks、设置端口和全局 HMAC secret。
-### 通过环境变量
-添加到 `~/.hermes/.env`：
-```bash
-WEBHOOK_ENABLED=true
-WEBHOOK_PORT=8644        # default
-WEBHOOK_SECRET=your-global-secret
-```
-### 验证服务器
-gateway 运行后：
-```bash
-curl http://localhost:8644/health
-```
-预期响应：
-```json
-{"status": "ok", "platform": "webhook"}
-```
----
-## 配置路由 {#configuring-routes}
-路由定义了不同 webhook 来源的处理方式。每个路由是 `config.yaml` 中 `platforms.webhook.extra.routes` 下的一个命名条目。
-### 路由属性
-| 属性 | 是否必填 | 描述 |
-|----------|----------|-------------|
-| `events` | 否 | 要接受的事件类型列表（例如 `["pull_request"]`）。若为空，则接受所有事件。事件类型从 `X-GitHub-Event`、`X-GitLab-Event` 或 payload 中的 `event_type` 读取。 |
-| `secret` | **是** | 用于签名验证的 HMAC secret。若路由未设置，则回退到全局 `secret`。仅用于测试时可设为 `"INSECURE_NO_AUTH"`（跳过验证）。 |
-| `prompt` | 否 | 使用点号表示法访问 payload 字段的模板字符串（例如 `{pull_request.title}`）。若省略，则将完整 JSON payload 转储到 prompt 中。 |
-| `filters` | 否 | 声明式 payload 过滤器，在认证/请求体/事件过滤之后、agent 或直接投递之前求值。不匹配时返回 `{"status":"ignored","reason":"filter"}`（HTTP 200）。 |
-| `script` | 否 | 位于 `~/.hermes/scripts/` 下的过滤/转换脚本。webhook payload 以 JSON 形式通过 stdin 传入。stdout 为 JSON 对象时会在模板渲染前替换 payload；文本 stdout 以 `script_output` 形式暴露；空 stdout、`[SILENT]` 或非零退出码会忽略该 webhook。 |
-| `skills` | 否 | agent 运行时加载的 skill 名称列表。 |
-| `deliver` | 否 | 响应发送目标：`github_comment`、`telegram`、`discord`、`slack`、`signal`、`sms`、`whatsapp`、`matrix`、`mattermost`、`homeassistant`、`email`、`dingtalk`、`feishu`、`wecom`、`weixin`、`bluebubbles`、`qqbot`，或 `log`（默认）。 |
-| `deliver_extra` | 否 | 额外的投递配置——键取决于 `deliver` 类型（例如 `repo`、`pr_number`、`chat_id`）。值支持与 `prompt` 相同的 `{dot.notation}` 模板语法。 |
-| `deliver_only` | 否 | 若为 `true`，完全跳过 agent——渲染后的 `prompt` 模板直接作为消息体投递。零 LLM token 消耗，亚秒级投递。参见[直接投递模式](#direct-delivery-mode)了解使用场景。要求 `deliver` 为真实目标（非 `log`）。 |
-| `cron_job` | 否 | 每次事件触发一个已有的 cron 任务（按 ID 或名称），而不是启动新的 webhook agent 会话。渲染后的 `prompt` 作为单次运行的临时上下文；以任务自身的 prompt、skills、模型和投递设置为准。与 `deliver_only` 互斥。参见[事件触发的 Cron 任务](#event-triggered-cron-jobs)。 |
-### 完整示例
-```yaml
-platforms:
-  webhook:
-    enabled: true
-    extra:
-      port: 8644
-      secret: "global-fallback-secret"
-      routes:
-        github-pr:
-          events: ["pull_request"]
-          secret: "github-webhook-secret"
-          prompt: |
-            Review this pull request:
-            Repository: {repository.full_name}
-            PR #{number}: {pull_request.title}
-            Author: {pull_request.user.login}
-            URL: {pull_request.html_url}
-            Diff URL: {pull_request.diff_url}
-            Action: {action}
-          skills: ["github-code-review"]
-          deliver: "github_comment"
-          deliver_extra:
-            repo: "{repository.full_name}"
-            pr_number: "{number}"
-        deploy-notify:
-          events: ["push"]
-          secret: "deploy-secret"
-          prompt: "New push to {repository.full_name} branch {ref}: {head_commit.message}"
-          filters:
-            - field: "ref"
-              equals: "refs/heads/main"
-          deliver: "telegram"
-```
-### Payload 过滤器 {#payload-filters}
-当服务商发送宽泛的事件流、但只有部分 payload 应唤醒 agent 或触发 `deliver_only` 投递时，使用 `filters`。过滤器在签名验证、请求体解析和 `events` 之后运行，但在 prompt 渲染、幂等去重、agent 调度或直接投递之前运行。
-```yaml
-platforms:
-  webhook:
-    extra:
-      routes:
-        todoist:
-          events: ["item:updated"]
-          secret: "todoist-secret"
-          filters:
-            - field: "payload.labels"
-              contains: "hermes"
-            - any:
-                - field: "payload.priority"
-                  equals: 4
-                - field: "payload.project_id"
-                  in_file: "~/.hermes/data/todoist/watchlist.json"
-          prompt: "Todoist task changed: {payload.content}"
-```
-支持的操作符：
-- `exists: true|false`
-- `missing: true`
-- `equals` / `not_equals`
-- `contains` — 适用于字符串、列表和 dict 键
-- `in` — 内联列表
-- `in_file` — JSON 数组、JSON 对象（使用其键）或按行分隔的文本文件
-- `regex`
-- `all`、`any` 和 `not` 分组
-字段路径使用点号表示法。当存在顶层 `payload` 对象时，`payload.foo` 从中读取；对扁平 payload 则从 webhook 请求体根部读取。`event` / `event_type` 匹配解析出的事件类型，`headers.<Name>` 读取请求头。
-### 脚本过滤与转换 {#script-filters-and-transforms}
-当声明式过滤器不够用时，使用 `script`。脚本必须位于当前 profile 的 `~/.hermes/scripts/` 目录下；相对路径在该目录内解析，且禁止路径穿越到目录之外。`.sh` 和 `.bash` 脚本用 bash 运行，其他扩展名用当前 Python 解释器运行。
-路由 payload 以 JSON 形式发送到 stdin：
-```python
-# ~/.hermes/scripts/todoist-hermes-label.py
-import json
-import sys
-payload = json.load(sys.stdin)
-labels = payload.get("payload", {}).get("labels", [])
-if "hermes" not in labels:
-    print("[SILENT]")
-    raise SystemExit(0)
-payload["body"] = payload["payload"]["content"]
-print(json.dumps(payload))
-```
-脚本结果：
-- stdout 为 JSON 对象时，替换 `prompt` 和 `deliver_extra` 使用的 payload。
-- 非 JSON 文本 stdout 会以 `script_output` 字段加入 payload。
-- 空 stdout、精确的 `[SILENT]`、`{"__hermes_ignore__": true}`、超时、脚本缺失或非零退出码，均返回 HTTP 200 及 `{"status":"ignored","reason":"script"}`。
-### Prompt 模板
-Prompt 使用点号表示法访问 webhook payload 中的嵌套字段：
-- `{pull_request.title}` 解析为 `payload["pull_request"]["title"]`
-- `{repository.full_name}` 解析为 `payload["repository"]["full_name"]`
-- `{__raw__}` — 特殊 token，将**整个 payload** 以缩进 JSON 格式转储（截断至 4000 个字符）。适用于监控告警或通用 webhook，agent 需要完整上下文时使用。
-- 缺失的键保留为字面量 `{key}` 字符串（不报错）
-- 嵌套的 dict 和 list 会被 JSON 序列化并截断至 2000 个字符
-可以将 `{__raw__}` 与常规模板变量混合使用：
-```yaml
-prompt: "PR #{pull_request.number} by {pull_request.user.login}: {__raw__}"
-```
-若路由未配置 `prompt` 模板，则将整个 payload 以缩进 JSON 格式转储（截断至 4000 个字符）。
-`deliver_extra` 的值中同样支持点号表示法模板。
-### 论坛话题投递
-向 Telegram 投递 webhook 响应时，可通过在 `deliver_extra` 中包含 `message_thread_id`（或 `thread_id`）来指定特定论坛话题：
-```yaml
-webhooks:
-  routes:
-    alerts:
-      events: ["alert"]
-      prompt: "Alert: {__raw__}"
-      deliver: "telegram"
-      deliver_extra:
-        chat_id: "-1001234567890"
-        message_thread_id: "42"
-```
-若 `deliver_extra` 中未提供 `chat_id`，则回退到目标平台配置的主频道。
----
-## GitHub PR 审查（分步说明） {#github-pr-review}
-本演练将为每个 pull request 设置自动代码审查。
-### 1. 在 GitHub 中创建 webhook
-1. 进入你的仓库 → **Settings** → **Webhooks** → **Add webhook**
-2. 将 **Payload URL** 设为 `http://your-server:8644/webhooks/github-pr`
-3. 将 **Content type** 设为 `application/json`
-4. 将 **Secret** 设为与路由配置匹配的值（例如 `github-webhook-secret`）
-5. 在 **Which events?** 下，选择 **Let me select individual events** 并勾选 **Pull requests**
-6. 点击 **Add webhook**
-### 2. 添加路由配置
-按照上方示例，将 `github-pr` 路由添加到 `~/.hermes/config.yaml`。
-### 3. 确保 `gh` CLI 已认证
-`github_comment` 投递类型使用 GitHub CLI 发布评论：
-```bash
-gh auth login
-```
-### 4. 测试
-在仓库中打开一个 pull request。webhook 触发后，Hermes 处理事件并在 PR 上发布审查评论。
----
-## GitLab Webhook 设置 {#gitlab-webhook-setup}
-GitLab webhook 的工作方式类似，但使用不同的认证机制。GitLab 通过 `X-Gitlab-Token` 请求头以明文字符串匹配（非 HMAC）发送 secret。
-### 1. 在 GitLab 中创建 webhook
-1. 进入你的项目 → **Settings** → **Webhooks**
-2. 将 **URL** 设为 `http://your-server:8644/webhooks/gitlab-mr`
-3. 输入你的 **Secret token**
-4. 选择 **Merge request events**（以及其他你需要的事件）
-5. 点击 **Add webhook**
-### 2. 添加路由配置
-```yaml
-platforms:
-  webhook:
-    enabled: true
-    extra:
-      routes:
-        gitlab-mr:
-          events: ["merge_request"]
-          secret: "your-gitlab-secret-token"
-          prompt: |
-            Review this merge request:
-            Project: {project.path_with_namespace}
-            MR !{object_attributes.iid}: {object_attributes.title}
-            Author: {object_attributes.last_commit.author.name}
-            URL: {object_attributes.url}
-            Action: {object_attributes.action}
-          deliver: "log"
-```
----
-## 投递选项 {#delivery-options}
-`deliver` 字段控制 agent 处理 webhook 事件后响应的发送目标。
-| 投递类型 | 描述 |
-|-------------|-------------|
-| `log` | 将响应记录到 gateway 日志输出。这是默认值，适合测试使用。 |
-| `github_comment` | 通过 `gh` CLI 将响应作为 PR/issue 评论发布。需要 `deliver_extra.repo` 和 `deliver_extra.pr_number`。`gh` CLI 必须安装并在 gateway 主机上完成认证（`gh auth login`）。 |
-| `telegram` | 将响应路由到 Telegram。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `discord` | 将响应路由到 Discord。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `slack` | 将响应路由到 Slack。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `signal` | 将响应路由到 Signal。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `sms` | 通过 Twilio 将响应路由到 SMS。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `whatsapp` | 将响应路由到 WhatsApp。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `matrix` | 将响应路由到 Matrix。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `mattermost` | 将响应路由到 Mattermost。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `homeassistant` | 将响应路由到 Home Assistant。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `email` | 将响应路由到 Email。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `dingtalk` | 将响应路由到 DingTalk。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `feishu` | 将响应路由到 Feishu/Lark。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `wecom` | 将响应路由到 WeCom。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `weixin` | 将响应路由到 Weixin（微信）。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-| `bluebubbles` | 将响应路由到 BlueBubbles（iMessage）。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。 |
-跨平台投递时，目标平台也必须在 gateway 中启用并连接。若 `deliver_extra` 中未提供 `chat_id`，响应将发送到该平台配置的主频道。
----
-## 直接投递模式 {#direct-delivery-mode}
-默认情况下，每次 webhook POST 都会触发一次 agent 运行——payload 成为 prompt，agent 处理后投递响应。这会在每次事件时消耗 LLM token。
-对于只需**推送纯文本通知**的场景——无需推理、无需 agent 循环，只需投递消息——可在路由上设置 `deliver_only: true`。渲染后的 `prompt` 模板直接作为消息体，适配器将其直接分发到配置的投递目标。
-### 何时使用直接投递
-- **外部服务推送** — Supabase/Firebase webhook 在数据库变更时触发 → 即时通知 Telegram 用户
-- **监控告警** — Datadog/Grafana 告警 webhook → 推送到 Discord 频道
-- **agent 间通知** — Agent A 通知 Agent B 的用户某个长时任务已完成
-- **后台任务完成** — Cron 任务完成 → 将结果发布到 Slack
-优势：
-- **零 LLM token** — agent 从不被调用
-- **亚秒级投递** — 单次适配器调用，无推理循环
-- **与 agent 模式相同的安全性** — HMAC 认证、速率限制、幂等性和请求体大小限制均正常生效
-- **同步响应** — 投递成功后 POST 返回 `200 OK`，若目标拒绝则返回 `502`，便于上游服务智能重试
-### 示例：从 Supabase 推送到 Telegram
-```yaml
-platforms:
-  webhook:
-    enabled: true
-    extra:
-      port: 8644
-      secret: "global-secret"
-      routes:
-        antenna-matches:
-          secret: "antenna-webhook-secret"
-          deliver: "telegram"
-          deliver_only: true
-          prompt: "🎉 New match: {match.user_name} matched with you!"
-          deliver_extra:
-            chat_id: "{match.telegram_chat_id}"
-```
-你的 Supabase edge function 使用 HMAC-SHA256 对 payload 签名并 POST 到 `https://your-server:8644/webhooks/antenna-matches`。webhook 适配器验证签名、从 payload 渲染模板、投递到 Telegram，并返回 `200 OK`。
-### 示例：通过 CLI 动态订阅
-```bash
-hermes webhook subscribe antenna-matches \
-  --deliver telegram \
-  --deliver-chat-id "123456789" \
-  --deliver-only \
-  --prompt "🎉 New match: {match.user_name} matched with you!" \
-  --description "Antenna match notifications"
-```
-### 响应状态码
-| 状态码 | 含义 |
-|--------|---------|
-| `200 OK` | 投递成功。响应体：`{"status": "delivered", "route": "...", "target": "...", "delivery_id": "..."}` |
-| `200 OK`（status=duplicate） | 在幂等性 TTL（1 小时）内重复的 `X-GitHub-Delivery` ID。不重复投递。 |
-| `401 Unauthorized` | HMAC 签名无效或缺失。 |
-| `400 Bad Request` | JSON 请求体格式错误。 |
-| `404 Not Found` | 未知路由名称。 |
-| `413 Payload Too Large` | 请求体超过 `max_body_bytes`。 |
-| `429 Too Many Requests` | 路由速率限制已超出。 |
-| `502 Bad Gateway` | 目标适配器拒绝消息或抛出异常。错误记录在服务端日志中；响应体为通用的 `Delivery failed`，避免泄露适配器内部信息。 |
-### 配置注意事项
-- `deliver_only: true` 要求 `deliver` 为真实目标。`deliver: log`（或省略 `deliver`）在启动时会被拒绝——适配器发现路由配置错误时拒绝启动。
-- 直接投递模式下 `skills` 字段被忽略（不运行 agent，无处注入 skill）。
-- 模板渲染使用与 agent 模式相同的 `{dot.notation}` 语法，包括 `{__raw__}` token。
-- 幂等性使用相同的 `X-GitHub-Delivery` / `X-Request-ID` 请求头——携带相同 ID 的重试返回 `status=duplicate` 且**不**重复投递。
----
-## 事件触发的 Cron 任务 {#event-triggered-cron-jobs}
-在路由上设置 `cron_job`，即可在事件到达时触发一个**已有的 cron 任务**——无需按固定周期轮询，也不会启动新的 webhook agent 会话。这让任何定时任务都能变成事件驱动的任务：把原有的定时计划保留为兜底扫描（或设为低频），让 webhook 在事情真正发生的那一刻立即触发它。
-工作原理：
-1. 事件经过与其他路由相同的 HMAC 认证、速率限制、`events`/`filters`/`script` 过滤和幂等去重。
-2. 路由的 `prompt` 模板根据 payload 渲染后，作为**单次运行的临时上下文**注入任务（与 `cronjob(action='run', prompt=...)` 走同一条通道——任务存储的 prompt 永远不会被修改）。
-3. 任务通过与调度器相同的 at-most-once 认领机制触发，因此 webhook 突发流量不会重复触发正在运行的任务，任务自身的投递目标会收到输出。
-### 示例：在收到 review 反馈时触发 PR 审查任务
-```yaml
-platforms:
-  webhook:
-    enabled: true
-    extra:
-      routes:
-        pr-feedback:
-          events: ["pull_request_review"]
-          secret: "github-webhook-secret"
-          cron_job: "pr-review-sweeper"        # 已有任务的 ID 或名称
-          prompt: |
-            {repository.full_name} 的 PR #{number} 收到了来自
-            {review.user.login} 的新审查反馈：{review.body}
-```
-### 通过 CLI
-```bash
-hermes webhook subscribe pr-feedback \
-  --events "pull_request_review" \
-  --cron-job "pr-review-sweeper" \
-  --prompt "PR #{number} 收到反馈：{review.body}"
-```
-创建订阅时会立即校验任务引用，拼写错误会当场报错。
-### 注意事项
-- `cron_job` 与 `deliver_only` 互斥（路由同时设置两者时适配器拒绝启动）。cron 任务自行处理投递。
-- `cron_job` 路由会忽略路由级的 `deliver`、`deliver_extra` 和 `skills` 字段——以任务自身的设置为准。
-- 已暂停/已禁用的任务不会被触发；事件会被记录并丢弃。
-- POST 立即返回 `202 Accepted`；任务在后台运行。
----
-## 动态订阅（CLI） {#dynamic-subscriptions}
-除了 `config.yaml` 中的静态路由，还可以使用 `hermes webhook` CLI 命令动态创建 webhook 订阅。当 agent 本身需要设置事件驱动触发器时，这尤为有用。
-### 创建订阅
-```bash
-hermes webhook subscribe github-issues \
-  --events "issues" \
-  --prompt "New issue #{issue.number}: {issue.title}\nBy: {issue.user.login}\n\n{issue.body}" \
-  --deliver telegram \
-  --deliver-chat-id "-100123456789" \
-  --description "Triage new GitHub issues"
-```
-此命令返回 webhook URL 和自动生成的 HMAC secret。将你的服务配置为 POST 到该 URL。
-### 列出订阅
-```bash
-hermes webhook list
-```
-### 删除订阅
-```bash
-hermes webhook remove github-issues
-```
-### 测试订阅
-```bash
-hermes webhook test github-issues
-hermes webhook test github-issues --payload '{"issue": {"number": 42, "title": "Test"}}'
-```
-### 动态订阅的工作原理
-- 订阅存储在 `~/.hermes/webhook_subscriptions.json`
-- webhook 适配器在每次收到请求时热重载该文件（基于 mtime 检测，开销可忽略不计）
-- `config.yaml` 中的静态路由始终优先于同名的动态订阅
-- 动态订阅与静态路由使用相同的格式和功能（events、prompt 模板、skills、delivery）
-- 无需重启 gateway——订阅后立即生效
-### agent 驱动的订阅
-agent 可通过 terminal 工具在 `webhook-subscriptions` skill 的引导下创建订阅。向 agent 请求"为 GitHub issues 设置 webhook"，它将运行相应的 `hermes webhook subscribe` 命令。
----
-## 安全性 {#security}
-webhook 适配器包含多层安全机制：
-### HMAC 签名验证
-适配器使用适合各来源的方式验证传入的 webhook 签名：
-- **GitHub**：`X-Hub-Signature-256` 请求头——以 `sha256=` 为前缀的 HMAC-SHA256 十六进制摘要
-- **GitLab**：`X-Gitlab-Token` 请求头——明文 secret 字符串匹配
-- **通用**：`X-Webhook-Signature` 请求头——原始 HMAC-SHA256 十六进制摘要
-若已配置 secret 但请求中不存在已识别的签名请求头，则请求被拒绝。
-### Secret 为必填项
-每个路由必须有 secret——直接设置在路由上或从全局 `secret` 继承。没有 secret 的路由会导致适配器在启动时报错退出。仅用于开发/测试时，可将 secret 设为 `"INSECURE_NO_AUTH"` 以完全跳过验证。
-`INSECURE_NO_AUTH` 仅在 gateway 绑定到回环地址（`127.0.0.1`、`localhost`、`::1`）时被接受。若与非回环绑定（如 `0.0.0.0` 或局域网 IP）组合使用，适配器拒绝启动——这可防止在公共接口上意外暴露未认证的端点。
-### 速率限制
-每个路由默认限制为**每分钟 30 次请求**（固定窗口）。可全局配置：
-```yaml
-platforms:
-  webhook:
-    extra:
-      rate_limit: 60  # requests per minute
-```
-超出限制的请求收到 `429 Too Many Requests` 响应。
-### 幂等性
-投递 ID（来自 `X-GitHub-Delivery`、`X-Request-ID` 或时间戳回退）缓存 **1 小时**。重复投递（例如 webhook 重试）会被静默跳过并返回 `200` 响应，防止重复触发 agent 运行。
-### 请求体大小限制
-超过 **1 MB** 的 payload 在读取请求体之前即被拒绝。可配置：
-```yaml
-platforms:
-  webhook:
-    extra:
-      max_body_bytes: 2097152  # 2 MB
-```
-### Prompt 注入风险
-:::warning
-Webhook payload 包含攻击者可控的数据——PR 标题、commit 消息、issue 描述等均可能包含恶意指令。在暴露于互联网时，请在沙箱环境（Docker、VM）中运行 gateway。考虑使用 Docker 或 SSH terminal 后端进行隔离。
-:::
----
-## 故障排查 {#troubleshooting}
-### Webhook 未到达
-- 验证端口已暴露且可从 webhook 来源访问
-- 检查防火墙规则——端口 `8644`（或你配置的端口）必须开放
-- 验证 URL 路径是否匹配：`http://your-server:8644/webhooks/<route-name>`
-- 使用 `/health` 端点确认服务器正在运行
-### 签名验证失败
-- 确保路由配置中的 secret 与 webhook 来源中配置的 secret 完全一致
-- 对于 GitHub，secret 基于 HMAC——检查 `X-Hub-Signature-256`
-- 对于 GitLab，secret 为明文 token 匹配——检查 `X-Gitlab-Token`
-- 检查 gateway 日志中的 `Invalid signature` 警告
-### 事件被忽略
-- 检查事件类型是否在路由的 `events` 列表中
-- GitHub 事件使用如 `pull_request`、`push`、`issues` 等值（`X-GitHub-Event` 请求头的值）
-- GitLab 事件使用如 `merge_request`、`push` 等值（`X-GitLab-Event` 请求头的值）
-- 若 `events` 为空或未设置，则接受所有事件
-### Agent 未响应
-- 在前台运行 gateway 以查看日志：`hermes gateway run`
-- 检查 prompt 模板是否正确渲染
-- 验证投递目标已配置并连接
-### 重复响应
-- 幂等性缓存应能防止此问题——检查 webhook 来源是否发送了投递 ID 请求头（`X-GitHub-Delivery` 或 `X-Request-ID`）
-- 投递 ID 缓存 1 小时
-### `gh` CLI 错误（GitHub 评论投递）
-- 在 gateway 主机上运行 `gh auth login`
-- 确保已认证的 GitHub 用户对该仓库有写权限
-- 检查 `gh` 是否已安装并在 PATH 中
----
-## 环境变量 {#environment-variables}
-| 变量 | 描述 | 默认值 |
-|----------|-------------|---------|
-| `WEBHOOK_ENABLED` | 启用 webhook 平台适配器 | `false` |
-| `WEBHOOK_PORT` | 接收 webhook 的 HTTP 服务器端口 | `8644` |
-| `WEBHOOK_SECRET` | 全局 HMAC secret（路由未指定自身 secret 时作为回退） | _（无）_ |