feat: support SDK

[FliPPeDround]

关联issue #83

---

1. PR简介

• 影响: 🔴 高 - 新增完整的 TypeScript SDK，支持 8 大 AI 能力模块
• 核心变更:
  • ✨ 新增 MiniMaxSDK 主类，提供文本、图像、视频、语音、音乐、搜索、视觉、配额 8 大功能模块
  • 🏗️ 新增统一的 Client 基类，封装配置加载和 HTTP 请求逻辑
  • 📦 更新构建配置，支持 SDK 独立打包和 TypeScript 类型声明生成
  • 📚 完善中英文文档，提供详细的 SDK 使用示例
  • 🧪 为各模块添加单元测试覆盖

---

2. 可视化架构图

SDK 整体架构

graph TD
    subgraph "SDK 入口层"
        A["MiniMaxSDK<br/>src/sdk/index.ts"]
    end
    
    subgraph "核心基础设施"
        B["Client<br/>src/sdk/client.ts"]
        C["MiniMaxSDKOptions<br/>src/sdk/types.ts"]
    end
    
    subgraph "AI 能力模块"
        D["TextSDK<br/>文本对话"]
        E["SpeechSDK<br/>语音合成"]
        F["ImageSDK<br/>图像生成"]
        G["VideoSDK<br/>视频生成"]
        H["MusicSDK<br/>音乐生成"]
        I["SearchSDK<br/>网络搜索"]
        J["VisionSDK<br/>图像理解"]
        K["QuotaSDK<br/>配额查询"]
    end
    
    subgraph "底层服务"
        L["loadConfig<br/>配置加载"]
        M["request/requestJson<br/>HTTP 客户端"]
        N["parseSSE<br/>流式解析"]
        O["poll<br/>任务轮询"]
    end
    
    A -->|继承| B
    A -->|使用| C
    B -->|调用| L
    B -->|调用| M
    B -->|调用| N
    B -->|调用| O
    
    A -->|聚合| D
    A -->|聚合| E
    A -->|聚合| F
    A -->|聚合| G
    A -->|聚合| H
    A -->|聚合| I
    A -->|聚合| J
    A -->|聚合| K
    
    D -->|继承| B
    E -->|继承| B
    F -->|继承| B
    G -->|继承| B
    H -->|继承| B
    I -->|继承| B
    J -->|继承| B
    K -->|继承| B
    
    style A fill:#bbdefb,color:#0d47a1
    style B fill:#c8e6c9,color:#1a5e20
    style D fill:#fff3e0,color:#e65100
    style E fill:#fff3e0,color:#e65100
    style F fill:#fff3e0,color:#e65100
    style G fill:#fff3e0,color:#e65100
    style H fill:#fff3e0,color:#e65100
    style I fill:#fff3e0,color:#e65100
    style J fill:#fff3e0,color:#e65100
    style K fill:#fff3e0,color:#e65100

Loading

---

3. 详细变更分析

3.1 核心基础设施

Client 基类 (src/sdk/client.ts)

• 变更内容: 新增统一的 HTTP 客户端基类
• 核心功能:
  • 构造函数接收 MiniMaxSDKOptions，调用 loadConfig 加载配置
  • 复用 request() 方法处理流式请求
  • 复用 requestJson<T>() 方法处理 JSON 响应

类型定义 (src/sdk/types.ts)

• 变更内容: 新增 SDK 核心类型定义
• 主要接口:

  interface MiniMaxSDKOptions {
    apiKey?: string;
    baseUrl?: string;
    region?: Region;
  }

• 工具类型: ModelPartial<T> - 可选化 model 字段的工具类型

主 SDK 类 (src/sdk/index.ts)

• 变更内容: 新增 MiniMaxSDK 主入口类
• 核心特性:
  • 继承自 Client 基类
  • 聚合 8 个功能模块作为 readonly 属性
  • 构造函数中初始化所有子模块

---

3.2 构建配置

构建脚本 (build.ts)

构建目标	入口文件	输出文件	特性
CLI	src/main.ts	dist/mmx.mjs	添加 shebang
SDK	src/sdk/index.ts	dist/sdk.mjs	生成 .d.ts

• 新增插件: bun-plugin-dts - 生成 TypeScript 类型声明文件

包配置 (package.json)

配置项	旧值	新值	说明
files	dist/mmx.mjs	dist/mmx.mjs, dist/sdk.mjs, dist/index.d.ts	添加 SDK 输出
exports	无	./sdk 路径导出	支持 SDK 模块导入
dependencies	——	+ bun-plugin-dts, es-toolkit	新增构建和工具依赖

---

3.3 文档更新

README.md & README_CN.md

• 新增章节: "SDK Usage" / "SDK 使用"
• 覆盖内容:
  • 安装说明
  • 基础用法
  • 8 大模块的完整示例代码
  • 流式与非流式调用对比
  • 自定义配置说明

---

3.4 测试覆盖

新增测试文件

测试文件	覆盖模块	测试场景
test/sdk/text.test.ts	TextSDK	基础对话
test/sdk/speech.test.ts	SpeechSDK	语音合成、获取音色
test/sdk/music.test.ts	MusicSDK	音乐生成
test/sdk/video.test.ts	VideoSDK	异步生成、任务查询
test/sdk/image.test.ts	ImageSDK	图像生成
test/sdk/vision.test.ts	VisionSDK	图像描述
test/sdk/search.test.ts	SearchSDK	网络搜索
test/sdk/quota.test.ts	QuotaSDK	配额查询

• 测试工具: 使用 createMockServer 创建模拟服务器
• 断言: 验证响应结构和数据正确性

---

4. 影响与风险评估

⚠️ 破坏性变更

• 无破坏性变更 - 新增功能，不影响现有 CLI 工具

✅ 兼容性

• 向后兼容: CLI 工具保持不变
• 新增导出: 通过 exports 字段支持 import { MiniMaxSDK } from 'mmx-cli/sdk'

🧪 测试建议

1. 单元测试: 验证各模块的参数验证逻辑
2. 集成测试: 测试真实 API 调用
3. 流式测试: 验证 SSE 流式解析的正确性
4. 错误处理: 测试网络错误、超时、无效参数等场景
5. 类型检查: 确保 TypeScript 类型声明准确无误

📦 依赖项变更

包名	版本	用途
bun-plugin-dts	^0.4.0	生成 TypeScript 类型声明
es-toolkit	^1.46.1	对象合并工具 (toMerged)

---

5. 使用示例

快速开始

import { MiniMaxSDK } from 'mmx-cli/sdk';

const sdk = new MiniMaxSDK({
  apiKey: 'sk-xxxxx',
  region: 'global',
});

// 文本对话
const response = await sdk.text.chat({
  messages: [{ role: 'user', content: 'Hello!' }],
});

// 图像生成
const image = await sdk.image.generate({
  prompt: 'A cat in a spacesuit',
  width: 1024,
  height: 1024,
});

// 流式音乐生成
const stream = await sdk.music.generate({
  prompt: 'Upbeat pop',
  lyrics: '[verse] Hello world',
  stream: true,
});

for await (const chunk of stream) {
  // 处理音频块
}

---

6. 总结

• 🌊 统一的 API 接口 - AI 能力模块，一致的调用方式
• 🛡️ 参数验证 - 完善的输入验证和错误处理
• 📚 完善的文档 - 中英文文档和丰富的示例代码
• 🧪 测试覆盖 - 单元测试确保代码质量

7. 问题&解决方向

参数校验

• 问题：CLI 的参数校验逻辑目前内聚在 defineCommand 内部，迁移成本较高，因此本次实现的参数校验功能并未与 CLI 复用。这会增加后续的维护负担。
• 方案：需要明确未来的解耦方向，将校验逻辑抽象为可共享的模块。

分包

• 问题：为遵循最小改动原则，仓库未进行 monorepo 改造。当前 SDK 通过 import { MiniMaxSDK } from 'mmx-cli/sdk' 的方式引用，导致安装时附带了 CLI 相关功能，引入了非必要的依赖，增加了安装体积。当前构建产物大小如下：

  File	Size
  dist/mmx.mjs	132 KB
  dist/sdk.mjs	77 KB
  dist/index.d.ts	10 KB

• 方案（建议）：monorepo 改造，抽离核心公共代码为 mmx ，分别对外提供能力的代码采用 mmx-sdk, mmx-cli, mmx-mcp，架构如下（改动较大）

monorepo/
├── packages/
│   ├── mmx/          # 核心库，提供共享类型与工具函数
│   ├── mmx-cli/      # 命令行工具
│   ├── mmx-sdk/      # SDK 封装
│   ├── mmx-mcp/      # MCP 服务实现
│   └── mmx-xxx/      # 未来预留扩展包（示例）
├── package.json      # 根 package.json，定义工作空间与公共依赖
└── README.md         # 项目根说明文档

视频生成SDK

• 问题：我个人的 token-plan 不支持视频生成能力，因此未对视频处理能力的完善度进行校验。

[RyanLee-Dev]

很不错的重构，可以邮箱联系我下 给你提供账号 yuanhe@minimaxi.com

[raylanlin]

测试报告

测试环境：Bun 1.3.11 / WSL2

✅ 通过项

检查项	结果
单元测试（137 个）	✅ 全部通过
构建（build）	✅ CLI 133KB + SDK 77KB
真实 API 冒烟	✅ quota / text / search 正常
架构设计	✅ Client 基类 + 8 模块结构清晰，流式覆盖到位

🔴 阻塞项（合并前需修复）

1. ESLint 报错 — src/sdk/client.ts:2:18 导入了 Region 但未使用，CI lint 会挂
2. TypeScript 报错 — src/types/api.ts 中 SpeechRequest.voice_setting 标记为 required，但 SDK 内部有默认值填充，类型应改为 optional。导致 tsc --noEmit 和 test/sdk/speech.test.ts 类型不匹配
3. Merge Conflict — 当前和 main 有冲突，git 层面无法直接合并

💡 建议项

4. 风格一致性 — src/sdk/video/index.ts:58 的 download 方法用了 new Error(...)，其他模块统一用 SDKError，建议统一

📝 作者已知问题

PR 描述里提到的三个设计层面问题（参数校验共享、安装体积、视频模块未实测）属于后续迭代方向，本次不作阻塞。

结论

架构和测试覆盖都不错，修掉上述 1+2 两项 CI 问题 + 解 conflict 后即可合并。

[raylanlin]

全模块真实 API 测试报告（补充）

补充测了 SDK 全部 8 个模块的真实 API 调用，结果如下：

模块	测试	结果
quota	info()	✅ 11 models
text	chat + chat(stream)	✅ 均正常
search	query()	✅ 7 results
vision	describe()	✅ 正常返回描述
image	generate()	✅ 正常返回图片 URL（⚠️ 宽高须 ≥512，SDK 未做客户端校验）
speech	synthesize() + voices()	✅ 均正常，332 个音色
video	generate(async)	✅ 正常返回 task_id
music	generate(stream) / generate(sync)	✅ 流式/同步均可，但音乐生成耗时 >2min（API 特性，非 bug）

额外发现

5. image.generate 缺少客户端校验 — SDK 未对 width/height 做范围校验（API 要求 512-2048），传入 256 直接被 API 拒绝。建议在 SDK 层加参数校验，提前报给用户。

综上，阻塞项仍是之前提到的 1+2（lint + tsc），建议作者一并修掉。

[FliPPeDround]

@raylanlin 感谢 review，已按反馈和自测做了处理，详情如下：

已处理项

1. 修复 CI 错误，包括 lint 与 typecheck
2. 统一错误风格：全部改为通过 SDKError 输出错误
3. 支持根据视频生成参数自动切换模型 → 4a580e5
4. 允许图片生成时不强制设宽高 → 4e6146c
5. 取消对 SDK 的打包压缩（77kb → 114kb），以便开发者获得更好的 debug 体验

关于 image.generate 缺少客户端校验

原 PR 中其实已经实现了宽高的范围（512–2048）和取模（%8）校验逻辑，见 这段代码。
同时我在本地测试也可以正常在 SDK 调用时被客户端拦截并报错。
如果我的理解有误，麻烦帮忙指出，谢谢！

[raylanlin]

全功能冒烟测试通过，可以合并

测试结果

构建：✅ CLI 133KB + SDK 115KB，构建正常

Lint：⚠️ 2 error + 8 warning（均为 PR 之前已有测试文件的问题，不在本次变更范围内）

TypeCheck：✅ tsc --noEmit 通过

单元测试：✅ 137/137 全部通过

全模块真实 API 冒烟：✅ 10/10 通过

模块	结果	备注
quota	✅	11 models
text.chat	✅	流式 + 非流式均正常
search	✅
vision	✅	图像描述正常返回
image	✅	宽高校验生效
speech.synthesize	✅
speech.voices	✅	音色列表正常
video.async	✅	task_id 正常返回
music	✅	同步/流式均可

之前 report 的 4 项阻塞/建议已全部修掉，SDK 架构清晰、测试覆盖到位，没有新引入的阻塞问题。🚀

[raylanlin]

⚠️ Merge Conflict 说明

main 上刚合并了 PR #121（dea0e53 fix: derive cli version from package metadata），和 PR #122 都改了 build.ts 同一区域：

<<<<<<< HEAD
const SDK_OUT = 'dist/sdk.mjs';
=======
const DEV_BUILD = process.argv.includes('--dev');
>>>>>>> origin/main

两行都保留即可解决：

const SDK_OUT = 'dist/sdk.mjs';
const DEV_BUILD = process.argv.includes('--dev');

rebase main 然后解掉这个冲突就能合了。