SDK 章节首页

@hasheeai/agent-sdk-ts 是 Hashee 官方 TypeScript Agent SDK——封装了 6 层 E2EE 加密栈、三种连接模式、artifact 协议、capability manifest 注册、tool call 双向流程、文件上传、群聊。本页是 SDK 章节的总入口和地图，带你用最少时间找到自己需要的那一页。

30 秒选路径

我想…	去这里
5 分钟跑通第一个 Agent	开发者章节 — 5 分钟创建第一个 Agent
在 VPS / 容器跑长驻 Agent	Hello World — WebSocket 模式
在 Cloudflare Workers / Lambda 跑无状态 Agent	Hello World — Webhook 模式
选连接模式	开发者章节 — 三种部署模式如何选
处理收到的消息	接收消息
发回复 / typing / Markdown	发送回复
LLM 流式输出	流式传输
上传 / 下载文件	文件上传
发结构化卡片	Artifact 入门
做”小程序”或”小游戏”	Artifact 高级 — 双向交互
让 Agent 调用客户端工具	Tool Call
处理群聊消息	群组消息处理
错误恢复 / 重连 / 幂等	错误处理
理解加密边界与私钥安全	安全与加密边界
申请用户数据访问	数据授权 (Data Grants)
看 Webhook 协议字段全表	Webhook 协议参考
看 SDK 版本历史 / 升级	SDK 变更日志

安装

npm install @hasheeai/agent-sdk-ts
# 或
pnpm add @hasheeai/agent-sdk-ts

V1 内测期通过 GitHub Packages 私有 registry 分发，详见安装与配置。

最小可工作 Agent

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

const agent = await HasheeAgent.init({
  agentId: process.env.HASHEE_AGENT_ID!,
  token: process.env.HASHEE_AGENT_TOKEN!,
  baseUrl: "https://api.hashee.ai",
  connectionMode: "websocket",
});

agent.addMessageHandler(async (msg) => {
  if (msg.payload?.type !== "text") return;
  await agent.typing(msg.conversation_id);
  await agent.send(msg.conversation_id, {
    type: "text",
    text: `Echo: ${msg.payload.text}`,
  });
});

agent.addStatusHandler((s) => console.log("status:", s));
console.log("waiting for messages...");

跑通后看发送回复把 echo 替换成真业务。

SDK 关键导出（一览）

类别	导出
主类	`HasheeAgent`
Webhook 模式	`createWebhookDispatcher`, `verifyWebhookSignature`, `parseWebhookPayload`
REST 直调	`restRequest`, `restUploadBinary`
加密原语 (L1-L3)	`generateCek`, `encryptContent` / `decryptContent`, `wrapCek` / `unwrapCek`, `signEnvelope` / `verifyEnvelope`
群组加密	`generateGroupKey`, `encryptGroupMessage`, `decryptGroupMessage`
身份密钥	`generateIdentityX25519`, `generateIdentityEd25519`, `importX25519PrivateKey`, `importEd25519PrivateKey`
Artifact / Tool 契约	`buildArtifactRequest`, `buildArtifactResponseRef`, `validateArtifactInteractionRequest`, `ARTIFACT_RESPONSE_STATUS`, `ARTIFACT_RESPONSE_REASON`
Capability Manifest	`CHANNEL_CAPABILITY_MATRIX`, `getPluginCapabilityMatrix`
流式	`createStreamSession`
Wire envelope	`encodeWireEnvelope`, `decodeWireEnvelope`, `findWrapForRecipient`, `HASHEE_ENVELOPE_V1_2`

绝大多数情况下你只用 HasheeAgent + createWebhookDispatcher，其它是非标准场景才用。

三种连接模式速读

模式	进程形态	E2EE 层数	适合
`websocket`（默认）	长驻进程 / 容器	6 层（含 Ratchet）	VPS, 容器, K8s
`webhook`	无状态函数	Layer 1-3	Workers, Lambda, Edge
`polling`	fallback	6 层	出站受限的环境

详见三种部署模式如何选。

章节地图

SDK
├── installation-and-config        安装与配置
├── getting-started (你在这里)      章节首页
├── hello-world-websocket          WS Hello World 详细
├── hello-world-webhook            Webhook Hello World 详细
├── messages                       接收消息（全消息类型）
├── send-replies                   发送回复（text/typing/Markdown/mention/reply-to）
├── streaming                      流式输出（StreamSession API）
├── files                          文件上传与下载
├── artifacts                      Artifact 入门（subtype 列表）
├── artifacts-advanced             Artifact 高级（双向交互、revision）
├── tool-call                      Tool Call (Capability Manifest)
├── groups                         群组消息处理
├── webhooks                       Webhook 协议参考（HMAC + R2 + 重试）
├── data-grants                    数据授权
├── error-handling                 错误处理 / 重连 / 幂等
└── security-boundaries            安全与加密边界

如果你准备从头通读，建议顺序： installation → hello-world (任选其一) → send-replies → messages → artifacts → tool-call → error-handling → security-boundaries。