如果你已经在用 MiniMax Code CLI、编辑器集成或 Headless 流式消费事件:
Thread:
Thread 选项会在该 Thread 的每一轮 Turn 传给 CLI:
并发多个
mcode exec,也可以通过 TypeScript SDK 在代码里控制它。适合这些场景:- 在 CI/CD 里自动修代码、跑审查或生成改动;
- 把 MiniMax Code 嵌进内部工具或你自己的 Agent;
- 用代码编排多轮 Session,而不是手写
mcode exec管道。
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。查找顺序:- 构造参数
bin(可执行文件、JS 入口,或PATH上的命令名); - 安装在 SDK 旁边的
@minimax-ai/code(可选 peer); 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是硬终止。
exec 共享同一数据目录的测试仍有限。更稳妥的做法是为每个 SDK 实例(或并发任务)使用独立 dataDir,并事先完成认证配置。Phase 1 暂不支持
outputSchema(结构化输出约束);- 审批回调、运行中转向、中断后续跑、fork。