LobeHub TypeScript 与 Python SDK 及文件上传
两个 SDK 都由同一份 OpenAPI 规范生成,因此资源和方法名一致:agents.list 在 TypeScript 中是 lobehub.agents.list(),在 Python 中是 client.agents.list()。
| SDK | 包 | 状态 |
|---|---|---|
| TypeScript | npm 上的 @lobehub/sdk | 已可用 |
| Python | PyPI 上的 lobehub | 即将推出(#23337) |
TypeScript SDK
npm install @lobehub/sdk创建客户端
选项:apiKey、accessToken(返回当前 token 的函数,优先级高于 apiKey)、baseURL(默认 https://app.lobehub.com),以及任意客户端选项,如自定义 fetch 或 headers。
调用方法
资源与 API 的顶层路径对应(agents、topics、messages、files、knowledgeBases、tasks、goals、responses……)。方法包括 list、get、create、update 和 delete,以及 files.uploadBatch、tasks.run、users.me 等具名操作。
方法在 HTTP 出错时不会抛出异常,而是返回 { data, error, response },其中 data 是完整的响应信封:
可以在每次调用时发送 X-Workspace-Id,也可以通过 headers 统一设置:
流式获取响应
事件类型见流式响应。
使用 OIDC 和 PKCE 登录
适用于每位用户通过公开客户端(没有客户端密钥,例如 LobeHub 内置客户端)登录的原生应用和桌面应用。这些辅助函数不会发送客户端密钥,因此不适用于在设置中注册的 Web OAuth 应用(机密客户端);见 OIDC 与 PKCE。
code: 'invalid_grant' 的 LobeHubOAuthError 表示用户需要重新登录。
TypeScript SDK 即将推出的能力
#23246 新增:
它还导出 LobeHubConnectionError 和 LobeHubTimeoutError,支持传入 throwOnError: true 改为抛出异常而不是返回 error,并在文档中标注每个方法所需的 API Key scope。
Python SDK
即将推出(#23337)。lobehub 包尚未发布到
PyPI。以下示例展示的是该 PR 中的接口,正式发布前可能调整。
pip install lobehub需要 Python 3.9 或更高版本。同时提供同步客户端(LobeHub)和异步客户端(AsyncLobeHub)。方法以普通 dict 返回响应信封中的 data,并用 TypedDict 标注类型。
选项:api_key、access_token(字符串或可调用对象)、base_url(或 LOBEHUB_BASE_URL)、workspace_id、timeout(秒,默认 600)和 max_retries(默认 2)。错误按状态码分为 APIError 的各个子类(BadRequestError、AuthenticationError、PermissionDeniedError、NotFoundError、ConflictError、UnprocessableEntityError、RateLimitError、InternalServerError),未收到响应时抛出 APIConnectionError / APITimeoutError。lobehub.oauth 提供与 TypeScript SDK 相同的 PKCE 辅助函数。
文件上传
上传使用 multipart/form-data,需要 file:write scope。
| 端点 | 字段 |
|---|---|
POST /api/v1/files | file(必填);可选 knowledgeBaseId、agentId、sessionId、directory、skipCheckFileType、skipDeduplication |
POST /api/v1/files/batches | files(1–20 个文件);可选字段同上,但不含 skipDeduplication |
限制:单个文件最大 100 MB,文件名最长 255 个字符,文件类型需在允许列表内,涵盖图片、视频、音频、文本、PDF、Office 文档、YAML、JSON、Markdown 和 CSV。账户超出存储上限时,上传也可能被拒绝。
响应包含文件记录 { file: { id, name, fileType, url, … } }。上传之后:
GET /files/{id}/url?expiresIn=3600返回临时下载 URL。POST /files/{id}/parses提取文本;POST /files/{id}/chunks对文本切分并向量化,以便搜索。- 上传时附带
knowledgeBaseId,文件会直接放入对应资源库。