Skip to main content
如果你已经在用 MiniMax Code CLI、编辑器集成或 Headless mcode exec,也可以通过 TypeScript SDK 在代码里控制它。适合这些场景:
  • 在 CI/CD 里自动修代码、跑审查或生成改动;
  • 把 MiniMax Code 嵌进内部工具或你自己的 Agent;
  • 用代码编排多轮 Session,而不是手写 mcode exec 管道。
SDK 通过本机 mcode exec --output-format stream-json 驱动 CLI:一次 run() / runStreamed() 对应一个 CLI 进程、一轮 Turn。当前是 Phase 1(0.x),API 在 1.0 前可能随次要版本调整。相关页面:Headless 与 CI、Python SDK。包页面:npm @minimax-ai/code-sdk。

环境要求

SDK 与 CLI 分开发布。只要 CLI 满足最低版本,升级 SDK 不必同步升级 CLI。运行前需要已登录,或在数据目录里配置可用的 API Key Provider。

安装

@minimax-ai/code 是可选 peer dependency,安装时会跑原生依赖脚本。npm 11 对项目级安装会拒绝 --allow-scripts(EALLOWSCRIPTS),请先在项目 package.json 中批准:

快速开始

创建客户端、开启 Thread,并运行 prompt:
流式消费事件:

CLI 查找顺序

SDK 不强制捆绑 CLI。查找顺序:
  1. 构造参数 bin(可执行文件、JS 入口,或 PATH 上的命令名);
  2. 安装在 SDK 旁边的 @minimax-ai/code(可选 peer);
  3. PATH 上的 mcode。
resolveFromCwd 默认为 false。设为 true 后,还会在 SDK 本地安装之后、PATH 之前搜索宿主工作目录。工作目录不可信时(例如 CI 检出的 PR)请保持关闭,并传入 bin,或把 CLI 装在 SDK 旁边 / PATH 上。每个 MCode 实例在首次运行前会执行一次 mcode --version 并缓存结果。低于 0.6.3 会抛出 MCodeVersionError。只比较 major.minor.patch,因此 0.6.3-preview.N 视为满足要求。

new MCode(options?)

env 不会与 process.env 合并。只传自定义变量会丢掉 PATH、HOME 等,可能导致 CLI 找不到 Node 或凭证。追加变量时请展开:

Thread:startThread / resumeThread

Thread 选项会在该 Thread 的每一轮 Turn 传给 CLI:注意:
  • mode: "lightweight" 只能用于新建 Thread;传给 resumeThread 会立即抛出 MCodeInvocationError;
  • Headless 没有 ask 权限策略;smart / full / off 与 Codex 的 OS sandbox 模式不等价,SDK 不做映射;
  • thread.id 在第一轮 Turn 发出首个事件后可用,即使该轮失败。

thread.run / thread.runStreamed

行为要点:
  • run() 仅在状态为 succeeded 时 resolve,返回 Turn(含 finalResponse、规范化后的 items、usage、model、sessionId、turnId、durationMs 和完整 result);其他结果都会 reject;
  • runStreamed() 原样产出 CLI 事件。turn.failed 是普通事件;只有进程或协议失败才会让迭代器抛错。中途 break 会取消本轮;
  • 同一 Thread 同时只能跑一轮;并发调用抛出 ThreadBusyError,不会排队。

事件与 items

事件类型与 CLI 一致:exec.started、session.started / session.resumed、turn.started、item.started / item.updated / item.completed、turn.completed、turn.failed、exec.completed。每行 stdout 必须是 schemaVersion === 1 的 JSON,否则视为协议错误。Turn.items 是 SDK 规范化后的结果:agent_message、reasoning、tool_call。按 item.id 合并,顺序为首次出现顺序;Turn 结束时仍未收到 item.completed 的项会标为 incomplete: true。usage.totalTokens = inputTokens + outputTokens,不包含 cacheReadTokens / cacheWriteTokens;reasoningTokens 可能与 outputTokens 重叠。

错误

所有错误都继承 MCodeError,并携带 exitCode、signal 以及 CLI stderr 末尾最多 64 KiB(stderr,仅供诊断)。常见错误类:SDK 不会自动重试,以免在结果未知时重复写入。若错误带有 sessionId,可用 resumeThread(error.sessionId) 继续。

取消与超时

  • signal 中止时,SDK 发送 SIGTERM;CLI 按取消路径收尾(最长约 60 秒),超时后 SDK 再发 SIGKILL;
  • timeoutMs 由 CLI 在访问检查、会话解析和模型选择之后计时;SDK 从进程启动起计时,并在 timeoutMs + 90s 强制结束;
  • 宿主正常退出时,SDK 会向仍在运行的 CLI 发送 SIGTERM,并删除临时 system prompt 目录。宿主被信号杀死时不会发出 exit,子进程可能残留。Phase 1 没有 close() / dispose();
  • Windows 上 Node.js 无法向子进程投递可捕获信号,SIGTERM 是硬终止。
推荐在宿主信号处理器里中止进行中的 Turn:
并发多个 exec 共享同一数据目录的测试仍有限。更稳妥的做法是为每个 SDK 实例(或并发任务)使用独立 dataDir,并事先完成认证配置。

Phase 1 暂不支持

  • outputSchema(结构化输出约束);
  • 审批回调、运行中转向、中断后续跑、fork。
需要直接调用 CLI 或处理结构化输出时,请使用 Headless 与 CI。