三种部署模式如何选

Hashee SDK 支持三种 Agent 连接模式，对应三种典型的运行环境。每种模式的安全边界、延迟特征、运维成本都不同——选对了能省一半工作量。

一句话总览

模式	进程形态	E2EE 层数	适合
WebSocket	长驻进程 / 容器 / VM	6 层完整栈（含 Ratchet）	自建后端、有持久化状态、需要前向保密
Webhook	无状态函数 / 边缘函数	Layer 1-3（无 Ratchet）	Cloudflare Workers / Vercel Edge / Lambda
Polling	兜底 fallback	6 层完整栈	限制网络出栈连接的环境（公司内网、某些 CI）

WebSocket 模式（默认推荐）

const agent = await HasheeAgent.init({
  agentId, token,
  baseUrl: "https://api.hashee.ai",
  connectionMode: "websocket",  // 默认
});

特征：

SDK 维持一条到 wss://api.hashee.ai/ws/agent/... 的长连接，30 秒一次心跳。
消息延迟稳定在数十毫秒级。
完整 E2EE 6 层栈，包括 Layer 4 Double Ratchet 提供的前向保密 + 后向保密。
同 Agent 最多 3 个并发 WebSocket 连接（横向扩容）。

适合：

自托管的 Node.js / Deno / Bun 后端
容器化（Kubernetes / Cloud Run）
需要保留状态（会话记忆、向量库、本地缓存）
群聊场景（多 conversation 同时在线）

不适合：

函数式（FaaS）部署——冷启动会断开连接
间歇性运行的本地脚本

Webhook 模式（无状态）

import { createWebhookDispatcher } from "@hasheeai/agent-sdk-ts";

const dispatcher = createWebhookDispatcher({
  secret: process.env.HASHEE_WEBHOOK_SECRET!,
  onMessage: async (msg) => {
    // msg 已自动解密
  },
});

// 在你的 Hono / Express / Workers handler 里
app.post("/webhook", async (req) => {
  await dispatcher.handle(req.headers, await req.text());
  return new Response("ok");
});

特征：

后端通过 HTTP POST 把消息推到你预先注册的 webhook_url。
跳过 Layer 4 Double Ratchet（无状态环境无法维护 ratchet state）；保留 Layer 1-3 提供的内容加密 + per-recipient wrap + 签名。
HMAC-SHA256 签名验证（X-Hashee-Signature）+ ±5 分钟时间戳窗口防重放。
单条 payload 硬上限 1 MB，超过部分自动走 R2 对象引用。
HTTP 响应 deadline 10 秒，超时算失败，触发重试。
重试策略：7 次指数退避，到达上限后 Agent 进入 unreachable 状态机。

适合：

Cloudflare Workers / Vercel Edge Functions / AWS Lambda / Google Cloud Functions
公网可达的 serverless 后端
不需要主动推送（只需要被动回复）

不适合：

需要 Agent 主动给用户发消息（webhook 是请求驱动；主动推送也可以但需要持有 token 调 REST）
需要长任务（超过 10 秒处理就要异步化 + 用 agent.send() 异步回写）

详见 Webhook 投递规范。

Polling 模式（兜底）

const agent = await HasheeAgent.init({
  agentId, token,
  baseUrl: "https://api.hashee.ai",
  connectionMode: "polling",
});

特征：

SDK 周期性 HTTP GET /agents/:id/messages?since=<cursor>。
完整 E2EE 6 层栈（与 WebSocket 一致）。
延迟取决于轮询间隔（默认 5s）。

适合：

出站只允许 HTTPS 的环境（部分企业内网）
临时调试 / 低频运行的脚本
网络对长连接有限制的 CI runner

不适合：

任何对实时性敏感的场景
高消息量（轮询请求数会随 conversation 数线性增长）

决策树

          ┌─ 长驻服务（VM / 容器 / k8s）？
          │   └─ 需要前向保密 / 群聊 / 多会话？
          │      └─ ✓ → WebSocket
          │
开始 ─────┤
          │
          ├─ 函数式（Workers / Lambda / Vercel Edge）？
          │   └─ 单条响应 ≤ 10s 内能完？
          │      └─ ✓ → Webhook
          │      └─ ✗ → 异步化（用 Webhook 接收 + 用 agent.send 异步回写）
          │
          └─ 长连接被防火墙阻挡 / WebSocket 不可用？
              └─ → Polling（兜底）

切换模式的代价

模式由 服务端注册时 + SDK 客户端启动时 双向声明。切换：

在 Hashee app 里给 System Agent 发：修改我的 Agent <name> 的连接模式为 webhook
平台会问你 webhook_url 与 webhook_secret
重启你的 Agent 进程使用新的 connectionMode

切换不会丢消息——平台会把切换前未投递的消息按新模式重新尝试投递。

切换会改变 E2EE 边界（Webhook 模式没有 Ratchet）。如果你是高敏感场景（医疗、金融），推荐保持 WebSocket。

常见问题

Q: WebSocket 模式下进程重启会丢消息吗？ 不会。平台为每个 Agent 维护投递游标（cursor），重连后从游标续传。

Q: Webhook 模式可以主动推送吗？ 可以——只是不通过 webhook 通道。在你的函数里调用 SDK 的 REST helper：

import { restRequest } from "@hasheeai/agent-sdk-ts";

await restRequest("POST", `/agents/${AGENT_ID}/messages`, {
  conversation_id, payload: { type: "text", text: "提醒：你的部署完成了" }
}, { token });

Q: 同一 Agent 能同时 WebSocket + Webhook 吗？ 不能。一个 Agent 只能注册一种 connection_mode。如果你需要”既能被推也能主动推”，用 WebSocket。