SDK 使用边界

在自己的 Node.js 服务或脚本里调用接口时，使用 SDK。需要向浏览器或其他语言提供统一 HTTP 接口时，从仓库启动 Bun 服务。

运行环境

SDK 面向 Node.js 24 或更高版本，仅支持 ESM。仓库的安装、测试和 HTTP 服务使用 Bun，版本以 package.json 的 packageManager 为准。

SDK 包含服务端网络和加密能力。浏览器页面应调用已部署的 HTTP 服务，不要把 SDK 和账号 Cookie 打包进浏览器代码。

SDK 可以在 Vercel 等 Serverless 函数里直接调用：加载和调用时不读写本地文件，版本号在构建时写进产物，匿名令牌只放在当前进程的内存里。函数实例被回收后，新实例会在第一次需要时重新注册匿名身份。

TypeScript 类型检查

SDK 的公开声明支持 strict: true 和 skipLibCheck: false。下游项目需要安装与 Node.js 运行环境匹配的 @types/node；例如面向 Node.js 24 的项目：

npm install -D typescript @types/node@24

如果 tsconfig.json 显式设置了 compilerOptions.types，需要在其中包含 "node"。

公开上传参数 LegacyUploadedFile.data 保留了 Buffer 类型。因此，即使浏览器项目只用 import type 导入响应正文类型，在关闭 skipLibCheck 时也仍需加载 Node 类型。类型导入不会引入 SDK 的运行时代码；本次修复不改变上传参数，也不将 SDK 扩展为浏览器运行时包。

从根入口导入

import { createHanaMusicApi, search, invokeModule } from 'hana-music-api';

发布包只开放 hana-music-api 根入口。不要依赖 hana-music-api/src/... 或 hana-music-api/dist/... 这样的内部路径，即使本地文件系统里能找到它们。

公开能力	用途
createHanaMusicApi	创建带默认配置的 client
search、songUrl 等具名函数	按需调用模块
invokeModule	按模块标识调用
createRequest、createOption	底层请求与旧式配置提取
generateDeviceId	生成满足匿名注册条件的设备号
配套公开类型	声明配置、模块标识、输入和响应外壳

startServer、createServer、模块加载器和运行时状态读写函数都属于仓库内部能力，不是 npm 包的公开导出。源码部署的用法见 部署 HTTP 服务。

Effect 留在内部

接口调用继续返回 Promise；generateDeviceId() 同步返回字符串。调用 SDK 不需要自行创建 Effect 运行时或提供内部服务。

参数类型由模块本地输入声明生成，普通响应正文保留未知 JSON。需要了解这条边界时，阅读 返回值与错误；维护内部模块时，阅读 架构详解。