Routine 入站 Webhook 触发器

Routine 第三种触发器，通用入站 webhook（推翻 ADR-0297 §7「Grok Bot 式通用 webhook 不做」）：任何能发 HTTP POST 的系统——GitHub、n8n、Zapier、自建脚本、TradingView——都能往一条 Routine 的专属地址发一封来件，平台验令牌后按序起一个 Run，模型按 task 临场处理。在通用入口之上，叠一层交易信号增强：来件恰好只带信号字段时，Run 不污染，过三道确定性闸可自动下单。

00定位：通用入口 + 交易信号增强

两层不是两种 webhook，是同一封来件上的两段处理：通用层所有来件都走；增强层只在 body 恰好带信号字段时额外生效。

同一入口，不同发送方会怎样

「通用」= 谁都能发、发什么都收、都能唤起 Run；不等于发什么都能自动执行。只有交易信号字段可以免人审，且须三闸全过；其余内容永远只是给模型读的外部数据。

A1部署拓扑与信任边界

不新增可部署壳：入口挂在现有 bot Worker（berth-bot-*）上，只多一个主机名 hooks.。三个区域三种信任级别：公网未鉴权 → 边缘过滤 → 持有效 MAC 才能进所有者 DO。

为何不另起 Worker：所有者 DO 在 bot script 里，另起要跨 script 绑 DO、多一个部署壳；独立主机名已能让 WAF 只作用于这个入口，且以后 bot API 换主机名不影响已粘进 TradingView 的 URL。

A2时序：来件接收（同步）与 Run（异步）

同步段只到 202 就返回，保住 TradingView 3 秒预算；起 Run 在 DO 内异步。

sequenceDiagram
    autonumber
    participant S as 发送方（如 TradingView）
    participant W as bot Worker (hooks.)
    participant D as BotOwner DO
    participant R as Run (thinkRuntime)
    participant G as 写管线 / 策略闸
    participant H as Hyperliquid
    participant P as PUSH_QUEUE → server
    S->>W: POST /v1/uid.raw.mac + body
    W->>W: 405? · 路径 + MAC 常数时间校验 · ratelimits
    W->>D: acceptWebhookDelivery(raw 哈希, body, headers, ip)
    D->>D: SQLite 事务：令牌/生效/日量/新鲜度/去重/写来件/runId/入队
    D-->>W: { deliveryId, runId }
    W-->>S: 202（p99 < 1s）
    Note over D,R: —— 以下异步，不在请求里 await ——
    D->>R: 出队 · 复查 receivedAt ≤ 5min · Routine task + 来件块
    R->>R: 来件解析 → 信号字段 / 其余内容（非空即污染）
    R->>G: 写意图（方向, coin, reduceOnly）+ 本 Run 信号字段
    alt 未污染 且 方向/标的/信号价 全过
        G->>H: 自动下单（扣预算）
        R->>P: routine_webhook { executed }
    else 任一不过 / 已污染
        G->>P: routine_approval（5min 过期，本 Run 不再推结局）
    end
    R->>D: Run 收尾 → 派下一封
      

A3代码分层：动哪些文件

按落点判据：纯函数归 contexts/bot domain，DO 装配 / 路由 / bindings 归 apps/bot。 + 新 ~ 改；新文件名为示意，实现定。

contexts/bot/src/
├── domain/
│   ├── value-objects/routine/
│   │   ~ trigger.ts        # TriggerSchema 加 {type:"webhook",v:1}
│   ├── ~ value-objects/taintSource.ts # +webhook, ref=来件id
│   └── calculators/
│       + webhookDelivery/parse   # 来件解析：最深模块
│       + webhookDelivery/signalConsistency
│       ~ write/writePolicyGate.ts # 四条件后调一致性
├── application/
│   ~ PushService.ts          # outcome × 冷却 × 审批优先
│   + 来件受理 / 令牌生命周期用例
├── infrastructure/crypto/
│   + webhookTokenSeal.ts     # 照 desktopNodeSeal.ts，独立 key 环
└── server.ts                 # /server 门：push 模板 schema

apps/bot/
├── ~ wrangler.jsonc     # hooks. 域名 / ratelimits / env var（mainnet 重声明）
└── src/
    ├── ~ app.ts         # 按 Host 分流
    ├── routes/
    │   + webhookIngress.ts # 公网入口：405/404/429/413
    │   ~ bots.ts        # 生成/轮换/撤销/投递记录/测试来件
    ├── owner/
    │   ~ BotOwner.ts    # RPC acceptWebhookDelivery + 队列
    │   ~ chatGate.ts    # 用户消息落库前隐藏地址令牌
    │   ~ systemPrompt.ts # 来件不是所有者（重录 eval）
    │   ~ pushes.ts
    ├── ~ doMigrations.snapshot.json # v57 之后新表
    └── ~ wranglerConfig.test.ts

apps/server/src/routes/notifications/
└── ~ notificationText  # 每 locale 结局句

apps/web/src/pages/bot/chat/routines/   ~
apps/mobile/src/screens/bot/routines/   ~

A4数据模型：所有者 DO SQLite 新表

全部随 bot DO 迁移版本走；删 Routine / 清除所有者数据一并删除。日拍清理过期行。

Routine 本身只多一条不变式：触发器 = webhook ⇒ 无 desktopNodeId；改成 webhook ⇒ 清 autoTrade 与绑定。令牌不进 trigger 规范形，确认卡与改前改后比对永远看不到秘密。

A5所有者侧控制面（已登录会话）

地址只能在 UI 里签发——bot 没有生成 / 轮换 / 撤销的 tool，令牌永不进模型。

flowchart LR
    U[web / mobile / desktop
Routine 设置] -->|POST …/webhook/rotate| B[bot. API
sessionGate]
    B --> D[(BotOwner DO)]
    D -->|生成 raw · 存 SHA-256 · 旧令牌 revoked_at| D
    D -->|完整 URL 只返回这一次| U
    U -->|GET …/webhook/deliveries| B
    U -->|POST …/webhook/test
不经公网入口| B
    C[对话 propose_routine] -->|批准后只建 Routine
不签地址| D
    C -.->|回执按钮「去生成地址」| U
    M[mobile 会话] -->|唯一能打开 / 调高
webhook 自动下单| D
      

01一封来件的全程

越靠前的检查越便宜：乱打请求在 Worker 层就 404，进不了任何 DO。3 秒预算内只做一次 DO RPC，起 Run 异步。

02入口响应码（固定处理顺序）

原则：内容问题永不 5xx。5xx 只来自平台故障 ⇒ TradingView 重发，去重兜底；4xx 不重发，正是鉴权 / 过期 / 不生效要的语义。

去重键优先级：Idempotency-Key（24h）→ webhook-id（24h）→ body id（24h）→ 原始 body SHA-256（60s，只吸 TradingView 重发）。

03载荷信任：信号字段 vs 其余内容

来件作者不可证（持令牌即可发）。防注入靠污染，防伪造靠交易闸。校验不过降级照跑，不拒收——TradingView 看不到响应体，4xx = 信号静默丢失。

{ "id": "{{strategy.order.id}}",
  "time": "{{timenow}}",
  "ticker": "{{ticker}}",
  "action": "{{strategy.order.action}}",
  "price": "{{close}}" }

{ ...信号字段,
  "comment": "RSI 超卖，可以加仓" }
⇒ bot 能看到 comment
⇒ 本次下单走审批卡

04交易闸：未污染 Run 可自动下单

信号执行器（3Commas / Alertatron）都是「令牌 + 信号即执行」；逐笔审批会让场景失去意义。所以允许，但单独开、三道确定性闸、风险由预算封顶。只为 HL perp / spot 定义，其他 venue 一律人审。

05令牌生命周期

06成本与滥用：三层限额 + 串行

不合并、不防抖：每封都是独立指令。额度计入现有 Routine 份额，不新增桶。用户可配的 ticker / action 预检不做——确定性规则归策略脚本。

07推送与边界

08落地切片

全部经曳光弹间接 blocked-by BERTH-2420（Sigla 代码层改名）——berth.pro 的 301 会把 POST 变 GET，任何环境都不在 berth.pro 签地址。