SDK 概览

官方 SDK 封装 AI 应用开发平台的 OpenAPI（/v1/openapi/*），屏蔽鉴权、SSE 解析、错误映射等底层细节，让你专注业务调用。

语言支持

语言	包名 / 坐标	最低版本	文档
TypeScript	@hxsyai/aiadp	现代浏览器 / Node.js 18+	TypeScript SDK
Go	hxsyai.com/ai-adp-sdk/go	Go 1.24+	Go SDK
Java	com.hxsyai:aiadp-sdk	Java 21+	Java SDK
Python	aiadp	Python 3.11+	Python SDK
微信小程序	@hxsyai/aiadp-miniprogram	支持分块请求与 SocketTask 的基础库	微信小程序 SDK

能力覆盖

各语言 SDK 均以平台 OpenAPI 为准。TypeScript SDK 与微信小程序 SDK 当前覆盖以下平台能力：

能力	说明
应用	应用列表 / 详情 / 运行参数
Agent 对话	send-messages、resume（HITL）、reconnect、stop，会话与消息历史，支持原始事件与消息聚合
文本生成	阻塞 / SSE 生成、停止生成、分页生成记录与记录详情
文件操作	Agent 工作空间文件的上传 / 列目录 / 文件树 / 编辑 / 复制 / 移动 / 删除 / 创建目录 / 搜索
知识库	列表 / 详情 / 检索
工作流	执行（阻塞 / 流式）
三方服务	服务列表 / 工具列表 / 调用
语音	语音合成 TTS / 识别 STT / 音色列表，支持非流式与 WebSocket 流式
SSE 事件	强类型事件解析（对话 / 工作流），支持连接超时、读取空闲超时与主动取消

通用约定

调用 OpenAPI 只需准备 API Key 和网关地址，与 认证与鉴权 一致。工作空间由网关根据 API Key 自动识别：

参数	说明	示例
API Key	平台签发的密钥	sk_***
接口地址	具体格式以各语言 SDK 文档为准	https://runtime-api.invalid/v1/openapi

建议通过环境变量注入，避免硬编码：

export AIADP_BASE_URL="https://runtime-api.invalid/v1/openapi"
export AIADP_API_KEY="sk_your_api_key"

Go SDK 地址

Go SDK 同时封装业务 OpenAPI 和模型兼容接口，因此初始化时使用网关根地址 https://runtime-gateway.invalid；不要追加 /v1/openapi 或 /v1/compatible-mode。其他 SDK 按各自页面给出的 Base URL 初始化。

TypeScript SDK 与微信小程序 SDK 将鉴权交给调用方，通过 auth() 动态返回 Authorization，便于接入已有登录、令牌刷新和凭据存储方案；SDK 本身不保存或刷新凭据。

语言特色

各 SDK 均贴合所在语言和运行环境的惯用法。

TypeScript SDK

• 同时支持 npm、CDN 全局脚本和 CDN 异步加载
• 提供 ESM、CommonJS、浏览器 IIFE 产物及完整 TypeScript 类型
• 支持按 apps、chat、files 等子入口导入，便于 Tree Shaking
• 调用方通过 auth() 管理鉴权，支持异步获取和刷新令牌
• Agent、AgentLite、文本生成均支持强类型 SSE 事件
• 可选聚合模式直接输出统一 ChatMessage，实时消息和历史消息可共用渲染结构
• 提供 HITL 恢复、显式断流重连、SSE 空闲超时及 WebSocket 连接取消能力
• 同时适用于现代浏览器和 Node.js 18+

Go SDK

• 同一个平台客户端同时支持业务 OpenAPI 与 OpenAI / Anthropic 兼容模型接口
• 复用 API Key、HTTP Client、超时、重试、日志和 User-Agent 配置
• 原生 error 传递错误，配合 errors.Is / errors.As 做哨兵值与类型断言分支
• 函数式 Option 配置（WithTimeout / WithRetry / WithLogger 等）
• SSE 流式以 stream.Next 循环 + type switch 消费强类型事件
• 业务能力按子包拆分（chat / files / voice …），各自 New(client) 构造

Java SDK

• Java 21+，充分使用 records、sealed interfaces、pattern matching、virtual threads
• 零运行时依赖（除 Jackson）—— HttpClient、System.Logger 全用 JDK 原生
• 类型化异常树（ApiKeyExpiredException 等），catch 类型而非匹配字符串
• 同步 + CompletableFuture 异步双入口，异步底层走 virtual-thread executor
• SSE 流式用 sealed ChatEvent + switch 模式匹配；流对象实现 AutoCloseable
• 请求用 Builder 构造，文件上传提供 fromPath / fromBytes / fromStream 三入口

Python SDK

• Python 3.11+，请求 / 响应均为 Pydantic v2 强类型模型
• 同步 Client + 异步 AsyncClient，接口对称，异步基于 httpx + asyncio
• 类型化异常树（APIKeyExpiredError 等），catch 类型而非匹配字符串
• SSE 流式用强类型事件 + match 模式匹配；流对象实现上下文管理协议
• 业务能力挂在 client.chat / client.files … 属性命名空间，惰性创建并缓存
• 语音 WebSocket 流式为可选扩展（aiadp[voice]），核心包零额外依赖

微信小程序 SDK

• 业务命名空间、请求类型、Chat 事件和 Workflow 事件与 TypeScript SDK 保持一致
• 普通请求、分块 SSE、文件传输和 WebSocket 分别适配微信原生网络 API
• Chat 支持 raw 原始事件和 aggregate 聚合消息，以及 HITL 恢复和显式断流重连
• 文件上传使用本地 filePath，下载返回微信 tempFilePath
• 调用方通过 auth() 接入业务登录态，SDK 不保存微信登录凭据或平台密钥

选型建议

优先按运行环境选择：网页和 Node.js 服务选 TypeScript SDK，Go 服务选 Go SDK，JVM 服务（Java / Kotlin / Scala）选 Java SDK，Python 服务选 Python SDK，微信小程序选独立的小程序 SDK。

具体安装与用法见各语言页面：TypeScript SDK ｜ Go SDK ｜ Java SDK ｜ Python SDK ｜ 微信小程序 SDK。