核心功能
@inferencesh/sdk 是 inference.sh 平台的官方 JavaScript/TypeScript SDK，专为 Node.js 和现代浏览器环境设计。核心能力包括：
1. 多模型推理执行
- 支持 150+ 预置 AI 应用（Flux 图像生成、Veo 视频、Claude/GPT 系列等）
- 同步/异步执行模式（
wait: false实现 Fire-and-Forget） - 实时流式输出（SSE 进度追踪）
2. 智能体（Agent）构建
- 模板模式：直接调用工作区预置智能体
- 临时模式：程序化构建自定义 Agent，支持 Claude Sonnet 4、GPT-4o 等核心模型
- 内置工具系统：客户端工具、应用工具（调用其他 AI 应用）、子智能体委派、Webhook 集成
3. 高级特性
- 有状态会话（Sessions）：保持工作进程温热，降低冷启动延迟
- 人工审批工作流：敏感操作需用户确认
- Skills 系统：可复用的上下文注入（Markdown 文档或远程 URL）
- 自动文件上传：支持本地路径、浏览器 File 对象、Base64 数据
4. 安全架构
- 前端应用强制代理模式（
proxyUrl），API 密钥驻留服务端 - 官方提供 Next.js App Router/Pages Router、Express、Hono、Remix、SvelteKit 代理中间件
5. 类型安全
- 完整 TypeScript 定义，包含 TaskDTO、ChatDTO、AgentTool 等核心类型
- 精细化错误处理（RequirementsNotMetException、InferenceError）
显著优点
- 生态整合：与 inference.sh 云原生推理平台深度集成，无需自建模型服务
- 开发体验：链式 API 设计（
tool().param().build()），符合现代 JavaScript 工程习惯 - 框架无关：底层 HTTP 客户端，上层提供 React/Vue/Svelte 友好封装
- 成本优化：会话复用减少冷启动，流式输出降低感知延迟
潜在局限
- 平台锁定：深度绑定 inference.sh 生态，迁移成本较高
- 运行时限制：Node.js 18+ 要求，旧环境需 polyfill
- 定价依赖：按量计费模式，高频调用需关注成本
- 浏览器限制：CORS 策略下必须配置服务端代理，纯前端无法直连
适合人群
- 构建 AI 原生应用的 JavaScript/TypeScript 开发者
- 需要快速集成多模态能力（文生图、文生视频）的 Web 团队
- 开发多智能体工作流（Multi-agent）的 AI 工程师
- 寻求类型安全、可维护 AI 集成的中大型企业前端团队
常规风险
- 密钥泄露：误将
inf_前缀 API 密钥提交至前端代码仓库 - 审批绕过：未正确实现
onToolCall回调导致敏感操作未经验证 - 流式中断：网络波动时 SSE 连接未重连导致输出截断
- 依赖更新：SDK 版本迭代快，需关注 Breaking Changes
技术规格
| 属性 | 说明 |
|------|------|
| 包管理 | npm/yarn/pnpm |
| 模块系统 | ESM + CommonJS 双支持 |
| 运行时 | Node.js 18+ / 现代浏览器 |
| 包体积 | ~50KB（tree-shakeable） |
| 官方文档 | https://inference.sh/docs/api/sdk-javascript |