安装与配置

@hasheeai/agent-sdk-ts 是 Hashee 官方的 TypeScript Agent SDK，封装了 6 层 E2EE 加密栈、三种连接模式、artifact 协议、capability manifest 注册、 tool call 双向流程。本页只讲怎么把它装好；具体用法在后面分章节展开。

系统要求

项	最低版本	推荐版本
Node.js	22.0	22 LTS
TypeScript	5.7	5.7+
包管理器	npm 10 / pnpm 9 / yarn 4	pnpm 9
平台	macOS / Linux / Windows / WSL2	Linux 服务器（生产）

不支持的 runtime：Node.js < 22（缺 crypto.subtle X25519）、Bun（Web Crypto 实现不完整， PR 跟进中）、Deno（KV Type 异）、浏览器（架构上不允许 Agent 跑在客户端）。

安装

npm public（V1.x 之后）

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

GitHub Packages（V1 内测期）

V1 内测期间 SDK 通过 GitHub Packages 私有 registry 分发。你需要：

申请加入 Hashee 开发者计划（V1 invite-only）。
收到通过邮件后，去 GitHub Settings → Developer settings → Personal access tokens → Generate token (classic)，只勾选 read:packages。
在你的项目根新建 .npmrc：

@hasheeai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

设置环境变量 GITHUB_TOKEN=ghp_...（建议用 direnv / dotenv）。
pnpm add @hasheeai/agent-sdk-ts —— 现在能装到。

CLI 工具（可选）

npm install -g @hasheeai/cli
hashee --version

详见 CLI 安装与认证。

TypeScript 工程结构推荐

my-agent/
├── src/
│   ├── index.ts            # entry：HasheeAgent.init + handler 注册
│   ├── handlers/           # 各类消息处理函数
│   │   ├── text.ts
│   │   ├── artifact.ts
│   │   └── tool-response.ts
│   ├── tools/              # tool 实现
│   ├── llm.ts              # 你的大模型适配
│   ├── persistence.ts      # 业务侧持久化
│   └── env.ts              # 环境变量验证
├── .env.example            # commit 进 git，不含实际值
├── .env                    # gitignored
├── .npmrc                  # 仅 GitHub Packages 时需要
├── tsconfig.json
├── package.json
└── README.md

tsconfig.json 最小可工作配置：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src",
    "resolveJsonModule": true
  },
  "include": ["src/**/*"]
}

package.json 关键字段：

{
  "name": "my-agent",
  "version": "0.1.0",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "dev": "tsx --env-file=.env src/index.ts",
    "build": "tsc",
    "start": "node --env-file=.env dist/index.js"
  },
  "dependencies": {
    "@hasheeai/agent-sdk-ts": "^0.2.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "tsx": "^4.20.0",
    "typescript": "^5.7.0"
  }
}

环境变量约定

SDK 不强制读环境变量（你显式传字符串给 HasheeAgent.init），但社区约定如下变量名，方便配合 PaaS / IaC：

变量	用途
`HASHEE_AGENT_ID`	Agent UUID
`HASHEE_AGENT_TOKEN`	`hsk_...` token
`HASHEE_BASE_URL`	默认 `https://api.hashee.ai`；staging 用 `https://staging-api.hashee.ai`
`HASHEE_CONNECTION_MODE`	`websocket` (默认) / `webhook` / `polling`
`HASHEE_X25519_PRIVATE_BASE64`	持久化的 wrap 私钥（base64）
`HASHEE_ED25519_PRIVATE_BASE64`	持久化的 sign 私钥（base64）
`HASHEE_WEBHOOK_SECRET`	Webhook 模式的共享 HMAC 密钥

模板 .env.example（commit 进 git）：

# 从 Hashee app 通过 System Agent Hashee 创建 Agent 后获得
HASHEE_AGENT_ID=
HASHEE_AGENT_TOKEN=

# 留空使用 SDK 默认（自动生成密钥并通过 onKeyGenerated 回传）
HASHEE_X25519_PRIVATE_BASE64=
HASHEE_ED25519_PRIVATE_BASE64=

# 默认 https://api.hashee.ai
HASHEE_BASE_URL=https://api.hashee.ai

# 默认 websocket；webhook 模式补充 HASHEE_WEBHOOK_SECRET
HASHEE_CONNECTION_MODE=websocket
HASHEE_WEBHOOK_SECRET=

在 Cloudflare Workers / Lambda 中

云函数运行时无法长持私钥到 disk，必须把 base64 私钥放进 Secret 资源：

# Cloudflare Workers
wrangler secret put HASHEE_AGENT_TOKEN
wrangler secret put HASHEE_X25519_PRIVATE_BASE64
wrangler secret put HASHEE_ED25519_PRIVATE_BASE64
wrangler secret put HASHEE_WEBHOOK_SECRET

# AWS Lambda（用 SAM / CDK）
# Environment.Variables.HASHEE_AGENT_TOKEN = SecureString

详见部署到 Cloudflare Workers。

验证安装

写个最小验证脚本 verify.ts：

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

console.log("SDK loaded:", typeof HasheeAgent);
console.log("Required env present:", {
  agent_id: !!process.env.HASHEE_AGENT_ID,
  agent_token: !!process.env.HASHEE_AGENT_TOKEN,
});

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

console.log("Connected:", agent);
process.exit(0);

跑：

tsx --env-file=.env verify.ts

预期输出：

SDK loaded: function
Required env present: { agent_id: true, agent_token: true }
Connected: HasheeAgent { agentId: '01906abc-...', status: 'connected' }

如果看到错误：

错误	原因	修
`ECONNREFUSED`	`HASHEE_BASE_URL` 拼错	看默认值
`401 AGENT_TOKEN_INVALID`	Token 错或被旋转	用 System Agent 重新生成
`404 AGENT_NOT_REGISTERED`	`HASHEE_AGENT_ID` 拼错	比对
`409 AGENT_KEYS_MISMATCH`	本地私钥 vs 后端公钥不匹配	删除本地 keystore 让 SDK 重生成 + 重注册
`TypeError: crypto.subtle.X25519`	Node < 22	升级到 22